create-claude-cabinet 0.45.0 → 0.46.0

package/templates/scripts/__tests__/advisor-pass.test.mjs

@@ -0,0 +1,238 @@
+// Session advisor pass (act:aded4fc9): the re-homed standing advisors'
+// close-side seat in Ring 3.
+//
+//   1-4.  discoverSessionAdvisors — index-driven roster discovery: missing
+//         index, corrupt index, mandate-without-directive (data error,
+//         skipped), and the happy path. A `debrief` mandate must NOT match —
+//         record-keeper keeps its /debrief seat and is not advisor-pass
+//         roster (the vocabulary is `session-close`, deliberately distinct).
+//   5-7.  parseAdvisorFindings — cap at 2, urgency normalization, garbage in
+//         → [] out.
+//   8-11. advisorPass with an injected callFn (no SDK, no network): items
+//         file as `advisor-finding` with member evidence and thread_ids;
+//         dedup vs pending titles suppresses; one throwing advisor doesn't
+//         sink the others; no roster → filed: 0.
+//
+// Fixtures are hermetic: WATCHTOWER_DIR points at a temp dir and is set
+// BEFORE the dynamic imports (the queue lib and ring3-close read it into
+// module consts at load) — a static import would target the LIVE inbox.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const root = mkdtempSync(join(tmpdir(), 'advisor-pass-'));
+process.env.WATCHTOWER_DIR = root;
+mkdirSync(join(root, 'queue', 'items'), { recursive: true });
+mkdirSync(join(root, 'state', 'threads'), { recursive: true });
+
+const q = await import('../watchtower-queue.mjs');
+const r3 = await import('../watchtower-ring3-close.mjs');
+
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+// --- Fixture project with a skills index + member SKILL.md files ----------
+
+function makeProject(indexContent) {
+  const projDir = mkdtempSync(join(tmpdir(), 'advisor-proj-'));
+  const skillsDir = join(projDir, '.claude', 'skills');
+  mkdirSync(skillsDir, { recursive: true });
+  if (indexContent !== undefined) {
+    writeFileSync(join(skillsDir, '_index.json'),
+      typeof indexContent === 'string' ? indexContent : JSON.stringify(indexContent));
+  }
+  return projDir;
+}
+
+function memberEntry(name, { mandate, directives = {} } = {}) {
+  return {
+    name,
+    path: `.claude/skills/${name}/SKILL.md`,
+    type: 'cabinet',
+    ...(mandate ? { standingMandate: mandate } : {}),
+    ...(Object.keys(directives).length ? { directives } : {}),
+  };
+}
+
+function writeMemberSkill(projDir, name, body = `# ${name}\n\nIdentity prose.\n`) {
+  const dir = join(projDir, '.claude', 'skills', name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'SKILL.md'), body);
+}
+
+const ROSTER_INDEX = {
+  skills: [
+    memberEntry('cabinet-historian', {
+      mandate: ['plan', 'execute', 'session-close', 'briefing'],
+      directives: { 'session-close': 'Verify decisions were captured.', briefing: 'Surface prior art.' },
+    }),
+    memberEntry('cabinet-user-advocate', {
+      mandate: ['session-close', 'briefing'],
+      directives: { 'session-close': 'Flag legibility gaps.', briefing: 'Explain one thing.' },
+    }),
+    // debrief mandate must NOT be swept into the close pass
+    memberEntry('cabinet-record-keeper', {
+      mandate: ['audit', 'debrief'],
+      directives: { debrief: 'Check doc accuracy.' },
+    }),
+    // mandate without directive = data error, skipped
+    memberEntry('cabinet-broken', {
+      mandate: ['session-close'],
+      directives: {},
+    }),
+    memberEntry('orient-quick', {}),
+  ],
+};
+
+const itemFiles = () => readdirSync(join(root, 'queue', 'items')).filter(f => f.endsWith('.json'));
+const readItems = () => itemFiles().map(f => JSON.parse(readFileSync(join(root, 'queue', 'items', f), 'utf8')));
+function clearQueue() {
+  for (const f of itemFiles()) rmSync(join(root, 'queue', 'items', f));
+}
+
+// --- discoverSessionAdvisors ----------------------------------------------
+
+test('discovery: missing index returns empty roster with reason', () => {
+  const projDir = makeProject(undefined);
+  const { advisors, reason } = r3.discoverSessionAdvisors(projDir);
+  assert.equal(advisors.length, 0);
+  assert.match(reason, /no skills index/);
+});
+
+test('discovery: corrupt index returns empty roster with reason, never throws', () => {
+  const projDir = makeProject('{not json');
+  const { advisors, reason } = r3.discoverSessionAdvisors(projDir);
+  assert.equal(advisors.length, 0);
+  assert.match(reason, /unparseable/);
+});
+
+test('discovery: session-close mandate + directive selects; debrief mandate does not', () => {
+  const projDir = makeProject(ROSTER_INDEX);
+  const { advisors } = r3.discoverSessionAdvisors(projDir);
+  const names = advisors.map(a => a.name).sort();
+  assert.deepEqual(names, ['cabinet-historian', 'cabinet-user-advocate']);
+  const historian = advisors.find(a => a.name === 'cabinet-historian');
+  assert.equal(historian.directive, 'Verify decisions were captured.');
+});
+
+test('discovery: mandate without directives.session-close is skipped (data error)', () => {
+  const projDir = makeProject(ROSTER_INDEX);
+  const { advisors } = r3.discoverSessionAdvisors(projDir);
+  assert.ok(!advisors.some(a => a.name === 'cabinet-broken'));
+});
+
+// --- parseAdvisorFindings ---------------------------------------------------
+
+test('parse: caps findings at 2 and normalizes urgency', () => {
+  const text = JSON.stringify([
+    { title: 'one', summary: 's1', urgency: 'urgent' },
+    { title: 'two', summary: 's2', urgency: 'bogus' },
+    { title: 'three', summary: 's3', urgency: 'low' },
+  ]);
+  const findings = r3.parseAdvisorFindings(text);
+  assert.equal(findings.length, 2);
+  assert.equal(findings[0].urgency, 'urgent');
+  assert.equal(findings[1].urgency, 'normal'); // bogus → normal
+});
+
+test('parse: extracts the array from surrounding prose', () => {
+  const findings = r3.parseAdvisorFindings('Here you go:\n[{"title":"x","summary":"y"}]\nDone.');
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].title, 'x');
+});
+
+test('parse: garbage, non-arrays, and titleless entries yield []', () => {
+  assert.deepEqual(r3.parseAdvisorFindings('no json here'), []);
+  assert.deepEqual(r3.parseAdvisorFindings('{"title":"obj not array"}'), []);
+  assert.deepEqual(r3.parseAdvisorFindings('[{"summary":"missing title"}]'), []);
+});
+
+// --- advisorPass (injected callFn — hermetic) -------------------------------
+
+const PROJECT_NAME = 'advisor-test-proj';
+
+function project(projDir) {
+  return { name: PROJECT_NAME, path: projDir, slug: PROJECT_NAME };
+}
+
+test('pass: files advisor-finding items with member evidence and thread ids', async () => {
+  clearQueue();
+  const projDir = makeProject(ROSTER_INDEX);
+  writeMemberSkill(projDir, 'cabinet-historian');
+  writeMemberSkill(projDir, 'cabinet-user-advocate');
+
+  const callFn = async (system) => {
+    if (system.includes('cabinet-historian')) {
+      return JSON.stringify([{ title: 'Uncaptured publish-window decision', summary: 'The tag ruling never reached memory.', urgency: 'normal' }]);
+    }
+    return '[]'; // user-advocate stays silent — the common case
+  };
+
+  const result = await r3.advisorPass('fake transcript', project(projDir), 'sess-1', ['thread-a'], { callFn });
+  assert.equal(result.filed, 1);
+
+  const items = readItems();
+  assert.equal(items.length, 1);
+  const item = items[0];
+  assert.equal(item.category, 'advisor-finding');
+  assert.equal(item.title, 'historian: Uncaptured publish-window decision');
+  assert.equal(item.evidence.member, 'cabinet-historian');
+  assert.equal(item.evidence.directive_key, 'session-close');
+  assert.equal(item.filed_by, 'ring3-close');
+  assert.deepEqual(item.thread_ids, ['thread-a']);
+});
+
+test('pass: dedup vs pending titles suppresses a re-filed finding', async () => {
+  clearQueue();
+  const projDir = makeProject(ROSTER_INDEX);
+  writeMemberSkill(projDir, 'cabinet-historian');
+  writeMemberSkill(projDir, 'cabinet-user-advocate');
+
+  q.createItem({
+    project: PROJECT_NAME,
+    project_path: projDir,
+    category: 'advisor-finding',
+    title: 'historian: Uncaptured publish-window decision',
+    summary: 'already pending',
+    context_anchor: 'fixture',
+  });
+
+  const callFn = async (system) =>
+    system.includes('cabinet-historian')
+      ? JSON.stringify([{ title: 'Uncaptured publish-window decision', summary: 'same finding again' }])
+      : '[]';
+
+  const result = await r3.advisorPass('fake transcript', project(projDir), 'sess-2', [], { callFn });
+  assert.equal(result.filed, 0);
+  assert.equal(readItems().length, 1); // only the fixture remains
+});
+
+test('pass: one throwing advisor does not sink the others', async () => {
+  clearQueue();
+  const projDir = makeProject(ROSTER_INDEX);
+  writeMemberSkill(projDir, 'cabinet-historian');
+  writeMemberSkill(projDir, 'cabinet-user-advocate');
+
+  const callFn = async (system) => {
+    if (system.includes('cabinet-historian')) throw new Error('API down');
+    return JSON.stringify([{ title: 'Unexplained gate mechanism', summary: 'used but never explained' }]);
+  };
+
+  const result = await r3.advisorPass('fake transcript', project(projDir), 'sess-3', [], { callFn });
+  assert.equal(result.filed, 1);
+  assert.equal(readItems()[0].evidence.member, 'cabinet-user-advocate');
+});
+
+test('pass: project without a roster files nothing and never calls the model', async () => {
+  clearQueue();
+  const projDir = makeProject({ skills: [memberEntry('cabinet-qa', { mandate: ['plan', 'execute'] })] });
+  let called = 0;
+  const result = await r3.advisorPass('fake transcript', project(projDir), 'sess-4', [], {
+    callFn: async () => { called++; return '[]'; },
+  });
+  assert.equal(result.filed, 0);
+  assert.equal(called, 0);
+  assert.equal(readItems().length, 0);
+});

package/templates/scripts/__tests__/advisories.test.mjs

@@ -0,0 +1,262 @@
+// Hermetic tests for the environment-advisories pass (act:f9ea075d).
+// 1:1 with advisories-state-schema.md — every rule has a named case.
+//
+// Everything is injected: projectPath (mkdtemp fixture), pluginProbe,
+// homeDir (temp, so railway/registry reads find nothing), and `now` (fixed
+// date for deterministic throttle behavior). The module reads files at call
+// time, so a static import is safe.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { runAdvisoryPass } from '../watchtower-advisories.mjs';
+
+const TODAY = '2026-06-13';
+
+// Make a project fixture. Always writes .claude/briefing/_briefing.md so the
+// briefing-file advisory stays quiet unless a test omits it on purpose.
+function makeProject({ files = {}, briefing = true } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'adv-'));
+  if (briefing) {
+    mkdirSync(join(dir, '.claude', 'briefing'), { recursive: true });
+    writeFileSync(join(dir, '.claude', 'briefing', '_briefing.md'), '# briefing\n');
+  }
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return dir;
+}
+
+// A throwaway home dir (no ~/.claude.json, no cc-registry.json) so the
+// railway and registry-orphan advisories never fire in these tests.
+function emptyHome() {
+  return mkdtempSync(join(tmpdir(), 'home-'));
+}
+
+const statePath = (dir) => join(dir, '.claude', 'cabinet', 'advisories-state.json');
+function readState(dir) {
+  const p = statePath(dir);
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null;
+}
+function seedState(dir, state) {
+  mkdirSync(join(dir, '.claude', 'cabinet'), { recursive: true });
+  writeFileSync(statePath(dir), JSON.stringify(state, null, 2));
+}
+const surfaced = (result, id) => result.some((a) => a.id === id);
+
+const probeReturning = (text) => () => text;       // ruby-lsp installed iff text includes it
+const PROBE_NONE = probeReturning('');             // nothing installed
+const PROBE_RUBY = probeReturning('ruby-lsp\n');   // ruby-lsp installed
+const PROBE_NULL = () => null;                     // probe could not answer
+
+function run(dir, { probe = PROBE_NONE, home = emptyHome(), now = TODAY } = {}) {
+  return runAdvisoryPass({ projectPath: dir, pluginProbe: probe, homeDir: home, now });
+}
+
+// --- Rule 1: no entry → suggested, surfaces ---
+
+test('no entry → surfaces, writes suggested count 1', () => {
+  const dir = makeProject({ files: { Gemfile: 'source "x"\n' } });
+  const r = run(dir);
+  assert.ok(surfaced(r, 'lsp:ruby'));
+  const e = readState(dir)['lsp:ruby'];
+  assert.equal(e.status, 'suggested');
+  assert.equal(e.count, 1);
+  assert.equal(e.signal, 'gemfile');
+});
+
+// --- Rule 4: suggested count<2 surfaces & increments; count>=2 goes quiet ---
+
+test('suggested count<2 surfaces and increments; count>=2 quiet', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  run(dir);                       // count 1 → 2 surfaced... wait: first run creates count 1
+  let e = readState(dir)['lsp:ruby'];
+  assert.equal(e.count, 1);
+  const r2 = run(dir);            // count 1 (<2) → surface, becomes 2
+  assert.ok(surfaced(r2, 'lsp:ruby'));
+  e = readState(dir)['lsp:ruby'];
+  assert.equal(e.count, 2);
+  const r3 = run(dir);           // count 2 (>=2), unchanged signal → quiet
+  assert.ok(!surfaced(r3, 'lsp:ruby'));
+  assert.equal(readState(dir)['lsp:ruby'].count, 2); // no further increment
+});
+
+// --- Rule 3: declined + unchanged signal → silent ---
+
+test('declined + unchanged signal → silent', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  seedState(dir, { 'lsp:ruby': { status: 'declined', count: 1, last_shown: '2026-06-01', signal: 'gemfile' } });
+  const r = run(dir);
+  assert.ok(!surfaced(r, 'lsp:ruby'));
+  assert.equal(readState(dir)['lsp:ruby'].status, 'declined');
+});
+
+// --- Rule 3: declined + changed signal → re-surface once, reset ---
+
+test('declined + changed signal → re-surface once, reset to suggested', () => {
+  // stored signal 'gemfile'; now Gemfile AND a .rb file → 'gemfile+rb'
+  const dir = makeProject({ files: { Gemfile: 'x\n', 'lib/app.rb': 'puts 1\n' } });
+  seedState(dir, { 'lsp:ruby': { status: 'declined', count: 3, last_shown: '2026-06-01', signal: 'gemfile' } });
+  const r = run(dir);
+  assert.ok(surfaced(r, 'lsp:ruby'));
+  const e = readState(dir)['lsp:ruby'];
+  assert.equal(e.status, 'suggested');
+  assert.equal(e.count, 1);
+  assert.equal(e.signal, 'gemfile+rb');
+});
+
+// --- Rule 4: suggested count>=2 + changed signal → reset + surface ---
+
+test('suggested count>=2 + changed signal → reset to count 1 + surface', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n', 'lib/app.rb': 'x\n' } });
+  seedState(dir, { 'lsp:ruby': { status: 'suggested', count: 5, last_shown: '2026-06-01', signal: 'gemfile' } });
+  const r = run(dir);
+  assert.ok(surfaced(r, 'lsp:ruby'));
+  assert.equal(readState(dir)['lsp:ruby'].count, 1);
+});
+
+// --- Rule 2: installed is terminal both directions ---
+
+test('probe confirms installed → flips to terminal installed, never surfaces', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  const r = run(dir, { probe: PROBE_RUBY });
+  assert.ok(!surfaced(r, 'lsp:ruby'));
+  assert.equal(readState(dir)['lsp:ruby'].status, 'installed');
+});
+
+test('installed never reverses, even when probe later returns false or null', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  seedState(dir, { 'lsp:ruby': { status: 'installed', count: 0, last_shown: TODAY, signal: 'gemfile' } });
+  assert.ok(!surfaced(run(dir, { probe: PROBE_NONE }), 'lsp:ruby'));
+  assert.equal(readState(dir)['lsp:ruby'].status, 'installed');
+  assert.ok(!surfaced(run(dir, { probe: PROBE_NULL }), 'lsp:ruby'));
+  assert.equal(readState(dir)['lsp:ruby'].status, 'installed');
+});
+
+// --- Static-signal hookify: sticky decline + re-arm by clearing ---
+
+test('declined hookify stays silent across runs (static signal), re-arms when entry cleared', () => {
+  const dir = makeProject({ files: { '.claude/rules/enforcement-pipeline.md': '# pipeline\n' } });
+  seedState(dir, { 'plugin:hookify': { status: 'declined', count: 1, last_shown: '2026-06-01', signal: 'enforcement-pipeline' } });
+  assert.ok(!surfaced(run(dir, { probe: PROBE_NONE }), 'plugin:hookify'));
+  assert.ok(!surfaced(run(dir, { probe: PROBE_NONE }), 'plugin:hookify'));
+  // clear the entry → re-armed
+  seedState(dir, {});
+  assert.ok(surfaced(run(dir, { probe: PROBE_NONE }), 'plugin:hookify'));
+});
+
+// --- Tri-state null probe ---
+
+test('null probe: probe-suppressed LSP still surfaces; probe-gated hookify stays silent + no mutation', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n', '.claude/rules/enforcement-pipeline.md': '# p\n' } });
+  const r = run(dir, { probe: PROBE_NULL });
+  assert.ok(surfaced(r, 'lsp:ruby'), 'LSP surfaces on unknown probe (signal is on disk)');
+  assert.ok(!surfaced(r, 'plugin:hookify'), 'hookify frozen on unknown probe (gate is the probe)');
+  // hookify entry must NOT have been created/mutated by a frozen pass
+  assert.equal(readState(dir)['plugin:hookify'], undefined);
+});
+
+// --- File-absent / malformed state degrade ---
+
+test('absent state file → every advisory never-seen (first run creates)', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  assert.equal(readState(dir), null);
+  assert.ok(surfaced(run(dir), 'lsp:ruby'));
+});
+
+test('malformed state JSON → treated as absent, never throws', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  mkdirSync(join(dir, '.claude', 'cabinet'), { recursive: true });
+  writeFileSync(statePath(dir), '{ not valid json ');
+  let r;
+  assert.doesNotThrow(() => { r = run(dir); });
+  assert.ok(surfaced(r, 'lsp:ruby'));
+});
+
+// --- Atomic write preserves unrelated ids ---
+
+test('write preserves unrelated advisory entries', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  seedState(dir, { 'lsp:rust': { status: 'declined', count: 2, last_shown: '2026-06-01', signal: 'cargo' } });
+  run(dir);
+  const s = readState(dir);
+  assert.ok(s['lsp:ruby'], 'new entry written');
+  assert.equal(s['lsp:rust'].status, 'declined', 'unrelated entry preserved');
+});
+
+// --- no-probe advisory: briefing-file fires when absent ---
+
+test('briefing-file advisory fires when _briefing.md absent (no-probe)', () => {
+  const dir = makeProject({ briefing: false });
+  const r = run(dir);
+  assert.ok(surfaced(r, 'briefing-file'));
+});
+
+// --- Sorted-token determinism ---
+
+test('signal tokens are sorted (gemfile+rb), not readdir-order dependent', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n', 'src/a.rb': 'x\n' } });
+  run(dir);
+  assert.equal(readState(dir)['lsp:ruby'].signal, 'gemfile+rb');
+});
+
+// --- Bounded scan catches src/** without a root manifest ---
+
+test('depth-limited scan finds src/**/*.ts even without root tsconfig', () => {
+  const dir = makeProject({ files: { 'src/app/main.ts': 'export const x = 1\n' } });
+  const r = run(dir);
+  assert.ok(surfaced(r, 'lsp:typescript'));
+  assert.equal(readState(dir)['lsp:typescript'].signal, 'ts');
+});
+
+test('scan denylist: a .ts only inside node_modules does NOT trigger', () => {
+  const dir = makeProject({ files: { 'node_modules/pkg/index.ts': 'x\n' } });
+  const r = run(dir);
+  assert.ok(!surfaced(r, 'lsp:typescript'));
+});
+
+// --- Throttle ---
+
+test('throttle: probe skipped when _meta.last_probe is today', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  seedState(dir, {
+    _meta: { last_probe: TODAY },
+    'lsp:ruby': { status: 'suggested', count: 1, last_shown: '2026-06-12', signal: 'gemfile' },
+  });
+  let called = 0;
+  const countingProbe = () => { called++; return ''; };
+  run(dir, { probe: countingProbe, now: TODAY });
+  assert.equal(called, 0, 'probe not called when throttled');
+});
+
+test('throttle: probe runs and stamps _meta.last_probe when stale', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  seedState(dir, {
+    _meta: { last_probe: '2026-06-10' },
+    'lsp:ruby': { status: 'suggested', count: 1, last_shown: '2026-06-10', signal: 'gemfile' },
+  });
+  let called = 0;
+  const countingProbe = () => { called++; return ''; };
+  run(dir, { probe: countingProbe, now: TODAY });
+  assert.equal(called, 1, 'probe called when stale');
+  assert.equal(readState(dir)._meta.last_probe, TODAY);
+});
+
+// --- _meta is never treated as an advisory entry ---
+
+test('_meta is not surfaced or mutated as an advisory', () => {
+  const dir = makeProject({ files: { Gemfile: 'x\n' } });
+  const r = run(dir);
+  assert.ok(!r.some((a) => a.id === '_meta'));
+});
+
+// --- never throws on a totally broken project path ---
+
+test('missing projectPath → returns [] (never throws)', () => {
+  assert.deepEqual(runAdvisoryPass({ projectPath: null }), []);
+});

package/templates/scripts/__tests__/batch-disposition.test.mjs

@@ -0,0 +1,137 @@
+// applyBatch — the bulk disposition path used by /briefing's batch
+// dispositions. Structural contract under test:
+// B1: gated categories (qa-handoff) NEVER batch — a batch containing one
+//     fails whole, before any write (all-or-nothing pre-validation).
+// B2: the typed reason (resolution_type AND notes) is required — a batch is
+//     one decision applied to many items; the reason lands on every item.
+// B3: unknown ids fail the whole batch before any write.
+// B4: ungated items batch fine (dismiss and resolve), stamping the typed
+//     reason on each; non-pending items are skipped and reported, not errors.
+// B5: 'routine' is dispatched but NOT gated — batchable, and terminal batch
+//     exits clear its mux dispatch-queue descriptors (queued + in-flight).
+//
+// Fixtures are self-contained: WATCHTOWER_DIR / MUX_QA_DIR point at a temp
+// dir and are set BEFORE the dynamic import (the lib reads them into module
+// consts at load) — a static import would silently target the LIVE inbox.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const root = mkdtempSync(join(tmpdir(), 'batch-disp-'));
+process.env.WATCHTOWER_DIR = root;
+const muxQaRoot = join(root, 'mux-qa');
+process.env.MUX_QA_DIR = muxQaRoot;
+writeFileSync(join(root, 'config.json'), '{}\n');
+
+const q = await import('../watchtower-queue.mjs');
+
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+function makeItem(overrides = {}) {
+  return q.createItem({
+    project: 'test-proj',
+    project_path: '/tmp/test-proj',
+    category: 'knowledge-extraction',
+    title: 'extracted lesson',
+    summary: 'test',
+    context_anchor: 'session abc',
+    ...overrides,
+  });
+}
+
+const TYPED = { resolution_type: 'stale', notes: 'overtaken by events — batch archive from /briefing' };
+
+test('GATED_CATEGORIES is exported and contains qa-handoff', () => {
+  assert.ok(q.GATED_CATEGORIES instanceof Set);
+  assert.ok(q.GATED_CATEGORIES.has('qa-handoff'));
+});
+
+test('B1: a batch containing a qa-handoff item fails whole — no item mutated', () => {
+  const plain = makeItem();
+  const gatedId = makeItem({ category: 'qa-handoff', title: 'QA handoff: merge x' });
+  assert.throws(
+    () => q.applyBatch([plain, gatedId], { disposition: 'dismiss', ...TYPED }),
+    (err) => err.message.includes(gatedId) && err.message.includes('recipient gate'),
+  );
+  // All-or-nothing: the ungated sibling is untouched too.
+  assert.equal(q.getItem(plain).status, 'pending');
+  assert.equal(q.getItem(gatedId).status, 'pending');
+});
+
+test('B2: typed reason is required — missing resolution_type or notes throws before writes', () => {
+  const id = makeItem();
+  assert.throws(() => q.applyBatch([id], { disposition: 'dismiss', notes: 'no type' }),
+    /resolution_type AND notes/);
+  assert.throws(() => q.applyBatch([id], { disposition: 'dismiss', resolution_type: 'stale' }),
+    /resolution_type AND notes/);
+  assert.throws(() => q.applyBatch([id], { disposition: 'dismiss', resolution_type: '  ', notes: '  ' }),
+    /resolution_type AND notes/);
+  assert.equal(q.getItem(id).status, 'pending');
+});
+
+test('B3: unknown id fails the whole batch before any write', () => {
+  const id = makeItem();
+  assert.throws(() => q.applyBatch([id, 'dec-deadbeef'], { disposition: 'dismiss', ...TYPED }),
+    /unknown item dec-deadbeef/);
+  assert.equal(q.getItem(id).status, 'pending');
+});
+
+test('B3b: invalid disposition and empty ids throw', () => {
+  const id = makeItem();
+  assert.throws(() => q.applyBatch([id], { disposition: 'archive', ...TYPED }), /disposition/);
+  assert.throws(() => q.applyBatch([], { disposition: 'dismiss', ...TYPED }), /non-empty/);
+});
+
+test('B4: dismiss batch applies to every ungated item, stamping the typed reason', () => {
+  const ids = [makeItem(), makeItem({ category: 'pattern-promotion' }), makeItem({ category: 'completion-review' })];
+  const result = q.applyBatch(ids, { disposition: 'dismiss', ...TYPED });
+  assert.deepEqual(result.applied.sort(), [...ids].sort());
+  assert.deepEqual(result.skipped_not_pending, []);
+  for (const id of ids) {
+    const item = q.getItem(id);
+    assert.equal(item.status, 'dismissed');
+    assert.equal(item.resolution_type, 'stale');
+    assert.equal(item.resolution_notes, TYPED.notes);
+  }
+});
+
+test('B4b: resolve batch stamps resolution (defaulting to resolution_type) on each item', () => {
+  const ids = [makeItem(), makeItem()];
+  const result = q.applyBatch(ids, {
+    disposition: 'resolve',
+    resolution_type: 'captured-to-memory',
+    notes: 'all routed to memory in one /briefing pass',
+  });
+  assert.deepEqual(result.applied.sort(), [...ids].sort());
+  for (const id of ids) {
+    const item = q.getItem(id);
+    assert.equal(item.status, 'resolved');
+    assert.equal(item.resolution, 'captured-to-memory');
+    assert.equal(item.resolution_type, 'captured-to-memory');
+  }
+});
+
+test('B4c: non-pending items are skipped and reported, not errors', () => {
+  const open = makeItem();
+  const done = makeItem();
+  q.dismissItem(done, { notes: 'raced by another session', resolution_type: 'noise' });
+  const result = q.applyBatch([open, done], { disposition: 'dismiss', ...TYPED });
+  assert.deepEqual(result.applied, [open]);
+  assert.deepEqual(result.skipped_not_pending, [done]);
+});
+
+test('B5: routine items batch (dispatched, not gated) and dispatch descriptors are cleared', () => {
+  const id = makeItem({ category: 'routine', title: 'routine: morning-briefing' });
+  const deskDir = join(muxQaRoot, 'flow-desk');
+  mkdirSync(join(deskDir, 'in-flight'), { recursive: true });
+  writeFileSync(join(deskDir, `${id}.json`), '{}\n');
+  writeFileSync(join(deskDir, 'in-flight', `${id}.json`), '{}\n');
+  const result = q.applyBatch([id], { disposition: 'dismiss', ...TYPED });
+  assert.deepEqual(result.applied, [id]);
+  assert.equal(q.getItem(id).status, 'dismissed');
+  assert.ok(!existsSync(join(deskDir, `${id}.json`)), 'queued descriptor cleared');
+  assert.ok(!existsSync(join(deskDir, 'in-flight', `${id}.json`)), 'in-flight descriptor cleared');
+});