cadet-agent 0.45.0 → 0.47.0

package/README.md

@@ -9,7 +9,7 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
   - `cadet-agent.md` is the thin global directive: identity, non-negotiable rules, workflow routing, hard-gate protocol, and skill dispatch.
   - `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 (PlanningReview, Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer).
+  - `skills/` contains scoped workflow-phase skills (PlanningReview, Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer, Handoff, Reconciliation).
   - `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).
@@ -28,7 +28,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 five IDEs. The same 10 skills + reviewer are available in each:
+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 |
 |---|---|---|---|---|---|
@@ -44,6 +44,7 @@ Cadet-Agent provides full workflow parity across five IDEs. The same 10 skills +
 | 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`) |
 
@@ -199,6 +200,7 @@ cadet-agent state seal                           # write the active work item's
 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 reconcile                    # reconcile the planning chain against state.json (read-only)
 cadet-agent harness cleanup --older-than-ms <n>  # apply the retention policy (bound required)
 cadet-agent harness capabilities                 # available CLI/Unity/MCP/hook/token/cost telemetry
 ```

package/package.json

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

package/src/cli.mjs

@@ -7,6 +7,8 @@ import {
   workItemIdOf, loadPolicy, RunLedger, loadRun, listRuns, cleanupRuns, buildReport, formatReport,
   runVerificationLoop, commandForGate, detectCapabilities, runsDir, gitChangedFiles, PolicyError, StateError,
   detectRepoRole, describeRepoRole, GATES, manualConfirmation,
+  gitChangeSet, DEFAULT_REPORT_DIR,
+  reconcileArtifacts, PLANS_DEFAULT_DIR,
   parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
   parseReachabilityDeclaration, validateReachabilityDeclaration, collectWorkItems,
   findDeferralCycles, readSiblingDeclarations, normalizeWorkItemRef, describeReachabilityGaps,
@@ -58,6 +60,8 @@ function showHelp() {
     cadet-agent harness verify-acs  Verify declared AC↔test coverage against a test report
     cadet-agent harness verify-reachability  Verify a story's declared reachability (opt-in)
     cadet-agent harness report      Summarize budget consumption and failures
+    cadet-agent harness changes     List the files a story changed, with status, counts, and links
+    cadet-agent harness reconcile   Reconcile the planning chain against state.json (read-only)
     cadet-agent harness cleanup     Apply the retention policy to .cadet/runs/
     cadet-agent harness capabilities  Report available CLI/Unity/MCP/hook/token/cost telemetry
 
@@ -78,6 +82,10 @@ function showHelp() {
     --report       Test report to derive the inventory from (harness verify-acs|matrix-check)
     --matrix       TDD matrix markdown to check (harness matrix-check)
     --inventory    Newline-separated test names, when no report is available (harness matrix-check)
+    --range        Base revision to diff instead of the working tree (harness changes)
+    --relative-to  Directory the emitted links are relative to (harness changes; default .cadet/reports)
+    --include-cadet  Keep .cadet/ bookkeeping among the listed files (harness changes)
+    --plans-dir    Directory holding the planning artifacts (harness reconcile; default .cadet/agent/project-plans)
     --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)
@@ -164,6 +172,10 @@ function parseArgs(argv) {
       case '--commit': opts.commitGiven = true; opts.commit = value(a); break;
       case '--matrix': opts.matrix = value(a); break;
       case '--inventory': opts.inventory = value(a); break;
+      case '--range': opts.range = value(a); break;
+      case '--relative-to': opts.relativeTo = value(a); break;
+      case '--include-cadet': opts.includeCadet = true; break;
+      case '--plans-dir': opts.plansDir = value(a); break;
       case '--write-coverage': opts.writeCoverage = true; break;
       case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
@@ -1293,6 +1305,109 @@ async function cmdHarness(opts) {
     return;
   }
 
+  // Read-only. Produces the deterministic half of a Change Report — which files
+  // changed, how, and by how much — so the agent never assembles that table from
+  // memory. The other half, why each file changed, is not knowable from git and
+  // stays the agent's job. See .cadet/agent/core/skills/CodeReview.md.
+  //
+  // A missing git is NOT a usage error here. This command informs a review that
+  // can still be completed, so it reports the limitation and exits 0 rather than
+  // blocking the review; the report records it under Limits.
+  if (sub === 'changes') {
+    const relativeTo = opts.relativeTo || DEFAULT_REPORT_DIR;
+    const changes = gitChangeSet(opts.targetDir, {
+      range: opts.range || null,
+      relativeTo,
+      includeCadet: opts.includeCadet === true,
+    });
+
+    const { exists, state } = readState(opts.targetDir);
+    const item = exists ? state?.activeWorkItem ?? null : null;
+    const workItem = item ? { epicId: item.epicId ?? null, storyId: item.storyId ?? null } : null;
+
+    const payload = {
+      ok: true,
+      available: changes.available,
+      workItem,
+      range: opts.range || 'working-tree',
+      relativeTo,
+      files: changes.files,
+      counts: changes.counts,
+      reason: changes.reason,
+    };
+    if (opts.format === 'json') {
+      emit(opts, '', payload);
+      return;
+    }
+
+    if (!changes.available) {
+      console.log(`\n⚠️  Change inventory unavailable: ${changes.reason}`);
+      console.log('   Do not list files from memory — record this as a limit of the report.');
+      return;
+    }
+
+    const c = changes.counts;
+    console.log(`\nChange inventory (${payload.range}) — ${changes.files.length} file(s)`);
+    console.log(`  ${c.added} added · ${c.modified} modified · ${c.renamed} renamed · ${c.deleted} deleted`);
+    if (changes.files.length === 0) {
+      console.log('\n  (no changes)');
+    } else {
+      console.log('');
+      for (const f of changes.files) {
+        const lines = f.added === null && f.deleted === null ? 'new' : `+${f.added ?? 0}/-${f.deleted ?? 0}`;
+        console.log(`  ${f.status}  ${lines.padEnd(10)} ${f.path}`);
+      }
+    }
+    const label = workItem ? `${workItem.epicId || 'none'}::${workItem.storyId || 'none'}` : 'none';
+    console.log(`\n  Links relative to ${relativeTo} · work item: ${label}`);
+    return;
+  }
+
+  // Read-only. Reconciles the planning chain against state.json: the mechanical
+  // half of the Reconciliation skill. It reports the inconsistencies it can prove
+  // from the artifacts and never repairs one — the skill proposes repairs for the
+  // user to approve. See .cadet/agent/core/skills/Reconciliation.md.
+  //
+  // Exit 0 whatever the verdict: the verdict is the payload, and a caller reading
+  // `--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.
+  if (sub === 'reconcile') {
+    const { exists, state } = readState(opts.targetDir);
+    const result = reconcileArtifacts(opts.targetDir, {
+      state: exists ? state : null,
+      plansDir: opts.plansDir || PLANS_DEFAULT_DIR,
+      story: opts.story || null,
+    });
+
+    if (opts.format === 'json') {
+      emit(opts, '', result);
+      return;
+    }
+    if (!result.available) {
+      console.log(`\nℹ️  Nothing to reconcile: ${result.reason}`);
+      return;
+    }
+
+    const s = result.summary;
+    console.log(`\nReconcile ${result.plansDir}${result.scopedEpic ? ` (${result.scopedEpic})` : ''} — verdict: ${result.verdict}`);
+    console.log(`  ${result.artifacts.epicCount} epic(s), ${result.artifacts.storyCount} story file(s)`);
+    console.log(`  ${s.total} finding(s): ${s.blocking} blocking · ${s.warning} warning · ${s.info} info`);
+    if (s.total === 0) {
+      console.log('\n  ✅ The chain is internally consistent.');
+    } else {
+      console.log('');
+      for (const f of result.findings) {
+        console.log(`  [${f.severity}] ${f.id} ${f.code} — ${f.subject}`);
+        console.log(`        ${f.detail}${f.evidence ? ` (${f.evidence})` : ''}`);
+      }
+    }
+    if (result.verdict === 'unknown') {
+      console.log('\n  ⚠️  At least one artifact could not be read, so consistency cannot be certified.');
+    }
+    return;
+  }
+
   // AR-5. Reconcile a TDD matrix's DELIVERED test-name claims against a compiled
   // inventory. Read-only: it reports, and never writes state, so it can be run at
   // authoring time (before anything has been implemented) as well as in a gate.
@@ -1390,7 +1505,7 @@ async function cmdHarness(opts) {
     return;
   }
 
-  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|verify-reachability|matrix-check|report|cleanup|capabilities.`);
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|verify-reachability|matrix-check|report|changes|reconcile|cleanup|capabilities.`);
 }
 
 export async function run(argv) {

package/src/harness/changes.mjs

@@ -0,0 +1,234 @@
+/**
+ * Change inventory — what a story actually touched, and how much.
+ *
+ * Why this exists: the Change Report's file table has to be *the same table*
+ * every run. When the agent assembled that list by hand — a `git status` here, a
+ * remembered path there — the result varied by run: a file dropped, a status
+ * guessed, a link that did not resolve, a line count invented. The rows are the
+ * part of the report that is mechanically knowable, so they are computed here
+ * and the agent supplies only the prose that is not.
+ *
+ * This is a read-only probe. It runs `git` and parses output; it never writes.
+ *
+ * Availability contract: mirrors `gitChangedFiles` (`util.mjs`). Returns
+ * `{ available: false, reason }` when git cannot be asked — "not a repository"
+ * and "no changes" must not look alike, so callers state the limitation rather
+ * than reporting an empty change set as a clean one.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, join, relative } from 'node:path';
+
+/** Default report directory, from which file links are made relative. */
+export const DEFAULT_REPORT_DIR = '.cadet/reports';
+
+/**
+ * Cadet's own bookkeeping. A story's change report should not lead with the
+ * ledger and state files its own gate checks rewrote. Same set and same reason
+ * as `util.mjs#CADET_MACHINERY`.
+ */
+const CADET_MACHINERY = ['.cadet/state.json', '.cadet/runs/', '.cadet/archive/'];
+
+function isCadetMachinery(relPath) {
+  return CADET_MACHINERY.some((p) => (p.endsWith('/') ? relPath.startsWith(p) : relPath === p));
+}
+
+/**
+ * Collapse porcelain's two status columns (`XY`) to the single letter the
+ * report shows. The staged column wins when it says something, because that is
+ * the status the eventual commit will carry; the worktree column is the
+ * fallback. `??` is an untracked file, which a reader reads as "added".
+ */
+const STATUS_LETTERS = { R: 'R', C: 'R', A: 'A', D: 'D', M: 'M', T: 'M' };
+
+function statusFromPorcelain(xy) {
+  if (xy === '??') return 'A';
+  const [staged, unstaged] = xy;
+  return STATUS_LETTERS[staged] || STATUS_LETTERS[unstaged] || 'M';
+}
+
+/**
+ * Normalize a `--numstat` path field, which spells renames three ways:
+ * `new`, `old => new`, and `dir/{old => new}/file`. Only the new path is kept,
+ * matching the name-status side, so the two maps join on the same key.
+ */
+function normalizeNumstatPath(raw) {
+  const path = String(raw || '').trim();
+  if (!path.includes(' => ')) return path;
+  const braced = path.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
+  if (braced) return `${braced[1]}${braced[3]}${braced[4]}`.replace(/\/{2,}/g, '/');
+  return path.split(' => ').pop().trim();
+}
+
+function defaultGitRunner(cmd, args) {
+  try {
+    return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run one git command and return its stdout, or `{ error }` describing why the
+ * question could not be asked. Every call goes through here so a single probe
+ * failure is reported the same way regardless of which command failed.
+ */
+function runGit(cwd, args, runner) {
+  let res;
+  try {
+    res = runner('git', ['-C', cwd, ...args]);
+  } catch (err) {
+    return { error: `git invocation failed: ${err.message}` };
+  }
+  if (!res) return { error: 'git is not available' };
+  if (res.error || res.status === null) {
+    return { error: 'git is not installed or could not be executed' };
+  }
+  if (res.status !== 0) {
+    return { error: String(res.stderr || '').trim() || `git exited ${res.status}` };
+  }
+  return { stdout: String(res.stdout || '') };
+}
+
+/**
+ * Files and statuses for the change set. Untracked files appear only in the
+ * working-tree form; a `--range` diff is a commit-to-commit question and cannot
+ * see them.
+ */
+function readNameStatus(cwd, { runner, range }) {
+  if (range) {
+    const res = runGit(cwd, ['diff', '--name-status', range, '--'], runner);
+    if (res.error) return { error: res.error };
+    const files = [];
+    for (const line of res.stdout.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      // "M\tpath" — or "R100\told\tnew", where the new path is the one that exists.
+      const fields = line.split('\t');
+      if (fields.length < 2) continue;
+      const path = fields[fields.length - 1].trim();
+      if (!path) continue;
+      files.push({ path: path.replace(/\\/g, '/'), status: fields[0][0] });
+    }
+    return { files };
+  }
+
+  const res = runGit(cwd, ['status', '--porcelain', '--untracked-files=all'], runner);
+  if (res.error) return { error: res.error };
+  const files = [];
+  for (const line of res.stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    // Porcelain v1: XY<space>path, with renames written "old -> new".
+    const xy = line.slice(0, 2);
+    let path = line.slice(3).trim();
+    if (path.includes(' -> ')) path = path.split(' -> ').pop().trim();
+    path = path.replace(/^"|"$/g, '');
+    if (!path) continue;
+    files.push({ path: path.replace(/\\/g, '/'), status: statusFromPorcelain(xy) });
+  }
+  return { files };
+}
+
+/**
+ * Accumulate one count onto a prior one. A file can appear in both the staged
+ * and the unstaged numstat, and those counts add. `null` means git reported no
+ * number (a binary file); it stays unknown unless a real number was seen.
+ */
+function addCount(prior, value) {
+  if (value === null) return prior === undefined ? null : prior;
+  return (prior ?? 0) + value;
+}
+
+/** Added/deleted counts per path, merged across the staged and unstaged diffs. */
+function mergeNumstat(target, stdout) {
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const [added, deleted, ...rest] = line.split('\t');
+    if (rest.length === 0) continue;
+    const path = normalizeNumstatPath(rest.join('\t'));
+    if (!path) continue;
+    // A binary file reports "-" for both; that is genuinely unknown, not zero.
+    const a = /^\d+$/.test(added) ? Number(added) : null;
+    const d = /^\d+$/.test(deleted) ? Number(deleted) : null;
+    const prior = target.get(path);
+    target.set(path, {
+      added: addCount(prior?.added, a),
+      deleted: addCount(prior?.deleted, d),
+    });
+  }
+}
+
+function readNumstat(cwd, { runner, range }) {
+  const counts = new Map();
+  if (range) {
+    const res = runGit(cwd, ['diff', '--numstat', range, '--'], runner);
+    if (res.error) return { error: res.error };
+    mergeNumstat(counts, res.stdout);
+    return { counts };
+  }
+  const unstaged = runGit(cwd, ['diff', '--numstat', '--'], runner);
+  if (unstaged.error) return { error: unstaged.error };
+  mergeNumstat(counts, unstaged.stdout);
+  const staged = runGit(cwd, ['diff', '--cached', '--numstat', '--'], runner);
+  if (staged.error) return { error: staged.error };
+  mergeNumstat(counts, staged.stdout);
+  return { counts };
+}
+
+/**
+ * The change inventory for a directory.
+ *
+ * @param {string} cwd Repository root to ask about.
+ * @param {object} [options]
+ * @param {Function} [options.runner] Injectable git runner, for tests.
+ * @param {string|null} [options.range] Diff a base revision instead of the working tree.
+ * @param {string} [options.relativeTo] Directory the `link` fields are made relative to.
+ * @param {boolean} [options.includeCadet] Keep `.cadet/` bookkeeping in the list.
+ * @returns {{available: boolean, files: Array, counts: object, reason: string|null}}
+ */
+export function gitChangeSet(cwd, {
+  runner = defaultGitRunner,
+  range = null,
+  relativeTo = DEFAULT_REPORT_DIR,
+  includeCadet = false,
+} = {}) {
+  const empty = { added: 0, modified: 0, deleted: 0, renamed: 0 };
+
+  const named = readNameStatus(cwd, { runner, range });
+  if (named.error) return { available: false, files: [], counts: empty, reason: named.error };
+
+  const counted = readNumstat(cwd, { runner, range });
+  if (counted.error) return { available: false, files: [], counts: empty, reason: counted.error };
+
+  // Links are relative to the report, not the repository root: a report at
+  // `.cadet/reports/x.md` must point at `../../Assets/Foo.cs` or the click does
+  // nothing. Computing it here is the whole reason the link is not hand-written.
+  const baseDir = isAbsolute(relativeTo) ? relativeTo : join(cwd, relativeTo);
+
+  const seen = new Map();
+  for (const file of named.files) {
+    if (!includeCadet && isCadetMachinery(file.path)) continue;
+    if (seen.has(file.path)) continue;
+    const count = counted.counts.get(file.path);
+    const linkTarget = relative(baseDir, join(cwd, file.path)).replace(/\\/g, '/');
+    seen.set(file.path, {
+      path: file.path,
+      status: file.status,
+      // Untracked files have no diff, so no count exists. Null, not zero: a
+      // zero would read as "changed nothing", which is a different claim.
+      added: count?.added ?? null,
+      deleted: count?.deleted ?? null,
+      link: `[${file.path}](${linkTarget})`,
+    });
+  }
+
+  const files = [...seen.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const counts = { ...empty };
+  for (const f of files) {
+    if (f.status === 'A') counts.added += 1;
+    else if (f.status === 'D') counts.deleted += 1;
+    else if (f.status === 'R') counts.renamed += 1;
+    else counts.modified += 1;
+  }
+
+  return { available: true, files, counts, reason: null };
+}

package/src/harness/commands.mjs

@@ -123,6 +123,20 @@ export const COMMANDS = {
     mutates: false,
     summary: 'Summarize budget consumption and failures.',
   },
+  'harness changes': {
+    mutates: false,
+    summary: 'List the files a story changed, with status, line counts, and links.',
+    // Read-only by construction: it runs `git status`/`git diff` and parses the
+    // output. It does not author the Change Report — the agent does, from the
+    // template — so there is no artifact for it to write and nothing to dry-run.
+  },
+  'harness reconcile': {
+    mutates: false,
+    summary: 'Reconcile the planning chain (requirements, design, plan, epics, stories) against state.json.',
+    // Read-only, and deliberately so: it reports the provable inconsistencies and
+    // never repairs one. An agent that could reconcile artifacts unattended could
+    // rewrite the design it is meant to be checking against.
+  },
   'harness matrix-check': {
     mutates: false,
     summary: 'Reconcile a TDD matrix against a compiled test inventory.',

package/src/harness/index.mjs

@@ -23,6 +23,13 @@ export {
   newId, isUuid, sha256, sha256Bytes, hashFile, hashTree, hashCriteria, timestamp, canonicalJson, changedFiles, gitChangedFiles,
 } from './util.mjs';
 
+export { DEFAULT_REPORT_DIR, gitChangeSet } from './changes.mjs';
+
+export {
+  PLANS_DEFAULT_DIR, REQUIRED_ARTIFACTS, RECONCILE_SEVERITIES, RECONCILE_VERDICTS,
+  DEFAULT_MAX_DOC_BYTES, parseStoryHeader, parseEpicHeader, collectArtifacts, reconcileArtifacts,
+} from './reconcile.mjs';
+
 export {
   STATE_VERSION, READABLE_STATE_VERSIONS, HISTORY_EXTERNAL_SINCE, isHistoryExternal,
   validateState, migrateStateV1toV2, migrateStateDocument, migrateStateFile, parseTargetVersion,