cadet-agent 0.48.0 → 0.53.0

package/README.md

@@ -2,7 +2,7 @@
 
 Cadet-Agent is an **opinionated** cross-IDE agent framework for game-development workflows. It is built on foundational software engineering practices and real-world game-development experience, with the goal of **guiding you through the entire development process** — from requirements and technical design through TDD, implementation, and review.
 
-Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished game from a single prompt. Instead, it walks you through each phase methodically: calibrating the learner model, scoping work into epics and stories, planning architecture, writing tests first, and iterating on feedback. The shared framework core integrates with GitHub Copilot, Cursor, Continue, Claude Code, and Deep Code.
+Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished game from a single prompt. Instead, it walks you through each phase methodically: calibrating the learner model, scoping work into epics and stories, planning architecture, writing tests first, and iterating on feedback. The shared framework core integrates with GitHub Copilot, Cursor, Continue, Claude Code, Deep Code, and Hermes.
 
 ## Repository Layout
 - `.cadet/agent/core/` contains the shared Cadet-Agent framework documents.
@@ -20,7 +20,7 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
 - `.cursor/` contains Cursor-specific authored files.
 - `.continue/` contains Continue-specific authored files.
 - `.claude/` contains Claude Code-specific authored files.
-- `.agents/skills/` contains Deep Code (and cross-client) skill adapters.
+- `.agents/skills/` contains Deep Code / Hermes (cross-client) skill adapters.
 - These IDE folders hold thin integration shims; the core framework logic still lives in `.cadet/agent/core/`.
 - `package-agent.ps1` builds the distributable `cadet-agent.zip` package.
 - `bump-version.ps1` bumps the version, updates version-bearing files, commits, tags, and pushes. It runs `npm run lint` first and refuses to release if the link check fails.
@@ -28,27 +28,27 @@ 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 11 skills + reviewer are available in each:
-
-| Feature | GitHub Copilot | Cursor | Continue | Claude Code | Deep Code |
-|---|---|---|---|---|---|
-| Auto-load rules | Agent definition | `alwaysApply` rule | Project rule | Project skill | Project skill (`.agents/skills/`) |
-| Skill dispatch | `/cadet-<skill>` prompts | Natural language | `/cadet-<skill>` commands | `/cadet-<skill>` skills | `/skills` menu (`/`) |
-| Planning Review | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Requirements | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Architecture | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Spike | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Story Breakdown | ✅ | ✅ | ✅ | ✅ | ✅ |
-| TDD | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Debugging | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 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`) |
-
-All adapters delegate to the canonical files under `.cadet/agent/core/` — no duplicated rules or skills. See `ADAPTERS.md` for the full inventory and `docs/guidance/DeepCode.md` for Deep Code setup.
+Cadet-Agent provides full workflow parity across six IDEs. The same 11 skills + reviewer are available in each:
+
+| Feature | GitHub Copilot | Cursor | Continue | Claude Code | Deep Code | Hermes |
+|---|---|---|---|---|---|---|
+| Auto-load rules | Agent definition | `alwaysApply` rule | Project rule | Project skill | Project skill (`.agents/skills/`) | Project skill (`.agents/skills/`) |
+| Skill dispatch | `/cadet-<skill>` prompts | Natural language | `/cadet-<skill>` commands | `/cadet-<skill>` skills | `/skills` menu (`/`) | `/cadet-<skill>` commands |
+| Planning Review | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Requirements | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Spike | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Story Breakdown | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| TDD | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Debugging | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Code Review | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Resume | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| MCP Setup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reconciliation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` | `cadet-agent-reviewer` skill | `/cadet-agent-reviewer` |
+| Git guard | PreToolUse hook | Manual | Manual | Manual | `permissions.ask` (`mutate-git-log`) | Command approval policies |
+
+All adapters delegate to the canonical files under `.cadet/agent/core/` — no duplicated rules or skills. See `ADAPTERS.md` for the full inventory, `docs/guidance/DeepCode.md` for Deep Code setup, and `docs/guidance/Hermes.md` for Hermes setup.
 
 ## Quick Install
 
@@ -299,6 +299,17 @@ Because Deep Code has no PreToolUse hook, enforce the commit/push approval gate
 
 See `docs/guidance/DeepCode.md` for the full setup, MCP wiring, and configuration reference.
 
+### Hermes request
+With [Hermes Agent](https://hermes-agent.nousresearch.com/docs/) installed (`iex (irm https://hermes-agent.nousresearch.com/install.ps1)` on native Windows), run `hermes` in the repository and confirm the `cadet-*` skills are discovered from `.agents/skills/` — the first run requires `hermes skills trust` to enable project skills. Then invoke a skill directly:
+
+```text
+/cadet-tdd for the ghost-replay story
+```
+
+Because Hermes has no PreToolUse hook, enable command approval policies so commit/push require confirmation (see the [Hermes security docs](https://hermes-agent.nousresearch.com/docs/user-guide/security)).
+
+See `docs/guidance/Hermes.md` for the full setup, MCP wiring, and configuration reference.
+
 ### Repository policy example
 If a specific game repository needs local conventions, add a policy file under `.cadet/agent/policies` using `.cadet/agent/core/Templates/PolicyTemplate.md`. For example, a repository policy could define:
 - where project plans should live

package/package.json

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

package/src/cli.mjs

@@ -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
@@ -90,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)
@@ -170,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.
@@ -531,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;
@@ -539,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,
@@ -555,6 +564,72 @@ 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);
+    // The boundary records the outgoing work item as complete (see
+    // `resetGatesForNewWorkItem`), so report it: that record is the answer to "is
+    // this story finished, with its epic still open?" — the question the framework
+    // had no vocabulary for.
+    const completed = fromId && Array.isArray(next.storyCompletions)
+      ? next.storyCompletions.find((row) => row?.workItemId === fromId) ?? null
+      : null;
+    emit(
+      opts,
+      `✅ Began ${toId}.\n   Gates reset; ${outgoing.length} evidence record(s) archived (${written.appended} appended, ${written.skipped} already archived).`
+      + (completed
+        ? `\n   Completed: ${completed.workItemId} (${completed.evidenceRecords} evidence record(s) behind it)`
+        : fromId ? `\n   Previous work item: ${fromId}` : '')
+      + `\n   Coverage rows: ${Object.keys(next.evidenceCoverage || {}).length}`,
+      {
+        ok: true,
+        from: fromId,
+        to: toId,
+        gatesReset: true,
+        completed: completed ? { workItemId: completed.workItemId, completedAt: completed.completedAt } : null,
+        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);
@@ -656,7 +731,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.`);
 }
 
 /**
@@ -1153,6 +1228,12 @@ 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,
+      // The revision this coverage claim attests, when the caller names one. AR-1/the
+      // citation policy make it required once the gated work is committed: without it the
+      // record can name its work item and its files but never the commit, and a reviewer
+      // has no structured way to check the claim (Harness.md §1). Validated and normalized
+      // by createEvidence, so a branch or tag name is refused rather than stored.
+      commit: opts.commit || null,
       // Audit pointer only. Not a relevant file: see above.
       artifactPath: reportPath ? reportPath.replace(/\\/g, '/') : null,
       inputTreeHash: computeInputTreeHash(opts.targetDir, [storyRel]),
@@ -1322,6 +1403,10 @@ async function cmdHarness(opts) {
         ? `reachability addressed (${validation.code}); project probe exit ${probe.exitCode}`
         : `reachability addressed (${validation.code}); no project probe configured`,
       exitCode: 0,
+      // Same citation requirement as verify-acs: the declaration is what is being attested,
+      // and it is attested of a revision. Validated and normalized by createEvidence, so a
+      // branch or tag name is refused rather than stored.
+      commit: opts.commit || null,
       inputTreeHash: computeInputTreeHash(opts.targetDir, [storyRel]),
       criteriaHash: hashCriteria([
         workItemId,
@@ -1436,6 +1521,10 @@ async function cmdHarness(opts) {
   // `--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.
+  //
+  // A scope that names no epic is the one exception, and it is not a verdict: the
+  // request itself was unsatisfiable, so it exits 2 like every other bad argument
+  // rather than quietly reconciling a set the caller never asked about.
   if (sub === 'reconcile') {
     const { exists, state } = readState(opts.targetDir);
     const result = reconcileArtifacts(opts.targetDir, {
@@ -1444,6 +1533,8 @@ async function cmdHarness(opts) {
       story: opts.story || null,
     });
 
+    if (result.scopeError) fail(opts, result.reason, () => 2);
+
     if (opts.format === 'json') {
       emit(opts, '', result);
       return;

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/reconcile.mjs

@@ -31,7 +31,11 @@
  * 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.
+ * an accepted historical gap is a recorded gate-exception, not silence. That
+ * exception is therefore HONOURED here rather than merely permitted: a gap an
+ * exception covers is reported as `info` naming the exception, because a blocking
+ * section filled with rows a human already ruled on teaches its reader to ignore
+ * the whole report.
  *
  * 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
@@ -48,9 +52,10 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { basename, isAbsolute, join, relative } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 
 import { PHASES } from './policy.mjs';
+import { activeExceptionEntries } from './state.mjs';
 import {
   collectWorkItems,
   parseReachabilityDeclaration,
@@ -306,14 +311,16 @@ export function collectArtifacts(targetDir, {
     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, '..'));
-  }
+  // Scope to one epic when a story or epic 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.
+  //
+  // RESOLVED here, APPLIED by the caller. Collecting the whole tree first is what
+  // lets `reconcileArtifacts` refuse a scope that names nothing: filtering during
+  // collection made an unrecognised argument indistinguishable from no argument
+  // at all, which is how an epic *directory* came to be understood as the literal
+  // scope `"epics"` and reconciled every epic regardless.
+  const scopedEpic = resolveScope(targetDir, story);
 
   const epics = [];
   for (const dir of dirs) {
@@ -323,7 +330,6 @@ export function collectArtifacts(targetDir, {
     // 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 = [];
@@ -355,6 +361,45 @@ export function collectArtifacts(targetDir, {
   return { available: true, reason: null, root, docs, epics, scopedEpic };
 }
 
+/**
+ * The epic key that a `--story` argument names.
+ *
+ * Accepts what a caller actually has to hand: the path to a story file, the path
+ * to `epic.md`, the epic's own directory, or the epic's key on its own. A FILE
+ * lives inside its epic; anything else IS the epic. Getting this wrong is not
+ * harmless: the previous version took the parent directory of whatever it was
+ * given, so an epic *directory* resolved to `"epics"` — a key that matches no
+ * epic — and the request was silently reinterpreted as "reconcile everything".
+ */
+function resolveScope(targetDir, story) {
+  if (!story) return null;
+  const abs = isAbsolute(story) ? story : join(targetDir, story);
+  return /\.md$/i.test(abs) ? basename(dirname(abs)) : basename(abs);
+}
+
+/**
+ * Refuse a scope that names nothing.
+ *
+ * The caller asked about ONE epic. Answering about a different set — or about all
+ * of them — is a wrong answer delivered confidently, which is worse than an error
+ * the user can correct; `Principles.md` says to state uncertainty explicitly
+ * rather than guess, and a scope that resolves to nothing is the guess.
+ *
+ * An epic tracked in `state.json` but absent from disk is NOT a failure: that is
+ * the `missing-epic-dir` finding, which is the whole point of asking.
+ */
+function scopeFailure(scope, collected, stateEpics) {
+  if (!scope) return null;
+  if (collected.epics.some((e) => e.key === scope)) return null;
+  if (Object.hasOwn(stateEpics, scope)) return null;
+  const known = [...new Set([...collected.epics.map((e) => e.key), ...Object.keys(stateEpics)])].sort();
+  return `--story scope \`${scope}\` matches no epic on disk or in state.json, so nothing was reconciled. `
+    + (known.length > 0
+      ? `Known epics: ${known.map((k) => `\`${k}\``).join(', ')}.`
+      : 'No epic directories were found under the plans directory.')
+    + ' Pass an epic directory, an epic key, or the path to one of its story files.';
+}
+
 /**
  * Reconcile the planning tree against `state.json`.
  *
@@ -369,6 +414,25 @@ export function reconcileArtifacts(targetDir, {
 } = {}) {
   const collected = collectArtifacts(targetDir, { plansDir, story, maxBytes });
   const plansDirRel = toPosix(plansDir);
+  const stateEpics = state?.epics && typeof state.epics === 'object' ? state.epics : {};
+
+  // ── 0. An explicit scope must name an epic ────────────────────────────────
+  // Checked before anything else, so a scope that names nothing is refused rather
+  // than answered with the whole tree.
+  const scopeError = scopeFailure(collected.scopedEpic, collected, stateEpics);
+  if (scopeError) {
+    return {
+      ok: false,
+      available: true,
+      plansDir: plansDirRel,
+      scopedEpic: collected.scopedEpic,
+      scopeError,
+      verdict: 'unknown',
+      findings: [],
+      summary: { total: 0, blocking: 0, warning: 0, info: 0 },
+      reason: scopeError,
+    };
+  }
 
   if (!collected.available) {
     return {
@@ -383,7 +447,12 @@ export function reconcileArtifacts(targetDir, {
     findings.push({ code, severity, subject, artifact, detail, evidence });
   };
 
-  const stateEpics = state?.epics && typeof state.epics === 'object' ? state.epics : {};
+  // Apply the scope (validated above): every per-epic and per-story check below
+  // must see only the epic that was asked about.
+  const epics = collected.scopedEpic
+    ? collected.epics.filter((e) => e.key === collected.scopedEpic)
+    : collected.epics;
+
   const phase = state?.session?.currentPhase ?? null;
   const workflowPath = state?.session?.workflowPath ?? null;
   const phaseIndex = PHASES.indexOf(phase);
@@ -405,15 +474,21 @@ export function reconcileArtifacts(targetDir, {
   }
 
   // ── 2. Epics: state vs disk, both directions ──────────────────────────────
-  const onDisk = new Set(collected.epics.map((e) => e.key));
+  const onDisk = new Set(epics.map((e) => e.key));
   for (const epicDir of Object.keys(stateEpics).sort()) {
+    // Compare only what is in scope. Iterating every epic in `state.json` while
+    // `onDisk` held just the scoped epic reported each UNSCOPED epic as
+    // `missing-epic-dir` (blocking) — twelve blocking findings about epics the run
+    // was never asked about, which also made a scoped run unable to reach
+    // `consistent` by construction.
+    if (collected.scopedEpic && epicDir !== collected.scopedEpic) continue;
     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) {
+  for (const epic of epics) {
     const stateEpic = stateEpics[epic.key];
 
     if (!stateEpic) {
@@ -554,8 +629,31 @@ export function reconcileArtifacts(targetDir, {
           ?? 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.');
+          // … unless the framework has already ruled the gap accepted. A recorded
+          // gate-exception is a reviewed human decision naming this work item, its
+          // category and its reason; re-raising it as `blocking` on every run fills
+          // the blocking section with rows nobody can act on, and teaches the
+          // reader to skim the one section that must never be skimmed. The honest
+          // fix — re-running eight merged, green stories' suites to manufacture
+          // records that never existed — is explicitly out of scope, which is what
+          // the exception records.
+          //
+          // The gap is still REPORTED, as `info` naming the exception, because this
+          // module's contract is a recorded gap rather than silence. The match is
+          // the one a transition uses (`activeExceptionEntries`, by work-item
+          // scope), so the two can never disagree about what is excused.
+          const excused = activeExceptionEntries(state, { workItemId: subject });
+          if (excused.length > 0) {
+            const exception = excused[excused.length - 1];
+            const date = exception.date ? String(exception.date).slice(0, 10) : null;
+            add('excused-gap', 'info', subject, storyFile.relPath,
+              `state.json marks this story done without an indexed evidence record, and \`${exception.gate}\` is recorded as an accepted gap `
+              + `(${exception.category ?? 'uncategorised'}${date ? `, ${date}` : ''}): ${exception.rationale ?? 'no rationale recorded'}`,
+              date ? `excepted ${date}` : 'excepted');
+          } else {
+            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.');
+          }
         }
       }
     }
@@ -593,13 +691,14 @@ export function reconcileArtifacts(targetDir, {
     available: true,
     plansDir: plansDirRel,
     scopedEpic: collected.scopedEpic,
+    scopeError: null,
     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),
+      epicCount: epics.length,
+      storyCount: epics.reduce((n, e) => n + e.stories.length, 0),
     },
     reason: null,
   };

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
@@ -181,6 +225,29 @@ export function validateState(state, context = {}) {
         }
       });
     }
+    // The story-completion marker. Non-terminal and additive: it records which
+    // work items a session has moved on from, and it is what makes "this story is
+    // finished, its epic is not" a state a reader can check rather than infer. A
+    // malformed entry is an error for the same reason a malformed coverage index
+    // is: a marker that reads as absent makes a finished story's outcome
+    // unattributable again, which is the ambiguity it exists to remove.
+    if (state.storyCompletions !== undefined && !Array.isArray(state.storyCompletions)) {
+      errors.push({ path: 'storyCompletions', message: 'storyCompletions must be an array' });
+    }
+    if (Array.isArray(state.storyCompletions)) {
+      state.storyCompletions.forEach((row, i) => {
+        if (!isPlainObject(row)) {
+          errors.push({ path: `storyCompletions[${i}]`, message: 'story completion must be an object' });
+          return;
+        }
+        if (typeof row.workItemId !== 'string' || row.workItemId.length === 0) {
+          errors.push({ path: `storyCompletions[${i}].workItemId`, message: 'workItemId must be a non-empty string' });
+        }
+        if (typeof row.completedAt !== 'string' || row.completedAt.length === 0) {
+          errors.push({ path: `storyCompletions[${i}].completedAt`, message: 'completedAt must be a timestamp string' });
+        }
+      });
+    }
     // The coverage index (contract v5). It is what keeps the "a done story owns
     // evidence" check answerable once the records themselves have moved to
     // commits and `.cadet/archive/`, so a malformed index is an error: an index
@@ -688,16 +755,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 = [];
@@ -1072,24 +1144,48 @@ export function recordEvidence(state, evidence) {
 }
 
 /**
- * Active gate exceptions keyed by gate, honoring scope and expiry.
+ * Every active exception entry covering `workItemId`, in record order.
  *
  * Reads both homes for an exception: `changeHistory` (v1-v3, where a `type`
  * discriminator picks it out of the log) and `gateExceptions` (v4, a dedicated
- * field where the discriminator would be redundant). Later entries win, so a
- * v4 document that still carries legacy entries behaves as it did before.
+ * field where the discriminator would be redundant).
+ *
+ * `activeExceptions` collapses these to one entry per gate, which is what a
+ * transition needs. A caller that must NAME the exception which excused
+ * something — the reconciler does, for a `done` story with no evidence — needs
+ * the entry itself, and a gate-keyed map has already discarded the ones it did
+ * not keep. Both read this function, so the two can never disagree about what is
+ * excused.
+ *
+ * An entry naming no gate is not active: an exception records that a GATE was
+ * not required, or was satisfied another way, so one that names no gate excuses
+ * nothing.
  */
-export function activeExceptions(state, { workItemId, now = new Date() } = {}) {
+export function activeExceptionEntries(state, { workItemId, now = new Date() } = {}) {
   const candidates = [
     ...(Array.isArray(state?.changeHistory) ? state.changeHistory.filter((e) => e?.type === 'gate-exception') : []),
     ...(Array.isArray(state?.gateExceptions) ? state.gateExceptions : []),
   ];
-  const active = {};
+  const active = [];
   for (const entry of candidates) {
     if (!isPlainObject(entry)) continue;
+    if (!entry.gate) continue;
     if (workItemId && entry.scope && !String(entry.scope).includes(workItemId)) continue;
     if (entry.expiresAt && new Date(entry.expiresAt).getTime() <= now.getTime()) continue;
-    if (entry.gate) active[entry.gate] = entry;
+    active.push(entry);
+  }
+  return active;
+}
+
+/**
+ * Active gate exceptions keyed by gate, honoring scope and expiry — a projection
+ * of {@link activeExceptionEntries}. Later entries win, so a v4 document that
+ * still carries legacy entries behaves as it did before.
+ */
+export function activeExceptions(state, { workItemId, now = new Date() } = {}) {
+  const active = {};
+  for (const entry of activeExceptionEntries(state, { workItemId, now })) {
+    active[entry.gate] = entry;
   }
   return active;
 }
@@ -1527,10 +1623,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;
@@ -1549,23 +1646,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 : {};
@@ -1587,6 +1749,34 @@ export function resetGatesForNewWorkItem(state, { epicId = null, storyId = null,
     activeWorkItem: { epicId, storyId },
   };
 
+  // The story boundary, recorded rather than implied.
+  //
+  // There is no story-level terminal transition — `closed` is the epic's, and it
+  // stays terminal — so a story that finishes while its epic is still open had no
+  // vocabulary at all, and every boundary ended in a judgement call about which
+  // edge was legal. None of them means "this story is finished", so that call had
+  // no correct answer: a session spent a full decision cycle on it and closed
+  // nothing. Moving on from a work item now names the outcome.
+  //
+  // It records what HAPPENED — the session moved on from this item — not a
+  // verdict: `completedAt` is the boundary's timestamp and `evidenceRecords` is
+  // how much the item left behind, so a completion with nothing behind it is
+  // visible rather than implied. One row per work item, replaced rather than
+  // appended if the same item is begun again, and no prose: bounded, like
+  // everything else this version keeps in the document.
+  const outgoingId = state?.activeWorkItem ? workItemIdOf(state) : null;
+  if (outgoingId && outgoingId !== `${epicId}::${storyId}`) {
+    base.storyCompletions = [
+      ...(Array.isArray(state.storyCompletions) ? state.storyCompletions : [])
+        .filter((row) => row?.workItemId !== outgoingId),
+      {
+        workItemId: outgoingId,
+        completedAt: timestamp(at),
+        evidenceRecords: Array.isArray(state.gateEvidence) ? state.gateEvidence.length : 0,
+      },
+    ];
+  }
+
   if (isHistoryExternal(state)) {
     // Fold the cleared records into the coverage index before they go.
     //

package/src/install.mjs

@@ -352,6 +352,13 @@ export async function install(targetDir, opts = {}) {
   console.log('    Reviewer: the cadet-agent-reviewer skill');
   console.log('    Git guard: no hook — approve via .deepcode\\settings.json permissions.ask (mutate-git-log)');
   console.log('    Docs: https://deepcode.vegamo.cn/');
+  console.log('  Hermes:');
+  console.log('    Already active — .agents\\skills\\cadet-agent\\SKILL.md is discovered as a project skill');
+  console.log('    Run `hermes skills trust` once inside the repo to enable project skills');
+  console.log('    Slash commands: /cadet-requirements, /cadet-tdd, /cadet-resume, ...');
+  console.log('    Reviewer: /cadet-agent-reviewer');
+  console.log('    Git guard: no hook — configure command approval policies for commit/push');
+  console.log('    Docs: https://hermes-agent.nousresearch.com/docs/');
   console.log('');
 }