docs(readme + install): reconcile all count drift (F4 RELEASE BLOCKER)

Disk reality: - blocks: 73, manifests: 12, skills: 38 (was 34/35), hooks: 10 (was 6/9) - shell primitives: 16 (13 opt-in + 3 always-copied) - bridges: 11, rust crates: 24 (was 8/9/14), MANIFEST full profile: 37 Updated: README.md lines 31, 70, 94, 111, 119-125, 254, 307 and install.sh --help + whiptail.
2026-04-22 13:36:17 +08:00 · 2026-04-22 13:36:17 +08:00 · a25796df76
commit a25796df76
parent 81462a03ef
2 changed files with 48 additions and 36 deletions
--- a/README.md
+++ b/README.md
@ -28,7 +28,7 @@ Thanks.

 ## What it is

-KeiSeiKit is a comprehensive drop-in toolkit for [Claude Code](https://claude.com/claude-code). It ships a curated set of composable behavioral blocks, a Rust assembler that builds agent `.md` files from TOML manifests deterministically, nine pre-wired hooks (three of them dedicated to RULE 0.14 session self-audit), 35 portable skills (including an interactive `/new-agent` wizard, 10 hub-and-spoke pipelines, and the `/self-audit` retrospective skill), **9 Rust primitive crates**, 13 shell primitives, and 11 cross-tool bridge templates. Everything follows a Constructor Pattern: one file per concern, manifests as single source of truth, and the generated agent files are regenerated on every relevant edit.
+KeiSeiKit is a comprehensive drop-in toolkit for [Claude Code](https://claude.com/claude-code). It ships a curated set of composable behavioral blocks, a Rust assembler that builds agent `.md` files from TOML manifests deterministically, 10 pre-wired PreToolUse/PostToolUse hooks (three of them dedicated to RULE 0.14 session self-audit), 38 portable skills (including an interactive `/new-agent` wizard, 10 hub-and-spoke pipelines, and the `/self-audit` retrospective skill), **24 Rust primitive crates**, 13 opt-in shell primitives (plus 3 always-copied sleep-sync helpers), and 11 cross-tool bridge templates. Everything follows a Constructor Pattern: one file per concern, manifests as single source of truth, and the generated agent files are regenerated on every relevant edit.

 The kit is MIT-licensed and fully generic — install it on a fresh machine and you get a sane 12-agent fleet (implementers, critics, researchers, cost-guardians, and more — all namespaced under `kei-*` so they won't collide with your own same-named agents), a wizard for spinning up new project specialists, 10 pipeline skills that combine primitives end-to-end (`/compose-solution`, `/site-create`, `/schema-design`, `/observability-setup`, `/auth-setup`, `/api-design`, `/ci-scaffold`, `/test-matrix`, `/docs-scaffold`, `/new-project`, `/vm-provision`), and a build pipeline that keeps every agent derivable from its manifest.

@ -67,7 +67,7 @@ cd KeiSeiKit
 5. Builds the Rust assembler (`cargo build --release` in `_assembler/`)
 6. If any Rust primitive is in the selected profile: writes a scoped workspace `Cargo.toml` listing ONLY the installed crates, then `cargo build --release`
 7. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place`
-8. Copies the six hooks and 34 skills
+8. Copies the 10 hooks and 38 skills

 After install, the only remaining step is merging `settings-snippet.json` into your `~/.claude/settings.json` to activate the hooks. You can do this automatically with `./install.sh --activate-hooks` or answer `y` at the end-of-install TTY prompt.

@ -91,7 +91,7 @@ By default `./install.sh` is **minimal** — agents + hooks + skills + bridges,
 | `frontend` | 8 site tools: `mock-render`, `visual-diff`, `tokens-sync`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode` | ~60s | ~80 MB |
 | `ops` | 8 infra tools: `kei-ledger`, `ssh-check`, `firewall-diff`, `provision-hetzner`, `provision-vultr`, `harden-base`, `metrics-scrape`, `log-ship` | ~90s | ~50 MB |
 | `dev` | 4 dev tools: `kei-migrate`, `kei-changelog`, `kei-ci-lint`, `kei-docs-scaffold` | ~60s | ~40 MB |
-| `full` | everything (22 primitives) | ~5 min | ~200 MB |
+| `full` | everything (37 primitives) | ~5 min | ~200 MB |

 Examples:

@ -108,7 +108,7 @@ Examples:

 Profile resolution lives in `_primitives/MANIFEST.toml` — one `[primitive.<name>]` entry per primitive plus a `[profile]` block. Edit the manifest to define new profiles without touching `install.sh`.

-> **Migrating from a full install:** if you're re-running `install.sh` after an earlier version that installed all 22 primitives unconditionally, the new default (`minimal`) will REMOVE them. To preserve the old behaviour explicitly, pass `--profile=full`.
+> **Migrating from a full install:** if you're re-running `install.sh` after an earlier version that installed all primitives unconditionally, the new default (`minimal`) will REMOVE them. To preserve the old behaviour explicitly, pass `--profile=full` (currently 37 primitives).

 > **Re-install disclaimer:** `install.sh` is idempotent for clean state but **overwrites kit-owned `_blocks/`, `_primitives/`, `_bridges/`, `_templates/`, `_assembler/`, `hooks/`, and `skills/` on re-run** — local modifications under those directories are backed up to `<dir>.bak-TIMESTAMP/` (or, for shared hook files, to `<file>.bak-TIMESTAMP`). User-owned `_manifests/*.toml` are never overwritten.

@ -116,12 +116,13 @@ Profile resolution lives in `_primitives/MANIFEST.toml` — one `[primitive.<nam

 | Category | Count | Examples |
 |---|---:|---|
-| Behavioral blocks | 73 | `baseline`, `evidence-grading`, `rule-math-first`, `stack-rust-axum`, `stack-react-vite`, `stack-vue-nuxt`, `stack-sveltekit`, `stack-astro`, `deploy-modal`, `api-fal-ai`, ... |
+| Behavioral blocks | 73 | `baseline`, `evidence-grading`, `rule-math-first`, `stack-rust-axum`, `stack-react-vite`, `stack-sveltekit`, `stack-astro`, `deploy-modal`, `api-fal-ai`, ... |
 | Generic agents (manifests) | 12 | `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, `kei-cost-guardian`, `kei-modal-runner`, ... |
-| Hooks | 6 | `assemble-agents`, `assemble-validate`, `no-hand-edit-agents`, `tomd-preread`, `agent-fork-logger`, `site-wysiwyd-check` |
-| Portable skills | 34 | `compose-solution`, `new-agent`, `new-project`, `site-create`, `schema-design`, `observability-setup`, `auth-setup`, `api-design`, `ci-scaffold`, `test-matrix`, `docs-scaffold`, `vm-provision`, ... |
-| Primitives (Rust crates, opt-in) | 8 | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync` |
-| Primitives (shell, opt-in) | 13 | `tomd`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode`, `metrics-scrape`, `log-ship`, `provision-hetzner`, `provision-vultr`, `harden-base`, `kei-ci-lint`, `kei-docs-scaffold` |
+| Hooks (PreToolUse / PostToolUse) | 10 | `assemble-agents`, `assemble-validate`, `no-hand-edit-agents`, `tomd-preread`, `agent-fork-logger`, `site-wysiwyd-check`, `session-end-dump`, `milestone-commit-hook`, `error-spike-detector`, `git-pre-commit-genesis` |
+| Portable skills | 38 | `compose-solution`, `new-agent`, `new-project`, `site-create`, `schema-design`, `observability-setup`, `auth-setup`, `api-design`, `ci-scaffold`, `test-matrix`, `docs-scaffold`, `vm-provision`, ... |
+| Primitives (Rust crates, opt-in) | 24 | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync`, `kei-memory`, `genesis-scan`, `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, `kei-store`, `kei-router`, `kei-sage`, `kei-task`, `kei-chat-store`, `kei-crossdomain`, `kei-search-core`, `kei-content-store`, `kei-social-store`, `kei-curator`, `kei-auth` |
+| Primitives (shell, opt-in via profile) | 13 | `tomd`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode`, `metrics-scrape`, `log-ship`, `provision-hetzner`, `provision-vultr`, `harden-base`, `kei-ci-lint`, `kei-docs-scaffold` |
+| Shell helpers (always copied) | 3 | `kei-sleep-setup`, `kei-sleep-sync`, `kei-sleep-queue` (dormant until you run `/sleep-setup`) |
 | Cross-tool bridges | 11 | Cursor legacy/MDC, Codex, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit |

 Of the 73 blocks, the **8 base blocks** (`baseline`, `evidence-grading`, `memory-protocol`, `rule-pre-dev-gate`, `rule-test-first`, `rule-error-budget`, `rule-double-audit`, `rule-math-first`) are referenced directly by the 12 shipped manifests. The remaining blocks (`stack-*`, `deploy-*`, `api-*`, `scraper-*`, `domain-*`) are a library consumed by the `/new-agent` wizard and the hub-and-spoke pipeline skills: when you compose a project specialist or spin up a site, the wizard / pipeline picks the appropriate blocks and emits artefacts that reference them.
@ -233,9 +234,11 @@ A third nightly phase — **Phase C** — runs after REM on a user-chosen cadenc
 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.
- **Plan + fork** — same plan plus a ready-to-review `deep-sleep/YYYY-MM-DD` branch with `git apply`-ready changes for auto-resolvable conflicts. Graph-check gate aborts the fork (plan is still committed) if any wikilink breaks after the patch.
+- **Plan + fork** — same plan plus an auto-resolve review markdown (`YYYY-MM-DD-autoresolve.md`) listing the auto-resolvable conflicts with WHY / EXAMPLE / TRADEOFF per item. You open each file in an editor, apply the suggested change, commit on a `deep-sleep/YYYY-MM-DD` branch, then let the graph-check gate verify the wikilinks still resolve.

-**Zero-conflict guarantee:** any conflict the engine marks `requires_human_decision` is EXCLUDED from the generated patch and listed plainly in the plan. No silent auto-apply of ambiguous changes.
+> v0.14.1 retraction: earlier README claimed a `git apply`-ready patch. The engine cannot synthesise real unified-diff hunks without reading the source files — that would risk fabricated edits (RULE 0.4). The autoresolve file is now plain markdown reviewed and applied by hand; the "fork" path only automates the rename/move class of ops, not content edits.
+
+**Zero-conflict guarantee:** any conflict the engine marks `requires_human_decision` is EXCLUDED from the auto-resolve markdown and listed plainly in the plan. No silent auto-apply of ambiguous changes.

 **Store backends** (picked in Phase 3b, consumed via the new `kei-store` trait):

@ -245,13 +248,13 @@ Two output modes, chosen once in `/sleep-setup` Phase 3b:
 | Forgejo self-hosted | production | Same wire protocol as GitHub |
 | Gitea self-hosted | production | Same wire protocol |
 | Filesystem only | production | Local `.git`; no push; fastest |
-| S3 / R2 / MinIO | MVP stub | Manifest-based local-cache; `aws-sdk-s3` integration planned |
+| S3 / R2 / MinIO | stub — local only until v0.15 | Manifest-based local cache ONLY; no upload to S3/R2/MinIO yet. Requires `KEI_STORE_ALLOW_S3_STUB=1` (explicit opt-in so you don't accidentally believe your data is in the cloud). `aws-sdk-s3` integration planned for v0.15. |

 Requires the new `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, and `kei-store` primitives (shipped in the `dev` and `full` profiles). Governed by the Phase C extension of RULE 0.15 in `~/.claude/rules/sleep-layer.md`.

 ## Primitives (Rust)

-`_primitives/_rust/` is a Cargo workspace with 14 single-binary crates (v0.13.0 added 4 deep-sleep primitives). `install.sh` builds `--release` and drops binaries at `~/.claude/agents/_primitives/_rust/target/release/<name>`.
+`_primitives/_rust/` is a Cargo workspace with 24 single-binary crates (v0.13.0 added 4 deep-sleep primitives; v0.14.0 added 10 LBM-port MCP crates). `install.sh` builds `--release` for the subset selected by the active profile and drops binaries at `~/.claude/agents/_primitives/_rust/target/release/<name>`.

 | Crate | Purpose |
 |---|---|
@ -266,7 +269,7 @@ Requires the new `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`,
 | `kei-memory` | Session retrospective + recurring pattern detector; offline-first analyzer powering RULE 0.14 self-audit |
 | `genesis-scan` | Patent-IP leak scanner (term blacklist + exempt-path rules; CI / pre-commit gate) |
 | `kei-conflict-scan` | v0.13.0 — deep-sleep conflict scanner across rules/hooks/blocks/orphans/CP violations |
-| `kei-refactor-engine` | v0.13.0 — consumes `kei-conflict-scan` JSON; emits plan markdown + `git apply`-ready patch |
+| `kei-refactor-engine` | v0.13.0 — consumes `kei-conflict-scan` JSON; emits plan markdown + auto-resolve review markdown (NOT a unified diff; v0.14.1 retraction) |
 | `kei-graph-check` | v0.13.0 — post-refactor wikilink + handoff + block-ref resolver gate |
 | `kei-store` | v0.13.0 — memory-repo backend abstraction (GitHub / Forgejo / Gitea / Filesystem / S3) |

@ -303,7 +306,7 @@ Requires the new `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`,
  Block edit (_blocks/<block>.md)             <-- triggers rebuild of ALL agents
 ```

-Six hooks enforce the pipeline:
+10 hooks enforce the pipeline (6 pipeline + 3 session-audit + 1 genesis-pre-commit):

 - **`assemble-agents`** (PostToolUse, Write/Edit) — rebuilds the affected agent(s) whenever a manifest or a block changes. No manual rebuild needed.
 - **`assemble-validate`** (PreToolUse, Bash) — blocks `git commit` inside `~/.claude` if any manifest fails validation. Keeps the repo in a buildable state at all times.
@ -311,6 +314,10 @@ Six hooks enforce the pipeline:
 - **`tomd-preread`** (PreToolUse, Read) — auto-converts opaque binary formats (`.docx`, `.doc`, `.xlsx`, `.pptx`, `.csv`) to markdown via the `tomd` primitive and redirects Claude to read the cached `.md` instead.
 - **`agent-fork-logger`** (PreToolUse, Agent) — RULE 0.12 advisory: logs every Agent subagent invocation to the `kei-ledger` SQLite DB so the orchestrator can validate the fork bundle. Never blocks; silent no-op if `kei-ledger` is absent.
 - **`site-wysiwyd-check`** (PostToolUse, Edit/Write) — on frontend-source edits (`.tsx`, `.vue`, `.svelte`, `.astro`, `.css`, `.html`, `.jsx`, `.ts`) in a project with a live dev server (`.keisei/dev-server.pid`), takes a Playwright screenshot via `mock-render` and diffs against `.keisei/target.png` via `visual-diff`. Advisory-only — drift is reported to stderr, never blocks.
+- **`session-end-dump`** (Stop event) — RULE 0.14 self-audit: archives the session JSONL trace and ingests it into `kei-memory`.
+- **`milestone-commit-hook`** (PostToolUse, Bash) — RULE 0.14 self-audit: appends a one-line session summary to `~/.claude/memory/audit-backlog.md` on every `feat:`/`refactor:`/merge commit.
+- **`error-spike-detector`** (PostToolUse, any tool) — RULE 0.14 self-audit: tags + logs the pattern when 3+ errors occur within the last 20 tool calls.
+- **`git-pre-commit-genesis`** (PreToolUse, Bash) — runs `genesis-scan` on staged files to block patent-IP leaks before commit.

 ## Adding custom blocks

--- a/install.sh
+++ b/install.sh
@ -4,7 +4,7 @@
 #
 # Usage:
 #   ./install.sh                           # interactive menu on TTY; profile=minimal on non-TTY
-#   ./install.sh --profile=<name>          # minimal|core|frontend|ops|dev|full  (skips menu)
+#   ./install.sh --profile=<name>          # minimal|core|frontend|ops|dev|mcp|full  (skips menu)
 #   ./install.sh --add=<name>[,<name>]     # install one or more primitives on top of current state
 #   ./install.sh --remove=<name>           # remove a single primitive
 #   ./install.sh --list                    # list installed primitives (name | kind | desc | path)
@ -54,11 +54,12 @@ Usage: ./install.sh [flags]

  --profile=<name>          set installed-primitive set to one of:
                              minimal   (no primitives)
-                              core      (tomd)
+                              core      (tomd, genesis-scan)
                              frontend  (8 site tools: mock-render / visual-diff / ...)
                              ops       (8 infra tools: kei-ledger / ssh-check / ...)
-                              dev       (4 dev tools: kei-migrate / kei-changelog / ...)
-                              full      (all 21 primitives)
+                              dev       (9 dev tools: kei-migrate / kei-memory / deep-sleep quartet / ...)
+                              mcp       (10 LBM-port tools: kei-router / kei-sage / kei-auth / ...)
+                              full      (all 37 primitives — MANIFEST source of truth)

  --add=<a>[,<b>,...]       add one or more primitives on top of current install.
                            Name must match [primitive.<name>] in _primitives/MANIFEST.toml.
@ -337,13 +338,14 @@ menu_should_skip() {
 menu_whiptail_profile() {
  local tool="$1"  # whiptail or dialog
  "$tool" --title "KeiSeiKit Installer" --radiolist \
-    "Choose install profile (SPACE to select, ENTER to confirm):" 20 78 7 \
+    "Choose install profile (SPACE to select, ENTER to confirm):" 22 78 8 \
    "minimal"  "agents + hooks + skills + bridges (~5s)"           ON  \
-    "core"     "+ tomd (~5s)"                                       OFF \
+    "core"     "+ tomd + genesis-scan (~5s)"                        OFF \
    "frontend" "+ 8 site tools (~60s, 80 MB)"                       OFF \
    "ops"      "+ 8 infra tools (~90s, 50 MB)"                      OFF \
-    "dev"      "+ 4 dev tools (~60s, 40 MB)"                        OFF \
-    "full"     "all 21 primitives (~5 min, 200 MB)"                 OFF \
+    "dev"      "+ 9 dev tools (~60s, 40 MB)"                        OFF \
+    "mcp"      "+ 10 LBM-port MCP tools (~90s, 50 MB)"              OFF \
+    "full"     "all 37 primitives (~5 min, 200 MB)"                 OFF \
    "custom"   "pick individual primitives"                         OFF \
    3>&1 1>&2 2>&3
 }
@ -376,15 +378,16 @@ menu_plain_profile() {
  echo "Choose install profile:"           >&2
  echo                                     >&2
  echo "  1) minimal   — agents + hooks + skills + bridges only (~5s)" >&2
-  echo "  2) core      — + tomd (~5s)"                                  >&2
+  echo "  2) core      — + tomd + genesis-scan (~5s)"                   >&2
  echo "  3) frontend  — + 8 site tools (~60s, 80 MB)"                  >&2
  echo "  4) ops       — + 8 infra tools (~90s, 50 MB)"                 >&2
-  echo "  5) dev       — + 4 dev tools (~60s, 40 MB)"                   >&2
-  echo "  6) full      — all 21 primitives (~5 min, 200 MB)"            >&2
-  echo "  7) custom    — pick individual primitives"                    >&2
+  echo "  5) dev       — + 9 dev tools (~60s, 40 MB)"                   >&2
+  echo "  6) mcp       — + 10 LBM-port MCP tools (~90s, 50 MB)"         >&2
+  echo "  7) full      — all 37 primitives (~5 min, 200 MB)"            >&2
+  echo "  8) custom    — pick individual primitives"                    >&2
  echo                                                                   >&2
  local reply
-  printf 'Enter choice [1-7] (default 1): ' >&2
+  printf 'Enter choice [1-8] (default 1): ' >&2
  read -r reply || return 1
  case "${reply:-1}" in
    1) echo minimal  ;;
@ -392,8 +395,9 @@ menu_plain_profile() {
    3) echo frontend ;;
    4) echo ops      ;;
    5) echo dev      ;;
-    6) echo full     ;;
-    7) echo custom   ;;
+    6) echo mcp      ;;
+    7) echo full     ;;
+    8) echo custom   ;;
    *) err "invalid choice: $reply"; return 1 ;;
  esac
 }
@ -868,7 +872,7 @@ if ! menu_should_skip; then
  if echo "$menu_out" | grep -q ','; then
    CUSTOM_PRIMS="$menu_out"
    PROFILE="custom"
-  elif echo "$menu_out" | grep -qE '^(minimal|core|frontend|ops|dev|full)$'; then
+  elif echo "$menu_out" | grep -qE '^(minimal|core|frontend|ops|dev|mcp|full)$'; then
    PROFILE="$menu_out"
  else
    # Single name from custom-with-one-item — treat as CUSTOM_PRIMS
@ -881,9 +885,9 @@ fi
 # Default profile is minimal.
 PROFILE="${PROFILE:-minimal}"
 case "$PROFILE" in
-  minimal|core|frontend|ops|dev|full|custom) ;;
+  minimal|core|frontend|ops|dev|mcp|full|custom) ;;
  *)
-    err "unknown profile: $PROFILE. Valid: minimal | core | frontend | ops | dev | full"
+    err "unknown profile: $PROFILE. Valid: minimal | core | frontend | ops | dev | mcp | full"
    exit 1
    ;;
 esac
@ -1210,9 +1214,10 @@ else
  NEXT STEP: merge settings-snippet.json into ~/.claude/settings.json
 ==========================================================================

-  KeiSeiKit ships 6 hooks (assemble-agents, assemble-validate, no-hand-edit,
-  tomd-preread, agent-fork-logger, site-wysiwyd-check). To activate them,
-  merge entries from:
+  KeiSeiKit ships 10 hooks (assemble-agents, assemble-validate, no-hand-edit,
+  tomd-preread, agent-fork-logger, site-wysiwyd-check, session-end-dump,
+  milestone-commit-hook, error-spike-detector, git-pre-commit-genesis).
+  To activate them, merge entries from:
      $KIT_DIR/settings-snippet.json
  into your:
      $SETTINGS_FILE