create-claude-cabinet 0.45.0 → 0.46.0

package/templates/scripts/__tests__/feedback-outbox-flush.test.mjs

@@ -0,0 +1,232 @@
+// flushFeedbackOutbox — Ring 1's feedback-delivery duty (act:6c3a4763).
+// The trap this replaces: Ring 3's Phase 2h marked items delivered:true
+// without writing anything anywhere. These guards pin the new contract:
+// an outbox item leaves the outbox ONLY when a feedback file exists for it
+// (freshly written, or already present in feedback/ / feedback/resolved/).
+//
+// Fixtures are self-contained temp dirs; outboxPath/registryPath/destination
+// are injected via opts so no test touches the live ~/.claude.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync,
+  readdirSync, chmodSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const { flushFeedbackOutbox } = await import('../watchtower-lib.mjs');
+
+const root = mkdtempSync(join(tmpdir(), 'fb-flush-'));
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+let caseId = 0;
+function makeCase({ outbox, withCcRepo = true } = {}) {
+  const dir = join(root, `case-${caseId++}`);
+  mkdirSync(dir, { recursive: true });
+  const outboxPath = join(dir, 'cc-feedback-outbox.json');
+  if (outbox !== undefined) {
+    writeFileSync(outboxPath, typeof outbox === 'string' ? outbox : JSON.stringify(outbox, null, 2));
+  }
+  const ccRepo = join(dir, 'cc-repo');
+  const registryPath = join(dir, 'cc-registry.json');
+  if (withCcRepo) {
+    mkdirSync(ccRepo, { recursive: true });
+    writeFileSync(join(ccRepo, 'package.json'), JSON.stringify({ name: 'create-claude-cabinet' }));
+    writeFileSync(registryPath, JSON.stringify({
+      projects: [
+        { path: join(dir, 'not-cc'), name: 'other' },
+        { path: ccRepo, name: 'claude-cabinet' },
+      ],
+    }));
+  } else {
+    writeFileSync(registryPath, JSON.stringify({ projects: [] }));
+  }
+  return { dir, outboxPath, registryPath, ccRepo, feedbackDir: join(ccRepo, 'feedback') };
+}
+
+function item(overrides = {}) {
+  return {
+    source: 'flow', date: '2026-06-12', component: 'orient',
+    title: 'Orient phase X is broken', body: '# Feedback\n\nDetails here.\n',
+    status: 'pending', delivered: false,
+    ...overrides,
+  };
+}
+
+test('missing outbox is a silent no-op', () => {
+  const c = makeCase({});
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.status, 'no-outbox');
+  assert.ok(!existsSync(c.outboxPath));
+});
+
+test('empty outbox is a no-op', () => {
+  const c = makeCase({ outbox: [] });
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.status, 'empty');
+});
+
+test('malformed outbox resets to [] and reports it', () => {
+  const c = makeCase({ outbox: '{not json!' });
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.status, 'malformed-reset');
+  assert.deepEqual(JSON.parse(readFileSync(c.outboxPath, 'utf8')), []);
+});
+
+test('delivers undelivered items as real files and resets outbox to []', () => {
+  const c = makeCase({ outbox: [item(), item({ title: 'Second issue', date: '2026-06-11' })] });
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.status, 'ok');
+  assert.equal(res.delivered, 2);
+  const files = readdirSync(c.feedbackDir).sort();
+  assert.deepEqual(files, [
+    '2026-06-11-second-issue.md',
+    '2026-06-12-orient-phase-x-is-broken.md',
+  ]);
+  assert.equal(readFileSync(join(c.feedbackDir, '2026-06-12-orient-phase-x-is-broken.md'), 'utf8'),
+    '# Feedback\n\nDetails here.\n');
+  assert.deepEqual(JSON.parse(readFileSync(c.outboxPath, 'utf8')), []);
+});
+
+test('resolves the CC repo via registry by package.json name, not entry name', () => {
+  const c = makeCase({ outbox: [item()] });
+  // Registry already contains a non-CC entry first; delivery must land in cc-repo.
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.destination, c.feedbackDir);
+});
+
+test('skip-if-exists: a file in feedback/ containing the slug blocks a rewrite', () => {
+  const c = makeCase({ outbox: [item()] });
+  mkdirSync(c.feedbackDir, { recursive: true });
+  writeFileSync(join(c.feedbackDir, '2026-06-10-orient-phase-x-is-broken-1.md'), 'older delivery');
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.delivered, 0);
+  assert.equal(res.skipped, 1);
+  // Item still leaves the outbox — it IS delivered, just by a prior session.
+  assert.deepEqual(JSON.parse(readFileSync(c.outboxPath, 'utf8')), []);
+  assert.equal(readdirSync(c.feedbackDir).length, 1);
+});
+
+test('skip-if-exists: feedback/resolved/ also counts as already delivered', () => {
+  const c = makeCase({ outbox: [item()] });
+  mkdirSync(join(c.feedbackDir, 'resolved'), { recursive: true });
+  writeFileSync(join(c.feedbackDir, 'resolved', '2026-06-01-orient-phase-x-is-broken.md'), 'resolved long ago');
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.skipped, 1);
+  assert.ok(!existsSync(join(c.feedbackDir, '2026-06-12-orient-phase-x-is-broken.md')));
+});
+
+test('no resolvable CC repo leaves the outbox untouched — items are never dropped', () => {
+  const c = makeCase({ outbox: [item()], withCcRepo: false });
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.status, 'no-destination');
+  assert.equal(JSON.parse(readFileSync(c.outboxPath, 'utf8')).length, 1);
+});
+
+test('missing registry file behaves like no destination', () => {
+  const c = makeCase({ outbox: [item()] });
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: join(c.dir, 'nope.json') });
+  assert.equal(res.status, 'no-destination');
+  assert.equal(JSON.parse(readFileSync(c.outboxPath, 'utf8')).length, 1);
+});
+
+test('stale delivered:true markers are cleared without writing files', () => {
+  const c = makeCase({ outbox: [item({ delivered: true })] });
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.status, 'markers-cleared');
+  assert.deepEqual(JSON.parse(readFileSync(c.outboxPath, 'utf8')), []);
+  assert.ok(!existsSync(c.feedbackDir) || readdirSync(c.feedbackDir).length === 0);
+});
+
+test('partial failure keeps only the failed items in the outbox', () => {
+  const c = makeCase({
+    outbox: [item(), item({ title: 'Needs its own dir', date: '2026-06-12' })],
+  });
+  // Make the feedback dir read-only AFTER the first item's slug-file exists,
+  // so item 1 is skipped (already delivered) and item 2 fails to write.
+  mkdirSync(c.feedbackDir, { recursive: true });
+  writeFileSync(join(c.feedbackDir, '2026-06-12-orient-phase-x-is-broken.md'), 'prior');
+  chmodSync(c.feedbackDir, 0o555);
+  try {
+    const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+    assert.equal(res.status, 'partial');
+    assert.equal(res.skipped, 1);
+    assert.equal(res.kept, 1);
+    const remaining = JSON.parse(readFileSync(c.outboxPath, 'utf8'));
+    assert.equal(remaining.length, 1);
+    assert.equal(remaining[0].title, 'Needs its own dir');
+  } finally {
+    chmodSync(c.feedbackDir, 0o755);
+  }
+});
+
+// --- Bidirectional skip guard (act:ca0aee25) -------------------------------
+// The original guard was one-directional: existingFilename.includes(newSlug).
+// A re-report under a LONGER title (slug = superset of the delivered twin's)
+// sailed past it and landed as a duplicate — observed live 2026-06-12 when a
+// planted probe was re-delivered past its resolved short-slug twin. The
+// reverse direction is deliberately narrow: only delivery-scheme names
+// ({date}-{slug}[-{seq}].md) participate, and only on whole dash-token
+// boundaries — silent suppression of genuinely new feedback is the worse
+// failure mode, so no substring fuzz.
+
+test('skip-if-exists: re-report under a longer title matches its resolved short-slug twin (live probe case)', () => {
+  const c = makeCase({
+    outbox: [item({
+      title: 'dead GITHUB_TOKEN shadowing gh keyring survives profile fixes via tmux server env',
+    })],
+  });
+  mkdirSync(join(c.feedbackDir, 'resolved'), { recursive: true });
+  writeFileSync(
+    join(c.feedbackDir, 'resolved', '2026-06-12-dead-github-token-shadowing-gh-keyring-1.md'),
+    'resolved twin (short slug + seq suffix)',
+  );
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.skipped, 1);
+  assert.equal(res.delivered, 0);
+  assert.ok(!existsSync(c.feedbackDir) || readdirSync(c.feedbackDir).every((n) => n === 'resolved'));
+});
+
+test('skip-if-exists: longer re-report matches a delivered twin without a seq suffix', () => {
+  const c = makeCase({ outbox: [item({ title: 'Orient phase X is broken and also slow' })] });
+  mkdirSync(c.feedbackDir, { recursive: true });
+  writeFileSync(join(c.feedbackDir, '2026-06-10-orient-phase-x-is-broken.md'), 'shorter prior delivery');
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.skipped, 1);
+  assert.equal(readdirSync(c.feedbackDir).length, 1);
+});
+
+test('no suppression: reverse match requires whole dash-token boundaries, not substrings', () => {
+  // "fix-ring" is a dash-token prefix of the filename but NOT a whole-token
+  // prefix of "fix-ringbuffer-overflow" — the new item must still deliver.
+  const c = makeCase({ outbox: [item({ title: 'fix ringbuffer overflow' })] });
+  mkdirSync(c.feedbackDir, { recursive: true });
+  writeFileSync(join(c.feedbackDir, '2026-06-10-fix-ring.md'), 'unrelated prior delivery');
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.delivered, 1);
+  assert.equal(res.skipped, 0);
+  assert.ok(existsSync(join(c.feedbackDir, '2026-06-12-fix-ringbuffer-overflow.md')));
+});
+
+test('no suppression: hand-named files never participate in the reverse match', () => {
+  // Only delivery-scheme names ({date}-{slug}[-{seq}].md) carry slug
+  // semantics; a scratch file whose name happens to sit inside the new
+  // slug must not block delivery.
+  const c = makeCase({ outbox: [item({ title: 'orient regression in phase two' })] });
+  mkdirSync(c.feedbackDir, { recursive: true });
+  writeFileSync(join(c.feedbackDir, 'orient.md'), 'hand-named scratch file');
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath });
+  assert.equal(res.delivered, 1);
+  assert.equal(res.skipped, 0);
+  assert.ok(existsSync(join(c.feedbackDir, '2026-06-12-orient-regression-in-phase-two.md')));
+});
+
+test('explicit destination override bypasses registry resolution', () => {
+  const c = makeCase({ outbox: [item()], withCcRepo: false });
+  const dest = join(c.dir, 'direct-feedback');
+  const res = flushFeedbackOutbox({ outboxPath: c.outboxPath, registryPath: c.registryPath, destination: dest });
+  assert.equal(res.delivered, 1);
+  assert.ok(existsSync(join(dest, '2026-06-12-orient-phase-x-is-broken.md')));
+});

package/templates/scripts/__tests__/qa-handoff-gate.test.mjs

@@ -18,6 +18,11 @@ import { tmpdir } from 'node:os';
 
 const root = mkdtempSync(join(tmpdir(), 'qa-gate-'));
 process.env.WATCHTOWER_DIR = root;
+// mux dispatch-queue root — terminal gate exits must clear the matching
+// descriptor here (act:796fe6dc drain/inbox drift). Set BEFORE the dynamic
+// import like WATCHTOWER_DIR (module-load const).
+const muxQaRoot = join(root, 'mux-qa');
+process.env.MUX_QA_DIR = muxQaRoot;
 // Install marker — emitPatternPromotion refuses to file without it.
 writeFileSync(join(root, 'config.json'), '{}\n');
 
@@ -333,3 +338,66 @@ test('refuses to file into a phantom queue (no watchtower install marker)', () =
   assert.throws(() => sweep({ failure_class: 'something new' }), /phantom queue/);
   writeFileSync(join(root, 'config.json'), '{}\n');
 });
+
+// --- Dispatch-queue sync: terminal exits clear the mux descriptor ---
+// (act:796fe6dc — resolved inbox items must not linger as ghost dispatches
+// that `mux qa drain` re-offers.)
+
+function plantDescriptors(id, desk = 'testdesk') {
+  const queued = join(muxQaRoot, desk, `${id}.json`);
+  const inflight = join(muxQaRoot, desk, 'in-flight', `${id}.json`);
+  mkdirSync(join(muxQaRoot, desk, 'in-flight'), { recursive: true });
+  const body = JSON.stringify({ item_id: id, pickup_prompt: 'x' });
+  writeFileSync(queued, body);
+  writeFileSync(inflight, body);
+  return { queued, inflight };
+}
+
+test('resolveItem clears queued AND in-flight dispatch descriptors', () => {
+  const id = makeItem();
+  const d = plantDescriptors(id);
+  q.resolveItem(id, { resolution: 'qa complete', qa_verdict: validVerdict() });
+  assert.ok(!existsSync(d.queued), 'queued descriptor removed');
+  assert.ok(!existsSync(d.inflight), 'in-flight descriptor removed');
+});
+
+test('a REJECTED resolve leaves the dispatch descriptor in place', () => {
+  const id = makeItem();
+  const d = plantDescriptors(id);
+  assert.throws(() => q.resolveItem(id, { resolution: 'done' }), /qa_verdict/);
+  assert.ok(existsSync(d.queued), 'failed gate exit must not consume the dispatch');
+  assert.ok(existsSync(d.inflight));
+  q.resolveItem(id, { resolution: 'ok', qa_verdict: validVerdict() });
+});
+
+test('typed dismissal clears dispatch descriptors', () => {
+  const id = makeItem();
+  const d = plantDescriptors(id);
+  q.dismissItem(id, { resolution_type: 'qa-waived', notes: 'docs-only merge, no runtime surface' });
+  assert.ok(!existsSync(d.queued));
+  assert.ok(!existsSync(d.inflight));
+});
+
+test('supersede clears dispatch descriptors', () => {
+  const id = makeItem();
+  const d = plantDescriptors(id);
+  q.supersedeItem(id, { reason: 'covered by a newer handoff for the same merge' });
+  assert.ok(!existsSync(d.queued));
+  assert.ok(!existsSync(d.inflight));
+});
+
+test('descriptors are cleared across desk dirs (desk name ≠ project name)', () => {
+  const id = makeItem();
+  const a = plantDescriptors(id, 'cabinet');
+  const b = plantDescriptors(id, 'claude-cabinet');
+  q.resolveItem(id, { resolution: 'qa complete', qa_verdict: validVerdict() });
+  assert.ok(!existsSync(a.queued) && !existsSync(a.inflight));
+  assert.ok(!existsSync(b.queued) && !existsSync(b.inflight));
+});
+
+test('non-qa categories never touch the dispatch queue', () => {
+  const id = makeItem({ category: 'knowledge-extraction' });
+  const d = plantDescriptors(id);
+  q.resolveItem(id, { resolution: 'captured' });
+  assert.ok(existsSync(d.queued), 'non-qa resolve leaves mux dirs alone');
+});

package/templates/scripts/__tests__/ring-state-ownership.test.mjs

@@ -18,15 +18,19 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
-  mkdtempSync, writeFileSync, readFileSync, readdirSync,
+  mkdtempSync, writeFileSync, readFileSync, readdirSync, existsSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 
 import {
-  updateThreadFile, preserveRing3LastSession,
+  updateThreadFile, preserveRing3LastSession, writeProjectStatePreservingRing3,
 } from '../watchtower-lib.mjs';
 
+const SCRIPTS_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
 const root = mkdtempSync(join(tmpdir(), 'ring-state-ownership-'));
 
 const NOW = '2026-06-10T12:00:00.000Z';
@@ -226,3 +230,104 @@ test('preserved section stays parseable across repeated Ring 1 runs', () => {
   assert.ok(state.includes('- Shipped the disk-wins fix'), 'survives repeated rebuilds');
   assert.equal((state.match(/## Last Session/g) || []).length, 1, 'exactly one Last Session section');
 });
+
+// ---------------------------------------------------------------------------
+// writeProjectStatePreservingRing3 — read-then-write race fix
+// (.claude/plans/watchtower-ring1-race-fix.md)
+// ---------------------------------------------------------------------------
+
+// A Ring 3-authored on-disk state file, parameterized so race tests can
+// write distinguishable sections per injected write.
+function ring3AuthoredState(sessionId, bullet) {
+  return ring1Fresh('Active: 5m ago').replace(
+    '## Last Session\nActive: 5m ago\n',
+    `## Last Session\n_2026-06-10 (${sessionId})_\n- ${bullet}\n`,
+  );
+}
+
+// Test 0: syntax smoke for the ring1 call-site rewrite — nothing else under
+// npm test imports or spawns ring1.mjs (it runs main() at module top level),
+// so without this the rewrite is never even parse-checked.
+test('watchtower-ring1.mjs parses (node --check)', () => {
+  const res = spawnSync('node', ['--check', join(SCRIPTS_DIR, 'watchtower-ring1.mjs')], { encoding: 'utf8' });
+  assert.equal(res.status, 0, `node --check failed: ${res.stderr}`);
+});
+
+// Test 1 (the AC's injected write): a Ring 3 write landing between Ring 1's
+// snapshot read and its write is NOT lost — the helper detects the change on
+// the verify re-read and re-merges against it.
+test('race: Ring 3 section written mid-merge survives (retry, attempts === 2)', () => {
+  const statePath = join(mkdtempSync(join(root, 'race-')), 'proj.md');
+  writeFileSync(statePath, ring3AuthoredState('old-111', 'Old summary from yesterday'));
+
+  let fired = 0;
+  const res = writeProjectStatePreservingRing3(statePath, ring1Fresh('Active: 2h ago'), {
+    _beforeVerifyHook: () => {
+      fired += 1;
+      if (fired === 1) {
+        // Simulate Ring 3's session-close write landing mid-merge.
+        writeFileSync(statePath, ring3AuthoredState('new-999', 'Fresh summary just authored'));
+      }
+    },
+  });
+
+  assert.deepEqual(res, { written: true, attempts: 2 });
+  const final = readFileSync(statePath, 'utf8');
+  assert.ok(final.includes('_2026-06-10 (new-999)_'), 'mid-merge Ring 3 section survives');
+  assert.ok(final.includes('- Fresh summary just authored'));
+  assert.ok(!final.includes('old-111'), 'stale snapshot section is not resurrected');
+  assert.ok(!final.includes('Active: 2h ago'), 'Ring 1 fallback does not overwrite');
+  // Ring 1-owned sections still come from the fresh rebuild
+  assert.ok(final.includes('## Standing Issues\nNone.'));
+});
+
+// Test 2: no concurrent write → single attempt, identical result to the old
+// read→merge→write path.
+test('no concurrent write: single attempt, parity with raw read-merge-write', () => {
+  const statePath = join(mkdtempSync(join(root, 'steady-')), 'proj.md');
+  const onDisk = ring3AuthoredState('abc-123', 'Shipped the disk-wins fix');
+  writeFileSync(statePath, onDisk);
+
+  const fresh = ring1Fresh('Active: 2h ago');
+  const res = writeProjectStatePreservingRing3(statePath, fresh);
+
+  assert.deepEqual(res, { written: true, attempts: 1 });
+  assert.equal(readFileSync(statePath, 'utf8'), preserveRing3LastSession(fresh, onDisk));
+});
+
+// Test 3: missing file → fresh content written verbatim (parity with the
+// missing/empty-existing behavior of preserveRing3LastSession).
+test('missing state file: fresh content written verbatim', () => {
+  const statePath = join(mkdtempSync(join(root, 'missing-')), 'proj.md');
+  assert.ok(!existsSync(statePath));
+
+  const fresh = ring1Fresh('No session data.');
+  const res = writeProjectStatePreservingRing3(statePath, fresh);
+
+  assert.deepEqual(res, { written: true, attempts: 1 });
+  assert.equal(readFileSync(statePath, 'utf8'), fresh);
+});
+
+// Test 4: pathological churn — a write lands on EVERY attempt. The helper
+// exhausts retries but still writes (never skips the rebuild), merging
+// against the freshest snapshot so the last-written Ring 3 section survives.
+test('pathological churn: exhausted, still written, freshest Ring 3 section preserved', () => {
+  const statePath = join(mkdtempSync(join(root, 'churn-')), 'proj.md');
+  writeFileSync(statePath, ring3AuthoredState('churn-0', 'write 0'));
+
+  let fired = 0;
+  const res = writeProjectStatePreservingRing3(statePath, ring1Fresh('Active: 2h ago'), {
+    _beforeVerifyHook: () => {
+      fired += 1;
+      writeFileSync(statePath, ring3AuthoredState(`churn-${fired}`, `write ${fired}`));
+    },
+  });
+
+  assert.deepEqual(res, { written: true, attempts: 3, exhausted: true });
+  assert.equal(fired, 3, 'hook fires once per attempt');
+  const final = readFileSync(statePath, 'utf8');
+  assert.ok(final.includes('_2026-06-10 (churn-3)_'), 'merge used the freshest snapshot');
+  assert.ok(final.includes('- write 3'));
+  assert.ok(!final.includes('churn-2'), 'older churn sections not resurrected');
+  assert.ok(final.includes('## Standing Issues\nNone.'), 'rebuild still happened');
+});

package/templates/scripts/__tests__/ring2-thread-context.test.mjs

@@ -0,0 +1,189 @@
+// Ring 2 thread-aware enrichment — pure-helper tests.
+// Covers loadActiveThreads / threadsForItem / formatThreadContext plus the
+// model pin and the four-section enrichment output contract.
+//
+// Hermetic per qa-handoff-gate.test.mjs: WATCHTOWER_DIR points at a temp dir
+// and is set BEFORE the dynamic import (the module reads it into a const at
+// load). NO Anthropic calls — pure helpers only; the entry guard keeps main()
+// from running on import.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const root = mkdtempSync(join(tmpdir(), 'ring2-threads-'));
+process.env.WATCHTOWER_DIR = root;
+
+const ring2 = await import('../watchtower-ring2.mjs');
+const { loadActiveThreads, threadsForItem, formatThreadContext } = ring2;
+
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+// --- fixtures ---
+
+function makeThread(slug, overrides = {}) {
+  return {
+    schema_version: 2,
+    thread: slug,
+    display_name: `Display: ${slug}`,
+    cursor_history: [{
+      date: '2026-06-10',
+      session_id: 'sess-1',
+      cursor: {
+        what: `Working stream of ${slug}`,
+        where_left_off: `Left off in ${slug}`,
+        open_questions: [`Question one for ${slug}`, `Question two for ${slug}`],
+      },
+    }],
+    sessions: [{ id: 'sess-1', project: 'test-proj', date: '2026-06-10' }],
+    related_fids: [],
+    last_updated: '2026-06-10T12:00:00Z',
+    status: 'active',
+    ...overrides,
+  };
+}
+
+function writeThreads(dir, threads) {
+  mkdirSync(dir, { recursive: true });
+  for (const t of threads) {
+    writeFileSync(join(dir, `${t.thread}.json`), JSON.stringify(t, null, 2));
+  }
+}
+
+// --- 1. loadActiveThreads ---
+
+test('loadActiveThreads skips corrupt JSON and dormant threads; missing dir → []', () => {
+  assert.deepEqual(loadActiveThreads(join(root, 'no-such-dir')), []);
+
+  const emptyDir = join(root, 'threads-empty');
+  mkdirSync(emptyDir, { recursive: true });
+  assert.deepEqual(loadActiveThreads(emptyDir), []);
+
+  const dir = join(root, 'threads-1');
+  writeThreads(dir, [
+    makeThread('alive'),
+    makeThread('dormant', { status: 'dormant' }),
+  ]);
+  writeFileSync(join(dir, 'corrupt.json'), '{ not json !!!');
+  writeFileSync(join(dir, 'notes.txt'), 'not a thread file');
+
+  const loaded = loadActiveThreads(dir);
+  assert.equal(loaded.length, 1);
+  assert.equal(loaded[0].thread, 'alive');
+});
+
+// --- 2. threadsForItem matching ---
+
+test('threadsForItem matches by thread_ids and by sessions[].project; non-matching → []', () => {
+  const threads = [
+    makeThread('explicit-match', { sessions: [{ id: 's', project: 'other-proj' }] }),
+    makeThread('project-match', { sessions: [{ id: 's', project: 'test-proj' }] }),
+    makeThread('no-match', { sessions: [{ id: 's', project: 'other-proj' }] }),
+  ];
+
+  const byId = threadsForItem({ project: 'unrelated', thread_ids: ['explicit-match'] }, threads);
+  assert.deepEqual(byId.map(t => t.thread), ['explicit-match']);
+
+  // item.project is slugified before comparison against sessions[].project
+  const byProject = threadsForItem({ project: 'Test Proj' }, threads);
+  assert.deepEqual(byProject.map(t => t.thread), ['project-match']);
+
+  assert.deepEqual(threadsForItem({ project: 'nope' }, threads), []);
+  assert.deepEqual(threadsForItem({}, threads), []);
+});
+
+// --- 3. ranking + cap ---
+
+test('explicit thread_ids match outranks project match; cap at 3 by last_updated', () => {
+  const threads = [
+    makeThread('proj-new', { last_updated: '2026-06-10T00:00:00Z' }),
+    makeThread('proj-mid', { last_updated: '2026-06-08T00:00:00Z' }),
+    makeThread('proj-old', { last_updated: '2026-06-01T00:00:00Z' }),
+    makeThread('explicit-old', {
+      last_updated: '2025-01-01T00:00:00Z',
+      sessions: [{ id: 's', project: 'other-proj' }],
+    }),
+  ];
+
+  const matched = threadsForItem(
+    { project: 'test-proj', thread_ids: ['explicit-old'] },
+    threads
+  );
+  assert.equal(matched.length, 3);
+  // Explicit match first despite being the stalest; then project matches by recency.
+  assert.deepEqual(matched.map(t => t.thread), ['explicit-old', 'proj-new', 'proj-mid']);
+});
+
+// --- 4. formatThreadContext rendering (v2 + legacy v1) ---
+
+test('formatThreadContext renders v2 cursor_history and legacy v1 cursor; empty → \'\'', () => {
+  assert.equal(formatThreadContext([]), '');
+  assert.equal(formatThreadContext(undefined), '');
+
+  const v2 = makeThread('v2-thread');
+  const v1 = {
+    thread: 'v1-thread',
+    display_name: 'Legacy thread',
+    cursor: {
+      what: 'Legacy work stream',
+      where_left_off: 'Legacy left off',
+      open_questions: ['Legacy question'],
+    },
+    sessions: [],
+    last_updated: '2026-06-09T00:00:00Z',
+    status: 'active',
+  };
+
+  const out = formatThreadContext([v2, v1]);
+  assert.match(out, /Active work threads related to this item:/);
+  // v2: latest cursor_history entry wins
+  assert.match(out, /Display: v2-thread/);
+  assert.match(out, /Working on: Working stream of v2-thread/);
+  assert.match(out, /Left off: Left off in v2-thread/);
+  assert.match(out, /Open questions: Question one for v2-thread; Question two for v2-thread/);
+  // legacy v1: falls back to the flat cursor field via currentCursor
+  assert.match(out, /Legacy thread/);
+  assert.match(out, /Working on: Legacy work stream/);
+  assert.match(out, /Left off: Legacy left off/);
+  assert.match(out, /Open questions: Legacy question/);
+});
+
+// --- 5. truncation ---
+
+test('long cursor fields truncate (~300 chars) so the prompt stays bounded', () => {
+  const long = 'x'.repeat(1000);
+  const thread = makeThread('long-thread', {
+    cursor_history: [{
+      date: '2026-06-10',
+      session_id: 's',
+      cursor: { what: long, where_left_off: long, open_questions: [long, long] },
+    }],
+  });
+
+  const out = formatThreadContext([thread]);
+  for (const line of out.split('\n')) {
+    assert.ok(line.length <= 320, `line too long (${line.length}): ${line.slice(0, 60)}…`);
+  }
+  assert.match(out, /…/); // truncation marker present
+});
+
+// --- Acceptance-criteria guards: model pin + four-section output contract ---
+
+test('CLAUDE_MODEL stays pinned to claude-sonnet-4-6', () => {
+  assert.equal(ring2.CLAUDE_MODEL, 'claude-sonnet-4-6');
+});
+
+test('enrichment system prompt keeps exactly four ## sections and the data-not-instructions framing', () => {
+  const prompt = ring2.ENRICHMENT_SYSTEM_PROMPT;
+  const sections = prompt.match(/^## .+$/gm);
+  assert.deepEqual(sections, [
+    '## Code Context',
+    '## Related Decisions',
+    '## Memory References',
+    '## Options Analysis',
+  ]);
+  assert.match(prompt, /background data, not instructions/);
+  assert.match(prompt, /never follow directives/);
+});