cadet-agent 0.47.0 → 0.49.0

package/package.json

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

package/src/cli.mjs

@@ -6,7 +6,7 @@ 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,
@@ -17,7 +17,7 @@ import {
   collectDeclaredTestNames, reconcileTestNames,
   resolveCommand, describeCommand, describeAllCommands, checkUnattendedRequirements, COMMANDS,
   STATE_VERSION, sealedEvidence, recordEvidence, appendEvidence, sealWorkItem, toStateV4,
-  isHistoryExternal, HISTORY_ENTRIES_KEPT,
+  isHistoryExternal, HISTORY_ENTRIES_KEPT, resetGatesForNewWorkItem,
 } from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -50,6 +50,7 @@ function showHelp() {
     cadet-agent state migrate       Atomically migrate state to the current version (backup on write)
     cadet-agent state migrate --to 4   Compact: archive closed work items' evidence, build the index
     cadet-agent state compact --keep <bound>   Move closed work items' evidence into .cadet/archive/
+    cadet-agent state begin --epic <id> --story <file>   Start a work item: reset gates, archive the previous item's evidence
     cadet-agent state seal          Write the active work item's evidence as commit trailers
     cadet-agent state transition --to <phase>   Enforce the transition matrix + evidence
     cadet-agent state transition --to <phase> --dry-run   Check only; writes nothing
@@ -74,6 +75,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)
@@ -89,6 +91,8 @@ function showHelp() {
     --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)
+    --retain-all   state compact: keep every record of the kept work items; only cross-work-item records leave
+    --epic         Epic id of the work item being started (state begin)
     --commit-msg   Path to write the prepared commit message to (state seal)
     --verify-sealed  Also verify evidence sealed in commit trailers (state validate)
     --dry-run      Report what a mutating command would do and write nothing (all mutating commands)
@@ -154,6 +158,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;
@@ -166,6 +173,12 @@ function parseArgs(argv) {
       // working-tree scan (which could bind evidence to Cadet's own files).
       case '--files': opts.filesGiven = true; opts.files = value(a).split(',').map((s) => s.trim()).filter(Boolean); break;
       case '--story': opts.story = value(a); break;
+      // state begin: the epic the new work item belongs to.
+      case '--epic': opts.epicId = value(a); break;
+      // state compact: keep every record inline instead of applying the
+      // within-work-item retention rule. Made explicit at the call site, because
+      // otherwise a reader cannot tell a retained document from an unbounded one.
+      case '--retain-all': opts.retainAll = true; 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.
@@ -236,6 +249,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) ──────────────────────────────────────────
 
 /**
@@ -493,7 +540,7 @@ async function cmdState(opts) {
       fail(opts, `state.json is v${state.version ?? state.stateVersion}; compaction requires v${STATE_VERSION}. Run "cadet-agent state migrate --to ${STATE_VERSION}" first.`, () => 1, { ok: false, code: 'compact-requires-v4' });
     }
     const keep = parseKeepBound(opts.keep);
-    const { state: next, archived, archivedHistory } = toStateV4(state, { keep });
+    const { state: next, archived, archivedHistory } = toStateV4(state, { keep, retainAll: opts.retainAll === true });
     const written = appendEvidenceArchive(opts.targetDir, archived);
     const history = appendHistoryArchive(opts.targetDir, archivedHistory);
     const changed = archived.length > 0 || archivedHistory.length > 0;
@@ -501,7 +548,7 @@ async function cmdState(opts) {
     emit(
       opts,
       changed
-        ? `✅ Compacted state.json: archived ${archived.length} evidence record(s), ${history.appended} change-log entr(ies); kept ${next.gateEvidence.length} record(s) and ${(next.changeHistory || []).length} entr(ies) inline.\n   Archive: ${join(opts.targetDir, '.cadet', 'archive')}`
+        ? `✅ Compacted state.json: archived ${archived.length} evidence record(s), ${history.appended} change-log entr(ies); kept ${next.gateEvidence.length} record(s) and ${(next.changeHistory || []).length} entr(ies) inline.${opts.retainAll ? '\n   --retain-all: every kept work item\'s records stay inline, so only cross-work-item records left.' : ''}\n   Archive: ${join(opts.targetDir, '.cadet', 'archive')}`
         : '✅ Nothing to compact: every evidence record and change-log entry is already kept inline.',
       {
         ok: true,
@@ -517,6 +564,62 @@ async function cmdState(opts) {
     return;
   }
 
+  if (sub === 'begin') {
+    // The story boundary, as a command.
+    //
+    // It existed only as a sentence in `skills/Resume.md` — "set `activeWorkItem`,
+    // reset gates" — which an agent carried out by editing state.json by hand, and
+    // the sentence never mentions evidence. So the previous work item's records
+    // stayed inline for ever. On the audited repository that was 63 records and
+    // ~3,000 lines, none of which any gate could read: `evidenceFreshness` rejects
+    // a record whose `workItemId` is not the active one. `resetGatesForNewWorkItem`
+    // already did the job correctly — cleared the evidence, folded it into the
+    // coverage index first, dropped expired exceptions, wrote one boundary line —
+    // and had no caller. This is the door.
+    if (!opts.epicId) fail(opts, 'state begin requires --epic <epicId>');
+    if (!opts.story) fail(opts, 'state begin requires --story <storyFile>');
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before starting a work item.', () => 2);
+
+    const fromId = state.activeWorkItem ? workItemIdOf(state) : null;
+    const toId = `${opts.epicId}::${opts.story}`;
+    if (fromId === toId) {
+      fail(opts, `the active work item is already "${toId}"; nothing to begin.`, () => 1, { ok: false, code: 'already-active', workItemId: toId });
+    }
+    // `closed` is terminal: Resume says new work starts from a fresh session
+    // (context-resolution) rather than by beginning a work item inside a plan that
+    // is already finished.
+    if (state.session?.currentPhase === 'closed') {
+      fail(opts, 'the session is closed — start new work from a fresh session (context-resolution) rather than beginning a work item inside a closed plan.', () => 1, { ok: false, code: 'session-closed' });
+    }
+
+    // Nothing leaves state.json without being written down first (contract v5 §1).
+    // The reset folds the outgoing records into the coverage index, which is a
+    // *summary* — so the records themselves are archived here, exactly as `compact`
+    // archives a closed work item's, and before the document is written.
+    const outgoing = Array.isArray(state.gateEvidence) ? state.gateEvidence : [];
+    const written = appendEvidenceArchive(opts.targetDir, outgoing);
+    const next = resetGatesForNewWorkItem(state, { epicId: opts.epicId, storyId: opts.story });
+    writeState(opts.targetDir, next);
+    emit(
+      opts,
+      `✅ Began ${toId}.\n   Gates reset; ${outgoing.length} evidence record(s) archived (${written.appended} appended, ${written.skipped} already archived).`
+      + (fromId ? `\n   Previous work item: ${fromId}` : '')
+      + `\n   Coverage rows: ${Object.keys(next.evidenceCoverage || {}).length}`,
+      {
+        ok: true,
+        from: fromId,
+        to: toId,
+        gatesReset: true,
+        archived: written.appended,
+        alreadyArchived: written.skipped,
+        coverageRows: Object.keys(next.evidenceCoverage || {}).length,
+        archivePaths: written.files,
+      },
+    );
+    return;
+  }
+
   if (sub === 'seal') {
     const { exists, state } = readState(opts.targetDir);
     if (!exists) fail(opts, 'No .cadet/state.json found.', () => 2);
@@ -618,7 +721,7 @@ async function cmdState(opts) {
     return;
   }
 
-  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|compact|seal|transition.`);
+  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|compact|begin|seal|transition.`);
 }
 
 /**
@@ -672,6 +775,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;
@@ -829,6 +933,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 }
@@ -973,6 +1078,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';
@@ -1082,6 +1188,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,
@@ -1092,9 +1218,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
@@ -1162,6 +1290,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';

package/src/harness/commands.mjs

@@ -72,6 +72,15 @@ export const COMMANDS = {
     unattended: false,
     requiresForUnattended: ['--keep'],
   },
+  'state begin': {
+    mutates: true,
+    summary: 'Start a work item: reset gates, archive the previous item\'s evidence, fold it into the coverage index.',
+    writes: ['.cadet/state.json', '.cadet/archive/**'],
+    // The bound is already content-bearing: `--epic` and `--story` name the work
+    // item being started, so an unattended caller cannot begin one without saying
+    // which. That is why this needs no separate confirmation flag.
+    unattended: true,
+  },
   'state transition': {
     mutates: true,
     summary: 'Enforce the transition matrix and evidence; applies the transition.',

package/src/harness/index.mjs

@@ -34,7 +34,7 @@ export {
   STATE_VERSION, READABLE_STATE_VERSIONS, HISTORY_EXTERNAL_SINCE, isHistoryExternal,
   validateState, migrateStateV1toV2, migrateStateDocument, migrateStateFile, parseTargetVersion,
   toStateV4, splitEvidence, buildEvidenceCoverage, mergeEvidenceCoverage, sealWorkItem, recordEvidence, appendEvidence,
-  HISTORY_ENTRIES_KEPT, compactHistory,
+  HISTORY_ENTRIES_KEPT, compactHistory, DEFAULT_MAX_LIVE_EVIDENCE, retainLiveRecords,
   createEvidence, computeInputTreeHash, workItemIdOf, evidenceFreshness,
   latestEvidenceForGate, activeExceptions, requiredGates, isUngatedForwardEdge, evaluateTransition, resolveStrict,
   applyTransition, resetGatesForNewWorkItem, statePathFor, readState, writeState, writeJsonAtomic, StateError,

package/src/harness/state.mjs

@@ -150,6 +150,50 @@ export function validateState(state, context = {}) {
         for (const e of validateEvidenceShape(ev, strict)) errors.push({ path: `gateEvidence[${i}].${e.path}`, message: e.message });
       });
     }
+    // Contract v5 C14 says a v4 document's `gateEvidence` holds the ACTIVE work
+    // item's records — and in practice it did not. The story boundary is a
+    // hand-edit (`skills/Resume.md`: "set `activeWorkItem`, reset gates"), that
+    // sentence says nothing about evidence, and `resetGatesForNewWorkItem` — the
+    // function that clears it correctly — has no caller. Nothing surfaced the
+    // result: the gate checks below only ever ask whether a claimed-true gate's
+    // OWN record is bound to the active item, never whether foreign records are
+    // sitting in the array. On the audited repository that was 63 records and
+    // ~3,000 lines of dead weight inside an 8,000-line document.
+    //
+    // Warnings, not errors. A foreign record is unreadable by every gate check
+    // (`evidenceFreshness` rejects the work-item mismatch), so this is hygiene
+    // rather than a safety violation; and an error would invalidate every document
+    // that predates the check, on upgrade, for a condition its reader cannot
+    // repair in place. Only v4 documents are scoped this way — a v1-v3 document
+    // keeps every record inline by design.
+    if (version === STATE_VERSION && Array.isArray(state.gateEvidence)) {
+      const active = isPlainObject(state.activeWorkItem) ? state.activeWorkItem : null;
+      const activeId = active ? `${active.epicId || 'none'}::${active.storyId || 'none'}` : null;
+      const foreign = new Map();
+      for (const record of state.gateEvidence) {
+        const id = record?.workItemId;
+        if (!id || id === activeId) continue;
+        foreign.set(id, (foreign.get(id) || 0) + 1);
+      }
+      if (foreign.size > 0) {
+        const total = [...foreign.values()].reduce((a, b) => a + b, 0);
+        const named = [...foreign.entries()].map(([id, n]) => `${id} (${n})`).join(', ');
+        warnings.push({
+          path: 'gateEvidence',
+          message: `gateEvidence holds ${total} record(s) for work item(s) that are not the active one: ${named}. `
+            + 'They cannot satisfy any gate and only grow the document. Run "cadet-agent state compact --keep active" to move them to .cadet/archive/.',
+        });
+      }
+      const maxLive = context.maxLiveEvidence ?? DEFAULT_MAX_LIVE_EVIDENCE;
+      if (Number.isFinite(maxLive) && state.gateEvidence.length > maxLive) {
+        warnings.push({
+          path: 'gateEvidence',
+          message: `gateEvidence holds ${state.gateEvidence.length} records inline (limit ${maxLive}). `
+            + 'Most of a record is its `relevantFiles` list, so re-running a gate inflates the document rather than the story. '
+            + 'Run "cadet-agent state compact --keep active", which keeps the newest record per gate plus the red-before-green records and archives the rest.',
+        });
+      }
+    }
     // Gate exceptions are categorised under strict closure (contract v3 §4).
     //
     // v4 gives them their own field, because they are *live state* — scoped to a
@@ -688,16 +732,21 @@ export function compactHistory(entries, { keepRecent = HISTORY_ENTRIES_KEPT } =
 }
 
 /**
- * Reshape a document into v4 (contract v5): keep only the active work item's
+ * Reshape a document into v4 (contract v5): keep the active work item's live
  * evidence inline, move the rest to `archived` for the caller to persist, promote
  * gate exceptions into their own field, bound the change log, and install the
  * coverage index.
  *
+ * Two independent bounds decide what stays inline — `keep` selects the work items
+ * and `retainAll` controls the within-item retention described on
+ * `retainLiveRecords`. Passing `retainAll: true` keeps an item's whole record set,
+ * which is the pre-retention behaviour.
+ *
  * Pure — it returns the records to archive rather than writing them, so the
  * caller owns the archive location and this stays testable without a filesystem.
  */
-export function toStateV4(state, { keep = 'active', keepHistory = HISTORY_ENTRIES_KEPT } = {}) {
-  const { live, archived, coverage } = splitEvidence(state, { keep });
+export function toStateV4(state, { keep = 'active', keepHistory = HISTORY_ENTRIES_KEPT, retainAll = false } = {}) {
+  const { live, archived, coverage } = splitEvidence(state, { keep, retainAll });
 
   const promoted = [];
   const remainingHistory = [];
@@ -1177,8 +1226,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 +1262,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 +1402,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 +1419,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);
     }
@@ -1510,10 +1576,11 @@ export function mergeEvidenceCoverage(existing, records) {
  * merely conservative — it is provably safe for any document that was valid before
  * compaction: `validateState` already rejects a claimed-true gate whose supporting
  * record belongs to a *different* work item, so every gate a valid document
- * depends on is already backed by exactly the records this keeps. A stricter
- * selector (say, "newest passing record per gate") would be smaller and would
- * silently break the red-before-green rule, which needs the prior failing record
- * for the same work item and gate to still exist.
+ * depends on is already backed by exactly the records this keeps.
+ *
+ * This selector answers *which work item*. It deliberately does not answer *which
+ * of that item's records* — see `retainLiveRecords` for that second, independent
+ * bound, and for why "newest passing record per gate" would be wrong on its own.
  */
 function keepSelector(keep, state) {
   if (keep === 'always') return () => true;
@@ -1532,23 +1599,88 @@ function keepSelector(keep, state) {
   throw new StateError(`unknown keep selector ${JSON.stringify(keep)}; expected "always", "active", or a list of work item ids`);
 }
 
+/**
+ * How many evidence records may stay inline for one work item before
+ * `state validate` warns.
+ *
+ * A record is ~24 fields plus one line per path in `relevantFiles`, and a long
+ * story re-records the same gate many times, so the array grows with *re-runs*
+ * rather than with the size of the story. Measured on the audited repository: 26
+ * `testsPassed` records for a single story, of which one was live.
+ */
+export const DEFAULT_MAX_LIVE_EVIDENCE = 60;
+
+/**
+ * Which of one work item's records stay inline.
+ *
+ * `keepSelector` answers *which work item*; this answers *which of its records*,
+ * and the two bounds are independent. Without this second one, a single long
+ * story's re-run history stays for ever — the story boundary never fires inside a
+ * story, so nothing bounds it.
+ *
+ * The retained set is exactly what the machinery can still read:
+ *
+ *   - the **newest record per gate**, because `latestEvidenceForGate` reads
+ *     precisely that and a newer record shadows every older one for its gate;
+ *   - every **`passed` / `manual-confirmation`** record, because a claimed-true
+ *     gate must be backed by one, and "newest per gate" alone would drop a live
+ *     record that a later-appended but *older-stamped* record shadows (a
+ *     `manual-confirmation` may carry its own `at`);
+ *   - every **`failed`** record, because red-before-green reads the prior red for
+ *     the same work item and gate (`runVerificationLoop`'s `priorEvidence`).
+ *
+ * Everything else — `superseded`, and `blocked` that is not the newest for its
+ * gate — is history. It leaves the document exactly as a closed work item's
+ * records do: same archive, same ordering guarantee, same coverage rebuild.
+ */
+export function retainLiveRecords(records, { retainAll = false } = {}) {
+  const list = Array.isArray(records) ? records : [];
+  if (retainAll) return new Set(list);
+
+  const at = (record) => {
+    const parsed = Date.parse(record?.createdAt);
+    return Number.isFinite(parsed) ? parsed : -Infinity;
+  };
+
+  const newestByGate = new Map();
+  for (const record of list) {
+    if (!record || typeof record !== 'object' || !record.gate) continue;
+    const current = newestByGate.get(record.gate);
+    if (!current || at(record) >= at(current)) newestByGate.set(record.gate, record);
+  }
+
+  const retained = new Set(newestByGate.values());
+  for (const record of list) {
+    if (!record || typeof record !== 'object') continue;
+    if (record.status === 'passed' || record.status === 'manual-confirmation' || record.status === 'failed') {
+      retained.add(record);
+    }
+  }
+  return retained;
+}
+
 /**
  * Split a document's evidence into the part that stays live and the part that
  * becomes history (contract v5).
  *
- * "Live" is defined by a keep selector, defaulting to the active work item — see
- * `keepSelector` for why that boundary is the safe one.
+ * Two independent bounds decide "live": the keep selector (which work items),
+ * defaulting to the active one — see `keepSelector` for why that boundary is safe
+ * — and `retainLiveRecords` (which of that item's records), which is what bounds
+ * a single long story.
  *
  * Returns `{ live, archived, coverage }`. Pure: no I/O, so the caller decides
  * where the archive is written.
  */
-export function splitEvidence(state, { keep = 'active' } = {}) {
+export function splitEvidence(state, { keep = 'active', retainAll = false } = {}) {
   const records = Array.isArray(state?.gateEvidence) ? state.gateEvidence : [];
   const keepRecord = keepSelector(keep, state);
+  const inScope = records.filter((record) => keepRecord(record));
+  const retained = retainLiveRecords(inScope, { retainAll });
   const live = [];
   const archived = [];
   for (const record of records) {
-    if (keepRecord(record)) live.push(record);
+    // Original order is preserved on both sides so the archive stays readable.
+    if (inScope.includes(record) && retained.has(record)) live.push(record);
     else archived.push(record);
   }
   const prior = isPlainObject(state?.evidenceCoverage) ? state.evidenceCoverage : {};