@mutagent/helix 0.1.0-alpha.14

package/mutagent-builder/.claude/skills/mutagent-builder/scripts/sync-spec/check-sync-spec.ts

@@ -0,0 +1,499 @@
+#!/usr/bin/env bun
+/**
+ * scripts/sync-spec/check-sync-spec.ts
+ *
+ * Deterministic freshness probe for the `ai-architect #sync-spec` mode. AgentSpec's `*sync-spec`
+ * command delegates here (Helix-mediated); `*build` reuses it build-internally on drift.
+ *
+ * CLI:
+ *   scripts/cli/run.sh scripts/sync-spec/check-sync-spec.ts --spec <agentspec.yaml?> --target <target-root> [--json]
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
+
+export interface Freshness {
+  updatedAt?: string | null;
+  gitCommitEpoch: number | null;
+  fileMtimeEpoch: number | null;
+  effectiveEpoch: number | null;
+}
+
+/**
+ * The eval-leg (third leg of the def → impl → eval triad, W2I5) freshness verdict.
+ * `not-applicable` = no eval-criteria artifact was requested or located (the 2-leg
+ * spec↔impl reconcile is unaffected — additive). The other three MIRROR the spec-leg
+ * semantics so both legs agree on "impl is newer → reconcile".
+ */
+export type EvalLegStatus = "not-applicable" | "missing-eval" | "in-sync" | "needs-sync";
+
+export interface SyncSpecStatus {
+  status: "missing-spec" | "in-sync" | "needs-sync" | "error";
+  specPath: string | null;
+  targetRoot: string;
+  specFreshness: { updatedAt: string | null; gitCommitEpoch: number | null; fileMtimeEpoch: number | null; effectiveEpoch: number | null };
+  codeFreshness: { gitCommitEpoch: number | null; fileMtimeEpoch: number | null; effectiveEpoch: number | null; newestPath: string | null };
+  /**
+   * The EVAL leg (W2I5 · KP-003). Detects when the impl amended past the eval criteria
+   * that ground the subject's evaluation. Subject-kind-agnostic at THIS layer — the
+   * predicate only stats the criteria artifact's freshness vs the impl; WHICH criteria
+   * (agent/skill eval-suite vs code code-quality) is the reconcile's concern
+   * (`ai-architect #sync-spec` + evaluator `sync-eval-criteria.ts`).
+   */
+  evalStatus: EvalLegStatus;
+  evalFreshness: { path: string | null; updatedAt: string | null; gitCommitEpoch: number | null; fileMtimeEpoch: number | null; effectiveEpoch: number | null };
+  reason: string;
+}
+
+interface CliArgs {
+  spec?: string;
+  target?: string;
+  evalCriteria?: string;
+  json: boolean;
+}
+
+function emptySpecFreshness(): SyncSpecStatus["specFreshness"] {
+  return { updatedAt: null, gitCommitEpoch: null, fileMtimeEpoch: null, effectiveEpoch: null };
+}
+
+function emptyCodeFreshness(targetRoot = ""): SyncSpecStatus["codeFreshness"] {
+  void targetRoot;
+  return { gitCommitEpoch: null, fileMtimeEpoch: null, effectiveEpoch: null, newestPath: null };
+}
+
+function emptyEvalFreshness(): SyncSpecStatus["evalFreshness"] {
+  return { path: null, updatedAt: null, gitCommitEpoch: null, fileMtimeEpoch: null, effectiveEpoch: null };
+}
+
+/** The eval leg is not-applicable when no criteria artifact was requested/located. */
+function notApplicableEval(): { evalStatus: EvalLegStatus; evalFreshness: SyncSpecStatus["evalFreshness"] } {
+  return { evalStatus: "not-applicable", evalFreshness: emptyEvalFreshness() };
+}
+
+function maxEpoch(values: Array<number | null | undefined>): number | null {
+  const present = values.filter((v): v is number => typeof v === "number" && Number.isFinite(v));
+  return present.length ? Math.max(...present) : null;
+}
+
+function epochSeconds(ms: number): number | null {
+  return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+}
+
+function normalizeCandidate(base: string, candidate: string): string {
+  return path.isAbsolute(candidate) ? candidate : path.resolve(base, candidate);
+}
+
+function isPrunedDir(absDir: string, targetRoot: string): boolean {
+  const rel = path.relative(targetRoot, absDir);
+  if (!rel || rel === "") return false;
+  const parts = rel.split(path.sep);
+  if (parts.includes("node_modules") || parts.includes(".git") || parts.includes("dist") || parts.includes("coverage")) return true;
+  const mutagentIdx = parts.indexOf(".mutagent");
+  if (mutagentIdx >= 0 && parts[mutagentIdx + 2] === "runs") return true; // .mutagent/<subject>/runs
+  // The evaluator's namespaced artifact root (.mutagent/evaluator/**) is eval OUTPUT, never
+  // implementation — pruning it keeps eval-suite criteria / datasets from masquerading as impl
+  // drift (they are the EVAL leg, compared separately). W2I5.
+  if (mutagentIdx >= 0 && parts[mutagentIdx + 1] === "evaluator") return true;
+  return false;
+}
+
+function isGeneratedReport(absFile: string, targetRoot: string): boolean {
+  const rel = path.relative(targetRoot, absFile);
+  const parts = rel.split(path.sep);
+  const file = parts.at(-1) ?? "";
+  if (!parts.includes(".mutagent")) return false;
+  if (/^(build-)?report\.(md|json|html)$/i.test(file)) return true;
+  if (/^verdict\.(md|json)$/i.test(file)) return true;
+  return false;
+}
+
+function walkFiles(root: string, predicate: (abs: string) => boolean): string[] {
+  const out: string[] = [];
+  const stack = [root];
+  while (stack.length) {
+    const current = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const abs = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!isPrunedDir(abs, root)) stack.push(abs);
+      } else if (entry.isFile() && predicate(abs)) {
+        out.push(abs);
+      }
+    }
+  }
+  return out.sort();
+}
+
+function locateSpec(targetRoot: string, explicitSpec?: string): string | null {
+  if (explicitSpec) {
+    const abs = normalizeCandidate(process.cwd(), explicitSpec);
+    try {
+      const stat = fs.statSync(abs);
+      return stat.isFile() ? abs : null;
+    } catch {
+      return null;
+    }
+  }
+
+  const direct = path.join(targetRoot, "agentspec.yaml");
+  if (fs.existsSync(direct) && fs.statSync(direct).isFile()) return direct;
+
+  const mutagentSpecs = path.join(targetRoot, ".mutagent", "specs");
+  if (fs.existsSync(mutagentSpecs)) {
+    const found = walkFiles(mutagentSpecs, (abs) => path.basename(abs) === "agentspec.yaml");
+    if (found.length) return found[0];
+  }
+
+  const found = walkFiles(targetRoot, (abs) => path.basename(abs) === "agentspec.yaml");
+  return found[0] ?? null;
+}
+
+function parseUpdatedAt(specPath: string): { updatedAt: string | null; epoch: number | null; error?: string } {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fs.readFileSync(specPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { updatedAt: null, epoch: null, error: `specPath: failed to parse YAML: ${message}` };
+  }
+  const updatedAt = (parsed as any)?.meta?.loop_state?.updated_at;
+  if (typeof updatedAt !== "string") return { updatedAt: null, epoch: null };
+  const ms = Date.parse(updatedAt);
+  if (!Number.isFinite(ms)) return { updatedAt: null, epoch: null };
+  return { updatedAt, epoch: Math.floor(ms / 1000) };
+}
+
+function gitEpochForPaths(targetRoot: string, files: string[]): number | null {
+  if (!files.length) return null;
+  let best: number | null = null;
+  for (let i = 0; i < files.length; i += 100) {
+    const batch = files.slice(i, i + 100).map((f) => path.relative(targetRoot, f));
+    const result = spawnSync("git", ["-C", targetRoot, "log", "-1", "--format=%ct", "--", ...batch], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status !== 0) continue;
+    const text = result.stdout.trim().split(/\s+/).find(Boolean);
+    const n = text ? Number(text) : NaN;
+    if (Number.isFinite(n)) best = best == null ? n : Math.max(best, n);
+  }
+  return best;
+}
+
+function fileMtimeEpoch(file: string): number | null {
+  try {
+    return epochSeconds(fs.statSync(file).mtimeMs);
+  } catch {
+    return null;
+  }
+}
+
+function newestMtime(files: string[]): { epoch: number | null; path: string | null } {
+  let bestEpoch: number | null = null;
+  let bestPath: string | null = null;
+  for (const file of files) {
+    const epoch = fileMtimeEpoch(file);
+    if (epoch != null && (bestEpoch == null || epoch > bestEpoch)) {
+      bestEpoch = epoch;
+      bestPath = file;
+    }
+  }
+  return { epoch: bestEpoch, path: bestPath };
+}
+
+function implementationFiles(targetRoot: string, specPath: string | null, evalPath?: string | null): string[] {
+  const normalizedSpec = specPath ? path.resolve(specPath) : null;
+  const normalizedEval = evalPath ? path.resolve(evalPath) : null;
+  return walkFiles(targetRoot, (abs) => {
+    const resolved = path.resolve(abs);
+    if (normalizedSpec && resolved === normalizedSpec) return false;
+    // The eval-criteria artifact is the EVAL leg, never impl — exclude it so it can never
+    // count as its own drift source (mirror of the spec exclusion). W2I5.
+    if (normalizedEval && resolved === normalizedEval) return false;
+    if (isGeneratedReport(abs, targetRoot)) return false;
+    return true;
+  });
+}
+
+/**
+ * Locate the eval-criteria artifact (the EVAL leg's freshness anchor). An explicit path
+ * wins; otherwise auto-locate under the evaluator's namespaced root
+ * (`.mutagent/evaluator/living-suite/*.{yaml,yml,json}` — the discovered eval-suite
+ * criteria) or a conventional criteria file at the target root. Returns `{ path, existed }`:
+ * an explicit-but-missing path yields `existed:false` (→ `missing-eval`); no path found
+ * yields `path:null` (→ `not-applicable`, additive no-op). W2I5.
+ */
+function locateEvalCriteria(targetRoot: string, explicit?: string): { path: string | null; existed: boolean } {
+  if (explicit) {
+    const abs = normalizeCandidate(process.cwd(), explicit);
+    try {
+      return { path: abs, existed: fs.statSync(abs).isFile() };
+    } catch {
+      return { path: abs, existed: false };
+    }
+  }
+  const criteriaExt = (abs: string): boolean => /\.(ya?ml|json)$/i.test(abs);
+  const livingSuite = path.join(targetRoot, ".mutagent", "evaluator", "living-suite");
+  if (fs.existsSync(livingSuite)) {
+    const found = walkFiles(livingSuite, criteriaExt);
+    if (found.length) return { path: found[0], existed: true };
+  }
+  for (const name of ["eval-criteria", "code-quality-criteria"]) {
+    for (const ext of ["yaml", "yml", "json"]) {
+      const candidate = path.join(targetRoot, `${name}.${ext}`);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return { path: candidate, existed: true };
+    }
+  }
+  return { path: null, existed: false };
+}
+
+/** Parse an optional freshness marker from an eval-criteria artifact (best-effort). */
+function parseEvalUpdatedAt(evalPath: string): { updatedAt: string | null; epoch: number | null } {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fs.readFileSync(evalPath, "utf8"));
+  } catch {
+    return { updatedAt: null, epoch: null };
+  }
+  const raw =
+    (parsed as any)?.meta?.loop_state?.updated_at ??
+    (parsed as any)?.updatedAt ??
+    (parsed as any)?.updated_at ??
+    (parsed as any)?.generatedAt;
+  if (typeof raw !== "string") return { updatedAt: null, epoch: null };
+  const ms = Date.parse(raw);
+  if (!Number.isFinite(ms)) return { updatedAt: null, epoch: null };
+  return { updatedAt: raw, epoch: Math.floor(ms / 1000) };
+}
+
+/**
+ * Compute the EVAL leg (status + freshness) given the code (impl) effective epoch. The
+ * `not-applicable` / `missing-eval` / `in-sync` / `needs-sync` verdict mirrors the spec
+ * leg's semantics so the two legs agree on "impl newer → reconcile". Deterministic. W2I5.
+ */
+function evalLeg(
+  targetRoot: string,
+  explicit: string | undefined,
+  codeEffectiveEpoch: number | null,
+): { evalStatus: EvalLegStatus; evalFreshness: SyncSpecStatus["evalFreshness"] } {
+  const located = locateEvalCriteria(targetRoot, explicit);
+  if (located.path == null) return notApplicableEval();
+  if (!located.existed) {
+    return { evalStatus: "missing-eval", evalFreshness: { ...emptyEvalFreshness(), path: located.path } };
+  }
+  const updated = parseEvalUpdatedAt(located.path);
+  const git = gitEpochForPaths(targetRoot, [located.path]);
+  const mtime = fileMtimeEpoch(located.path);
+  const effectiveEpoch = maxEpoch([updated.epoch, git, mtime]);
+  const evalFreshness = {
+    path: located.path,
+    updatedAt: updated.updatedAt,
+    gitCommitEpoch: git,
+    fileMtimeEpoch: mtime,
+    effectiveEpoch,
+  };
+  const evalStatus: EvalLegStatus =
+    codeEffectiveEpoch != null && effectiveEpoch != null && codeEffectiveEpoch > effectiveEpoch
+      ? "needs-sync"
+      : "in-sync";
+  return { evalStatus, evalFreshness };
+}
+
+/**
+ * The legs that DRIFTED — the triad's headline surface. `spec` drifts on `missing-spec`
+ * (cold construct) or `needs-sync`; `eval` drifts on `missing-eval` or `needs-sync`. The
+ * reconcile (ai-architect) reads this to reconcile BOTH legs when an impl amends. W2I5.
+ */
+export function driftedLegs(status: SyncSpecStatus): Array<"spec" | "eval"> {
+  const legs: Array<"spec" | "eval"> = [];
+  if (status.status === "missing-spec" || status.status === "needs-sync") legs.push("spec");
+  if (status.evalStatus === "missing-eval" || status.evalStatus === "needs-sync") legs.push("eval");
+  return legs;
+}
+
+export function checkSyncSpec(args: { targetRoot: string; specPath?: string; evalCriteriaPath?: string }): SyncSpecStatus {
+  const targetRoot = path.resolve(args.targetRoot);
+  let targetStat: fs.Stats;
+  try {
+    targetStat = fs.statSync(targetRoot);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      status: "error",
+      specPath: null,
+      targetRoot,
+      specFreshness: emptySpecFreshness(),
+      codeFreshness: emptyCodeFreshness(),
+      ...notApplicableEval(),
+      reason: `targetRoot: unreadable target root: ${message}`,
+    };
+  }
+  if (!targetStat.isDirectory()) {
+    return {
+      status: "error",
+      specPath: null,
+      targetRoot,
+      specFreshness: emptySpecFreshness(),
+      codeFreshness: emptyCodeFreshness(),
+      ...notApplicableEval(),
+      reason: "targetRoot: target root is not a directory",
+    };
+  }
+
+  const specPath = locateSpec(targetRoot, args.specPath);
+  if (!specPath) {
+    const files = implementationFiles(targetRoot, null, locateEvalCriteria(targetRoot, args.evalCriteriaPath).path);
+    const newest = newestMtime(files);
+    const codeEffective = maxEpoch([gitEpochForPaths(targetRoot, files), newest.epoch]);
+    return {
+      status: "missing-spec",
+      specPath: null,
+      targetRoot,
+      specFreshness: emptySpecFreshness(),
+      codeFreshness: {
+        gitCommitEpoch: gitEpochForPaths(targetRoot, files),
+        fileMtimeEpoch: newest.epoch,
+        effectiveEpoch: codeEffective,
+        newestPath: newest.path,
+      },
+      ...evalLeg(targetRoot, args.evalCriteriaPath, codeEffective),
+      reason: "no agentspec.yaml found; derive spec from implementation",
+    };
+  }
+
+  const updated = parseUpdatedAt(specPath);
+  if (updated.error) {
+    return {
+      status: "error",
+      specPath,
+      targetRoot,
+      specFreshness: emptySpecFreshness(),
+      codeFreshness: emptyCodeFreshness(),
+      ...notApplicableEval(),
+      reason: updated.error,
+    };
+  }
+
+  const specGit = gitEpochForPaths(targetRoot, [specPath]);
+  const specMtime = fileMtimeEpoch(specPath);
+  const specFreshness = {
+    updatedAt: updated.updatedAt,
+    gitCommitEpoch: specGit,
+    fileMtimeEpoch: specMtime,
+    effectiveEpoch: maxEpoch([updated.epoch, specGit, specMtime]),
+  };
+
+  const evalLocated = locateEvalCriteria(targetRoot, args.evalCriteriaPath);
+  const files = implementationFiles(targetRoot, specPath, evalLocated.path);
+  const codeGit = gitEpochForPaths(targetRoot, files);
+  const codeMtime = newestMtime(files);
+  const codeFreshness = {
+    gitCommitEpoch: codeGit,
+    fileMtimeEpoch: codeMtime.epoch,
+    effectiveEpoch: maxEpoch([codeGit, codeMtime.epoch]),
+    newestPath: codeMtime.path,
+  };
+  const evalResult = evalLeg(targetRoot, args.evalCriteriaPath, codeFreshness.effectiveEpoch);
+
+  if (specFreshness.effectiveEpoch == null) {
+    return {
+      status: "error",
+      specPath,
+      targetRoot,
+      specFreshness,
+      codeFreshness,
+      ...evalResult,
+      reason: "specFreshness.effectiveEpoch: unable to compare spec freshness",
+    };
+  }
+
+  if (codeFreshness.effectiveEpoch != null && codeFreshness.effectiveEpoch > specFreshness.effectiveEpoch) {
+    return {
+      status: "needs-sync",
+      specPath,
+      targetRoot,
+      specFreshness,
+      codeFreshness,
+      ...evalResult,
+      reason: "implementation is newer than agentspec",
+    };
+  }
+
+  return {
+    status: "in-sync",
+    specPath,
+    targetRoot,
+    specFreshness,
+    codeFreshness,
+    ...evalResult,
+    reason: "agentspec is as fresh as implementation",
+  };
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = { json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") args.json = true;
+    else if (arg === "--spec") args.spec = argv[++i];
+    else if (arg === "--target") args.target = argv[++i];
+    else if (arg === "--eval-criteria") args.evalCriteria = argv[++i];
+    else if (arg === "--help" || arg === "-h") {
+      console.log("Usage: scripts/cli/run.sh scripts/sync-spec/check-sync-spec.ts --spec <agentspec.yaml?> --target <target-root> [--eval-criteria <path?>] [--json]");
+      process.exit(0);
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  if (!args.target) throw new Error("--target is required");
+  return args;
+}
+
+function formatSummary(status: SyncSpecStatus): string {
+  const lines = [
+    `[sync-spec] ${status.status}: ${status.reason}`,
+    `targetRoot: ${status.targetRoot}`,
+    `specPath: ${status.specPath ?? "<none>"}`,
+    `specFreshness: updatedAt=${status.specFreshness.updatedAt ?? "null"} git=${status.specFreshness.gitCommitEpoch ?? "null"} mtime=${status.specFreshness.fileMtimeEpoch ?? "null"} effective=${status.specFreshness.effectiveEpoch ?? "null"}`,
+    `codeFreshness: git=${status.codeFreshness.gitCommitEpoch ?? "null"} mtime=${status.codeFreshness.fileMtimeEpoch ?? "null"} effective=${status.codeFreshness.effectiveEpoch ?? "null"} newestPath=${status.codeFreshness.newestPath ?? "null"}`,
+    `evalStatus: ${status.evalStatus}  (eval leg — W2I5 triad)`,
+    `evalFreshness: path=${status.evalFreshness.path ?? "<none>"} updatedAt=${status.evalFreshness.updatedAt ?? "null"} git=${status.evalFreshness.gitCommitEpoch ?? "null"} mtime=${status.evalFreshness.fileMtimeEpoch ?? "null"} effective=${status.evalFreshness.effectiveEpoch ?? "null"}`,
+    `driftedLegs: ${driftedLegs(status).join("+") || "<none>"}`,
+  ];
+  return lines.join("\n");
+}
+
+export function runCli(argv: string[]): number {
+  let args: CliArgs;
+  try {
+    args = parseArgs(argv);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const status: SyncSpecStatus = {
+      status: "error",
+      specPath: null,
+      targetRoot: "",
+      specFreshness: emptySpecFreshness(),
+      codeFreshness: emptyCodeFreshness(),
+      ...notApplicableEval(),
+      reason: `args: ${reason}`,
+    };
+    console.error(JSON.stringify(status, null, 2));
+    return 1;
+  }
+  const status = checkSyncSpec({ targetRoot: args.target!, specPath: args.spec, evalCriteriaPath: args.evalCriteria });
+  const out = args.json ? JSON.stringify(status, null, 2) : formatSummary(status);
+  if (status.status === "error") console.error(out);
+  else console.log(out);
+  return status.status === "error" ? 1 : 0;
+}
+
+if (import.meta.main) process.exit(runCli(process.argv.slice(2)));

package/mutagent-builder/.claude/skills/mutagent-builder/scripts/verify/spec-impl-coverage.ts

@@ -0,0 +1,182 @@
+/**
+ * scripts/verify/spec-impl-coverage.ts
+ * The BUILD-FAITHFULNESS gate (PR-024) — assert every spec-declared code tool is implemented + tested.
+ * Type A — Pure core (computeCoverage, no I/O) + a thin guarded CLI. Mirrors validate-spec.ts.
+ *
+ * WHY: TDD proves the code that EXISTS passes; it is SILENT on whether all the code the SPEC requires
+ * exists (a dropped tool has no test, so nothing fails). A build is GREEN only when TDD passes AND
+ * this gate passes. The dogfood sim shipped a scaffold missing `collect-range` with 27 green tests —
+ * this gate makes that a STEER instead.
+ *
+ * CONVENTION: each implementing module carries `// @implements <tool-id>`; ≥1 test references that
+ * module (by basename or the same marker). The actor DECLARES the mapping in code; this script VERIFIES
+ * completeness against the spec; the Verifier RE-RUNS it (Context-Inversion — never trusts the actor).
+ *
+ * Usage: scripts/cli/run.sh scripts/verify/spec-impl-coverage.ts <agentspec.yaml> <scaffold-dir>
+ *   exit 0 = every code tool covered (+ no dangling job.backed_by refs)  → "[coverage] PASS"
+ *   exit 1 = at least one uncovered tool OR a dangling backed_by ref (a STEER)
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+/** One spec code-tool's coverage status. */
+export interface CoverageEntry {
+  id: string;
+  module: string | null;
+  test: string | null;
+  covered: boolean;
+  reason?: string;
+}
+
+export interface CoverageResult {
+  ok: boolean;
+  entries: CoverageEntry[];
+  /** job.backed_by refs (P2) that don't resolve to a declared code-tool id — a spec defect. */
+  danglingBackedBy: string[];
+}
+
+/** A scanned file. Pure inputs so the core is unit-testable without disk. */
+export interface ScannedFile {
+  path: string;
+  content: string;
+}
+
+/** `@implements <id>` marker matcher — id is treated literally (regex-escaped). */
+function implementsMarker(id: string): RegExp {
+  const esc = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`@implements\\s+${esc}(?:\\s|$)`, "m");
+}
+
+/**
+ * PURE core. For each declared code-tool id, require (a) a src file carrying `// @implements <id>`
+ * AND (b) ≥1 test file referencing that module (by basename) or carrying the same marker. Also flags
+ * job `backed_by` refs that don't resolve to a declared tool id. No I/O, never throws.
+ */
+export function computeCoverage(
+  toolIds: string[],
+  srcFiles: ScannedFile[],
+  testFiles: ScannedFile[],
+  backedByRefs: string[] = [],
+): CoverageResult {
+  const entries: CoverageEntry[] = [];
+  for (const id of toolIds) {
+    const re = implementsMarker(id);
+    const mod = srcFiles.find((f) => re.test(f.content)) ?? null;
+    let test: ScannedFile | null = null;
+    if (mod) {
+      const base = path.basename(mod.path).replace(/\.ts$/, "");
+      test =
+        testFiles.find((t) => t.content.includes(base) || re.test(t.content)) ?? null;
+    }
+    const covered = Boolean(mod) && Boolean(test);
+    entries.push({
+      id,
+      module: mod ? mod.path : null,
+      test: test ? test.path : null,
+      covered,
+      reason: !mod
+        ? `no module carries \`// @implements ${id}\``
+        : !test
+          ? `module ${path.basename(mod.path)} has no test referencing it`
+          : undefined,
+    });
+  }
+  const declared = new Set(toolIds);
+  const danglingBackedBy = [...new Set(backedByRefs)].filter((r) => !declared.has(r));
+  const ok = entries.every((e) => e.covered) && danglingBackedBy.length === 0;
+  return { ok, entries, danglingBackedBy };
+}
+
+/** Recursively collect .ts files under a dir (excluding node_modules / dotdirs). */
+function walkTs(dir: string): ScannedFile[] {
+  const out: ScannedFile[] = [];
+  const walk = (d: string): void => {
+    let ents: fs.Dirent[];
+    try {
+      ents = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of ents) {
+      if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile() && e.name.endsWith(".ts"))
+        out.push({ path: full, content: fs.readFileSync(full, "utf-8") });
+    }
+  };
+  walk(path.resolve(dir));
+  return out;
+}
+
+/** Read a spec + scaffold from disk and compute coverage. Throws only on an unreadable spec file. */
+export function coverageForScaffold(
+  specPath: string,
+  scaffoldDir: string,
+): CoverageResult {
+  const spec = parseYaml(fs.readFileSync(path.resolve(specPath), "utf-8")) as Record<
+    string,
+    unknown
+  >;
+  const def = (spec?.definition ?? {}) as Record<string, unknown>;
+  const tools = (def?.tools ?? {}) as Record<string, unknown>;
+  const codeTools = Array.isArray(tools?.code) ? (tools.code as { id?: string }[]) : [];
+  const toolIds = codeTools.map((t) => t?.id).filter((x): x is string => Boolean(x));
+  const jobs = Array.isArray(def?.jobs_to_be_done)
+    ? (def.jobs_to_be_done as { backed_by?: unknown }[])
+    : [];
+  const backedBy = jobs.flatMap((j) =>
+    Array.isArray(j?.backed_by) ? (j.backed_by as string[]) : [],
+  );
+  const all = walkTs(scaffoldDir);
+  const srcFiles = all.filter((f) => !/\.test\.ts$/.test(f.path));
+  const testFiles = all.filter((f) => /\.test\.ts$/.test(f.path));
+  return computeCoverage(toolIds, srcFiles, testFiles, backedBy);
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────
+function runCli(argv: string[]): number {
+  const args = argv.slice(2).filter((a) => !a.startsWith("--"));
+  const [specPath, scaffoldDir] = args;
+  if (!specPath || !scaffoldDir) {
+    process.stderr.write(
+      "Usage: scripts/cli/run.sh scripts/verify/spec-impl-coverage.ts <agentspec.yaml> <scaffold-dir>\n" +
+        "Asserts every definition.tools.code[].id has an `// @implements <id>` module + a test.\n" +
+        "Exit 0 = all covered; exit 1 = an uncovered tool or a dangling backed_by ref (STEER).\n",
+    );
+    return 1;
+  }
+  let result: CoverageResult;
+  try {
+    result = coverageForScaffold(specPath, scaffoldDir);
+  } catch (err) {
+    process.stderr.write(`Error reading ${specPath}: ${String(err)}\n`);
+    return 1;
+  }
+  console.info("tool-id            module                          test                 covered");
+  console.info("─────────────────  ──────────────────────────────  ───────────────────  ───────");
+  for (const e of result.entries) {
+    const mod = e.module ? path.basename(e.module) : "—";
+    const tst = e.test ? path.basename(e.test) : "—";
+    console.info(
+      `${e.id.padEnd(17)}  ${mod.padEnd(30)}  ${tst.padEnd(19)}  ${e.covered ? "✓" : "✗"}` +
+        (e.reason ? `\n  └─ ${e.reason}` : ""),
+    );
+  }
+  for (const d of result.danglingBackedBy)
+    console.info(`✗ dangling job.backed_by → "${d}" is not a declared code tool`);
+  if (result.ok) {
+    console.info(`[coverage] PASS — all ${result.entries.length} code tool(s) implemented + tested.`);
+    return 0;
+  }
+  const missing = result.entries.filter((e) => !e.covered).map((e) => e.id);
+  console.info(
+    `[coverage] STEER — uncovered: ${missing.join(", ") || "(none)"}` +
+      (result.danglingBackedBy.length ? ` · dangling: ${result.danglingBackedBy.join(", ")}` : ""),
+  );
+  return 1;
+}
+
+if (import.meta.main) process.exit(runCli(process.argv));