@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/bin/__tests__/develop-contract.test.js

@@ -12,6 +12,8 @@ const PACKAGE_ROOT = path.join(__dirname, '../..');
 const POLICY_PATH = path.join(PACKAGE_ROOT, 'src/claude/scripts/workflow-policy.cjs');
 const POLICY = require(POLICY_PATH);
 const PROVENANCE_HELPER = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/provenance.cjs'));
+const RESOLVER = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-resolver.cjs'));
+const RECEIPTS = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-receipt.cjs'));
 const FINAL_STATE = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-final-state.cjs'));
 const VALIDATOR = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/validate-spec-output.cjs'));
 const GROUNDER = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-ground.cjs'));
@@ -24,11 +26,24 @@ const SPECS = path.join(PACKAGE_ROOT, 'src/claude/skills/specs/SKILL.md');
 const SCAFFOLD = path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-scaffold.cjs');
 const GATE = path.join(PACKAGE_ROOT, 'src/claude/skills/develop/references/quality-gate.md');
 const TEST_SKILL = path.join(PACKAGE_ROOT, 'src/claude/skills/test/SKILL.md');
+const TEST_SOURCE_ROOT = path.dirname(TEST_SKILL);
+const TEST_REFERENCES = ['execution-strategy.md', 'failure-triage.md', 'test-memory.md'];
+const TEST_RUNNER = path.join(PACKAGE_ROOT, 'src/claude/agents/test-runner.md');
 const SYNC_SKILL = path.join(PACKAGE_ROOT, 'src/claude/skills/sync/SKILL.md');
 const CODE_REVIEW_SKILL = path.join(PACKAGE_ROOT, 'src/claude/skills/code-review/SKILL.md');
 const PARALLEL_WAVES = path.join(PACKAGE_ROOT, 'src/claude/skills/develop/references/parallel-waves.md');
+const DEVELOP_REFERENCES = ['quality-gate.md', 'parallel-waves.md', 'subagent-patterns.md'];
+const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
 const SYNC_PROTOCOLS = path.join(PACKAGE_ROOT, 'src/claude/skills/sync/references/sync-protocols.md');
+const PROCESS_FIRST_AGENTS = [
+  'implementer.md',
+  'inspector.md',
+  'code-auditor.md',
+  'docs-keeper.md',
+  'deployer.md',
+].map((name) => path.join(PACKAGE_ROOT, 'src/claude/agents', name));
 const PROVENANCE = path.join(PACKAGE_ROOT, '../../docs/provenance.md');
+const SPECS_USAGE_GUIDE = path.join(PACKAGE_ROOT, '../../docs/specs-usage-guide.md');
 const RUNTIME_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-policy-runtime-'));
 const RUNTIME_SPEC = path.join(RUNTIME_ROOT, 'specs', 'demo', 'spec.json');
 fs.mkdirSync(path.dirname(RUNTIME_SPEC), { recursive: true });
@@ -73,9 +88,23 @@ function installClaudeRuntimeClosure(fixtureRoot, entry = 'hooks/spec-gate.cjs')
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.copyFileSync(path.join(hooksRoot, hook), target);
   }
+  // Hook helpers the raw-copied hooks require at runtime.
+  for (const helper of ['hook-state-dir.cjs', 'runtime-dir.cjs', 'hook-payload.cjs']) {
+    const target = path.join(destinationRoot, 'hooks', 'lib', helper);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(path.join(hooksRoot, 'lib', helper), target);
+  }
   return path.join(destinationRoot, entry);
 }
 
+function installClaude(root) {
+  return spawnSync(process.execPath, [INSTALLER, '--platform', 'claude', '--yes'], {
+    cwd: root,
+    encoding: 'utf8',
+    env: { ...process.env, PATH: '/usr/bin:/bin' },
+  });
+}
+
 function markdownLegacyRegions(content) {
   const headings = [];
   const primaryLines = [];
@@ -300,7 +329,7 @@ function canonicalFlashTask(overrides = {}) {
   return {
     status: 'in_progress',
     receipt: 'FLASH_UNVERIFIED',
-    blocker: 'awaiting /hapo:test <feature>',
+    blocker: 'awaiting /cf:test <feature>',
     dependencyBlocked: true,
     unblocks: false,
     feature_name: 'demo',
@@ -348,7 +377,7 @@ test('develop flags retain their process-v3 contracts', () => {
   assert.match(develop, /implementation-notes-template\.html/);
   assert.match(develop, /Never create it by default/i);
   assert.match(develop, /--parallel \[N\][\s\S]*parallel-waves\.md[\s\S]*isolated worktrees[\s\S]*one controller writer/i);
-  assert.match(develop, /--flash[\s\S]*Status: in_progress[\s\S]*FLASH_UNVERIFIED[\s\S]*awaiting \/hapo:test <feature>/i);
+  assert.match(develop, /--flash[\s\S]*Status: in_progress[\s\S]*FLASH_UNVERIFIED[\s\S]*awaiting \/cf:test <feature>/i);
   assert.match(develop, /FLASH_UNVERIFIED[\s\S]*do not unblock dependents[\s\S]*sync-finalize path/i);
 });
 
@@ -771,6 +800,35 @@ test('Specs primary output is a flat process-first packet with isolated legacy c
   assertVocabularyIsLegacyOnly(SPECS, regions);
 });
 
+test('core execution agents default to process-first state and isolate legacy packets', () => {
+  for (const filePath of PROCESS_FIRST_AGENTS) {
+    const content = read(filePath);
+    const name = path.basename(filePath);
+    assert.match(content, /plan\.md/i, `${name} must read the process-first plan`);
+    assert.match(content, /task-NN-\*\.md|task-NN-<slug>\.md/i, `${name} must understand flat tasks`);
+    assert.match(content, /legacy/i, `${name} must isolate legacy compatibility`);
+  }
+
+  const implementer = read(PROCESS_FIRST_AGENTS[0]);
+  assert.match(implementer, /Under every dispatch mode[\s\S]{0,160}do NOT edit[\s\S]{0,80}`plan\.md`[\s\S]{0,80}`Status:`[\s\S]{0,80}`## Receipt`/i);
+  assert.match(implementer, /controller/i);
+  assert.match(implementer, /process-first work[\s\S]{0,100}Ownership[\s\S]{0,100}`Related Files` only for a valid legacy adapter/i);
+
+  const auditor = read(PROCESS_FIRST_AGENTS[2]);
+  assert.match(auditor, /accepted C1\/C2 decisions/i);
+  assert.match(auditor, /Only for a valid legacy adapter[\s\S]*`Related Files`[\s\S]*`## Evidence`/i);
+  assert.match(auditor, /Never require those legacy artifacts from a[\s\S]*process-first packet/i);
+  assert.match(auditor, /attestation belongs only to the valid legacy/i);
+
+  const docsKeeper = read(PROCESS_FIRST_AGENTS[3]);
+  assert.match(docsKeeper, /never[\s\S]{0,80}invent or write Status, Receipt, approval, or execution proof/i);
+
+  const deployer = read(PROCESS_FIRST_AGENTS[4]);
+  assert.match(deployer, /current final inline Receipt/i);
+  assert.match(deployer, /C3\/release authorization/i);
+  assert.match(deployer, /does not write process-first Status\/Receipt/i);
+});
+
 test('R7 Develop and Sync surfaces teach process-v3 and isolate hierarchical Legacy sections', () => {
   const surfaces = [
     ['develop', DEVELOP],
@@ -795,10 +853,10 @@ test('R7 Develop and Sync surfaces teach process-v3 and isolate hierarchical Leg
 
   const develop = regionsByName.get('develop').primary;
   assert.match(develop, /`specs\/<feature>\/plan\.md` plus flat `task-NN-\*\.md`/i);
-  assert.match(develop, /selects one unblocked task at a time/i);
+  assert.match(develop, /one unblocked task at a time/i);
   assert.match(develop, /Outcome and Acceptance/i);
   assert.match(develop, /Verification Plan/);
-  assert.match(develop, /final `## Receipt`/i);
+  assert.match(develop, /final inline `## Receipt`/i);
 
   const sync = regionsByName.get('sync').primary;
   assert.match(sync, /<task-NN-slug\.md>/i);
@@ -807,10 +865,10 @@ test('R7 Develop and Sync surfaces teach process-v3 and isolate hierarchical Leg
   assert.match(sync, /current inline Receipt/i);
 
   const waves = regionsByName.get('parallel waves').primary;
-  assert.match(waves, /plan task table[\s\S]*flat task's[\s\S]*`## Dependencies`/i);
-  assert.match(waves, /acceptance, Verification Plan/i);
+  assert.match(waves, /dependencies from the plan table and each task/i);
+  assert.match(waves, /acceptance, proof command/i);
   assert.match(waves, /one file has one writer per wave/i);
-  assert.match(waves, /writes inline Receipts and Status updates one task at a\s+time/i);
+  assert.match(waves, /writes inline Receipts and Status one task at a time/i);
 
   const protocols = regionsByName.get('sync protocols').primary;
   assert.match(protocols, /`plan\.md` and flat `task-\*\.md` files/i);
@@ -819,6 +877,267 @@ test('R7 Develop and Sync surfaces teach process-v3 and isolate hierarchical Leg
   assert.match(legacyCorpus, /sync-finalize/i);
 });
 
+test('Develop process-first source contract preserves selection, recovery, final-Head, parallel, and Flash boundaries', () => {
+  const develop = markdownLegacyRegions(read(DEVELOP)).primary;
+  const quality = read(GATE);
+  const waves = markdownLegacyRegions(read(PARALLEL_WAVES)).primary;
+  const dispatch = read(path.join(path.dirname(PARALLEL_WAVES), 'subagent-patterns.md'));
+
+  for (const clause of [
+    /first dependency-valid `pending` row in `plan\.md` order/i,
+    /Specific-task\s+mode never touches a sibling/i,
+    /More than one `in_progress`/i,
+    /For an interrupted `in_progress` task/i,
+    /only the controller writes Status or Receipt/i,
+    /do not research, replan, or add a routine user gate/i,
+  ]) assert.match(develop, clause);
+  assert.match(quality, /consecutive Head captures are identical/i);
+  assert.match(quality, /skip, skipped, todo, cancel, canceled, cancelled/i);
+  assert.match(quality, /exact command, current Head, required proof level, oracle/i);
+  assert.match(waves, /every commit[\s\S]*complete changed tree/i);
+  assert.match(waves, /handoff metadata cannot substitute/i);
+  assert.match(develop, /later explicit non-Flash invocation may recover/i);
+  assert.match(dispatch, /controller alone writes Status and inline Receipt/i);
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-plan-native-'));
+  try {
+    const featureDir = path.join(root, 'specs', 'ordered');
+    fs.mkdirSync(featureDir, { recursive: true });
+    fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Ordered\nSpecs-Contract: process-first-ready-v1\n');
+    const task = (status, dependencies, receipt = '<!-- Fill only after execution. -->') =>
+      `# Task\n\nStatus: ${status}\n\n## Dependencies\n\n${dependencies}\n\n## Verification Plan\n\n- Command: \`node --test\`\n\n## Receipt\n\n${receipt}\n`;
+    fs.writeFileSync(path.join(featureDir, 'task-01-first.md'), task('pending', '- none'));
+    fs.writeFileSync(path.join(featureDir, 'task-02-second.md'), task('pending', '- task-01-first.md'));
+    initFixtureGit(root);
+
+    let candidate = RESOLVER.resolveWorkflowCandidate({ projectRoot: root, explicitFeature: 'ordered' });
+    assert.equal(candidate.queueReady, true);
+    assert.deepEqual(Object.keys(candidate.taskRegistry), ['task-01-first.md', 'task-02-second.md']);
+    let runtime = PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root, specsRoot: path.join(root, 'specs'), specFile: candidate.planFile,
+      featureName: 'ordered', runtimeSession: 'plan-native-test',
+    });
+    const preMutationHead = runtime.head;
+    fs.mkdirSync(path.join(root, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'src', 'app.js'), 'later worktree mutation\n');
+    runtime = PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root, specsRoot: path.join(root, 'specs'), specFile: candidate.planFile,
+      featureName: 'ordered', runtimeSession: 'plan-native-test',
+    });
+    assert.notEqual(runtime.head, preMutationHead, 'a later non-Spec mutation must stale the earlier Head');
+    const stableRuntime = PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root, specsRoot: path.join(root, 'specs'), specFile: candidate.planFile,
+      featureName: 'ordered', runtimeSession: 'plan-native-test',
+    });
+    assert.equal(stableRuntime.head, runtime.head, 'unchanged consecutive captures must reach a fixed point');
+    let dependencies = RECEIPTS.workflowDependencyProofState(featureDir, candidate.taskRegistry, runtime, POLICY);
+    assert.equal(dependencies['task-01-first.md'].eligible, false);
+
+    const receipt = `Verification: PASS\nCommand: node --test\nExit: 0\nBase: ${runtime.base}\nHead: ${runtime.head}\n\n\`\`\`text\n1 test passed\n\`\`\``;
+    fs.writeFileSync(path.join(featureDir, 'task-01-first.md'), task('done', '- none', receipt));
+    candidate = RESOLVER.resolveWorkflowCandidate({ projectRoot: root, explicitFeature: 'ordered' });
+    runtime = PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root, specsRoot: path.join(root, 'specs'), specFile: candidate.planFile,
+      featureName: 'ordered', runtimeSession: 'plan-native-test',
+    });
+    assert.deepEqual(RECEIPTS.checkWorkflowTaskReceipt(
+      featureDir, 'task-01-first.md', runtime, POLICY,
+    ).failures, []);
+    dependencies = RECEIPTS.workflowDependencyProofState(featureDir, candidate.taskRegistry, runtime, POLICY);
+    assert.equal(dependencies['task-01-first.md'].eligible, true);
+    assert.equal(candidate.taskRegistry['task-02-second.md'].dependencies[0], 'task-01-first.md');
+
+    fs.writeFileSync(path.join(featureDir, 'task-01-first.md'), task('in_progress', '- none'));
+    fs.writeFileSync(path.join(featureDir, 'task-02-second.md'), task('in_progress', '- task-01-first.md'));
+    candidate = RESOLVER.resolveWorkflowCandidate({ projectRoot: root, explicitFeature: 'ordered' });
+    assert.equal(Object.values(candidate.taskRegistry).filter(({ status }) => status === 'in_progress').length, 2);
+
+    fs.writeFileSync(path.join(featureDir, 'task-01-first.md'), task('paused', '- none'));
+    fs.writeFileSync(path.join(featureDir, 'task-02-second.md'), task('blocked', '- task-01-first.md'));
+    candidate = RESOLVER.resolveWorkflowCandidate({ projectRoot: root, explicitFeature: 'ordered' });
+    assert.equal(candidate.taskRegistry['task-01-first.md'].status, 'paused');
+    assert.equal(candidate.taskRegistry['task-02-second.md'].status, 'blocked');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('Claude installed Develop preserves plan-native execution and references', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-claude-develop-'));
+  try {
+    const result = installClaude(root);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    const sourceRoot = path.dirname(DEVELOP);
+    const installedRoot = path.join(root, '.claude/skills/develop');
+    for (const relative of ['SKILL.md', ...DEVELOP_REFERENCES.map((name) => `references/${name}`)]) {
+      assert.equal(
+        fs.readFileSync(path.join(installedRoot, relative), 'utf8'),
+        fs.readFileSync(path.join(sourceRoot, relative), 'utf8'),
+        `Claude Develop projection drifted: ${relative}`,
+      );
+    }
+    assert.equal(fs.existsSync(path.join(root, '.agents/skills/develop')), false);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('Test process-first handoff preserves proof ownership and side-effect boundaries', () => {
+  const skill = read(TEST_SKILL);
+  const strategy = read(path.join(TEST_SOURCE_ROOT, 'references/execution-strategy.md'));
+  const runner = read(TEST_RUNNER);
+  const review = read(CODE_REVIEW_SKILL);
+  const developConsumers = [read(DEVELOP), read(GATE), read(path.join(
+    path.dirname(PARALLEL_WAVES), 'subagent-patterns.md',
+  ))].join('\n');
+
+  const exactKeys = [
+    'schema_version', 'target', 'verdict', 'command', 'exit', 'counts',
+    'provenance', 'proof_level', 'expected', 'observed', 'reachability',
+    'artifacts', 'branches', 'raw_output', 'redactions', 'payload_sha256',
+  ];
+  for (const key of exactKeys) assert.match(strategy, new RegExp(`\\b${key}\\b`));
+  const developHandoffFields = new Map([
+    ['command', /Verification handoff separately contains the fresh command/i],
+    ['exit', /fresh command, exit/i],
+    ['branches', /named probes/i],
+    ['counts', /counts, output/i],
+    ['raw_output', /counts, output/i],
+    ['provenance', /observed Head/i],
+    ['reachability', /runtime reachability/i],
+    ['proof_level', /required proof level/i],
+  ]);
+  for (const [field, sourceClause] of developHandoffFields) {
+    assert.match(developConsumers, sourceClause, `Develop must currently consume ${field}`);
+    assert.ok(exactKeys.includes(field), `test-proof-v1 must preserve Develop field ${field}`);
+  }
+  assert.match(runner, /Emit only `schema_version: "test-proof-v1"`/);
+  assert.match(runner, /sole writer of[\s\S]*Status and inline Receipt/i);
+  assert.match(review, /consume only the controller-validated[\s\S]*`test-proof-v1`[\s\S]*handoff/i);
+  assert.match(review, /Never create or search for a separate[\s\S]*process-first receipt/i);
+  assert.doesNotMatch([skill, strategy, runner].join('\n'), /npm\s+install|inject-auth\.js|--cookies\s|Bearer eyJ/);
+
+  const stable = (value) => {
+    if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+    if (value && typeof value === 'object') return `{${Object.keys(value).sort()
+      .map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+    return JSON.stringify(value);
+  };
+  const proof = {
+    schema_version: 'test-proof-v1',
+    target: { feature: 'fixture', task_path: 'specs/fixture/task-01-proof.md' },
+    verdict: 'PASS', command: 'node --test', exit: 0,
+    counts: { executed: 1, passed: 1, failed: 0, skipped: 0 },
+    provenance: { base: 'a'.repeat(40), head: 'b'.repeat(64) },
+    proof_level: 'source', expected: 'named probe passes', observed: 'named probe passed',
+    reachability: { status: 'PASS', evidence: ['test-runner -> controller'] },
+    artifacts: [],
+    branches: [{
+      id: 'fixture named probe', required: true, verdict: 'PASS', command: 'node --test',
+      exit: 0, counts: { executed: 1, passed: 1, failed: 0, skipped: 0 },
+      proof_level: 'source',
+    }],
+    raw_output: '1 test passed', redactions: [],
+  };
+  proof.payload_sha256 = crypto.createHash('sha256').update(stable(proof)).digest('hex');
+  assert.deepEqual(Object.keys(proof).sort(), exactKeys.slice().sort());
+  assert.match(proof.payload_sha256, /^[a-f0-9]{64}$/);
+  assert.equal(proof.counts.executed, proof.branches.reduce(
+    (sum, branch) => sum + branch.counts.executed, 0,
+  ));
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-test-proof-side-effects-'));
+  const absentRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-test-proof-memory-absent-'));
+  const externalTemp = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-test-owned-'));
+  try {
+    fs.mkdirSync(path.join(root, '.hapo'), { recursive: true });
+    const memory = path.join(root, '.hapo/test-memory.json');
+    fs.writeFileSync(memory, '{"known_issues":[]}\n');
+    fs.writeFileSync(path.join(root, '.gitignore'), 'ignored-proof-state/\n');
+    fs.writeFileSync(path.join(root, 'tracked.js'), 'before\n');
+    initFixtureGit(root);
+    const memoryBefore = crypto.createHash('sha256').update(fs.readFileSync(memory)).digest('hex');
+    const command = spawnSync(process.execPath, ['-e', [
+      "const fs=require('node:fs');",
+      "fs.appendFileSync('tracked.js','after\\n');",
+      "fs.writeFileSync('untracked-proof.txt','created by project command\\n');",
+      "fs.mkdirSync('ignored-proof-state',{recursive:true});",
+      "fs.writeFileSync('ignored-proof-state/output.txt','project output\\n');",
+      "console.log('tests 1\\npass 1\\nfail 0\\nskipped 0');",
+    ].join('')], { cwd: root, encoding: 'utf8' });
+    assert.equal(command.status, 0, command.stderr);
+    assert.match(command.stdout, /tests 1/);
+    const drift = spawnSync('git', [
+      '-C', root, 'status', '--porcelain=v1', '--ignored', '--untracked-files=all',
+    ], { encoding: 'utf8' });
+    assert.equal(drift.status, 0, drift.stderr);
+    assert.match(drift.stdout, / M tracked\.js/);
+    assert.match(drift.stdout, /\?\? untracked-proof\.txt/);
+    assert.match(drift.stdout, /!! ignored-proof-state\//);
+    const memoryAfter = crypto.createHash('sha256').update(fs.readFileSync(memory)).digest('hex');
+    assert.equal(memoryAfter, memoryBefore, 'present Test memory must stay byte-identical');
+    for (const relative of ['test-report.md', 'test-cache', 'test-auth.json']) {
+      assert.equal(fs.existsSync(path.join(root, '.hapo', relative)), false, `${relative} must stay absent`);
+    }
+    assert.equal(fs.existsSync(path.join(root, 'node_modules')), false, 'project-local lazy install must stay absent');
+
+    const absentMemory = path.join(absentRoot, '.hapo/test-memory.json');
+    assert.equal(fs.existsSync(absentMemory), false);
+    const noop = spawnSync(process.execPath, ['-e', "console.log('tests 1; pass 1')"], {
+      cwd: absentRoot, encoding: 'utf8',
+    });
+    assert.equal(noop.status, 0, noop.stderr);
+    assert.equal(fs.existsSync(absentMemory), false, 'absent Test memory must stay absent');
+
+    fs.writeFileSync(path.join(externalTemp, 'ephemeral.txt'), 'proof temp\n');
+  } finally {
+    fs.rmSync(externalTemp, { recursive: true, force: true });
+    fs.rmSync(absentRoot, { recursive: true, force: true });
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  assert.equal(fs.existsSync(externalTemp), false, 'Test-owned external temp must be cleaned');
+});
+
+test('Claude installed Test preserves plan-native proof and references', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-claude-test-proof-'));
+  try {
+    const result = installClaude(root);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    const installedRoot = path.join(root, '.claude/skills/test');
+    for (const relative of ['SKILL.md', ...TEST_REFERENCES.map((name) => `references/${name}`)]) {
+      assert.equal(
+        fs.readFileSync(path.join(installedRoot, relative), 'utf8'),
+        fs.readFileSync(path.join(TEST_SOURCE_ROOT, relative), 'utf8'),
+        `Claude Test projection drifted: ${relative}`,
+      );
+    }
+    const installedRunner = fs.readFileSync(path.join(root, '.claude/agents/test-runner.md'), 'utf8');
+    assert.equal(installedRunner, fs.readFileSync(TEST_RUNNER, 'utf8'));
+    assert.match(installedRunner, /test-proof-v1/);
+    const installedReview = fs.readFileSync(path.join(root, '.claude/skills/code-review/SKILL.md'), 'utf8');
+    assert.equal(installedReview, fs.readFileSync(CODE_REVIEW_SKILL, 'utf8'));
+    assert.match(installedReview, /controller-validated `test-proof-v1`/);
+    assert.match(installedReview, /Do not load or follow legacy separate-receipt paragraphs/i);
+    assert.equal(fs.existsSync(path.join(root, '.agents/skills/test')), false);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('specs-usage-guide documents Test proof handoff without timing claims', () => {
+  const guide = read(SPECS_USAGE_GUIDE);
+  const section = guide.split('## Test proof handoff')[1]?.split('### Receipt canonical')[0] || '';
+  assert.match(section, /`test-proof-v1`/);
+  assert.match(section, /Test không ghi `Status:` hay inline[\s\S]*Develop controller là writer duy nhất/i);
+  assert.match(section, /tracked\/untracked\/ignored drift/i);
+  assert.match(section, /HTTPS\/localhost origin[\s\S]*fresh consent/i);
+  assert.match(section, /separate-receipt adapter/i);
+  assert.match(section, /không phải benchmark thời gian/i);
+  assert.match(section, /không chứng minh live adherence/i);
+  assert.doesNotMatch(section, /\b\d+(?:\.\d+)?\s*(?:ms|milliseconds?|seconds?|minutes?)\b/i);
+  assert.doesNotMatch(section, /\[(?:LIVE_)?VERIFIED\]/i);
+});
+
 test('canonical verdict adapter handles completion and unfinished decisions', () => {
   assert.deepEqual(POLICY.REVIEW_VERDICTS, ['PASS', 'PASS_WITH_WARNINGS', 'FAIL', 'BLOCKED']);
   assert.doesNotThrow(() => POLICY.assertVerdict('PASS_WITH_WARNINGS'));
@@ -971,7 +1290,7 @@ test('auto authoring reaches readiness only after promotion, validation, groundi
 
     const specs = read(SPECS);
     const executableBlocks = [...specs.matchAll(/```bash\n([\s\S]*?)```/g)].map((match) => match[1]);
-    assert.ok(executableBlocks.every((block) => !/hapo:?develop/i.test(block)), 'Specs must never execute Develop');
+    assert.ok(executableBlocks.every((block) => !/cf:?develop/i.test(block)), 'Specs must never execute Develop');
     assert.match(specs, /An implementation workflow owns execution/i);
     assert.match(specs, /selects one unblocked task[\s\S]*runs\s+the task's verification[\s\S]*inline `## Receipt`/i);
     assert.match(specs, /The user decides\s+at C3 whether the feature is done/i);
@@ -1265,8 +1584,6 @@ test('first-run cache bypass is blocked - canonical receipt required even withou
     );
     // Clear cache to simulate fresh first-run with valid receipt
     try { fs.unlinkSync(path.join(claude, 'hooks', '.logs', 'spec-gate-last.json')); } catch {}
-    try { fs.unlinkSync(path.join(__dirname, '..', '.logs', 'spec-gate-last.json')); } catch {}
-    // Need to clear the cache that the hook uses (under claude hooks .logs) - we already cleared above
     // Re-run with valid receipt - should not block
     const result2 = spawnSync(process.execPath, [specGate], {
       cwd: root,
@@ -1277,7 +1594,6 @@ test('first-run cache bypass is blocked - canonical receipt required even withou
     assert.equal(result2.stdout, '', 'valid canonical receipt on first run must not block');
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
-    try { fs.unlinkSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/.logs/spec-gate-last.json')); } catch {}
   }
 });
 
@@ -1415,6 +1731,20 @@ test('runtime provenance derives exact Git evidence, CLI context, and stale/forg
       'valid-shaped arbitrary SHA values must not bind',
     );
 
+    fs.writeFileSync(specFile, JSON.stringify({
+      status: 'in_progress',
+      feature_name: 'demo',
+      task_registry: {},
+      receipt_refresh: true,
+    }));
+    const specCommit = spawnSync('git', ['-C', root, 'add', 'specs/demo/spec.json'], { encoding: 'utf8' });
+    assert.equal(specCommit.status, 0, specCommit.stderr);
+    const commitReceipt = spawnSync('git', ['-C', root, 'commit', '-qm', 'refresh spec receipt'], { encoding: 'utf8' });
+    assert.equal(commitReceipt.status, 0, commitReceipt.stderr);
+    const afterSpecOnlyCommit = PROVENANCE_HELPER.deriveRuntimeContext(input);
+    assert.equal(afterSpecOnlyCommit.base, initial.base, 'spec-only commits must not stale receipt Base');
+    assert.equal(afterSpecOnlyCommit.head, initial.head, 'spec-only commits must not stale receipt Head');
+
     const cli = spawnSync(process.execPath, [
       path.join(PACKAGE_ROOT, 'src/claude/scripts/provenance.cjs'), '--json',
       '--project-root', root, '--specs-root', specsRoot, '--spec-file', specFile,
@@ -1522,6 +1852,52 @@ test('runtime provenance derives exact Git evidence, CLI context, and stale/forg
   }
 });
 
+test('runtime provenance chooses a deterministic root when all history is Specs-only and multi-root', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-provenance-multi-root-'));
+  const specsRoot = path.join(root, 'specs');
+  const featureRoot = path.join(specsRoot, 'demo');
+  const specFile = path.join(featureRoot, 'spec.json');
+  try {
+    fs.mkdirSync(featureRoot, { recursive: true });
+    fs.writeFileSync(specFile, JSON.stringify({ status: 'in_progress', feature_name: 'demo', task_registry: {} }));
+    for (const args of [
+      ['init', '-q', '-b', 'first-root'],
+      ['config', 'user.email', 'cafekit@example.invalid'],
+      ['config', 'user.name', 'CafeKit Test'],
+      ['add', 'specs/demo/spec.json'],
+      ['commit', '-qm', 'first specs root'],
+      ['checkout', '--orphan', 'unrelated-specs'],
+      ['rm', '-qrf', '.'],
+    ]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    const unrelatedSpec = path.join(specsRoot, 'unrelated', 'spec.json');
+    fs.mkdirSync(path.dirname(unrelatedSpec), { recursive: true });
+    fs.writeFileSync(unrelatedSpec, JSON.stringify({ status: 'in_progress', feature_name: 'unrelated', task_registry: {} }));
+    let result = spawnSync('git', ['-C', root, 'add', 'specs/unrelated/spec.json'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    result = spawnSync('git', ['-C', root, 'commit', '-qm', 'second specs root'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    result = spawnSync('git', ['-C', root, 'merge', '--allow-unrelated-histories', '-qm', 'merge specs roots', 'first-root'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+
+    const roots = spawnSync('git', ['-C', root, 'rev-list', '--max-parents=0', '--reverse', 'HEAD'], { encoding: 'utf8' });
+    assert.equal(roots.status, 0, roots.stderr);
+    const expectedBase = roots.stdout.trim().split('\n')[0].toLowerCase();
+    const context = PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root,
+      specsRoot,
+      specFile,
+      featureName: 'demo',
+      runtimeSession: 'multi-root-session',
+    });
+    assert.equal(context.base, expectedBase);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('lane traces - Direct, Standard, explicit Strict classification, override, state mutation and completion', () => {
   // Direct: isolated reversible low-risk
   const direct = POLICY.classifyLane({ reversible: true, lowRisk: true, isolated: true, taskCount: 1 });
@@ -1595,26 +1971,27 @@ test('flash selective promotion - only specific task is promoted, not blanket',
 test('parallel waves require immutable provenance receipts and safe recovery', () => {
   const waves = markdownLegacyRegions(read(PARALLEL_WAVES)).primary;
   assert.match(waves, /only for explicit parallel execution/i);
-  assert.match(waves, /worktree isolation[\s\S]*fall back to the sequential loop/i);
+  assert.match(waves, /isolated worktree support[\s\S]*fall back to the sequential loop/i);
   assert.match(waves, /Clamp `--parallel N` to 1\.\.5; default to 3/i);
-  assert.match(waves, /clean destination[\s\S]*base_sha[\s\S]*base compatibility/i);
-  assert.match(waves, /parallel consent[\s\S]*worker commits[\s\S]*controller cherry-picks/i);
+  assert.match(waves, /clean destination[\s\S]*base_sha[\s\S]*incompatible bases/i);
+  assert.match(waves, /consent for worker commits and controller cherry-picks/i);
   for (const field of ['base_sha', 'head_sha', 'branch', 'worktree_path', 'commit_range']) {
     assert.match(waves, new RegExp(`\\b${field}\\b`));
   }
-  assert.match(waves, /git diff(?: --stat)? [^\\n]*(?:BASE_SHA|base_sha)[^\\n]*(?:HEAD_SHA|head_sha)/i);
-  assert.match(waves, /new commit|new commits|Every fix is a new commit/i);
-  assert.match(waves, /plan task table[\s\S]*flat task's[\s\S]*Dependencies/i);
+  assert.match(waves, /git rev-list --reverse <base_sha>\.\.<head_sha>/i);
+  assert.match(waves, /git diff --name-status <base_sha>\.\.<head_sha>/i);
+  assert.match(waves, /code\/spec repair[\s\S]*new commit/i);
+  assert.match(waves, /dependencies from the plan table and each task/i);
   for (const sharedSurface of ['registry', 'lockfile', 'manifest', 'generated output', 'migration', 'export barrel']) {
     assert.match(waves, new RegExp(sharedSurface, 'i'));
   }
   assert.match(waves, /One file has one writer per wave/i);
-  assert.match(waves, /controller owns[\s\S]*state and evidence synchronization/i);
-  assert.match(waves, /authorization covers worker commits/i);
+  assert.match(waves, /only the controller writes state\/proof/i);
+  assert.match(waves, /commit only with user authorization/i);
   assert.match(waves, /blocked or failed worker keeps[\s\S]*worktree and branch/i);
   assert.match(waves, /Never[\s\S]*force-delete[\s\S]*merge success or explicit discard authorization/i);
-  assert.match(waves, /git cherry-pick <worker-commit>/i);
-  assert.match(waves, /On conflict, abort the cherry-pick[\s\S]*retain its[\s\S]*worktree\/branch/i);
+  assert.match(waves, /git cherry-pick <next-worker-commit>/i);
+  assert.match(waves, /On conflict, abort the pick[\s\S]*retain its branch\/worktree/i);
   assert.match(waves, /cleanup_authorization: merged-release/i);
   assert.match(waves, /affected integration|final.*integration/i);
   for (const category of ['baseline', 'environment', 'spec', 'code']) {
@@ -2305,7 +2682,7 @@ test('P0 receipt fail-closed: Exit 1/-1/abc/conflict/empty command rejected', ()
 });
 
 test('P0 flash marker-only must not promote or finalize', () => {
-  const flash = canonicalFlashTask({ blocker: 'awaiting /hapo:test' });
+  const flash = canonicalFlashTask({ blocker: 'awaiting /cf:test' });
   const markerOnly = 'Verification: PASS';
   const promoted = POLICY.promoteFlashTask(flash, 'PASS', markerOnly);
   assert.equal(promoted.status, 'in_progress');
@@ -2388,7 +2765,7 @@ test('P0 sync-finalize derives promotion from current FLASH_UNVERIFIED plus expl
   assert.equal(forgedOpenResult.status, 'in_progress');
   assert.equal(forgedOpenResult.unblocks, false);
 
-  const current = canonicalFlashTask({ blocker: 'awaiting /hapo:test' });
+  const current = canonicalFlashTask({ blocker: 'awaiting /cf:test' });
   const supported = spawnSync(process.execPath, [
     POLICY_PATH,
     '--sync-finalize',
@@ -2961,3 +3338,45 @@ test('P0 canonical phantom vectors - zero, cancellation, suite, FAIL, error, col
   assert.equal(POLICY.isTapMetadataHeading('# Notes'), false);
   assert.equal(POLICY.isTapMetadataHeading('# pass 1 explanation'), false);
 });
+
+test('generated runtime state under every platform folder stays out of the worktree digest', () => {
+  // The gate writes its cache and the installer writes runtime.json under the platform
+  // folder on every run. If those writes moved Head, a project tracking its runtime
+  // directory could never hold a stable receipt. The exclusion list must name each
+  // shipped platform, and a real source change must still move Head.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-state-roots-'));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'], ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    fs.mkdirSync(path.join(root, 'specs', 'demo'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'specs', 'demo', 'plan.md'), '# Demo plan\n');
+    const derive = () => PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root,
+      specsRoot: path.join(root, 'specs'),
+      specFile: path.join(root, 'specs', 'demo', 'plan.md'),
+      featureName: 'demo',
+      runtimeSession: 'state-roots',
+    });
+    const before = derive();
+
+    for (const folder of ['.claude', '.codex', '.omp']) {
+      fs.mkdirSync(path.join(root, folder, 'hooks', '.logs'), { recursive: true });
+      fs.mkdirSync(path.join(root, folder, '.logs'), { recursive: true });
+      fs.writeFileSync(path.join(root, folder, 'hooks', '.logs', 'spec-gate-last.json'), '{"demo":{}}\n');
+      fs.writeFileSync(path.join(root, folder, '.logs', 'hook-log.jsonl'), '{}\n');
+      fs.writeFileSync(path.join(root, folder, 'runtime.json'), '{"spec":{"completion_gate":true}}\n');
+    }
+    const afterState = derive();
+    assert.equal(afterState.head, before.head, 'runtime state under .claude, .codex, and .omp must not move Head');
+    assert.equal(afterState.base, before.base);
+
+    // Anything else under the platform folder is source: a hook edit must move Head.
+    fs.mkdirSync(path.join(root, '.omp', 'hooks'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.omp', 'hooks', 'rules.cjs'), '// edited\n');
+    assert.notEqual(derive().head, before.head, 'a real file under the platform folder must still move Head');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});