cadet-agent 0.49.0 → 0.54.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.49.0",
+  "version": "0.54.0",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -601,16 +601,26 @@ async function cmdState(opts) {
     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).`
-      + (fromId ? `\n   Previous work item: ${fromId}` : '')
+      + (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,
@@ -1218,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]),
@@ -1387,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,
@@ -1501,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, {
@@ -1509,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/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

@@ -225,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
@@ -1121,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;
 }
@@ -1702,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('');
 }