cadet-agent 0.46.0 → 0.48.0

package/README.md

@@ -9,7 +9,7 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
   - `cadet-agent.md` is the thin global directive: identity, non-negotiable rules, workflow routing, hard-gate protocol, and skill dispatch.
   - `Harness.md` is the canonical harness contract: budgets, evidence-backed gates, retries, context tiers, tool routing, privacy, and escalation.
   - `harness.schema.json` and `state.schema.json` are the machine-readable schemas for harness records and session state.
-  - `skills/` contains scoped workflow-phase skills (PlanningReview, Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer).
+  - `skills/` contains scoped workflow-phase skills (PlanningReview, Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer, Handoff, Reconciliation).
   - `templates/` contains runtime templates for planning artifacts.
 - `.cadet/harness.json` holds repository-local budget/policy overrides (preserved by sync).
 - `.cadet/runs/` holds sanitized run ledgers (preserved by sync; no secrets or raw prompts by default).
@@ -28,7 +28,7 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
 
 ## Cross-IDE Support
 
-Cadet-Agent provides full workflow parity across five IDEs. The same 10 skills + reviewer are available in each:
+Cadet-Agent provides full workflow parity across five IDEs. The same 11 skills + reviewer are available in each:
 
 | Feature | GitHub Copilot | Cursor | Continue | Claude Code | Deep Code |
 |---|---|---|---|---|---|
@@ -44,6 +44,7 @@ Cadet-Agent provides full workflow parity across five IDEs. The same 10 skills +
 | Code Review | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Resume | ✅ | ✅ | ✅ | ✅ | ✅ |
 | MCP Setup | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reconciliation | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` | `cadet-agent-reviewer` skill |
 | Git guard | PreToolUse hook | Manual | Manual | Manual | `permissions.ask` (`mutate-git-log`) |
 
@@ -199,6 +200,7 @@ cadet-agent state seal                           # write the active work item's
 cadet-agent state transition --to review         # enforce the matrix + evidence
 cadet-agent harness verify --gate testsPassed --files src/a.cs   # bounded, classified loop
 cadet-agent harness report                       # budget consumption and failures (no secrets)
+cadet-agent harness reconcile                    # reconcile the planning chain against state.json (read-only)
 cadet-agent harness cleanup --older-than-ms <n>  # apply the retention policy (bound required)
 cadet-agent harness capabilities                 # available CLI/Unity/MCP/hook/token/cost telemetry
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadet-agent",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -6,7 +6,9 @@ import {
   validateState, migrateStateFile, readState, writeState, evaluateTransition, applyTransition,
   workItemIdOf, loadPolicy, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
   runVerificationLoop, commandForGate, detectCapabilities, runsDir, gitChangedFiles, PolicyError, StateError,
-  detectRepoRole, describeRepoRole, GATES, manualConfirmation,
+  detectRepoRole, describeRepoRole, GATES, PHASES, manualConfirmation,
+  gitChangeSet, DEFAULT_REPORT_DIR,
+  reconcileArtifacts, PLANS_DEFAULT_DIR,
   parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
   parseReachabilityDeclaration, validateReachabilityDeclaration, collectWorkItems,
   findDeferralCycles, readSiblingDeclarations, normalizeWorkItemRef, describeReachabilityGaps,
@@ -58,6 +60,8 @@ function showHelp() {
     cadet-agent harness verify-acs  Verify declared AC↔test coverage against a test report
     cadet-agent harness verify-reachability  Verify a story's declared reachability (opt-in)
     cadet-agent harness report      Summarize budget consumption and failures
+    cadet-agent harness changes     List the files a story changed, with status, counts, and links
+    cadet-agent harness reconcile   Reconcile the planning chain against state.json (read-only)
     cadet-agent harness cleanup     Apply the retention policy to .cadet/runs/
     cadet-agent harness capabilities  Report available CLI/Unity/MCP/hook/token/cost telemetry
 
@@ -70,6 +74,7 @@ function showHelp() {
     --command      Command override (harness verify)
     --files        Comma-separated relevant files to bind evidence to (harness verify|confirm)
     --commit       Revision the gate attests, as a hex SHA (harness verify|confirm)
+    --expect-phase Refuse to record a gate unless the current phase matches (harness verify|confirm|verify-acs|verify-reachability)
     --reason       Why automation was unavailable (harness confirm)
     --expires-at   ISO-8601 expiry bounding the confirmation (harness confirm)
     --environment  key=value,... describing what was verified (harness confirm)
@@ -78,6 +83,10 @@ function showHelp() {
     --report       Test report to derive the inventory from (harness verify-acs|matrix-check)
     --matrix       TDD matrix markdown to check (harness matrix-check)
     --inventory    Newline-separated test names, when no report is available (harness matrix-check)
+    --range        Base revision to diff instead of the working tree (harness changes)
+    --relative-to  Directory the emitted links are relative to (harness changes; default .cadet/reports)
+    --include-cadet  Keep .cadet/ bookkeeping among the listed files (harness changes)
+    --plans-dir    Directory holding the planning artifacts (harness reconcile; default .cadet/agent/project-plans)
     --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
     --older-than-ms  Age bound, in ms, for records cleanup may delete (harness cleanup; required)
     --keep         always|active|<work-item ids> for what stays in state.json (state compact; required)
@@ -146,6 +155,9 @@ function parseArgs(argv) {
       case '--command': opts.command = value(a); break;
       case '--work-item': opts.workItemId = value(a); break;
       case '--phase': opts.phase = value(a); break;
+      // --expect-phase: a guard against recording a gate into a phase the caller
+      // did not intend. See assertExpectedPhase.
+      case '--expect-phase': opts.expectPhase = value(a); break;
       case '--run': opts.runId = value(a); break;
       case '--type': opts.type = value(a); break;
       case '--reason': opts.reason = value(a); break;
@@ -164,6 +176,10 @@ function parseArgs(argv) {
       case '--commit': opts.commitGiven = true; opts.commit = value(a); break;
       case '--matrix': opts.matrix = value(a); break;
       case '--inventory': opts.inventory = value(a); break;
+      case '--range': opts.range = value(a); break;
+      case '--relative-to': opts.relativeTo = value(a); break;
+      case '--include-cadet': opts.includeCadet = true; break;
+      case '--plans-dir': opts.plansDir = value(a); break;
       case '--write-coverage': opts.writeCoverage = true; break;
       case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
@@ -224,6 +240,40 @@ function fail(opts, message, code = json => json.exitCode || 1, json = {}) {
   process.exit(exitCode);
 }
 
+/**
+ * `--expect-phase <phase>` — refuse to record gate evidence into a phase the
+ * caller did not intend.
+ *
+ * The failure this closes is a caller error, not a framework one: `state
+ * transition` already reports `allowed: false` and exits 1, but an agent that
+ * chains commands with `;` and filters the output reads the *next* command's
+ * success as the transition's, and goes on to record the following gates into the
+ * phase it never left. The verdict was correct and ignored; the record was then
+ * written anyway. This is a check because the mistake recurred after being
+ * documented, and a check is what the framework's own doctrine asks for at that
+ * point.
+ *
+ * The flag is opt-in and cheap: omitting it changes nothing. A mismatch is
+ * refused before any write, so a stray `--expect-phase` cannot corrupt state —
+ * it can only stop the command.
+ */
+function assertExpectedPhase(opts, state) {
+  if (!opts.expectPhase) return;
+  if (!PHASES.includes(opts.expectPhase)) {
+    fail(opts, `--expect-phase "${opts.expectPhase}" is not a known phase. Valid phases: ${PHASES.join(', ')}.`, () => 1, { ok: false, code: 'unknown-phase', expectedPhase: opts.expectPhase });
+  }
+  const actual = state?.session?.currentPhase ?? null;
+  if (actual === opts.expectPhase) return;
+  fail(
+    opts,
+    `--expect-phase ${opts.expectPhase}, but the current phase is "${actual ?? '(none)'}". `
+    + 'Refusing to record evidence for a phase the caller did not intend — re-read .cadet/state.json '
+    + '(or run `state transition --dry-run`) and retry once the phase is what you expected.',
+    () => 1,
+    { ok: false, code: 'phase-mismatch', expectedPhase: opts.expectPhase, actualPhase: actual },
+  );
+}
+
 // ── evidence archive (contract v5) ──────────────────────────────────────────
 
 /**
@@ -660,6 +710,7 @@ async function cmdHarness(opts) {
 
     const { exists, state } = readState(opts.targetDir);
     if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before recording confirmation.', () => 2);
+    assertExpectedPhase(opts, state);
 
     const strict = policy.strictClosure?.enabled === true ? policy.strictClosure : null;
     const mc = strict?.manualConfirmation || null;
@@ -817,6 +868,7 @@ async function cmdHarness(opts) {
     const gate = opts.gate;
     if (!gate) fail(opts, 'harness verify requires --gate <gate>');
     const { state } = readState(opts.targetDir);
+    assertExpectedPhase(opts, state);
     const caps = detectCapabilities({ targetDir: opts.targetDir });
     const descriptor = opts.command
       ? { command: opts.command, tool: 'custom', automated: true }
@@ -961,6 +1013,7 @@ async function cmdHarness(opts) {
     // never written cannot be asserted into coverage.
     if (!opts.story) fail(opts, 'harness verify-acs requires --story <path>');
     const { exists, state } = readState(opts.targetDir);
+    assertExpectedPhase(opts, state);
     const strict = policy.strictClosure?.enabled === true;
     const workItemId = state ? workItemIdOf(state) : 'unscoped';
     const phase = state?.session?.currentPhase || 'implementation';
@@ -1070,6 +1123,26 @@ async function cmdHarness(opts) {
     const at = new Date();
     const criteriaStrings = coverage.ac.flatMap((a) => [a.id, ...a.declared]);
     const nowIso = at.toISOString();
+    // The story is the only INPUT to the AC claim: it carries the declared
+    // AC→test mapping, and `criteriaHash` binds those names (C12), so editing the
+    // mapping invalidates the record.
+    //
+    // The test report is an OUTPUT of the run that satisfied `testsPassed`, not an
+    // input, and binding it was a defect: a repository whose test script rewrites a
+    // fixed report path (e.g. `test-results-junit.xml`) staled this record the
+    // moment it re-ran the tests, because the file the record had just read changed
+    // underneath it. This is the same class Harness §5 already excludes
+    // (`.cadet/state.json`, `.cadet/runs/**`) — "binding evidence to either would
+    // make a gate stale the instant it was written" — so a generated report gets
+    // the same treatment and is kept as `artifactPath` for audit, where nothing
+    // re-hashes it.
+    //
+    // The story path is made repo-relative for the same reason verify-reachability
+    // does it: an absolute path never resolves under the root when freshness is
+    // re-derived at transition time, so both hashes would be computed over a
+    // missing file and match — a binding that is silently inert.
+    const storyPath = resolve(opts.targetDir, opts.story);
+    const storyRel = relative(opts.targetDir, storyPath).replace(/\\/g, '/') || basename(storyPath);
     const evidence = createEvidence({
       evidenceId: newId(),
       workItemId,
@@ -1080,9 +1153,11 @@ async function cmdHarness(opts) {
       command: `harness verify-acs --story ${opts.story}`,
       result: `AC coverage verified: ${coverage.ac.length} criteria, inventory ${coverage.inventorySize} (${inventory.format})`,
       exitCode: 0,
-      inputTreeHash: computeInputTreeHash(opts.targetDir, [opts.story, ...(reportPath ? [reportPath] : [])]),
+      // Audit pointer only. Not a relevant file: see above.
+      artifactPath: reportPath ? reportPath.replace(/\\/g, '/') : null,
+      inputTreeHash: computeInputTreeHash(opts.targetDir, [storyRel]),
       criteriaHash: hashCriteria(criteriaStrings),
-      relevantFiles: [opts.story, ...(reportPath ? [reportPath] : [])].map((f) => f.replace(/\\/g, '/')),
+      relevantFiles: [storyRel],
       createdAt: at,
       expiresAt: null,
       // Schema + validator require an object carrying a `scope`, not a bare
@@ -1150,6 +1225,7 @@ async function cmdHarness(opts) {
     const storyPath = resolve(opts.targetDir, opts.story);
     const storyRel = relative(opts.targetDir, storyPath).replace(/\\/g, '/') || basename(storyPath);
     const { exists, state } = readState(opts.targetDir);
+    assertExpectedPhase(opts, state);
     const enabled = policy.reachability?.enabled === true;
     const probeCommand = policy.reachability?.command || null;
     const workItemId = state ? workItemIdOf(state) : 'unscoped';
@@ -1293,6 +1369,109 @@ async function cmdHarness(opts) {
     return;
   }
 
+  // Read-only. Produces the deterministic half of a Change Report — which files
+  // changed, how, and by how much — so the agent never assembles that table from
+  // memory. The other half, why each file changed, is not knowable from git and
+  // stays the agent's job. See .cadet/agent/core/skills/CodeReview.md.
+  //
+  // A missing git is NOT a usage error here. This command informs a review that
+  // can still be completed, so it reports the limitation and exits 0 rather than
+  // blocking the review; the report records it under Limits.
+  if (sub === 'changes') {
+    const relativeTo = opts.relativeTo || DEFAULT_REPORT_DIR;
+    const changes = gitChangeSet(opts.targetDir, {
+      range: opts.range || null,
+      relativeTo,
+      includeCadet: opts.includeCadet === true,
+    });
+
+    const { exists, state } = readState(opts.targetDir);
+    const item = exists ? state?.activeWorkItem ?? null : null;
+    const workItem = item ? { epicId: item.epicId ?? null, storyId: item.storyId ?? null } : null;
+
+    const payload = {
+      ok: true,
+      available: changes.available,
+      workItem,
+      range: opts.range || 'working-tree',
+      relativeTo,
+      files: changes.files,
+      counts: changes.counts,
+      reason: changes.reason,
+    };
+    if (opts.format === 'json') {
+      emit(opts, '', payload);
+      return;
+    }
+
+    if (!changes.available) {
+      console.log(`\n⚠️  Change inventory unavailable: ${changes.reason}`);
+      console.log('   Do not list files from memory — record this as a limit of the report.');
+      return;
+    }
+
+    const c = changes.counts;
+    console.log(`\nChange inventory (${payload.range}) — ${changes.files.length} file(s)`);
+    console.log(`  ${c.added} added · ${c.modified} modified · ${c.renamed} renamed · ${c.deleted} deleted`);
+    if (changes.files.length === 0) {
+      console.log('\n  (no changes)');
+    } else {
+      console.log('');
+      for (const f of changes.files) {
+        const lines = f.added === null && f.deleted === null ? 'new' : `+${f.added ?? 0}/-${f.deleted ?? 0}`;
+        console.log(`  ${f.status}  ${lines.padEnd(10)} ${f.path}`);
+      }
+    }
+    const label = workItem ? `${workItem.epicId || 'none'}::${workItem.storyId || 'none'}` : 'none';
+    console.log(`\n  Links relative to ${relativeTo} · work item: ${label}`);
+    return;
+  }
+
+  // Read-only. Reconciles the planning chain against state.json: the mechanical
+  // half of the Reconciliation skill. It reports the inconsistencies it can prove
+  // from the artifacts and never repairs one — the skill proposes repairs for the
+  // user to approve. See .cadet/agent/core/skills/Reconciliation.md.
+  //
+  // Exit 0 whatever the verdict: the verdict is the payload, and a caller reading
+  // `--format json` must not have to tolerate a failure exit to get it. A run with
+  // no planning artifacts at all is a legitimate state (a framework-source repo, a
+  // small change), not an error.
+  if (sub === 'reconcile') {
+    const { exists, state } = readState(opts.targetDir);
+    const result = reconcileArtifacts(opts.targetDir, {
+      state: exists ? state : null,
+      plansDir: opts.plansDir || PLANS_DEFAULT_DIR,
+      story: opts.story || null,
+    });
+
+    if (opts.format === 'json') {
+      emit(opts, '', result);
+      return;
+    }
+    if (!result.available) {
+      console.log(`\nℹ️  Nothing to reconcile: ${result.reason}`);
+      return;
+    }
+
+    const s = result.summary;
+    console.log(`\nReconcile ${result.plansDir}${result.scopedEpic ? ` (${result.scopedEpic})` : ''} — verdict: ${result.verdict}`);
+    console.log(`  ${result.artifacts.epicCount} epic(s), ${result.artifacts.storyCount} story file(s)`);
+    console.log(`  ${s.total} finding(s): ${s.blocking} blocking · ${s.warning} warning · ${s.info} info`);
+    if (s.total === 0) {
+      console.log('\n  ✅ The chain is internally consistent.');
+    } else {
+      console.log('');
+      for (const f of result.findings) {
+        console.log(`  [${f.severity}] ${f.id} ${f.code} — ${f.subject}`);
+        console.log(`        ${f.detail}${f.evidence ? ` (${f.evidence})` : ''}`);
+      }
+    }
+    if (result.verdict === 'unknown') {
+      console.log('\n  ⚠️  At least one artifact could not be read, so consistency cannot be certified.');
+    }
+    return;
+  }
+
   // AR-5. Reconcile a TDD matrix's DELIVERED test-name claims against a compiled
   // inventory. Read-only: it reports, and never writes state, so it can be run at
   // authoring time (before anything has been implemented) as well as in a gate.
@@ -1390,7 +1569,7 @@ async function cmdHarness(opts) {
     return;
   }
 
-  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|verify-reachability|matrix-check|report|cleanup|capabilities.`);
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|verify-reachability|matrix-check|report|changes|reconcile|cleanup|capabilities.`);
 }
 
 export async function run(argv) {

package/src/harness/changes.mjs

@@ -0,0 +1,234 @@
+/**
+ * Change inventory — what a story actually touched, and how much.
+ *
+ * Why this exists: the Change Report's file table has to be *the same table*
+ * every run. When the agent assembled that list by hand — a `git status` here, a
+ * remembered path there — the result varied by run: a file dropped, a status
+ * guessed, a link that did not resolve, a line count invented. The rows are the
+ * part of the report that is mechanically knowable, so they are computed here
+ * and the agent supplies only the prose that is not.
+ *
+ * This is a read-only probe. It runs `git` and parses output; it never writes.
+ *
+ * Availability contract: mirrors `gitChangedFiles` (`util.mjs`). Returns
+ * `{ available: false, reason }` when git cannot be asked — "not a repository"
+ * and "no changes" must not look alike, so callers state the limitation rather
+ * than reporting an empty change set as a clean one.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, join, relative } from 'node:path';
+
+/** Default report directory, from which file links are made relative. */
+export const DEFAULT_REPORT_DIR = '.cadet/reports';
+
+/**
+ * Cadet's own bookkeeping. A story's change report should not lead with the
+ * ledger and state files its own gate checks rewrote. Same set and same reason
+ * as `util.mjs#CADET_MACHINERY`.
+ */
+const CADET_MACHINERY = ['.cadet/state.json', '.cadet/runs/', '.cadet/archive/'];
+
+function isCadetMachinery(relPath) {
+  return CADET_MACHINERY.some((p) => (p.endsWith('/') ? relPath.startsWith(p) : relPath === p));
+}
+
+/**
+ * Collapse porcelain's two status columns (`XY`) to the single letter the
+ * report shows. The staged column wins when it says something, because that is
+ * the status the eventual commit will carry; the worktree column is the
+ * fallback. `??` is an untracked file, which a reader reads as "added".
+ */
+const STATUS_LETTERS = { R: 'R', C: 'R', A: 'A', D: 'D', M: 'M', T: 'M' };
+
+function statusFromPorcelain(xy) {
+  if (xy === '??') return 'A';
+  const [staged, unstaged] = xy;
+  return STATUS_LETTERS[staged] || STATUS_LETTERS[unstaged] || 'M';
+}
+
+/**
+ * Normalize a `--numstat` path field, which spells renames three ways:
+ * `new`, `old => new`, and `dir/{old => new}/file`. Only the new path is kept,
+ * matching the name-status side, so the two maps join on the same key.
+ */
+function normalizeNumstatPath(raw) {
+  const path = String(raw || '').trim();
+  if (!path.includes(' => ')) return path;
+  const braced = path.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
+  if (braced) return `${braced[1]}${braced[3]}${braced[4]}`.replace(/\/{2,}/g, '/');
+  return path.split(' => ').pop().trim();
+}
+
+function defaultGitRunner(cmd, args) {
+  try {
+    return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run one git command and return its stdout, or `{ error }` describing why the
+ * question could not be asked. Every call goes through here so a single probe
+ * failure is reported the same way regardless of which command failed.
+ */
+function runGit(cwd, args, runner) {
+  let res;
+  try {
+    res = runner('git', ['-C', cwd, ...args]);
+  } catch (err) {
+    return { error: `git invocation failed: ${err.message}` };
+  }
+  if (!res) return { error: 'git is not available' };
+  if (res.error || res.status === null) {
+    return { error: 'git is not installed or could not be executed' };
+  }
+  if (res.status !== 0) {
+    return { error: String(res.stderr || '').trim() || `git exited ${res.status}` };
+  }
+  return { stdout: String(res.stdout || '') };
+}
+
+/**
+ * Files and statuses for the change set. Untracked files appear only in the
+ * working-tree form; a `--range` diff is a commit-to-commit question and cannot
+ * see them.
+ */
+function readNameStatus(cwd, { runner, range }) {
+  if (range) {
+    const res = runGit(cwd, ['diff', '--name-status', range, '--'], runner);
+    if (res.error) return { error: res.error };
+    const files = [];
+    for (const line of res.stdout.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      // "M\tpath" — or "R100\told\tnew", where the new path is the one that exists.
+      const fields = line.split('\t');
+      if (fields.length < 2) continue;
+      const path = fields[fields.length - 1].trim();
+      if (!path) continue;
+      files.push({ path: path.replace(/\\/g, '/'), status: fields[0][0] });
+    }
+    return { files };
+  }
+
+  const res = runGit(cwd, ['status', '--porcelain', '--untracked-files=all'], runner);
+  if (res.error) return { error: res.error };
+  const files = [];
+  for (const line of res.stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    // Porcelain v1: XY<space>path, with renames written "old -> new".
+    const xy = line.slice(0, 2);
+    let path = line.slice(3).trim();
+    if (path.includes(' -> ')) path = path.split(' -> ').pop().trim();
+    path = path.replace(/^"|"$/g, '');
+    if (!path) continue;
+    files.push({ path: path.replace(/\\/g, '/'), status: statusFromPorcelain(xy) });
+  }
+  return { files };
+}
+
+/**
+ * Accumulate one count onto a prior one. A file can appear in both the staged
+ * and the unstaged numstat, and those counts add. `null` means git reported no
+ * number (a binary file); it stays unknown unless a real number was seen.
+ */
+function addCount(prior, value) {
+  if (value === null) return prior === undefined ? null : prior;
+  return (prior ?? 0) + value;
+}
+
+/** Added/deleted counts per path, merged across the staged and unstaged diffs. */
+function mergeNumstat(target, stdout) {
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const [added, deleted, ...rest] = line.split('\t');
+    if (rest.length === 0) continue;
+    const path = normalizeNumstatPath(rest.join('\t'));
+    if (!path) continue;
+    // A binary file reports "-" for both; that is genuinely unknown, not zero.
+    const a = /^\d+$/.test(added) ? Number(added) : null;
+    const d = /^\d+$/.test(deleted) ? Number(deleted) : null;
+    const prior = target.get(path);
+    target.set(path, {
+      added: addCount(prior?.added, a),
+      deleted: addCount(prior?.deleted, d),
+    });
+  }
+}
+
+function readNumstat(cwd, { runner, range }) {
+  const counts = new Map();
+  if (range) {
+    const res = runGit(cwd, ['diff', '--numstat', range, '--'], runner);
+    if (res.error) return { error: res.error };
+    mergeNumstat(counts, res.stdout);
+    return { counts };
+  }
+  const unstaged = runGit(cwd, ['diff', '--numstat', '--'], runner);
+  if (unstaged.error) return { error: unstaged.error };
+  mergeNumstat(counts, unstaged.stdout);
+  const staged = runGit(cwd, ['diff', '--cached', '--numstat', '--'], runner);
+  if (staged.error) return { error: staged.error };
+  mergeNumstat(counts, staged.stdout);
+  return { counts };
+}
+
+/**
+ * The change inventory for a directory.
+ *
+ * @param {string} cwd Repository root to ask about.
+ * @param {object} [options]
+ * @param {Function} [options.runner] Injectable git runner, for tests.
+ * @param {string|null} [options.range] Diff a base revision instead of the working tree.
+ * @param {string} [options.relativeTo] Directory the `link` fields are made relative to.
+ * @param {boolean} [options.includeCadet] Keep `.cadet/` bookkeeping in the list.
+ * @returns {{available: boolean, files: Array, counts: object, reason: string|null}}
+ */
+export function gitChangeSet(cwd, {
+  runner = defaultGitRunner,
+  range = null,
+  relativeTo = DEFAULT_REPORT_DIR,
+  includeCadet = false,
+} = {}) {
+  const empty = { added: 0, modified: 0, deleted: 0, renamed: 0 };
+
+  const named = readNameStatus(cwd, { runner, range });
+  if (named.error) return { available: false, files: [], counts: empty, reason: named.error };
+
+  const counted = readNumstat(cwd, { runner, range });
+  if (counted.error) return { available: false, files: [], counts: empty, reason: counted.error };
+
+  // Links are relative to the report, not the repository root: a report at
+  // `.cadet/reports/x.md` must point at `../../Assets/Foo.cs` or the click does
+  // nothing. Computing it here is the whole reason the link is not hand-written.
+  const baseDir = isAbsolute(relativeTo) ? relativeTo : join(cwd, relativeTo);
+
+  const seen = new Map();
+  for (const file of named.files) {
+    if (!includeCadet && isCadetMachinery(file.path)) continue;
+    if (seen.has(file.path)) continue;
+    const count = counted.counts.get(file.path);
+    const linkTarget = relative(baseDir, join(cwd, file.path)).replace(/\\/g, '/');
+    seen.set(file.path, {
+      path: file.path,
+      status: file.status,
+      // Untracked files have no diff, so no count exists. Null, not zero: a
+      // zero would read as "changed nothing", which is a different claim.
+      added: count?.added ?? null,
+      deleted: count?.deleted ?? null,
+      link: `[${file.path}](${linkTarget})`,
+    });
+  }
+
+  const files = [...seen.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const counts = { ...empty };
+  for (const f of files) {
+    if (f.status === 'A') counts.added += 1;
+    else if (f.status === 'D') counts.deleted += 1;
+    else if (f.status === 'R') counts.renamed += 1;
+    else counts.modified += 1;
+  }
+
+  return { available: true, files, counts, reason: null };
+}

package/src/harness/commands.mjs

@@ -123,6 +123,20 @@ export const COMMANDS = {
     mutates: false,
     summary: 'Summarize budget consumption and failures.',
   },
+  'harness changes': {
+    mutates: false,
+    summary: 'List the files a story changed, with status, line counts, and links.',
+    // Read-only by construction: it runs `git status`/`git diff` and parses the
+    // output. It does not author the Change Report — the agent does, from the
+    // template — so there is no artifact for it to write and nothing to dry-run.
+  },
+  'harness reconcile': {
+    mutates: false,
+    summary: 'Reconcile the planning chain (requirements, design, plan, epics, stories) against state.json.',
+    // Read-only, and deliberately so: it reports the provable inconsistencies and
+    // never repairs one. An agent that could reconcile artifacts unattended could
+    // rewrite the design it is meant to be checking against.
+  },
   'harness matrix-check': {
     mutates: false,
     summary: 'Reconcile a TDD matrix against a compiled test inventory.',

package/src/harness/index.mjs

@@ -23,6 +23,13 @@ export {
   newId, isUuid, sha256, sha256Bytes, hashFile, hashTree, hashCriteria, timestamp, canonicalJson, changedFiles, gitChangedFiles,
 } from './util.mjs';
 
+export { DEFAULT_REPORT_DIR, gitChangeSet } from './changes.mjs';
+
+export {
+  PLANS_DEFAULT_DIR, REQUIRED_ARTIFACTS, RECONCILE_SEVERITIES, RECONCILE_VERDICTS,
+  DEFAULT_MAX_DOC_BYTES, parseStoryHeader, parseEpicHeader, collectArtifacts, reconcileArtifacts,
+} from './reconcile.mjs';
+
 export {
   STATE_VERSION, READABLE_STATE_VERSIONS, HISTORY_EXTERNAL_SINCE, isHistoryExternal,
   validateState, migrateStateV1toV2, migrateStateDocument, migrateStateFile, parseTargetVersion,

package/src/harness/reconcile.mjs

@@ -0,0 +1,606 @@
+/**
+ * Artifact reconciliation — does the planning chain still agree with itself?
+ *
+ * Why this exists: every per-story check can pass while the chain as a whole
+ * stops making sense. A story gets renamed and its neighbours still point at the
+ * old file; a story is marked done in state while its markdown still says
+ * planned; a deferral names a work item that finished three stories ago; an epic
+ * directory exists that no plan mentions. Each is a claim in one artifact that
+ * another artifact contradicts, and nothing looked at more than one document at a
+ * time — `designArtifactSyncConfirmed` ("Requirements, design, plan, epics
+ * mutually consistent") is the one gate on `validation -> closed` and, before
+ * this module, nothing in the codebase could back it.
+ *
+ * Scope. This module reads the planning tree and reports what it can *prove*
+ * from the artifacts themselves. It does not and cannot judge whether a design
+ * decision is still honoured, whether two requirements contradict each other, or
+ * whether the project drifted from its intent — that is the Reconciliation
+ * skill's semantic pass. The split is deliberate: a check that cannot be
+ * mechanised must not be dressed up as one, because a prose assertion that
+ * nothing verifies is the exact shape `docs/core/HarnessContract-v4.md` §0.1
+ * names as the anti-pattern.
+ *
+ * Gaps are reported for work that is still OPEN, not for history. A field added
+ * to a template in one release is not retroactively owed by every document
+ * written before it, and a check that says so fires on a correct project — which
+ * is how a report teaches its reader to ignore it. That is not a theory: the
+ * first version of this module was run against a real 88-story project and
+ * produced 15 blocking findings for epics that merely lived one directory deeper,
+ * two more for documents that existed under other names, and ~120 warnings for
+ * fields that predated the templates. So: a reachability declaration is owed by a
+ * story in flight (it is written during implementation), a witness checkpoint by
+ * an epic that is not closed, and a `done` story's evidence ALWAYS — a completion
+ * claim has to be traceable whenever it was made, and the framework's answer to
+ * an accepted historical gap is a recorded gate-exception, not silence.
+ *
+ * Discovery is by content, not by path: an epic is a directory containing
+ * `epic.md` wherever it sits, and a required document is matched by filename
+ * pattern wherever it sits, because a real project nests its artifacts under a
+ * named project folder and calls its requirements `mvp-requirements.md`.
+ *
+ * Read-only. It writes nothing: no state, no ledger, no report. The skill authors
+ * the report from this verdict.
+ *
+ * The honesty rule. `verdict` is `unknown` whenever any artifact or required
+ * field could not be read, because a clean verdict must never be reachable from
+ * input the module could not parse — "an unparseable report proves nothing"
+ * (`src/cli.mjs` verify-acs).
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative } from 'node:path';
+
+import { PHASES } from './policy.mjs';
+import {
+  collectWorkItems,
+  parseReachabilityDeclaration,
+  validateReachabilityDeclaration,
+} from './reachability.mjs';
+
+/** Where the framework puts planning artifacts when a policy does not relocate them. */
+export const PLANS_DEFAULT_DIR = '.cadet/agent/project-plans';
+
+/**
+ * The documents a large change is expected to produce, matched by filename
+ * PATTERN rather than by a fixed path.
+ *
+ * The fixed-path version of this check was wrong in practice. A real project
+ * (`dolven-tactics`) keeps its artifacts under a named project folder with its
+ * own document names — `.cadet/agent/project-plans/dolven-tactics-mvp/
+ * mvp-requirements.md` — so looking for `requirements.md` at the plans root
+ * reported two blocking findings against a project that had both documents. A
+ * check that fires on a correct project is worse than no check: it teaches the
+ * reader to ignore the output. Discovery is bounded and the path that satisfied
+ * each one is reported, so the reader can see which file counted.
+ *
+ * `project-plan.md` is advisory rather than required: no skill in the dispatch
+ * table produces one (Requirements, Architecture and StoryBreakdown cover the
+ * others), so demanding it would report a gap for a document the workflow never
+ * asked for.
+ */
+export const REQUIRED_ARTIFACTS = [
+  { name: 'requirements', pattern: /requirements[^/\\]*\.md$/i, fromPhase: 'architectureComplete', severity: 'blocking' },
+  { name: 'technical-design', pattern: /technical-design[^/\\]*\.md$/i, fromPhase: 'story-breakdown', severity: 'blocking' },
+  { name: 'project-plan', pattern: /project-plan[^/\\]*\.md$/i, fromPhase: null, severity: 'info' },
+];
+
+export const RECONCILE_SEVERITIES = ['blocking', 'warning', 'info'];
+export const RECONCILE_VERDICTS = ['consistent', 'findings', 'unknown'];
+
+/** A planning document larger than this is not read; the bound keeps a runaway file from stalling a run. */
+export const DEFAULT_MAX_DOC_BYTES = 256 * 1024;
+
+/**
+ * How deep the planning tree is walked. Real layouts nest: a project folder, then
+ * `epics/`, then `epic-N/`. Three levels is not enough to assume, so the walk is
+ * bounded rather than shallow — and bounded rather than unbounded so a symlink
+ * loop or a stray `node_modules` cannot turn a read into a crawl.
+ */
+export const MAX_SCAN_DEPTH = 5;
+
+/** Directories never worth scanning in a game repo. */
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'Library', 'obj', 'Temp', 'Logs', 'Build', 'UserSettings']);
+
+const SEVERITY_RANK = { blocking: 0, warning: 1, info: 2 };
+
+function toPosix(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+function repoRelative(targetDir, abs) {
+  const rel = toPosix(relative(targetDir, abs));
+  return rel || '.';
+}
+
+/** 1-based line of the first match, for citing a finding back to its source. */
+function lineOf(text, pattern) {
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (pattern.test(lines[i])) return i + 1;
+  }
+  return null;
+}
+
+/** The body of a `## Heading` section, up to the next `## ` heading. */
+function sectionBody(text, heading) {
+  const lines = text.split(/\r?\n/);
+  const wanted = heading.toLowerCase();
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^##\s+(.+?)\s*$/);
+    if (m && m[1].toLowerCase() === wanted) { start = i + 1; break; }
+  }
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    out.push(lines[i]);
+  }
+  return out.join('\n').trim();
+}
+
+/**
+ * The path a link field points at. The templates allow either a bare path or a
+ * markdown link (`[text](../epic.md)`), and a consumer may write either, so both
+ * are accepted rather than one being silently unresolvable.
+ */
+function linkTarget(value) {
+  if (!value) return null;
+  const md = String(value).match(/\]\(([^)]+)\)/);
+  const raw = (md ? md[1] : String(value)).trim().replace(/^<|>$/g, '');
+  if (!raw || /^(none|n\/a|todo|tbd)$/i.test(raw)) return null;
+  return raw;
+}
+
+/**
+ * Every path-like candidate in a link field.
+ *
+ * The template's `fmt="link"` promises one path, but a real epic wrote three
+ * separated by `·` with parenthetical annotations — `a.md (note) · b.md (note)`
+ * — and treating that whole string as one filename reported a perfectly good
+ * link as dangling. A link field is satisfied when ANY candidate resolves.
+ */
+function linkCandidates(value) {
+  if (!value) return [];
+  const text = String(value);
+  const out = [];
+  for (const m of text.matchAll(/\]\(([^)]+)\)/g)) out.push(m[1]);
+  const withoutMarkdown = text.replace(/\[[^\]]*\]\([^)]*\)/g, ' · ');
+  for (const part of withoutMarkdown.split(/[·,;|]/)) {
+    const token = part.replace(/\([^)]*\)/g, ' ').trim().split(/\s+/)[0];
+    if (token && /\.md$/i.test(token)) out.push(token);
+  }
+  return [...new Set(out.map((s) => s.trim().replace(/^<|>$/g, '')))]
+    .filter((s) => s && !/^(none|n\/a|todo|tbd)$/i.test(s));
+}
+
+/**
+ * Does a story's declared link resolve?
+ *
+ * The story template writes `Parent Epic: ../epic.md`, while the documented
+ * layout puts `epic.md` in the *same* directory as its stories (see
+ * `docs/templates/EpicTemplate.md`'s directory listing, and
+ * `reachability.readSiblingDeclarations`, which finds siblings in that same
+ * directory). Both readings are accepted here, so neither convention is reported
+ * as broken — but a wrong *filename* still is, which is the case worth catching.
+ */
+function resolvesStoryLink(storyPath, target) {
+  if (isAbsolute(target)) return existsSync(target);
+  if (existsSync(join(storyPath, '..', target))) return true;
+  return existsSync(join(storyPath, '..', basename(target)));
+}
+
+function readBounded(path, maxBytes) {
+  try {
+    const stat = statSync(path);
+    if (stat.size > maxBytes) return { error: `file is ${stat.size} bytes, above the ${maxBytes}-byte read bound` };
+    return { text: readFileSync(path, 'utf-8') };
+  } catch (err) {
+    return { error: `cannot read: ${err.message}` };
+  }
+}
+
+/**
+ * The fields a story must carry for the structural checks to run at all. A field
+ * that cannot be read is reported, never defaulted away: a missing `Status` must
+ * not silently read as "no mismatch".
+ */
+export function parseStoryHeader(text) {
+  const field = (label) => {
+    const m = text.match(new RegExp(`^${label}:[ \\t]*(.*)$`, 'm'));
+    return m ? m[1].trim() : null;
+  };
+  return {
+    storyId: (text.match(/^(EPIC-\d+-STORY-\d+)\s*$/m) || [])[1] ?? null,
+    status: field('Status') || null,
+    parentEpic: field('Parent Epic') || null,
+    reachability: field('Reachability') || null,
+    designRefs: field('Design refs') || null,
+    statusLine: lineOf(text, /^Status:/),
+  };
+}
+
+export function parseEpicHeader(text) {
+  const field = (label) => {
+    const m = text.match(new RegExp(`^${label}:[ \\t]*(.*)$`, 'm'));
+    return m ? m[1].trim() : null;
+  };
+  const stories = sectionBody(text, 'Stories');
+  return {
+    epicId: (text.match(/^(EPIC-\d+)\s*$/m) || [])[1] ?? null,
+    status: field('Status') || null,
+    requirementsLinks: linkCandidates(field('Requirements')),
+    technicalDesignLinks: linkCandidates(field('Technical Design')),
+    witnessCheckpoint: sectionBody(text, 'Witness checkpoint'),
+    declaredStoryCount: stories
+      ? (stories.split(/\r?\n/).filter((l) => /^\s*-\s+\[/.test(l)).length || null)
+      : null,
+    statusLine: lineOf(text, /^Status:/),
+  };
+}
+
+/**
+ * Every directory under `root`, breadth-first and depth-bounded. Skipping the
+ * usual game-repo ballast keeps a walk of a real project cheap.
+ */
+function walkDirs(root, maxDepth = MAX_SCAN_DEPTH) {
+  const found = [];
+  let level = [root];
+  for (let depth = 0; depth <= maxDepth && level.length > 0; depth++) {
+    const next = [];
+    for (const dir of level) {
+      found.push(dir);
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch { continue; }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (SKIP_DIRS.has(entry.name)) continue;
+        next.push(join(dir, entry.name));
+      }
+    }
+    level = next;
+  }
+  return found;
+}
+
+/** The first file under `root` whose name matches, or null. */
+function findDoc(root, pattern) {
+  for (const dir of walkDirs(root)) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isFile() || !pattern.test(entry.name)) continue;
+      return join(dir, entry.name);
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk the planning tree. Returns what exists and what could be read — nothing is
+ * interpreted here, so a caller can report an unreadable tree as such.
+ *
+ * Both the epics and the documents are DISCOVERED rather than assumed to sit at a
+ * fixed depth. Real layouts nest (`<project>/epics/epic-N/`) and name their own
+ * documents, and a reconciler that assumes the packaged template's layout reports
+ * a correct project as broken.
+ */
+export function collectArtifacts(targetDir, {
+  plansDir = PLANS_DEFAULT_DIR,
+  story = null,
+  maxBytes = DEFAULT_MAX_DOC_BYTES,
+} = {}) {
+  const root = isAbsolute(plansDir) ? plansDir : join(targetDir, plansDir);
+  if (!existsSync(root)) {
+    return { available: false, reason: `no planning artifacts at ${toPosix(plansDir)}`, root, docs: [], epics: [], scopedEpic: null };
+  }
+
+  const dirs = walkDirs(root);
+
+  const docs = REQUIRED_ARTIFACTS.map(({ name, pattern }) => {
+    const path = findDoc(root, pattern);
+    return { name, path, relPath: path ? repoRelative(targetDir, path) : null, present: path !== null };
+  });
+
+  // Scope to one epic when a story path is given. State keys epics by directory
+  // NAME (`epic-1-player-movement`), not by path, so the scope is that name — and
+  // every epic lookup in this module uses the same key.
+  let scopedEpic = null;
+  if (story) {
+    const abs = isAbsolute(story) ? story : join(targetDir, story);
+    scopedEpic = basename(join(abs, '..'));
+  }
+
+  const epics = [];
+  for (const dir of dirs) {
+    const name = basename(dir);
+    const epicFile = join(dir, 'epic.md');
+    // An epic is identified by content, not by its directory name: a consumer may
+    // name the folder anything, and `adr/`, `spikes/` and `evidence/` live in the
+    // same tree — at whatever depth the project chose.
+    if (!existsSync(epicFile)) continue;
+    if (scopedEpic && name !== scopedEpic) continue;
+
+    const epicRead = readBounded(epicFile, maxBytes);
+    let storyFiles = [];
+    try {
+      storyFiles = readdirSync(dir)
+        .filter((f) => /^story-.*\.md$/i.test(f))
+        .sort();
+    } catch { storyFiles = []; }
+
+    const stories = storyFiles.map((file) => {
+      const path = join(dir, file);
+      const read = readBounded(path, maxBytes);
+      return { file, path, relPath: repoRelative(targetDir, path), ...read };
+    });
+
+    epics.push({
+      // `key` is the directory name, which is what state.json and work-item ids
+      // use (`epic-1-foo::story-2.md`). `dir` is the repo-relative path, for
+      // display only — conflating the two makes every lookup silently miss.
+      key: name,
+      dir: repoRelative(targetDir, dir),
+      dirPath: dir,
+      epicFile: { path: epicFile, relPath: repoRelative(targetDir, epicFile), ...epicRead },
+      stories,
+    });
+  }
+
+  epics.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+  return { available: true, reason: null, root, docs, epics, scopedEpic };
+}
+
+/**
+ * Reconcile the planning tree against `state.json`.
+ *
+ * @returns {{ok: boolean, available: boolean, plansDir: string, verdict: string|null,
+ *            findings: Array, summary: object, reason: string|null}}
+ */
+export function reconcileArtifacts(targetDir, {
+  state = null,
+  plansDir = PLANS_DEFAULT_DIR,
+  story = null,
+  maxBytes = DEFAULT_MAX_DOC_BYTES,
+} = {}) {
+  const collected = collectArtifacts(targetDir, { plansDir, story, maxBytes });
+  const plansDirRel = toPosix(plansDir);
+
+  if (!collected.available) {
+    return {
+      ok: true, available: false, plansDir: plansDirRel, verdict: null,
+      findings: [], summary: { total: 0, blocking: 0, warning: 0, info: 0 },
+      reason: collected.reason,
+    };
+  }
+
+  const findings = [];
+  const add = (code, severity, subject, artifact, detail, evidence = null) => {
+    findings.push({ code, severity, subject, artifact, detail, evidence });
+  };
+
+  const stateEpics = state?.epics && typeof state.epics === 'object' ? state.epics : {};
+  const phase = state?.session?.currentPhase ?? null;
+  const workflowPath = state?.session?.workflowPath ?? null;
+  const phaseIndex = PHASES.indexOf(phase);
+
+  // ── 1. Required top-level documents ───────────────────────────────────────
+  for (const { name, fromPhase, severity } of REQUIRED_ARTIFACTS) {
+    const doc = collected.docs.find((d) => d.name === name);
+    if (!doc || doc.present) continue;
+    // Only expect a document once the workflow has reached the phase that
+    // produces it, so an early-phase run does not report the future as a gap.
+    const expected = fromPhase === null
+      ? workflowPath === 'large'
+      : phaseIndex >= 0 && phaseIndex >= PHASES.indexOf(fromPhase);
+    if (!expected) continue;
+    add('missing-artifact', severity, `${name}.md`, `${plansDirRel}/**`,
+      fromPhase === null
+        ? 'no project plan was found anywhere under the plans directory. No skill in the dispatch produces one, so this is advisory — but a large change is expected to have one.'
+        : `no ${name} document was found anywhere under the plans directory, though the workflow reached \`${phase}\`. The chain has no root to reconcile against.`);
+  }
+
+  // ── 2. Epics: state vs disk, both directions ──────────────────────────────
+  const onDisk = new Set(collected.epics.map((e) => e.key));
+  for (const epicDir of Object.keys(stateEpics).sort()) {
+    if (!onDisk.has(epicDir)) {
+      add('missing-epic-dir', 'blocking', epicDir, `${plansDirRel}/${epicDir}`,
+        'state.json tracks this epic, but no `epic.md` exists for it on disk. Every story under it is unreachable as an artifact.');
+    }
+  }
+
+  for (const epic of collected.epics) {
+    const stateEpic = stateEpics[epic.key];
+
+    if (!stateEpic) {
+      add('orphan-epic-dir', 'warning', epic.key, epic.epicFile.relPath,
+        'this epic exists on disk but state.json does not track it. Nothing will ever mark its stories done.');
+    }
+
+    if (epic.epicFile.error) {
+      add('unparsable-artifact', 'warning', epic.key, epic.epicFile.relPath,
+        `the epic could not be read (${epic.epicFile.error}), so its status and links were not checked.`);
+    } else {
+      const header = parseEpicHeader(epic.epicFile.text);
+      if (!header.status) {
+        add('unparsable-artifact', 'warning', epic.key, epic.epicFile.relPath,
+          'the epic has no readable `Status:` field, so its status was not reconciled.');
+      }
+      if (header.epicId === null) {
+        add('unparsable-artifact', 'warning', epic.key, epic.epicFile.relPath,
+          'the epic declares no `EPIC-N` id, so its identity was not checked.');
+      }
+
+      // Epic -> requirements / design links must resolve. A field may carry more
+      // than one link, and it is satisfied when any one of them resolves.
+      for (const [label, targets] of [['Requirements', header.requirementsLinks], ['Technical Design', header.technicalDesignLinks]]) {
+        if (targets.length === 0) continue;
+        const resolved = targets.some((t) => existsSync(isAbsolute(t) ? t : join(epic.dirPath, t)));
+        if (!resolved) {
+          add('dangling-epic-link', 'warning', epic.key, epic.epicFile.relPath,
+            `the epic's \`${label}\` points at ${targets.map((t) => `\`${t}\``).join(', ')}, and none of them exist. The chain cannot be followed past this epic.`,
+            `line ${lineOf(epic.epicFile.text, new RegExp(`^${label}:`)) ?? '?'}`);
+        }
+      }
+
+      const epicStatus = String(stateEpic?.status ?? '').toLowerCase();
+      const epicClosed = epicStatus === 'complete' || epicStatus === 'done';
+      if (!header.witnessCheckpoint && !epicClosed) {
+        add('missing-witness-checkpoint', 'warning', epic.key, epic.epicFile.relPath,
+          'the epic declares no Witness checkpoint. The template marks it REQUIRED: without it, nothing states which story first makes the epic reachable.');
+      }
+    }
+
+    if (epic.stories.length === 0) {
+      add('epic-without-stories', 'warning', epic.key, epic.epicFile.relPath,
+        'this epic directory contains no `story-*.md` files. An epic with no stories delivers nothing and cannot be reviewed.');
+    }
+
+    const stateStories = stateEpic?.stories && typeof stateEpic.stories === 'object' ? stateEpic.stories : {};
+    const diskStories = new Set(epic.stories.map((s) => s.file));
+
+    for (const file of Object.keys(stateStories).sort()) {
+      if (!diskStories.has(file)) {
+        add('missing-story-file', 'blocking', `${epic.key}::${file}`, `${plansDirRel}/${epic.key}/${file}`,
+          'state.json tracks this story, but its markdown file is absent. Its acceptance criteria are no longer written down anywhere.');
+      }
+    }
+    for (const storyFile of epic.stories) {
+      if (!Object.hasOwn(stateStories, storyFile.file)) {
+        add('orphan-story-file', 'warning', `${epic.key}::${storyFile.file}`, storyFile.relPath,
+          'this story file is not tracked in state.json. It will never be marked done, and no gate refers to it.');
+      }
+    }
+
+    // ── 3. Per-story checks ─────────────────────────────────────────────────
+    for (const storyFile of epic.stories) {
+      const subject = `${epic.key}::${storyFile.file}`;
+
+      if (storyFile.error) {
+        add('unparsable-artifact', 'warning', subject, storyFile.relPath,
+          `the story could not be read (${storyFile.error}), so none of its fields were reconciled.`);
+        continue;
+      }
+
+      const header = parseStoryHeader(storyFile.text);
+
+      if (!header.status) {
+        add('unparsable-artifact', 'warning', subject, storyFile.relPath,
+          'the story has no readable `Status:` field, so it was not reconciled against state.json.');
+      }
+
+      // Story status vs state status.
+      const stateStatus = stateStories[storyFile.file];
+      const stateStatusLower = String(stateStatus).toLowerCase();
+      const isDone = stateStatusLower === 'done';
+      const isInFlight = stateStatusLower === 'in-progress';
+      if (header.status && stateStatus) {
+        const md = header.status.toLowerCase();
+        const st = String(stateStatus).toLowerCase();
+        const agree = md === st || (md === 'done' && st === 'done') || (md === 'in progress' && st === 'in-progress');
+        if (!agree) {
+          add('status-mismatch', 'warning', subject, storyFile.relPath,
+            `the story file says \`${header.status}\` while state.json says \`${stateStatus}\`. One of the two is the record and the other is stale, and a reader cannot tell which.`,
+            `line ${header.statusLine ?? '?'}`);
+        }
+      }
+
+      // Parent Epic link must resolve.
+      const parent = linkTarget(header.parentEpic);
+      if (parent) {
+        if (!resolvesStoryLink(storyFile.path, parent)) {
+          add('dangling-parent-epic', 'blocking', subject, storyFile.relPath,
+            `\`Parent Epic: ${header.parentEpic}\` does not resolve. The story has no epic, so nothing owns its completion.`,
+            `line ${lineOf(storyFile.text, /^Parent Epic:/) ?? '?'}`);
+        }
+      } else {
+        add('unparsable-artifact', 'warning', subject, storyFile.relPath,
+          'the story declares no readable `Parent Epic:`, so its place in the chain was not checked.');
+      }
+
+      // Reachability: reuse the shipped validator so reconcile and
+      // verify-reachability cannot disagree about the same declaration.
+      const declaration = parseReachabilityDeclaration(storyFile.path);
+      const workItems = state ? collectWorkItems(state) : null;
+      const verdict = validateReachabilityDeclaration(declaration, { workItems, self: subject });
+      if (!verdict.ok) {
+        if (verdict.code === 'malformed') {
+          add('unparsable-artifact', 'warning', subject, storyFile.relPath,
+            `the reachability declaration could not be parsed: ${verdict.message}`);
+        } else if (verdict.code === 'not-declared') {
+          // The declaration is written DURING implementation, so only a story in
+          // flight owes one. A story that has not started has nothing truthful to
+          // declare yet, and a story that closed before the field existed is
+          // history — reporting either buries the findings that are real.
+          if (isInFlight) {
+            add('missing-reachability', 'warning', subject, storyFile.relPath,
+              'this story is in progress but declares no reachability. The declaration is required before it can pass review, and nothing yet states how its deliverable is reached.');
+          }
+        } else if (verdict.code === 'deferral-target-done') {
+          add('expired-deferral', 'blocking', subject, storyFile.relPath, verdict.message);
+        } else {
+          add('unresolved-deferral', 'warning', subject, storyFile.relPath, verdict.message);
+        }
+      }
+
+      // A story state calls done must own evidence, or "done" is a claim with
+      // nothing behind it.
+      if (isDone) {
+        const row = state?.evidenceCoverage?.[subject]
+          ?? Object.values(state?.evidenceCoverage ?? {}).find((r) => r?.workItemId === subject);
+        const count = Number(row?.recordCount ?? 0);
+        if (!row || !Number.isFinite(count) || count <= 0) {
+          add('done-without-evidence', 'blocking', subject, storyFile.relPath,
+            'state.json marks this story done, but no evidence record is indexed against it. The completion cannot be traced to anything that ran.');
+        }
+      }
+    }
+  }
+
+  // ── 4. Sort, number, and summarise ────────────────────────────────────────
+  findings.sort((a, b) => {
+    const s = (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9);
+    if (s !== 0) return s;
+    if (a.code !== b.code) return a.code < b.code ? -1 : 1;
+    return a.subject < b.subject ? -1 : a.subject > b.subject ? 1 : 0;
+  });
+  findings.forEach((f, i) => { f.id = `R-${i + 1}`; });
+
+  const summary = {
+    total: findings.length,
+    blocking: findings.filter((f) => f.severity === 'blocking').length,
+    warning: findings.filter((f) => f.severity === 'warning').length,
+    info: findings.filter((f) => f.severity === 'info').length,
+  };
+
+  // An unreadable input cannot yield a clean verdict, whatever else was found.
+  //
+  // Only blocking and warning findings make the chain inconsistent. An `info`
+  // finding is advisory — the project-plan check is one — and folding it into the
+  // verdict would mean no project could ever be called consistent without a
+  // document no skill produces, which would make the verdict useless rather than
+  // strict.
+  const anythingUnparsable = findings.some((f) => f.code === 'unparsable-artifact');
+  const inconsistent = summary.blocking > 0 || summary.warning > 0;
+  const verdict = anythingUnparsable ? 'unknown' : inconsistent ? 'findings' : 'consistent';
+
+  return {
+    ok: true,
+    available: true,
+    plansDir: plansDirRel,
+    scopedEpic: collected.scopedEpic,
+    verdict,
+    findings,
+    summary,
+    artifacts: {
+      docs: collected.docs.map((d) => ({ name: d.name, present: d.present, path: d.relPath })),
+      epicCount: collected.epics.length,
+      storyCount: collected.epics.reduce((n, e) => n + e.stories.length, 0),
+    },
+    reason: null,
+  };
+}

package/src/harness/state.mjs

@@ -1177,8 +1177,17 @@ export function isUngatedForwardEdge(fromPhase, toPhase) {
  * must have been created at or after that instant. Without it, "fresh" would mean
  * only "not yet expired", which lets a long phase carry evidence that predates
  * the work it is meant to attest.
+ *
+ * `phaseScoped` is false for the strict-closure `revalidate` set. A revalidated
+ * gate asks "is this still true *now*?" — answered by the input-tree hash, the
+ * criteria hash, and the expiry — not "was it recorded in the phase I am leaving?".
+ * Enforcing the phase stamp on a revalidated gate made the answer "no" for every
+ * record written in an earlier phase, so the whole suite had to be re-recorded in
+ * `review` and again in `validation` on a tree that had not changed by a byte.
+ * Primary gates keep the phase scope: a record still has to be written in the
+ * phase it belongs to.
  */
-function checkGate({ gate, state, gates, exceptions, now, workItemId, fromPhase, rootDir, computeTreeHash, inputTreeHash, critHash, recencyFloor = null }) {
+function checkGate({ gate, state, gates, exceptions, now, workItemId, fromPhase, rootDir, computeTreeHash, inputTreeHash, critHash, recencyFloor = null, phaseScoped = true }) {
   const missingGates = [];
   const staleEvidence = [];
 
@@ -1204,7 +1213,7 @@ function checkGate({ gate, state, gates, exceptions, now, workItemId, fromPhase,
   const { fresh, reasons } = evidenceFreshness(evidence, {
     now,
     workItemId,
-    phase: fromPhase,
+    phase: phaseScoped ? fromPhase : null,
     inputTreeHash: currentTreeHash,
     criteriaHash: critHash,
   });
@@ -1344,6 +1353,14 @@ export function evaluateTransition(state, toPhase, context = {}) {
   }
 
   // Strict closure: re-derive the earlier gates at this transition.
+  //
+  // A revalidated gate is checked WITHOUT the phase scope (`phaseScoped: false`).
+  // Its question is "is this still true now?", which the input-tree hash, the
+  // criteria hash, and the expiry answer; the phase stamp answers only "which
+  // phase wrote it down", which is exactly the fact revalidation is not doubting.
+  // With the phase scope on, every record written in an earlier phase was rejected
+  // as stale, so an unchanged tree still forced the whole suite to be re-recorded
+  // in `review` and again in `validation`. See checkGate.
   const strict = resolveStrict(context);
   const revalidated = [];
   if (strict && strict.revalidateOnClosure !== false) {
@@ -1353,7 +1370,7 @@ export function evaluateTransition(state, toPhase, context = {}) {
     for (const gate of spec.revalidate) {
       if (spec.gates.includes(gate)) continue; // already checked as a primary gate
       revalidated.push(gate);
-      const r = checkGate({ ...shared, gate, recencyFloor });
+      const r = checkGate({ ...shared, gate, recencyFloor, phaseScoped: false });
       missingGates.push(...r.missingGates);
       staleEvidence.push(...r.staleEvidence);
     }