@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/src/claude/hooks/__tests__/precompact.test.js

@@ -0,0 +1,158 @@
+'use strict';
+
+// Behavioral tests for precompact.cjs and the compact-restart readback in
+// session.cjs. Both hooks run as real subprocesses against a temporary git
+// fixture; the capture is asserted from the file it writes and from what the
+// next session actually prints.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PRECOMPACT = path.join(__dirname, '..', 'precompact.cjs');
+const SESSION = path.join(__dirname, '..', 'session.cjs');
+const { hookStateDir } = require(path.join(__dirname, '..', 'lib', 'hook-state-dir.cjs'));
+const RECOVERY = path.join(hookStateDir(), 'compact-recovery.json');
+
+function fixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-precompact-'));
+  for (const args of [
+    ['init', '-q', '-b', 'work'],
+    ['config', 'user.email', 'cafekit@example.invalid'],
+    ['config', 'user.name', 'CafeKit Test'],
+  ]) {
+    const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+  }
+  fs.writeFileSync(path.join(dir, 'tracked.txt'), 'one\n');
+  for (const args of [['add', '-A'], ['commit', '-qm', 'fixture']]) {
+    const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+  }
+  return dir;
+}
+
+function run(hook, dir, payload) {
+  const result = spawnSync(process.execPath, [hook], {
+    cwd: dir,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_PROJECT_DIR: dir },
+  });
+  return { code: result.status, stdout: result.stdout || '', stderr: result.stderr || '' };
+}
+
+function clearCapture() {
+  try { fs.unlinkSync(RECOVERY); } catch { /* absent */ }
+}
+
+function readCapture() {
+  return JSON.parse(fs.readFileSync(RECOVERY, 'utf8'));
+}
+
+test('PreCompact records branch, HEAD, dirty count and the in-flight task', () => {
+  const dir = fixture();
+  try {
+    fs.writeFileSync(path.join(dir, 'tracked.txt'), 'two\n');
+    fs.writeFileSync(path.join(dir, 'untracked.txt'), 'scratch\n');
+    const featureDir = path.join(dir, 'specs', 'demo');
+    fs.mkdirSync(featureDir, { recursive: true });
+    fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\nSpecs-Contract: process-first-ready-v1\n');
+    for (const [name, status] of [['task-01-one.md', 'in_progress'], ['task-02-two.md', 'pending']]) {
+      fs.writeFileSync(path.join(featureDir, name), [
+        `# ${name}`, '', `Status: ${status}`, '',
+        '## Dependencies', '', '- none', '',
+        '## Verification Plan', '', '- Command: node --test', '',
+      ].join('\n'));
+    }
+
+    clearCapture();
+    const result = run(PRECOMPACT, dir, { hook_event_name: 'PreCompact', trigger: 'auto', session_id: 'compact-session', cwd: dir });
+    assert.strictEqual(result.code, 0, result.stderr);
+
+    const record = readCapture();
+    assert.strictEqual(record.branch, 'work');
+    assert.match(record.head, /^[0-9a-f]{7,}$/);
+    assert.strictEqual(record.dirty_count, 3, 'one modified file, one untracked file, one untracked specs directory');
+    assert.strictEqual(record.trigger, 'auto');
+    assert.strictEqual(record.session_id, 'compact-session');
+    assert.strictEqual(record.workflow.feature, 'demo');
+    assert.deepStrictEqual(record.workflow.in_progress, ['task-01-one.md']);
+    assert.strictEqual(record.workflow.counts.in_progress, 1);
+    assert.strictEqual(record.workflow.counts.pending, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+    clearCapture();
+  }
+});
+
+test('a compact restart prints the captured anchors alongside the authorization warning', () => {
+  const dir = fixture();
+  try {
+    clearCapture();
+    assert.strictEqual(run(PRECOMPACT, dir, { hook_event_name: 'PreCompact', trigger: 'manual', cwd: dir }).code, 0);
+    const restart = run(SESSION, dir, { hook_event_name: 'SessionStart', source: 'compact', cwd: dir });
+    assert.strictEqual(restart.code, 0, restart.stderr);
+    assert.match(restart.stdout, /VERIFY PENDING AUTHORIZATIONS/, 'the existing warning must survive');
+    assert.match(restart.stdout, /State before compaction/);
+    assert.match(restart.stdout, /branch work/);
+    assert.match(restart.stdout, /Re-read these from disk before acting/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+    clearCapture();
+  }
+});
+
+test('a compact restart without a capture still prints the warning and nothing invented', () => {
+  const dir = fixture();
+  try {
+    clearCapture();
+    const restart = run(SESSION, dir, { hook_event_name: 'SessionStart', source: 'compact', cwd: dir });
+    assert.strictEqual(restart.code, 0, restart.stderr);
+    assert.match(restart.stdout, /VERIFY PENDING AUTHORIZATIONS/);
+    assert.doesNotMatch(restart.stdout, /State before compaction/, 'no capture means no claim about prior state');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('a normal session start prints no compaction anchors', () => {
+  const dir = fixture();
+  try {
+    clearCapture();
+    assert.strictEqual(run(PRECOMPACT, dir, { hook_event_name: 'PreCompact', cwd: dir }).code, 0);
+    const startup = run(SESSION, dir, { hook_event_name: 'SessionStart', source: 'startup', cwd: dir });
+    assert.strictEqual(startup.code, 0, startup.stderr);
+    assert.doesNotMatch(startup.stdout, /State before compaction/);
+    assert.doesNotMatch(startup.stdout, /VERIFY PENDING AUTHORIZATIONS/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+    clearCapture();
+  }
+});
+
+test('PreCompact fails open outside a repository and on malformed input', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-precompact-bare-'));
+  try {
+    clearCapture();
+    const noGit = run(PRECOMPACT, dir, { hook_event_name: 'PreCompact', cwd: dir });
+    assert.strictEqual(noGit.code, 0, 'a directory outside git must not fail the hook');
+    const record = readCapture();
+    assert.strictEqual(record.branch, null, 'unavailable git facts are recorded as null, never guessed');
+    assert.strictEqual(record.head, null);
+    assert.strictEqual(record.workflow, null);
+
+    clearCapture();
+    const malformed = spawnSync(process.execPath, [PRECOMPACT], {
+      cwd: dir, input: 'not json', encoding: 'utf8', env: { ...process.env, CLAUDE_PROJECT_DIR: dir },
+    });
+    assert.strictEqual(malformed.status, 0, 'malformed payload must fail open');
+    assert.strictEqual(fs.existsSync(RECOVERY), false, 'a malformed payload writes no capture');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+    clearCapture();
+  }
+});

package/src/claude/hooks/__tests__/semantic-review-authority.test.js

@@ -30,6 +30,8 @@ function installSemanticRuntime(target, runtime) {
   for (const name of ['semantic-review-authority.cjs', 'completion-authority-state.cjs']) {
     fs.copyFileSync(path.join(PACKAGE_ROOT, `src/${runtime}/hooks`, name), path.join(hooks, name));
   }
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/runtime-dir.cjs'), path.join(hooks, 'lib/runtime-dir.cjs'));
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/hook-payload.cjs'), path.join(hooks, 'lib/hook-payload.cjs'));
   fs.copyFileSync(
     path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/runtime-path-safety.cjs'),
     path.join(hooks, 'lib/runtime-path-safety.cjs'),

package/src/claude/hooks/__tests__/spec-gate.test.js

@@ -2,8 +2,9 @@
 
 // Behavioral tests for spec-gate.cjs (Stop completion gate). The hook is run as
 // a real subprocess: a Stop payload is piped to stdin; we assert exit code and
-// whether stdout carries {"decision":"block",...}. Cache lives under the hook's
-// own .logs/ dir (shared), so each test seeds/clears it deliberately.
+// whether stdout carries {"decision":"block",...}. The hook resolves its own
+// state directory; running from source that is a temp directory rather than the
+// source tree, and it is shared, so each test seeds/clears it deliberately.
 
 const { test, beforeEach, after } = require('node:test');
 const assert = require('node:assert');
@@ -14,7 +15,8 @@ const os = require('node:os');
 const path = require('node:path');
 
 const HOOK = path.join(__dirname, '..', 'spec-gate.cjs');
-const CACHE = path.join(__dirname, '..', '.logs', 'spec-gate-last.json');
+const { hookStateDir } = require(path.join(__dirname, '..', 'lib', 'hook-state-dir.cjs'));
+const CACHE = path.join(hookStateDir(), 'spec-gate-last.json');
 const PROVENANCE = require(path.join(__dirname, '..', '..', 'scripts', 'provenance.cjs'));
 const POLICY = require(path.join(__dirname, '..', '..', 'scripts', 'workflow-policy.cjs'));
 const FEATURE = 'demo';
@@ -286,6 +288,13 @@ function installClaudeGate(root, policyMode = 'valid') {
   fs.mkdirSync(hooks, { recursive: true });
   fs.mkdirSync(scripts, { recursive: true });
   fs.copyFileSync(HOOK, path.join(hooks, 'spec-gate.cjs'));
+  fs.mkdirSync(path.join(hooks, 'lib'), { recursive: true });
+  fs.copyFileSync(path.join(__dirname, '..', 'lib', 'runtime-dir.cjs'), path.join(hooks, 'lib', 'runtime-dir.cjs'));
+  fs.copyFileSync(path.join(__dirname, '..', 'lib', 'hook-payload.cjs'), path.join(hooks, 'lib', 'hook-payload.cjs'));
+  fs.copyFileSync(
+    path.join(__dirname, '..', 'lib', 'hook-state-dir.cjs'),
+    path.join(hooks, 'lib', 'hook-state-dir.cjs'),
+  );
   for (const name of [
     'completion-authority-check.cjs', 'completion-authority-state.cjs', 'semantic-review-authority.cjs',
   ]) fs.copyFileSync(path.join(__dirname, '..', name), path.join(hooks, name));
@@ -1479,3 +1488,339 @@ test('36. process-v3 Stop accepts two completed packets with valid Receipts', ()
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// ── Receipt freshness: bound while written or altered, structure-only once committed on a clean tree ──
+
+const STALE_BASE = 'f'.repeat(40);
+const STALE_HEAD = 'e'.repeat(40);
+
+function commitAll(dir, message) {
+  for (const args of [['add', '-A'], ['commit', '-qm', message, '--allow-empty']]) {
+    const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+  }
+}
+
+function boundReceipt(base = VALID_BASE, head = VALID_HEAD) {
+  return [
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${base}`, `Head: ${head}`, '```text', '$ node --test', 'pass: 1', '```',
+  ];
+}
+
+function runHookFrom(dir, cwd) {
+  const res = spawnSync(process.execPath, [HOOK], {
+    cwd,
+    input: JSON.stringify({ hook_event_name: 'Stop', session_id: 'test', transcript_path: '/tmp/t', stop_hook_active: false, cwd: dir }),
+    encoding: 'utf8',
+    env: { ...process.env, PROJECT_ROOT: dir },
+  });
+  return { code: res.status, stdout: (res.stdout || '').trim(), stderr: res.stderr || '' };
+}
+
+test('37. committed receipt on a clean tree survives later commits', () => {
+  const dir = makeWorkflowFixture(boundReceipt());
+  try {
+    commitAll(dir, 'receipt');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'unrelated.txt'), 'later change\n');
+    commitAll(dir, 'unrelated source change');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '', 'a committed, unchanged receipt on a clean tree must stay accepted after unrelated commits');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('38. untracked task file requires binding', () => {
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'an untracked task file must keep full binding');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('38b. the same stale receipt is accepted once committed on a clean tree', () => {
+  // Documents the accepted trade-off: once committed and clean, Base and Head
+  // must be concrete but are no longer compared against the runtime.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    commitAll(dir, 'receipt');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.stdout, '', result.stderr);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('39. staged but uncommitted task file requires binding', () => {
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    const add = spawnSync('git', ['-C', dir, 'add', '-A'], { encoding: 'utf8' });
+    assert.strictEqual(add.status, 0, add.stderr);
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'git add alone must not grant structure-only');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('40. modified receipt requires binding', () => {
+  const dir = makeWorkflowFixture(boundReceipt());
+  try {
+    commitAll(dir, 'receipt');
+    const taskFile = path.join(dir, 'specs', FEATURE, 'task-01-demo.md');
+    const context = workflowRuntimeContext(dir);
+    const before = fs.readFileSync(taskFile, 'utf8');
+    const after = before.replace(`Head: ${context.head}`, `Head: ${STALE_HEAD}`);
+    assert.notStrictEqual(after, before, 'fixture must contain the bound Head');
+    fs.writeFileSync(taskFile, after);
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'a receipt edited after commit must be rebound');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('41. unborn HEAD fails closed before any receipt check', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-spec-gate-'));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'], ['config', 'user.name', 'CafeKit Test']]) {
+      const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+      assert.strictEqual(result.status, 0, result.stderr);
+    }
+    const featureDir = path.join(dir, 'specs', FEATURE);
+    fs.mkdirSync(featureDir, { recursive: true });
+    fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
+    fs.writeFileSync(path.join(featureDir, 'task-01-demo.md'), [
+      '# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '', ...boundReceipt(STALE_BASE, STALE_HEAD), '',
+    ].join('\n'));
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'an unborn HEAD must block');
+    // The block arrives from provenance derivation, which cannot resolve a base
+    // commit here, so the receipt check is never reached. Asserting the reason
+    // keeps this case honest: it guards fail-closed behavior on an unborn HEAD,
+    // not the binding-mode selector. The selector's own HEAD-unreadable branch
+    // is guarded by cases 38 and 39.
+    assert.match(body.reason, /controlled failure/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('42. dirty tree outside specs requires binding, regardless of working directory', () => {
+  const dir = makeWorkflowFixture(boundReceipt());
+  try {
+    commitAll(dir, 'receipt');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'dirty.txt'), 'uncommitted\n');
+    clearCache();
+    const fromRoot = parseBlock(runHook({}, dir).stdout);
+    assert.ok(fromRoot && fromRoot.decision === 'block', 'an uncommitted change outside specs must rebind');
+    assert.match(fromRoot.reason, /\bprovenance\b/);
+    clearCache();
+    const fromSpecs = parseBlock(runHookFrom(dir, path.join(dir, 'specs', FEATURE)).stdout);
+    assert.ok(fromSpecs && fromSpecs.decision === 'block', 'the status check must pin the project root, not the working directory');
+    assert.match(fromSpecs.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('42b. a change hidden by skip-worktree or assume-unchanged requires binding', () => {
+  // `git status` honors both index flags, so a tracked file outside the specs
+  // root can differ from HEAD while the tree reports clean. Structure mode must
+  // not be granted from a report that git itself is suppressing.
+  for (const flag of ['--skip-worktree', '--assume-unchanged']) {
+    const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+    try {
+      fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'src', 'hidden.txt'), 'committed\n');
+      commitAll(dir, 'receipt and source');
+      const marked = spawnSync('git', ['-C', dir, 'update-index', flag, 'src/hidden.txt'], { encoding: 'utf8' });
+      assert.strictEqual(marked.status, 0, marked.stderr);
+      fs.writeFileSync(path.join(dir, 'src', 'hidden.txt'), 'tampered\n');
+      const status = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' });
+      assert.strictEqual(status.stdout.trim(), '', `${flag} must make the tree look clean for this case to mean anything`);
+      clearCache();
+      const body = parseBlock(runHook({}, dir).stdout);
+      assert.ok(body && body.decision === 'block', `${flag} must not grant structure-only`);
+      assert.match(body.reason, /\bprovenance\b/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+test('43. structure checks still block in committed mode', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 1',
+    `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`, '```text', '$ node --test', 'fail: 1', '```',
+  ]);
+  try {
+    commitAll(dir, 'receipt');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block');
+    assert.match(body.reason, /exit_result/);
+    assert.doesNotMatch(body.reason, /\bprovenance\b/, 'committed mode must not report a provenance failure for a stale but concrete pair');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('43b. committed mode still requires concrete Base and Head fields', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${STALE_BASE}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    commitAll(dir, 'receipt without Head');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'a missing Head field must still block');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('44. edited artifact bytes still block in committed mode', () => {
+  const artifactPath = 'output/bundle.js';
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`,
+    `Artifact: ${artifactPath} (sha256:${FIXTURE_ARTIFACT_DIGEST})`,
+    '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    fs.mkdirSync(path.join(dir, 'output'), { recursive: true });
+    fs.writeFileSync(path.join(dir, artifactPath), FIXTURE_ARTIFACT);
+    commitAll(dir, 'receipt and artifact');
+    clearCache();
+    const accepted = runHook({}, dir);
+    assert.strictEqual(accepted.stdout, '', accepted.stderr);
+    fs.writeFileSync(path.join(dir, artifactPath), 'tampered\n');
+    commitAll(dir, 'tamper artifact');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'artifact bytes must still be verified in committed mode');
+    assert.match(body.reason, /artifact_hash/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('45. the cache grants no authority across a state change', () => {
+  // A cached PASS must not survive a later mutation. The first run accepts and
+  // writes the cache; the second run sees tampered artifact bytes committed on a
+  // still-clean tree and must block without the cache being cleared first.
+  const artifactPath = 'output/cached.js';
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`,
+    `Artifact: ${artifactPath} (sha256:${FIXTURE_ARTIFACT_DIGEST})`,
+    '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    fs.mkdirSync(path.join(dir, 'output'), { recursive: true });
+    fs.writeFileSync(path.join(dir, artifactPath), FIXTURE_ARTIFACT);
+    commitAll(dir, 'receipt and artifact');
+    clearCache();
+    const accepted = runHook({}, dir);
+    assert.strictEqual(accepted.stdout, '', 'first run must accept and populate the cache');
+    fs.writeFileSync(path.join(dir, artifactPath), 'tampered after the cached pass\n');
+    commitAll(dir, 'tamper artifact, tree stays clean');
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'a cached pass must not hide a later mutation');
+    assert.match(body.reason, /artifact_hash/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('46. a dirty file inside the specs root does not force binding', () => {
+  // The status and index queries exclude the specs root on purpose: a receipt is
+  // written into that root, so counting it would make every receipt invalidate
+  // itself. Dropping the exclusion from either query must fail this case.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    commitAll(dir, 'receipt');
+    fs.writeFileSync(path.join(dir, 'specs', FEATURE, 'plan.md'), '# Demo plan\n\nEdited after the receipt was committed.\n');
+    fs.writeFileSync(path.join(dir, 'specs', FEATURE, 'notes-untracked.md'), 'scratch\n');
+    const dirty = spawnSync('git', ['-C', dir, 'status', '--porcelain', '--untracked-files=all'], { encoding: 'utf8' });
+    assert.match(dirty.stdout, /specs\//, 'the specs root must actually be dirty for this case to mean anything');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.stdout, '', 'work inside the specs root must not reopen a committed receipt');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('47. completed-set branch accepts committed receipts and blocks a tampered one', () => {
+  // Two finished packets resolve to the completed-set branch, which is the path
+  // that revalidated every done receipt on every Stop. Prove the new mode works
+  // there, then prove it still blocks.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    const secondDir = path.join(dir, 'specs', 'second');
+    fs.mkdirSync(secondDir, { recursive: true });
+    fs.writeFileSync(path.join(secondDir, 'plan.md'), '# Second plan\n');
+    fs.writeFileSync(path.join(secondDir, 'task-01-second.md'), [
+      '# Task 01: second', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '', ...boundReceipt(STALE_BASE, STALE_HEAD), '',
+    ].join('\n'));
+    commitAll(dir, 'two completed packets');
+    clearCache();
+    const accepted = runHook({}, dir);
+    assert.strictEqual(accepted.stdout, '', 'the completed-set branch must accept committed receipts on a clean tree');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'dirty.txt'), 'uncommitted\n');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'the completed-set branch must rebind on a dirty tree');
+    assert.match(body.reason, /\bprovenance\b/);
+    assert.match(body.reason, /second|demo/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('48. the gate\'s own runtime state does not defeat structure mode', () => {
+  // The gate writes its cache under .claude/hooks/.logs on every Stop. If that
+  // write counted as a dirty tree, a project tracking its runtime directory could
+  // never reach structure mode and the gate would defeat itself. The status query
+  // excludes the same runtime-state roots the provenance manifest already ignores.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    const stateDir = path.join(dir, '.claude', 'hooks', '.logs');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, 'spec-gate-last.json'), '{}\n');
+    fs.writeFileSync(path.join(dir, '.claude', 'runtime.json'), '{}\n');
+    commitAll(dir, 'receipt plus tracked runtime state');
+    // Mutate the tracked runtime state exactly as a Stop would.
+    fs.writeFileSync(path.join(stateDir, 'spec-gate-last.json'), '{"demo":{"task-01-demo.md":"done"}}\n');
+    fs.writeFileSync(path.join(dir, '.claude', 'runtime.json'), '{"spec":{}}\n');
+    const dirty = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' });
+    assert.match(dirty.stdout, /\.claude\//, 'the runtime state must actually be dirty for this case to mean anything');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.stdout, '', 'generated runtime state must not be read as a dirty worktree');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/__tests__/state.test.js

@@ -43,6 +43,13 @@ function inInstalledProcessSpecStateFixture(run) {
     fs.mkdirSync(hooks, { recursive: true });
     fs.mkdirSync(scripts, { recursive: true });
     fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'spec-state.cjs'), path.join(hooks, 'spec-state.cjs'));
+    fs.mkdirSync(path.join(hooks, 'lib'), { recursive: true });
+    fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'lib', 'runtime-dir.cjs'), path.join(hooks, 'lib', 'runtime-dir.cjs'));
+    fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'lib', 'hook-payload.cjs'), path.join(hooks, 'lib', 'hook-payload.cjs'));
+    fs.copyFileSync(
+      path.join(CLAUDE_ROOT, 'hooks', 'lib', 'hook-state-dir.cjs'),
+      path.join(hooks, 'lib', 'hook-state-dir.cjs'),
+    );
     for (const file of [
       'provenance.cjs',
       'spec-receipt.cjs',