@haposoft/cafekit 0.16.0-rc.7 → 0.16.0

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__/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';
@@ -99,6 +101,10 @@ function makeWorkflowFixture(receiptLines = [], plannedCommand = 'node --test')
     '',
     'Status: done',
     '',
+    '## Dependencies',
+    '',
+    '- none',
+    '',
     '## Verification Plan',
     '',
     `- Command: ${plannedCommand}`,
@@ -282,6 +288,11 @@ 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', '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));
@@ -1318,10 +1329,80 @@ test('32. process-v3 requires Receipt heading and runtime-bound provenance', ()
   }
 });
 
+test('32b. process-v3 ignores a Receipt heading and proof contained only in a fence', () => {
+  const dir = makeWorkflowFixture([
+    '~~~~markdown', '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', 'pass: 1', '```', '~~~~',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'fenced-only process-v3 Receipt must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /missing_receipt/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32c. process-v3 ignores canonical Receipt fields contained only in its output fence', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', '```text', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'fenced-only canonical fields must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /verification_state/);
+    assert.match(body.reason, /command/);
+    assert.match(body.reason, /provenance/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32d. process-v3 preserves explicit failures from the Receipt output fence', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test',
+    'exit code: 1', 'FAIL', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'explicit fenced output failure must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /verification_state/);
+    assert.match(body.reason, /exit_result/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32e. process-v3 rejects output whose closing fence is shorter than its opener', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '````text', '$ node --test',
+    'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'malformed output fence must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /command_output/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('33. process-v3 done task with canonical inline Receipt passes', () => {
   const dir = makeWorkflowFixture([
     '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
-    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test',
+    'Status: pending', '## Receipt', 'pass: 1', '```',
   ]);
   try {
     clearCache();
@@ -1360,6 +1441,7 @@ test('35. process-v3 Stop ignores a completed packet when one packet remains act
     fs.writeFileSync(path.join(activeDir, 'plan.md'), '# Active plan\n');
     fs.writeFileSync(path.join(activeDir, 'task-01-active.md'), [
       '# Task 01: active', '', 'Status: pending', '',
+      '## Dependencies', '', '- none', '',
       '## Verification Plan', '', '- Command: node --test', '',
     ].join('\n'));
     clearCache();
@@ -1389,6 +1471,7 @@ test('36. process-v3 Stop accepts two completed packets with valid Receipts', ()
     });
     fs.writeFileSync(path.join(otherDir, 'task-01-other.md'), [
       '# Task 01: other', '', 'Status: done', '',
+      '## Dependencies', '', '- none', '',
       '## Verification Plan', '', '- Command: node --test', '',
       '## Receipt', '',
       'Verification: PASS', 'Command: node --test', 'Exit: 0',

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

@@ -7,7 +7,258 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const HOOK = path.join(__dirname, '..', 'state.cjs');
+const CLAUDE_ROOT = path.join(__dirname, '..', '..');
+const STATE_HOOK = path.join(CLAUDE_ROOT, 'hooks', 'state.cjs');
+const POLICY = require(path.join(CLAUDE_ROOT, 'scripts', 'workflow-policy.cjs'));
+
+function processTaskContent(title, status, dependency = 'none') {
+  return [
+    `# ${title}`, '', `Status: ${status}`, '',
+    '## Dependencies', '', `- ${dependency}`, '',
+    '## Verification Plan', '', '- Command: node --test', '',
+  ].join('\n');
+}
+
+function canonicalProcessTask(root, title, dependency = 'none') {
+  const context = POLICY.deriveRuntimeContext({
+    projectRoot: root,
+    specsRoot: path.join(root, 'specs'),
+    specFile: path.join(root, 'specs', 'auth', 'plan.md'),
+    featureName: 'auth',
+    runtimeSession: 'session-auth-state',
+  });
+  return [
+    processTaskContent(title, 'done', dependency),
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${context.base}`, `Head: ${context.head}`,
+    '```text', 'node --test', '1 test passed', '```', '',
+  ].join('\n');
+}
+
+function inInstalledProcessSpecStateFixture(run) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-spec-state-'));
+  try {
+    const hooks = path.join(dir, '.claude', 'hooks');
+    const scripts = path.join(dir, '.claude', 'scripts');
+    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', 'hook-state-dir.cjs'),
+      path.join(hooks, 'lib', 'hook-state-dir.cjs'),
+    );
+    for (const file of [
+      'provenance.cjs',
+      'spec-receipt.cjs',
+      'spec-resolver.cjs',
+      'workflow-policy.cjs',
+    ]) {
+      fs.copyFileSync(path.join(CLAUDE_ROOT, 'scripts', file), path.join(scripts, file));
+    }
+
+    const feature = path.join(dir, 'specs', 'auth');
+    fs.mkdirSync(feature, { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\nSpecs-Contract: process-first-ready-v1\n');
+
+    for (const args of [
+      ['init', '-q'],
+      ['config', 'user.email', 'cafekit@example.invalid'],
+      ['config', 'user.name', 'CafeKit Test'],
+      ['commit', '--allow-empty', '-qm', 'fixture'],
+    ]) {
+      const git = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+      assert.strictEqual(git.status, 0, git.stderr);
+    }
+
+    const writeTask = (basename, title, status, dependency = 'none') => {
+      fs.writeFileSync(
+        path.join(feature, basename),
+        processTaskContent(title, status, dependency),
+      );
+    };
+    const runState = () => spawnSync(process.execPath, [path.join(hooks, 'spec-state.cjs')], {
+      cwd: dir,
+      env: { ...process.env, PROJECT_ROOT: dir },
+      input: JSON.stringify({
+        cwd: dir,
+        featureName: 'auth',
+        session_id: 'session-auth-state',
+        hook_event_name: 'UserPromptSubmit',
+        prompt: 'Continue',
+      }),
+      encoding: 'utf8',
+    });
+    return run({
+      cacheFile: path.join(hooks, '.logs', 'tollgate-last.txt'),
+      dir,
+      feature,
+      hooks,
+      runState,
+      writePlan: (content) => fs.writeFileSync(path.join(feature, 'plan.md'), content),
+      writeTask,
+    });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('Claude installed spec-state re-evaluates a standalone task when blocked becomes pending', () => {
+  inInstalledProcessSpecStateFixture(({ cacheFile, hooks, runState, writeTask }) => {
+    writeTask('task-01-auth.md', 'Task 01: auth', 'blocked');
+
+    const blocked = runState();
+    assert.strictEqual(blocked.status, 0, blocked.stderr);
+    assert.match(blocked.stdout, /0 pending, 1 blocked/);
+    assert.doesNotMatch(blocked.stdout, /Next unblocked/);
+    assert.ok(cacheFile.startsWith(`${hooks}${path.sep}`), 'cache must stay inside temporary installed hooks');
+    assert.strictEqual(fs.existsSync(cacheFile), true, 'installed cache must be created');
+    const blockedCache = fs.readFileSync(cacheFile, 'utf8');
+
+    writeTask('task-01-auth.md', 'Task 01: auth', 'pending');
+    const pending = runState();
+    assert.strictEqual(pending.status, 0, pending.stderr);
+    assert.match(pending.stdout, /Spec state changed: `auth`/);
+    assert.match(pending.stdout, /1 pending, 0 blocked/);
+    assert.match(pending.stdout, /Next unblocked: `task-01-auth\.md`/);
+    assert.notStrictEqual(fs.readFileSync(cacheFile, 'utf8'), blockedCache, 'state cache must change');
+  });
+});
+
+test('Claude installed spec-state requires current canonical dependency proof and keys receipt mutations', () => {
+  inInstalledProcessSpecStateFixture(({ cacheFile, dir, feature, hooks, runState, writeTask }) => {
+    const predecessor = 'task-01-semantic-review.md';
+    const dependent = 'task-02-implementation.md';
+    writeTask(predecessor, 'Task 01: semantic review', 'blocked');
+    writeTask(dependent, 'Task 02: implementation', 'pending', predecessor);
+    const dependentPath = path.join(feature, dependent);
+    const unchangedDependent = fs.readFileSync(dependentPath, 'utf8');
+
+    const blocked = runState();
+    assert.strictEqual(blocked.status, 0, blocked.stderr);
+    assert.match(blocked.stdout, /0 done \/ 2 total \(0 in_progress, 1 pending, 1 blocked\)/);
+    assert.doesNotMatch(blocked.stdout, /Next unblocked/);
+    assert.ok(cacheFile.startsWith(`${hooks}${path.sep}`), 'cache must stay inside temporary installed hooks');
+    assert.strictEqual(fs.existsSync(cacheFile), true, 'installed cache must be created');
+    const blockedCache = fs.readFileSync(cacheFile, 'utf8');
+
+    writeTask(predecessor, 'Task 01: semantic review', 'done');
+    const missing = runState();
+    assert.strictEqual(missing.status, 0, missing.stderr);
+    assert.doesNotMatch(missing.stdout, /Next unblocked/);
+    const missingCache = fs.readFileSync(cacheFile, 'utf8');
+    assert.notStrictEqual(missingCache, blockedCache, 'done without proof must change cached proof state');
+
+    fs.appendFileSync(path.join(feature, predecessor), '\n## Receipt\n\nVerification: PASS\n');
+    const malformed = runState();
+    assert.strictEqual(malformed.status, 0, malformed.stderr);
+    assert.doesNotMatch(malformed.stdout, /Next unblocked/);
+
+    fs.writeFileSync(path.join(feature, predecessor), canonicalProcessTask(dir, 'Task 01: semantic review'));
+    const ready = runState();
+    assert.strictEqual(ready.status, 0, ready.stderr);
+    assert.match(ready.stdout, /Next unblocked: `task-02-implementation\.md`/);
+    const readyCache = fs.readFileSync(cacheFile, 'utf8');
+    assert.notStrictEqual(readyCache, missingCache, 'canonical proof must change cached proof state');
+
+    fs.writeFileSync(
+      path.join(feature, predecessor),
+      fs.readFileSync(path.join(feature, predecessor), 'utf8').replace('Verification: PASS', 'Verification: FAIL'),
+    );
+    const mutated = runState();
+    assert.strictEqual(mutated.status, 0, mutated.stderr);
+    assert.doesNotMatch(mutated.stdout, /Next unblocked/);
+    assert.notStrictEqual(fs.readFileSync(cacheFile, 'utf8'), readyCache, 'receipt-only mutation must change cache');
+    assert.strictEqual(fs.readFileSync(dependentPath, 'utf8'), unchangedDependent, 'dependent must remain pending');
+  });
+});
+
+test('Claude installed spec-state keeps unversioned pending packets out of Next with migration guidance', () => {
+  inInstalledProcessSpecStateFixture(({ feature, runState, writePlan, writeTask }) => {
+    const fencedMarkerPlan = '# Auth plan\n\n```markdown\nSpecs-Contract: process-first-ready-v1\n```\n';
+    writePlan(fencedMarkerPlan);
+    writeTask('task-01-auth.md', 'Task 01: auth', 'pending');
+    const taskBytes = fs.readFileSync(path.join(feature, 'task-01-auth.md'));
+    const result = runState();
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout, /Next unblocked/);
+    assert.match(result.stdout, /Migration required: add `Specs-Contract: process-first-ready-v1`/);
+    const cached = runState();
+    assert.strictEqual(cached.status, 0, cached.stderr);
+    assert.doesNotMatch(cached.stdout, /Next unblocked/);
+    assert.match(cached.stdout, /Add `Specs-Contract: process-first-ready-v1`/);
+
+    writePlan(fencedMarkerPlan.replace('# Auth plan\n', '# Auth plan\nSpecs-Contract: process-first-ready-v1\n'));
+    const marked = runState();
+    assert.strictEqual(marked.status, 0, marked.stderr);
+    assert.match(marked.stdout, /Spec state changed: `auth`/);
+    assert.match(marked.stdout, /Next unblocked: `task-01-auth\.md`/);
+    assert.deepStrictEqual(fs.readFileSync(path.join(feature, 'task-01-auth.md')), taskBytes, 'marker-only transition must not change task bytes');
+  });
+});
+
+test('Claude resolver ignores fenced workflow annotations and rejects fenced-only Status', () => {
+  inInstalledProcessSpecStateFixture(({ dir, feature, runState, writePlan, writeTask }) => {
+    const resolver = require(path.join(dir, '.claude', 'scripts', 'spec-resolver.cjs'));
+    const trailingFence = resolver.annotatedMarkdownLines([
+      '```markdown', '``` trailing', 'Specs-Contract: process-first-ready-v1',
+      'Status: done', '## Receipt', '```',
+    ].join('\n'));
+    assert.deepStrictEqual(trailingFence.slice(2, 5).map(({ outsideFence }) => outsideFence), [false, false, false]);
+    const fourSpaceFence = resolver.annotatedMarkdownLines('    ```markdown\nStatus: pending');
+    assert.strictEqual(fourSpaceFence[1].outsideFence, true);
+    writePlan('# Auth plan\nSpecs-Contract: process-first-ready-v1\n');
+    fs.writeFileSync(path.join(feature, 'task-01-fenced-only.md'), [
+      '# Task 01', '', '```markdown', 'Status: done', '```', '',
+      '## Dependencies', '', '- none', '', '## Verification Plan', '', '- Command: node --test', '',
+    ].join('\n'));
+    const malformed = resolver.resolveWorkflowCandidate({ projectRoot: dir, runtime: {}, explicitFeature: 'auth' });
+    assert.strictEqual(malformed.error, 'explicit_malformed');
+    assert.match(malformed.reason, /must contain exactly one supported Status field/);
+
+    fs.rmSync(path.join(feature, 'task-01-fenced-only.md'));
+    writeTask('task-01-dependent.md', 'Task 01: dependent', 'pending', 'task-02-predecessor.md');
+    fs.writeFileSync(path.join(feature, 'task-02-predecessor.md'), [
+      '# Task 02', '', 'Status: pending', '', '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '~~~~markdown', 'Status: done', '## Dependencies', '- task-01-dependent.md', '## Receipt',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0', '```text', 'fake pass', '```', '~~~~', '',
+    ].join('\n'));
+    const result = runState();
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.match(result.stdout, /Next unblocked: `task-02-predecessor\.md`/);
+    assert.doesNotMatch(result.stdout, /Next unblocked: `task-01-dependent\.md`/);
+  });
+});
+
+test('Claude resolver accepts unique legacy task numbers, rejects ambiguity, and rejects exact cycles', () => {
+  inInstalledProcessSpecStateFixture(({ dir, feature, writePlan, writeTask }) => {
+    const resolver = require(path.join(dir, '.claude', 'scripts', 'spec-resolver.cjs'));
+    writePlan('# Auth plan\n');
+    writeTask('task-01-a.md', 'Task 01: a', 'pending');
+    writeTask('task-02-b.md', 'Task 02: b', 'pending', 'Task 01');
+    fs.writeFileSync(path.join(feature, 'task-03-c.md'), '# Task 03: c\n\nStatus: pending\n');
+    const unique = resolver.resolveWorkflowCandidate({ projectRoot: dir, runtime: {}, explicitFeature: 'auth' });
+    assert.deepStrictEqual(unique.taskRegistry['task-02-b.md'].dependencies, ['task-01-a.md']);
+    assert.deepStrictEqual(unique.taskRegistry['task-03-c.md'].dependencies, []);
+    assert.strictEqual(unique.workflowContract, null);
+    assert.strictEqual(unique.queueReady, false);
+
+    writeTask('task-01-second.md', 'Task 01: second', 'pending');
+    const ambiguous = resolver.resolveWorkflowCandidate({ projectRoot: dir, runtime: {}, explicitFeature: 'auth' });
+    assert.strictEqual(ambiguous.error, 'explicit_malformed');
+    assert.match(ambiguous.reason, /legacy dependency Task 01 maps to 2 task basenames/);
+
+    fs.rmSync(path.join(feature, 'task-01-second.md'));
+    fs.rmSync(path.join(feature, 'task-03-c.md'));
+    writePlan('# Auth plan\nSpecs-Contract: process-first-ready-v1\n');
+    writeTask('task-01-a.md', 'Task 01: a', 'pending', 'task-02-b.md');
+    writeTask('task-02-b.md', 'Task 02: b', 'pending', 'task-01-a.md');
+    const cycle = resolver.resolveWorkflowCandidate({ projectRoot: dir, runtime: {}, explicitFeature: 'auth' });
+    assert.strictEqual(cycle.error, 'explicit_malformed');
+    assert.match(cycle.reason, /dependency cycle detected: task-01-a\.md -> task-02-b\.md -> task-01-a\.md/);
+  });
+});
 
 test('Stop snapshot includes tracked modifications and untracked files', () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-state-'));
@@ -22,7 +273,7 @@ test('Stop snapshot includes tracked modifications and untracked files', () => {
 
     fs.writeFileSync(path.join(dir, 'tracked.txt'), 'after\n');
     fs.writeFileSync(path.join(dir, 'new-untracked.json'), '{}\n');
-    const result = spawnSync(process.execPath, [HOOK], {
+    const result = spawnSync(process.execPath, [STATE_HOOK], {
       cwd: dir,
       input: JSON.stringify({ hook_event_name: 'Stop', cwd: dir }),
       encoding: 'utf8',
@@ -47,7 +298,7 @@ test('Stop snapshot includes untracked files before the first commit', () => {
     spawnSync('git', ['init', '-q'], { cwd: dir });
     fs.writeFileSync(path.join(dir, 'first-untracked.txt'), 'new\n');
 
-    const result = spawnSync(process.execPath, [HOOK], {
+    const result = spawnSync(process.execPath, [STATE_HOOK], {
       cwd: dir,
       input: JSON.stringify({ hook_event_name: 'Stop', cwd: dir }),
       encoding: 'utf8',