create-claude-cabinet 0.49.0 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/CLAUDE.md

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

package/templates/cabinet/worktree-invocation-contract.md

@@ -132,15 +132,22 @@ either way). Recovery: `git update-index --no-skip-worktree .mcp.json
 && git checkout -- .mcp.json && git merge main`; the next health run
 re-symlinks and re-hides.
 
-## What this contract does NOT cover
+## Who merges (universal), and what stays caller-specific
 
-Caller-specific orchestration stays in the caller's own Step 0, never
-here:
+The universal rule every caller shares (act:3d1ac2b7): **finished worktree
+work is MERGED by its producer** — a close-out or handoff describes work
+already on main, and `merge_state: "merge-pending"` exists only for a
+merge explicitly gated on something external, named in
+`evidence.merge_gate`.
+
+The merge ORCHESTRATION is caller-specific and stays inline in each
+caller's own skill, never here:
 
 - **`/execute-group`** keeps inline: that its `isolation: worktree`
-  agents branch from and merge into MAIN regardless of the invoking cwd,
-  and its inline-build escape hatch. These describe the workflow's merge
-  model and would contradict `/execute`'s no-merge model — they are not
-  universal.
-- **`/execute`** keeps inline: that it does NOT merge (the worktree→main
-  bridge is `/qa-handoff`), and how its close-out files the handoff.
+  agents branch from and merge into MAIN regardless of the invoking cwd
+  (sequential, baseline-gated merges owned by the workflow), and its
+  inline-build escape hatch.
+- **`/execute`** keeps inline: its merge-first close-out — Step 8
+  delegates the merge to `/qa-handoff`'s merge-now recipe, then files a
+  `merged` handoff that dispatches; every merge failure HALTs, never
+  silently downgraded to merge-pending.

package/templates/engagement/__tests__/transport-token.test.mjs

@@ -0,0 +1,103 @@
+// Unit tests for the transport token pre-flight (act:8b527625).
+// Run: node --test templates/engagement/__tests__/transport-token.test.mjs
+// Guards the structural fix for the silent-failure-on-missing-token path:
+// checkToken never throws and returns actionable guidance; resolveToken's
+// throw carries the same guidance (the backstop when pre-flight is skipped).
+
+import { test } from 'node:test';
+import assert from 'node:assert';
+import {
+  checkToken,
+  resolveToken,
+  missingTokenGuidance,
+} from '../engagement-transport.mjs';
+
+const VAR = 'CC_TEST_ENGAGEMENT_TOKEN_UNSET';
+
+test('checkToken: unset env var → ok false with actionable message', () => {
+  delete process.env[VAR];
+  const r = checkToken({ token: `env:${VAR}` });
+  assert.strictEqual(r.ok, false);
+  assert.strictEqual(r.varName, VAR);
+  assert.match(r.message, new RegExp(`${VAR} is not set`));
+  assert.match(r.message, /export CC_TEST_ENGAGEMENT_TOKEN_UNSET=/, 'message names the export line');
+  assert.match(r.message, /API Tokens/, 'message says where to get the key');
+  assert.match(r.message, /Restart your terminal/, 'message says to restart the shell');
+});
+
+test('checkToken: set env var → ok true', () => {
+  process.env[VAR] = 'tok-123';
+  try {
+    assert.deepStrictEqual(checkToken({ token: `env:${VAR}` }), { ok: true });
+  } finally {
+    delete process.env[VAR];
+  }
+});
+
+test('checkToken: empty-string env var counts as unset', () => {
+  process.env[VAR] = '';
+  try {
+    const r = checkToken({ token: `env:${VAR}` });
+    assert.strictEqual(r.ok, false);
+    assert.strictEqual(r.varName, VAR);
+  } finally {
+    delete process.env[VAR];
+  }
+});
+
+test('checkToken: literal token → ok true', () => {
+  assert.deepStrictEqual(checkToken({ token: 'literal-token' }), { ok: true });
+});
+
+test('checkToken: no token configured → ok false, varName null, names transport.token', () => {
+  for (const cfg of [{}, { token: '' }, null, undefined]) {
+    const r = checkToken(cfg);
+    assert.strictEqual(r.ok, false);
+    assert.strictEqual(r.varName, null);
+    assert.match(r.message, /transport\.token/);
+  }
+});
+
+test('checkToken never throws', () => {
+  for (const cfg of [undefined, null, {}, { token: 42 && 'env:' }, { token: 'env:' }]) {
+    assert.doesNotThrow(() => checkToken(cfg));
+  }
+});
+
+test('resolveToken: unset env var throws WITH the guidance, not the bare error', () => {
+  delete process.env[VAR];
+  assert.throws(
+    () => resolveToken(`env:${VAR}`),
+    (err) => {
+      assert.match(err.message, new RegExp(`${VAR} is not set`));
+      assert.match(err.message, /export CC_TEST_ENGAGEMENT_TOKEN_UNSET=/);
+      assert.match(err.message, /API Tokens/);
+      return true;
+    },
+  );
+});
+
+test('resolveToken: set env var resolves; literal passes through; falsy → null', () => {
+  process.env[VAR] = 'tok-456';
+  try {
+    assert.strictEqual(resolveToken(`env:${VAR}`), 'tok-456');
+  } finally {
+    delete process.env[VAR];
+  }
+  assert.strictEqual(resolveToken('literal'), 'literal');
+  assert.strictEqual(resolveToken(''), null);
+  assert.strictEqual(resolveToken(null), null);
+});
+
+test('missingTokenGuidance is the single source both paths share', () => {
+  delete process.env[VAR];
+  const fromCheck = checkToken({ token: `env:${VAR}` }).message;
+  let fromThrow;
+  try {
+    resolveToken(`env:${VAR}`);
+  } catch (err) {
+    fromThrow = err.message;
+  }
+  assert.strictEqual(fromCheck, missingTokenGuidance(VAR));
+  assert.strictEqual(fromThrow, missingTokenGuidance(VAR));
+});

package/templates/engagement/engagement-transport.mjs

@@ -5,12 +5,46 @@ import { join } from 'node:path';
 // Token resolution — env:VAR_NAME or literal
 // ---------------------------------------------------------------------------
 
+export function missingTokenGuidance(varName) {
+  return (
+    `${varName} is not set — the engagement API needs this token to reach the server.\n` +
+    `1. Get your API key: it's the same key you use for the admin tools\n` +
+    `   (platform admin panel → API Tokens). If you don't have one, ask your\n` +
+    `   consultant or admin to create one for you.\n` +
+    `2. Add it to your shell profile:\n` +
+    `   echo 'export ${varName}=your-key-here' >> ~/.zshenv\n` +
+    `3. Restart your terminal (or run: source ~/.zshenv), then try again.`
+  );
+}
+
+// Never throws — the mechanical pre-flight check for the /collab-* skills.
+// { ok: true } when a token resolves; { ok: false, varName, message } when
+// the env var backing an env: ref is unset; { ok: false, varName: null,
+// message } when no token is configured at all.
+export function checkToken(transportConfig) {
+  const tokenRef = transportConfig?.token;
+  if (!tokenRef) {
+    return {
+      ok: false,
+      varName: null,
+      message: 'No API token configured — set transport.token in the engagement config (e.g. "env:ENGAGEMENT_API_TOKEN").',
+    };
+  }
+  if (tokenRef.startsWith('env:')) {
+    const varName = tokenRef.slice(4);
+    if (!process.env[varName]) {
+      return { ok: false, varName, message: missingTokenGuidance(varName) };
+    }
+  }
+  return { ok: true };
+}
+
 export function resolveToken(tokenRef) {
   if (!tokenRef) return null;
   if (tokenRef.startsWith('env:')) {
     const varName = tokenRef.slice(4);
     const value = process.env[varName];
-    if (!value) throw new Error(`Environment variable ${varName} is not set (from token ref "${tokenRef}")`);
+    if (!value) throw new Error(missingTokenGuidance(varName));
     return value;
   }
   return tokenRef;

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

@@ -51,7 +51,8 @@ test('GATED_CATEGORIES is exported and contains 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' });
+  // merged-by-construction (act:3d1ac2b7): qa-handoff filings carry the sha.
+  const gatedId = makeItem({ category: 'qa-handoff', title: 'QA handoff: merge x', evidence: { merged_commit: 'abc1234' } });
   assert.throws(
     () => q.applyBatch([plain, gatedId], { disposition: 'dismiss', ...TYPED }),
     (err) => err.message.includes(gatedId) && err.message.includes('recipient gate'),

package/templates/scripts/__tests__/qa-handoff-aging.e2e.test.mjs

@@ -50,6 +50,9 @@ function makeItem(category, title, agedDays) {
     title,
     summary: 'aging e2e fixture',
     context_anchor: 'git show abc1234',
+    // merged-by-construction (act:3d1ac2b7): qa-handoff filings carry the sha
+    // (harmless extra evidence for the non-qa control categories).
+    evidence: { merged_commit: 'abc1234' },
   });
   if (agedDays > 0) {
     const j = readBack(id);

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

@@ -32,7 +32,13 @@ test.after(() => rmSync(root, { recursive: true, force: true }));
 
 const itemFile = (id) => join(root, 'queue', 'items', `${id}.json`);
 
+// The default fixture is a 'merged' handoff, which requires a sha-shaped
+// evidence.merged_commit at the boundary (act:3d1ac2b7 merged-by-construction).
+// /tmp/test-proj is not on disk, so the ancestry check stamps 'unverifiable'
+// and files — the taxonomy itself is exercised against real git repos in
+// qa-handoff-merged-by-construction.test.mjs.
 function makeItem(overrides = {}) {
+  const { evidence, ...rest } = overrides;
   return q.createItem({
     project: 'test-proj',
     project_path: '/tmp/test-proj',
@@ -40,7 +46,8 @@ function makeItem(overrides = {}) {
     title: 'QA handoff: test merge',
     summary: 'test',
     context_anchor: 'git show abc1234',
-    ...overrides,
+    evidence: { merged_commit: 'abc1234', ...(evidence || {}) },
+    ...rest,
   });
 }
 

package/templates/scripts/__tests__/qa-handoff-merge-state.test.mjs

@@ -1,10 +1,15 @@
-// qa-handoff merge_state — schema + create-time guard on the queue lib.
+// qa-handoff merge_state — schema + create-time guards on the queue lib.
 // A handoff filed BEFORE the worktree branch merged carries
 // merge_state: "merge-pending"; the default (absent) is "merged". The queue
 // API canonicalizes a legal token, rejects a present-but-illegal one at the
 // boundary (a typo cannot silently read as "merged"), and never loosens the
-// recipient gate. The skill (SKILL.md) owns the dispatch/pickup-prompt
-// behavior; this file pins the data contract those decisions key off.
+// recipient gate. Since act:3d1ac2b7 (merged-by-construction) the boundary
+// also requires: a sha-shaped merged_commit on every 'merged' handoff
+// (ancestry-verified where git can answer — the real-git taxonomy lives in
+// qa-handoff-merged-by-construction.test.mjs), and a named external blocker
+// (evidence.merge_gate) on every 'merge-pending' handoff — the silent
+// merge-pending default is retired. The skill (SKILL.md) owns the
+// dispatch/pickup-prompt behavior; this file pins the data contract.
 //
 // 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 at
@@ -47,6 +52,9 @@ function validVerdict(overrides = {}) {
   };
 }
 
+// Every merge-pending filing needs a named external blocker (act:3d1ac2b7).
+const GATE = 'staging deploy dpl_123 in flight — clears on deploy SUCCESS';
+
 // --- normalizeMergeState: the single token normalizer ---
 
 test('absent (null/undefined) defaults to "merged" — the original contract', () => {
@@ -78,22 +86,42 @@ test('QA_MERGE_STATES export names exactly the two legal states', () => {
 // --- createItem: structural guard, qa-handoff only, additive ---
 
 test('legal merge_state is stored canonically on the qa-handoff item', () => {
-  const id = makeItem({ evidence: { merge_state: 'merge-pending', pending_branch_head: 'deadbee' } });
+  const id = makeItem({ evidence: { merge_state: 'merge-pending', pending_branch_head: 'deadbee', merge_gate: GATE } });
   const item = q.getItem(id);
   assert.equal(item.evidence.merge_state, 'merge-pending');
   assert.equal(item.evidence.pending_branch_head, 'deadbee');
 });
 
 test('a drift token is canonicalized at file time', () => {
-  const id = makeItem({ evidence: { merge_state: 'merge_pending' } });
+  const id = makeItem({ evidence: { merge_state: 'merge_pending', merge_gate: GATE } });
   assert.equal(q.getItem(id).evidence.merge_state, 'merge-pending');
 });
 
 test('absent merge_state is NOT injected (additive-field discipline; reader defaults)', () => {
-  const id = makeItem({ evidence: { foo: 'bar' } });
+  const id = makeItem({ evidence: { foo: 'bar', merged_commit: 'abc1234' } });
   const ev = q.getItem(id).evidence;
   assert.ok(!('merge_state' in ev), 'no merge_state key written when none was passed');
   assert.equal(q.normalizeMergeState(ev.merge_state), 'merged', 'reader treats absent as merged');
+  assert.equal(ev.ancestry_verified, 'unverifiable', 'defaulted-merged is still ancestry-stamped');
+});
+
+test("a 'merged' handoff without merged_commit is rejected (omission was the trivial bypass)", () => {
+  assert.throws(
+    () => makeItem({ evidence: { merged_into: 'main' } }),
+    /requires a sha-shaped evidence\.merged_commit/,
+  );
+});
+
+test('merge-pending without a named merge_gate is rejected (the silent default is retired)', () => {
+  assert.throws(
+    () => makeItem({ evidence: { merge_state: 'merge-pending', pending_branch_head: 'deadbee' } }),
+    /requires evidence\.merge_gate/,
+  );
+  // The rejection teaches the merge-first close-out, not just the field name.
+  assert.throws(
+    () => makeItem({ evidence: { merge_state: 'merge-pending' } }),
+    /merge-first|merge → push/,
+  );
 });
 
 test('an illegal merge_state is rejected at create time, naming the field + legal set', () => {
@@ -124,16 +152,24 @@ test("a 'merged' handoff with merged_commit: 'PENDING' is rejected", () => {
   );
 });
 
-test("merge-pending is the legitimate filed-before-merge path — not rejected", () => {
-  // The honest way to say 'work done, not yet merged'. merged_into stays the
-  // target 'main'; merge_state carries the not-yet-ness.
-  const id = makeItem({ evidence: { merge_state: 'merge-pending', merged_into: 'main', merged_commit: null, pending_branch_head: 'deadbee' } });
-  assert.equal(q.getItem(id).evidence.merge_state, 'merge-pending');
+test("merge-pending with a named gate is the legitimate gated-merge path — not rejected", () => {
+  // The honest way to say 'work done, merge genuinely blocked'. merged_into
+  // stays the target 'main'; merge_state carries the not-yet-ness; merge_gate
+  // names WHY (act:3d1ac2b7 — gateless merge-pending is rejected above).
+  const id = makeItem({ evidence: { merge_state: 'merge-pending', merged_into: 'main', merged_commit: null, pending_branch_head: 'deadbee', merge_gate: GATE } });
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merge_state, 'merge-pending');
+  assert.equal(ev.merge_gate, GATE);
 });
 
-test("a genuine 'merged' handoff (merged_into: 'main', real sha) passes", () => {
+test("a genuine 'merged' handoff (merged_into: 'main', real sha) passes, ancestry-stamped", () => {
   const id = makeItem({ evidence: { merged_into: 'main', merged_commit: 'abc1234' } });
-  assert.equal(q.getItem(id).evidence.merged_commit, 'abc1234');
+  const ev = q.getItem(id).evidence;
+  assert.equal(ev.merged_commit, 'abc1234');
+  // /tmp/test-proj is not a repo — git can't answer, so the stamp says so
+  // (the verified/refuted arms run against real repos in the
+  // merged-by-construction suite).
+  assert.equal(ev.ancestry_verified, 'unverifiable');
 });
 
 test('the merge-coherence guard is fenced to qa-handoff', () => {
@@ -144,19 +180,32 @@ test('the merge-coherence guard is fenced to qa-handoff', () => {
 
 // --- The merge state never loosens the recipient gate ---
 
-test('a merge-pending handoff still resolves only through a stamped qa_verdict', () => {
-  const pendingId = makeItem({ evidence: { merge_state: 'merge-pending' } });
-  // No verdict → still rejected; merge_state grants no bypass.
-  assert.throws(() => q.resolveItem(pendingId, { resolution: 'done' }), /qa_verdict/);
+test('a merge-pending handoff cannot resolve at all — the flip doorway comes first', () => {
+  const pendingId = makeItem({ evidence: { merge_state: 'merge-pending', merge_gate: GATE } });
+  // Even a fully valid verdict is rejected while merge-pending: resolution
+  // asserts QA of MERGED work, and the merge was never recorded
+  // (act:3d1ac2b7 — the widest bypass around markHandoffMerged).
+  assert.throws(
+    () => q.resolveItem(pendingId, { resolution: 'qa complete', qa_verdict: validVerdict() }),
+    /merge-pending.*markHandoffMerged/s,
+  );
   assert.equal(q.getItem(pendingId).status, 'pending');
-  // With a valid (post-merge) verdict → resolves; merge_state is preserved.
+  // After the guarded flip (fake repo → 'unverifiable' stamp, still flips),
+  // the same verdict resolves; the record shows the verified-or-stamped merge.
+  q.markHandoffMerged(pendingId, { merged_commit: 'abc1234' });
   const out = q.resolveItem(pendingId, { resolution: 'qa complete', qa_verdict: validVerdict() });
   assert.equal(out.status, 'resolved');
-  assert.equal(out.evidence.merge_state, 'merge-pending');
+  assert.equal(out.evidence.merge_state, 'merged');
   assert.equal(out.qa_verdict.verdict, 'runtime-verified');
 });
 
+test('dismissal stays legal for a merge-pending handoff (audited escape hatch)', () => {
+  const pendingId = makeItem({ evidence: { merge_state: 'merge-pending', merge_gate: GATE } });
+  const out = q.dismissItem(pendingId, { notes: 'lane abandoned — work superseded', resolution_type: 'noise' });
+  assert.equal(out.status, 'dismissed');
+});
+
 test('merge_state survives the disk round-trip', () => {
-  const id = makeItem({ evidence: { merge_state: 'merge-pending' } });
+  const id = makeItem({ evidence: { merge_state: 'merge-pending', merge_gate: GATE } });
   assert.equal(q.getItem(id).evidence.merge_state, 'merge-pending'); // readItem throws on schema drift
 });