cadet-agent 0.20.2 → 0.24.0

package/README.md

@@ -7,8 +7,13 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
 ## Repository Layout
 - `.cadet/agent/core/` contains the shared Cadet-Agent framework documents.
   - `cadet-agent.md` is the thin global directive: identity, non-negotiable rules, workflow routing, hard-gate protocol, and skill dispatch.
-  - `skills/` contains scoped workflow-phase skills (Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview).
+  - `Harness.md` is the canonical harness contract: budgets, evidence-backed gates, retries, context tiers, tool routing, privacy, and escalation.
+  - `harness.schema.json` and `state.schema.json` are the machine-readable schemas for harness records and session state.
+  - `skills/` contains scoped workflow-phase skills (Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer).
   - `templates/` contains runtime templates for planning artifacts.
+- `.cadet/harness.json` holds repository-local budget/policy overrides (preserved by sync).
+- `.cadet/runs/` holds sanitized run ledgers (preserved by sync; no secrets or raw prompts by default).
+- `src/harness/` contains the dependency-free harness implementation (policy, budget, state, verification, context, routing, redaction, ledger, archive, hook).
 - `.cadet/agent/docs/` contains setup guides for each supported IDE.
 - `.github/agents/` contains the Copilot custom agent definitions (Cadet Agent + Cadet Agent Reviewer).
 - `.github/prompts/` contains Copilot slash-command skill prompts (`/cadet-review`, `/cadet-tdd`, etc.).
@@ -21,7 +26,7 @@ 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 four IDEs. The same 7 skills + resume + reviewer are available in each:
+Cadet-Agent provides full workflow parity across four IDEs. The same 9 skills + reviewer are available in each:
 
 | Feature | GitHub Copilot | Cursor | Continue | Claude Code |
 |---|---|---|---|---|
@@ -35,6 +40,7 @@ Cadet-Agent provides full workflow parity across four IDEs. The same 7 skills +
 | Debugging | ✅ | ✅ | ✅ | ✅ |
 | Code Review | ✅ | ✅ | ✅ | ✅ |
 | Resume | ✅ | ✅ | ✅ | ✅ |
+| MCP Setup | ✅ | ✅ | ✅ | ✅ |
 | Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` |
 | Git guard | PreToolUse hook | Manual | Manual | Manual |
 
@@ -58,7 +64,7 @@ npx cadet-agent@latest init --target ./my-unity-project
 npx cadet-agent@latest sync
 ```
 
-When a new release is available, `sync` downloads the updated framework and replaces managed files (`.cadet/agent/core/`, IDE integration shims, agent definitions). Your local policies (`.cadet/agent/policies/`) and project plans (`.cadet/agent/project-plans/`) are automatically preserved. After syncing, start a fresh chat for the changes to take effect.
+When a new release is available, `sync` downloads the updated framework and replaces managed files (`.cadet/agent/core/`, IDE integration shims, agent definitions). Your local policies (`.cadet/agent/policies/`), project plans (`.cadet/agent/project-plans/`), harness overrides (`.cadet/harness.json`), and run ledgers (`.cadet/runs/`) are automatically preserved. After syncing, start a fresh chat for the changes to take effect.
 
 To sync a specific directory:
 
@@ -128,7 +134,7 @@ flowchart TD
 
 ### Resuming a Session
 
-Use the `/cadet-resume` slash command to pick up where you left off. It reads `.cadet/state.json` and reports the current phase, epic/story progress, and outstanding gates — then dispatches the right skill for the next step. If no state file exists, it initializes a fresh session from `context-resolution`.
+Use the `/cadet-resume` slash command to pick up where you left off. It reads `.cadet/state.json` and reports the current phase, epic/story progress, and outstanding gates — then dispatches the right skill for the next step. It also checks the current branch and working tree, so leftover changes from a previous task are resolved (commit, stash, push, or move to a new branch) before a new task begins. If no state file exists, it initializes a fresh session from `context-resolution`.
 
 ### Phase Gating
 
@@ -140,6 +146,36 @@ Hard gates are enforced at every phase transition. The agent reads `.cadet/state
 | review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated` |
 | validation → closed | `designArtifactSyncConfirmed` |
 
+### Harness
+
+Gates are backed by **evidence**, not assertion. Each claimed gate must have a fresh, non-superseded evidence record bound to the current work item, input tree hash, and acceptance criteria. The harness also bounds context, tokens, tool calls, retries, wall-clock time, cost, and archive sizes — and those bounds are enforced, not advisory.
+
+- Rules: `.cadet/agent/core/Harness.md`. Data contract: `docs/core/HarnessContract.md`.
+- Overrides: `.cadet/harness.json` (preserved by sync; conservative defaults in `src/harness/policy.mjs`).
+- Ledgers: `.cadet/runs/<runId>.json` (sanitized; artifacts are redacted before they are written; no secrets or raw prompts by default).
+- Transitions recompute the input tree hash from the evidence's relevant files, so editing a relevant file invalidates the evidence.
+- `harness verify` binds evidence to `--files` (or the working tree's changed files), and a `testsPassed` green result requires a prior red record.
+- 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`.
+- 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
+cadet-agent state transition --to review         # enforce the matrix + evidence
+cadet-agent harness verify --gate testsPassed --files src/a.cs   # bounded, classified loop
+cadet-agent harness report                       # budget consumption and failures (no secrets)
+cadet-agent harness cleanup                      # apply the retention policy
+cadet-agent harness capabilities                 # available CLI/Unity/MCP/hook/token/cost telemetry
+```
+
+Every command supports `--format human|json` and exits nonzero for invalid state, failed verification, budget exhaustion, stale evidence, or safety rejection.
+
+See `docs/guidance/HarnessTroubleshooting.md` for stale evidence, budget exhaustion, unavailable Unity CLI, and live MCP connection failures.
+
 ## Examples
 
 ### GitHub Copilot
@@ -199,7 +235,7 @@ If a specific game repository needs local conventions, add a policy file under `
 
 ## Package Output
 Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
-- `.cadet/agent/core/`
+- `.cadet/agent/core/` (including `Harness.md`, `harness.schema.json`, and `state.schema.json`)
 - `.cadet/agent/core/skills/`
 - `.cadet/agent/core/templates/`
 - `.github/agents/cadet.agent.md`
@@ -207,8 +243,12 @@ Running `./package-agent.ps1` produces `cadet-agent.zip` with this layout:
 - `.github/prompts/cadet-*.prompt.md`
 - `.github/hooks/`
 - `.cursor/rules/cadet-agent.md`
+- `.cursor/rules/cadet-agent-reviewer.md`
 - `.continue/rules/cadet-agent.md`
-- `.claude/skills/cadet-agent.md`
+- `.continue/rules/cadet-agent-reviewer.md`
+- `.continue/config.yaml`
+- `.claude/skills/cadet-agent/SKILL.md`
+- `.claude/skills/cadet-*/SKILL.md`
 
 ## Notes
 - `.cadet/agent/core/FrameworkManifest.json` defines the managed and preserved paths for packaged installs.

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "cadet-agent",
-  "version": "0.20.2",
-  "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"
-  },
-  "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.24.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"
+  },
+  "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

@@ -2,6 +2,11 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { install, sync } from './install.mjs';
+import {
+  validateState, migrateStateFile, readState, writeState, evaluateTransition, applyTransition,
+  workItemIdOf, loadPolicy, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
+  runVerificationLoop, commandForGate, detectCapabilities, runsDir, gitChangedFiles, PolicyError, StateError,
+} from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -28,51 +33,386 @@ 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 transition --to <phase>   Enforce the transition matrix + evidence
+
+    cadet-agent harness record      Append a sanitized span/evidence/decision event
+    cadet-agent harness verify      Run a bounded, classified verification loop
+    cadet-agent harness report      Summarize budget consumption and failures
+    cadet-agent harness cleanup     Apply the retention policy to .cadet/runs/
+    cadet-agent harness capabilities  Report available CLI/Unity/MCP/hook/token/cost telemetry
+
   Options:
     --target, -t  Target directory (default: current working directory)
     --source       Release API URL override (for forked deployments)
+    --format       human|json (default: human)
+    --to           Target phase (state transition)
+    --gate         Gate name (harness verify)
+    --command      Command override (harness verify)
+    --files        Comma-separated relevant files to bind evidence to (harness verify)
     --help, -h    Show this help
     --version, -v Show version number
 `);
 }
 
-export async function run(argv) {
-  const command = argv[2];
+function parseArgs(argv) {
+  const opts = { format: 'human', targetDir: process.cwd(), sourceUrl: null, rest: [] };
+  // argv[2] is the top-level command (`state`/`harness`/`init`/...); argv[3] begins
+  // the subcommand and its options.
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--target': case '-t': opts.targetDir = argv[++i]; break;
+      case '--source': opts.sourceUrl = argv[++i]; break;
+      case '--format': opts.format = argv[++i] || 'human'; break;
+      case '--to': opts.to = argv[++i]; break;
+      case '--gate': opts.gate = argv[++i]; break;
+      case '--command': opts.command = argv[++i]; break;
+      case '--work-item': opts.workItemId = argv[++i]; break;
+      case '--phase': opts.phase = argv[++i]; break;
+      case '--run': opts.runId = argv[++i]; break;
+      case '--type': opts.type = argv[++i]; break;
+      case '--reason': opts.reason = argv[++i]; break;
+      case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
+      case '--files': opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
+      case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
+      default: opts.rest.push(a);
+    }
+  }
+  return opts;
+}
+
+function emit(opts, human, json) {
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(json, null, 2));
+  } else {
+    console.log(human);
+  }
+}
+
+function fail(opts, message, code = json => json.exitCode || 1, json = {}) {
+  const exitCode = code(json);
+  if (opts.format === 'json') {
+    console.error(JSON.stringify({ ok: false, error: message, ...json }, null, 2));
+  } else {
+    console.error(`\n❌ ${message}`);
+  }
+  process.exit(exitCode);
+}
+
+// ── state commands ──────────────────────────────────────────────────────────
+
+async function cmdState(opts) {
+  const sub = opts.rest[0];
+  const statePath = join(opts.targetDir, '.cadet', 'state.json');
+
+  if (sub === 'validate') {
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) {
+      emit(opts, 'No .cadet/state.json found (nothing to validate).', { ok: true, valid: true, exists: false });
+      return;
+    }
+    // Pass rootDir so stale/foreign evidence is caught at validation time.
+    const result = validateState(state, { rootDir: opts.targetDir });
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: result.valid, valid: result.valid, errors: result.errors, warnings: result.warnings });
+    } else {
+      if (result.valid) console.log(`✅ state.json is valid (v${state.version}).`);
+      else {
+        console.error('❌ state.json is invalid:');
+        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 (!result.valid) process.exit(1);
+    return;
+  }
+
+  if (sub === 'migrate') {
+    const result = migrateStateFile(statePath, { backup: true });
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, migrated: result.migrated, statePath: result.statePath });
+    } else if (result.migrated) {
+      console.log(`✅ Migrated ${statePath} to v2 (backup: ${statePath}.v1.bak).`);
+    } else {
+      console.log('✅ state.json is already v2 — nothing to migrate.');
+    }
+    return;
+  }
+
+  if (sub === 'transition') {
+    if (!opts.to) fail(opts, 'state transition requires --to <phase>');
+    const { exists, state } = readState(opts.targetDir);
+    if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before transitioning.', () => 2);
+    // Freshness is enforced against the current working tree: evaluateTransition
+    // recomputes each gate's input-tree hash from the evidence's relevant files.
+    const evaluation = evaluateTransition(state, opts.to, { rootDir: opts.targetDir });
+    if (!evaluation.allowed) {
+      const detail = {
+        ok: false,
+        allowed: false,
+        missingGates: evaluation.missingGates,
+        staleEvidence: evaluation.staleEvidence,
+        errors: evaluation.errors,
+      };
+      const lines = ['❌ Transition rejected:'];
+      for (const e of evaluation.errors) lines.push(`   ${e}`);
+      if (evaluation.missingGates.length) lines.push(`   missing gates/evidence: ${evaluation.missingGates.join(', ')}`);
+      for (const s of evaluation.staleEvidence) lines.push(`   stale: ${s.gate} — ${s.reason || (s.reasons || []).join('; ')}`);
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(lines.join('\n'));
+      process.exit(1);
+    }
+    const next = applyTransition(state, opts.to, { rootDir: opts.targetDir });
+    writeState(opts.targetDir, next);
+    emit(opts, `✅ Transitioned to ${opts.to}.`, { ok: true, allowed: true, to: opts.to });
+    return;
+  }
+
+  fail(opts, `Unknown state subcommand: ${sub || '(none)'}. Use validate|migrate|transition.`);
+}
+
+// ── harness commands ────────────────────────────────────────────────────────
 
-  // Parse --target <dir> or -t <dir>
-  let targetDir = process.cwd();
-  let sourceUrl = null;
-  const targetIdx = argv.indexOf('--target');
-  const tIdx = argv.indexOf('-t');
-  const sourceIdx = argv.indexOf('--source');
-  if (targetIdx !== -1 && argv[targetIdx + 1]) {
-    targetDir = argv[targetIdx + 1];
-  } else if (tIdx !== -1 && argv[tIdx + 1]) {
-    targetDir = argv[tIdx + 1];
+async function cmdHarness(opts) {
+  const sub = opts.rest[0];
+  const policy = loadPolicy(opts.targetDir);
+
+  if (sub === 'capabilities') {
+    const caps = detectCapabilities({ targetDir: opts.targetDir });
+    if (opts.format === 'json') emit(opts, '', { ok: true, capabilities: caps });
+    else {
+      console.log('Cadet-Agent capability report');
+      console.log(`  CLI:            ${caps.cli ? 'available' : 'unavailable'}`);
+      console.log(`  Unity CLI:      ${caps.unityCli.available ? `available (${caps.unityCli.version || 'version unknown'})` : 'unavailable — compile/analyzer gates fall back to manual confirmation'}`);
+      console.log(`  MCP:            ${caps.mcp.available ? 'configured' : 'unavailable — live inspection not available'}`);
+      console.log(`  Copilot hook:   ${caps.hook.copilot ? 'installed' : 'not installed'}`);
+      console.log(`  Token telemetry:${caps.tokenTelemetry.provider ? ' provider' : ' estimate/unknown'}`);
+      console.log(`  Cost telemetry: ${caps.costTelemetry.available ? 'available' : `unavailable (${caps.costTelemetry.reason})`}`);
+      console.log(`  Note: ${caps.hook.note}`);
+    }
+    return;
   }
-  if (sourceIdx !== -1 && argv[sourceIdx + 1]) {
-    sourceUrl = argv[sourceIdx + 1];
+
+  if (sub === 'record') {
+    const { state } = readState(opts.targetDir);
+    const ledger = new RunLedger({
+      targetDir: opts.targetDir,
+      policy,
+      runId: opts.runId || state?.activeRunId || null,
+      workItemId: opts.workItemId || (state ? workItemIdOf(state) : null),
+      phase: opts.phase || state?.session?.currentPhase || null,
+    });
+    const type = opts.type || 'tool-call';
+    const reason = opts.reason || opts.rest[1] || 'recorded event';
+    if (type === 'decision') {
+      ledger.addDecision({ kind: 'stop', reason });
+    } else if (type === 'verification') {
+      ledger.addSpan({ kind: 'verification', name: opts.gate || 'manual', status: opts.evidenceStatus || 'ok', reason });
+    } else {
+      ledger.addSpan({ kind: type, name: opts.gate || type, status: 'ok', reason, tool: opts.tool || null });
+    }
+    ledger.finalize();
+    const path = ledger.persist();
+    emit(opts, `✅ Recorded ${type} event in ${path}.`, { ok: true, runId: ledger.runId, path });
+    return;
   }
 
-  switch (command) {
-    case 'init':
-      await install(targetDir, { sourceUrl });
-      break;
-    case 'sync':
-      await sync(targetDir, { sourceUrl });
-      break;
-    case '--version':
-    case '-v':
-      console.log(`cadet-agent v${getVersion()}`);
-      break;
-    case '--help':
-    case '-h':
-    case undefined:
-      showHelp();
-      break;
-    default:
-      console.error(`Unknown command: ${command}`);
-      console.error('Run cadet-agent --help for usage.');
+  if (sub === 'verify') {
+    const gate = opts.gate;
+    if (!gate) fail(opts, 'harness verify requires --gate <gate>');
+    const { state } = readState(opts.targetDir);
+    const caps = detectCapabilities({ targetDir: opts.targetDir });
+    const descriptor = opts.command
+      ? { command: opts.command, tool: 'custom', automated: true }
+      : commandForGate(gate, { policy, projectPath: opts.targetDir, unityAvailable: caps.unityCli.available });
+
+    if (!descriptor.automated || !descriptor.command) {
+      const detail = { ok: false, gate, blocked: true, reason: descriptor.reason || 'no automated command available' };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(`❌ Cannot automate gate "${gate}": ${detail.reason}. Record a manual confirmation instead.`);
+      process.exit(1);
+    }
+
+    const ledger = new RunLedger({
+      targetDir: opts.targetDir,
+      policy,
+      runId: state?.activeRunId || null,
+      workItemId: state ? workItemIdOf(state) : null,
+      phase: state?.session?.currentPhase || null,
+      capabilities: caps,
+    });
+
+    // Relevant files bind the evidence to a concrete input tree so later edits
+    // invalidate it. Prefer an explicit --files list; otherwise use the working
+    // tree's changed files. If git cannot be queried and no files were supplied,
+    // freshness coverage cannot be established — fail safe rather than record a
+    // passing gate against an empty input tree. `allowEmptyFreshness` is the
+    // explicit, visible opt-out.
+    const allowEmpty = policy?.allowEmptyFreshness === true;
+    let relevantFiles;
+    let filesSource;
+    if (opts.files && opts.files.length) {
+      relevantFiles = opts.files.map((f) => f.replace(/\\/g, '/'));
+      filesSource = 'explicit';
+    } else {
+      const changed = gitChangedFiles(opts.targetDir);
+      if (!changed.available) {
+        if (!allowEmpty) {
+          const detail = {
+            ok: false,
+            gate,
+            blocked: true,
+            code: 'freshness-unavailable',
+            reason: `cannot establish freshness coverage: ${changed.reason}. Pass --files <paths> to bind evidence to the relevant files, or enable allowEmptyFreshness in .cadet/harness.json to opt into unscoped evidence.`,
+          };
+          if (opts.format === 'json') emit(opts, '', detail);
+          else console.error(`❌ ${detail.reason}`);
+          process.exit(1);
+        }
+        relevantFiles = [];
+        filesSource = 'unscoped (allowEmptyFreshness)';
+      } else {
+        relevantFiles = changed.files;
+        filesSource = 'working-tree';
+      }
+    }
+
+    if (relevantFiles.length === 0 && !allowEmpty && filesSource !== 'explicit') {
+      const detail = {
+        ok: false,
+        gate,
+        blocked: true,
+        code: 'freshness-unavailable',
+        reason: 'no relevant files were found to bind evidence to. Pass --files <paths>, or enable allowEmptyFreshness in .cadet/harness.json to opt into unscoped evidence.',
+      };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(`❌ ${detail.reason}`);
       process.exit(1);
+    }
+
+    // Red-before-green applies to testable work items; a `no_test_required`
+    // change is exempt (contract §5).
+    const noTestRequired = state?.session?.workflowPath === 'no_test_required';
+
+    // Record how the relevant files were chosen (provenance) in the ledger.
+    ledger.addDecision({
+      kind: 'stop',
+      reason: `freshness-bound via ${filesSource}`,
+      scope: relevantFiles.join(',') || '(none)',
+    });
+
+    const result = await runVerificationLoop({
+      gate,
+      command: descriptor.command,
+      tool: descriptor.tool,
+      workItemId: ledger.workItemId || 'unscoped',
+      phase: ledger.phase || 'implementation',
+      relevantFiles,
+      rootDir: opts.targetDir,
+      policy,
+      budgets: ledger.tracker,
+      artifactDir: join(runsDir(opts.targetDir), 'artifacts'),
+      priorEvidence: Array.isArray(state?.gateEvidence) ? state.gateEvidence : [],
+      requireRedFirst: noTestRequired ? false : null,
+    });
+
+    for (const a of result.attempts) ledger.addEvidence(a.evidence);
+    ledger.finalize({ status: result.ok ? 'ok' : 'failed' });
+    const path = ledger.persist();
+
+    // Close the loop: record the produced evidence in state.json so
+    // `state transition` can see it. A passing verification flips the gate
+    // 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 };
+      }
+      writeState(opts.targetDir, next);
+      stateUpdated = true;
+    }
+
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: result.ok, status: result.status, gate, attempts: result.attempts.length, stopReason: result.stopReason, runId: ledger.runId, path, stateUpdated });
+    } else if (result.ok) {
+      console.log(`✅ Gate "${gate}" verified (${result.attempts.length} attempt(s)). Ledger: ${path}`);
+    } else {
+      console.error(`❌ Gate "${gate}" failed (${result.status}, ${result.stopReason || 'no reason'}). Ledger: ${path}`);
+    }
+    if (!result.ok) process.exit(1);
+    return;
+  }
+
+  if (sub === 'report') {
+    const runs = listRuns(opts.targetDir);
+    const target = opts.runId || runs[0]?.runId;
+    if (!target) fail(opts, 'No run records found in .cadet/runs/.', () => 2);
+    const run = loadRun(opts.targetDir, target);
+    if (!run) fail(opts, `Run ${target} not found.`, () => 2);
+    if (opts.format === 'json') emit(opts, '', { ok: true, report: buildReport(run) });
+    else console.log(formatReport(run));
+    return;
+  }
+
+  if (sub === 'cleanup') {
+    const { deleted, kept } = cleanupRuns(opts.targetDir, policy, {
+      olderThanMs: Number.isFinite(opts.olderThanMs) ? opts.olderThanMs : null,
+    });
+    emit(opts, `✅ Cleanup: deleted ${deleted.length} run(s), kept ${kept.length}.`, { ok: true, deleted, kept });
+    return;
+  }
+
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|verify|report|cleanup|capabilities.`);
+}
+
+export async function run(argv) {
+  const command = argv[2];
+  const opts = parseArgs(argv);
+
+  try {
+    switch (command) {
+      case 'init':
+        await install(opts.targetDir, { sourceUrl: opts.sourceUrl });
+        break;
+      case 'sync':
+        await sync(opts.targetDir, { sourceUrl: opts.sourceUrl });
+        break;
+      case 'state':
+        await cmdState(opts);
+        break;
+      case 'harness':
+        await cmdHarness(opts);
+        break;
+      case '--version':
+      case '-v':
+        console.log(`cadet-agent v${getVersion()}`);
+        break;
+      case '--help':
+      case '-h':
+      case undefined:
+        showHelp();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.error('Run cadet-agent --help for usage.');
+        process.exit(1);
+    }
+  } catch (err) {
+    if (err instanceof PolicyError || err instanceof StateError) {
+      fail(opts, err.message);
+    }
+    throw err;
   }
 }