create-claude-cabinet 0.48.0 → 0.49.0

package/templates/scripts/__tests__/detector-registry.test.mjs

@@ -0,0 +1,152 @@
+// Structural detector-symmetry test (act:4d11fd53, grp:wt-noise-immunity).
+//
+// Scans the THREE ring scripts' source text (read-only — house precedent:
+// suppression-ledger's wiring assertion) for `category: '<literal>'` at
+// createItem FILING sites, and asserts the set of filed categories exactly
+// matches INBOX_DETECTOR_REGISTRY (watchtower-lib) — every filed category
+// declares a reconciler or an explicit exemption, and no registry entry
+// goes stale. A new detector shipped without a declared retraction path
+// fails the suite, not the operator's trust: the 2026-07-12 drain found
+// the same missing-retraction disease in four detectors.
+//
+// `category:` also appears at READ sites (listPending/listItems filters);
+// each occurrence is classified by its NEAREST preceding call opener so
+// query filters are never conflated with filing sites (CP1 finding). A
+// count floor guards the parser against vacuous passes.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const lib = await import('../watchtower-lib.mjs');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const scriptsDir = resolve(here, '..');
+const RING_SCRIPTS = [
+  'watchtower-ring1.mjs',
+  'watchtower-ring2.mjs',
+  'watchtower-ring3-close.mjs',
+];
+
+// Call openers that can own a `category:` property, matched as
+// `name({` (word-boundary + object-literal) so prose like "briefing
+// file(s)" or longer identifiers (fileRosterFinding) never classify.
+// Filing owners: createItem and the rings' injectable `file` seam
+// (`const file = deps.file || createItem` — ring2:1727, ring3:2380);
+// everything else is a read filter.
+const OWNER_RE = /\b(createItem|listPending|listItems|listPendingItems|file)\s*\(\s*\{/g;
+const FILING_OWNERS = new Set(['createItem', 'file']);
+
+function classifySites(source, fileName) {
+  const owners = [];
+  let om;
+  while ((om = OWNER_RE.exec(source)) !== null) {
+    owners.push({ name: om[1], index: om.index });
+  }
+  const filing = new Map(); // category → count
+  const reads = new Map();
+  const unparseable = [];
+  // Every `category:` occurrence is examined, not only pre-quoted matches:
+  // a filing site written with a template literal, a variable, or any shape
+  // the census can't extract would otherwise EVADE the registry gate — the
+  // precise hole the contract claims closed (CP3). Both quote styles parse;
+  // anything else inside a filing owner fails the suite loudly.
+  const occ = /category\s*:/g;
+  let m;
+  while ((m = occ.exec(source)) !== null) {
+    let owner = null;
+    for (const o of owners) {
+      if (o.index < m.index) owner = o;
+      else break;
+    }
+    const isFiling = !!owner && FILING_OWNERS.has(owner.name);
+    const lit = source.slice(m.index, m.index + 200)
+      .match(/^category\s*:\s*(['"])([^'"\n]+)\1/);
+    if (!lit) {
+      if (isFiling) {
+        const line = source.slice(0, m.index).split('\n').length;
+        unparseable.push(`${fileName}:${line} (${owner.name})`);
+      }
+      continue; // dynamic categories at read sites are not our concern
+    }
+    const bucket = isFiling ? filing : reads;
+    bucket.set(lit[2], (bucket.get(lit[2]) || 0) + 1);
+  }
+  return { filing, reads, unparseable };
+}
+
+const allFiling = new Map();
+const allReads = new Map();
+const allUnparseable = [];
+let totalFilingSites = 0;
+for (const name of RING_SCRIPTS) {
+  const { filing, reads, unparseable } = classifySites(readFileSync(join(scriptsDir, name), 'utf8'), name);
+  for (const [cat, n] of filing) {
+    allFiling.set(cat, (allFiling.get(cat) || 0) + n);
+    totalFilingSites += n;
+  }
+  for (const [cat, n] of reads) allReads.set(cat, (allReads.get(cat) || 0) + n);
+  allUnparseable.push(...unparseable);
+}
+
+test('every filing-site category is a statically parseable string literal', () => {
+  // A category the census cannot read is a detector the registry cannot
+  // gate — refuse the shape rather than let it ship unregistered.
+  assert.deepEqual(allUnparseable, [],
+    `filing sites with non-literal category values (use a plain quoted string): ${allUnparseable.join(', ')}`);
+});
+
+test('parser sanity: a real filing-site census, not a vacuous pass', () => {
+  // 2026-07-13 census: 2 ring1 + 8 ring2 + 9 ring3 filing sites across 16
+  // distinct categories. Floors, not exact counts — categories may be added
+  // (with registry entries) without touching this test.
+  assert.ok(totalFilingSites >= 15,
+    `expected ≥15 createItem filing sites across the rings, parsed ${totalFilingSites}`);
+  assert.ok(allFiling.size >= 16,
+    `expected ≥16 distinct filed categories, parsed ${allFiling.size}`);
+  // Read filters exist and were NOT counted as filings (the conflation guard):
+  assert.ok(allReads.size >= 3,
+    `expected the known listPending/listItems category filters to classify as reads, parsed ${allReads.size}`);
+});
+
+test('every ring-filed category is registered with a reconciler or an explicit exemption', () => {
+  const unregistered = [...allFiling.keys()]
+    .filter(cat => !(cat in lib.INBOX_DETECTOR_REGISTRY));
+  assert.deepEqual(unregistered, [],
+    `unregistered inbox categories: ${unregistered.join(', ')} — a detector must not ship `
+    + 'without a declared retraction path or exemption (add it to INBOX_DETECTOR_REGISTRY '
+    + 'in watchtower-lib.mjs per the Detector Symmetry contract)');
+});
+
+test('no registry entry is stale — every registered category is actually filed by a ring', () => {
+  const stale = Object.keys(lib.INBOX_DETECTOR_REGISTRY)
+    .filter(cat => !allFiling.has(cat));
+  assert.deepEqual(stale, [],
+    `registry entries with no live filing site: ${stale.join(', ')} — remove or re-anchor them`);
+});
+
+test('every registry entry declares exactly one of reconciler | exempt, non-empty', () => {
+  for (const [cat, entry] of Object.entries(lib.INBOX_DETECTOR_REGISTRY)) {
+    const hasReconciler = typeof entry.reconciler === 'string' && entry.reconciler.trim().length > 0;
+    const hasExempt = typeof entry.exempt === 'string' && entry.exempt.trim().length > 0;
+    assert.ok(hasReconciler !== hasExempt,
+      `${cat}: must declare exactly one of reconciler|exempt (got reconciler=${hasReconciler}, exempt=${hasExempt})`);
+  }
+});
+
+test('the program\'s reconciled categories are registered as reconcilers, not exemptions', () => {
+  // The four in-flight fixes are the registry's founding entries — they
+  // must never silently degrade to exemptions.
+  for (const cat of ['branch-diverged', 'worktree-unmerged', 'completion-review']) {
+    assert.ok(lib.INBOX_DETECTOR_REGISTRY[cat]?.reconciler,
+      `${cat} must declare its reconciler`);
+  }
+  // coverage-warning's declared semantics are the standing-debt aggregation
+  // (act:e888dd63) — assert the registry entry actually says so.
+  assert.match(lib.INBOX_DETECTOR_REGISTRY['coverage-warning']?.exempt || '',
+    /standing-debt aggregation/i);
+  assert.match(lib.INBOX_DETECTOR_REGISTRY['coverage-warning']?.exempt || '',
+    /first_seen/);
+});

package/templates/scripts/__tests__/draft-surfacing.test.mjs

@@ -0,0 +1,433 @@
+// Draft surfacing intelligence — freshness + fold proposals (act:00051dca,
+// Lane C of grp:wt-noise-immunity).
+//
+// Contract under test:
+//   F1: the fold recipe (unigram Jaccard >= FOLD_SIMILARITY_THRESHOLD over
+//       stopworded alphanumeric-run tokens of title+draft) surfaces EXACTLY
+//       the 2026-07-12 live fold candidates and nothing else.
+//   F2: the Ring 2 sweep annotates every surfaced pair RECIPROCALLY (the
+//       self-validating criterion) and never auto-dismisses anything.
+//   F3: freshness — a pending draft citing an action that is CLOSED in the
+//       item's project pib-db gets evidence.freshness {overtaken, cited} and
+//       is excluded from the high-confidence sign-off batch. The done
+//       predicate covers both close paths (completed=1 and the ungated
+//       status='done'). Tri-state discipline: fid-not-found, open action,
+//       soft-deleted action, and missing/unreadable db all mean UNKNOWN —
+//       no annotation, the draft stays batch-eligible.
+//   F4: annotateItemEvidence write discipline — pending fence checked at
+//       WRITE time (a sweep can never resurrect a resolved item), deep-equal
+//       values skip the write (idempotent re-sweeps), schema_version rides
+//       through (annotated items stay readable), and itemPath rejects
+//       traversal-shaped ids.
+//   F5: the sweep writes its positive-confirmation sidecar — "ran with zero
+//       annotations" is distinguishable from "never ran".
+//
+// FIXTURE PROVENANCE: the five draft texts below are sanitized copies of the
+// live resolved items the 2026-07-12 full inbox read surfaced as real fold
+// candidates — the Boolean#cast trio (dec-5f850429 / dec-b2dc5070 /
+// dec-f3446e84) and the testimonials pair (dec-eb6dcdb4 / dec-dd944a5b).
+// Sanitization is a 1:1 token rename (the client name → "Acme"), which
+// preserves unigram-Jaccard values EXACTLY, verified against the live items
+// at authoring time: 5f8↔b2d 0.246, 5f8↔f34 0.311, b2d↔f34 0.218 (below
+// threshold — the trio connects through its hub), eb6↔dd9 0.600, all
+// cross-topic pairs ≤ 0.02. Verbatim drafts are deliberately NOT committed:
+// templates/scripts/__tests__/ ships in the public npm tarball.
+//
+// Hermetic: WATCHTOWER_DIR points at a temp dir set BEFORE the dynamic
+// imports (the queue lib reads it into a module const at load).
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, statSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const root = mkdtempSync(join(tmpdir(), 'draft-surfacing-'));
+process.env.WATCHTOWER_DIR = root;
+mkdirSync(join(root, 'queue', 'items'), { recursive: true });
+writeFileSync(join(root, 'config.json'), '{}\n');
+
+const q = await import('../watchtower-queue.mjs');
+const r2 = await import('../watchtower-ring2.mjs');
+
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+// --- Sanitized fixture drafts (see FIXTURE PROVENANCE above) -----------------
+
+const TRIO_A = {
+  ref: 'dec-5f850429',
+  title: "lesson: ActiveModel::Type::Boolean#cast is fail-open — use explicit allowlist for consent/legal/safety params",
+  draft: "# ActiveModel::Type::Boolean#cast is fail-open — use explicit allowlist for consent/legal/safety params\n\n"
+    + "ActiveModel::Type::Boolean#cast is fail-open: any string not in its explicit false-list (nil, '0', 'false', etc.) "
+    + "casts to true. This means esign_consent='yes-ish' or any junk string would mint a true consent value on a legal "
+    + "record. For consent, legal, or safety gates, use an explicit allowlist check (e.g., [true, 'true'].include?(value)) "
+    + "rather than relying on Boolean#cast. Caught live during CP3 sweep of Lane 1b before a consent-less-in-spirit "
+    + "signature could have been minted.",
+};
+const TRIO_B = {
+  ref: 'dec-b2dc5070',
+  title: "lesson: Rails Boolean#cast treats 'yes-ish' as true — consent gates need a strict allowlist",
+  draft: "# Rails Boolean#cast treats 'yes-ish' as true — consent gates need a strict allowlist\n\n"
+    + "Rails' Boolean#cast is too permissive for security-sensitive consent gates: it treats strings like 'yes-ish' as "
+    + "true. The e-sign consent gate was hardened to a strict [true, 'true'] allowlist after CP3 caught this fail-open. "
+    + "Any model attribute used as a security gate (not just display) should use a strict allowlist rather than relying "
+    + "on AR's cast.",
+};
+const TRIO_C = {
+  ref: 'dec-f3446e84',
+  title: "lesson: Boolean param cast: use strict allowlist not ActiveModel::Type::Boolean for legal-effect consent fields",
+  draft: "# Boolean param cast: use strict allowlist not ActiveModel::Type::Boolean for legal-effect consent fields\n\n"
+    + "For any param that gates a legal-effect action (e-sign consent, marketing consent), use a strict allowlist "
+    + "(true/false only) rather than ActiveModel::Type::Boolean#cast. The fail-open cast accepts truthy junk values "
+    + "('1', 'yes', 'true', etc.) and can mint a consent record from a malformed or replayed param. The allowlist "
+    + "pattern: `params[:field] == true || params[:field] === false` (or equivalent). Track any remaining fail-open "
+    + "cast sites as a follow-up action.",
+};
+const PAIR_A = {
+  ref: 'dec-eb6dcdb4',
+  title: 'lesson: Acme: Testimonial model is not MCP-editable — admin UI only',
+  draft: "# Acme: Testimonial model is not MCP-editable — admin UI only\n\n"
+    + "The Testimonial model was lifted from campaign landing-content into its own model and is only accessible via the "
+    + "admin UI (Testimonials page). There is no MCP tool or API endpoint for it. Do not tell the client they can edit "
+    + "testimonials via Claude — only via the admin panel. If Claude-editable testimonials are wanted, a small MCP-tool "
+    + "addition is needed first.",
+};
+const PAIR_B = {
+  ref: 'dec-dd944a5b',
+  title: 'lesson: testimonials are NOT editable via Claude MCP — admin UI only',
+  draft: "# testimonials are NOT editable via Claude MCP — admin UI only\n\n"
+    + "The Testimonial model has no MCP tool and no API endpoint — it was lifted out of campaign landing-content into "
+    + "its own model that only the admin UI touches (Testimonials page). Do not tell clients they can edit testimonials "
+    + "via Claude; say 'editable in the admin UI (Testimonials page).'",
+};
+const FIXTURES = [TRIO_A, TRIO_B, TRIO_C, PAIR_A, PAIR_B];
+
+function queueDraft(project, { title, draft }, overrides = {}) {
+  return q.createItem({
+    project,
+    project_path: overrides.project_path || `/tmp/${project}`,
+    category: 'knowledge-extraction',
+    title,
+    summary: title,
+    context_anchor: 'session fixture',
+    draft_artifact: draft,
+    filed_by: 'ring3',
+    ...overrides,
+  });
+}
+
+function readStored(id) {
+  return JSON.parse(readFileSync(join(root, 'queue', 'items', `${id}.json`), 'utf8'));
+}
+
+// --- F1: the fold recipe surfaces exactly the live pairs ---------------------
+
+test('F1: proposeFolds surfaces exactly the 2026-07-12 pairs — trio hub links + testimonials pair', () => {
+  const items = FIXTURES.map((f) => ({ id: f.ref, title: f.title, draft_artifact: f.draft }));
+  const pairs = q.proposeFolds(items);
+  const keys = pairs.map((p) => [p.a, p.b].sort().join('|')).sort();
+  assert.deepEqual(keys, [
+    'dec-5f850429|dec-b2dc5070',
+    'dec-5f850429|dec-f3446e84',
+    'dec-dd944a5b|dec-eb6dcdb4',
+  ]);
+  for (const p of pairs) assert.ok(p.similarity >= q.FOLD_SIMILARITY_THRESHOLD);
+  // Below-threshold direction: the b2d↔f34 wording sits just under the line
+  // (0.218) and cross-topic pairs are noise-level — none of them surface.
+  assert.ok(!keys.includes('dec-b2dc5070|dec-f3446e84'));
+  assert.ok(!keys.some((k) => k.includes('dec-eb6dcdb4') && k.includes('dec-5f850429')));
+});
+
+test('F1b: short-text floor and empty inputs never propose folds (no NaN, no boilerplate match)', () => {
+  assert.equal(q.unigramJaccard(new Set(), new Set()), 0);
+  assert.equal(q.unigramJaccard(new Set(['a']), new Set()), 0);
+  // Two near-empty drafts sharing one token would score 1.0 — the
+  // FOLD_MIN_TOKENS floor keeps them out entirely.
+  const tiny = [
+    { id: 'dec-aaaa0001', title: 'fix', draft_artifact: 'testimonials' },
+    { id: 'dec-aaaa0002', title: 'fix', draft_artifact: 'testimonials' },
+  ];
+  assert.deepEqual(q.proposeFolds(tiny), []);
+  assert.deepEqual(q.proposeFolds(null), []);
+  assert.deepEqual(q.proposeFolds([{ id: 'x', title: null, draft_artifact: null }]), []);
+});
+
+// --- F2: sweep reciprocity + never-dismiss -----------------------------------
+
+test('F2: sweep annotates every surfaced pair reciprocally; nothing is dismissed', () => {
+  const project = 'fold-proj';
+  const ids = {};
+  for (const f of FIXTURES) ids[f.ref] = queueDraft(project, f);
+
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: { [project]: { path: join(root, 'no-such-project') } } },
+    { watchtowerDir: root },
+  );
+
+  // All five ride the fold graph: the trio through its hub, the pair directly.
+  const expectPartners = {
+    [ids[TRIO_A.ref]]: [ids[TRIO_B.ref], ids[TRIO_C.ref]].sort(),
+    [ids[TRIO_B.ref]]: [ids[TRIO_A.ref]],
+    [ids[TRIO_C.ref]]: [ids[TRIO_A.ref]],
+    [ids[PAIR_A.ref]]: [ids[PAIR_B.ref]],
+    [ids[PAIR_B.ref]]: [ids[PAIR_A.ref]],
+  };
+  for (const [id, partners] of Object.entries(expectPartners)) {
+    const stored = readStored(id);
+    assert.equal(stored.status, 'pending', 'annotation never changes status');
+    assert.deepEqual(stored.evidence.possible_duplicate_of, partners, `partners of ${id}`);
+  }
+  // Reciprocity as an invariant: every listed partner lists you back.
+  for (const [id, partners] of Object.entries(expectPartners)) {
+    for (const partner of partners) {
+      assert.ok(readStored(partner).evidence.possible_duplicate_of.includes(id));
+    }
+  }
+  assert.equal(summary.fold_annotated, 5);
+  // No pib-db for this project — freshness skipped LOUDLY, not silently.
+  assert.deepEqual(summary.skipped_projects, [project]);
+  assert.equal(summary.freshness_annotated, 0);
+
+  // Fold-annotated items are excluded from the sign-off batch.
+  const { signoff, individual } = q.partitionForBatchSignoff(
+    q.listPending({ project }));
+  assert.equal(signoff.length, 0);
+  assert.equal(individual.length, 5);
+});
+
+test('F2b: a second sweep over already-annotated items performs zero writes (idempotent)', () => {
+  const project = 'fold-proj'; // same items as F2
+  const files = q.listPending({ project }).map((i) => join(root, 'queue', 'items', `${i.id}.json`));
+  const before = files.map((f) => [f, statSync(f).mtimeMs, readFileSync(f, 'utf8')]);
+
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: { [project]: { path: join(root, 'no-such-project') } } },
+    { watchtowerDir: root },
+  );
+  assert.equal(summary.fold_annotated, 0, 'unchanged annotations are not rewritten');
+  for (const [f, mtime, content] of before) {
+    assert.equal(statSync(f).mtimeMs, mtime, `untouched: ${f}`);
+    assert.equal(readFileSync(f, 'utf8'), content);
+  }
+});
+
+// --- F3: freshness against a fixture pib-db ----------------------------------
+
+function makeProjectDb(dir, { withDeletedAt = true } = {}) {
+  mkdirSync(dir, { recursive: true });
+  const Database = require('better-sqlite3');
+  const db = new Database(join(dir, 'pib.db'));
+  db.exec(`CREATE TABLE actions (
+    fid TEXT PRIMARY KEY, text TEXT, status TEXT DEFAULT 'open',
+    completed INTEGER DEFAULT 0, completed_at TEXT${withDeletedAt ? ', deleted_at TEXT' : ''}
+  )`);
+  return db;
+}
+
+const openFixtureDb = (projectPath) => {
+  const Database = require('better-sqlite3');
+  const p = join(projectPath, 'pib.db');
+  if (!existsSync(p)) return null;
+  return new Database(p, { readonly: true });
+};
+
+test('F3: a draft citing a since-closed action is annotated and leaves the sign-off batch', () => {
+  const project = 'fresh-proj';
+  const projDir = join(root, 'projects', project);
+  const db = makeProjectDb(projDir);
+  db.prepare("INSERT INTO actions (fid, status, completed, completed_at) VALUES ('act:11112222', 'done', 1, '2026-07-10')").run();
+  db.prepare("INSERT INTO actions (fid, status, completed) VALUES ('act:33334444', 'open', 0)").run();
+  db.close();
+
+  const overtaken = queueDraft(project, {
+    title: 'lesson: the cross-ring reader still exits nonzero on an empty portfolio',
+    draft: 'The reader exits 1 when config has no projects — tracked as act:11112222; workaround is a guard in the caller until that action lands.',
+  }, { project_path: projDir });
+  const freshOpen = queueDraft(project, {
+    title: 'lesson: keep the parity test binding when adding join keys',
+    draft: 'Join keys must stay parity-tested against the resolver — see act:33334444 for the open follow-up work.',
+  }, { project_path: projDir });
+  const noCitations = queueDraft(project, {
+    title: 'lesson: plain drafts with no citations ride the batch untouched',
+    draft: 'A lesson body citing no work items at all.',
+  }, { project_path: projDir });
+  const unknownFid = queueDraft(project, {
+    title: 'lesson: a citation the db has never heard of stays unknown',
+    draft: 'References act:99990000 which exists in no actions table anywhere.',
+  }, { project_path: projDir });
+
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: { [project]: { path: projDir } } },
+    { watchtowerDir: root, openDb: openFixtureDb },
+  );
+  assert.equal(summary.freshness_annotated, 1);
+  assert.deepEqual(summary.skipped_projects, []);
+
+  const stored = readStored(overtaken);
+  assert.equal(stored.status, 'pending', 'never auto-dismissed');
+  assert.deepEqual(stored.evidence.freshness, {
+    overtaken: true,
+    cited: [{ fid: 'act:11112222', closed_at: '2026-07-10' }],
+  });
+  // Tri-state: open action, no citations, unknown fid ⇒ NO annotation.
+  for (const id of [freshOpen, noCitations, unknownFid]) {
+    assert.equal(readStored(id).evidence.freshness, undefined, `no annotation on ${id}`);
+  }
+
+  const { signoff, individual } = q.partitionForBatchSignoff(q.listPending({ project }));
+  assert.ok(individual.some((i) => i.id === overtaken), 'overtaken draft demoted to individual');
+  assert.deepEqual(signoff.map((i) => i.id).sort(), [freshOpen, noCitations, unknownFid].sort(),
+    'unannotated drafts stay batch-eligible');
+});
+
+test('F3b: the ungated close path (status=done, completed=0) still reads as closed', () => {
+  const project = 'ungated-proj';
+  const projDir = join(root, 'projects', project);
+  const db = makeProjectDb(projDir);
+  db.prepare("INSERT INTO actions (fid, status, completed) VALUES ('act:55556666', 'done', 0)").run();
+  db.close();
+  const id = queueDraft(project, {
+    title: 'lesson: cites work closed through the ungated status flip',
+    draft: 'That behavior changed under act:55556666 and this draft may be overtaken by it.',
+  }, { project_path: projDir });
+  r2.runDraftAnnotationSweep(
+    { projects: { [project]: { path: projDir } } },
+    { watchtowerDir: root, openDb: openFixtureDb },
+  );
+  const fresh = readStored(id).evidence.freshness;
+  assert.equal(fresh.overtaken, true);
+  assert.deepEqual(fresh.cited, [{ fid: 'act:55556666', closed_at: null }]);
+});
+
+test('F3c: a soft-deleted action is unknown, not closed; an old schema without deleted_at still works', () => {
+  // deleted_at set ⇒ no annotation.
+  const pA = 'deleted-proj';
+  const dirA = join(root, 'projects', pA);
+  const dbA = makeProjectDb(dirA);
+  dbA.prepare("INSERT INTO actions (fid, status, completed, completed_at, deleted_at) VALUES ('act:77778888', 'done', 1, '2026-07-01', '2026-07-02')").run();
+  dbA.close();
+  const idA = queueDraft(pA, {
+    title: 'lesson: cites a soft-deleted action',
+    draft: 'Cites act:77778888 which was closed and then deleted.',
+  }, { project_path: dirA });
+
+  // Older consumer schema without the deleted_at column ⇒ fallback query runs.
+  const pB = 'oldschema-proj';
+  const dirB = join(root, 'projects', pB);
+  const dbB = makeProjectDb(dirB, { withDeletedAt: false });
+  dbB.prepare("INSERT INTO actions (fid, status, completed, completed_at) VALUES ('act:aaaa1111', 'done', 1, '2026-06-30')").run();
+  dbB.close();
+  const idB = queueDraft(pB, {
+    title: 'lesson: cites closed work in an old-schema db',
+    draft: 'Cites act:aaaa1111 living in a db predating soft deletion.',
+  }, { project_path: dirB });
+
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: { [pA]: { path: dirA }, [pB]: { path: dirB } } },
+    { watchtowerDir: root, openDb: openFixtureDb },
+  );
+  assert.equal(readStored(idA).evidence.freshness, undefined, 'soft-deleted ⇒ unknown');
+  assert.equal(readStored(idB).evidence.freshness.overtaken, true, 'old schema ⇒ fallback query');
+  assert.equal(summary.freshness_annotated, 1);
+});
+
+test('F3d: extractCitedActFids — unique, ordered, capped, shape-validated', () => {
+  assert.deepEqual(q.extractCitedActFids('see act:12345678 and act:12345678 then act:90abcdef'),
+    ['act:12345678', 'act:90abcdef']);
+  // Malformed fids never match: non-hex, too short, and too long (\b after
+  // {8} rejects a 9th hex char) all yield nothing — the regex IS the shape
+  // validation for everything that later reaches a SQL parameter.
+  assert.deepEqual(q.extractCitedActFids('act:XYZ act:1234 act:123456789 react:12345678'), []);
+  assert.deepEqual(q.extractCitedActFids(''), []);
+  assert.deepEqual(q.extractCitedActFids(null), []);
+  const many = Array.from({ length: 80 }, (_, i) => `act:${String(10000000 + i)}`).join(' ');
+  assert.equal(q.extractCitedActFids(many).length, 50, 'capped at 50 per draft');
+});
+
+// --- F4: annotate write discipline -------------------------------------------
+
+test('F4: annotate-after-resolve is a skip — a sweep can never resurrect a resolved item', () => {
+  const project = 'race-proj';
+  const id = queueDraft(project, { title: 'lesson: race fixture', draft: 'body text for the race fixture case' });
+  q.resolveItem(id, { resolution: 'captured', resolution_type: 'captured-to-memory', resolution_notes: 'raced the sweep' });
+  const res = q.annotateItemEvidence(id, { possible_duplicate_of: ['dec-beefcafe'] });
+  assert.equal(res, null);
+  const stored = readStored(id);
+  assert.equal(stored.status, 'resolved', 'resolution stamp intact');
+  assert.equal(stored.resolution_type, 'captured-to-memory');
+  assert.equal(stored.evidence.possible_duplicate_of, undefined);
+});
+
+test('F4b: annotated items survive the round trip — schema_version preserved, still listed', () => {
+  const project = 'roundtrip-proj';
+  const id = queueDraft(project, { title: 'lesson: round trip fixture', draft: 'body text for the round trip case' });
+  const res = q.annotateItemEvidence(id, { freshness: { overtaken: true, cited: [{ fid: 'act:0000ffff', closed_at: null }] } });
+  assert.equal(res.changed, true);
+  const stored = readStored(id);
+  assert.equal(stored.schema_version, 1);
+  const listed = q.listPending({ project });
+  assert.equal(listed.length, 1, 'annotated item still readable through readItem/listPending');
+  assert.equal(listed[0].evidence.freshness.overtaken, true);
+  // Unchanged re-annotation: no write.
+  const again = q.annotateItemEvidence(id, { freshness: { overtaken: true, cited: [{ fid: 'act:0000ffff', closed_at: null }] } });
+  assert.equal(again.changed, false);
+});
+
+test('F4c: itemPath rejects traversal-shaped ids at every entry', () => {
+  for (const evil of ['../escape', 'a/b', 'a\\b', '.hidden', '', null, 42]) {
+    assert.throws(() => q.annotateItemEvidence(evil, {}), /illegal item id/);
+    assert.throws(() => q.getItem(evil), /illegal item id/);
+  }
+});
+
+// --- F4d: sweep error arms ----------------------------------------------------
+
+test('F4d: a throwing listPending is counted and skipped — one bad project never kills the sweep', () => {
+  const good = 'errarm-good';
+  const id = queueDraft(good, { title: 'lesson: healthy sibling project draft', draft: 'a normal draft body for the healthy sibling project' });
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: { 'errarm-bad': { path: '/tmp/x' }, [good]: { path: join(root, 'no-db') } } },
+    {
+      watchtowerDir: root,
+      listPendingFn: (f) => {
+        if (f.project === 'errarm-bad') throw new Error('boom');
+        return q.listPending(f);
+      },
+    },
+  );
+  assert.equal(summary.errors, 1, 'the throw is counted, not swallowed silently');
+  assert.equal(summary.items_scanned, 1, 'the healthy project is still swept');
+  assert.equal(readStored(id).status, 'pending');
+});
+
+test('F4e: drafts filed under a project outside config are counted as unscanned, never invisible', () => {
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: {} },
+    { watchtowerDir: root },
+  );
+  // Every pending draft queued by earlier tests belongs to a project absent
+  // from this empty config — the sweep must SAY so.
+  assert.ok(summary.unscanned_items >= 1, `unscanned_items visible (got ${summary.unscanned_items})`);
+  assert.equal(summary.items_scanned, 0);
+});
+
+// --- F5: positive confirmation sidecar ---------------------------------------
+
+test('F5: every sweep writes the health sidecar — zero-annotation runs are visible', () => {
+  const sidecarPath = join(root, 'state', 'draft-annotations-health.json');
+  const summary = r2.runDraftAnnotationSweep(
+    { projects: { 'empty-proj': { path: join(root, 'nowhere') } } },
+    { watchtowerDir: root, nowIso: () => '2026-07-13T00:00:00.000Z' },
+  );
+  assert.equal(summary.items_scanned, 0);
+  assert.ok(existsSync(sidecarPath));
+  const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'));
+  assert.equal(sidecar.schema_version, 1);
+  assert.equal(sidecar.last_run, '2026-07-13T00:00:00.000Z');
+  assert.equal(sidecar.items_scanned, 0);
+});