create-claude-cabinet 0.45.0 → 0.47.0

package/templates/skills/session-handoff/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: session-handoff
 description: |
-  The default session-close verb. Two phases: (1) run /debrief in full,
+  The default session-close verb. Three phases: (1) run /debrief in full,
   which sweeps and performs a /qa-handoff for every worktree→main merge
   this session still needs one for; (2) propose a seed prompt for the
   next session — you discuss/revise/approve/reject — and ONLY on approve
-  spawn a new window seeded with it. Distinct from /qa-handoff: that
+  spawn a new window seeded with it; (3) a non-blocking epilogue that —
+  in the dying tab, while the next session is already running — surfaces
+  this project's work threads in plain language and offers at most one
+  well-explained inbox decision. Distinct from /qa-handoff: that
   hands a single merge BACKWARD to the live QA station (window 1); this
   closes the session and hands FORWARD to the next session (a new
   window). Plain /debrief is for shutting down with nothing queued.
@@ -21,10 +24,12 @@ This is the **default close verb**. The verb is the signal of intent:
 plain `/debrief` means "I'm done, nothing queued."
 
 It is a **thin wrapper** over `/debrief` (the `debrief-quick` pattern: a
-runtime redirect, not a re-implementation). It adds exactly one original
-responsibility — propose-and-launch the next session — and inherits
-everything else from debrief by reference. Do **not** re-document or
-paraphrase debrief's phases here; run them.
+runtime redirect, not a re-implementation). It adds two original
+responsibilities — propose-and-launch the next session (Phase 2) and a
+non-blocking epilogue that makes thread state visible and drains one
+inbox decision (Phase 3) — and inherits everything else from debrief by
+reference. Do **not** re-document or paraphrase debrief's phases here;
+run them.
 
 ## Phase 1 — Close & sweep (mechanical, no gate)
 
@@ -132,6 +137,163 @@ fully complete before phase 2.
 4. **On reject — clean close.** Debrief already ran; nothing is spawned.
    Say so plainly and stop.
 
+## Phase 3 — Epilogue (non-blocking, skippable)
+
+Phase 2 has resolved — a window launched, nothing was launched, or the
+operator rejected. The session is closing and the operator is here only
+to close the tab. That is the one moment with the session's full
+context, zero blocking, and guaranteed attention; spend it on
+**visibility**, not ceremony. The whole point of the watchtower thread
+machinery is that long-running lines of work carry a living cursor — and
+those cursors are normally invisible under the surface. The epilogue is
+where they surface.
+
+**This phase NEVER blocks the close.** The handoff already happened in
+Phase 2; the epilogue runs *after* it, so there is no blocking-close
+friction to recreate. If any step below fails or finds nothing, drop it
+and close cleanly. Always lead with the permission line, verbatim:
+
+> Reply to act on any of this, or just close the tab — nothing here is
+> lost; everything resurfaces in /briefing.
+
+### 1. Setup — resolve the MAIN checkout first
+
+The installed watchtower libraries (`scripts/watchtower-*.mjs`) live only
+in the **main checkout**; a worktree — where this skill usually runs —
+does not have them. Resolve the main repo root before touching anything:
+
+```bash
+COMMON=$(git rev-parse --git-common-dir 2>/dev/null) || COMMON=""
+if [ -n "$COMMON" ]; then COMMON=$(cd "$COMMON" && pwd); MAIN_ROOT=$(dirname "$COMMON"); fi
+```
+
+`--git-common-dir` returns the main repo's `.git` from a worktree (and
+`.git` from the main checkout); `cd … && pwd` makes it absolute and its
+parent is the repo root — correct from either place.
+
+- **No watchtower (expected on non-watchtower installs):** if `MAIN_ROOT`
+  is empty, or `$MAIN_ROOT/scripts/watchtower-lib.mjs` or
+  `~/.claude-cabinet/watchtower/state` does not exist, print
+  `Epilogue skipped (no watchtower).` and close. This is a clean
+  structural self-skip — report it, don't swallow it.
+- **Installed but a read blows up later:** that is a real fault, not an
+  expected skip — surface ONE loud line naming what failed, then close.
+  Never let a failure masquerade as "nothing to show."
+
+Resolve project identity (which fields to match on differs between the
+two stores — getting this wrong silently returns zero rows):
+
+```bash
+node "$MAIN_ROOT/scripts/watchtower-lib.mjs" resolve "$PWD"
+```
+
+Prints `{ "name", "slug", "path", … }` and exits 0; exit 2 means
+unresolvable — skip the epilogue loudly. **Thread files key on
+`identity.slug`** (`sessions[].project` carries the slug); **the inbox
+keys on `identity.name`** (queue items carry the config project name).
+
+### 2. Thread visibility (read-only — never write thread files)
+
+Ring 3 owns the thread store under the disk-wins contract; the epilogue
+**only reads** it. Read thread files from
+`~/.claude-cabinet/watchtower/state/threads/*.json` (ignore any
+`threads-test/`). Use the **`/threads` read contract** for every field
+shape — `display_name` (falls back to slug), the current cursor (last
+`cursor_history[]` entry's `cursor`, or a legacy lone `cursor` object),
+`sessions[].project`, `status` — rather than re-deriving it here; if a
+file is unparseable, skip that file.
+
+Keep `status: active` threads whose `sessions[].project` includes
+`identity.slug`. **Selection (hard caps — repeat them at point of use):**
+the thread(s) this session actually moved (from debrief's session
+inventory — usually 1–2), plus at most **one** other active thread by
+recency. **Cap 3 total.** Ring 3 deliberately mints overlapping threads
+at different zoom levels (initiative / project-area / cross-cutting) over
+the same work — collapse those to one per work area; never show three
+views of one thing.
+
+Render **one plain-prose paragraph per thread** (~80–100 words, a soft
+budget — readability over completeness; cryptic bullets are the failure
+mode this phase exists to avoid). Each paragraph:
+
+- the `display_name`, and a one-sentence what/why;
+- **`On record (before this session):`** — `where_left_off` and
+  `next_steps` near-verbatim (paraphrase drift is how cursors go vague),
+  plus the top 1–2 `open_questions` when present (that field IS "what
+  hangs on it");
+- **`This session:`** — one sentence on how *this* session moved the
+  cursor, sourced from debrief's session inventory.
+
+The two temporal labels are load-bearing: Ring 3 processes this
+session's transcript *after* close, so the on-disk cursor still
+describes the world *before* this session. Without the labels it reads
+as confidently wrong ("next: build X" when X was just built); with them
+it reads as a progress narrative. Disk = the arc; this session = the
+delta.
+
+### 3. Inbox drain — at most one well-explained decision
+
+It is an **inbox** (signals awaiting triage), not a decision queue —
+present it that way. Import from the resolved main checkout:
+
+```js
+import { listPending, applyBatch, GATED_CATEGORIES, DISPATCHED_CATEGORIES }
+  from '<MAIN_ROOT>/scripts/watchtower-queue.mjs';
+```
+
+Load `listPending({ project: identity.name })` and **exclude
+`GATED_CATEGORIES ∪ DISPATCHED_CATEGORIES`** (import the sets — never
+hand-list categories; the membership drifts the moment a category is
+added). Gated/dispatched items (qa-handoff, routine) belong to window
+1's standing station — a closing session must never dispose of them
+(a terminal exit on a dispatched item reaches into the station's mux
+dispatch queue). If any are pending, show ONE visibility line and move
+on: `N qa-handoff item(s) pending — dispatched to window 1.`
+
+From what remains, **prefer fresh items** (filed during or near this
+session) — re-surfacing of older skipped items is `/briefing`'s job, not
+the epilogue's; this keeps the epilogue from becoming a static affordance
+the operator learns to skim past. Then:
+
+- If one category has **≥3 items disposable by a single judgment** (e.g.
+  stale knowledge-extraction drafts), present **one category-batch
+  decision** in full prose.
+- Otherwise present at most **3 singletons**, only the **first** in full
+  prose; the rest as one-liners the operator can ask about.
+
+**Hard cap: one full-prose decision per epilogue.** Every decision
+carries, in plain English: what this is, why it's in front of you now,
+what each choice means, and what hangs on it — a decision the operator
+can make without holding system internals in their head. **Prose only —
+no AskUserQuestion** (a dialog eclipses the prose it asks about, and the
+decision content is exactly what the operator must read; see
+`cabinet/skill-output-conventions.md`).
+
+On the operator's reply, apply approvals with **one `applyBatch` call per
+disposition group** (resolve and dismiss can't share a call) — never
+per-item `resolveItem`/`dismissItem` loops:
+
+```js
+const r = applyBatch(ids, { disposition: 'dismiss', resolution_type: '<typed>', notes: '<reason>' });
+```
+
+`applyBatch` pre-validates the whole group and throws before writing if
+anything is wrong (unknown id, a gated item slipping in) — a throw is a
+**stop-and-show**, not a retry: name what it refused and stop. Anything
+the operator doesn't act on stays pending — nothing is lost. The write is
+safe even though the seeded session is already orienting (each item is an
+atomic temp+rename; there is no shared-file race to "fix").
+
+### Anti-accretion invariant (frozen)
+
+The epilogue has **exactly two sections — threads, then one decision —
+and that count never grows.** Every future "the epilogue should also show
+X" idea either displaces something within the existing caps or routes to
+`/briefing` (the portfolio curator that owns persistent surfacing). No
+new sections, ever. This is the same discipline /briefing v2 holds, for
+the same reason: a close-of-session surface that accretes becomes the
+noise it was built to replace.
+
 ## Degradation (no silent failure)
 
 - **mux absent / desk gone / `mux handoff` fails:** the seed was
@@ -141,6 +303,10 @@ fully complete before phase 2.
   the seed survives via the file. Nothing is lost.
 - **No merges / no QA handoffs to sweep:** debrief's sweep phase
   self-skips silently; phase 2 still runs.
+- **Epilogue, no watchtower installed:** Phase 3 reports
+  `Epilogue skipped (no watchtower).` and closes — a structural
+  self-skip, never a swallowed error. A read that fails *with*
+  watchtower present surfaces one loud line instead.
 
 ## Scope boundary
 
@@ -150,6 +316,9 @@ fully complete before phase 2.
 - It spawns the window **only on approve**, as the last act of phase 2.
 - It does not run the next session's work — it hands it the seed and
   stops.
+- Phase 3 makes **no mux calls** and **no thread-file writes** — it
+  reads watchtower state and disposes inbox items through `applyBatch`.
+  It never blocks the close.
 
 ## Follow-ups (tracked, not in this skill yet)
 

package/templates/skills/setup-accounts/SKILL.md

@@ -72,8 +72,19 @@ Apply both filters in order:
    is completed). Show a note in the overview table: "Waiting on
    [dependency item prompt]".
 
-The skill operates on items of any `kind` — the walkthrough UX applies
-to `credential`, `provide`, `confirm`, and `decide` items alike.
+**Decisions are answered in `/collab-client`, not here (§5.1).** This
+skill walks the client through *account setup* — items of kind
+`credential`, `provide`, and `confirm`. `decide` items are now rendered
+as answerable decisions in the client packet (the engine's internalized
+projection), so **exclude `decide` items from this walkthrough.** If the
+filtered set contains `decide` items (or the section is decide-only),
+do not walk them — surface a one-line redirect:
+> N decision(s) in this engagement are answered in `/collab-client`
+> under "Needs your attention" — run `/collab-client updates`.
+
+Setup-accounts records only account-setup answers
+(`credential` / `provide` / `confirm`); it never records a `decide`
+answer.
 
 **Empty result guard:** If the filtered item set is empty (no items
 match the section or all are gated by dependencies), tell the user and
@@ -119,17 +130,25 @@ the overview table.
 
 ### Item Selection (for lists > 5 items)
 
-If there are more than 5 incomplete items, present the overview table
-first, then ask which items the user wants to tackle this session
-rather than walking through all of them sequentially:
-
-Use `AskUserQuestion`:
-- header: "This session"
-- question: "Which items do you want to work on now? You can always
-  come back for the rest."
-- multiSelect: true
-- options: one per incomplete item (label: item prompt, description:
-  cost/time summary)
+`AskUserQuestion` allows **at most 4 options per call**, so never emit
+one option per item when there are many — it would overflow the dialog.
+For more than 5 incomplete items, present the overview table first, then
+narrow in **grouped steps**, each a question with ≤4 options:
+
+1. **Pick a group.** Offer up to 4 groups — by `section` (when items
+   span sections), else by `tier` within the section (e.g.
+   blocks-launch, recommended, pre-ad-spend). Each option label is the
+   group name + its remaining count; if there are more than 4 groups,
+   collapse the remainder into a final "Everything else" option.
+2. **Pick items within the chosen group.** If the group has ≤4
+   incomplete items, ask one `multiSelect` question (one option per
+   item). If it has more, walk them in order, or batch into successive
+   ≤4-option `multiSelect` questions — never a single >4-option call.
+
+**Long prompts:** an option `label` must stay short — summarize a long
+item `prompt` to a few words (the service / account name) for the label,
+and put the full prompt in the option `description` and the per-item
+detail view. Never paste a multi-sentence prompt into a label.
 
 For 5 or fewer incomplete items, proceed directly to the per-item
 walkthrough without asking.
@@ -356,7 +375,10 @@ node "/absolute/path/to/engagement/capture-and-encrypt.mjs" \
 For non-credential items, record completion:
 - `kind: confirm` → `recordAnswer(state, key, { mode: 'confirmed', confirmed_at: new Date().toISOString() })`
 - `kind: provide` → `recordAnswer(state, key, { mode: 'provided', value: '<user input>', provided_at: new Date().toISOString() })`
-- `kind: decide` → `recordAnswer(state, key, { mode: 'decided', value: '<selected option>', decided_at: new Date().toISOString() })`
+
+(`kind: decide` items are NOT walked or recorded here — they are answered
+in `/collab-client`; see "Decisions are answered in `/collab-client`"
+under Select Items.)
 
 ### Path B: "Someone else will handle this"
 
@@ -411,8 +433,8 @@ For non-credential items, record completion:
 3. If `kind: provide`: ask for the value directly.
    Record: `recordAnswer(state, key, { mode: 'provided', value: '<input>', provided_at: new Date().toISOString() })`
 
-3b. If `kind: decide`: ask the user to choose from the item's `options`.
-   Record: `recordAnswer(state, key, { mode: 'decided', value: '<selected option>', decided_at: new Date().toISOString() })`
+   (`kind: decide` does not occur here — decisions are answered in
+   `/collab-client`, not in this walkthrough; see Select Items.)
 
 4. If `kind: confirm`: mark as confirmed.
    Record: `recordAnswer(state, key, { mode: 'confirmed', confirmed_at: ... })`

package/templates/skills/threads/SKILL.md

@@ -97,6 +97,10 @@ inferring the arc — the turning points, where it stands now, and its
 `lineage` if present (what it grew out of, what it merged into). End
 with the current cursor's open questions and next steps.
 
+> This is **one work thread's** evolution. For the whole project's
+> **decision causality** — what past decisions still constrain it, what
+> superseded what — use the `/briefing lineage` drill-down instead.
+
 ### Connections mode
 
 Across all threads, surface: shared concepts (overlapping cursor

package/templates/skills/triage-audit/SKILL.md

@@ -135,6 +135,12 @@ visible in the triage UI with its full context — title, description,
 assumption, evidence, question, and your commentary. The user needs to
 see everything to make good decisions.
 
+**Register:** the commentary you write for each finding is operator-facing
+— plain English, concept-first, framing what the finding means and what
+the fix would cost (see `cabinet/skill-output-conventions.md` §9). Keep
+exact paths and symbols in the finding's evidence field where they
+belong; the commentary explains, it doesn't re-dump the location.
+
 **Fallback (no browser available):** Present findings in the conversation
 grouped by cabinet member, severity-ordered within each group. For each
 finding, show its full context (title, description, assumption, evidence,

package/templates/skills/validate/phases/validators.md

@@ -181,6 +181,47 @@ committed ones survive, masking the problem). `README.md` indexes are
 tracked, so they don't flag. Skips silently outside a git work tree or
 when neither directory exists.
 
+### qa-handoff-verdict
+
+```bash
+node -e '
+const fs=require("fs"),os=require("os"),path=require("path");
+const dir=path.join(os.homedir(),".claude-cabinet","watchtower","queue","items");
+if(!fs.existsSync(dir)){console.log("no watchtower queue — skipping");process.exit(0)}
+let bad=0;
+for(const f of fs.readdirSync(dir)){
+  if(!f.endsWith(".json"))continue;
+  let j;try{j=JSON.parse(fs.readFileSync(path.join(dir,f),"utf8"))}catch{continue}
+  if(j.category==="qa-handoff"&&j.status==="resolved"){
+    const v=j.qa_verdict;
+    if(!v||typeof v!=="object"||Array.isArray(v)){
+      console.log("WARN bypass: "+j.id+" — resolved qa-handoff with no validated qa_verdict ("+(j.resolved_at||"").slice(0,10)+", "+(j.project||"?")+")");
+      bad++;
+    }
+  }
+}
+if(bad>0){
+  console.log("");
+  console.log(bad+" resolved qa-handoff item(s) lack a validated qa_verdict — resolved by a");
+  console.log("direct file write that bypassed the recipient gate (validateQaVerdict fires only");
+  console.log("through resolveItem). Pre-gate items are legacy; post-gate ones mean QA was");
+  console.log("recorded without a verdict. Review, and re-resolve through the gate if live.");
+}else{
+  console.log("All resolved qa-handoff items carry a validated qa_verdict.");
+}
+'
+```
+
+Surfaces the one hole in the staff-QA recipient gate: the gate guards
+`resolveItem`, not the file. A session that writes queue-item JSON
+directly can stamp a resolved `qa-handoff` with no (or an unvalidated)
+`qa_verdict` — the bypass demonstrated 4× within hours of the gate
+shipping. This is a **warning, not a gate** (exit 0): pre-gate handoffs
+legitimately lack a verdict and can't be dated per-consumer, so failing
+`/validate` on them would cry wolf. It still names every offender so a
+post-gate bypass is visible. Skips silently when no watchtower queue
+exists.
+
 ## Example Validators (commented — enable for your project)
 
 <!--

package/templates/skills/watchtower/SKILL.md

@@ -6,7 +6,7 @@ description: >
   queue depth), configure (add/remove projects, adjust frequencies).
   Use when: "/watchtower", "watchtower status", "install watchtower",
   "configure watchtower".
-argument-hint: "install | status | configure"
+argument-hint: "install | status | configure | sync"
 ---
 
 # /watchtower
@@ -21,6 +21,7 @@ Parse `$ARGUMENTS` to determine subcommand:
 |-------|------------|
 | (empty), "status" | **status** |
 | "install" | **install** |
+| "sync" | **sync** |
 | "configure" | **configure** |
 | "uninstall" | **uninstall** |
 
@@ -30,6 +31,26 @@ Parse `$ARGUMENTS` to determine subcommand:
 
 Set up the Watchtower daemon and register projects.
 
+> **Reinstall keeps the runtime fresh automatically.** Once a runtime
+> exists at `~/.claude-cabinet/watchtower/`, every `create-claude-cabinet`
+> reinstall content-hash-refreshes the runtime scripts, hooks, and cabinet
+> docs (changed-or-new files only — including a brand-new `watchtower-*.mjs`
+> that wasn't in the runtime yet) via `lib/watchtower-setup.js`. The refresh
+> is **content-aware**: it compares each template against the runtime file's
+> ACTUAL on-disk bytes (not a cached manifest), so a hand-edited or stale
+> runtime file self-heals back to the template on reinstall — it can't be
+> silently skipped. No hand-copy of `templates/scripts/watchtower-*.mjs` is
+> needed after a template edit. This `install` step still owns the ONE-TIME
+> fresh setup below that the refresh never touches: directory tree creation,
+> `config.json`, the launchd/systemd daemons, the project-key migration, and
+> the coherence assertion. (The refresh is refresh-only — it no-ops when no
+> runtime exists yet.)
+>
+> **For a single-file fix between full reinstalls, use `/watchtower sync`**
+> (below) — it hash-diffs the three script tiers (template → tracked → live
+> runtime) and heals the divergence without re-running daemon registration.
+> `/watchtower status` reports the same diff read-only.
+
 ### Steps
 
 1. **Create directory tree**
@@ -45,6 +66,8 @@ Set up the Watchtower daemon and register projects.
        watchtower-ring3-close.mjs
        watchtower-build-context.mjs
        watchtower-migrate-keys.mjs
+       watchtower-hook-runner.mjs
+       watchtower-phase-shim.mjs
      hooks/
        watchtower-session-end.sh
      state/
@@ -66,13 +89,18 @@ Set up the Watchtower daemon and register projects.
    - `watchtower-ring2-runner.sh`
    - `watchtower-validate.mjs`
    - `watchtower-queue.mjs` (if present — ships with Plan 2)
+   - `watchtower-routines.mjs` (routine dispatch engine)
    - `watchtower-ring3-close.mjs`
    - `watchtower-build-context.mjs` (REQUIRED by the SessionStart hook)
    - `watchtower-migrate-keys.mjs` (project-key migration tool)
+   - `watchtower-hook-runner.mjs` (consumer hook runner — Plan 9)
+   - `watchtower-phase-shim.mjs` (consumer phase-migration adapter — Plan 9)
 
    After copying, assert the set is coherent before any ring runs:
    ```bash
-   node -e "import(process.env.HOME + '/.claude-cabinet/watchtower/scripts/watchtower-lib.mjs').then(m => process.exit(m.resolveProjectIdentity && m.updateThreadFile && m.preserveRing3LastSession ? 0 : 1))"
+   node -e "import(process.env.HOME + '/.claude-cabinet/watchtower/scripts/watchtower-lib.mjs').then(m => process.exit(m.resolveProjectIdentity && m.updateThreadFile && m.preserveRing3LastSession && m.writeProjectStatePreservingRing3 && m.flushFeedbackOutbox ? 0 : 1))"
+   node -e "import(process.env.HOME + '/.claude-cabinet/watchtower/scripts/watchtower-routines.mjs').then(m => process.exit(m.runRoutinePass && m.triggerDue && m.validateRoutine ? 0 : 1))"
+   node -e "import(process.env.HOME + '/.claude-cabinet/watchtower/scripts/watchtower-hook-runner.mjs').then(m => process.exit(m.runSeam && m.ensureRegistered && m.discoverHooks ? 0 : 1))"
    ```
 
 2b. **One-time project-key migration** (upgrades from pre-resolver versions): older Ring 3 builds filed inbox items, session dirs, and thread memberships under worktree-basename phantom keys. Run the migration after copying scripts — dry-run first, review the per-key counts, then apply:
@@ -92,6 +120,17 @@ Set up the Watchtower daemon and register projects.
    - Ask user which projects to track (default: all registered)
    - Set default ring frequencies (ring1: 300s)
 
+4b. **Register the consumer hook runner** (Plan 9 — wires the ring seams to
+   the runner without editing the rings). Idempotent and append-only: it adds
+   the runner command to each of the three `config.hooks` seam arrays only if
+   absent, preserving any raw consumer commands already there.
+   ```bash
+   node ~/.claude-cabinet/watchtower/scripts/watchtower-hook-runner.mjs --register
+   ```
+   After this, a consumer activates project-specific background behavior by
+   dropping executable scripts into `<project>/.claude/watchtower/hooks/<seam>/`
+   — no further config editing. See "Consumer hooks" below.
+
 5. **Install platform daemons**:
    - **macOS**: Copy plist files to `~/Library/LaunchAgents/`, then `launchctl load` each:
      - `com.claude-cabinet.watchtower-ring1.plist`
@@ -133,6 +172,68 @@ Watchtower installed.
 
 ---
 
+## Subcommand: sync
+
+Propagate a watchtower script/hook/doc fix across the three tiers — template
+(`templates/`), tracked (the project's committed `scripts/` + `.claude/`), and
+the live runtime (`~/.claude-cabinet/watchtower/`) — WITHOUT re-running daemon
+registration, `config.json`, or project re-registration. This is the surgical
+path the maintainability rules ask for: a one-file fix no longer needs a full
+`create-claude-cabinet` reinstall or a `/watchtower install` re-run, and no
+hand-copy to three locations.
+
+`watchtower-sync.mjs` reads the ACTUAL on-disk bytes of every tier (never a
+cached manifest, which can itself go stale), classifies each watchtower file,
+and propagates the authoritative tier downward. Authority is by contract:
+**template wins when present, else the tracked copy; the runtime is always a
+heal target and never a source, and the template tier is never written.** The
+managed file set is DISCOVERED by scanning the tiers, so the sync tool cannot
+itself accumulate a stale hardcoded list.
+
+### Steps
+
+1. **Preview the divergence** (read-only):
+   ```bash
+   node ~/.claude-cabinet/watchtower/scripts/watchtower-sync.mjs --check
+   ```
+   Show the operator the per-file report (drift / missing / orphan) before
+   touching anything.
+
+2. **Heal** — preview the writes first, then apply:
+   ```bash
+   node ~/.claude-cabinet/watchtower/scripts/watchtower-sync.mjs --heal --dry-run
+   node ~/.claude-cabinet/watchtower/scripts/watchtower-sync.mjs --heal
+   ```
+
+3. **Commit any TRACKED-tier heals.** The report flags when tracked-tier files
+   changed — those are committed project copies, so an uncommitted heal reverts
+   on the next clean checkout. The runtime tier heals in place (regenerated
+   infra — no commit needed).
+
+4. **Orphans are reported, never auto-deleted.** A script that lingers only in
+   the runtime (removed upstream) is surfaced for deliberate manual removal.
+
+5. **No daemon restart** is needed for a pure script/doc refresh — the rings
+   re-read their scripts on the next cron tick. Restart a ring only if you
+   changed its runner or cadence (see configure).
+
+If the runtime does not exist yet (`watchtower-sync.mjs` not found under
+`~/.claude-cabinet/watchtower/scripts/`), there is nothing to sync to — run
+`/watchtower install` first.
+
+### Output
+
+```
+Watchtower sync
+  template: <path or (absent)>
+  tracked:  <path or (absent)>
+  runtime:  <path>
+  <N>/<total> in sync · <N> drift · <N> missing · <N> orphan
+  healed: <list, or "nothing to heal">
+```
+
+---
+
 ## Subcommand: status
 
 Show Watchtower health and current state.
@@ -168,6 +269,24 @@ Show Watchtower health and current state.
 
 6. **Read config for project list**
 
+7. **Read frontier-watchdog state**: read `~/.claude/cc-registry.json`. If
+   `frontierModel` is a non-empty string, report the designated key. If it
+   is absent or empty, report the watchdog is inert (a never-configured
+   watchdog must not read the same as a passing one — act:77f7b7b2).
+
+8. **Script-tier sync check** (read-only): hash-diff the three watchtower
+   script tiers — template → tracked → live runtime — so a missed copy
+   surfaces here instead of as a silently-not-running fix. Run from the
+   project root (cwd resolves the tracked tier; template is detected only in
+   the CC source repo):
+   ```bash
+   node ~/.claude-cabinet/watchtower/scripts/watchtower-sync.mjs --check
+   ```
+   Exit 0 = all tiers in sync; exit 2 = drift/missing/orphan detected. On
+   drift, report the count and point the operator at `/watchtower sync` to
+   heal it. This step is read-only — it never writes. If the runtime script is
+   absent (no runtime yet), skip and note `/watchtower install` is needed.
+
 ### Output
 
 ```
@@ -179,6 +298,8 @@ Watchtower Status
   Inbox:       <N> pending items (oldest: <age>)
   Summary:     updated <time> ago
   Memory:      <pass/violations> (see state/memory-health.md)
+  Frontier:    <designated key> — OR — none designated; watchdog inert (set: npx create-claude-cabinet --frontier-model <value>)
+  Scripts:     in sync across tiers — OR — <N> drifted/missing (run /watchtower sync to heal)
   Projects:
     <name>: state updated <time> ago
     ...
@@ -209,6 +330,8 @@ Interactively add/remove projects, adjust frequencies, toggle defaults.
    - Change Ring 2 slow frequency (default 1800s)
    - Toggle Ring 3 features (session_auto_naming, etc.)
    - Toggle defaults (decision_routing, stale_work_detection, etc.)
+   - Manage routines (declare/edit/remove a project's interactive
+     routines — see "Routines" below)
    - View current configuration
 
 3. **Write updated config.json** atomically
@@ -221,6 +344,80 @@ Interactively add/remove projects, adjust frequencies, toggle defaults.
 
 Show the updated configuration summary.
 
+### Routines
+
+Declared interactive routines are the push mechanism for a project's
+recurring conversations (morning briefing, command-queue processing,
+articulation sweeps): watchtower watches the trigger and dispatches the
+routine to the desk's main session the way QA handoffs are dispatched —
+nothing depends on the operator remembering a verb. The declaration
+schema, trigger types, and ownership contract live in
+`watchtower-contracts.md` ("Routine Dispatch"). When declaring one:
+
+1. Ask for name (kebab-case), trigger (time-of-day / interval /
+   path-nonempty / session-close + its parameter), and the script path.
+2. The script is a project-authored phase file (e.g.
+   `.claude/routines/<name>.md`) holding the conversation script. If it
+   does not exist yet, offer to draft it with the user — a routine
+   pointing at a missing script dispatches a prompt that immediately
+   dead-ends.
+3. Validate against `validateRoutine` before writing:
+   ```bash
+   node -e "import(process.env.HOME + '/.claude-cabinet/watchtower/scripts/watchtower-routines.mjs').then(m => { const e = m.validateRoutine(JSON.parse(process.argv[1])); if (e.length) { console.error(e.join('; ')); process.exit(1); } })" '<routine-json>'
+   ```
+4. Write the routine into `config.json` under
+   `projects.<name>.routines` (atomic write).
+
+Routine firings appear as `routine` inbox items and in the desk's ·N
+badge; they resolve normally (`resolution_type: 'acted-on'`) — no QA
+gate, normal expiry. `defaults.routine_dispatch: false` turns the whole
+mechanism off.
+
+### Consumer hooks (non-interactive customs)
+
+Routines are the INTERACTIVE extension model (they talk to the operator).
+Consumer hooks are the NON-INTERACTIVE counterpart: unattended scripts that
+run in the background at the ring lifecycle seams — Flow's Railway DB pull and
+machine-drift check, article-rewriter's reMarkable sync and Sentry check,
+maginnis's timelog collection. They never prompt; anything that needs the
+operator is a routine, not a hook.
+
+A consumer adds a hook by dropping an executable script into the project:
+
+```
+<project-root>/.claude/watchtower/hooks/<seam>/<NN>-<name>.{sh,mjs,js,py}
+```
+
+The three seams, and what each hook receives on stdin:
+
+| Seam | Fires | stdin state |
+|------|-------|-------------|
+| `ring1-post-collect` | Ring 1, per project, after state collection (every ~5m) | the project's collected state (`name`, `path`, `git`, `pib`, …) |
+| `ring2-slow-post` | Ring 2 slow tier, portfolio-wide (every ~30m) | the slow-tier state |
+| `ring3-close-post` | Ring 3, at each session close | `{ session_id, project, project_path, summary, stats }` |
+
+`watchtower-hook-runner.mjs` (registered once per seam by install step 4b)
+discovers the scripts in name order, runs each in the project root with the
+ring state on stdin and `WATCHTOWER_SEAM` / `WATCHTOWER_PROJECT` /
+`WATCHTOWER_PROJECT_PATH` / `WATCHTOWER_SESSION_ID` exported, isolates each
+failure, and budgets the batch to finish inside the ring's timeout. A hook
+that prints `{"additional_checks":[…]}` has those surfaced to Ring 1. Files
+prefixed `_` or `.` are skipped (the disable convention). Full I/O contract:
+`watchtower-contracts.md` → "Consumer Hook Contract (Plan 9)".
+
+**Migrating an existing script** (the orient/debrief phase → ring hook path):
+if the logic already lives in a repo script that expects the project root as
+cwd rather than reading stdin, register it through the shim instead of moving
+it — one line in `config.hooks[<seam>]`:
+
+```
+node ~/.claude-cabinet/watchtower/scripts/watchtower-phase-shim.mjs --phase scripts/<existing>.sh
+```
+
+The shim runs it with the same cwd/env/stdin normalization, so the port is
+mechanical. New hooks should prefer the drop-in directory; the shim is for
+scripts that already exist.
+
 ---
 
 ## Subcommand: uninstall