create-claude-cabinet 0.48.0 → 0.49.0

package/lib/CLAUDE.md

@@ -33,6 +33,16 @@ No build step; CommonJS.
   it, `expandFrozenClosure`, and the hoisted top-level `manifestPath`
   are exported + unit-tested. `generateAgentWrappers()` (see root
   § Generated artifacts) also lives here.
+  Also home of `seedAdvisoriesGitignore()` (act:c008862c,
+  grp:wt-noise-immunity), run in the install body: on FRESH installs
+  only (no prior `.ccrc.json`) it seeds a `.gitignore` entry for
+  `.claude/cabinet/advisories-state.json` (machine-written runtime
+  state — tracked, it churns every commit and reads as authored work in
+  mux worktrees) unless some rule already ignores it (`git
+  check-ignore`); existing installs are left untouched — untracking a
+  live consumer repo is operator-gated — but a TRACKED copy is reported
+  loudly so the consumer walk surfaces it. No-git and dry-run aware,
+  injectable exec, exported for tests.
 - `lib/modules.js` — the `MODULES` manifest: every module → the template
   paths it copies into `.claude/` (architecture-0005; extracted from
   `cli.js` in act:e82baead). `cli.js` requires + re-exports it for
@@ -90,6 +100,18 @@ No build step; CommonJS.
   (act:c1013967): the `.ccrc.json` `frozenModules` accessors for the
   freeze-module mechanism (a non-array reads as empty — shape-drift
   defensive; `create()` preserves the field via `...existing`).
+  Also exposes `readMcpOptOut` (act:b770c323): the `.ccrc.json`
+  `mcpOptOut` accessor — the CC-shipped MCP server keys this consumer
+  declines (flow's `no-pib-db.md` is the live specimen; its validator
+  requires the pib-db registration absent while the engagement→
+  work-tracking closure keeps shipping the files). Same defensive shape
+  as `readFrozenModules`; the key survives reinstalls via `create()`'s
+  `...existing` spread, so a consumer sets it once by hand. Honored by
+  `mergeMcpServers` in `lib/cli.js` (opted-out keys are never added and
+  are REMOVED if present — self-heal toward declared intent; removal is
+  scoped to keys CC ships, so hand-added servers are never touched;
+  nothing-to-contribute installs don't rewrite `.mcp.json`). Tests in
+  `test/mcp-opt-out/`.
   `normalize()` guards shape drift (non-object top level reads as
   'no metadata').
 - `lib/settings-merge.js` — merges CC hooks into `.claude/settings.json`.

package/lib/cli.js

@@ -5,7 +5,7 @@ const os = require('os');
 const crypto = require('crypto');
 const { copyTemplates, recordSkip, isProjectOwnedSeed, classifyFileOwnership } = require('./copy');
 const { mergeSettings, healUserSettings, mergeWatchtowerHooks, mergeMuxHooks, mergeBashCompressHooks, mergeCcDevHooks, mergeSkillOverrides } = require('./settings-merge');
-const { create: createMetadata, read: readMetadata, readFrozenModules, setFrozenModules } = require('./metadata');
+const { create: createMetadata, read: readMetadata, readFrozenModules, setFrozenModules, readMcpOptOut } = require('./metadata');
 const { setupDb, shouldSkipInit, readBundledSchemaVersion } = require('./db-setup');
 const { setupVerifyRuntime } = require('./verify-setup');
 const { setupSiteAuditRuntime } = require('./site-audit-setup');
@@ -551,6 +551,35 @@ function computeRemovals({ existingManifest, allManifest, selectedModules, templ
   return { toRemove, kept };
 }
 
+// Merge CC-shipped MCP server entries into a consumer's .mcp.json mcpServers
+// object, honoring the .ccrc.json `mcpOptOut` list (act:b770c323). Pure and
+// mutating-in-place on `existing` (the caller serializes the parent object):
+//   - incoming keys NOT opted out are set/overwritten (the prior Object.assign
+//     behavior) and reported in `added`;
+//   - incoming keys the consumer opted out are never added (`skipped`);
+//   - an opted-out key already present in `existing` is DELETED (`removed`) —
+//     self-heal toward the declared intent, but ONLY for keys CC itself ships
+//     (in `incoming`), so a consumer's hand-added servers are never touched.
+function mergeMcpServers(existing, incoming = {}, optOut = []) {
+  const optedOut = new Set(optOut);
+  const added = [];
+  const removed = [];
+  const skipped = [];
+  for (const [key, value] of Object.entries(incoming)) {
+    if (optedOut.has(key)) {
+      skipped.push(key);
+      if (Object.prototype.hasOwnProperty.call(existing, key)) {
+        delete existing[key];
+        removed.push(key);
+      }
+      continue;
+    }
+    existing[key] = value;
+    added.push(key);
+  }
+  return { added, removed, skipped };
+}
+
 // Signals that a directory contains a real project (not just empty)
 const PROJECT_SIGNALS = [
   'package.json', 'Cargo.toml', 'requirements.txt', 'pyproject.toml',
@@ -690,6 +719,42 @@ function printHelp() {
 `);
 }
 
+// --- advisories-state gitignore seeding (act:c008862c) ---
+// .claude/cabinet/advisories-state.json is machine-written runtime state
+// (the advisory pass rewrites it), so tracked it churns every commit and
+// reads as authored work in mux worktrees. FRESH installs (no prior
+// .ccrc.json) seed a .gitignore entry so it never enters git; existing
+// installs are left untouched — untracking a live consumer repo is
+// operator-gated — but a TRACKED copy is reported so the consumer walk
+// surfaces it. Pure and injectable for tests.
+const ADVISORIES_STATE_PATH = '.claude/cabinet/advisories-state.json';
+function seedAdvisoriesGitignore(projectDir, { fresh, dryRun, exec } = {}) {
+  const run = exec || ((cmd) => require('child_process').execSync(cmd, { cwd: projectDir, stdio: 'pipe' }));
+  try {
+    run(`git ls-files --error-unmatch ${ADVISORIES_STATE_PATH}`);
+    return { status: 'tracked-reported' };
+  } catch { /* not tracked — fall through */ }
+  if (!fresh) return { status: 'skipped-existing-install' };
+  try {
+    run('git rev-parse --git-dir');
+  } catch {
+    return { status: 'skipped-no-git' };
+  }
+  try {
+    // Already ignored by ANY rule (exact line or a covering glob like this
+    // repo's `.claude/cabinet/*`) — nothing to add.
+    run(`git check-ignore -q ${ADVISORIES_STATE_PATH}`);
+    return { status: 'already-present' };
+  } catch { /* not ignored — seed below */ }
+  const giPath = path.join(projectDir, '.gitignore');
+  let content = '';
+  try { content = fs.readFileSync(giPath, 'utf8'); } catch { /* no .gitignore yet */ }
+  if (dryRun) return { status: 'would-seed' };
+  const nl = content && !content.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(giPath, `${nl}# machine-written advisory-dismissal state (CC)\n${ADVISORIES_STATE_PATH}\n`);
+  return { status: 'seeded' };
+}
+
 async function run() {
   const flags = parseArgs(process.argv);
 
@@ -1406,9 +1471,22 @@ async function run() {
           existing = {};
         }
         if (!existing.mcpServers) existing.mcpServers = {};
-        Object.assign(existing.mcpServers, mcpConfig.mcpServers);
-        fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + '\n');
-        console.log(`  🔌 Merged pib-db MCP server into .mcp.json`);
+        const optOut = readMcpOptOut(projectDir);
+        const { added, removed, skipped } = mergeMcpServers(existing.mcpServers, mcpConfig.mcpServers, optOut);
+        // Only write when this merge actually contributed or healed something —
+        // an all-opted-out install must not reformat a consumer's .mcp.json.
+        if (added.length > 0 || removed.length > 0) {
+          fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + '\n');
+        }
+        if (added.length > 0) {
+          console.log(`  🔌 Merged ${added.join(', ')} MCP server into .mcp.json`);
+        }
+        if (skipped.length > 0) {
+          console.log(`  ⏭  MCP registration declined by .ccrc.json mcpOptOut: ${skipped.join(', ')}`);
+        }
+        if (removed.length > 0) {
+          console.log(`  🧹 Removed opted-out MCP entr${removed.length === 1 ? 'y' : 'ies'} from .mcp.json: ${removed.join(', ')}`);
+        }
       }
     } catch (err) {
       console.log(`  ⚠ MCP config merge failed: ${err.message}`);
@@ -1632,6 +1710,23 @@ async function run() {
     }
   }
 
+  // --- Seed advisories-state gitignore (fresh installs only; act:c008862c) ---
+  try {
+    const seedResult = seedAdvisoriesGitignore(projectDir, {
+      fresh: dirState !== 'existing-install',
+      dryRun: !!flags.dryRun,
+    });
+    if (seedResult.status === 'seeded') {
+      console.log('  🙈 Gitignored .claude/cabinet/advisories-state.json (machine-written state)');
+    } else if (seedResult.status === 'would-seed') {
+      console.log('  [dry run] Would gitignore .claude/cabinet/advisories-state.json');
+    } else if (seedResult.status === 'tracked-reported') {
+      console.log('  ℹ .claude/cabinet/advisories-state.json is TRACKED in this repo — left untouched. Untracking (git rm --cached) is an operator call; tracked, it churns every commit.');
+    }
+  } catch (err) {
+    console.log(`  ⚠ advisories-state gitignore seeding skipped: ${err.message}`);
+  }
+
   // --- Write metadata ---
   if (!flags.dryRun) {
     createMetadata(projectDir, {
@@ -1725,4 +1820,4 @@ async function run() {
   console.log('');
 }
 
-module.exports = { run, MODULES, generateAgentWrappers, generateSkillIndex, expandFrozenClosure, computeRemovals, manifestPath };
+module.exports = { run, MODULES, generateAgentWrappers, generateSkillIndex, expandFrozenClosure, computeRemovals, mergeMcpServers, manifestPath, seedAdvisoriesGitignore };

package/lib/metadata.js

@@ -111,6 +111,25 @@ function setFrozenModules(projectDir, mods) {
   return normalized;
 }
 
+/**
+ * Read the project's MCP opt-out list from `.ccrc.json` (`mcpOptOut`) — the
+ * CC-shipped MCP server keys this consumer declines (act:b770c323; the live
+ * specimen is flow's no-pib-db.md: engagement→work-tracking closure ships the
+ * pib-db files, but the consumer's own validator requires the MCP registration
+ * absent). Honored by the `.mcp.json` merge in lib/cli.js: opted-out keys are
+ * never added and, when present from a prior install, are removed (self-heal
+ * toward the declared intent). Same defensive shape as `readFrozenModules`:
+ * non-array reads as "no opt-outs"; a malformed `.ccrc.json` still throws in
+ * `read()` and halts the install. The key survives reinstalls via `create()`'s
+ * `...existing` spread — no threading required.
+ */
+function readMcpOptOut(projectDir) {
+  const m = read(projectDir);
+  const raw = m && m.mcpOptOut;
+  if (!Array.isArray(raw)) return [];
+  return [...new Set(raw.filter((x) => typeof x === 'string'))];
+}
+
 module.exports = {
   read,
   write,
@@ -120,4 +139,5 @@ module.exports = {
   METADATA_FILE,
   readFrozenModules,
   setFrozenModules,
+  readMcpOptOut,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/CLAUDE.md

@@ -15,15 +15,58 @@ consumes the registry stays in cli.js).
 ## mux config (`templates/mux/config/`)
 
 - `worktree-session-health.sh` — self-healing worktree health check (4
-  checks, auto-fix, cache + tmux indicator).
+  checks, auto-fix, cache + tmux indicator); the single home for the
+  worktree LANE LIFECYCLE (act:dc80380c): PROVISION (a per-project
+  `.mux-worktree-provision` file declares gitignored env files copied
+  main → worktree at creation and freshness-checked on later health
+  runs — a locally-modified worktree copy is never overwritten; reports
+  name paths/hashes/mtimes only, never file CONTENTS), `--preflight`
+  (pre-spawn source check: every declared provision file exists in MAIN
+  and every declared time-boxed `check:` command passes; exit 1 gates
+  parallel lane spawns — surfaced as `mux worktree preflight`), and
+  `--reap` (removal-time docker container reap: exact
+  compose-project-label match on the worktree dir name, containers only
+  NEVER volumes, always exits 0 — a failed reap is loud but never blocks
+  removal; every removal path delegates here). Also owns the worktree
+  MERGE-OR-LOSE noise immunity (act:c008862c): `rebuild_worktree_excludes`
+  makes per-worktree excludes LIVE via `extensions.worktreeConfig` + a
+  worktree-scoped `core.excludesFile` (git never consults a linked
+  worktree's `worktrees/<name>/info/exclude` — the old rules were
+  silently dead), copying the user's own excludesFile patterns in FIRST
+  so the authored-record negations win, then hiding untracked identity
+  symlinks (root-anchored; only while actually a symlink into main) and
+  machine-written generated state (names kept in step with
+  `GENERATED_STATE_PATTERNS` in watchtower-lib and `GENERATED_STATE_RE`
+  in worktree-dirty-check.sh — the merge tail diffs the lists);
+  `hide_identity_symlink_typechange` sets git's skip-worktree bit on
+  TRACKED `.mcp.json`/`.claudeignore` mux symlinks (typechange churn is
+  exclude-immune) — granted only while the symlink resolves into main,
+  cleared whenever a real file returns.
 - `worktree-health-popup.sh` — tmux popup for health details (triggered by
   double-clicking a `·wt` tab).
 - `worktree-dirty-check.sh` — single shared worktree dirty-detection
   (fail-DIRTY on any error, `--untracked-files=all`; the authored-record
   set is derived from the worktree's index — any top-level `.claude/`
   entry holding tracked files — with the static plans/methodology pair as
-  fallback floor); delegated to by both `bin/mux` and the pane-exited
-  `worktree-cleanup.sh`; sandboxed fixture suite in `templates/mux/__tests__/`,
+  fallback floor). act:c008862c taught it the noise/work boundary:
+  untracked identity symlinks (`?? .mcp.json`/`.claudeignore`/`pib.db`)
+  are churn ONLY while the path is a live symlink — a real file there is
+  real work — and a skip-worktree'd path that no longer holds a symlink
+  counts DIRTY (a real edit may hide behind the bit; a clean-verdict
+  deletion must never race the health heal); untracked generated state
+  (`GENERATED_STATE_RE`: advisories-state.json, checklist-stats.json,
+  `.claude/verification/`, `e2e/.verify-progress.jsonl` — the shell twin
+  of watchtower-lib's `GENERATED_STATE_PATTERNS`, list-diffed at the
+  program merge tail) is subtracted from BOTH counting passes, so a
+  fully-merged worktree no longer reads "MERGE OR LOSE" over runtime
+  residue while a tracked-and-modified copy still counts dirty.
+  Delegated to by both `bin/mux` and the pane-exited
+  `worktree-cleanup.sh` — whose dirty-close inbox filing mirrors ring1's
+  earned-urgency register split (`urgent` only with unmerged commits,
+  `normal` for uncommitted-only, `evidence.unmerged` carried) and whose
+  clean-close removal reaps lane containers via `--reap`, routing an
+  incomplete reap to the desk's sticky notes, never silence;
+  sandboxed fixture suite in `templates/mux/__tests__/`,
   which also holds the `mux-fail-loud` suite (bin/mux fail-loud worktree
   creation + resume reuse, run against a private tmux server), the
   `claude-carveout` suite (tracked `.claude/` = authored: never frozen with
@@ -161,7 +204,22 @@ consumes the registry stays in cli.js).
 - `watchtower-contracts.md` — shared contracts for all watchtower components
   (atomic writes, no-index, session-ID join, schema versioning, project-state
   section ownership — Ring 3 owns `## Last Session` once authored — and
-  deferred schemas).
+  deferred schemas). Also home of "Detector Symmetry" (act:4d11fd53,
+  grp:wt-noise-immunity): every ring-filed inbox category declares its
+  mechanical retraction condition + filing exclusions, or an explicit
+  exemption — encoded in `INBOX_DETECTOR_REGISTRY` (watchtower-lib) and
+  enforced by a structural filing-site test; machine retractions resolve
+  through `autoReconcileItem` (`resolution_type: 'auto-reconciled'` +
+  `evidence.actor`, excluded from engagement buckets); reconcilers fail
+  toward KEEPING (retract only on positive evidence — fid-not-found
+  keeps); the long-lived branch exclusion list
+  (`defaults.long_lived_branches`, staging/production exact-match +
+  `backup/*` glob, consumer-overridable) gates FILING only, never the
+  attention surfaces; and the standing-debt aggregation contract
+  (act:e888dd63) — a standing condition files ONE item per (project,
+  debt-class), APPENDS evidence with `first_seen` = oldest and a
+  session-count urgency escalation, and post-resolution recurrence files
+  FRESH, never a refile loop.
 
 ## Workflows (`templates/workflows/`)
 
@@ -249,7 +307,39 @@ consumes the registry stays in cli.js).
   `checkMemoryIntegrity` delegates to it (the old filename-substring scan
   predated both mechanisms and flagged 203 false orphans while the validator
   passed green). Tests in `__tests__/bsql-loader-verify.test.mjs` +
-  `__tests__/memory-reachability.test.mjs`.
+  `__tests__/memory-reachability.test.mjs`. Lane A of
+  grp:wt-noise-immunity added the reconciliation substrate:
+  `autoReconcileItem` — the ONE resolution path for machine (ring)
+  retractions: resolves through the real queue with `resolution_type:
+  'auto-reconciled'`, then stamps `evidence.actor` + caller evidence
+  naming WHY (action fid / branch); returns null when the item is no
+  longer pending (a human got there first); a failed evidence stamp is
+  logged and tolerated — the typed resolution already landed atomically.
+  `INBOX_DETECTOR_REGISTRY` — the detector-symmetry ledger mapping every
+  ring-filed inbox category to `{reconciler}` or `{exempt}` (exactly
+  one), enforced by the structural filing-site test
+  `__tests__/detector-registry.test.mjs`: it scans `category:` literals
+  at createItem sites across ring1 + ring2 + ring3-close (read-only
+  source scan) and fails on an unregistered category or a non-literal
+  category value inside a filing owner (act:4d11fd53).
+  `GENERATED_STATE_PATTERNS`/`generatedStateIsDisposable` — the JS SSOT
+  for machine-written generated state (UNTRACKED `??` lines only:
+  `.claude/verification/`, advisories-state.json, checklist-stats.json,
+  `e2e/.verify-progress.jsonl` — a TRACKED file of the same name is
+  authored by definition), folded into `claudeChurnIsDisposable` for
+  ring1's `countRealUncommitted` and ring3's Phase 2a dirty filter; the
+  mux shell twin (`GENERATED_STATE_RE` in worktree-dirty-check.sh) is
+  list-diffed at the program merge tail (act:c008862c). And
+  `resolveProjectFromTranscriptSlug` — the slug-parsing fallback beside
+  `resolveProjectIdentity` for CLEANED-UP mux worktrees (act:29001b07,
+  filesystem resolution has nothing left to resolve): decodes the
+  transcript dir slug's `--mux-worktrees-` tail through mux's own
+  `~/.config/mux/projects.json` (longest match on a `-` boundary;
+  same-length tie = ambiguous → null), hands the MAIN-checkout path to
+  the canonical resolver, and returns null on EVERY failure — the caller
+  files `project_unresolved: true`, never a cwd guess. The export NAME
+  is a cross-lane contract: ring3-close feature-detects it on its
+  namespace import.
 - `watchtower-ring3-close.mjs` — Ring 3 session-close transcript processing:
   the knowledge-extraction lenses + the dedup that gates whether an
   extraction is filed. The **recall-fix program** (audit act:7d6a4b3b;
@@ -275,7 +365,36 @@ consumes the registry stays in cli.js).
   suppression sites appends a `recordSuppression` ledger line. Tests in
   `__tests__/ring3-dedup`, `ring3-memory-titles`, `ring3-novelty-rescue`,
   `ring3-recent-slice`, `ring3-chunk-merge`, `suppression-ledger`,
-  `ring3-close-lenses`.
+  `ring3-close-lenses`. Lane B of grp:wt-noise-immunity rebuilt the
+  filing quality. Attribution (act:29001b07): BOTH entry points — live
+  session close and manual reprocess — share ONE `resolveSessionProject`
+  call that attributes the session by its TRANSCRIPT SLUG, never the
+  runner's cwd (302 of 510 reprocess-recovered extractions were
+  confidently misattributed to the runner's project before this): cwd is
+  trusted only when it AGREES with the transcript's project-dir slug
+  (`transcriptSlugFromPath`/`normalizeSlugKey`); a distrusted cwd falls
+  to the lib's `resolveProjectFromTranscriptSlug` (feature-detected by
+  name on the namespace import) and then to `project_unresolved: true` —
+  inbox filing proceeds, but no state-file or thread key is minted from
+  a raw slug. Phase 2c's `completionReviewEmitGuard` adds the
+  create-vs-complete filter (act:9eebbac4): an action whose db `created`
+  date falls inside the session's day window (+1 for past-midnight
+  spill) with confidence below `high` is not a completion candidate (an
+  action born this session whose only evidence is its own creation);
+  mechanical (db row, the same prepared statement as the status
+  re-check) and FAIL-OPEN in every gap — no sessionDate, an unparseable
+  sessionDate (windowEnd is a required conjunct), a missing `created`
+  column, or a thrown lookup all emit. coverage-warning is now a
+  STANDING-DEBT aggregation (act:e888dd63): ONE pending item per
+  (project, debt-class — `COVERAGE_DEBT_CLASS`) whose evidence APPENDS
+  per session (session-id union, so a reprocess replay can't inflate
+  counts; per-path counts; `first_seen` = oldest evidence date;
+  `filed_at` bumped so the expiry clock measures the LAST recurrence),
+  urgency escalating with session count (`coverageDebtUrgency`: normal
+  at 5, urgent at 15); resolving closes the accumulated view and a
+  persisting debt refiles FRESH next session. The `## Last Session`
+  block names its authoritative per-session record (`appendRecordPointer`
+  → `<slug>/sessions/<date>-<sessionId>.md`; act:8c076580).
 - `watchtower-queue.mjs` — inbox queue CRUD library (atomic temp+rename,
   no-index convention); also home of the staff-QA recipient gate
   (2026-06-11): every terminal exit on a `qa-handoff` item is structural —
@@ -328,6 +447,25 @@ consumes the registry stays in cli.js).
   drain. Fail-loud exit policy: 2 = malformed invocation, 1 = can't-proceed
   (item left pending), 0 = resolved; never leaks the absolute queue path.
   qa-drain's Step 2 is the consumer; 23 tests in `__tests__/resolve-cli.test.mjs`.
+  Also home of the surfacing-intelligence apparatus (act:00051dca,
+  grp:wt-noise-immunity): `extractCitedActFids` (regex-validated `act:`
+  fids from draft text, first-appearance order, capped at 50 — the
+  matches are the ONLY values that ever reach a pib-db query, bound as
+  parameters); the fold recipe — `foldTokens` (lowercase alnum runs,
+  length ≥3, stopworded) + `unigramJaccard` with
+  `FOLD_SIMILARITY_THRESHOLD = 0.22` and the `FOLD_MIN_TOKENS = 3`
+  short-text floor (calibrated 2026-07-12 against the live pairs a full
+  510-draft human read surfaced), `proposeFolds` annotating BOTH sides
+  of a pair (reciprocity is the self-validating criterion); and
+  `annotateItemEvidence` — the additive evidence-only write path
+  (fresh read from disk, PENDING-only fence, deep-equal skip so
+  idempotent re-sweeps never rewrite). `isHighConfidenceSignoff` DEMOTES
+  on `evidence.freshness.overtaken` or a non-empty
+  `evidence.possible_duplicate_of` — the item drops out of batch
+  sign-off into individual review, never auto-dismissed. Every
+  caller-supplied id → path join routes through `assertLegalItemId`
+  (`itemPath` id-shape guard — persisted annotation id arrays flow back
+  in as lookups).
 - `watchtower-routines.mjs` — routine dispatch engine (act:c2a55c08):
   projects declare interactive routines in watchtower config (`{name,
   trigger, script}`; triggers: time-of-day, interval, path-nonempty,
@@ -416,7 +554,9 @@ consumes the registry stays in cli.js).
   configured project, Ring 1's parsed state-file sections + git-attention
   facts, Ring 3's recent sessions + thread cursor timelines, and the inbox's
   pending counts + RESOLUTION HISTORY (`resolution_mix` — engaged vs
-  discarded vs untyped, the never-before-consulted signal). The script
+  discarded vs machine vs untyped; `machine` = `MACHINE_TYPES`
+  auto-reconciled ring retractions, excluded from `ENGAGED_TYPES` so cron
+  activity never reads as operator engagement). The script
   GATHERS; the consumer synthesizes — no convergence scoring
   (pattern-intelligence-first). Read-only projection (no write path; hermetic
   fs-snapshot test), a sibling of `watchtower-narrative-corpus.mjs`, touches
@@ -475,7 +615,25 @@ consumes the registry stays in cli.js).
   drill-down) / `--window <N>` — answer-first, verbs + counts, NEVER
   decimals. Consumers: /inbox Step 2a (answer-first verdict before the
   walk/bulk/summary choice, healthy projects suppressed) and /briefing Step
-  3b (the "backlog rot" weighable candidate). 12 hermetic tests in
+  3b (the "backlog rot" weighable candidate). act:ab4927eb
+  (grp:wt-noise-immunity) sharpened the verdict:
+  `deriveAssessmentDetail` returns `{state, state_reason}` and two
+  ABSOLUTE not-consumed arms override a healthy keep ratio — a pile ≥50
+  pending (`deep-pile`) or an oldest tail ≥21d on a pile ≥10
+  (`old-tail`) can never read `keeping` (the 2026-07-12 morning
+  regression: 884 pending / 29d oldest reported all-keeping); rendered
+  wordings are state_reason-honest. `worked_recent` and the keep-ratio
+  event window EXCLUDE machine acts (`bucketResolution` 'machine' /
+  `MACHINE_TYPES`, re-exported from the cross-ring reader; surfaced as a
+  `machine_resolutions` count) so cron retractions can't suppress the
+  not-consumed verdict. Backlog rot handles AGGREGATED standing-debt
+  items: age = `evidence.first_seen` (falls back to filed_at) and weight
+  = the accumulated session count (`evidence.session_ids` — the live
+  producer spelling — /`session_count`/`sessions`), so one 49-session
+  debt can trip `MIN_PILE_FOR_ROT` alone; raw item counts ride beside
+  the weighted ones. `assessRingsAlive` also reads Ring 2's
+  `draft-annotations-health.json` sidecar (its named reader) —
+  informational only, never flips `all_ok`. 12 hermetic tests in
   `__tests__/inbox-assessment.test.mjs`.
 - `watchtower-migrate-keys.mjs` — one-time migration re-keying inbox items,
   thread memberships, and state dirs filed under pre-resolver
@@ -723,13 +881,48 @@ retained for the human-readable line only. Compares against `origin/<main>`
 structured `state/git-attention.json` sidecar that
 `watchtower-build-context.mjs` re-verifies against live git before relaying
 any banner — so a stale "MERGE OR LOSE" line can't survive a merge that
-already happened; act:6f36cbe2, act:a136b362), Ring 2 (Claude intelligence,
+already happened; act:6f36cbe2, act:a136b362. Since grp:wt-noise-immunity
+Ring 1's tick also RETRACTS what the rings filed — every machine
+retraction routes through `autoReconcileItem` (watchtower-lib;
+`'auto-reconciled'` + `evidence.actor`, excluded from engagement buckets
+portfolio-wide): `autoResolveBranchDivergedItems` retracts
+branch-diverged items whose branch merged, is verifiably gone
+(membership in a successful branch listing — a failed git call retracts
+nothing), or sits on `defaults.long_lived_branches` (staging/production
+exact + `backup/*` glob) — an exclusion that gates FILING ONLY, so an
+excluded branch stays visible on all four attention surfaces (attention
+line, git-attention sidecar, summary, Standing Issues; act:98649971);
+`autoReconcileCompletionReviews` resolves completion-review items whose
+action fid is verifiably CLOSED in its own project's pib-db (opened
+read-only; fid-not-found KEEPS the item — act:9eebbac4);
+worktree-unmerged filing splits an earned-urgency register
+(act:c008862c): `urgent` only with real unmerged commits, `normal` for
+uncommitted-files-only (`evidence.unmerged`), with REGISTER-AWARE dedup
+— a register change supersedes + refiles under the current register, and
+escalation is damped (a soft→urgent flip needs corroborating commits
+ahead, since `hasUnmergedContent` fails toward true on git blips);
+`countRealUncommitted` excludes generated runtime state via the
+watchtower-lib SSOT. CP3 hardening: untracked filenames pass as execFile
+args (never shell-interpolated), every branch-name path gates on
+`isSafeRefName`, and the detector census fails loudly on a non-literal
+`category:` inside a filing owner), Ring 2 (Claude intelligence,
 fast 5-min + slow 30-min tiers; the slow tier also runs `recallCanary`
 (act:6354a9db) — reads + prunes `state/suppression-ledger.jsonl`, writes
 `state/recall-canary.json`, an over-suppression-only trend detector gated on
 `defaults.recall_canary`; `buildRecallCanary`/`readLedgerRecords`/`withinDays`
-exported), Ring 3 (session close, transcript processing; fires session-close
-routines as Phase 2j2; runs the standing session advisors as Phase 2m — see
+exported — and `runDraftAnnotationSweep` (act:00051dca; gated on
+`defaults.draft_annotations`, default ON): annotates pending
+knowledge-extraction drafts with freshness (cited `act:` fids positively
+CLOSED in the item's own project pib-db — parameter-bound lookups via
+`openPibDb`, now `timeout: 5000` for lock parity with Ring 3) and fold
+proposals (the watchtower-queue recipe), demoting them out of batch
+sign-off, never dismissing; unreadable dbs and out-of-config drafts are
+counted LOUDLY (`skipped_projects`/`unscanned_items`) and every run
+writes the positive-confirmation sidecar
+`state/draft-annotations-health.json`, so "no annotations" is
+distinguishable from "never ran"), Ring 3 (session close, transcript
+processing; fires session-close routines as Phase 2j2; runs the standing
+session advisors as Phase 2m — see
 below; runs three session-close extraction lenses (act:4ff2cfb3) — Phase 2n
 raised-but-unhandled (loose ends the session raised but neither did nor filed
 → inbox category `raised-unhandled`), Phase 2o skill-candidate (a manual
@@ -874,7 +1067,14 @@ shared fail-DIRTY `worktree-dirty-check.sh`; carve-out-aware `mux worktree
 refresh` preserves uncommitted edits to ANY tracked `.claude/` file — tracked
 = authored, only gitignored infra is disposable, classification
 single-sourced in `worktree-session-health.sh` and guarded by the
-`claude-carveout` test suite), trail logging, sticky notes, global DX
+`claude-carveout` test suite), worktree lane lifecycle (act:dc80380c:
+per-project `.mux-worktree-provision` env-file provisioning at spawn,
+`mux worktree preflight` pre-spawn source check, docker container reap
+on every removal path — all single-sourced in
+`worktree-session-health.sh`), live per-worktree excludes + skip-worktree
+identity-churn suppression so a fully-merged worktree never reads
+"MERGE OR LOSE" over mux/runtime residue (act:c008862c), trail logging,
+sticky notes, global DX
 captures, portal color-switching, durable tmux bindings (`mux.tmux.conf`
 sourced via `~/.tmux.conf`), clipboard copy with hard-wrap removal
 (`unwrap-copy.py`), screenshot-to-clipboard launchd watcher

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,6 +97,41 @@ 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).
 
+## 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.
+
 ## What this contract does NOT cover
 
 Caller-specific orchestration stays in the caller's own Step 0, never