cadet-agent 0.31.0 → 0.32.1

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "cadet-agent",
-  "version": "0.31.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.32.1",
+  "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 } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { install, sync } from './install.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,
+  parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
+  createEvidence, newId, computeInputTreeHash, hashCriteria,
 } from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -41,6 +43,7 @@ function showHelp() {
     cadet-agent harness record      Append a sanitized span/evidence/decision event
     cadet-agent harness confirm     Record manual-confirmation evidence (writes ledger + state)
     cadet-agent harness verify      Run a bounded, classified verification loop
+    cadet-agent harness verify-acs  Verify declared AC↔test coverage against a test report
     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
@@ -87,6 +90,9 @@ function parseArgs(argv) {
       case '--scope': opts.scope = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
       case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
       case '--files': opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
+      case '--story': opts.story = argv[++i]; break;
+      case '--report': opts.report = argv[++i]; break;
+      case '--write-coverage': opts.writeCoverage = true; break;
       case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
       case '--agents-md': opts.agentsMd = argv[++i]; break;
       case '--yes': case '-y': opts.yes = true; break;
@@ -537,6 +543,168 @@ async function cmdHarness(opts) {
     return;
   }
 
+  if (sub === 'verify-acs') {
+    // Mechanical AC↔test verification (contract v4). Declared tests must appear
+    // in the inventory of a run that actually executed them; a name that was
+    // never written cannot be asserted into coverage.
+    if (!opts.story) fail(opts, 'harness verify-acs requires --story <path>');
+    const { exists, state } = readState(opts.targetDir);
+    const strict = policy.strictClosure?.enabled === true;
+    const workItemId = state ? workItemIdOf(state) : 'unscoped';
+    const phase = state?.session?.currentPhase || 'implementation';
+
+    let criteria;
+    try {
+      ({ criteria } = parseStoryCriteria(opts.story));
+    } catch (err) {
+      fail(opts, `cannot parse story "${opts.story}": ${err.message}`, () => 1, { ok: false, code: 'story-parse', story: opts.story });
+    }
+    if (criteria.length === 0) {
+      fail(opts, `story "${opts.story}" declares no acceptance criteria (expected a "## Acceptance Criteria" section).`, () => 1, { ok: false, code: 'no-criteria', story: opts.story });
+    }
+
+    // Resolve the inventory: an explicit --report, else the artifact of the most
+    // recent passing testsPassed evidence. Neither resolving is `blocked`, never
+    // a pass — an unproven inventory cannot satisfy coverage.
+    let reportText = null;
+    let reportSource = null;
+    let reportPath = null;
+    if (opts.report) {
+      try {
+        reportText = readFileSync(opts.report, 'utf-8');
+        reportSource = 'explicit';
+        reportPath = opts.report;
+      } catch (err) {
+        fail(opts, `cannot read --report "${opts.report}": ${err.message}`, () => 1, { ok: false, code: 'report-unreadable', report: opts.report });
+      }
+    } else if (exists) {
+      const prior = Array.isArray(state.gateEvidence) ? state.gateEvidence : [];
+      const passing = prior
+        .filter((e) => e.gate === 'testsPassed' && e.status === 'passed' && e.artifactPath)
+        .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+      const newest = passing[0];
+      if (newest) {
+        try {
+          reportText = readFileSync(newest.artifactPath, 'utf-8');
+          reportSource = 'testsPassed-evidence';
+          reportPath = newest.artifactPath;
+        } catch { /* fall through to blocked */ }
+      }
+    }
+    if (reportText === null) {
+      const detail = { ok: false, story: opts.story, blocked: true, code: 'no-test-report', reason: 'no test report available: pass --report <path>, or run `cadet-agent harness verify --gate testsPassed` first so its artifact can be read.' };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else console.error(`❌ ${detail.reason}`);
+      process.exit(1);
+    }
+
+    const inventory = parseTestInventory(reportText);
+    const coverage = compareCoverage(criteria, inventory);
+    const gaps = describeCoverageGaps(coverage);
+
+    // Under strict closure an unknown/empty inventory can never prove coverage,
+    // even if every AC declared no tests in a way that looked consistent.
+    const unknownInventory = inventory.format === 'unknown' || inventory.names.length === 0;
+    const effectiveOk = coverage.ok && !unknownInventory;
+
+    if (!strict) {
+      // v2/v3 parity: report, write nothing, exit 0.
+      if (opts.format === 'json') {
+        emit(opts, '', { ok: effectiveOk, story: opts.story, ac: coverage.ac, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: false, reportPath });
+      } else if (effectiveOk) {
+        console.log(`✅ AC coverage verified for ${opts.story} (${coverage.ac.length} criteria, ${coverage.inventorySize} tests in inventory).`);
+        console.log('   strictClosure is off — reported only, state.json unchanged.');
+      } else {
+        console.error(`⚠️  AC coverage gaps in ${opts.story} (strictClosure off — reported only):`);
+        if (unknownInventory) console.error(`   no test inventory could be derived from ${reportPath || 'the report'} (format: ${inventory.format}).`);
+        for (const g of gaps) console.error(g);
+      }
+      if (!effectiveOk) process.exit(1);
+      return;
+    }
+
+    if (!effectiveOk) {
+      const detail = { ok: false, story: opts.story, ac: coverage.ac, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: false, code: unknownInventory ? 'inventory-unknown' : 'coverage-gap' };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else {
+        console.error(`❌ Cannot set acceptanceCriteriaValidated for ${opts.story}:`);
+        if (unknownInventory) console.error(`   no test inventory could be derived from ${reportPath || 'the report'} (format: ${inventory.format}). An unparseable report proves nothing.`);
+        for (const g of gaps) console.error(g);
+      }
+      process.exit(1);
+    }
+
+    const at = new Date();
+    const criteriaStrings = coverage.ac.flatMap((a) => [a.id, ...a.declared]);
+    const nowIso = at.toISOString();
+    const evidence = createEvidence({
+      evidenceId: newId(),
+      workItemId,
+      acceptanceCriterionId: null,
+      phase,
+      gate: 'acceptanceCriteriaValidated',
+      status: 'passed',
+      command: `harness verify-acs --story ${opts.story}`,
+      result: `AC coverage verified: ${coverage.ac.length} criteria, inventory ${coverage.inventorySize} (${inventory.format})`,
+      exitCode: 0,
+      inputTreeHash: computeInputTreeHash(opts.targetDir, [opts.story, ...(reportPath ? [reportPath] : [])]),
+      criteriaHash: hashCriteria(criteriaStrings),
+      relevantFiles: [opts.story, ...(reportPath ? [reportPath] : [])].map((f) => f.replace(/\\/g, '/')),
+      createdAt: at,
+      expiresAt: null,
+      // Schema + validator require an object carrying a `scope`, not a bare
+      // string: state.schema.json#/$defs/evidence references
+      // harness.schema.json#/$defs/freshnessPolicy, which has required:["scope"]
+      // with scope ∈ story|phase|run|manual.
+      freshnessPolicy: { scope: 'story' },
+      source: 'automated',
+    });
+
+    let coveragePath = null;
+    if (opts.writeCoverage) {
+      const base = opts.story.replace(/\.md$/, '');
+      coveragePath = `${base}.coverage.json`;
+      const doc = {
+        schemaVersion: 1,
+        story: opts.story.replace(/\\/g, '/'),
+        generatedAt: nowIso,
+        ac: coverage.ac,
+        inventorySize: coverage.inventorySize,
+        format: inventory.format,
+      };
+      try { writeFileSync(coveragePath, `${JSON.stringify(doc, null, 2)}\n`, 'utf-8'); } catch { coveragePath = null; }
+    }
+
+    // Ledger first, then state — the v3 ordering: fail toward "less proven".
+    const ledger = new RunLedger({ targetDir: opts.targetDir, policy, runId: state?.activeRunId || null, workItemId, phase });
+    ledger.addEvidence(evidence);
+    ledger.addDecision({ kind: 'stop', reason: `AC coverage verified via ${reportSource}`, scope: `${coverage.ac.length} criteria` });
+    ledger.finalize({ status: 'ok' });
+    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 };
+      writeState(opts.targetDir, next);
+    }
+
+    if (opts.format === 'json') {
+      emit(opts, '', { ok: true, story: opts.story, ac: coverage.ac, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: exists, coveragePath, evidenceId: evidence.evidenceId, runId: ledger.runId, path: ledgerPath });
+    } else {
+      console.log(`✅ acceptanceCriteriaValidated for ${opts.story} (${coverage.ac.length} criteria, inventory ${coverage.inventorySize}, ${inventory.format}).`);
+      console.log(`   Ledger: ${ledgerPath}`);
+      if (coveragePath) console.log(`   Coverage: ${coveragePath}`);
+    }
+    return;
+  }
+
   if (sub === 'report') {
     const runs = listRuns(opts.targetDir);
     const target = opts.runId || runs[0]?.runId;
@@ -556,7 +724,7 @@ async function cmdHarness(opts) {
     return;
   }
 
-  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|report|cleanup|capabilities.`);
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|report|cleanup|capabilities.`);
 }
 
 export async function run(argv) {

package/src/harness/index.mjs

@@ -63,3 +63,9 @@ export {
 export {
   REPO_ROLES, REPO_ROLE_MARKER, detectRepoRole, isFrameworkSourceWithoutWorkItem, describeRepoRole,
 } from './repo-role.mjs';
+
+export {
+  INVENTORY_FORMATS, COVERAGE_STATUSES, DEFAULT_MAX_REPORT_BYTES, DEFAULT_MAX_INVENTORY_ENTRIES,
+  normalizeTestName, parseTestInventory, parseStoryCriteria, parseStoryCriteriaText,
+  compareCoverage, describeCoverageGaps,
+} from './verify-acs.mjs';

package/src/harness/verify-acs.mjs

@@ -0,0 +1,291 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Mechanical AC↔test verification (Harness contract v4).
+ *
+ * Closes the defect class where a recorded claim names an artifact that does not
+ * exist and nothing re-checks the name: an epic's TDD matrix named tests that
+ * were never written, and the drift was only noticed at the validation gate,
+ * after the story had merged.
+ *
+ * Three responsibilities:
+ *   1. parseTestInventory — extract the identifiers of tests that ACTUALLY RAN
+ *      from a verification run's report (TAP, JUnit XML, Unity JSON).
+ *   2. parseStoryCriteria — read the declared AC → test mapping from the story,
+ *      which is the single source of truth for the coverage claim.
+ *   3. compareCoverage — declared vs found, with every gap reported together.
+ *
+ * Nothing here "passes" on unknown input: an unparseable report yields an empty
+ * inventory, which cannot satisfy coverage (Harness.md §3 — unknown is never
+ * silently zero/passing).
+ */
+
+export const INVENTORY_FORMATS = Object.freeze(['tap', 'junit', 'unity-json', 'unknown']);
+
+export const COVERAGE_STATUSES = Object.freeze(['covered', 'missing', 'undeclared']);
+
+/** Bound on how many bytes of a report are scanned, so a huge report cannot blow the budget. */
+export const DEFAULT_MAX_REPORT_BYTES = 4 * 1024 * 1024;
+
+/** Upper bound on identifiers extracted, mirroring the archive file-count discipline. */
+export const DEFAULT_MAX_INVENTORY_ENTRIES = 20000;
+
+/**
+ * Normalize a test identifier for comparison.
+ *
+ * Deliberately conservative: trim, collapse internal whitespace, strip a trailing
+ * duplicate-index suffix such as ` (1)`. Case is preserved so `Grid_Foo` and
+ * `grid_foo` do NOT match — a fuzzier rule would defeat the purpose of the check.
+ * A project that needs looser matching must rename its tests, not loosen this.
+ */
+export function normalizeTestName(name) {
+  if (name === null || name === undefined) return '';
+  return String(name)
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\s*\(\d+\)$/, '');
+}
+
+/**
+ * Extract the identifiers of tests that ran from a report.
+ *
+ * Detection is by content, so a repository needs no extra configuration.
+ * Returns `{ format, names, partial, truncatedBytes }`.
+ * - `format` is one of INVENTORY_FORMATS.
+ * - `partial` is true when the report was truncated by a bound; a partial
+ *   inventory cannot prove coverage for the truncated region.
+ */
+export function parseTestInventory(
+  report,
+  { maxBytes = DEFAULT_MAX_REPORT_BYTES, maxEntries = DEFAULT_MAX_INVENTORY_ENTRIES } = {},
+) {
+  if (report === null || report === undefined) {
+    return { format: 'unknown', names: [], partial: false, truncatedBytes: 0 };
+  }
+  const text = typeof report === 'string' ? report : String(report);
+  if (text.trim() === '') {
+    return { format: 'unknown', names: [], partial: false, truncatedBytes: 0 };
+  }
+
+  let body = text;
+  let partial = false;
+  let truncatedBytes = 0;
+  if (Buffer.byteLength(body, 'utf-8') > maxBytes) {
+    body = Buffer.from(body, 'utf-8').subarray(0, maxBytes).toString('utf-8');
+    // Drop a possibly-torn final line.
+    const lastBreak = body.lastIndexOf('\n');
+    if (lastBreak !== -1) body = body.slice(0, lastBreak);
+    partial = true;
+    truncatedBytes = Buffer.byteLength(text, 'utf-8') - maxBytes;
+  }
+
+  const trimmed = body.trim();
+
+  // Unity JSON: a JSON document with a `tests` array of objects carrying `name`.
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      const arr = Array.isArray(parsed) ? parsed : (Array.isArray(parsed?.tests) ? parsed.tests : null);
+      if (arr) {
+        const names = [];
+        for (const entry of arr) {
+          const n = entry && (entry.name ?? entry.fullName ?? entry.testName);
+          if (n) names.push(String(n));
+          if (names.length >= maxEntries) { partial = true; break; }
+        }
+        if (names.length > 0) {
+          return { format: 'unity-json', names: dedupe(names), partial, truncatedBytes };
+        }
+      }
+    } catch {
+      // Not JSON after all — fall through to the text formats.
+    }
+  }
+
+  // JUnit XML: <testcase ... name="...">
+  if (/<testcase\b/i.test(body)) {
+    const names = [];
+    const re = /<testcase\b[^>]*?\bname\s*=\s*"([^"]*)"/gi;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+      names.push(m[1]);
+      if (names.length >= maxEntries) { partial = true; break; }
+    }
+    return { format: 'junit', names: dedupe(names), partial, truncatedBytes };
+  }
+
+  // Node TAP: `ok N - name` / `not ok N - name`. A failing test still ran, so
+  // both forms are included.
+  const tapRe = /^(?:not ok|ok)\s+\d+\s+-\s+(.*)$/gm;
+  const tapNames = [];
+  let t;
+  while ((t = tapRe.exec(body)) !== null) {
+    const name = normalizeTestName(t[1]);
+    if (name) tapNames.push(name);
+    if (tapNames.length >= maxEntries) { partial = true; break; }
+  }
+  if (tapNames.length > 0) {
+    return { format: 'tap', names: dedupe(tapNames), partial, truncatedBytes };
+  }
+
+  return { format: 'unknown', names: [], partial, truncatedBytes };
+}
+
+function dedupe(names) {
+  return [...new Set(names.map((n) => String(n)))];
+}
+
+/**
+ * Parse a story's acceptance criteria and their declared tests.
+ *
+ * Expected shape (per the story template):
+ *
+ *   ### AC-1: <title>
+ *   - Given ..., When ..., Then ...
+ *   - Declared tests:
+ *     - Test_Name_One
+ *     - Test_Name_Two
+ *
+ * or inline: `- Declared tests: Test_Name_One, Test_Name_Two`
+ *
+ * Returns `{ criteria: [{ id, title, tests }] }`.
+ * Throws when an AC heading carries no id, or when two ACs share an id — a story
+ * that cannot be parsed is not a story that can be silently accepted.
+ */
+export function parseStoryCriteria(storyPath) {
+  const text = readFileSync(storyPath, 'utf-8');
+  return parseStoryCriteriaText(text);
+}
+
+/** Text-in variant of parseStoryCriteria, for tests and in-memory use. */
+export function parseStoryCriteriaText(text) {
+  const lines = String(text).split(/\r?\n/);
+
+  // Only look inside the Acceptance Criteria section, so a stray `### AC-` in
+  // notes cannot be picked up.
+  let start = lines.findIndex((l) => /^##\s+Acceptance Criteria\s*$/i.test(l.trim()));
+  if (start === -1) return { criteria: [] };
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i].trim())) { end = i; break; }
+  }
+  const section = lines.slice(start + 1, end);
+
+  const criteria = [];
+  const seen = new Map(); // normalized id -> original
+  let current = null;
+
+  const headingRe = /^###\s+(.*)$/;
+  const declaredInlineRe = /^[-*]\s*Declared tests?\s*:\s*(.+)$/i;
+  const declaredBareRe = /^[-*]\s*Declared tests?\s*:?\s*$/i;
+  const bulletRe = /^[-*]\s+(.*)$/;
+
+  for (const raw of section) {
+    const line = raw.trim();
+    const heading = headingRe.exec(line);
+    if (heading) {
+      const rest = heading[1].trim();
+      const idMatch = /^(AC-[\w.-]+)\s*:?\s*(.*)$/i.exec(rest);
+      if (!idMatch) {
+        throw new Error(`acceptance criterion heading has no AC id: "${rest}"`);
+      }
+      const id = idMatch[1];
+      const key = id.toUpperCase();
+      if (seen.has(key)) {
+        throw new Error(`duplicate AC id "${id}" in story`);
+      }
+      seen.set(key, id);
+      current = { id, title: idMatch[2].trim(), tests: [] };
+      criteria.push(current);
+      continue;
+    }
+    if (!current) continue;
+
+    // `- Declared tests: A, B` (inline) — check before the bare form.
+    const inline = declaredInlineRe.exec(line);
+    if (inline) {
+      for (const name of splitTestList(inline[1])) current.tests.push(name);
+      current.bareDeclaredList = true; // allow following nested bullets too
+      continue;
+    }
+
+    // `- Declared tests:` on its own line — the following bullets are the tests.
+    if (declaredBareRe.test(line)) {
+      current.bareDeclaredList = true;
+      continue;
+    }
+
+    // A nested bullet while in the declared-tests list.
+    if (current.bareDeclaredList) {
+      const bullet = bulletRe.exec(line);
+      if (bullet) {
+        current.tests.push(bullet[1].trim());
+        continue;
+      }
+      current.bareDeclaredList = false;
+    }
+  }
+
+  for (const c of criteria) {
+    delete c.bareDeclaredList;
+    c.tests = dedupe(c.tests.map((t) => t.trim()).filter(Boolean));
+  }
+  return { criteria };
+}
+
+function splitTestList(text) {
+  return text.split(/[,;]/).map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Compare a story's declared tests against a run's inventory.
+ *
+ * Returns `{ ok, ac: [{ id, declared, found, status }], inventorySize, format }`.
+ * `status` is `covered` (all declared found), `missing` (some declared absent),
+ * or `undeclared` (the AC declares no test at all).
+ *
+ * Every gap is reported together; the caller renders all of them, never just the
+ * first.
+ */
+export function compareCoverage(criteria, inventory) {
+  const found = new Set((inventory?.names || []).map((n) => normalizeTestName(n)));
+  const ac = [];
+  let ok = true;
+
+  for (const c of criteria) {
+    const declared = (c.tests || []).map((t) => String(t));
+    if (declared.length === 0) {
+      ok = false;
+      ac.push({ id: c.id, declared: [], found: [], status: 'undeclared' });
+      continue;
+    }
+    const present = declared.filter((t) => found.has(normalizeTestName(t)));
+    const status = present.length === declared.length ? 'covered' : 'missing';
+    if (status !== 'covered') ok = false;
+    ac.push({ id: c.id, declared, found: present, status });
+  }
+
+  return {
+    ok,
+    ac,
+    inventorySize: (inventory?.names || []).length,
+    format: inventory?.format || 'unknown',
+  };
+}
+
+/** Format the gaps as concrete, actionable lines (spec §5.1 step 4). */
+export function describeCoverageGaps(coverage) {
+  const lines = [];
+  for (const entry of coverage.ac) {
+    if (entry.status === 'undeclared') {
+      lines.push(`   ${entry.id}: declares no test — record the test identifier(s) that prove this criterion.`);
+    } else if (entry.status === 'missing') {
+      const found = new Set(entry.found.map((n) => normalizeTestName(n)));
+      const absent = entry.declared.filter((t) => !found.has(normalizeTestName(t)));
+      for (const t of absent) {
+        lines.push(`   ${entry.id}: declared test "${t}" did not appear in the test report — either it was renamed (update the story) or it was never written.`);
+      }
+    }
+  }
+  return lines;
+}