@haposoft/cafekit 0.16.0-rc.4 → 0.16.0-rc.5

package/bin/__tests__/review-receipt-c2.semantic-firewall.test.js

@@ -0,0 +1,378 @@
+'use strict';
+
+// R1-01 owned proof: frozen C2 SemanticReviewReceipt (verdict vs
+// lifecycle_disposition, structural-only checks per R3.4), C13
+// SemanticReviewHistory (exact keys, whole-lineage digest dedupe), and C16
+// AuthoringValidationReceipt (the sole spec-authoring-validation.cjs atomic
+// writer, fail-closed freshness in validate-spec-output.cjs).
+
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const test = require('node:test');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../..');
+const SCAFFOLD = path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-scaffold.cjs');
+const VALIDATOR = path.join(PACKAGE_ROOT, 'src/claude/scripts/validate-spec-output.cjs');
+const AUTHORING_VALIDATOR = path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-authoring-validation.cjs');
+
+function exec(root, script, args) {
+  return spawnSync(process.execPath, [script, ...args], { cwd: root, encoding: 'utf8' });
+}
+
+function output(result) { return `${result.stdout}\n${result.stderr}`; }
+
+function writeSpec(specPath, spec) {
+  fs.writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+}
+
+function readSpec(specPath) {
+  return JSON.parse(fs.readFileSync(specPath, 'utf8'));
+}
+
+function task(id, title, ownedPath, action, criterion, taskRole) {
+  return `# Task ${id}: ${title}
+**Status:** pending
+
+## Outcome
+Deliver observable ${title.toLowerCase()} behavior through the declared entrypoint.
+
+## Scope
+- **In scope:** Exact behavior for ${ownedPath}.
+- **Out of scope:** Unrelated runtime behavior.
+
+## Anchors and Ownership
+| ID | Type | Target | Role | Access | Action |
+|---|---|---|---|---|---|
+| A-${id}-01 | file | \`${ownedPath}\` | owner | write | ${action} |
+| A-${id}-02 | artifact | \`artifacts/${id}.json\` | verifier | write | create |
+
+## Changes
+${criterion ? `- [ ] Implement the owned behavior. _Requirements: ${criterion.slice(1)}_` : '- [ ] Verify the subject implementation through the canonical proof boundary.'}
+
+## Acceptance
+${criterion ? `- **${criterion}:** The command returns the concrete expected state.` : '- The verifier produces an observable proof artifact without claiming the subject acceptance criterion.'}
+
+## Dependencies
+- none
+
+## Verification Plan
+- **Verification ref:** V1
+- **Task role:** ${taskRole}
+- **Command:** \`node --test test/service.test.js\`
+- **Expected:** Exit code 0 and exact state enabled.
+- **Negative path:** Invalid input returns the specified failure state.
+- **Reachability:** \`src/entry.js\`
+`;
+}
+
+// A ready, coordinator-validated fixture. C16's own receipt is produced by
+// the real spec-authoring-validation.cjs coordinator, never hand-written, so
+// every test here starts from a byte-accurate receipt.
+function makeReadyFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-c2-'));
+  fs.mkdirSync(path.join(root, 'src'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'test'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'artifacts'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'src/entry.js'), 'module.exports = { enabled: true };\n');
+  fs.writeFileSync(path.join(root, 'src/service.js'), 'module.exports = { enabled: true };\n');
+  fs.writeFileSync(path.join(root, 'test/service.test.js'), 'require("node:test")("service",()=>{});\n');
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ scripts: { test: 'node --test' } }));
+  const boundaries = [{
+    id: 'B-OWN', type: 'ownership', tasks: ['R1-01', 'R1-02'],
+    write_sets: {
+      'R1-01': ['src/entry.js', 'artifacts/R1-01.json'],
+      'R1-02': ['src/service.js', 'artifacts/R1-02.json'],
+    },
+  }, {
+    id: 'B-V', type: 'proof', subject: 'R1-01', verifier: 'R1-02',
+    verification_ref: 'V1', artifact_anchor: 'A-R1-02-02',
+  }];
+  const scaffold = exec(root, SCAFFOLD, ['feature', '--tasks', 'R1-01-entry,R1-02-verify', '--boundaries', JSON.stringify(boundaries)]);
+  assert.equal(scaffold.status, 0, scaffold.stderr);
+  const specDir = path.join(root, 'specs/feature');
+  fs.writeFileSync(path.join(specDir, 'requirements.md'), `# Requirements
+
+## Requirements
+### Requirement 1: Entry behavior
+- **R1.1**: When valid input arrives, the entry shall return enabled state.
+- **R1.2**: The verifier shall produce a separate observable proof artifact for the enabled state.
+`);
+  fs.writeFileSync(path.join(root, 'src/design-boundary.js'), 'module.exports = {};\n');
+  fs.writeFileSync(path.join(specDir, 'design.md'), `# Design
+
+## Architecture
+The entry delegates to the service and emits a verifier-owned artifact.
+
+## Typed Anchors
+| ID | Type | Target | Role | Access | Action |
+|---|---|---|---|---|---|
+| A-D-01 | file | \`src/design-boundary.js\` | design boundary | read | read |
+
+## Canonical Contracts & Invariants
+### D1 — Entry decision
+The entry always returns enabled true on valid input.
+### I1 — Invalid-state invariant
+Invalid input never returns enabled state.
+### C1 — Result contract
+The result contains an enabled boolean.
+
+## Verification Definitions
+- **V1**: Criteria R1.1; Owner R1-01; Proof criteria R1.2; Proof owner R1-02; Evidence anchor A-R1-02-02; Decision refs D1, I1, C1; Method command \`node --test test/service.test.js\`; Expected exit 0 with enabled state and verifier artifact; Negative/failure invalid input returns rejected state without an enabled result; Reachability/grounding entrypoint \`src/entry.js\` via A-D-01, A-R1-02-02.
+`);
+  fs.writeFileSync(path.join(specDir, 'tasks/task-R1-01-entry.md'), task('R1-01', 'Entry', 'src/entry.js', 'modify', 'R1.1', 'subject'));
+  fs.writeFileSync(path.join(specDir, 'tasks/task-R1-02-verify.md'), task('R1-02', 'Verify', 'src/service.js', 'modify', 'R1.2', 'verifier'));
+  const promoted = exec(root, SCAFFOLD, ['feature', '--sync-semantic-model']);
+  assert.equal(promoted.status, 0, output(promoted));
+  const specPath = path.join(specDir, 'spec.json');
+  const coordinated = exec(root, AUTHORING_VALIDATOR, [specDir]);
+  assert.equal(coordinated.status, 0, output(coordinated));
+  const spec = readSpec(specPath);
+  spec.validation.status = 'completed';
+  spec.validation.semantic_review = {
+    status: 'completed',
+    semantic_digest: null,
+    verdict: 'PASS',
+    lifecycle_disposition: 'CONTINUE',
+    findings: [],
+    unresolved_decisions: [],
+    graph_coverage: [
+      'criterion_local', 'cross_criterion', 'runtime_path', 'assumption_provenance', 'compatibility_migration',
+    ].map((surface) => ({ surface, covered: true, notes: 'Fixture coverage.' })),
+    repair_round: 0,
+    reviewed_criteria: ['R1.1', 'R1.2'],
+    counterexamples: [{
+      criterion: 'R1.1', case_kind: 'failure',
+      scenario: 'The entry receives an invalid input object without the required discriminator.',
+      expected: 'The entry returns rejected state and never emits enabled true.',
+      decision_refs: ['D1', 'I1', 'C1'], verification_ref: 'V1',
+    }, {
+      criterion: 'R1.2', case_kind: 'adversarial',
+      scenario: 'The implementation reports enabled state without producing the verifier-owned artifact.',
+      expected: 'Verification fails because the separate proof artifact is absent.',
+      decision_refs: ['D1', 'I1', 'C1'], verification_ref: 'V1',
+    }],
+    reviewer_evidence: { assurance: 'Routine', summary: 'Fixture reviewer evidence for structural contract test.' },
+  };
+  writeSpec(specPath, spec);
+  const digest = exec(root, VALIDATOR, [specDir, '--semantic-digest']);
+  assert.equal(digest.status, 0, output(digest));
+  const refreshed = readSpec(specPath);
+  refreshed.validation.semantic_review.semantic_digest = digest.stdout.trim();
+  refreshed.ready_for_implementation = true;
+  writeSpec(specPath, refreshed);
+  return { root, specDir, specPath };
+}
+
+function cleanup(fixture) {
+  fs.rmSync(fixture.root, { recursive: true, force: true });
+}
+
+function sha256Tag(bytes) {
+  return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+test('C2 receipt freezes the exact key set with separate verdict and lifecycle_disposition', () => {
+  const fixture = makeReadyFixture();
+  try {
+    const clean = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(clean.status, 0, output(clean));
+    // Snapshot the known-clean baseline once; every mutation below clones it
+    // fresh so one case's leftover mutation never contaminates the next.
+    const baseline = readSpec(fixture.specPath);
+
+    const missingLifecycle = JSON.parse(JSON.stringify(baseline));
+    missingLifecycle.validation.semantic_review.lifecycle_disposition = null;
+    writeSpec(fixture.specPath, missingLifecycle);
+    const result1 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result1.status, 1, output(result1));
+    assert.match(output(result1), /lifecycle_disposition: must be CONTINUE or BLOCKED when completed/);
+
+    const extraKey = JSON.parse(JSON.stringify(baseline));
+    extraKey.validation.semantic_review.reviewer_note = 'not a canonical C2 field';
+    writeSpec(fixture.specPath, extraKey);
+    const result2 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result2.status, 1, output(result2));
+    assert.match(output(result2), /semantic_review: schema 2\.1 fields must be exactly/);
+
+    const conflated = JSON.parse(JSON.stringify(baseline));
+    conflated.validation.semantic_review.verdict = 'FAIL';
+    conflated.validation.semantic_review.lifecycle_disposition = 'CONTINUE';
+    writeSpec(fixture.specPath, conflated);
+    const result3 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    // R3.4: structural validator enforces shape/type/enum/cardinality only —
+    // it does not judge whether a FAIL+CONTINUE pairing is a meaningful
+    // review outcome (that policy belongs to the R1-02 finalizer).
+    assert.equal(result3.status, 0, output(result3));
+  } finally { cleanup(fixture); }
+});
+
+test('sync migrates an exact legacy review into a fresh C2/C13/C16 lifecycle even when the semantic model is unchanged', () => {
+  const fixture = makeReadyFixture();
+  try {
+    const legacy = readSpec(fixture.specPath);
+    legacy.validation = {
+      status: 'completed',
+      semantic_review: {
+        status: 'completed',
+        semantic_digest: legacy.validation.semantic_review.semantic_digest,
+        reviewed_criteria: legacy.validation.semantic_review.reviewed_criteria,
+        counterexamples: legacy.validation.semantic_review.counterexamples,
+      },
+    };
+    legacy.ready_for_implementation = true;
+    writeSpec(fixture.specPath, legacy);
+
+    const migrated = exec(fixture.root, SCAFFOLD, ['feature', '--sync-semantic-model']);
+    assert.equal(migrated.status, 0, output(migrated));
+    const next = readSpec(fixture.specPath);
+    assert.equal(next.ready_for_implementation, false);
+    assert.equal(next.validation.status, 'not-run');
+    assert.deepEqual(Object.keys(next.validation).sort(), [
+      'authoring_validation', 'semantic_review', 'semantic_review_history', 'status',
+    ]);
+    assert.equal(next.validation.semantic_review.status, 'not-run');
+    assert.deepEqual(next.validation.semantic_review_history.entries, []);
+    assert.equal(next.validation.authoring_validation, null);
+    assert.equal(next.authoring.requirements, 'draft');
+    assert.equal(next.authoring.design, 'draft');
+    assert.equal(next.authoring.tasks, 'draft');
+  } finally { cleanup(fixture); }
+});
+
+test('C2 findings/unresolved_decisions/graph_coverage/reviewer_evidence enforce exact shape', () => {
+  const fixture = makeReadyFixture();
+  try {
+    const badFinding = readSpec(fixture.specPath);
+    badFinding.validation.semantic_review.findings = [{
+      id: 'F1', severity: 'Severe', location: 'design.md', summary: 'A concrete finding summary.', blocking: false, disposition: 'open',
+    }];
+    writeSpec(fixture.specPath, badFinding);
+    const result1 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result1.status, 1, output(result1));
+    assert.match(output(result1), /findings\[0\]\.severity: must be Critical, High, Medium, or Low/);
+
+    const badCoverage = readSpec(fixture.specPath);
+    badCoverage.validation.semantic_review.graph_coverage = badCoverage.validation.semantic_review.graph_coverage.slice(0, 4);
+    writeSpec(fixture.specPath, badCoverage);
+    const result2 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result2.status, 1, output(result2));
+    assert.match(output(result2), /graph_coverage: missing required surface/);
+
+    const badEvidence = readSpec(fixture.specPath);
+    badEvidence.validation.semantic_review.reviewer_evidence = { assurance: 'Overkill', summary: 'A concrete reviewer summary.' };
+    writeSpec(fixture.specPath, badEvidence);
+    const result3 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result3.status, 1, output(result3));
+    assert.match(output(result3), /reviewer_evidence\.assurance: must be Routine, Elevated, or Strict/);
+  } finally { cleanup(fixture); }
+});
+
+test('C13 semantic_review_history freezes exact keys and dedupes across the whole lineage', () => {
+  const fixture = makeReadyFixture();
+  try {
+    const spec = readSpec(fixture.specPath);
+    const receiptDigestA = sha256Tag(Buffer.from('receipt-a'));
+    const receiptDigestB = sha256Tag(Buffer.from('receipt-b'));
+    const semanticDigest = spec.validation.semantic_review.semantic_digest;
+    spec.validation.semantic_review_history.entries = [
+      {
+        sequence: 0, semantic_digest: semanticDigest, review_receipt_digest: receiptDigestA,
+        verdict: 'FAIL', lifecycle_disposition: 'CONTINUE', blocking_count: 1, attempt_index: 0, review_epoch: 0,
+      },
+      {
+        sequence: 1, semantic_digest: semanticDigest, review_receipt_digest: receiptDigestB,
+        verdict: 'PASS', lifecycle_disposition: 'CONTINUE', blocking_count: 0, attempt_index: 1, review_epoch: 0,
+      },
+    ];
+    writeSpec(fixture.specPath, spec);
+    const clean = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(clean.status, 0, output(clean));
+    // Snapshot the known-clean 2-entry baseline once; every mutation below
+    // clones it fresh so one case's leftover mutation never contaminates the
+    // next (each case must independently isolate the single defect it proves).
+    const baseline = readSpec(fixture.specPath);
+
+    const missingEpoch = JSON.parse(JSON.stringify(baseline));
+    delete missingEpoch.validation.semantic_review_history.entries[0].review_epoch;
+    writeSpec(fixture.specPath, missingEpoch);
+    const result1 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result1.status, 1, output(result1));
+    assert.match(output(result1), /entries\[0\]: fields must be exactly/);
+
+    // Whole-lineage dedupe: a third entry replaying entry 0's digest is a
+    // replay even though entry 0 is not the latest entry.
+    const replay = JSON.parse(JSON.stringify(baseline));
+    replay.validation.semantic_review_history.entries.push({
+      sequence: 2, semantic_digest: semanticDigest, review_receipt_digest: receiptDigestA,
+      verdict: 'PASS', lifecycle_disposition: 'CONTINUE', blocking_count: 0, attempt_index: 2, review_epoch: 0,
+    });
+    writeSpec(fixture.specPath, replay);
+    const result2 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result2.status, 1, output(result2));
+    assert.match(output(result2), /review_receipt_digest: replays an existing entry's digest anywhere in the lineage/);
+
+    const badLineage = JSON.parse(JSON.stringify(baseline));
+    badLineage.validation.semantic_review_history.lineage_id = sha256Tag(Buffer.from('wrong'));
+    writeSpec(fixture.specPath, badLineage);
+    const result3 = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(result3.status, 1, output(result3));
+    assert.match(output(result3), /lineage_id: must be sha256 of feature_name and created_at/);
+  } finally { cleanup(fixture); }
+});
+
+test('C16 coordinator is the sole atomic writer: clean pass writes, a failing pass leaves spec.json untouched', () => {
+  const fixture = makeReadyFixture();
+  try {
+    const before = readSpec(fixture.specPath);
+    assert.equal(before.authoring.requirements, 'validated');
+    assert.equal(before.authoring.design, 'validated');
+    assert.equal(before.authoring.tasks, 'validated');
+    assert.ok(before.validation.authoring_validation);
+    assert.match(before.validation.authoring_validation.requirements.digest, /^sha256:[a-f0-9]{64}$/);
+
+    // Re-running the coordinator on already-fresh bytes is a clean no-op pass.
+    const rerun = exec(fixture.root, AUTHORING_VALIDATOR, [fixture.specDir]);
+    assert.equal(rerun.status, 0, output(rerun));
+
+    // Break grounding (dangling design anchor target) so the coordinator's
+    // own validate+ground pass fails; spec.json bytes must stay identical.
+    const designPath = path.join(fixture.specDir, 'design.md');
+    fs.writeFileSync(designPath, fs.readFileSync(designPath, 'utf8').replace(
+      '| A-D-01 | file | `src/design-boundary.js` | design boundary | read | read |',
+      '| A-D-01 | file | `src/does-not-exist.js` | design boundary | read | read |',
+    ));
+    const beforeBytes = fs.readFileSync(fixture.specPath, 'utf8');
+    const failing = exec(fixture.root, AUTHORING_VALIDATOR, [fixture.specDir]);
+    assert.notEqual(failing.status, 0, output(failing));
+    const afterBytes = fs.readFileSync(fixture.specPath, 'utf8');
+    assert.equal(afterBytes, beforeBytes, 'a failed coordinator run must leave spec.json completely unchanged');
+  } finally { cleanup(fixture); }
+});
+
+test('C16/I20 fail-closed freshness: an edit after validation reverts the stage to draft-equivalent structurally', () => {
+  const fixture = makeReadyFixture();
+  try {
+    const clean = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(clean.status, 0, output(clean));
+
+    // Edit requirements.md after the coordinator already ran; do not rerun the
+    // coordinator. authoring.requirements still reads validated, but its
+    // receipt digest no longer matches the current bytes.
+    fs.appendFileSync(path.join(fixture.specDir, 'requirements.md'), '\nA later edit changes the authored requirement text.\n');
+    const stale = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(stale.status, 1, output(stale));
+    assert.match(output(stale), /spec\.json\.authoring\.requirements: reads validated but validation\.authoring_validation.*digest-mismatched/);
+
+    // An absent receipt with a validated reading is refused identically.
+    const missingReceipt = readSpec(fixture.specPath);
+    missingReceipt.validation.authoring_validation = null;
+    writeSpec(fixture.specPath, missingReceipt);
+    const absent = exec(fixture.root, VALIDATOR, [fixture.specDir]);
+    assert.equal(absent.status, 1, output(absent));
+    assert.match(output(absent), /spec\.json\.authoring\.requirements: reads validated but validation\.authoring_validation is absent/);
+  } finally { cleanup(fixture); }
+});

package/bin/__tests__/specs-v2-execution-closeout.test.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -14,6 +15,8 @@ const PROVENANCE = require(path.join(SCRIPTS, 'provenance.cjs'));
 const RECEIPT = require(path.join(SCRIPTS, 'spec-receipt.cjs'));
 const SCAFFOLD = path.join(SCRIPTS, 'spec-scaffold.cjs');
 const VALIDATOR = path.join(SCRIPTS, 'validate-spec-output.cjs');
+const AUTHORING_VALIDATION = path.join(SCRIPTS, 'spec-authoring-validation.cjs');
+const RUNTIME_CLOSURE = require('./test-runtime-dependency-closure.cjs');
 const SEMANTIC_MODEL = require(path.join(SCRIPTS, 'spec-semantic-model.cjs'));
 const CLAUDE_CHECK = require(path.join(ROOT, 'src/claude/hooks/completion-authority-check.cjs'));
 const CODEX_CHECK = require(path.join(ROOT, 'src/codex/hooks/completion-authority-check.cjs'));
@@ -143,12 +146,41 @@ Only a validated and grounded current digest reaches closeout.
 R1.1 and R1.2 are verified by V1 against D1, I1, and C1.
 `);
   const specPath = path.join(featureDir, 'spec.json');
+  const seed = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+  const seedProjection = SEMANTIC_MODEL.modelFromMarkdown(featureDir, seed);
+  assert.deepEqual(seedProjection.errors, []);
+  seed.semantic_model = seedProjection.model;
+  fs.writeFileSync(specPath, `${JSON.stringify(seed, null, 2)}\n`);
+  // I21: only the C16 coordinator may set an authoring stage to `validated`,
+  // and only together with the digest receipt that proves it fresh. The fixture
+  // runs the real command instead of hand-authoring the enum.
+  const authored = spawnSync(
+    process.execPath,
+    [AUTHORING_VALIDATION, featureDir, '--root', root],
+    { cwd: root, encoding: 'utf8' },
+  );
+  assert.equal(authored.status, 0, `${authored.stdout}\n${authored.stderr}`);
   const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
-  spec.authoring.requirements = 'validated';
-  spec.authoring.design = 'validated';
+  assert.equal(spec.authoring.requirements, 'validated');
+  assert.equal(spec.authoring.design, 'validated');
   spec.validation.status = 'completed';
   spec.validation.semantic_review = {
-    status: 'completed', semantic_digest: null, reviewed_criteria: ['R1.1', 'R1.2'],
+    status: 'completed',
+    semantic_digest: null,
+    verdict: 'PASS',
+    lifecycle_disposition: 'CONTINUE',
+    findings: [],
+    unresolved_decisions: [],
+    graph_coverage: [
+      'criterion_local', 'cross_criterion', 'runtime_path',
+      'assumption_provenance', 'compatibility_migration',
+    ].map((surface) => ({ surface, covered: true, notes: `${surface} reviewed for the closeout fixture.` })),
+    repair_round: 0,
+    reviewer_evidence: {
+      assurance: 'Routine',
+      summary: 'Closeout fixture reviewer confirmed both criteria against the grounded final-state boundary.',
+    },
+    reviewed_criteria: ['R1.1', 'R1.2'],
     counterexamples: [{
       criterion: 'R1.1', case_kind: 'failure',
       scenario: 'A requirements artifact changes after the reviewed digest was recorded.',
@@ -161,13 +193,24 @@ R1.1 and R1.2 are verified by V1 against D1, I1, and C1.
       decision_refs: ['D1', 'I1', 'C1'], verification_ref: 'V1',
     }],
   };
-  const projection = SEMANTIC_MODEL.modelFromMarkdown(featureDir, spec);
-  assert.deepEqual(projection.errors, []);
-  spec.semantic_model = projection.model;
   fs.writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
   const digest = spawnSync(process.execPath, [VALIDATOR, featureDir, '--semantic-digest'], { cwd: root, encoding: 'utf8' });
   assert.equal(digest.status, 0, `${digest.stdout}\n${digest.stderr}`);
   spec.validation.semantic_review.semantic_digest = digest.stdout.trim();
+  // C13: a completed receipt is only terminal when the durable history records
+  // it. The entry binds the same semantic digest, the receipt's own canonical
+  // digest, and the attempt index the receipt reports as repair_round.
+  spec.validation.semantic_review_history.entries = [{
+    sequence: 0,
+    semantic_digest: spec.validation.semantic_review.semantic_digest,
+    review_receipt_digest: `sha256:${crypto.createHash('sha256')
+      .update(SEMANTIC_MODEL.stableJson(spec.validation.semantic_review), 'utf8').digest('hex')}`,
+    verdict: 'PASS',
+    lifecycle_disposition: 'CONTINUE',
+    blocking_count: 0,
+    attempt_index: spec.validation.semantic_review.repair_round,
+    review_epoch: 0,
+  }];
   spec.ready_for_implementation = true;
   spec.status = specStatus === 'complete' ? 'done' : specStatus;
   delete spec.current_phase;
@@ -212,12 +255,16 @@ function installGate(root, kind) {
   fs.mkdirSync(path.join(runtimeDir, 'hooks'), { recursive: true });
   fs.mkdirSync(path.join(runtimeDir, 'hooks', 'lib'), { recursive: true });
   fs.mkdirSync(path.join(runtimeDir, 'scripts'), { recursive: true });
-  for (const name of [
-    'workflow-policy.cjs', 'provenance.cjs', 'spec-resolver.cjs', 'spec-receipt.cjs',
-    'validate-spec-output.cjs', 'spec-ground.cjs', 'spec-semantic-model.cjs', 'spec-final-state.cjs',
-  ]) {
-    fs.copyFileSync(path.join(SCRIPTS, name), path.join(runtimeDir, 'scripts', name));
-  }
+  // Copy the real transitive require closure rather than a hand-listed subset.
+  // A hand-listed subset silently rots the moment one of these entrypoints
+  // gains a new local dependency: the fixture keeps building, and the gate only
+  // fails later with a bare MODULE_NOT_FOUND from inside the installed runtime.
+  RUNTIME_CLOSURE.copyClaudeTestRuntime(ROOT, runtimeDir, [
+    'scripts/workflow-policy.cjs', 'scripts/provenance.cjs', 'scripts/spec-resolver.cjs',
+    'scripts/spec-receipt.cjs', 'scripts/validate-spec-output.cjs', 'scripts/spec-ground.cjs',
+    'scripts/spec-semantic-model.cjs', 'scripts/spec-final-state.cjs',
+    'hooks/lib/runtime-path-safety.cjs',
+  ]);
   if (kind === 'claude') {
     for (const name of [
       'spec-gate.cjs', 'completion-authority-check.cjs', 'completion-authority-state.cjs',

package/bin/__tests__/specs-v2-policy-and-scaffold.test.js

@@ -32,6 +32,25 @@ function readSpec(root, feature) {
   return JSON.parse(fs.readFileSync(path.join(root, 'specs', feature, 'spec.json'), 'utf8'));
 }
 
+// A canonical 2.1 scaffold always emits the C2 semantic_review shape plus the
+// C13 history and C16 receipt slots. A genuine schema 2.0 record predates all
+// three, so a fixture that simulates legacy migration input must strip them —
+// relabelling schema_version alone produces a record that never existed and
+// trips the 2.0 allowlist before the behavior under test is ever reached.
+function downgradeToLegacy20(spec) {
+  spec.schema_version = '2.0';
+  delete spec.validation.semantic_review_history;
+  delete spec.validation.authoring_validation;
+  const review = spec.validation.semantic_review;
+  spec.validation.semantic_review = {
+    status: review.status,
+    semantic_digest: review.semantic_digest,
+    reviewed_criteria: review.reviewed_criteria,
+    counterexamples: review.counterexamples,
+  };
+  return spec;
+}
+
 function ownershipBoundary() {
   return JSON.stringify([{
     id: 'B-OWN', type: 'ownership', tasks: ['R1-01', 'R1-02'],
@@ -250,8 +269,7 @@ test('durable transaction recovery covers every fresh and replacement rename bou
         ]);
         assert.equal(initial.status, 0, output(initial));
         const specPath = path.join(root, 'specs', feature, 'spec.json');
-        const spec = readSpec(root, feature);
-        spec.schema_version = '2.0';
+        const spec = downgradeToLegacy20(readSpec(root, feature));
         fs.writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
       },
       invoke(root, feature, env) { return runMatchingTasksOnly(root, feature, env); },
@@ -362,23 +380,37 @@ test('tasks-only normalization is table-driven, conservative, and idempotent', (
         ]);
         assert.equal(Object.hasOwn(spec.task_registry['tasks/task-R1-01-one.md'], 'legacy_owner'), false);
         assert.deepEqual(Object.keys(spec.workflow_policy), CANONICAL_POLICY_FIELDS);
+        // The legacy input asserts requirements: 'validated' with no C16 receipt
+        // behind it. Migration downgrades it to draft rather than carrying the
+        // unprovable claim forward: only spec-authoring-validation.cjs may write
+        // `validated`, and only together with a matching digest receipt (I21).
         assert.deepEqual(spec.authoring, {
-          requirements: 'validated', design: 'draft', research: 'absent', tasks: 'draft',
+          requirements: 'draft', design: 'draft', research: 'absent', tasks: 'draft',
         });
         assert.equal(spec.ready_for_implementation, false);
-        assert.deepEqual(spec.validation, {
-          status: 'not-run',
-          semantic_review: {
-            status: 'not-run', semantic_digest: null, reviewed_criteria: [], counterexamples: [],
-          },
+        // A legacy validation block never satisfies the canonical 2.1 shape, so
+        // migration replaces it with the fresh C2 review, a seeded C13 lineage,
+        // and an empty C16 slot — the legacy digest/criteria are not carried
+        // forward as if they had been reviewed under the current contract.
+        assert.deepEqual(Object.keys(spec.validation).sort(), [
+          'authoring_validation', 'semantic_review', 'semantic_review_history', 'status',
+        ]);
+        assert.equal(spec.validation.status, 'not-run');
+        assert.deepEqual(spec.validation.semantic_review, {
+          status: 'not-run', semantic_digest: null, verdict: null, lifecycle_disposition: null,
+          findings: [], unresolved_decisions: [], graph_coverage: [], repair_round: 0,
+          reviewed_criteria: [], counterexamples: [], reviewer_evidence: null,
         });
+        assert.deepEqual(spec.validation.semantic_review_history.entries, []);
+        assert.match(spec.validation.semantic_review_history.lineage_id, /^sha256:[0-9a-f]{64}$/);
+        assert.equal(spec.validation.authoring_validation, null);
       },
     },
     {
       name: 'legacy research pointer and valid done lifecycle',
       research: true,
       mutate(spec) {
-        spec.schema_version = '2.0';
+        downgradeToLegacy20(spec);
         spec.research = { path: 'research.md' };
         delete spec.authoring.research;
         const task = spec.task_registry['tasks/task-R1-01-one.md'];
@@ -402,7 +434,7 @@ test('tasks-only normalization is table-driven, conservative, and idempotent', (
     {
       name: 'legacy nested inert receipt read migration',
       mutate(spec) {
-        spec.schema_version = '2.0';
+        downgradeToLegacy20(spec);
         spec.workflow_policy.override_receipt = null;
       },
       verify(spec) {
@@ -522,6 +554,7 @@ test('tasks-only migration rejects invalid evidence without any write', () => {
     {
       name: 'ambiguous top level inert receipt',
       mutate(root, feature, spec) {
+        downgradeToLegacy20(spec);
         delete spec.schema_version;
         spec.override_receipt = null;
         fs.writeFileSync(path.join(root, 'specs', feature, 'spec.json'), `${JSON.stringify(spec, null, 2)}\n`);
@@ -531,7 +564,7 @@ test('tasks-only migration rejects invalid evidence without any write', () => {
     {
       name: 'legacy top level non inert receipt',
       mutate(root, feature, spec) {
-        spec.schema_version = '2.0';
+        downgradeToLegacy20(spec);
         spec.override_receipt = { issuer: 'unsupported' };
         fs.writeFileSync(path.join(root, 'specs', feature, 'spec.json'), `${JSON.stringify(spec, null, 2)}\n`);
       },
@@ -587,15 +620,46 @@ test('schema 2.0 migration rejects unknown authority fields instead of projectio
       const feature = `legacy-unknown-${name}`;
       assert.equal(run(root, [feature, '--tasks', 'R1-01-one,R1-02-two', '--boundaries', ownershipBoundary()]).status, 0);
       const specPath = path.join(root, 'specs', feature, 'spec.json');
-      const spec = readSpec(root, feature);
-      spec.schema_version = '2.0';
+      const spec = downgradeToLegacy20(readSpec(root, feature));
       mutate(spec);
       fs.writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
       const before = readTree(path.dirname(specPath));
       const result = runMatchingTasksOnly(root, feature);
       assert.equal(result.status, 2, `${name}: ${output(result)}`);
-      assert.match(output(result), /unsupported legacy authority field/);
+      // Must name the injected dead_authority field specifically: before the
+      // legacy downgrade above, this matched on the 2.1-only validation records
+      // instead and passed without exercising the mutation under test.
+      assert.match(output(result), /unsupported legacy authority field.*dead_authority/);
       assert.deepEqual(readTree(path.dirname(specPath)), before);
     } finally { fs.rmSync(root, { recursive: true, force: true }); }
   }
 });
+
+test('--help and --version answer on stdout before any precondition runs', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-scaffold-info-flags-'));
+  try {
+    for (const flag of ['--help', '-h']) {
+      const result = run(root, [flag]);
+      assert.equal(result.status, 0, `${flag}: ${output(result)}`);
+      assert.match(result.stdout, /^Usage: node spec-scaffold\.cjs/, `${flag} must print usage on stdout`);
+      assert.equal(result.stderr, '', `${flag} must not write to stderr`);
+    }
+
+    for (const flag of ['--version', '-v']) {
+      const result = run(root, [flag]);
+      assert.equal(result.status, 0, `${flag}: ${output(result)}`);
+      // Prerelease suffixes are normal on this package (e.g. 0.16.0-rc.4).
+      assert.match(result.stdout.trim(), /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/, `${flag} must print a SemVer version`);
+      assert.equal(result.stderr, '', `${flag} must not write to stderr`);
+    }
+
+    // A help flag must never be read as a feature name, and must not create a spec.
+    assert.deepEqual(fs.readdirSync(root), [], 'info flags must not touch the work tree');
+
+    // The no-argument path keeps usage-as-diagnostic: stderr, exit 2.
+    const bare = run(root, []);
+    assert.equal(bare.status, 2, output(bare));
+    assert.equal(bare.stdout, '', 'bare invocation must not print usage on stdout');
+    assert.match(bare.stderr, /^Usage: node spec-scaffold\.cjs/);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});