create-claude-cabinet 0.48.0 → 0.50.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.50.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 —
@@ -297,28 +416,45 @@ consumes the registry stays in cli.js).
   required, and a structural refusal of GATED_CATEGORIES items (today:
   qa-handoff) — gated items never batch, each exits only through its own
   gate; `routine` is dispatched but NOT gated, so stale routines are legal
-  batch fodder (18-test hermetic suite in `__tests__/batch-disposition.test.mjs`).
+  batch fodder (19-test hermetic suite in `__tests__/batch-disposition.test.mjs`).
   Inbox bulk triage splits sign-off from judgment via `isHighConfidenceSignoff`/
   `partitionForBatchSignoff` — high-confidence pre-drafted extractions
   auto-group into one batch sign-off while judgment items stay per-item
   (act:7f1e4d91). qa-handoff items carry a first-class `evidence.merge_state`
   (act:971570c4): `'merged'` (default — filed after the worktree branch
-  merged) or `'merge-pending'` (filed before the merge, when it's gated on an
-  in-flight deploy). `normalizeMergeState` + `QA_MERGE_STATES` are exported;
-  `createItem` rejects a present-but-illegal token at the boundary (a typo
-  can't read as `'merged'`) and canonicalizes a legal one (additive — absent
-  stays absent, readers default to `'merged'`). A `createItem`
+  merged) or `'merge-pending'` (filed before the merge, ONLY when it's gated
+  on something external). `normalizeMergeState` + `QA_MERGE_STATES` are
+  exported; `createItem` rejects a present-but-illegal token at the boundary
+  (a typo can't read as `'merged'`) and canonicalizes a legal one (additive —
+  absent stays absent, readers default to `'merged'`). A `createItem`
   MERGE-COHERENCE guard (act:e859b3a3) also rejects a `'merged'` handoff
   whose `merged_into`/`merged_commit` free-texts a not-yet-merged marker
-  (`PENDING`/`unmerged`/…) — unmerged work can't be filed as merged at the
-  boundary, the honest state is `'merge-pending'`; pure string check, fenced
-  to qa-handoff, and the drain's Step 0 does the live git-ancestry
-  verification of the sha. The recipient gate is unchanged: a merge-pending
-  handoff still resolves only through a stamped `qa_verdict` cited against
-  the post-merge commit. The skill defers stage-2 dispatch and the pickup
-  prompt says "merge then QA" when merge-pending. 32-test hermetic suite in
-  `templates/scripts/__tests__/qa-handoff-gate.test.mjs` + 12-test
-  `qa-handoff-merge-state.test.mjs`. Also home of the operator RESOLVE CLI
+  (`PENDING`/`unmerged`/…) — pure string check, fenced to qa-handoff. On top
+  of it, the MERGED-BY-CONSTRUCTION guards (act:3d1ac2b7) make the merge
+  claim verified, not asserted — a two-layer defense with the drain's Step 0
+  live re-check: a `'merged'` handoff requires a sha-shaped `merged_commit`
+  (omission was the trivial bypass) which `verifyMergedAncestry` checks
+  against git (queue-local origin/HEAD→main/master ref resolution, no fetch,
+  execFile args, 5s timeout; REJECT only on positive refutation, file with a
+  visible `evidence.ancestry_verified: 'unverifiable'` stamp when git can't
+  answer); a `'merge-pending'` handoff requires a non-empty
+  `evidence.merge_gate` naming the external blocker (rejection messages
+  teach the merge-first close-out, self-correcting older skill text); and
+  the ONE legal merge-pending→merged flip is `markHandoffMerged` — same
+  verification, writes the deferred stage-2 dispatch descriptor directly
+  into the mux queue dir (fs-only, desk token shape-guarded, in-flight
+  aware), records `evidence.stage2_dispatch` so a failed dispatch retries
+  by state — while `annotateItemEvidence` REFUSES `merge_state` patches on
+  qa-handoffs (the side door is closed). The recipient gate is unchanged: a
+  merge-pending handoff resolves only AFTER `markHandoffMerged` records the
+  verified merge, then through a stamped `qa_verdict` cited against the
+  post-merge commit. The skill defers stage-2 dispatch and the pickup
+  prompt says "merge then QA" when merge-pending (`buildQaPickupPrompt` is
+  the library sibling of the skill's merged-path prompt — pared to the gate
+  essentials, not byte-parity). 32-test hermetic suite in
+  `templates/scripts/__tests__/qa-handoff-gate.test.mjs` + 20-test
+  `qa-handoff-merge-state.test.mjs` + 19-test
+  `qa-handoff-merged-by-construction.test.mjs` (real temp git repos). Also home of the operator RESOLVE CLI
   (act:00030e1d): `resolve <id> --verdict-file <path.json>` (`parseResolveArgs`
   + `runResolveCli` + an isMain guard) reads the FULL `resolveItem` params
   object `{resolution, resolution_type, resolution_notes, qa_verdict}` from a
@@ -328,6 +464,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,
@@ -370,8 +525,17 @@ consumes the registry stays in cli.js).
   (git-dir == git-common-dir; worktree windows stay silent) and built from
   the shared `buildPickupPrompt` so the resolve-on-run wording is
   single-sourced; qa-handoff items are excluded by the `category: 'routine'`
-  filter (operator-initiated by design). Exports `renderMissedRoutineSection`/
-  `isMainCheckout` for tests.
+  filter (operator-initiated by design). Also OPENS every injection with a
+  session-start acknowledgment directive (act:058d00f0,
+  `renderSessionAckSection`, `PRIORITY_NEVER`): a short instruction telling
+  the session to begin its first reply with ONE plain-English line
+  confirming the context loaded — positive confirmation the hook chain
+  works (the injection is invisible in the terminal, so a silent session
+  was indistinguishable from a broken hook). Prompt-layer convention only;
+  a frontier-model warning still precedes it, resume re-injections skip it;
+  tests in `__tests__/session-ack.test.mjs`. Exports
+  `renderMissedRoutineSection`/`renderSessionAckSection`/`isMainCheckout`
+  for tests.
 - `watchtower-snapshot.mjs` — mid-session awareness polling (act:a8057f87):
   the sibling primitive behind `/catch-up`. The SessionStart hook captures a
   per-session BASELINE snapshot (keyed by the stdin `.session_id`, written to
@@ -416,7 +580,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 +641,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 +907,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
@@ -805,7 +1024,9 @@ step — then push it to the desk's main window via `mux qa dispatch`; usually
 filed right after the merge — an unmerged named branch now PROMPTS merge-now
 (Claude merges → `merged`) vs keep-gated, never a silent `merge-pending`
 default (act:350e7373); merge-pending is opt-in, filed BEFORE the merge only
-when the merge is gated, in which case stage-2 dispatch defers — see the
+when the merge is gated on a named external blocker (`evidence.merge_gate`,
+required at the boundary; act:3d1ac2b7), in which case stage-2 dispatch
+defers until `markHandoffMerged` records the verified flip — see the
 watchtower-queue `merge_state` entry above; stages 1–2 of the QA-handoff
 protocol, `.claude/plans/qa-handoff-protocol.md`). Stage 3 — the drain — is
 enforced by the staff-QA recipient gate in `watchtower-queue.mjs`: qa-handoff
@@ -874,7 +1095,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
@@ -950,10 +1178,15 @@ MAIN checkout for breadcrumbs/report, so worktree invocations land artifacts
 durably). `checkpoint-protocol.md` documents three CP modes (Interactive,
 Advisory, Full) and is the shared contract between `/execute` and
 `/execute-group`. `/execute` is worktree-aware (act:1067adee): its Step 0
-reads the worktree-invocation contract and syncs main *into* the worktree (it
-never merges OUT — the worktree→main bridge is `/qa-handoff`); breadcrumb
-writes resolve to `$MAIN/.claude/verification/`, closing the lost-on-cleanup
-gap (act:d4767af6); and its Step 8 worktree close-out files a `merge-pending`
-qa-handoff and marks the action done at commit, degrading loudly (never
-silently) when watchtower isn't installed. On the main checkout all of this
-no-ops.
+reads the worktree-invocation contract and syncs main *into* the worktree
+(the merge OUT happens once, at close-out); breadcrumb writes resolve to
+`$MAIN/.claude/verification/`, closing the lost-on-cleanup gap
+(act:d4767af6); and its Step 8 worktree close-out is MERGE-FIRST
+(act:3d1ac2b7): re-sync + re-gate, merge + push via `/qa-handoff`'s
+merge-now recipe (no prompt — merge-now is the default; every failure HALTs
+loudly, the action stays open), then file a `merged` qa-handoff that
+dispatches unconditionally. Done is marked only after merge + filing
+succeed. `merge-pending` is reserved for an explicitly gated merge
+(`evidence.merge_gate` required). Without watchtower the close-out still
+merges, then degrades loudly (never silently) — the no-handoff note names
+what to QA manually. On the main checkout all of this no-ops.