cadet-agent 0.41.0 → 0.43.0

package/README.md

@@ -184,13 +184,18 @@ Gates are backed by **evidence**, not assertion. Each claimed gate must have a f
 - When Git is unavailable and no `--files` are given, verification blocks (`freshness-unavailable`) rather than recording unscoped evidence.
 - `state validate` rejects a `true` gate whose evidence is missing, stale, expired, superseded, or bound to another work item; evidence records are schema-validated in full (`command`, `result`, `criteriaHash`, and a freshness bound).
 - Evidence must include a UUID, work item, phase, gate, status, command/result, input-tree hash, criteria hash, relevant files, timestamp, and either `expiresAt` or `freshnessPolicy`.
+- **Evidence history does not live in `state.json`.** A v4 document keeps only the active work item's records inline; a closed work item's evidence is written into the commit that closes it, as `Cadet-*` trailers, and archived to `.cadet/archive/`. `evidenceCoverage` indexes what left, so the "a done story owns evidence" check still works offline. Cadet still never commits: `state seal` prepares a message file and you commit with `git commit -F`.
 - Command output counts against the output budget; a configured cost budget cannot be satisfied by unmeasurable cost (the run is blocked, `budget-blocked`).
 - State and run ledgers are written atomically, so an interrupted write cannot truncate a record; persisted artifacts are redacted before hashing or writing.
 - Empty freshness coverage is an explicit policy decision: set `allowEmptyFreshness: true` in `.cadet/harness.json` only when unscoped evidence is acceptable.
 
 ```bash
-cadet-agent state validate                       # validate state against the schema
-cadet-agent state migrate                        # atomically upgrade v1 → v2 (no writes if it fails)
+cadet-agent state validate                       # validate state against the schema (read-only)
+cadet-agent state validate --verify-sealed       # also read evidence out of commit trailers
+cadet-agent state migrate                        # atomically upgrade v1 → the current version
+cadet-agent state migrate --to 4                 # archive closed work items' evidence; build the index
+cadet-agent state compact --keep active          # routine housekeeping on a v4 state
+cadet-agent state seal                           # write the active work item's evidence as commit trailers
 cadet-agent state transition --to review         # enforce the matrix + evidence
 cadet-agent harness verify --gate testsPassed --files src/a.cs   # bounded, classified loop
 cadet-agent harness report                       # budget consumption and failures (no secrets)

package/package.json

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

package/src/cli.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { install, sync } from './install.mjs';
@@ -11,6 +11,8 @@ import {
   createEvidence, newId, computeInputTreeHash, hashCriteria,
   collectDeclaredTestNames, reconcileTestNames,
   resolveCommand, describeCommand, describeAllCommands, checkUnattendedRequirements, COMMANDS,
+  STATE_VERSION, sealedEvidence, recordEvidence, appendEvidence, sealWorkItem, toStateV4,
+  isHistoryExternal, HISTORY_ENTRIES_KEPT,
 } from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -38,8 +40,12 @@ function showHelp() {
     npx cadet-agent@latest sync     Update framework, preserving local policies/plans
     npx cadet-agent@latest sync --target <dir>   Sync a specific directory
 
-    cadet-agent state validate      Validate .cadet/state.json against the v2 schema
-    cadet-agent state migrate       Atomically migrate v1 state to v2 (backup on write)
+    cadet-agent state validate      Validate .cadet/state.json against the schema
+    cadet-agent state validate --verify-sealed   Also read sealed evidence from commit trailers
+    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 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
 
@@ -70,6 +76,9 @@ function showHelp() {
     --inventory    Newline-separated test names, when no report is available (harness matrix-check)
     --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
     --older-than-ms  Age bound, in ms, for records cleanup may delete (harness cleanup; required)
+    --keep         always|active|<work-item ids> for what stays in state.json (state compact; required)
+    --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)
     --yes, -y      Never prompt; keep existing files (non-interactive installs)
     --help, -h    Show this help (valid at any depth; never writes)
@@ -155,6 +164,14 @@ function parseArgs(argv) {
       case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
       case '--older-than-ms': opts.olderThanMs = Number(value(a)); break;
+      // state compact: the bound on what may leave state.json. Content-bearing
+      // rather than a confirmation flag, so an unattended agent must state which
+      // work items it is keeping inline.
+      case '--keep': opts.keep = value(a); break;
+      // state seal: where the prepared commit message goes.
+      case '--commit-msg': opts.commitMsgPath = value(a); break;
+      // state validate: read commit trailers too, not just the live document.
+      case '--verify-sealed': opts.verifySealed = true; break;
       case '--agents-md': opts.agentsMd = value(a); break;
       case '--yes': case '-y': opts.yes = true; break;
       default: opts.rest.push(a);
@@ -203,6 +220,101 @@ function fail(opts, message, code = json => json.exitCode || 1, json = {}) {
   process.exit(exitCode);
 }
 
+// ── evidence archive (contract v5) ──────────────────────────────────────────
+
+/**
+ * `.cadet/archive/evidence/` — the append-only home for evidence that has left
+ * `state.json`.
+ *
+ * A directory of per-work-item JSONL files rather than one file, because a single
+ * log for a whole repository would be rewritten on every append by anything that
+ * wanted to dedupe it, and an audit trail should not be rewritten. One file per
+ * work item also means the common read — "what evidence did this story have?" —
+ * touches one small file instead of parsing everything.
+ */
+function evidenceArchiveDir(targetDir) {
+  return join(targetDir, '.cadet', 'archive', 'evidence');
+}
+
+/** A filesystem-safe file name for a work item id, which contains `::`. */
+function archiveFileName(workItemId) {
+  const safe = String(workItemId).replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 120);
+  return `${safe || 'unscoped'}.jsonl`;
+}
+
+/** Every evidenceId already archived, so a repeated compaction is idempotent. */
+function readArchivedIds(targetDir) {
+  const dir = evidenceArchiveDir(targetDir);
+  const ids = new Set();
+  if (!existsSync(dir)) return ids;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.jsonl')) continue;
+    let text;
+    try { text = readFileSync(join(dir, file), 'utf-8'); } catch { continue; }
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const record = JSON.parse(line);
+        if (record?.evidenceId) ids.add(record.evidenceId);
+      } catch {
+        // A malformed line is skipped rather than fatal: this is an append-only
+        // log, and refusing to read the rest of it because of one bad line would
+        // make the archive less durable than the file it replaced.
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * Append records to the archive, one JSON object per line, grouped by work item.
+ *
+ * Records whose `evidenceId` is already archived are skipped, so re-running a
+ * compaction after a partial failure cannot duplicate history — which matters
+ * because this log is the only remaining copy of the records it holds.
+ */
+function appendEvidenceArchive(targetDir, records) {
+  const known = readArchivedIds(targetDir);
+  const byFile = new Map();
+  let skipped = 0;
+  for (const record of records) {
+    if (!record || typeof record !== 'object') continue;
+    if (record.evidenceId && known.has(record.evidenceId)) { skipped += 1; continue; }
+    const name = archiveFileName(record.workItemId || 'unscoped');
+    if (!byFile.has(name)) byFile.set(name, []);
+    byFile.get(name).push(JSON.stringify(record));
+  }
+  if (byFile.size === 0) return { files: [], appended: 0, skipped };
+  const dir = evidenceArchiveDir(targetDir);
+  mkdirSync(dir, { recursive: true });
+  const files = [];
+  let appended = 0;
+  for (const [name, lines] of byFile) {
+    const path = join(dir, name);
+    writeFileSync(path, `${lines.join('\n')}\n`, { flag: 'a', encoding: 'utf-8' });
+    files.push(path);
+    appended += lines.length;
+  }
+  return { files, appended, skipped };
+}
+
+/**
+ * Append change-log entries that no longer fit inline to `.cadet/archive/history.jsonl`.
+ *
+ * `changeHistory` is not retired — eight skills write artifact paths into it and
+ * `Resume` reads its tail — so compaction bounds it rather than dropping it. The
+ * overflow goes here in full, one entry per line, so bounding the document never
+ * destroys the audit trail it used to hold.
+ */
+function appendHistoryArchive(targetDir, entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return { path: null, appended: 0 };
+  const dir = join(targetDir, '.cadet', 'archive');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, 'history.jsonl');
+  writeFileSync(path, `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`, { flag: 'a', encoding: 'utf-8' });
+  return { path, appended: entries.length };
+}
+
 // ── state commands ──────────────────────────────────────────────────────────
 
 async function cmdState(opts) {
@@ -232,8 +344,64 @@ async function cmdState(opts) {
     const result = validateState(state, { rootDir: opts.targetDir, strictClosure: policy.strictClosure });
     const role = detectRepoRole(opts.targetDir);
     const repoRoleDetail = describeRepoRole(role);
+
+    // `--verify-sealed` consults git for evidence sealed into commit trailers,
+    // which is where a closed work item's records live from v4 on.
+    //
+    // It is additive by construction: it can only clear an error that a real
+    // sealed record backs, never raise a new one. That direction is deliberate —
+    // a check that could fail because git was unavailable would make the
+    // read-only validation command depend on the environment it is auditing.
+    let sealed = null;
+    if (opts.verifySealed) {
+      const probe = sealedEvidence(opts.targetDir, { workItemId: workItemIdOf(state) });
+      if (!probe.available) {
+        // Never a silent pass: "not verified" and "verified clean" must not look
+        // the same, matching how a missing rootDir is reported for freshness.
+        result.warnings.push({
+          path: 'sealedEvidence',
+          message: `sealed evidence was not verified: ${probe.reason}. Live evidence only; a gate satisfied by a sealed record will be reported as unbacked.`,
+        });
+      } else {
+        const latestFor = (gate) => probe.records
+          .filter((r) => r.gate === gate && (r.status === 'passed' || r.status === 'manual-confirmation') && !r.partial)
+          .reduce((a, b) => {
+            if (!a) return b;
+            return (Date.parse(a.createdAt ?? '') || 0) >= (Date.parse(b.createdAt ?? '') || 0) ? a : b;
+          }, null);
+        const resolvedBySeal = [];
+        const unresolved = [];
+        for (const err of result.errors) {
+          const match = /^gates\.([A-Za-z]+)$/.exec(String(err.path));
+          const record = match ? latestFor(match[1]) : null;
+          if (record) {
+            resolvedBySeal.push({ gate: match[1], sealedCommit: record.sealedCommit });
+            continue;
+          }
+          unresolved.push(err);
+        }
+        result.errors = unresolved;
+        result.valid = unresolved.length === 0;
+        sealed = {
+          available: true,
+          records: probe.records.length,
+          gates: [...new Set(probe.records.map((r) => r.gate))].filter(Boolean).sort(),
+          resolvedBySeal,
+          diagnostics: probe.diagnostics,
+        };
+      }
+    }
+
     if (opts.format === 'json') {
-      emit(opts, '', { ok: result.valid, valid: result.valid, errors: result.errors, warnings: result.warnings, repoRole: role.role, repoRoleDetail });
+      emit(opts, '', {
+        ok: result.valid,
+        valid: result.valid,
+        errors: result.errors,
+        warnings: result.warnings,
+        repoRole: role.role,
+        repoRoleDetail,
+        ...(sealed ? { sealed } : {}),
+      });
     } else {
       if (result.valid) console.log(`✅ state.json is valid (v${state.version}).`);
       else {
@@ -241,6 +409,12 @@ async function cmdState(opts) {
         for (const e of result.errors) console.error(`   ${e.path}: ${e.message}`);
       }
       for (const w of result.warnings) console.log(`   ⚠️  ${w.path}: ${w.message}`);
+      if (sealed) {
+        if (sealed.available) {
+          console.log(`   Sealed evidence: ${sealed.records} record(s) in commit trailers; gates: ${sealed.gates.join(', ') || '(none)'}`);
+          for (const r of sealed.resolvedBySeal) console.log(`   ✅ ${r.gate} backed by sealed record in ${String(r.sealedCommit).slice(0, 8)}`);
+        }
+      }
       console.log(`   Repo role: ${role.role} — ${repoRoleDetail}`);
     }
     if (!result.valid) process.exit(1);
@@ -248,14 +422,122 @@ async function cmdState(opts) {
   }
 
   if (sub === 'migrate') {
-    const result = migrateStateFile(statePath, { backup: true });
+    // The archive is written through `beforeWrite`, which runs after the migrated
+    // document validates but before the backup and the rename — so a migration
+    // that would fail writes nothing at all, while a crash after the archive
+    // leaves records in both places rather than neither.
+    const archivePaths = [];
+    let historyArchived = 0;
+    const result = migrateStateFile(statePath, {
+      backup: true,
+      to: opts.to ?? null,
+      keep: opts.keep ?? 'active',
+      beforeWrite: ({ archived, archivedHistory }) => {
+        const written = appendEvidenceArchive(opts.targetDir, archived);
+        archivePaths.push(...written.files);
+        const history = appendHistoryArchive(opts.targetDir, archivedHistory);
+        if (history.path) archivePaths.push(history.path);
+        historyArchived = history.appended;
+      },
+    });
+    const detail = {
+      ok: true,
+      migrated: result.migrated,
+      statePath: result.statePath,
+      version: STATE_VERSION,
+      archived: result.archived.length,
+      archivedHistory: historyArchived,
+      promotedExceptions: result.promoted,
+      droppedHistoryEntries: result.droppedHistory,
+      archivePaths,
+      backupPath: result.backupPath ?? null,
+    };
     if (opts.format === 'json') {
-      emit(opts, '', { ok: true, migrated: result.migrated, statePath: result.statePath });
+      emit(opts, '', detail);
     } else if (result.migrated) {
-      console.log(`✅ Migrated ${statePath} to v2 (backup: ${statePath}.v1.bak).`);
+      console.log(`✅ Migrated ${statePath} to v${STATE_VERSION} (backup: ${result.backupPath}).`);
+      if (result.archived.length) {
+        console.log(`   Archived ${result.archived.length} evidence record(s) to ${evidenceArchiveDir(opts.targetDir)}`);
+      }
+      if (historyArchived) console.log(`   Archived ${historyArchived} change-log entr(ies) to .cadet/archive/history.jsonl (the last ${HISTORY_ENTRIES_KEPT} stay inline).`);
+      if (result.promoted) console.log(`   Promoted ${result.promoted} gate exception(s) out of changeHistory.`);
     } else {
-      console.log('✅ state.json is already v2 — nothing to migrate.');
+      console.log(`✅ state.json is already v${STATE_VERSION} — nothing to migrate.`);
+    }
+    return;
+  }
+
+  if (sub === 'compact') {
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) fail(opts, 'No .cadet/state.json found.', () => 2);
+    // Compaction is the v4 shape, so a v2/v3 document needs the explicit version
+    // migration first. Doing it implicitly here would hide a version change
+    // inside what a caller thinks is housekeeping.
+    if (!isHistoryExternal(state)) {
+      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 written = appendEvidenceArchive(opts.targetDir, archived);
+    const history = appendHistoryArchive(opts.targetDir, archivedHistory);
+    const changed = archived.length > 0 || archivedHistory.length > 0;
+    if (changed) writeState(opts.targetDir, next);
+    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')}`
+        : '✅ Nothing to compact: every evidence record and change-log entry is already kept inline.',
+      {
+        ok: true,
+        archived: archived.length,
+        archivedHistory: history.appended,
+        kept: next.gateEvidence.length,
+        appended: written.appended,
+        skipped: written.skipped,
+        archivePaths: [...written.files, ...(history.path ? [history.path] : [])],
+        coverageRows: Object.keys(next.evidenceCoverage || {}).length,
+      },
+    );
+    return;
+  }
+
+  if (sub === 'seal') {
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) fail(opts, 'No .cadet/state.json found.', () => 2);
+    const policy = loadPolicy(opts.targetDir);
+    const { workItemId, records, lines, partial } = sealWorkItem(state, {
+      workItemId: opts.workItemId || null,
+      maxBytes: policy.output?.maxInlineBytes,
+    });
+    if (records.length === 0) {
+      fail(opts, `no inline evidence to seal for ${workItemId || '(no active work item)'}. Evidence for a closed work item lives in its commit and .cadet/archive/.`, () => 1, { ok: false, code: 'nothing-to-seal', workItemId });
+    }
+    // The message file is what makes this compatible with C5: Cadet prepares the
+    // message, and the commit is still the user's action.
+    const messagePath = opts.commitMsgPath || join(opts.targetDir, '.cadet', 'seal.commit-msg');
+    const header = [
+      `chore(gates): seal evidence for ${workItemId}`,
+      '',
+      'Evidence for this work item, written here so it travels with the code.',
+      'Edit the subject line to describe the change; keep the trailer block intact —',
+      'the records are read back out of it, and altering one changes the commit id.',
+      '',
+    ].join('\n');
+    writeFileSync(messagePath, `${header}${lines.join('\n')}`, 'utf-8');
+    const archived = appendEvidenceArchive(opts.targetDir, records);
+    const { state: next } = toStateV4(state, { keep: opts.keep ?? 'active' });
+    writeState(opts.targetDir, next);
+    emit(
+      opts,
+      [
+        `✅ Prepared ${records.length} evidence record(s) for commit.`,
+        `   Message:  ${messagePath}`,
+        `   Commit:   git commit -F "${messagePath}"`,
+        archived.appended ? `   Archived: ${archived.appended} record(s) to ${evidenceArchiveDir(opts.targetDir)}` : '   Archive:  already up to date',
+        partial.length ? `   ⚠️  ${partial.length} record(s) exceeded the trailer bound and were marked partial (they cannot satisfy a gate).` : null,
+      ].filter(Boolean).join('\n'),
+      { ok: true, workItemId, records: records.length, messagePath, archived: archived.appended, partial },
+    );
     return;
   }
 
@@ -303,7 +585,18 @@ async function cmdState(opts) {
     return;
   }
 
-  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|transition.`);
+  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|compact|seal|transition.`);
+}
+
+/**
+ * Parse the `--keep` bound for `state compact`: `always`, `active`, or a
+ * comma-separated list of work-item ids. Returns what `toStateV4` expects.
+ */
+function parseKeepBound(raw) {
+  const text = String(raw ?? '').trim();
+  if (text === 'always') return 'always';
+  if (text === 'active' || text === '') return 'active';
+  return text.split(',').map((s) => s.trim()).filter(Boolean);
 }
 
 // ── harness commands ────────────────────────────────────────────────────────
@@ -453,19 +746,15 @@ async function cmdHarness(opts) {
     ledger.finalize({ status: 'ok' });
     const ledgerPath = ledger.persist();
 
-    const next = { ...state };
+    // Supersede-and-append plus the coverage index live in `recordEvidence`, so
+    // this path and `harness verify` cannot disagree about either. Before that
+    // helper the two commands built the array separately, which is how an index
+    // would have ended up maintained by one of them and not the other.
     const prior = Array.isArray(state.gateEvidence) ? state.gateEvidence : [];
-    next.gateEvidence = [
-      // Immutability: supersede prior passing evidence, never delete it.
-      ...prior.map((e) => (e.gate === gate && (e.status === 'passed' || e.status === 'manual-confirmation')
-        ? { ...e, status: 'superseded', supersededBy: evidence.evidenceId }
-        : e)),
-      evidence,
-    ];
-    next.gates = { ...(state.gates || {}), [gate]: true };
+    const superseded = prior.filter((e) => e.gate === gate && (e.status === 'passed' || e.status === 'manual-confirmation')).length;
+    const next = recordEvidence(state, evidence);
     writeState(opts.targetDir, next);
 
-    const superseded = prior.filter((e) => e.gate === gate && (e.status === 'passed' || e.status === 'manual-confirmation')).length;
     emit(
       opts,
       `✅ Recorded manual confirmation for gate "${gate}". Evidence: ${evidence.evidenceId}\n   Ledger: ${ledgerPath}`,
@@ -610,18 +899,20 @@ async function cmdHarness(opts) {
     // only when it is evidence-backed; a failing one records the attempt.
     let stateUpdated = false;
     if (state) {
-      const next = { ...state };
-      next.gateEvidence = [...(Array.isArray(state.gateEvidence) ? state.gateEvidence : []), ...result.attempts.map((a) => a.evidence)];
-      if (Array.isArray(next.gateEvidence)) {
-        // Mark prior evidence for this gate as superseded by the new record.
-        const newest = result.finalEvidence?.evidenceId;
-        next.gateEvidence = next.gateEvidence.map((e) =>
-          e.gate === gate && e.evidenceId !== newest && e.status === 'passed' && result.ok
-            ? { ...e, status: 'superseded', supersededBy: newest }
-            : e);
-      }
-      if (result.ok) {
-        next.gates = { ...(state.gates || {}), [gate]: true };
+      // The failed attempts from this run are appended first, then the passing
+      // record supersedes prior passing evidence for the gate. Red-before-green is
+      // why the attempts are not filtered out on success: the red record is the
+      // thing that made the green one permissible, and dropping it would leave a
+      // green gate whose justification no longer exists.
+      const attempts = result.attempts.map((a) => a.evidence);
+      let next = state;
+      if (result.ok && result.finalEvidence) {
+        for (const ev of attempts) {
+          if (ev?.evidenceId !== result.finalEvidence.evidenceId) next = appendEvidence(next, ev);
+        }
+        next = recordEvidence(next, result.finalEvidence);
+      } else {
+        for (const ev of attempts) next = appendEvidence(next, ev);
       }
       writeState(opts.targetDir, next);
       stateUpdated = true;
@@ -799,15 +1090,7 @@ async function cmdHarness(opts) {
     const ledgerPath = ledger.persist();
 
     if (exists) {
-      const next = { ...state };
-      const priorEv = Array.isArray(state.gateEvidence) ? state.gateEvidence : [];
-      next.gateEvidence = [
-        ...priorEv.map((e) => (e.gate === 'acceptanceCriteriaValidated' && (e.status === 'passed' || e.status === 'manual-confirmation')
-          ? { ...e, status: 'superseded', supersededBy: evidence.evidenceId }
-          : e)),
-        evidence,
-      ];
-      next.gates = { ...(state.gates || {}), acceptanceCriteriaValidated: true };
+      const next = recordEvidence(state, evidence);
       writeState(opts.targetDir, next);
     }
 

package/src/harness/commands.mjs

@@ -37,12 +37,14 @@ export const COMMANDS = {
 
   'state validate': {
     mutates: false,
-    summary: 'Validate .cadet/state.json against the schema.',
+    summary: 'Validate .cadet/state.json against the current schema.',
+    // `--verify-sealed` reads commit trailers. It is a read: verifying a seal
+    // must never repair one, so the flag cannot write.
   },
   'state migrate': {
     mutates: true,
-    summary: 'Atomically migrate v1 state to the current version.',
-    writes: ['.cadet/state.json', '.cadet/state.json.v1.bak'],
+    summary: 'Atomically migrate state to the current version (backup on write).',
+    writes: ['.cadet/state.json', '.cadet/state.json.v*.bak', '.cadet/archive/**'],
     unattended: false,
     // A failed migration must leave the tree exactly as it found it: no backup,
     // no partial write. The backup is an artifact of a *successful* migration,
@@ -52,6 +54,24 @@ export const COMMANDS = {
     // before validation — verified by reintroducing the original ordering.
     atomicFailure: true,
   },
+  'state seal': {
+    mutates: true,
+    summary: 'Write a work item\'s evidence as commit trailers, for `git commit -F`.',
+    // Cadet does not commit (contract C5). Sealing prepares a message file and
+    // archives the records; the commit itself stays a user action.
+    writes: ['.cadet/archive/**', '*.commit-msg'],
+    unattended: true,
+  },
+  'state compact': {
+    mutates: true,
+    summary: 'Move closed work items\' evidence out of state.json into .cadet/archive/.',
+    writes: ['.cadet/state.json', '.cadet/archive/**'],
+    // Irreversible in the sense that matters: records leave the document that
+    // every gate check reads. An unattended agent must say what to keep, so the
+    // bound is content-bearing rather than a bare confirmation.
+    unattended: false,
+    requiresForUnattended: ['--keep'],
+  },
   'state transition': {
     mutates: true,
     summary: 'Enforce the transition matrix and evidence; applies the transition.',
@@ -184,12 +204,17 @@ export function checkUnattendedRequirements(key, opts) {
     if (flag === '--older-than-ms') {
       return !Number.isFinite(opts.olderThanMs);
     }
+    if (flag === '--keep') {
+      // `always`, `active`, or a comma-separated work-item list. An empty value
+      // is not a bound, so it must fail the same way a missing flag does.
+      return !(typeof opts.keep === 'string' && opts.keep.trim() !== '');
+    }
     return true;
   });
   if (missing.length === 0) return { ok: true };
   return {
     ok: false,
     missing,
-    reason: `"${key}" deletes records irreversibly, so it requires ${missing.join(', ')} when run unattended.`,
+    reason: `"${key}" removes records that gate checks read, so it requires ${missing.join(', ')} when run unattended.`,
   };
 }