create-claude-cabinet 0.49.0 → 0.50.0

package/templates/scripts/__tests__/qa-handoff-merged-by-construction.test.mjs

@@ -0,0 +1,310 @@
+// qa-handoff merged-by-construction (act:3d1ac2b7) — the boundary guards that
+// make a 'merged' claim verified rather than asserted, exercised against REAL
+// git repos (a local bare "origin" + a clone; no network — the same fixture
+// pattern as ahead-check-origin.test.mjs).
+//
+// The taxonomy under test (verifyMergedAncestry):
+//   verified     — merged_commit IS an ancestor of the resolved main ref
+//   refuted      — git answered definitively NOT an ancestor → filing rejected
+//   unverifiable — git can't answer (no repo / no main ref / non-sha) → filing
+//                  proceeds WITH a visible evidence.ancestry_verified stamp
+// Plus markHandoffMerged — the ONE legal merge-pending→merged doorway (same
+// verification, deferred stage-2 dispatch recorded by STATE in evidence) —
+// and the annotateItemEvidence fence that closes the evidence-patch side door.
+//
+// Fixture pattern matches qa-handoff-gate.test.mjs: WATCHTOWER_DIR + MUX_QA_DIR
+// are set BEFORE the dynamic import (the lib reads them into module consts).
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+const root = mkdtempSync(join(tmpdir(), 'qa-mbc-'));
+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 }));
+
+// --- git fixture: bare origin + clone; one merged lane, one unmerged branch ---
+
+function git(cwd, cmd) {
+  return execSync(`git ${cmd}`, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+function commit(cwd, file, body) {
+  writeFileSync(join(cwd, file), body);
+  git(cwd, `add ${file}`);
+  git(cwd, `-c user.email=t@t -c user.name=t commit -q -m "add ${file}"`);
+  return git(cwd, 'rev-parse HEAD');
+}
+
+const origin = join(root, 'origin.git');
+const repo = join(root, 'repo');
+execSync(`git init -q --bare -b main "${origin}"`, { stdio: 'ignore' });
+execSync(`git clone -q "${origin}" "${repo}"`, { stdio: 'ignore' });
+commit(repo, 'base.txt', 'base');
+git(repo, 'push -q -u origin main');
+
+// An unmerged branch — its tip must be REFUTED as a merged claim.
+git(repo, 'checkout -q -b feature');
+const unmergedSha = commit(repo, 'feat.txt', 'feat');
+git(repo, 'checkout -q main');
+
+// A genuinely merged lane — its post-merge sha must VERIFY.
+git(repo, 'checkout -q -b lane');
+commit(repo, 'lane.txt', 'lane');
+git(repo, 'checkout -q main');
+git(repo, 'merge -q --no-edit lane');
+const mergedSha = git(repo, 'rev-parse HEAD');
+git(repo, 'push -q origin main');
+
+// A repo git can't answer for: commits exist, but no origin and no main/master.
+const refless = join(root, 'refless');
+execSync(`git init -q -b trunk "${refless}"`, { stdio: 'ignore' });
+commit(refless, 'x.txt', 'x');
+
+function makeItem(overrides = {}) {
+  const { evidence, ...rest } = overrides;
+  return q.createItem({
+    project: 'test-proj',
+    project_path: repo,
+    category: 'qa-handoff',
+    title: 'QA handoff: lane merge',
+    summary: 'test',
+    context_anchor: `git show ${mergedSha.slice(0, 7)}`,
+    evidence: { merged_commit: mergedSha, ...(evidence || {}) },
+    ...rest,
+  });
+}
+
+// --- verifyMergedAncestry: the taxonomy ---
+
+test('verified: the post-merge sha is an ancestor of origin/main', () => {
+  assert.deepEqual(q.verifyMergedAncestry(repo, mergedSha), { state: 'verified', ref: 'origin/main' });
+});
+
+test('refuted: an unmerged branch tip is definitively not an ancestor', () => {
+  const v = q.verifyMergedAncestry(repo, unmergedSha);
+  assert.equal(v.state, 'refuted');
+});
+
+test("unverifiable: non-sha input, missing path, and a repo with no main ref — never 'refuted'", () => {
+  assert.equal(q.verifyMergedAncestry(repo, 'HEAD').state, 'unverifiable');          // ref name, not a sha
+  assert.equal(q.verifyMergedAncestry(repo, '--all').state, 'unverifiable');          // option injection shape
+  assert.equal(q.verifyMergedAncestry('/nope/never', mergedSha).state, 'unverifiable');
+  assert.equal(q.verifyMergedAncestry(refless, mergedSha).state, 'unverifiable');     // no origin, no main/master
+});
+
+// --- createItem: the merged arm ---
+
+test("a truly merged filing is accepted and stamped 'verified'", () => {
+  const id = makeItem();
+  assert.equal(q.getItem(id).evidence.ancestry_verified, 'verified');
+});
+
+test('a merged filing whose sha git refutes is REJECTED, teaching the fix', () => {
+  assert.throws(
+    () => makeItem({ evidence: { merged_commit: unmergedSha } }),
+    /NOT an ancestor.*did the push happen\?.*merge-pending.*merge_gate/s,
+  );
+});
+
+test('a merged filing with a non-sha merged_commit is rejected (option-injection closed)', () => {
+  for (const bad of ['HEAD', '--all', 'main', 'abc123g']) {
+    assert.throws(() => makeItem({ evidence: { merged_commit: bad } }), /sha-shaped/);
+  }
+});
+
+// --- markHandoffMerged: the one legal doorway, with deferred dispatch ---
+
+function makePending(overrides = {}) {
+  return makeItem({
+    desk: 'testdesk',
+    evidence: {
+      merge_state: 'merge-pending',
+      merged_commit: null,
+      pending_branch_head: unmergedSha,
+      merge_gate: 'staging deploy in flight — clears on SUCCESS',
+    },
+    ...overrides,
+  });
+}
+
+test('flip to merged: verifies ancestry, stamps evidence, writes the stage-2 descriptor', () => {
+  const id = makePending();
+  const out = q.markHandoffMerged(id, { merged_commit: mergedSha });
+  assert.equal(out.dispatch, 'dispatched');
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merge_state, 'merged');
+  assert.equal(ev.merged_commit, mergedSha);
+  assert.equal(ev.ancestry_verified, 'verified');
+  assert.equal(ev.stage2_dispatch.status, 'dispatched');
+  const desc = JSON.parse(readFileSync(join(muxQaRoot, 'testdesk', `${id}.json`), 'utf8'));
+  assert.equal(desc.item_id, id);
+  assert.equal(desc.project, 'testdesk');
+  assert.equal(desc.merged_commit, mergedSha);
+  assert.match(desc.pickup_prompt, /Post-merge QA/);
+  assert.match(desc.pickup_prompt, new RegExp(id));
+  // Second call is state-keyed idempotent: already dispatched → no re-write.
+  assert.equal(q.markHandoffMerged(id, { merged_commit: mergedSha }).dispatch, 'dispatched');
+});
+
+test('flip with a refuted sha throws and leaves the item unchanged on disk', () => {
+  const id = makePending();
+  assert.throws(() => q.markHandoffMerged(id, { merged_commit: unmergedSha }), /NOT an ancestor/);
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merge_state, 'merge-pending');
+  assert.ok(!('stage2_dispatch' in ev));
+});
+
+test('flip requires a sha-shaped merged_commit and a qa-handoff item', () => {
+  const id = makePending();
+  assert.throws(() => q.markHandoffMerged(id, {}), /sha-shaped/);
+  assert.throws(() => q.markHandoffMerged(id, { merged_commit: 'HEAD' }), /sha-shaped/);
+  const ke = q.createItem({
+    project: 'test-proj', project_path: repo, category: 'knowledge-extraction',
+    title: 'ke', summary: 's', context_anchor: 'c',
+  });
+  assert.throws(() => q.markHandoffMerged(ke, { merged_commit: mergedSha }), /not qa-handoff/);
+});
+
+test('no legal desk → flip lands, dispatch recorded no-desk, retried by state on re-call', () => {
+  for (const desk of [null, '../evil', 'a/b', '.hidden']) {
+    const id = makePending({ desk });
+    const out = q.markHandoffMerged(id, { merged_commit: mergedSha });
+    assert.equal(out.dispatch, 'no-desk', `desk ${JSON.stringify(desk)} must not route`);
+    assert.equal(q.getItem(id).evidence.stage2_dispatch.status, 'no-desk');
+    // Re-call retries the dispatch (state-keyed) rather than short-circuiting.
+    assert.equal(q.markHandoffMerged(id, { merged_commit: mergedSha }).dispatch, 'no-desk');
+  }
+  // Traversal check: nothing escaped the mux queue root.
+  assert.ok(!existsSync(join(root, 'evil')), 'no dir created outside MUX_QA_DIR');
+  const deskDirs = existsSync(muxQaRoot) ? readdirSync(muxQaRoot) : [];
+  assert.ok(!deskDirs.some((d) => d.includes('.') || d.includes('evil')), `illegal desk dirs: ${deskDirs}`);
+});
+
+test('the already-merged short-circuit refuses a DIFFERENT sha (no silent swallow)', () => {
+  const id = makePending();
+  q.markHandoffMerged(id, { merged_commit: mergedSha });
+  // Same sha → idempotent success; different sha → loud refusal, item intact.
+  assert.equal(q.markHandoffMerged(id, { merged_commit: mergedSha }).dispatch, 'dispatched');
+  const otherSha = 'a'.repeat(40);
+  assert.throws(() => q.markHandoffMerged(id, { merged_commit: otherSha }), /refusing to silently ignore/);
+  assert.equal(q.getItem(id).evidence.merged_commit, mergedSha);
+});
+
+test('a drained (in-flight) item is not double-offered', () => {
+  const id = makePending();
+  mkdirSync(join(muxQaRoot, 'testdesk', 'in-flight'), { recursive: true });
+  writeFileSync(join(muxQaRoot, 'testdesk', 'in-flight', `${id}.json`), '{}\n');
+  const out = q.markHandoffMerged(id, { merged_commit: mergedSha });
+  assert.equal(out.dispatch, 'already-in-flight');
+  assert.ok(!existsSync(join(muxQaRoot, 'testdesk', `${id}.json`)), 'no queued duplicate beside the in-flight copy');
+});
+
+test('createItem stores the trimmed sha it verified (stamp and value never disagree)', () => {
+  const id = makeItem({ evidence: { merged_commit: `${mergedSha} ` } });
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merged_commit, mergedSha);
+  assert.equal(ev.ancestry_verified, 'verified');
+});
+
+test('a failed dispatch is recoverable by state: flip lands, retry succeeds once unblocked', () => {
+  const id = makePending({ desk: 'blockeddesk' });
+  // Force ENOTDIR: a regular file where the desk DIR must go.
+  writeFileSync(join(muxQaRoot, 'blockeddesk'), 'not a dir');
+  const out = q.markHandoffMerged(id, { merged_commit: mergedSha });
+  assert.match(out.dispatch, /^failed: /);
+  assert.equal(q.getItem(id).evidence.merge_state, 'merged', 'the flip itself landed');
+  rmSync(join(muxQaRoot, 'blockeddesk'));
+  // State-keyed retry: status !== 'dispatched' → the re-call re-dispatches.
+  assert.equal(q.markHandoffMerged(id, { merged_commit: mergedSha }).dispatch, 'dispatched');
+  assert.ok(existsSync(join(muxQaRoot, 'blockeddesk', `${id}.json`)));
+});
+
+test('unverifiable flip through the doorway: flips, stamps, still dispatches', () => {
+  const id = makeItem({
+    desk: 'testdesk',
+    project_path: refless,
+    evidence: { merge_state: 'merge-pending', merged_commit: null, merge_gate: 'gated externally' },
+  });
+  const out = q.markHandoffMerged(id, { merged_commit: mergedSha });
+  assert.equal(out.dispatch, 'dispatched');
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merge_state, 'merged');
+  assert.equal(ev.ancestry_verified, 'unverifiable', 'git cannot answer in the refless repo — stamped, not blocked');
+});
+
+test('the amend path: a filed-merged item passes markHandoffMerged legally and re-dispatches', () => {
+  const id = makeItem({ desk: 'testdesk' });                    // merged by default, no stage2_dispatch
+  const out = q.markHandoffMerged(id, { merged_commit: mergedSha });
+  assert.equal(out.dispatch, 'dispatched');
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merge_state, 'merged', 'the defaulted state becomes explicit through the doorway');
+  assert.equal(ev.stage2_dispatch.status, 'dispatched');
+});
+
+test('the boundary mints the verification record: pre-planted stamps are discarded at createItem', () => {
+  // merge-pending arm: neither stamp survives.
+  const pendingId = makePending({
+    evidence: {
+      merge_state: 'merge-pending', merged_commit: null,
+      merge_gate: 'gated externally',
+      ancestry_verified: 'verified',                    // spoofed
+      stage2_dispatch: { status: 'dispatched' },        // spoofed
+    },
+  });
+  const pev = q.getItem(pendingId).evidence;
+  assert.ok(!('ancestry_verified' in pev), 'spoofed ancestry stamp discarded');
+  assert.ok(!('stage2_dispatch' in pev), 'spoofed dispatch status discarded');
+  // merged arm: the stamp present is the one the boundary just minted, and a
+  // pre-planted dispatched status cannot make the doorway short-circuit —
+  // markHandoffMerged verifies and dispatches for real.
+  const mergedId = makeItem({
+    desk: 'testdesk',
+    evidence: { merged_commit: mergedSha, stage2_dispatch: { status: 'dispatched' } },
+  });
+  const mev = q.getItem(mergedId).evidence;
+  assert.equal(mev.ancestry_verified, 'verified');
+  assert.ok(!('stage2_dispatch' in mev), 'pre-planted dispatch status discarded');
+  const out = q.markHandoffMerged(mergedId, { merged_commit: mergedSha });
+  assert.equal(out.dispatch, 'dispatched');
+  assert.ok(existsSync(join(muxQaRoot, 'testdesk', `${mergedId}.json`)), 'a real descriptor landed');
+});
+
+// --- the side door is closed ---
+
+test('annotateItemEvidence refuses the whole verification record on a qa-handoff', () => {
+  const id = makePending();
+  // merge_state, the verified sha, the ancestry stamp, and the dispatch
+  // status are all one record — any of them patchable would let a later
+  // markHandoffMerged short-circuit or a stamp be falsified.
+  for (const patch of [
+    { merge_state: 'merged' },
+    { merged_commit: mergedSha },
+    { ancestry_verified: 'verified' },
+    { stage2_dispatch: { status: 'dispatched' } },
+  ]) {
+    assert.throws(() => q.annotateItemEvidence(id, patch), /markHandoffMerged/);
+  }
+  assert.equal(q.getItem(id).evidence.merge_state, 'merge-pending');
+  // Other evidence keys on the same item still annotate (Ring 2's job).
+  const r = q.annotateItemEvidence(id, { freshness: { checked: true } });
+  assert.equal(r.changed, true);
+});
+
+test('the fence is category-scoped: merge_state annotates freely off qa-handoff', () => {
+  const ke = q.createItem({
+    project: 'test-proj', project_path: repo, category: 'knowledge-extraction',
+    title: 'ke2', summary: 's', context_anchor: 'c',
+  });
+  const r = q.annotateItemEvidence(ke, { merge_state: 'whatever' });
+  assert.equal(r.changed, true);
+});

package/templates/scripts/__tests__/resolve-cli.test.mjs

@@ -49,6 +49,7 @@ function runCli(args) {
 }
 
 function makeQaItem(overrides = {}) {
+  const { evidence, ...rest } = overrides;
   return q.createItem({
     project: 'test-proj',
     project_path: '/tmp/test-proj',
@@ -56,7 +57,11 @@ function makeQaItem(overrides = {}) {
     title: 'QA handoff: test merge',
     summary: 'test',
     context_anchor: 'git show abc1234',
-    ...overrides,
+    // merged-by-construction (act:3d1ac2b7): merged filings carry the sha;
+    // /tmp/test-proj is not a repo → 'unverifiable' stamp (this suite tests
+    // the resolve CLI, not the ancestry taxonomy).
+    evidence: { merged_commit: 'abc1234', ...(evidence || {}) },
+    ...rest,
   });
 }
 

package/templates/scripts/__tests__/routine-dispatch.test.mjs

@@ -305,6 +305,8 @@ test('qa-handoff gate untouched by the generalization (regression)', () => {
   const id = q.createItem({
     project: 'proj-a', project_path: projectPath, category: 'qa-handoff',
     title: 'QA handoff: t', summary: 's', context_anchor: 'git show abc',
+    // merged-by-construction (act:3d1ac2b7): qa-handoff filings carry the sha.
+    evidence: { merged_commit: 'abc1234' },
   });
   assert.throws(() => q.resolveItem(id, { resolution: 'done' }), /qa_verdict/);
   assert.throws(() => q.expireItem(id), /never expire/);

package/templates/scripts/__tests__/session-ack.test.mjs

@@ -0,0 +1,61 @@
+// Hermetic tests for the session-start acknowledgment directive
+// (act:058d00f0): the pure renderer, and an end-to-end subprocess run of the
+// builder asserting the directive actually renders (built-but-never-fired
+// guard) and renders FIRST, above the summary block.
+//
+// The subprocess run is hermetic: WATCHTOWER_DIR and HOME point at temp
+// dirs, so no real state, registry, or ~/.claude.json is read and the
+// advisory pass has nothing to probe.
+
+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';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const bctx = await import('../watchtower-build-context.mjs');
+const SCRIPT = fileURLToPath(new URL('../watchtower-build-context.mjs', import.meta.url));
+
+test('renderSessionAckSection: plain-English contract, bounded size', () => {
+  const out = bctx.renderSessionAckSection();
+  assert.match(out, /^--- Session-Start Acknowledgment ---\n/);
+  assert.match(out, /first reply/i);
+  assert.match(out, /ONE plain-English line/);
+  // Ordering contract with the shell hook's prepended frontier warning.
+  assert.match(out, /frontier-model warning/i);
+  // Re-injection carve-out: no mid-conversation acknowledgment on resume.
+  assert.match(out, /resume/i);
+  // Never-truncated sections eat the fixed budget for everything else —
+  // keep the directive small.
+  assert.ok(out.length < 1000, `ack directive too large: ${out.length} chars`);
+});
+
+test('builder output opens with the ack directive, then the state summary', () => {
+  const wt = mkdtempSync(join(tmpdir(), 'wt-ack-'));
+  const home = mkdtempSync(join(tmpdir(), 'wt-ack-home-'));
+  const project = mkdtempSync(join(tmpdir(), 'wt-ack-proj-'));
+  try {
+    mkdirSync(join(wt, 'state'), { recursive: true });
+    writeFileSync(join(wt, 'config.json'), JSON.stringify({ projects: {} }));
+    writeFileSync(join(wt, 'state', 'summary.md'), '# Watchtower — test\n\nAll quiet.\n');
+
+    const out = execFileSync(process.execPath, [SCRIPT, '--project-path', project], {
+      encoding: 'utf8',
+      env: { ...process.env, WATCHTOWER_DIR: wt, HOME: home },
+      timeout: 30_000,
+    });
+
+    assert.ok(
+      out.startsWith('--- Session-Start Acknowledgment ---'),
+      `output does not open with the ack directive:\n${out.slice(0, 200)}`
+    );
+    const stateIdx = out.indexOf('--- Watchtower State ---');
+    assert.ok(stateIdx > 0, 'summary block missing from builder output');
+  } finally {
+    rmSync(wt, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  }
+});

package/templates/scripts/watchtower-build-context.mjs

@@ -31,7 +31,7 @@ const PROJECT_STALENESS_DAYS = 7;
 // `assembleSections` removes whole sections (never trims within one) in
 // descending priority order until the output fits MAX_OUTPUT_CHARS;
 // PRIORITY_NEVER is never dropped.
-const PRIORITY_NEVER = 0;    // summary + missed-routine directive — always kept
+const PRIORITY_NEVER = 0;    // ack directive + summary + missed-routine directive — always kept
 const PRIORITY_KEEP = 1;     // threads, inbox, advisories — try hard to keep
 const PRIORITY_PROJECT = 2;  // per-project state
 const PRIORITY_DOMAIN = 3;   // injected domain files
@@ -377,6 +377,22 @@ function isMainCheckout(projectPath) {
 // Render the run-first directive for pending routine items, or null when there
 // are none. qa-handoff items never reach here — the caller filters to
 // category 'routine'. Caps the inline list at 3; the rest stay in the inbox.
+// --- Session-start acknowledgment directive (act:058d00f0) ---
+//
+// The injection is invisible in the terminal, so a healthy quiet session is
+// indistinguishable from a silently broken hook. This never-truncated
+// directive tells the session to open its first reply with one visible
+// plain-English line composed from the injected state — positive
+// confirmation the context loaded (no-silent-failures), replacing the
+// signal orient's briefing used to give. Prompt-layer convention only:
+// nothing is blocked if the line is skipped.
+function renderSessionAckSection() {
+  return [
+    '--- Session-Start Acknowledgment ---',
+    'Open your first reply of this session with ONE plain-English line confirming this watchtower context loaded: where the operator left off, what needs attention in this project, and the inbox count — e.g. "Watchtower: picked up where you left off (merged the auth fix to main, 2h ago); 1 flagged action here; inbox 12 pending." If the state below carries a staleness or health warning, lead with that warning instead. A frontier-model warning above this block stays first. One line, then proceed with the operator\'s request. Skip it if the conversation already has replies (context re-injected on resume).',
+  ].join('\n');
+}
+
 function renderMissedRoutineSection(pendingItems, projectName, projectPath) {
   if (!Array.isArray(pendingItems) || pendingItems.length === 0) return null;
   const n = pendingItems.length;
@@ -425,6 +441,12 @@ function main() {
 
   const sections = [];
 
+  // Step 1b: Session-start acknowledgment directive — rendered first so the
+  // visible-confirmation contract sits at the top of the injection
+  // (act:058d00f0). The shell hook prepends any frontier-model warning above
+  // the builder output, so that warning still comes first overall.
+  sections.push({ key: 'session-ack', content: renderSessionAckSection(), priority: PRIORITY_NEVER });
+
   // Step 2: Read state/summary.md
   const summaryPath = join(WATCHTOWER_DIR, 'state', 'summary.md');
   const summaryContent = safeReadFile(summaryPath);
@@ -618,7 +640,7 @@ function assembleSections(sections) {
 
 // Exports for hermetic tests (act:a136b362). Importing this module must NOT
 // run main() — gate the entry on an argv/url match (matches the ring scripts).
-export { reverifyGitAttention, verifyGitFact, renderMissedRoutineSection, isMainCheckout };
+export { reverifyGitAttention, verifyGitFact, renderMissedRoutineSection, renderSessionAckSection, isMainCheckout };
 
 const isMain = (() => {
   try {