Merge docs/readme-missing-sections — About + nightly-cycle + Security

2026-04-22 22:43:54 +08:00 · 2026-04-22 22:43:54 +08:00 · 8eadb12d00
commit 8eadb12d00
parent 5ec90ca241 b55c3d6ef3
1 changed files with 83 additions and 0 deletions
--- 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 (<parfionovich@keilab.io>) 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 <your-fork-of-this-repo> 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
+         <uuid>.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/<uuid>.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.