@haposoft/cafekit 0.16.0-rc.6 → 0.16.0-rc.8

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

@@ -7,7 +7,253 @@ 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'));
+    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 +268,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 +293,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',

package/src/claude/hooks/lib/context.cjs

@@ -2,7 +2,7 @@
 /**
  * context.cjs - Context/reminder building for session injection
  *
- * Extracted from hooks for reuse in both Claude hooks and OpenCode plugins.
+ * Extracted from hooks for reuse across runtime adapters.
  * Builds session context, rules, paths, and plan information.
  *
  * @module context

package/src/claude/hooks/lib/detect.cjs

@@ -2,7 +2,7 @@
 /**
  * detect.cjs - Project and environment detection logic
  *
- * Extracted from session.cjs for reuse in both Claude hooks and OpenCode plugins.
+ * Extracted from session.cjs for reuse across runtime adapters.
  * Detects project type, package manager, framework, and runtime versions.
  *
  * @module detect

package/src/claude/hooks/spec-gate.cjs

@@ -93,6 +93,7 @@ try {
     if (typeof POLICY.validateCanonicalReceipt !== 'function'
       || typeof POLICY.completionDecisionForSpec !== 'function'
       || typeof RECEIPT.checkTaskReceipt !== 'function'
+      || typeof RECEIPT.checkWorkflowReceiptSet !== 'function'
       || typeof FINAL_STATE.evaluateCloseout !== 'function') {
       throw new Error('shared workflow policy lacks completion authority functions');
     }
@@ -112,8 +113,37 @@ try {
   } catch { /* gate stays on */ }
   // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
   const baseDir   = cwd;
-  const resolved = FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  const target = typeof RESOLVER.extractExplicitTarget === 'function'
+    ? RESOLVER.extractExplicitTarget(payload)
+    : null;
+  let resolved = typeof RESOLVER.resolveWorkflowCandidate === 'function'
+    ? RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true })
+    : FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  if (typeof RESOLVER.refineWorkflowGateResolution === 'function') {
+    resolved = RESOLVER.refineWorkflowGateResolution(resolved);
+  }
   if (!resolved) process.exit(0);
+  if (resolved.layoutKind === 'process-v3-completed-set') {
+    const configuredGate = runtime.spec?.completion_gate;
+    if (configuredGate !== undefined && configuredGate !== true) {
+      emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
+      process.exit(0);
+    }
+    const checked = RECEIPT.checkWorkflowReceiptSet(
+      resolved.candidates,
+      baseDir,
+      sessionIdentity(payload),
+      POLICY,
+    );
+    if (checked.failures.length === 0) process.exit(0);
+    const lines = [`⚠️ Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
+    for (const failure of checked.failures) {
+      lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
+      lines.push(`  Fix: write a runtime-bound \`## Receipt\` with the planned command in \`specs/${failure.featureName}/${failure.taskPath}\`.`);
+    }
+    emitBlock(lines.slice(0, 8).join('\n'));
+    process.exit(0);
+  }
   if (resolved.error === 'multiple_active' || resolved.error === 'multiple_persisted') {
     process.stdout.write(JSON.stringify({
       decision: 'block',
@@ -137,13 +167,14 @@ try {
   }
   if (resolved.error) process.exit(0);
 
-  const activeSpec = resolved.spec;
+  const activeSpec = resolved.spec || {};
+  const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
   const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
   const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
     || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  if (activeSpec.schema_version === '2.1') {
+  if (!processWorkflow && activeSpec.schema_version === '2.1') {
     const finalState = FINAL_STATE.evaluateCloseout({
       resolver: RESOLVER,
       policy: POLICY,
@@ -160,7 +191,7 @@ try {
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
-    specFile: resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    specFile: resolved.stateFile || resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
     featureName,
     runtimeSession: sessionIdentity(payload),
   });
@@ -170,7 +201,7 @@ try {
     emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
     process.exit(0);
   }
-  const taskRegistry = activeSpec.task_registry || {};
+  const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
   const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
@@ -183,7 +214,7 @@ try {
     currentStatuses[tp] = task?.status || 'pending';
   }
 
-  const staleFlashTasks = Object.entries(taskRegistry)
+  const staleFlashTasks = processWorkflow ? [] : Object.entries(taskRegistry)
     .filter(([, task]) => POLICY.isStaleFlashDone(task))
     .map(([taskPath]) => taskPath);
   if (staleFlashTasks.length > 0) {
@@ -206,11 +237,13 @@ try {
   const failures = allDoneTasks
     .map((taskPath) => ({
       taskPath,
-      fails: RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
+      fails: processWorkflow
+        ? RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY).failures
+        : RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
     }))
     .filter((f) => f.fails.length > 0);
 
-  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureCloseoutRequired = !processWorkflow && explicitCloseout && allDoneTasks.length > 0;
   const featureReceipt = featureCloseoutRequired
     ? RECEIPT.checkFeatureReceipt(featureDir, runtimeContext, POLICY)
     : null;
@@ -253,7 +286,9 @@ try {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
     lines.push(taskPath === 'feature-receipt.md'
       ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
-      : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
+      : processWorkflow
+        ? `  Fix: write a runtime-bound \`## Receipt\` with command output in \`specs/${featureName}/${path.posix.basename(taskPath)}\`.`
+        : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {
     lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);

package/src/claude/hooks/spec-state.cjs

@@ -73,14 +73,17 @@ try {
     if (fs.existsSync(p)) runtime = JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch { /* ignore */ }
 
-  // Reminder toggle — same key the OpenCode spec-state plugin honors.
+  // Reminder toggle.
   // (The Stop completion gate has its own toggle: spec.completion_gate.)
   if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
 
   const baseDir   = process.env.PROJECT_ROOT || cwd;
   const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
   const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
-  const resolved = RESOLVER.resolveActiveSpec({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
+  const resolveWorkflow = typeof RESOLVER.resolveWorkflowCandidate === 'function'
+    ? RESOLVER.resolveWorkflowCandidate
+    : RESOLVER.resolveActiveSpec;
+  const resolved = resolveWorkflow({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
 
   if (!resolved) {
     process.exit(0); // No active spec, do nothing
@@ -108,19 +111,20 @@ try {
     process.exit(0);
   }
 
-  const activeSpec = resolved.spec;
+  const activeSpec = resolved.spec || {};
+  const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
-    specFile: resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    specFile: resolved.stateFile || resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
     featureName,
     runtimeSession: sessionIdentity(payload),
   });
 
-  const phase = activeSpec.current_phase || activeSpec.phase || 'unknown';
-  const taskRegistry = activeSpec.task_registry || {};
+  const phase = resolved.phase || activeSpec.current_phase || activeSpec.phase || 'unknown';
+  const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
   const flashTasks = POLICY.flashState(taskRegistry);
   const taskEntries = Object.entries(taskRegistry);
   const taskCounts = taskEntries.reduce((acc, [, task]) => {
@@ -128,14 +132,32 @@ try {
     acc[status] = (acc[status] || 0) + 1;
     return acc;
   }, {});
+  const featureDir = path.join(specsPath, featureName);
   const taskStatusByPath = new Map(taskEntries.map(([taskPath, task]) => [taskPath, task?.status || 'pending']));
+  const dependencyProof = processWorkflow
+    ? RECEIPT.workflowDependencyProofState(featureDir, taskRegistry, runtimeContext, POLICY)
+    : {};
+  const taskState = taskEntries.map(([taskPath, task]) => [
+    taskPath,
+    task?.status || 'pending',
+    [...(Array.isArray(task?.dependencies) ? task.dependencies : [])].sort(),
+  ]).sort(([left], [right]) => left.localeCompare(right));
+  const proofState = Object.entries(dependencyProof).map(([taskPath, proof]) => [
+    taskPath,
+    proof.done,
+    proof.valid,
+    proof.eligible,
+    proof.signature,
+  ]);
   const nextUnblocked = taskEntries.find(([, task]) => {
     const status = task?.status || 'pending';
     const deps = Array.isArray(task?.dependencies) ? task.dependencies : [];
-    return status === 'pending' && deps.every((dep) => taskStatusByPath.get(dep) === 'done');
+    return resolved.queueReady !== false && status === 'pending' && deps.every((dep) => (
+      processWorkflow ? dependencyProof[dep]?.eligible === true : taskStatusByPath.get(dep) === 'done'
+    ));
   });
-  const featureDir = path.join(specsPath, featureName);
-  const featureReceiptPresent = RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
+  const featureReceiptPresent = !processWorkflow
+    && RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
 
   // ── State-change gate: only emit the full tollgate when spec state changed ──
   // The cache is shared by installed hook copies, so its key must carry the
@@ -152,6 +174,10 @@ try {
     Head: runtimeContext.head,
     contextId: runtimeContext.context_id,
     phase,
+    workflowContract: resolved.workflowContract || null,
+    queueReady: resolved.queueReady !== false,
+    taskState,
+    proofState,
     done: taskCounts.done || 0,
     total: taskEntries.length,
     featureReceiptPresent,
@@ -164,7 +190,11 @@ try {
   }
 
   if (stateKey && lastKey === stateKey) {
-    console.log(`\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${taskCounts.done || 0}/${taskEntries.length} tasks done). Tollgate active — sync \`spec.json\` when state changes.\n`);
+    const stateTarget = processWorkflow ? 'task Markdown' : '`spec.json`';
+    const migration = processWorkflow && resolved.queueReady === false
+      ? ' Add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.'
+      : '';
+    console.log(`\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${taskCounts.done || 0}/${taskEntries.length} tasks done). Tollgate active — sync ${stateTarget} when state changes.${migration}\n`);
     process.exit(0);
   }
 
@@ -187,9 +217,17 @@ try {
   if (flashTasks.length > 0) {
     lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. A PASS proof keeps the persisted task in_progress until explicit sync-finalize.`);
   }
-  lines.push(`- Sync \`spec.json\` + task Markdown status after verified work; task proof belongs in \`receipts/<task-basename>.md\`.`);
-  lines.push(`- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`);
-  lines.push(`- Validate with \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
+  if (processWorkflow) {
+    if (resolved.queueReady === false) {
+      lines.push('- Migration required: add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.');
+    }
+    lines.push('- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.');
+    lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop revalidates every task currently marked done.`);
+  } else {
+    lines.push('- Sync `spec.json` + task Markdown status after verified work; task proof belongs in `receipts/<task-basename>.md`.');
+    lines.push(`- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`);
+    lines.push(`- Validate with \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
+  }
   lines.push('');
 
   console.log(lines.join('\n'));

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -67,7 +67,7 @@ try {
 
   // Valve 2: block with an actionable message carrying the exact command.
   // NOTE: deliberately does NOT mention the runtime.json escape hatch — an
-  // OpenCode smoke test proved the model reads the advertised override and
+  // Smoke testing proved the model reads the advertised override and
   // simply disables the guard itself. The hatch stays functional for humans.
   const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
   const feature = m ? m[2] : '<feature>';

package/src/claude/migration-manifest.json

@@ -80,15 +80,29 @@
   "obsolete": {
     "agents": {
       "claude": ["agents/god-developer.md"],
-      "codex": ["agents/god_developer.toml"],
-      "opencode": ["agents/god-developer.md"]
+      "codex": ["agents/god_developer.toml"]
     },
     "runtimeFiles": [
       "hooks/skill-router.cjs",
       "hooks/lib/skill-router-routes.cjs",
       "scripts/browser-tool.cjs",
       "skills/generate-graph",
-      "skills/impact-analysis"
+      "skills/impact-analysis",
+      "skills/specs/references/archive-workflow.md",
+      "skills/specs/references/ask-user-question-gates.md",
+      "skills/specs/references/codebase-analysis.md",
+      "skills/specs/references/cross-spec-dependency.md",
+      "skills/specs/references/research-strategy.md",
+      "skills/specs/references/scope-inquiry.md",
+      "skills/specs/references/translation-mirror.md",
+      "skills/specs/rules/design-discovery-full.md",
+      "skills/specs/rules/design-discovery-light.md",
+      "skills/specs/rules/design-principles.md",
+      "skills/specs/rules/design-review.md",
+      "skills/specs/rules/ears-format.md",
+      "skills/specs/rules/phase-decision-matrix.md",
+      "skills/specs/rules/task-scoring-rubric.md",
+      "skills/specs/rules/tasks-generation.md"
     ],
     "settingsHookCommandSubstrings": [
       "hooks/skill-router.cjs"