create-claude-cabinet 0.45.0 → 0.47.0

package/templates/cabinet/watchtower-contracts.md

@@ -80,7 +80,23 @@ the section, Ring 1 writes its own ephemeral fallback ("Active: …" /
 last-commit line) and rebuilds it freely; once the marker is present,
 Ring 1 must carry the existing section forward verbatim. Without this,
 Ring 1's full-file rebuild deterministically clobbers Ring 3's summary
-within one cron tick (~5 minutes).
+within one cron tick (~5 minutes). Rebuild writes must go through
+`writeProjectStatePreservingRing3()` in `watchtower-lib.mjs` (re-read
+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)
 
@@ -111,6 +127,182 @@ standard files:
 `/inbox` reads these when `enrichment_status` is `"complete"`.
 Missing files degrade gracefully (null in the read result).
 
+## Routine Dispatch (declared interactive routines)
+
+Projects declare interactive customs as **routines** in `config.json`,
+under their project entry:
+
+```json
+"projects": {
+  "flow": {
+    "path": "/Users/x/flow",
+    "routines": [
+      {
+        "name": "morning-briefing",
+        "description": "Walk the operator through the day's landscape",
+        "trigger": { "type": "time-of-day", "at": "08:30" },
+        "script": ".claude/routines/morning-briefing.md",
+        "urgency": "normal",
+        "stale_after_hours": 24
+      }
+    ]
+  }
+}
+```
+
+- `name` — kebab-case slug, unique within the project.
+- `trigger.type` — `time-of-day` (`at: "HH:MM"`, local, fires once per
+  day), `interval` (`minutes`, >= 5), `path-nonempty` (`path` relative
+  to the project root or absolute; `cooldown_minutes` default 60), or
+  `session-close` (fires when Ring 3 closes a session for the project;
+  worktree sessions resolve to the main project; `cooldown_minutes`
+  default 0).
+- `script` — project-authored phase file (the established CC phase
+  convention) holding the routine's conversation script. The receiving
+  session reads it and runs it; watchtower never parses it.
+- `stale_after_hours` (default 24) — how long a pending dispatch stays
+  blocking before a fresh firing supersedes it.
+
+Ownership: `watchtower-routines.mjs` owns trigger evaluation, firing
+state (`state/routine-state.json`), and dispatch. Ring 1 ticks the
+mechanical triggers; Ring 3 raises session-close events. Both are
+feature-flagged by `defaults.routine_dispatch`. A firing files an inbox
+item (category `routine` — the durable record) and pushes a descriptor
+through `mux qa dispatch`, the SAME hardened desk-dispatch path as
+qa-handoffs (act:796fe6dc) — never a parallel one. Terminal exits on
+any dispatched-category item (qa-handoff, routine) clear the matching
+mux descriptor; routine items resolve normally (no QA gate, normal
+expiry — expiry also clears the descriptor). A pending routine item
+blocks refiring of the same routine until resolved or stale.
+
+## Session Advisor Pass (re-homed standing advisors)
+
+The standing session advisors (historian, system-advocate,
+user-advocate, anthropic-insider) hold two session-boundary seats, both
+index-driven via `.claude/skills/_index.json` — the roster is whoever
+declares the mandate, never a hardcoded list (act:aded4fc9):
+
+- **Close side (automatic):** Ring 3's Phase 2m runs every member whose
+  `standingMandate` includes `session-close` against the compressed
+  session transcript, scoped by `directives.session-close`. Findings
+  file as `advisor-finding` inbox items (max 2 per member per session,
+  deduped against pending + resolved/dismissed corpora). Feature-flagged
+  by `defaults.session_advisors`. Cost: reuses Ring 3's pinned-sonnet
+  run — no Claude Code spawn.
+- **Start side (pull, intent-aware):** `/briefing` full mode spawns
+  every member whose `standingMandate` includes `briefing`, scoped by
+  `directives.briefing`, with the briefing's gathered portfolio context.
+  Observations route through the curator's Step 3b selection and Step 4
+  close — never a permanent section (anti-accretion invariant).
+- **Consultation side (skill-level):** the /orient and /debrief
+  cabinet-consultations phases persist their members' ACTIONABLE
+  findings through this same channel before the briefing/report
+  renders (act:84daa7bc) — `advisor-finding` items with
+  `filed_by: "manual"` and `evidence.directive_key: "orient"` or
+  `"debrief"`, capped at 2 per member per session like Phase 2m.
+  Same dedup-vs-pending discipline (an existing pending item is
+  referenced, not re-filed), same /briefing re-surfacing — never a
+  parallel path. Projects without watchtower fall back to a pib-db
+  action; with neither available, the finding is marked UNTRACKED in
+  the rendered output so the non-persistence is loud.
+
+`advisor-finding` is ungated and undispatched: normal expiry applies
+(findings decay naturally), and `/briefing` weighs fresh ones near the
+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
@@ -195,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.

package/templates/engagement/OVERVIEW.md

@@ -117,6 +117,17 @@ timelog. The running total appears only in a principal's update — never
 in a delegate's. Billing can be scoped by period: the full engagement
 total, the current month, or only hours since the last sync.
 
+**Invoicing.** `/collab-consultant invoice [YYYY-MM]` renders a clean
+invoice document from a month's tracked hours (defaults to the last full
+calendar month; `--itemized` for one line per timelog row instead of a
+single consolidated line). The document is built for upload to the
+operator's bank (Relay), whose "Create Invoice → Autofill from document"
+extracts the customer, line items, and total — so the document carries
+no invoice number and no From/bank block (Relay supplies those). It's
+written to `invoices/<YYYY-MM>.html` with a best-effort PDF conversion.
+Relay defaults the due date to today, so the skill reminds you to set the
+Net-30 due date by hand after autofill.
+
 ### Credential handoff
 
 When a client needs to provide a secret (API key, token, password):
@@ -142,6 +153,7 @@ When a client needs to provide a secret (API key, token, password):
 | `/engagement-message` | Consultant | Send a free-text note to a recipient |
 | `/engagement-sync` | Consultant | Push updates to recipients (with preview + confirm) + pull feedback |
 | `/engagement-status` | Consultant | Dashboard: previews, feedback inbox, billing, tag warnings |
+| `/collab-consultant invoice` | Consultant | Render a month's invoice document for upload to Relay's autofill |
 | `/engagement` | Client | Review the latest update and respond |
 | `/engagement-progress` | Client | Quick glance — what's new, counts, read-only |