From b55c3d6ef31616007f7a1efc16b88361b2a3ef41 Mon Sep 17 00:00:00 2001 From: Parfii-bot Date: Wed, 22 Apr 2026 21:46:06 +0800 Subject: [PATCH] docs(readme): restore About section + nightly-cycle overview + security model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds 6 missing pieces flagged by readme review: 1. ## About — author attribution + "not a product" positioning + "Why Rust, not Python" (was removed in 1f3aaca, but load-bearing context for new users). Keeps the product-oriented greeting intact above it. 2. ## Install — plugin vs classic two-path table up front; links to PLUGIN.md (v0.16+ Anthropic plugin format was previously un-linked). 3. ## The nightly cycle at a glance — unified ASCII overview of the three-phase sleep cycle (A incubation → B REM → C NREM), biological analog, phase-interaction rules (marathon owns night, Phase C cadence, morning report is human-only). 4. ### Deep-sleep NREM consolidation — 4-primitive pipeline diagram (conflict-scan → refactor-engine → graph-check via kei-store) plus a concrete example of a detected conflict. 5. ## Security model — 7 bullets covering memory-repo privacy, RULE 0.1, secrets-guard, GitHub Actions SHA pinning, S3 SSRF guard, marker 0o600, exFAT/FAT32 warning. Plus battle-matrix mention. 6. ## Docs — link index to CHANGELOG / PLUGIN / USB-BRAIN guide / battle tests (none of those four files were referenced from README before). README.md: +83 lines (1221 → 1304). Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/README.md b/README.md index 501045c..5cb4120 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,16 @@ KeiSeiKit is that structure: persistent agent memory across sessions, pre-commit **Rust-first by design.** Every primitive that can be Rust, is Rust. Type-system guarantees remove entire classes of hallucination at compile time: no `None`-vs-`[]` confusions, no missing `.await`, no unhandled `Result`. For LLM-authored code this is not a style preference but a survival constraint. +## About + +Built by Denis Parfionovich () as a personal working environment — not a commercial product. The problems it solves are ones I hit every day across 4–8 parallel Claude Code terminals: forgetting between sessions, repeating the same mistake on the third try, parallel agents clobbering each other's files, a hallucinated API name shipped to production. None of these are solvable by a better prompt. They are solvable by structure around the prompt. + +**Why Rust, not Python.** Transformers write Python confidently and wrongly. Five minutes to a plausible-looking function, two hours to debug why `dict.get("key", None) or []` silently swallowed an empty list, or why an async context manager leaked a file handle across a retry loop. Rust's type system catches whole categories of those errors at compile time — the model literally cannot ship a `None`-vs-`[]` confusion, a missing `.await`, or an unhandled `Result`, because the compiler refuses. For an LLM-written codebase this is not aesthetic preference, it is survival. Every Rust primitive here is one category of hallucination the transformer is no longer allowed to commit. + +Most of what is here is well-established bricks (git-as-state, cron, TF-IDF, constructor-pattern composition). What may be new in the Claude Code context is the Constructor Pattern for agents (composable blocks, deterministic build, rebuild-on-block-edit hooks) and the three-phase sleep layer (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly incubation + REM + NREM consolidation). + +Treat this as **my sample, not a claim of originality.** I work from my own rules stacked in one place and cannot always tell what came from somewhere I have read and what came from my own head. Forks and PRs welcome from everyone, not only from those who write code. If you hit a problem with Claude Code and have an idea for solving it, open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution. + --- ## At a glance @@ -69,6 +79,13 @@ The kit is MIT-licensed and fully generic — install it on a fresh machine and ## Install +Two install paths — pick whichever fits your Claude Code version: + +| Path | Command | Best for | +|---|---|---| +| **Plugin** (v0.16+, recommended on Claude Code 2.1+) | `/plugin marketplace add KeiSei84/KeiSeiKit` then `/plugin install keisei@keisei-marketplace` | Agents + skills + hooks + MCP. Zero cargo build. See [PLUGIN.md](./PLUGIN.md). | +| **Classic** `./install.sh` | Below | Full kit incl. 25 Rust primitives + 13 shell primitives. Required for the `ops` / `dev` / `full` profiles. | + ```bash git clone KeiSeiKit cd KeiSeiKit @@ -986,6 +1003,35 @@ Manual trigger: `/self-audit` skill (same flow, invoked on demand). Requires the `kei-memory` primitive. Included in the `dev` and `full` profiles; otherwise add via `./install.sh --add=kei-memory`. +## The nightly cycle at a glance + +The sleep layer is a **three-phase nightly cycle** on an Anthropic-cloud agent. The three phases run in order on the same scheduled trigger; each is covered in its own section below. + +``` + YOUR NIGHT + ┌──────────────────────────────────────────────────────┐ +Day →→→ │ Phase A Phase B Phase C │ →→→ Morning + │ INCUBATION REM NREM │ + │ "sleep on it" consolidation deep-sleep │ + │ v0.12.0 v0.11.0 v0.13.0 │ + │ (queued tasks) (trace patterns) (conflict │ + │ refactor) │ + └──────────────────────────────────────────────────────┘ + ↓ ↓ ↓ + sleep-results/ reports/sleep-*.md sleep-deep/*.md + .md (always) (every N days) +``` + +**Biological analog.** Your Mac is the hippocampus (fast, stateful, volatile — captures raw episodes). The memory-repo is the transport layer. The cloud agent is the neocortex (slow, stateless, generalising). The morning `git pull` is the recall. Phase A mirrors the "sleep on it" effect (Wagner et al. 2004, *Nature*), Phase B mirrors REM dream-state pattern extraction, Phase C mirrors NREM slow-wave system consolidation. + +**Phase interaction rules (important):** + +- A `marathon` task in Phase A (8-hour budget, 1 task only) **owns the whole night** — Phases B and C are skipped for that night. Traces are append-only, so the next night's Phase B picks up the skipped backlog. +- Phase C only fires when today is a multiple of `DEEP_SLEEP_CRON_DAYS` (default 7) counted from your install date. Anchor lives in `sync-repo/reports/install-anchor.txt`. +- The morning report is for **HUMAN review**. It is NEVER auto-injected into a Claude Code session. Any rule or hook that emerges from it is installed via `/escalate-recurrence` — not by the cloud agent. + +Governed end-to-end by RULE 0.15 in `~/.claude/rules/sleep-layer.md`. + ## Cloud REM sync (sleep layer, v0.11.0) Run a nightly "sleep" cycle on Anthropic's cloud — no laptop, no infra, no DevOps. @@ -1036,6 +1082,22 @@ Results in `sync-repo/sleep-results/.md`, linked from the next morning's R A third nightly phase — **Phase C** — runs after REM on a user-chosen cadence (default: every 7 days). Biological analog: NREM slow-wave-sleep system consolidation. The remote agent scans your memory-repo for conflicts across rules, hooks, `_blocks/`, and memory (contradictory directives, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations) and produces a structured refactor plan. +**4-primitive pipeline, in order:** + +``` +kei-conflict-scan → kei-refactor-engine → kei-graph-check (via kei-store transport) + (detect) (propose) (verify) (read/write memory-repo) +``` + +1. `kei-conflict-scan` reads `_rules/`, `hooks/hooks.json`, `_blocks/`, and `memory/` and emits a typed conflict list (name-collision, matcher-overlap, duplicate-block, orphan-wikilink, CP-violation). +2. `kei-refactor-engine` groups conflicts by safe-to-auto-resolve vs `requires_human_decision` and writes the plan + auto-resolve markdown. +3. `kei-graph-check` walks every wikilink / block-ref / handoff-ref in the proposed state; if anything fails to resolve, the fork branch is blocked and the plan is annotated. +4. `kei-store` is the transport — reads the pre-state from your GitHub / Forgejo / Gitea / FS / S3 backend and writes the two output files back atomically. + +**Concrete example** (real category, paraphrased): + +> Conflict detected: hook `no-github-push.sh` (PreToolUse:Bash, matcher `git push`) and rule file `patents.md` (§"Never reference unfiled applications") both govern the same risk surface — a github push containing unfiled-patent language. The hook blocks on URL; the rule blocks on content. Suggested refactor: keep both (they are complementary), but add a cross-ref from `patents.md` to the hook so a future reader sees the two-layer defence. Auto-resolvable (pure documentation edit, no behaviour change). Written to `YYYY-MM-DD-autoresolve.md` for human review. + Two output modes, chosen once in `/sleep-setup` Phase 3b: - **Plan only** (default) — markdown report in `sync-repo/sleep-deep/YYYY-MM-DD-plan.md`. Read in the morning, decide what to merge by hand. @@ -1216,6 +1278,27 @@ Phase 6 is the feedback loop: when a component has no prior art, the skill draft See `skills/compose-solution/SKILL.md` and its phase files (`phase-1-intake.md` through `phase-7-assemble.md`) for the full 7-phase pipeline. +## Security model + +What the kit touches, what it never touches, and the mitigations baked in: + +- **Memory-repo must be private.** Sleep-sync pushes your session traces (prompts, tool calls, file paths, code snippets) to a git repo you control. `/sleep-setup` Phase 1 warns loudly on PUBLIC visibility. A public memory-repo leaks everything your agents have seen. If the session is marked `[PATENT-IP]` or runs in a banned-project CWD, `session-end-dump.sh` skips the push entirely — local trace is kept, never leaves the machine. +- **No GitHub push for kit-internal state.** RULE 0.1 forbids `git push` to github.com for any repo containing unfiled-patent IP. Kit ships `genesis-leak-guard.sh` as a pre-commit hook symlink template to keep patent-sensitive terms off any remote. +- **Secrets by reference only.** `secrets-guard` hook (Rust) blocks hardcoded tokens at `PreToolUse(Edit|Write)`. Every SSH key, API key, deploy token lives in `~/.claude/secrets/.env` (chmod 600, gitignored) or per-project `secrets/*.env`. Hook detects OpenAI/Anthropic/GitHub/Slack/AWS/Telegram token shapes plus PEM private keys (see RULE 0.8). +- **Supply-chain defences.** All GitHub Actions in `.github/workflows/` are pinned by full commit SHA (defends against CVE-2025-30066-class mutable-tag attacks). `scripts/validate-workflow-shas.sh` verifies every pin; `scripts/install-actionlint.sh` checks SHA-256 of the downloaded tarball before extraction. Dependabot raises weekly PRs for SHA updates. +- **S3 / R2 / MinIO hardening.** `kei-store::s3_cloud::validate_endpoint` rejects loopback, link-local, and cloud-metadata hosts (`127.0.0.0/8`, `169.254.0.0/16`, `metadata.google.internal`, …) by default to close the SSRF / IMDS-credential-leak surface. Plain HTTP requires opt-in. Non-AWS endpoints must set explicit `access_key_env` + `secret_key_env` — the AWS default credential chain is not consulted. +- **Brain attach-marker is owner-only.** `~/.keisei/attached.toml` is `chmod 0o600` on unix. Every manifest-sourced string printed by `keisei status` / `attach` / `mount` / `detach` is scrubbed through a control-byte sanitiser — closes the escape-sequence-injection surface from a malicious `brain.name`. +- **exFAT / FAT32 warning.** SQLite WAL shared-memory mmap is unreliable on those filesystems; `keisei mount` will corrupt `kei-memory` / `kei-artifact` / `kei-social-store` DBs. Brain load prints an advisory. See `docs/USB-BRAIN-GUIDE*.md` for APFS / ext4 / NTFS-native walkthroughs. + +Install-test battle matrix runs every profile against Ubuntu 24.04 + Alpine 3.19 + Debian 12 (`tests/battle/`) — "does it work on a fresh machine?" signal before each release. + +## Docs + +- [CHANGELOG.md](./CHANGELOG.md) — full release notes, generated from Conventional Commits by `kei-changelog` +- [PLUGIN.md](./PLUGIN.md) — Anthropic plugin-format install path (v0.16+) and differences from classic installer +- [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) — portable brain on removable media; platform splits for macOS / Linux / Windows +- [tests/battle/README.md](./tests/battle/README.md) — Docker install-test matrix + ## License MIT. See `LICENSE` in this directory.