cadet-agent 0.36.0 → 0.39.0

package/README.md

@@ -190,16 +190,30 @@ Gates are backed by **evidence**, not assertion. Each claimed gate must have a f
 
 ```bash
 cadet-agent state validate                       # validate state against the schema
-cadet-agent state migrate                        # atomically upgrade v1 → v2
+cadet-agent state migrate                        # atomically upgrade v1 → v2 (no writes if it fails)
 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 cleanup                      # apply the retention policy
+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
 ```
 
 Every command supports `--format human|json` and exits nonzero for invalid state, failed verification, budget exhaustion, stale evidence, or safety rejection.
 
+Every command also **declares whether it writes**, and the declaration is enforced rather than
+trusted. `--help` is read-only at any depth, `--dry-run` is honoured by every mutating command, and a
+command declared read-only is tested to perform no writes. A destructive command that may run
+unattended must require a content-bearing bound — `cleanup` requires `--older-than-ms` — so an agent
+states *what* it acts on rather than merely *that* it approves. Run
+`cadet-agent harness capabilities --format json` to read the registry.
+
+Two refusals exist so an unattended agent cannot destroy evidence by accident:
+
+```bash
+cadet-agent harness cleanup                      # exits 1: deletes nothing without a bound
+cadet-agent harness record --dry-run             # reports what it would write, writes nothing
+```
+
 See `docs/guidance/HarnessTroubleshooting.md` for stale evidence, budget exhaustion, unavailable Unity CLI, and live MCP connection failures.
 
 ## Examples

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "cadet-agent",
-  "version": "0.36.0",
-  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
-  "type": "module",
-  "bin": {
-    "cadet-agent": "bin/cli.mjs"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "lint": "lychee --offline --include-fragments \"**/*.md\"",
-    "verify": "npm test && npm run lint"
-  },
-  "files": [
-    "bin/",
-    "src/"
-  ],
-  "keywords": [
-    "cadet",
-    "cadet-agent",
-    "unity",
-    "game-development",
-    "ai-agent",
-    "copilot",
-    "cursor",
-    "claude-code"
-  ],
-  "license": "CC-BY-4.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/naishtech/cadet-agent.git"
-  },
-  "homepage": "https://github.com/naishtech/cadet-agent#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "cadet-agent",
+  "version": "0.39.0",
+  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
+  "type": "module",
+  "bin": {
+    "cadet-agent": "bin/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "lint": "lychee --offline --include-fragments \"**/*.md\"",
+    "verify": "npm test && npm run lint"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "cadet",
+    "cadet-agent",
+    "unity",
+    "game-development",
+    "ai-agent",
+    "copilot",
+    "cursor",
+    "claude-code"
+  ],
+  "license": "CC-BY-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naishtech/cadet-agent.git"
+  },
+  "homepage": "https://github.com/naishtech/cadet-agent#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.mjs

@@ -10,6 +10,7 @@ import {
   parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
   createEvidence, newId, computeInputTreeHash, hashCriteria,
   collectDeclaredTestNames, reconcileTestNames,
+  resolveCommand, describeCommand, describeAllCommands, checkUnattendedRequirements, COMMANDS,
 } from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -58,55 +59,103 @@ function showHelp() {
     --gate         Gate name (harness verify|confirm)
     --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)
     --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)
     --scope        Comma-separated scope of the confirmation (harness confirm)
+    --story        Story markdown declaring the acceptance criteria (harness verify-acs)
+    --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)
     --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)
+    --dry-run      Report what a mutating command would do and write nothing (all mutating commands)
     --yes, -y      Never prompt; keep existing files (non-interactive installs)
-    --help, -h    Show this help
+    --help, -h    Show this help (valid at any depth; never writes)
     --version, -v Show version number
 `);
 }
 
+/**
+ * Does the invocation ask for help?
+ *
+ * Scanned against the raw argv rather than the parsed options on purpose. Once
+ * parsing begins, `--help` in a value position (`--target --help`) is consumed
+ * as another flag's argument and never seen again — so it must be detected
+ * before `parseArgs` runs. `--` ends flag scanning, so a literal `--help` after
+ * it is an operand and does not trigger help.
+ */
+function wantsHelp(argv) {
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') return false;
+    if (a === '--help' || a === '-h') return true;
+  }
+  return false;
+}
+
 function parseArgs(argv) {
   const opts = { format: 'human', targetDir: process.cwd(), sourceUrl: null, rest: [] };
   // argv[2] is the top-level command (`state`/`harness`/`init`/...); argv[3] begins
   // the subcommand and its options.
-  for (let i = 3; i < argv.length; i++) {
+  //
+  // `value()` reads the argument a flag expects and rejects the case where the
+  // next token is itself a flag. Without this check `--target --format` bound
+  // the literal string "--format" as the target directory and then wrote a
+  // ledger into a directory named `--format/` — a stray write, from a typo, in
+  // an arbitrary place. A silently swallowed option is worse than a rejected
+  // one because the command still reports success.
+  //
+  // A negative number is allowed through: it is a plausible value (`--older-than-ms -1`)
+  // and cannot be mistaken for one of this CLI's flags, all of which are words.
+  //
+  // `i` is declared here, outside the loop, because `value()` must advance the
+  // shared cursor — a closure over a loop-scoped `i` would not exist yet at
+  // definition time.
+  let i = 3;
+  const value = (flag) => {
+    const next = argv[i + 1];
+    if (next === undefined || (next.startsWith('-') && !/^-\d/.test(next))) {
+      fail(opts, `Option ${flag} requires a value.`, () => 1, { ok: false, code: 'missing-option-value', option: flag });
+    }
+    i += 1;
+    return next;
+  };
+  for (i = 3; i < argv.length; i++) {
     const a = argv[i];
     switch (a) {
-      case '--target': case '-t': opts.targetDir = argv[++i]; break;
-      case '--source': opts.sourceUrl = argv[++i]; break;
-      case '--format': opts.format = argv[++i] || 'human'; break;
-      case '--to': opts.to = argv[++i]; break;
-      case '--gate': opts.gate = argv[++i]; break;
-      case '--command': opts.command = argv[++i]; break;
-      case '--work-item': opts.workItemId = argv[++i]; break;
-      case '--phase': opts.phase = argv[++i]; break;
-      case '--run': opts.runId = argv[++i]; break;
-      case '--type': opts.type = argv[++i]; break;
-      case '--reason': opts.reason = argv[++i]; break;
-      case '--expires-at': opts.expiresAt = argv[++i]; break;
-      case '--environment': opts.environment = argv[++i]; break;
-      case '--scope': opts.scope = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
-      case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
+      case '--target': case '-t': opts.targetDir = value(a); break;
+      case '--source': opts.sourceUrl = value(a); break;
+      case '--format': opts.format = value(a); break;
+      case '--to': opts.to = value(a); break;
+      case '--gate': opts.gate = value(a); break;
+      case '--command': opts.command = value(a); break;
+      case '--work-item': opts.workItemId = value(a); break;
+      case '--phase': opts.phase = value(a); break;
+      case '--run': opts.runId = value(a); break;
+      case '--type': opts.type = value(a); break;
+      case '--reason': opts.reason = value(a); break;
+      case '--expires-at': opts.expiresAt = value(a); break;
+      case '--environment': opts.environment = value(a); break;
+      case '--scope': opts.scope = value(a).split(',').map((s) => s.trim()).filter(Boolean); break;
+      case '--evidence-status': opts.evidenceStatus = value(a); break;
       // Track that the flag was supplied even when its value is empty, so an
       // empty `--files ""` is rejected rather than silently falling back to the
       // working-tree scan (which could bind evidence to Cadet's own files).
-      case '--files': opts.filesGiven = true; opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
-      case '--story': opts.story = argv[++i]; break;
-      case '--report': opts.report = argv[++i]; break;
+      case '--files': opts.filesGiven = true; opts.files = value(a).split(',').map((s) => s.trim()).filter(Boolean); break;
+      case '--story': opts.story = value(a); break;
+      case '--report': opts.report = value(a); break;
       // AR-1: the revision a gate record attests, so a gate-related fix claim
       // can be traced to the commit that contains it.
-      case '--commit': opts.commitGiven = true; opts.commit = argv[++i]; break;
-      case '--matrix': opts.matrix = argv[++i]; break;
-      case '--inventory': opts.inventory = argv[++i]; break;
+      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 '--write-coverage': opts.writeCoverage = true; break;
       case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
-      case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
-      case '--agents-md': opts.agentsMd = argv[++i]; break;
+      case '--older-than-ms': opts.olderThanMs = Number(value(a)); break;
+      case '--agents-md': opts.agentsMd = value(a); break;
       case '--yes': case '-y': opts.yes = true; break;
       default: opts.rest.push(a);
     }
@@ -265,7 +314,13 @@ async function cmdHarness(opts) {
 
   if (sub === 'capabilities') {
     const caps = detectCapabilities({ targetDir: opts.targetDir });
-    if (opts.format === 'json') emit(opts, '', { ok: true, capabilities: caps });
+    // The command registry is published here so an agent can *ask* which
+    // commands write instead of inferring it from a name or trusting a flag it
+    // must remember to pass. It is informational: the safety guarantee does not
+    // depend on the agent reading it, because the dispatcher enforces the
+    // registry regardless.
+    const commands = describeAllCommands();
+    if (opts.format === 'json') emit(opts, '', { ok: true, capabilities: caps, commands });
     else {
       console.log('Cadet-Agent capability report');
       console.log(`  CLI:            ${caps.cli ? 'available' : 'unavailable'}`);
@@ -275,6 +330,11 @@ async function cmdHarness(opts) {
       console.log(`  Token telemetry:${caps.tokenTelemetry.provider ? ' provider' : ' estimate/unknown'}`);
       console.log(`  Cost telemetry: ${caps.costTelemetry.available ? 'available' : `unavailable (${caps.costTelemetry.reason})`}`);
       console.log(`  Note: ${caps.hook.note}`);
+      console.log('  Commands (mutating commands honour --dry-run; nothing writes without it being declared):');
+      for (const c of commands) {
+        const bound = c.requiresForUnattended.length ? ` [unattended requires ${c.requiresForUnattended.join(', ')}]` : '';
+        console.log(`    ${c.mutates ? 'WRITES ' : 'read   '} ${c.command}${bound}`);
+      }
     }
     return;
   }
@@ -874,7 +934,61 @@ async function cmdHarness(opts) {
 
 export async function run(argv) {
   const command = argv[2];
+
+  // `--help`/`-h` is a global, read-only flag: it must be honoured at ANY depth
+  // (`harness record --help`, `state transition --help`) and must short-circuit
+  // before dispatch. Previously it was only recognised as `argv[2]`, so a nested
+  // help flag fell through into `parseArgs`'s `rest` array — and mutating
+  // subcommands acted on it. `harness record --help` appended a ledger,
+  // `harness cleanup --help` applied the retention policy and deleted run
+  // records, and `state migrate --help` wrote a `.v1.bak` backup. "Checking the
+  // help" is not a read-only operation if help is never actually checked.
+  if (wantsHelp(argv)) {
+    showHelp();
+    return;
+  }
+
   const opts = parseArgs(argv);
+  const commandKey = resolveCommand(argv);
+
+  // Global `--dry-run`, driven by the registry rather than by each handler.
+  //
+  // This is the structural fix for the class of bug where a mutating command
+  // simply did not check the flag: `--dry-run` was parsed globally but honoured
+  // by one command, so `harness record --dry-run` wrote a ledger and
+  // `cleanup --dry-run` would have deleted records. Declaring which commands
+  // write, and honouring the flag for all of them here, means a new mutating
+  // command is covered the moment it is registered — no per-handler check to
+  // remember, and no way to forget one.
+  //
+  // A read-only command needs no interception: it is asserted not to write.
+  // A command may opt out when its dry-run is an *evaluation* rather than a
+  // no-op: `state transition --dry-run` reports the same verdict a real
+  // transition would, so its handler owns the flag. See `evaluatesOnDryRun`.
+  if (opts.dryRun === true && commandKey && COMMANDS[commandKey].mutates === true && COMMANDS[commandKey].evaluatesOnDryRun !== true) {
+    emit(
+      opts,
+      `✅ Dry run: \"${commandKey}\" would run and may write ${(COMMANDS[commandKey].writes || []).join(', ') || 'state'} — nothing was written.`,
+      {
+        ok: true,
+        dryRun: true,
+        applied: false,
+        command: commandKey,
+        mutates: true,
+        writes: COMMANDS[commandKey].writes || [],
+      },
+    );
+    return;
+  }
+
+  // A destructive command that may run unattended must carry an explicit,
+  // content-bearing bound on what it acts on. `--older-than-ms` states *what*
+  // to delete; a bare confirmation flag would only state *that* something was
+  // approved, which an agent can pass without knowing what it is approving.
+  if (commandKey) {
+    const guard = checkUnattendedRequirements(commandKey, opts);
+    if (!guard.ok) fail(opts, guard.reason, () => 1, { ok: false, command: commandKey, code: 'unattended-requirement-missing', missing: guard.missing });
+  }
 
   // Validate the create-only policy flag early so a typo fails loudly.
   const AGENTS_MD_MODES = ['keep', 'overwrite', 'merge'];

package/src/harness/commands.mjs

@@ -0,0 +1,192 @@
+/**
+ * Command registry — the single source of truth for what the CLI's commands do.
+ *
+ * Why this exists: before it, dispatch was two hand-written `if (sub === …)`
+ * chains and nothing declared which commands write. Every safety property was a
+ * convention the *caller* had to remember:
+ *
+ *   - `--dry-run` was parsed globally but honoured by exactly one command, so
+ *     `harness record --dry-run` silently wrote a ledger. An opt-in flag only
+ *     protects the caller who already knows to pass it.
+ *   - Nothing asserted that a command documented as read-only performs no
+ *     writes, so a write in `report`/`matrix-check` would go unnoticed.
+ *   - `cleanup` deletes run records, and an unattended agent could invoke it
+ *     with no bound on what it deletes.
+ *
+ * The registry inverts that: safety is a property of the command, enforced by
+ * the dispatcher and asserted by tests, not a rule the caller must recall. An
+ * agent that does not know what a command does still cannot write by accident.
+ *
+ * Contract: docs/core/HarnessContract.md C13.
+ */
+
+/** Every command the CLI exposes, keyed by its invocation path. */
+export const COMMANDS = {
+  init: {
+    mutates: true,
+    summary: 'Install Cadet-Agent into the target directory.',
+    writes: ['AGENTS.md', '.cadet/**'],
+    unattended: true,
+  },
+  sync: {
+    mutates: true,
+    summary: 'Update the framework, preserving local policies and plans.',
+    writes: ['.cadet/**', 'AGENTS.md'],
+    unattended: true,
+  },
+
+  'state validate': {
+    mutates: false,
+    summary: 'Validate .cadet/state.json against the schema.',
+  },
+  'state migrate': {
+    mutates: true,
+    summary: 'Atomically migrate v1 state to the current version.',
+    writes: ['.cadet/state.json', '.cadet/state.json.v1.bak'],
+    unattended: false,
+    // A failed migration must leave the tree exactly as it found it: no backup,
+    // no partial write. The backup is an artifact of a *successful* migration,
+    // so producing one and then failing would be a write the caller did not get.
+    atomicFailure: true,
+  },
+  'state transition': {
+    mutates: true,
+    summary: 'Enforce the transition matrix and evidence; applies the transition.',
+    writes: ['.cadet/state.json'],
+    unattended: true,
+    // `--dry-run` here is not merely "don't write" — it reports the *same
+    // verdict* a real transition would (`allowed`, plus every missing or stale
+    // gate), which is the entire point of the flag. The handler therefore keeps
+    // ownership of the dry-run path and the global interception stands down.
+    // Collapsing the two meanings would replace a useful verdict with a bare
+    // "nothing was written". Contract C13.
+    evaluatesOnDryRun: true,
+  },
+
+  'harness record': {
+    mutates: true,
+    summary: 'Append a sanitized span/evidence/decision event to the run ledger.',
+    writes: ['.cadet/runs/**'],
+    unattended: true,
+  },
+  'harness confirm': {
+    mutates: true,
+    summary: 'Record manual-confirmation evidence (ledger + state).',
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
+    unattended: true,
+  },
+  'harness verify': {
+    mutates: true,
+    summary: 'Run a bounded, classified verification loop.',
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
+    unattended: true,
+  },
+  'harness verify-acs': {
+    mutates: true,
+    summary: 'Verify declared AC↔test coverage; may write coverage + state.',
+    writes: ['.cadet/runs/**', '.cadet/state.json', '*.coverage.json'],
+    unattended: true,
+  },
+  'harness report': {
+    mutates: false,
+    summary: 'Summarize budget consumption and failures.',
+  },
+  'harness matrix-check': {
+    mutates: false,
+    summary: 'Reconcile a TDD matrix against a compiled test inventory.',
+  },
+  'harness capabilities': {
+    mutates: false,
+    summary: 'Report available CLI/Unity/MCP/hook/token/cost telemetry.',
+  },
+  'harness cleanup': {
+    mutates: true,
+    summary: 'Apply the retention policy to .cadet/runs/, deleting run records.',
+    writes: ['.cadet/runs/**'],
+    // Destructive and irreversible for the records it removes. An unattended
+    // agent may only run it with an explicit, content-bearing bound on what it
+    // deletes — see `requiresForUnattended`. A bare "yes" would be a boolean the
+    // agent can always supply without knowing what it is approving.
+    unattended: false,
+    requiresForUnattended: ['--older-than-ms'],
+  },
+};
+
+/** The set of commands that write to the filesystem. */
+export function mutatingCommands() {
+  return Object.entries(COMMANDS).filter(([, c]) => c.mutates).map(([k]) => k);
+}
+
+/** The set of commands that are guaranteed not to write. */
+export function readOnlyCommands() {
+  return Object.entries(COMMANDS).filter(([, c]) => !c.mutates).map(([k]) => k);
+}
+
+/**
+ * Resolve the command key for a parsed invocation.
+ *
+ * Top-level commands (`init`, `sync`) are keyed by name; `state`/`harness`
+ * subcommands are keyed by `<group> <sub>`. Returns null when the invocation
+ * does not name a known command — an unknown command is a usage error, and the
+ * caller reports it rather than guessing a safety posture.
+ */
+export function resolveCommand(argv) {
+  const top = argv[2];
+  if (!top) return null;
+  if (top === 'state' || top === 'harness') {
+    const sub = argv[3];
+    if (!sub || sub.startsWith('-')) return null;
+    const key = `${top} ${sub}`;
+    return Object.hasOwn(COMMANDS, key) ? key : null;
+  }
+  return Object.hasOwn(COMMANDS, top) ? top : null;
+}
+
+/** Describe a command for machine consumption. */
+export function describeCommand(key) {
+  const c = COMMANDS[key];
+  if (!c) return null;
+  return {
+    command: key,
+    mutates: c.mutates === true,
+    summary: c.summary,
+    writes: c.mutates ? c.writes ?? [] : [],
+    unattended: c.unattended !== false,
+    requiresForUnattended: c.requiresForUnattended ?? [],
+    // True when `--dry-run` yields a verdict from the command's own evaluator
+    // rather than a generic no-op acknowledgement.
+    evaluatesOnDryRun: c.evaluatesOnDryRun === true,
+  };
+}
+
+/** The full registry as a machine-readable list, sorted by command path. */
+export function describeAllCommands() {
+  return Object.keys(COMMANDS).sort().map(describeCommand);
+}
+
+/**
+ * Check that an invocation carries the flags a command requires when it may run
+ * unattended. Returns `{ ok: true }` or `{ ok: false, missing, reason }`.
+ *
+ * `--dry-run` satisfies nothing here on purpose: a dry run does not perform the
+ * action, so it is never a substitute for the bound the action requires.
+ */
+export function checkUnattendedRequirements(key, opts) {
+  const c = COMMANDS[key];
+  if (!c || c.mutates !== true) return { ok: true };
+  const required = c.requiresForUnattended ?? [];
+  if (required.length === 0) return { ok: true };
+
+  const missing = required.filter((flag) => {
+    if (flag === '--older-than-ms') {
+      return !Number.isFinite(opts.olderThanMs);
+    }
+    return true;
+  });
+  if (missing.length === 0) return { ok: true };
+  return {
+    ok: false,
+    missing,
+    reason: `"${key}" deletes records irreversibly, so it requires ${missing.join(', ')} when run unattended.`,
+  };
+}

package/src/harness/index.mjs

@@ -73,3 +73,8 @@ export {
 export {
   collectDeclaredTestNames, reconcileTestNames, inventoryFromCSharpSources,
 } from './matrix-check.mjs';
+
+export {
+  COMMANDS, mutatingCommands, readOnlyCommands, resolveCommand,
+  describeCommand, describeAllCommands, checkUnattendedRequirements,
+} from './commands.mjs';

package/src/harness/policy.mjs

@@ -162,6 +162,7 @@ export const EXCEPTION_CATEGORIES = Object.freeze([
   'unscoped-freshness',
   'documentation-only',
   'tooling-gap',
+  'pre-harness-story',
 ]);
 
 /** Default expiry (in days) per category. `null` means "no default bound". */
@@ -172,6 +173,11 @@ export const EXCEPTION_EXPIRY_DAYS = Object.freeze({
   'unscoped-freshness': 1,
   'documentation-only': null,   // scoped to the work item
   'tooling-gap': 14,
+  // No default bound: this records a PERMANENT historical fact (a story closed
+  // before the harness existed, whose gates were never recorded as evidence).
+  // The gap will never close on its own, so a time-bounded exception would only
+  // re-raise the same finding every N days without anything having changed.
+  'pre-harness-story': null,
 });
 
 /** Categories whose exception must carry a closure review note. */

package/src/harness/state.mjs

@@ -231,19 +231,37 @@ export function validateState(state, context = {}) {
     // It is an ERROR, not a warning, because a `done` story with no evidence is
     // indistinguishable from a story that was never verified — which is the
     // condition the framework exists to prevent. Projects that closed stories
-    // before the harness existed can resolve it with a scoped gate exception or
-    // by re-recording; silently tolerating it is what let the gap grow.
+    // before the harness existed resolve it with a scoped `pre-harness-story`
+    // exception naming the story's work item; silently tolerating it is what let
+    // the gap grow.
     if (isPlainObject(state.epics) && Array.isArray(state.gateEvidence)) {
       const evidenced = new Set(
         state.gateEvidence
           .map((e) => (isPlainObject(e) ? e.workItemId : null))
           .filter((id) => typeof id === 'string' && id.length > 0),
       );
+      // A scoped exception is the FIRST-CLASS escape for a permanent historical
+      // gap. `activeExceptions` is keyed on the ACTIVE work item, which is the
+      // current story — the wrong scope here, where we walk every completed story
+      // — so the scope match is done explicitly against each story's work-item id.
+      // Only a valid, categorised exception counts: an unknown category is not a
+      // loophole, it is a typo, and `validateGateException` rejects it separately.
+      const excepted = new Set();
+      if (Array.isArray(state.changeHistory)) {
+        for (const entry of state.changeHistory) {
+          if (!isPlainObject(entry) || entry.type !== 'gate-exception') continue;
+          if (!EXCEPTION_CATEGORIES.includes(entry.category)) continue;
+          const scope = Array.isArray(entry.scope) ? entry.scope : (entry.scope ? [entry.scope] : []);
+          for (const s of scope) excepted.add(String(s));
+        }
+      }
       for (const [epicId, epic] of Object.entries(state.epics)) {
         if (!isPlainObject(epic) || !isPlainObject(epic.stories)) continue;
         for (const [storyId, status] of Object.entries(epic.stories)) {
           if (status !== 'done') continue;
-          if (evidenced.has(`${epicId}::${storyId}`)) continue;
+          const workItemId = `${epicId}::${storyId}`;
+          if (evidenced.has(workItemId)) continue;
+          if (excepted.has(workItemId)) continue;
           errors.push({
             path: `epics.${epicId}.stories.${storyId}`,
             message: `story "${storyId}" is marked done but has no evidence record for its work item `
@@ -583,16 +601,22 @@ export function migrateStateFile(statePath, { backup = true } = {}) {
   const tmpPath = join(tmpDir, 'state.json');
   try {
     writeFileSync(tmpPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
-    if (backup) {
-      copyFileSync(statePath, `${statePath}.v1.bak`);
-    }
-    // A failed rename leaves the original in place; validate before committing.
+    // Validate BEFORE writing anything to the real tree. The backup is an
+    // artifact of a *successful* migration, so producing one and then failing
+    // would leave a write the caller never got and did not ask for — a failed
+    // `migrate` must leave the directory exactly as it found it. Checking first
+    // also means a bad migration cannot overwrite a previous good backup.
+    //
     // This is a structural-only check: a freshly migrated state has no on-disk
     // evidence to bind, so freshness is intentionally not evaluated here.
     const check = validateState(state, { structuralOnly: true });
     if (!check.valid) {
       throw new StateError(`migrated state failed validation: ${check.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
     }
+    if (backup) {
+      copyFileSync(statePath, `${statePath}.v1.bak`);
+    }
+    // A failed rename leaves the original in place.
     renameSync(tmpPath, statePath);
   } finally {
     rmSync(tmpDir, { recursive: true, force: true });