create-claude-cabinet 0.46.0 → 0.47.0

package/templates/cabinet/memory-lifecycle-contract.md

@@ -0,0 +1,135 @@
+# Memory Lifecycle Contract
+
+The shared contract for how built-in memory stays bounded as it grows.
+Every component that reads or writes the memory dir follows this:
+`validate-memory.mjs`, `write-memory-file.mjs`, the `/cc-remember` and
+`/memory` skills, the `memory-index-guard` hook, and (Stage 2) the
+lifecycle verbs. Full design + cabinet critique: see
+`.claude/plans/cross-store-memory-redesign.md` (act:02d15a70 = Stage 1,
+this contract; act:45fb9169 = Stage 2, gated).
+
+## The core principle
+
+`MEMORY.md` is loaded **in full at every session start** — it competes
+for the model's context window, so it has a hard budget (≤200 lines /
+≤25KB). The disease this contract cures: the old rule required the
+eagerly-loaded index to enumerate EVERY memory file (one line each), so
+its size tracked total memory count and it overflowed forever — the
+prune→overflow→prune treadmill.
+
+The fix decouples the eager index from total volume: `MEMORY.md` is a
+bounded **working set**, not a complete catalogue. Total memory can grow
+without bound (disk and search both scale for decades); only what loads
+eagerly is bounded. This is the same shape watchtower threads already
+use — surface the current cursor, leave the history on disk.
+
+## The three blocks of MEMORY.md
+
+A well-formed `MEMORY.md` working set has three kinds of content:
+
+1. **Pinned tier (decay-exempt).** Load-bearing knowledge a fresh
+   session needs surfaced *unbidden* — hard constraints, identity, hard
+   preferences, active-project pointers. These are valuable precisely
+   because they are stable and often OLD; they must never decay out on
+   recency. The defining test: *would a session that has never seen this
+   fail without it, and would it not know to go looking?* (e.g. "CC
+   hooks read tool input from stdin, not `$CLAUDE_TOOL_INPUT`".) Mark a
+   pinned entry with `pinned: true` in its file frontmatter (the Stage-1
+   default authority; revisit in Stage 2).
+
+2. **Recency block.** The recent window of curated entries, newest
+   first, filling the remaining budget to roughly 80% of the cap.
+   Recency is a fine proxy for "likely relevant next session" for
+   episodic material — and a BAD proxy for load-bearing constraints,
+   which is exactly why they go in the pinned tier instead.
+
+3. **Region pointers.** The cue-based-retrieval tier (see below) that
+   lets everything outside the working set stay reachable without a line
+   each.
+
+## Reachability replaces enumeration
+
+The validator invariant is no longer "every file has its own index
+line." It is: **every on-disk memory file is reachable from
+`MEMORY.md`** — by one of:
+
+- a direct working-set or `MEMORY-archive.md` index line, OR
+- a **region pointer** whose glob matches the file.
+
+A file that is none of these is an orphan and fails validation.
+"Present on disk" alone is **not** reachable — that test would be
+vacuous (every file is grep-able), which would silently delete the
+guarantee rather than relax it. The point of relaxing enumeration is to
+allow *bounded* indexing (a region covers N files with one line), not to
+allow invisible files.
+
+## Region pointers
+
+A region pointer declares that a whole class of files is reachable
+without enumerating them. Format — the **backtick-quoted glob is the
+only part the validator reads**; the rest is free-text guidance:
+
+```
+- region `lesson_*.md` → older lessons; grep the memory dir
+- region `session_summary_*.md` → past session records; grep by date
+```
+
+Rules:
+
+- **Globs use `*` and `?` only**, matched against the bare filename.
+- **Region pointers are DERIVED, never authoritative.** They are
+  regenerated from what's actually on disk (by hand in Stage 1, by the
+  consolidation pass in Stage 2). A pointer whose glob matches **zero**
+  files on disk is a stale, confidently-wrong retrieval cue — *worse
+  than no map* — and **fails validation**. Fix the glob or remove it;
+  never hand-edit a pointer to claim a region that isn't there.
+- **Region pointers are for recoverable history you'd think to search**
+  (old session narratives, cooled lesson archives). They are the WRONG
+  home for latent constraints — those stay in the pinned tier, eagerly
+  present, because their value is that you retrieve them *without*
+  knowing to look.
+
+## Spill-rate instrumentation (the Stage-2 gate)
+
+`validate-memory.mjs` appends a working-set pressure sample to
+`<memoryDir>/.memory-pressure.jsonl` (a dotfile — invisible to the
+orphan scan) at most once per day, only when utilization is ≥90% of the
+budget. This measures how often the working set actually runs near its
+limit, so Stage 2 (the lifecycle verbs + a background forcing function)
+is built only if the data shows recurring pressure on authored files —
+not on a felt "it keeps overflowing" metaphor. Stage 1 alone stops the
+acute treadmill; the sampler decides whether Stage 2 is warranted.
+
+## Stage 2 (designed, gated — NOT yet built)
+
+The lifecycle verbs and their forcing function are specified in the plan
+but gated on the spill-rate data. When built they will carry these
+already-decided constraints (recorded here so Stage 1 doesn't paint them
+into a corner):
+
+- **decay** — drop an entry from the working set; the file stays
+  reachable (via a region pointer or the archive). Reversible.
+- **consolidate** — merge a cluster into one gist that ALWAYS keeps a
+  lossless `consolidated_from:` provenance pointer (lossy = dropped from
+  the working set, never erased from disk). A cluster containing a
+  pinned/load-bearing entry files to the inbox; it never auto-applies,
+  because the *gist* becomes the retrieved truth and a wrong gist erases
+  a load-bearing detail.
+- **supersede** — mark an entry false/obsolete so retrieval stops
+  surfacing it as live truth (kept on disk for audit, with a reverse
+  breadcrumb in its successor). Deferred until the frontmatter-parsing
+  question is resolved (line-scan vs. a deliberately-added dependency —
+  the repo currently refuses a YAML parser; see
+  `lesson_parsefrontmatter_flow_sequences`). supersede is a reference
+  graph: dangling targets, cycles, and re-pointing working-set/region
+  references to the superseded slug must all be validated.
+- **Cross-store fold** — for session-summaries carrying design
+  reasoning, the durable target is a committed `.claude/methodology/`
+  gist, NEVER the thread cursor (which holds understanding, not
+  narration) and NEVER a delete-in-the-same-pass (the memory dir and
+  threads are both local-only/ungit'd; append-verify-then-mark
+  `folded_into:`, reclaim in a separate idempotent sweep).
+- **Forcing function** — memory hygiene (decay/consolidate) extends
+  Ring 2-slow's existing `runMemoryHygiene`; only drift-supersede is the
+  Ring 4 memory pass. No new ring for hygiene. First passes run
+  dry-run-with-report.

package/templates/cabinet/pib-db-access.md

@@ -23,6 +23,19 @@ Check: are pib_* MCP tools available?
   NO  → use node scripts/pib-db.mjs list-projects, etc.
 ```
 
+### MCP invocation specifics (read before first use, not after a failure)
+
+Two details that otherwise cost a failed call + a `ToolSearch` round-trip
+every session:
+
+- **Full tool names are prefixed `mcp__pib-db__`** (e.g.
+  `mcp__pib-db__pib_query`). When loading deferred tools via `ToolSearch`,
+  query `select:mcp__pib-db__pib_query,mcp__pib-db__pib_list_actions` —
+  the bare `pib_*` names will not match.
+- **`pib_query`'s parameter is `sql`, not `query`.** Calling it with a
+  `query` argument fails (and can fail quietly). The CLI form is
+  `query "SQL"`; the MCP form is `{ "sql": "SELECT ..." }`.
+
 ## Available Operations
 
 | MCP Tool                   | CLI Equivalent                                  | Description                    |

package/templates/cabinet/watchtower-contracts.md

@@ -85,6 +85,19 @@ within one cron tick (~5 minutes). Rebuild writes must go through
 verify with retry), never a raw read→merge→write — the raw form has a
 read-then-write race that drops a Last Session Ring 3 authors mid-merge.
 
+The inline `## Last Session` block holds the COMPLETE session bullet set
+— byte-identical to the bullets in the per-session record at
+`state/projects/<slug>/sessions/<date>-<session-id>.md`. It is NOT a
+pointer, a digest, or a truncated subset. Both bodies derive from the
+ONE model bullet string via `buildLastSessionBlock()`, and Ring 3 writes
+the inline block UNCONDITIONALLY — creating `<slug>.md` if it does not
+yet exist — so the inline section is never silently skipped (the prior
+`existsSync` gate dropped it on fresh projects, leaving readers to render
+Ring 1's truncated one-line fallback while the per-session file held the
+full set; act:ac119994). `upsertLastSessionSection()` performs the
+in-place splice/append with the same line-anchored header search
+`preserveRing3LastSession()` reads with — one splice convention, not two.
+
 ### Thread File Durability (disk wins over model)
 
 `state/threads/<slug>.json` carries the sibling rule: **disk wins over
@@ -199,6 +212,97 @@ top of the owning project's chunk — the re-surfacing the close pass
 promises. A `session-close`/`briefing` mandate without the matching
 directive key is a data error: consumers skip the member and log it.
 
+## Session-Close Extraction Lenses — Phase 2n/2o/2p (act:4ff2cfb3)
+
+Ring 3's session close runs three extraction lenses beyond the knowledge
+pass (2d) and advisor pass (2m), each modeled on `advisorPass` with an
+injectable `callFn` (testable; never folded into the hardened Phase 2d —
+see `lesson_ring3_lens_injectable_phase_pattern`):
+
+- **Phase 2n — Raised-but-unhandled.** Loose ends the session RAISED
+  (promises, side-issues, open questions) but neither completed nor
+  filed → an inbox item under the `raised-unhandled` category. Capped at
+  `RAISED_UNHANDLED_MAX = 5` per session.
+- **Phase 2o — Skill-candidate.** A manual procedure repeated by hand
+  that a skill could absorb → a `skill-candidate` inbox item ("make a
+  skill?"). Capped at `SKILL_CANDIDATE_MAX = 3` per session.
+- **Phase 2p — Checklist-catch.** A surfaced change-impact check that
+  caught a real bug → recorded to `checklist-stats.json` (the
+  catch-recording side; consumed by `/debrief`'s checklist-feedback and
+  the audit `checklist-pruning` phase). Not an inbox item — a stats write.
+
+The two new inbox categories (`raised-unhandled`, `skill-candidate`)
+follow the standard item schema and the same dedup-vs-corpora discipline
+as the other Ring 3 extractions.
+
+## Suppression Ledger (Ring 3 dedup observability)
+
+The recall-fix program (audit act:7d6a4b3b) makes Ring 3's
+knowledge-capture dedup **auditable**. Every time `isDuplicate`
+suppresses an extraction, the suppression site appends one structured
+record to a shared sidecar so over-suppression is visible instead of
+vanishing into a write-only cron.
+
+**File:** `state/suppression-ledger.jsonl` (under `WATCHTOWER_DIR`).
+Append-only JSON-lines. NOT shipped as a template — generated at
+runtime, like `checklist-stats.json` and `.memory-pressure.jsonl`.
+
+**Producer:** `recordSuppression(record, opts)` in `watchtower-lib.mjs`
+(shared home; reachable by every ring). Called from every Ring 3
+suppression site — Phase 2d (extraction), Phase 2m (advisor close
+pass), Phase 2n (raised-unhandled lens), Phase 2o (skill-candidate
+lens). The human `log()` line stays beside it; the ledger is the
+machine-readable twin, never a parse of the prose.
+
+**Consumer:** the Ring 2 slow over-suppression canary (M5) — the ONLY
+reader. It windows records by `ts`, computes a per-project
+suppression-rate (suppressed / (suppressed + filed)) against a captured
+post-M1a baseline, samples actual suppressed titles + what they matched
+for human eyeball, tracks net-durably-saved (filed × approval-rate), and
+writes `state/recall-canary.json`. The canary also prunes the ledger to
+a retention window on each run (growth is bounded at canary cadence, not
+on the suppression hot path). It is over-suppression-only and states so
+in its own `note` field. Guards: `total===0 ⇒ no alert`; a minimum
+denominator before a rate can fire; baseline captured on first run (else
+it would alert on its own improvement).
+
+**The surfacing path** (no write-only telemetry): the canary writes
+`state/recall-canary.json` (per-project `{suppressed, filed, rate,
+baseline, by_corpus, approval_rate, net_durably_saved, sample, alert}`);
+**Ring 1** reads it and renders an alerting project's entry into that
+project's **Standing Issues** (Ring 1 owns the per-project state file);
+**/briefing**'s State-file-flags reader surfaces it. Three named hops,
+each owning its tier. Flag: `defaults.recall_canary` (opt-out).
+
+**Record shape (the contract):**
+
+```json
+{
+  "ts": "ISO-8601 timestamp of the suppression",
+  "project": "resolved project name (or null)",
+  "corpus": "memory | thread-cursor | pending | resolved | dismissed",
+  "suppressed_title": "the extraction title that was killed",
+  "matched_against": "the corpus entry it collided with",
+  "session_id": "the closing session's id (or null)"
+}
+```
+
+**Invariants:**
+
+- **Fail-open.** `recordSuppression` never throws. A failed append logs
+  one line and continues — a dropped ledger record must NEVER block an
+  extraction from filing. The ledger is observability, not the decision.
+- **Additive.** New fields ride alongside; readers default missing
+  fields. The `corpus` enum grows when a new dedup corpus lands (M1a
+  added `thread-cursor` as a first-class corpus split off from
+  `memory`).
+- **Baseline before behavior.** The ledger lands BEFORE any matcher
+  change so it records the OLD (pre-M1a) suppression behavior as the
+  before-baseline the canary compares against.
+- **Over-suppression only.** The ledger sees what dedup KILLED, not what
+  extraction never proposed (M2 under-extraction). The canary states
+  this blindness in its own output.
+
 ## Deferred Schemas
 
 The following are specified in project notes but NOT formalized until
@@ -283,3 +387,313 @@ They're complementary, not redundant.
   staleness detection (stale work, memory hygiene). Where's the line
   between R2's "is this work item stale?" and R4's "is this document
   still true?" Is R4 an extension of R2 slow, or genuinely distinct?
+
+## Ring 4 — Truth Reconciliation (built, stage 1)
+
+**Status: BUILT (act:36dae795). Supersedes the design-phase section
+above** — the open design questions there are now resolved here.
+Implemented in `templates/scripts/watchtower-ring4.mjs` (the ring) +
+`templates/scripts/watchtower-ring4-runner.sh` (PID-locked runner,
+modeled on the Ring 2 runner). Hermetic suite:
+`templates/scripts/__tests__/ring4-reconcile.test.mjs`. Cron/launchd
+registration is a `/watchtower install` follow-up, not part of this
+build.
+
+### What it does
+
+Periodically compares documentary CLAIMS against codebase REALITY and
+files drift as `doc-drift` inbox items. Reconciliation is COMPARISON,
+NOT generation — Ring 4 never rewrites a document; it flags drift with
+enough context to fix, and the operator triages it. Stage 1 is PURELY
+MECHANICAL (no Claude API call), which keeps the cron cheap and the
+ring hermetically testable.
+
+It owns two ledger duties at orient/debrief retirement
+(`orient-debrief-coverage-ledger.md` §C/§D): documentation staleness
+(CLAUDE.md key-file claims, briefing files, system-status) and the
+dropped embedded-pulse description-accuracy spot checks (counts). The
+standalone `/pulse` stays invocable on demand.
+
+### Resolved design questions
+
+- **Scope per run → rotation, not full sweep.** Each run reconciles at
+  most `RING4_PROJECT_CAP` (3) projects, least-recently-reconciled
+  first, BUT a project with commits since its last reconcile jumps the
+  queue. This is the nervous-system principle in mechanical form: R4
+  consumes R1's signal (git recency) to prioritize, rather than
+  blind-sweeping the portfolio. State in `state/ring4-reconcile.json`
+  (`last_run`, `projects_checked`).
+- **Drift threshold → mechanical existence/counts, high precision.**
+  Stage 1 flags only (a) a backtick-fenced repo-relative path that is
+  missing on disk, gated so the path's TOP-LEVEL directory still
+  exists (kills illustrative/foreign-path noise — `webapp/...` in a
+  CC memory file is skipped because `webapp/` isn't a repo dir) and
+  not gitignored (a gitignored absent path is a generated/local
+  artifact — its absence is expected, not drift); and (b) a count
+  claim that disagrees with a mechanical file count, but ONLY for
+  config-declared count rules (zero-noise default). A "slightly
+  outdated line count" is deliberately NOT flagged.
+- **Trigger vs schedule → weekly cadence + git-recency priority.** A
+  weekly gate (`RECONCILE_INTERVAL_DAYS`, mirrors Ring 2's roster
+  review) plus git-recency-driven project order, rather than coupling
+  to R1/R2 internal trigger files.
+- **Relationship to Ring 2 → genuinely distinct ring.** R2 slow asks
+  "is this WORK ITEM stale?" (pib-db state); R4 asks "is this DOCUMENT
+  still true?" (doc claims vs codebase). Distinct cadence (weekly vs
+  30-min), distinct runner/cron, distinct produced category.
+- **Cross-project → per-project only, stage 1.** A CC template
+  claiming something about consumer behavior is a documented future
+  extension, not built.
+
+### The document set (current-reality docs only)
+
+`collectDocuments()` scans docs consumed AS TRUTH, capped at
+`RING4_DOC_CAP` (40): root `CLAUDE.md`, `system-status.md` (root and
+`.claude/`), `.claude/cabinet/_briefing*.md`, and the project's
+built-in memory entries (`MEMORY.md` + curated `*.md`). It
+deliberately EXCLUDES `.claude/plans/` and `.claude/methodology/`:
+those are HISTORICAL records — a plan for retired work SHOULD
+reference now-deleted files, so path-existence over them is mostly
+noise (the CC dogfood produced ~90 false claims from historical plans;
+filtering to current-reality docs + gitignore-awareness cut it to 2
+real findings). Whether a plan is actually DONE — plan-to-reality
+drift — is a distinct SEMANTIC check, deferred.
+
+### Memory is DRIFT-SUPERSEDE only
+
+The memory pass is the missing-path reconciler applied to memory files
+("is what we wrote still true?" — entries referencing renamed/removed
+files). Paths in a memory file resolve against the PROJECT root, not
+the memory dir. Memory HYGIENE (budget / decay / consolidate) stays
+Ring 2 slow's `runMemoryHygiene` / `surfacePersistentViolations` —
+Ring 4 does NOT fork a second memory-health producer (act:36dae795
+2026-06-16 scope note; design in `cross-store-memory-redesign.md`).
+
+### Inbox contract
+
+Findings file `doc-drift` items (`filed_by: 'ring4'`, urgency `low`,
+three triage options: fix-doc / fix-code / dismiss). Dedup is ONE
+pending item per `evidence.drift_key` per project — `path:<doc>` for
+missing-path, `count:<doc>:<label>` for count-mismatch (mirrors Ring
+2's `roster_kind` convention: a still-open drift item is a reference,
+not a duplicate). At most `RING4_ITEM_CAP` (8) items filed per run.
+`doc-drift` is NOT a dispatched or gated category — it is a plain
+inbox item the operator triages. The weekly cadence + per-doc dedup
+keep re-nagging bounded.
+
+### Config
+
+Feature flag `defaults.truth_reconciliation` (default true) gates the
+whole ring; `ring_frequencies.ring4` (604800 = weekly) carries the
+intended cron interval. Count rules are per-project and opt-in:
+`projects[<name>].reconcile.count_rules = [{ label, doc, pattern,
+glob }]` where `pattern` is a regex source with one capture group
+around the number and `glob` uses the small dependency-free grammar in
+`countGlob` (`dir/*`, `dir/prefix-*/`, `dir/*.ext`, `dir/**/*.ext`).
+Default empty → the count pass no-ops (no false drift).
+
+### Deferred (future stages)
+
+Semantic comparison (does this prose paragraph still describe the
+code?), plan-to-reality / plan-status reconciliation, dependency-
+version drift beyond the count-rule mechanism, gitignored-directory
+patterns that don't match a non-existent path, and cross-project
+template-vs-consumer reconciliation.
+
+## Consumer Hook Contract (Plan 9)
+
+The formalized extension model for **non-interactive** consumer customs at
+the ring lifecycle seams (act:4a6e907c). Supersedes the deferred-schema
+placeholder `hooks/<ring>-<phase>.d/` above — the real location is
+per-project, not a global runtime dir. Interactive customs are owned by
+routine dispatch (act:c2a55c08, "Routine Dispatch" above), never by hooks.
+
+### Seams and invocation
+
+The rings already invoke consumer hooks by running each command string in
+`config.hooks[<seam>]` with the ring's state JSON on stdin. Three seams:
+
+| Seam | Ring / scope | Outer timeout |
+|------|--------------|---------------|
+| `ring1-post-collect` | Ring 1, per project, post state-collect | 30s |
+| `ring2-slow-post` | Ring 2 slow tier, portfolio-wide | 60s |
+| `ring3-close-post` | Ring 3, per session close | 120s |
+
+`watchtower-hook-runner.mjs --seam <seam>` is registered ONCE per seam (via
+`--register`, called by `/watchtower install`). The rings invoke it like any
+hook command — the rings are NOT modified. The runner then resolves the
+target project(s) and runs that project's hook scripts.
+
+### Registration (drop-a-file)
+
+A consumer registers a hook per-project by placing an executable script in
+`<project-root>/.claude/watchtower/hooks/<seam>/`. Presence is registration —
+no config editing. Discovery is name-sorted (numeric-prefix convention:
+`10-foo.sh` before `20-bar.sh`). A file is runnable if it has the executable
+bit (run directly, shebang decides the interpreter) or a known extension
+(`.sh`/`.bash` → bash, `.mjs`/`.js`/`.cjs` → node, `.py` → python3); other
+files (`.json`, `.md`, …) are ignored. Files prefixed `_` or `.` are skipped
+(disable convention).
+
+### Project resolution
+
+- Single-project seams (`ring1-post-collect`, `ring3-close-post`): the project
+  is taken from the ring's stdin state (`.path`/`.name`, or `.project_path`/
+  `.project`).
+- Portfolio seam (`ring2-slow-post`): the slow state carries no project, so the
+  runner enumerates `config.projects` and runs each project's seam dir.
+
+### Hook I/O contract
+
+A hook script receives:
+- **stdin:** the ring's state JSON, verbatim (see the seam table for shape).
+- **cwd:** the project root.
+- **env:** `WATCHTOWER_SEAM`, `WATCHTOWER_PROJECT`, `WATCHTOWER_PROJECT_PATH`,
+  `WATCHTOWER_SESSION_ID` (ring3), `WATCHTOWER_HOOK_DIR`.
+
+A hook script returns:
+- **exit 0** = success; non-zero = failure (isolated, recorded, never fatal).
+- **stdout:** optional JSON. `{"additional_checks":[…]}` is the Ring 1
+  passthrough — the runner surfaces those at the envelope top level so Ring
+  1's existing `parsed.additional_checks` consumption works. Other JSON is
+  captured as structured `output`; non-JSON is captured verbatim (truncated).
+- **stderr:** captured for diagnostics; non-fatal.
+
+### Isolation and budget
+
+The runner is bulletproof: any single hook's failure (non-zero exit, timeout,
+spawn error) becomes a typed status (`failed` / `timeout`) and never aborts
+the loop, and the runner always prints a valid envelope and exits 0 — one bad
+consumer hook can never break a ring tick. Because the runner is a single
+command sharing the ring's one timeout envelope, it runs hooks sequentially
+against a deadline (the seam timeout minus headroom) and marks any hook it
+can't reach in time `skipped` (reason `budget-exhausted`) — no silent
+truncation. `WATCHTOWER_HOOK_BUDGET_MS` overrides the per-seam budget.
+
+### Output envelope
+
+```json
+{ "schema_version": 1, "seam": "<seam>",
+  "targets": [{ "name": "...", "path": "..." }],
+  "hooks": [{ "hook": "<path>", "project": "...", "status": "success|failed|timeout|skipped", "output"?: ..., "exit"?: N, "stderr"?: "...", "reason"?: "budget-exhausted" }],
+  "additional_checks"?: [ ... ] }
+```
+
+### Migration shim
+
+`watchtower-phase-shim.mjs --phase <path> [--cwd <dir>] [--seam <seam>]` is the
+adapter for an EXISTING repo script (a former orient/debrief phase) that
+expects the project root as cwd rather than reading stdin. Registered as a one
+-line `config.hooks[<seam>]` entry, it runs the target with the same cwd/env/
+stdin normalization and passes JSON stdout through transparently (preserving
+`additional_checks`), propagating the target's exit code. New hooks prefer the
+drop-in directory; the shim is for scripts that already exist.
+
+## Decision Lineage (read-only projection — Plan 12, act:a2efc0ce)
+
+The `/briefing lineage` drill-down answers "what past decisions still
+constrain THIS project, and what's reversible?" It is a **projection** over
+existing stores, never a new store, and it **writes nothing** — no state file,
+no inbox item, no memory write. This is the structural invariant: the engine
+holds no persisted copy, so it cannot drift from its sources.
+
+`watchtower-narrative-corpus.mjs` is the read-only substrate helper. It covers
+the two watchtower-NATIVE stores so it needs no auto-memory-dir resolver:
+
+- `assembleNarrativeCorpus({cwd})` — current project ONLY (resolved
+  worktree-aware via `resolveProjectIdentity`; no free `project` arg, so the
+  five-namespace keying footgun can't arise). Returns `inbox_decisions`
+  (knowledge-extraction items; `resolution_type: 'captured-to-memory'`
+  duplicates dropped so a decision that became a memory file isn't
+  double-counted; `superseded` status KEPT — it is the supersession view's
+  own subject), `thread_cursors` (full `cursor_history` timelines),
+  `per_store_counts`, `skipped_unresolved` (phantom-key items repo-wide that
+  the resolver couldn't attribute — surfaced, never silently dropped),
+  `time_span`. CLI: `--corpus --project-path <cwd>`.
+- `parseDecisionEdges(markdown)` (pure) + `readMemoryDecisions(dir)` — the
+  memory/methodology/pib stores are read by the `/briefing` CONSUMER (which
+  resolves their paths), but the EDGE RULE lives here, tested: a
+  `**Supersedes:**` block is a RECORDED directional edge; a `[[wikilink]]` is
+  an undirected see-also and is **never** rendered as a supersession. CLI:
+  `--memory <consumer-resolved-dir>`.
+
+Provenance is load-bearing because a narrative is a trust surface: the render
+labels *recorded* edges (parsed `Supersedes:` / pib `absorbs act:`) distinctly
+from *inferred* ones (model-read from prose), and never presents an inferred
+link as recorded history. Deliberately a SIBLING of `watchtower-snapshot.mjs`
+(same reader family, same hermetic-test shape), touching zero ring code. Tests:
+`__tests__/narrative-corpus.test.mjs`. Staged: the machine-readable
+supersede-edge discipline (making edges consistent + live) is deferred and
+MERGES INTO the cross-store `supersede` verb
+(`.claude/plans/cross-store-memory-redesign.md`, Ring 2-slow), not a fork.
+
+## Cross-Ring Reader (read-only projection — Stage 1, act:f5814d6c)
+
+`watchtower-cross-ring-reader.mjs` is the synthesis SUBSTRATE for `/briefing`:
+one call assembles, per configured project, what every ring produced —
+Ring 1's parsed state-file sections + git-attention facts, Ring 3's recent
+session summaries + thread cursor timelines, and the inbox's pending counts +
+resolution history (`resolution_mix`: what the operator's dispositions
+actually engaged vs discarded). The script GATHERS; the consumer SYNTHESIZES —
+no convergence scoring or cross-store "insight" is computed here (a
+mechanical projection on a trust surface must not fabricate synthesis). Like
+its siblings it is a **projection** over existing stores, never a new store,
+and it **writes nothing** — no write path exists in the module; the hermetic
+test asserts the filesystem is untouched.
+
+**Per-store join keys** (name = `config.projects` key, slug = `slugify(name)`;
+the reader derives both exactly as `resolveProjectIdentity` does, parity-tested):
+
+| Store | Located by | Key |
+|-------|-----------|-----|
+| Ring 1 state file | `state/projects/<slug>.md` | slug |
+| Ring 3 sessions | `state/projects/<slug>/sessions/*.md` | slug |
+| Threads | `sessions[].project` via `threadMatchesProject` | slug |
+| git-attention facts | `fact.project` | name |
+| Inbox items | `item.project` via `listItems` | name |
+
+**Ring 2 has no dedicated block by design.** Its durable outputs already
+arrive through two covered channels — pattern-promotion items ride the inbox,
+and the recall canary is projected into Ring 1's Standing Issues — so a
+dedicated block would double-report inside one output. Enrichment BODIES stay
+behind the Enrichment Directory contract (`/inbox` reads them per-item).
+
+**Honesty fields** (the complement of the config-driven walk — nothing falls
+silently between views): `unattributed_items` (partitioned on config-key
+MEMBERSHIP, not the `project_unresolved` flag), `orphan_threads`,
+`orphaned_state_files`, `duplicate_path_warning` (realpath-compared),
+per-view `path_exists` + `attributed_but_flagged`, and windowing counts
+(`sessions_total` / `sessions_in_window` / `sessions_included`). Sessions
+order by each file's content `Date:` line (same-day filenames sort randomly
+by uuid). `superseded`/`expired` items never stamp `resolved_at`, so they are
+reported as filed-date-window counts, never blended into the disposition-time
+`resolution_mix`; untyped `resolution_type` lands in `untyped_or_other`,
+counted, never dropped.
+
+**Output-size caps, always with totals** (CP3: an uncapped live portfolio
+measured 1.37 MB — no consumer channel carries that): thread histories keep
+the newest `THREAD_HISTORY_CAP` (3) snapshots with per-thread `history_total`
+(the full evolution is lineage mode's job — `projectCursorTimeline` itself is
+uncapped); the resolution-event list keeps the newest `RESOLUTION_EVENTS_CAP`
+(20) with `resolution_events_total` while `resolution_mix` counts ALL events.
+The consumer sees "3 of 85", never a silently complete-looking 3. The
+briefing consumes by writing `--portfolio` to a temp file and Reading slices —
+never by echoing JSON through a truncating shell channel. `--project` accepts
+the config-key name or a UNIQUE slug match (the /briefing scope filter is
+slug-shaped).
+
+**Consumer:** `/briefing` Step 1d — the reader is the REPLACEMENT gather path
+for the old per-store state/thread reads (with a raw-read fallback for
+consumers that haven't reinstalled), and its output feeds Step 3a chunk
+synthesis and Step 4 cross-cutting synthesis. Pending counts are a narration
+snapshot; the briefing's live `listPending()` load remains the disposition
+source of truth. The 4-field cursor projection (`projectCursorTimeline`) has
+its ONE definition here; `watchtower-narrative-corpus.mjs` imports it
+(watchtower-lib is ring-loaded and soak-frozen, so the shared helper lives in
+the non-ring reader). CLI: `--portfolio | --project <name> | --project-path
+<cwd>`, `--since <ISO|Ndays>` (default 14d, UTC). Tests:
+`__tests__/cross-ring-reader.test.mjs`.
+
+**Staged:** precompute-and-cache (a Ring 2 slow-tier phase persisting the
+view) is Stage 2, deferred until the recall-canary soak lifts; consolidating
+the cursor projection into watchtower-lib waits for the same gate.

package/templates/cabinet/worktree-invocation-contract.md

@@ -0,0 +1,87 @@
+# Worktree-Invocation Contract
+
+The shared, universal preamble for any skill that may run from a
+mux/linked git worktree. `/execute` and `/execute-group` both **read
+this file and follow it** at their Step 0 rather than each spelling the
+mechanism — so the detect/sync/artifact rules change in one place.
+
+Running a skill from a linked worktree is the **normal case**, not an
+error — never refuse. Establish these three facts first; everything
+caller-specific (how a particular skill merges, whether it spawns
+worktree agents) lives in the caller's own Step 0, AFTER it reads this.
+
+## 1. Detect where you are
+
+```bash
+COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
+TOP="$(git rev-parse --show-toplevel 2>/dev/null)"
+# In a linked worktree the common .git lives under the MAIN checkout, so
+# dirname(COMMON) != TOP. On the main checkout they are equal.
+if [ -n "$COMMON" ] && [ "$(dirname "$COMMON")" != "$TOP" ]; then
+  : # linked worktree — sync + artifact rules below apply
+fi
+```
+
+`--path-format=absolute` is load-bearing: from the main checkout
+`--git-common-dir` is a bare relative `.git`, and a string compare /
+`dirname` on the relative form misclassifies. Force absolute on the
+read. (Same trap the pib-db path resolver and the completion-gate hook
+both handle.)
+
+## 2. Sync with main before anything else (worktree only)
+
+A worktree starts behind — plan text, code, and the staleness/CP guards
+all read state that may have moved on main since the worktree was cut.
+If the branch is behind main:
+
+```bash
+git merge main --no-edit
+```
+
+**On conflict, HALT the whole skill — do not auto-resolve and do not
+proceed to implement against a half-synced tree.** This is an
+interactive skill; resolution is the operator's call. Leave the worktree
+exactly as the conflicted merge left it (conflict markers, an in-progress
+merge) and surface, in plain English:
+
+> Sync with main hit a conflict in `<files>`. The worktree is mid-merge.
+> Resolve the conflicts and `git commit` the merge — **or** `git merge
+> --abort` to back out — then re-run the skill. I stopped before
+> implementing so nothing lands on a half-synced tree.
+
+## 3. Completion artifacts land in the MAIN checkout
+
+A worktree's `.claude/verification/` is gitignored and disposable —
+anything written there is lost on worktree cleanup (the lost-breadcrumb
+failure: `lesson_workflow_report_worktree_cwd`). Resolve the MAIN
+checkout once and write every verification artifact under it:
+
+```bash
+MAIN="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
+# breadcrumbs, reports → "$MAIN/.claude/verification/<fid>.json"  (never cwd-relative)
+mkdir -p "$MAIN/.claude/verification"
+```
+
+On the main checkout `$MAIN` resolves to the cwd, so the same line is
+correct in both places — no on-main special case. The completion-gate
+hook already READS breadcrumbs from `$MAIN/.claude/verification/`; this
+makes the WRITE side agree.
+
+**Sibling copies of this one git-truth — keep them in step:** the
+`MAIN_RESOLVE` string constant in
+`templates/workflows/execute-group-implement.js`, and the shell spelling
+in `templates/hooks/action-completion-gate.sh` (a hook can't read this
+doc). Three copies, one resolution; change one, change all three.
+
+## What this contract does NOT cover
+
+Caller-specific orchestration stays in the caller's own Step 0, never
+here:
+
+- **`/execute-group`** keeps inline: that its `isolation: worktree`
+  agents branch from and merge into MAIN regardless of the invoking cwd,
+  and its inline-build escape hatch. These describe the workflow's merge
+  model and would contradict `/execute`'s no-merge model — they are not
+  universal.
+- **`/execute`** keeps inline: that it does NOT merge (the worktree→main
+  bridge is `/qa-handoff`), and how its close-out files the handoff.