create-claude-cabinet 0.48.0 → 0.50.0

package/templates/cabinet/watchtower-contracts.md

@@ -336,6 +336,91 @@ each owning its tier. Flag: `defaults.recall_canary` (opt-out).
   extraction never proposed (M2 under-extraction). The canary states
   this blindness in its own output.
 
+## Detector Symmetry (no detector without a retraction path)
+
+The 2026-07-12 inbox drain (893→194 pending) hit the same disease four
+times in four detectors: branch-diverged never retracted (35/39 stale),
+completion-review never reconciled (28/66 moot), worktree-unmerged
+retracted only on branch deletion, and dismissed items refiled on the
+next tick because dedup checks only PENDING items (the `backup/*` loop
+refiled within hours, twice in one day). `autoResolveWorktreeItems`'
+own comment states the principle: dedup suppresses refiling but nothing
+retracts the original — **stale alarms train the operator to ignore
+real ones**. This contract encodes the rule so detector #5 cannot ship
+with the same bug (grp:wt-noise-immunity, act:4d11fd53).
+
+**Every detector that FILES an inbox item must declare, at ship time:**
+
+1. **Its retraction condition** — the mechanical, per-tick check that
+   the filed condition no longer holds (branch merged/gone, action
+   closed, …). Retraction is truth-checking, not judgment: it runs in
+   Ring 1's tick beside the other reconcilers.
+2. **Its filing exclusions** — states that must never file, checked at
+   the FILING site (not just retraction) so a human dismissal cannot
+   reopen the loop: dedup consults only pending items, so an excluded
+   state that files at all refiles after every dismissal, forever.
+3. **Or an explicit exemption** — a detector with no possible
+   mechanical retraction (pure knowledge extraction, advisory
+   observations, session-historical facts) declares that explicitly in
+   the registry, with the rationale.
+
+**The registry and its enforcement:** `INBOX_DETECTOR_REGISTRY` in
+`watchtower-lib.mjs` maps every ring-filed category to
+`{ reconciler }` or `{ exempt }` (exactly one). A structural test
+(`templates/scripts/__tests__/detector-registry.test.mjs`) parses the
+`category:` literals at `createItem` filing sites across ring1, ring2,
+and ring3-close (read-only source scan, house precedent:
+suppression-ledger's wiring assertion) and fails the suite when a
+filing site's category is missing from the registry — a new category
+without a declared reconciler or exemption breaks the build, not the
+operator's trust.
+
+**Machine resolutions are machine acts, not engagement.** Every
+auto-retraction resolves through `autoReconcileItem` (watchtower-lib):
+`resolution_type: 'auto-reconciled'` + `evidence.actor: 'ring1'` + a
+note naming the evidence (action fid / branch). The cross-ring reader's
+engagement bucketing and the inbox assessment's `worked_recent` EXCLUDE
+this type — cron sweeps must never read as operator engagement or
+suppress the not-consumed verdict. A semantically-wrong close (e.g. an
+action closed via the ungated `pib_update_action --status done` path)
+stays traceable to its mechanical trigger through the stamp.
+
+**Fail-toward-keeping.** A reconciler retracts only on POSITIVE
+evidence that the condition cleared: branch absence is concluded only
+from membership in a successful branch listing (a failed git call
+retracts nothing); an action-fid lookup retracts only on a FOUND,
+non-deleted, closed row — fid-not-found keeps the item, which is
+load-bearing for flow (a readable-but-vestigial pib.db; the real
+tracker is flow.db) and for misattributed items whose fid lives in a
+different project's db. Foreign pib.dbs are opened READ-ONLY behind an
+existsSync guard; reconciler writes land only in the watchtower queue.
+
+**Branch exclusion list:** `defaults.long_lived_branches` (watchtower
+config), default `["staging", "production", "backup/*"]`. Entries
+without `*` are EXACT names (`staging-fix` files normally); `*` is a
+glob. **Consumer-default risk, documented:** a consumer whose real work
+branch is literally named `staging` or `production` will never get a
+branch-diverged item for it — the branch stays visible on the attention
+line / git-attention sidecar / summary / Standing Issues (the exclusion
+gates filing ONLY), and the consumer overrides the list in config.
+
+**Standing-debt aggregation (coverage-warning first):** a detector
+whose finding is a STANDING condition (recurs while a debt persists)
+files ONE item per (project, debt-class) and APPENDS evidence to the
+pending item (path union + per-path counts + session count), carrying
+`evidence.first_seen` (oldest evidence date) so aging reads the debt's
+true age, with an urgency escalation at a session-count threshold.
+Resolving the item closes the accumulated view; if the debt persists,
+the next tick files FRESH — post-disposition recurrence is a new
+signal, not a refile loop (act:e888dd63; 49 identical coverage-warning
+items for one month-old debt was the live specimen).
+
+**Known limitation (named, not hidden):** reconcilers run per
+configured project — items whose project was deleted or de-registered
+are never visited and age pending until a human disposes them (the
+inbox's aging surfaces them). Auto-resolving on "project gone" would
+guess; the honest state is pending.
+
 ## Deferred Schemas
 
 The following are specified in project notes but NOT formalized until

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

@@ -97,15 +97,57 @@ correct in both places — no on-main special case. One rule, both
 directions: worktree-invisible `.claude/` state is always addressed
 through `$MAIN`, whether you are writing it (§3) or reading it (here).
 
-## What this contract does NOT cover
-
-Caller-specific orchestration stays in the caller's own Step 0, never
-here:
+## 5. Worktree environment lifecycle (mux projects)
+
+Mux owns the worktree environment end to end; sessions should not
+hand-repair it. Three verbs, all single-sourced in
+`~/.config/mux/worktree-session-health.sh`:
+
+- **Provision** — a project that declares gitignored env files in
+  `.mux-worktree-provision` (project root; one path per line) gets them
+  copied from main at worktree creation and freshness-checked on later
+  health runs. A locally-modified worktree copy is never overwritten.
+- **Preflight** — `mux worktree preflight [project]` verifies main's
+  declared env files exist and every declared `check:` command passes.
+  Run it BEFORE spawning parallel worktree lanes; non-zero exit means
+  do not spawn yet. Probes should verify identity/freshness, not bare
+  liveness — a leftover stack answers a bare port probe. Trust note:
+  `check:` lines execute as shell from the project root (same trust
+  class as npm scripts and CC hooks) — don't run preflight inside a
+  clone you don't trust.
+- **Reap** — every worktree removal path stops the lane's docker
+  containers (exact compose-project-label match on the worktree dir
+  name; containers only, volumes kept). Assumes the lane's compose
+  stack was started from the worktree ROOT (compose's default project
+  name = directory basename); a stack started with `-p`/
+  `COMPOSE_PROJECT_NAME` or from a subdirectory is not reaped. Nothing
+  for a session to do; noted so cleanup surprises are recognized as
+  reaping, not data loss.
+
+One symptom worth recognizing from a worktree: if `git merge main`
+aborts citing "local changes to .mcp.json" while `git status` shows
+clean, that is the mux identity symlink held under skip-worktree (main
+changed the file since the worktree was cut — pre-existing behavior
+either way). Recovery: `git update-index --no-skip-worktree .mcp.json
+&& git checkout -- .mcp.json && git merge main`; the next health run
+re-symlinks and re-hides.
+
+## Who merges (universal), and what stays caller-specific
+
+The universal rule every caller shares (act:3d1ac2b7): **finished worktree
+work is MERGED by its producer** — a close-out or handoff describes work
+already on main, and `merge_state: "merge-pending"` exists only for a
+merge explicitly gated on something external, named in
+`evidence.merge_gate`.
+
+The merge ORCHESTRATION is caller-specific and stays inline in each
+caller's own skill, 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.
+  agents branch from and merge into MAIN regardless of the invoking cwd
+  (sequential, baseline-gated merges owned by the workflow), and its
+  inline-build escape hatch.
+- **`/execute`** keeps inline: its merge-first close-out — Step 8
+  delegates the merge to `/qa-handoff`'s merge-now recipe, then files a
+  `merged` handoff that dispatches; every merge failure HALTs, never
+  silently downgraded to merge-pending.

package/templates/engagement/__tests__/transport-token.test.mjs

@@ -0,0 +1,103 @@
+// Unit tests for the transport token pre-flight (act:8b527625).
+// Run: node --test templates/engagement/__tests__/transport-token.test.mjs
+// Guards the structural fix for the silent-failure-on-missing-token path:
+// checkToken never throws and returns actionable guidance; resolveToken's
+// throw carries the same guidance (the backstop when pre-flight is skipped).
+
+import { test } from 'node:test';
+import assert from 'node:assert';
+import {
+  checkToken,
+  resolveToken,
+  missingTokenGuidance,
+} from '../engagement-transport.mjs';
+
+const VAR = 'CC_TEST_ENGAGEMENT_TOKEN_UNSET';
+
+test('checkToken: unset env var → ok false with actionable message', () => {
+  delete process.env[VAR];
+  const r = checkToken({ token: `env:${VAR}` });
+  assert.strictEqual(r.ok, false);
+  assert.strictEqual(r.varName, VAR);
+  assert.match(r.message, new RegExp(`${VAR} is not set`));
+  assert.match(r.message, /export CC_TEST_ENGAGEMENT_TOKEN_UNSET=/, 'message names the export line');
+  assert.match(r.message, /API Tokens/, 'message says where to get the key');
+  assert.match(r.message, /Restart your terminal/, 'message says to restart the shell');
+});
+
+test('checkToken: set env var → ok true', () => {
+  process.env[VAR] = 'tok-123';
+  try {
+    assert.deepStrictEqual(checkToken({ token: `env:${VAR}` }), { ok: true });
+  } finally {
+    delete process.env[VAR];
+  }
+});
+
+test('checkToken: empty-string env var counts as unset', () => {
+  process.env[VAR] = '';
+  try {
+    const r = checkToken({ token: `env:${VAR}` });
+    assert.strictEqual(r.ok, false);
+    assert.strictEqual(r.varName, VAR);
+  } finally {
+    delete process.env[VAR];
+  }
+});
+
+test('checkToken: literal token → ok true', () => {
+  assert.deepStrictEqual(checkToken({ token: 'literal-token' }), { ok: true });
+});
+
+test('checkToken: no token configured → ok false, varName null, names transport.token', () => {
+  for (const cfg of [{}, { token: '' }, null, undefined]) {
+    const r = checkToken(cfg);
+    assert.strictEqual(r.ok, false);
+    assert.strictEqual(r.varName, null);
+    assert.match(r.message, /transport\.token/);
+  }
+});
+
+test('checkToken never throws', () => {
+  for (const cfg of [undefined, null, {}, { token: 42 && 'env:' }, { token: 'env:' }]) {
+    assert.doesNotThrow(() => checkToken(cfg));
+  }
+});
+
+test('resolveToken: unset env var throws WITH the guidance, not the bare error', () => {
+  delete process.env[VAR];
+  assert.throws(
+    () => resolveToken(`env:${VAR}`),
+    (err) => {
+      assert.match(err.message, new RegExp(`${VAR} is not set`));
+      assert.match(err.message, /export CC_TEST_ENGAGEMENT_TOKEN_UNSET=/);
+      assert.match(err.message, /API Tokens/);
+      return true;
+    },
+  );
+});
+
+test('resolveToken: set env var resolves; literal passes through; falsy → null', () => {
+  process.env[VAR] = 'tok-456';
+  try {
+    assert.strictEqual(resolveToken(`env:${VAR}`), 'tok-456');
+  } finally {
+    delete process.env[VAR];
+  }
+  assert.strictEqual(resolveToken('literal'), 'literal');
+  assert.strictEqual(resolveToken(''), null);
+  assert.strictEqual(resolveToken(null), null);
+});
+
+test('missingTokenGuidance is the single source both paths share', () => {
+  delete process.env[VAR];
+  const fromCheck = checkToken({ token: `env:${VAR}` }).message;
+  let fromThrow;
+  try {
+    resolveToken(`env:${VAR}`);
+  } catch (err) {
+    fromThrow = err.message;
+  }
+  assert.strictEqual(fromCheck, missingTokenGuidance(VAR));
+  assert.strictEqual(fromThrow, missingTokenGuidance(VAR));
+});

package/templates/engagement/engagement-transport.mjs

@@ -5,12 +5,46 @@ import { join } from 'node:path';
 // Token resolution — env:VAR_NAME or literal
 // ---------------------------------------------------------------------------
 
+export function missingTokenGuidance(varName) {
+  return (
+    `${varName} is not set — the engagement API needs this token to reach the server.\n` +
+    `1. Get your API key: it's the same key you use for the admin tools\n` +
+    `   (platform admin panel → API Tokens). If you don't have one, ask your\n` +
+    `   consultant or admin to create one for you.\n` +
+    `2. Add it to your shell profile:\n` +
+    `   echo 'export ${varName}=your-key-here' >> ~/.zshenv\n` +
+    `3. Restart your terminal (or run: source ~/.zshenv), then try again.`
+  );
+}
+
+// Never throws — the mechanical pre-flight check for the /collab-* skills.
+// { ok: true } when a token resolves; { ok: false, varName, message } when
+// the env var backing an env: ref is unset; { ok: false, varName: null,
+// message } when no token is configured at all.
+export function checkToken(transportConfig) {
+  const tokenRef = transportConfig?.token;
+  if (!tokenRef) {
+    return {
+      ok: false,
+      varName: null,
+      message: 'No API token configured — set transport.token in the engagement config (e.g. "env:ENGAGEMENT_API_TOKEN").',
+    };
+  }
+  if (tokenRef.startsWith('env:')) {
+    const varName = tokenRef.slice(4);
+    if (!process.env[varName]) {
+      return { ok: false, varName, message: missingTokenGuidance(varName) };
+    }
+  }
+  return { ok: true };
+}
+
 export function resolveToken(tokenRef) {
   if (!tokenRef) return null;
   if (tokenRef.startsWith('env:')) {
     const varName = tokenRef.slice(4);
     const value = process.env[varName];
-    if (!value) throw new Error(`Environment variable ${varName} is not set (from token ref "${tokenRef}")`);
+    if (!value) throw new Error(missingTokenGuidance(varName));
     return value;
   }
   return tokenRef;

package/templates/engagement/pib-db-patches/pib-db-lib.mjs

@@ -44,7 +44,11 @@ function today() {
 //   6 — added projects.tags (symmetric with actions.tags at v2)
 //   7 — added client-facing copy columns on actions + projects (4 each)
 //   8 — added engagement_events.visibility (client|internal, default internal)
-export const SCHEMA_VERSION = 8;
+//   9 — audit finding ids run-prefixed (run_id || '/' || id) — same change
+//       as BASE v7 (act:4ec70792); numbered 9 here because the patch owns
+//       7-8. Keep base and patch bumped in the same release
+//       (engagement-setup's base-ahead guard enforces it).
+export const SCHEMA_VERSION = 9;
 
 // Each entry: { version, sql }. A single version may have multiple SQL
 // statements (e.g. column add + index). Statements run in array order;
@@ -53,8 +57,8 @@ export const SCHEMA_VERSION = 8;
 // gate — try/catch is a safety net for pre-pragma DBs.
 //
 // NOTE on version numbering (base vs patch):
-//   Base (work-tracking): v1-v6 (v6 = client columns)
-//   Patch (engagement):   v1-v7 (v5 = engagement_events, v6 = projects.tags, v7 = client columns)
+//   Base (work-tracking): v1-v7 (v6 = client columns, v7 = audit id prefix)
+//   Patch (engagement):   v1-v9 (v5 = engagement_events, v6 = projects.tags, v7 = client columns, v9 = audit id prefix)
 //   The same physical columns appear at different version numbers because
 //   base and patch have different migration histories. The try/catch on
 //   "duplicate column" makes the overlap safe — a DB that already has
@@ -86,6 +90,10 @@ const MIGRATIONS = [
   { version: 7, sql: "ALTER TABLE projects ADD COLUMN client_generated_at TEXT" },
   { version: 7, sql: "ALTER TABLE projects ADD COLUMN client_generated_status TEXT" },
   { version: 8, sql: "ALTER TABLE engagement_events ADD COLUMN visibility TEXT NOT NULL DEFAULT 'internal' CHECK(visibility IN ('client','internal'))" },
+  // v9: prefix legacy audit finding ids with their run id (base v7 twin —
+  // act:4ec70792). Idempotent via the NOT LIKE guard. skipOn: a db that
+  // predates the audit tables has nothing to prefix.
+  { version: 9, sql: "UPDATE audit_findings SET id = run_id || '/' || id WHERE run_id IS NOT NULL AND run_id != '' AND id NOT LIKE run_id || '/%'", skipOn: /no such table: audit_findings/i },
 ];
 
 export function migrate(db) {
@@ -102,7 +110,11 @@ export function migrate(db) {
       if (m.version <= current) continue;
       try { db.exec(m.sql); applied++; }
       catch (e) {
-        if (!/already exists|duplicate column/i.test(e.message || '')) throw e;
+        const msg = e.message || '';
+        // Per-entry skip condition (explicit, never a general widening):
+        // e.g. the v9 audit-id prefix on a db that predates audit tables.
+        if (m.skipOn && m.skipOn.test(msg)) continue;
+        if (!/already exists|duplicate column/i.test(msg)) throw e;
       }
     }
     db.pragma(`user_version = ${SCHEMA_VERSION}`);
@@ -438,37 +450,69 @@ export function ingestFindings(db, { runDir }) {
   const timestamp = data.meta?.timestamp || new Date().toISOString();
   const dateStr = timestamp.slice(0, 10);
 
+  // Same-run re-ingest refreshes the run row; cross-run id collisions are
+  // structurally impossible now that run ids carry the date
+  // (run-<YYYY-MM-DD>-<HH-MM-SS>, minted by merge-findings).
   db.prepare(`
-    INSERT OR REPLACE INTO audit_runs (id, date, timestamp, trigger, finding_count)
+    INSERT INTO audit_runs (id, date, timestamp, trigger, finding_count)
     VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      date = excluded.date, timestamp = excluded.timestamp,
+      trigger = excluded.trigger, finding_count = excluded.finding_count
   `).run(runId, dateStr, timestamp, data.meta?.trigger || 'manual', data.findings?.length || 0);
 
-  // Try the full INSERT with deliberation columns first; fall back to the
+  // Stored finding ids are RUN-PREFIXED (<runId>/<member-NNNN>): member ids
+  // restart every run, and the old bare-id INSERT OR REPLACE silently
+  // destroyed prior runs' rows AND their triage columns on collision
+  // (act:4ec70792, demonstrated live 2026-07-13). The upsert updates
+  // CONTENT columns only — the four triage columns (triage_status,
+  // triage_notes, triaged_at, fix_description) are never in the SET list,
+  // so a same-run re-ingest can never reset an operator's dispositions.
+  // Try the full shape with deliberation columns first; fall back to the
   // legacy shape for existing databases that haven't added them yet.
   let insert;
   let hasDeliberationCols = true;
   try {
     insert = db.prepare(`
-      INSERT OR REPLACE INTO audit_findings
+      INSERT INTO audit_findings
         (id, run_id, cabinet_member, severity, title, description, assumption,
          evidence, question, file, line, suggested_fix, auto_fixable, type,
          status, annotations, rebuttal)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        run_id = excluded.run_id, cabinet_member = excluded.cabinet_member,
+        severity = excluded.severity, title = excluded.title,
+        description = excluded.description, assumption = excluded.assumption,
+        evidence = excluded.evidence, question = excluded.question,
+        file = excluded.file, line = excluded.line,
+        suggested_fix = excluded.suggested_fix,
+        auto_fixable = excluded.auto_fixable, type = excluded.type,
+        status = excluded.status, annotations = excluded.annotations,
+        rebuttal = excluded.rebuttal
     `);
   } catch {
     hasDeliberationCols = false;
     insert = db.prepare(`
-      INSERT OR REPLACE INTO audit_findings
+      INSERT INTO audit_findings
         (id, run_id, cabinet_member, severity, title, description, assumption,
          evidence, question, file, line, suggested_fix, auto_fixable, type)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        run_id = excluded.run_id, cabinet_member = excluded.cabinet_member,
+        severity = excluded.severity, title = excluded.title,
+        description = excluded.description, assumption = excluded.assumption,
+        evidence = excluded.evidence, question = excluded.question,
+        file = excluded.file, line = excluded.line,
+        suggested_fix = excluded.suggested_fix,
+        auto_fixable = excluded.auto_fixable, type = excluded.type
     `);
   }
 
   let count = 0;
   for (const f of (data.findings || [])) {
+    const storedId = String(f.id).startsWith(`${runId}/`) ? f.id : `${runId}/${f.id}`;
     const base = [
-      f.id, runId, f['cabinet-member'], f.severity, f.title,
+      storedId, runId, f['cabinet-member'], f.severity, f.title,
       f.description || null, f.assumption || null, f.evidence || null,
       f.question || null, f.file || null, f.line || null,
       f.suggestedFix || null, f.autoFixable ? 1 : 0, f.type || 'finding'

package/templates/mux/__tests__/mux-fail-loud.fixture.sh

@@ -266,11 +266,10 @@ assert "a worktree window opened" test "$(win_count)" -eq $((before + 1))
 seedf=$(ls -t "$SEED_DIR"/sess-*.txt 2>/dev/null | head -1)
 assert "a seed-prompt file was written" test -n "$seedf"
 if [[ -n "$seedf" ]]; then
-  assert "auto_orient=1 prepends the orient instruction as line 1" \
-    bash -c "head -1 '$seedf' | grep -qx 'Run /orient-quick first to load state, then:'"
-  tail -n +3 "$seedf" > "$SANDBOX/got-body.txt"
-  assert "multi-line prompt body preserved byte-identical (quotes/\$/backticks intact)" \
-    diff "$SANDBOX/expected-body.txt" "$SANDBOX/got-body.txt"
+  # No orient prefix: /orient is retired — the watchtower SessionStart hook
+  # loads state; the seed file carries the prompt VERBATIM.
+  assert "seed file carries the prompt verbatim, no injected preamble (quotes/\$/backticks intact)" \
+    diff "$SANDBOX/expected-body.txt" "$seedf"
 fi
 
 echo "== T12: the prompt is an ARG to claude, never executed as shell (auto-submit safety)"