agent-doc-system 0.0.0-stage → 1.1.0

package/bin/agentdoc.mjs

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+// agentdoc — portable documentation & software-catalog system.
+//
+// The command list lives in bin/usage.txt and is printed from there, so this
+// header, `--help` and the shipped file cannot drift into three different
+// claims about what the tool does. The flags each command accepts live in
+// bin/commands.mjs, which drives both parsing and `agentdoc <command> --help`.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AgentDocError, CODES } from "../core/codes.mjs";
+import { compile, sha256Hex } from "../core/compile.mjs";
+import { Repo } from "../core/fsx.mjs";
+import { assertFresh, readGraph, COMPILER_VERSION, GRAPH_SCHEMA_VERSION, COMPILER_NAME } from "../core/graph.mjs";
+import { queryContext, renderContext } from "../core/query.mjs";
+import { impact } from "../core/impact.mjs";
+import { audit, scaffoldProposal } from "../core/audit.mjs";
+import { observationFreshness, stalenessDiagnostics } from "../core/observations.mjs";
+import { assertNoSecretsInText } from "../core/secrets.mjs";
+import { installTemplates } from "../core/scaffold.mjs";
+import { COMMANDS, flagsOf, parseArgs, commandHelp, UsageError } from "./commands.mjs";
+import { loadSchemaBundle, loadConfig } from "../core/descriptors.mjs";
+import { execFileSync } from "node:child_process";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.join(HERE, "..");
+const VERSION = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+const MIN_NODE_MAJOR = 22;
+// Commands are run from wherever the agent happens to be. Walk up until the
+// configuration is found, so `agentdoc query src/foo.ts` works from a
+// subdirectory instead of failing with a misleading missing-file error.
+function findRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 24; i++) {
+    if (fs.existsSync(path.join(dir, "agentdoc", "agentdoc.config.yaml"))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return start;
+}
+
+const ROOT = findRoot(process.cwd());
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+// Flags are declared per command in bin/commands.mjs. An undeclared flag is a
+// usage error (exit 2), so a typo in a gate flag can never pass for the gate.
+let parsed = { flags: new Map(), positional: [] };
+if (Object.prototype.hasOwnProperty.call(COMMANDS, cmd)) {
+  try {
+    parsed = parseArgs(cmd, argv.slice(1));
+  } catch (e) {
+    if (!(e instanceof UsageError)) throw e;
+    console.error(e.message);
+    process.exit(2);
+  }
+}
+const positional = parsed.positional;
+// The only way to read a flag. Reading one the command does not declare is a
+// defect in this file, not user input: it would be a flag `--help` never shows.
+function opt(name) {
+  if (!Object.prototype.hasOwnProperty.call(flagsOf(cmd), name)) {
+    throw new Error("flag --" + name + " is read by '" + cmd + "' but not declared for it in bin/commands.mjs");
+  }
+  return parsed.flags.has(name) ? parsed.flags.get(name) : null;
+}
+
+function fail(errors, stats) {
+  for (const e of errors) console.error("ERROR " + (e.format ? e.format() : e.code + ": " + e.message));
+  if (stats) console.error("agentdoc: " + JSON.stringify(stats));
+  process.exit(1);
+}
+
+function usage(exitCode) {
+  const text = fs.readFileSync(path.join(HERE, "usage.txt"), "utf8");
+  (exitCode === 0 ? process.stdout : process.stderr).write(text);
+  process.exit(exitCode);
+}
+
+function printDiagnostics(res) {
+  for (const d of res.diagnostics || []) {
+    const prefix = d.severity === "error" ? "ERROR " : d.acceptance ? "WARN ACCEPTED " : "WARN  ";
+    console.log(prefix + d.code + ": " + d.message);
+    if (d.acceptance) console.log("  " + d.acceptance.classification + ": " + d.acceptance.reason);
+  }
+}
+
+function gateObservationFreshness(res) {
+  // Time-dependent gates run before artifact gates. A committed graph can be
+  // stale for many reasons; when the cause is an observation that has aged out
+  // of its promise, saying "rebuild the graph" sends the reader down the wrong
+  // path entirely.
+  const abs = path.join(ROOT, res.graphPath);
+  if (!fs.existsSync(abs)) return null;
+  const { graph } = readGraph(res.repo, res.graphPath);
+  const fresh = observationFreshness(graph.observations || [], new Date());
+  const stale = stalenessDiagnostics(fresh);
+  if (!stale.length) return fresh;
+  if (!opt("allow-stale-observations")) {
+    for (const d of stale) console.error("ERROR " + d.code + ": " + d.message);
+    process.exit(1);
+  }
+  // Staleness was explicitly allowed through. This is where a rule's
+  // degradeOnStale is applied — at gate time, never at compile time, so a
+  // compile stays a pure function of the checkout. `conflict` keeps the
+  // election and warns; `unresolved` refuses to stand on a stale observation.
+  // Match the elected assertion to the stale observation *set* by capturedAt
+  // + environment — capturedAt alone can collide across sets.
+  const staleSets = new Set(fresh.filter((f) => f.stale).map((f) => f.capturedAt + "\u0000" + f.environment));
+  const assertionById = new Map((graph.assertions || []).map((a) => [a.id, a]));
+  const rules = new Map((((res.cfg || {}).authority || {}).rules || []).map((r) => [r.id, r]));
+  const degraded = [];
+  for (const c of graph.conflicts || []) {
+    if (c.status !== "resolved" || !c.election || !c.election.electedAssertionId) continue;
+    const rule = rules.get(c.election.ruleId);
+    if (!rule || !rule.degradeOnStale) continue;
+    const elected = assertionById.get(c.election.electedAssertionId);
+    const obs = elected && elected.observed;
+    if (!obs || !obs.at || !staleSets.has(obs.at + "\u0000" + obs.environment)) continue;
+    if (rule.degradeOnStale === "unresolved") {
+      degraded.push(
+        c.subject + " " + c.key + " — the elected observation (" + obs.at + ") is past its maxAgeDays " +
+        "and authority rule " + rule.id + " requires the election to degrade to unresolved"
+      );
+    } else {
+      console.error(
+        "WARN  " + CODES.ELECTION_STALE + ": " + c.subject + " " + c.key +
+        " — the elected observation (" + obs.at + ") is past its maxAgeDays; authority rule " +
+        rule.id + " keeps the election"
+      );
+    }
+  }
+  if (degraded.length) {
+    for (const m of degraded) console.error("ERROR " + CODES.CONFLICT_UNRESOLVED + ": " + m);
+    process.exit(1);
+  }
+  return fresh;
+}
+
+function requireFresh(res, fresh) {
+  const abs = path.join(ROOT, res.graphPath);
+  if (!fs.existsSync(abs)) {
+    fail([new AgentDocError(CODES.GRAPH_MISSING, "no compiled graph at " + res.graphPath + " — run `agentdoc compile`")]);
+  }
+  const { graph, text } = readGraph(res.repo, res.graphPath);
+  try {
+    assertFresh(graph, {
+      inputHash: res.stats.inputHash,
+      dirty: res.stats.dirty,
+      compilerVersion: COMPILER_VERSION,
+      schemaVersion: GRAPH_SCHEMA_VERSION,
+    });
+  } catch (e) {
+    fail([e]);
+  }
+  if (graph.source.dirty && opt("require-clean")) {
+    fail([new AgentDocError(
+      CODES.DIRTY_SOURCE,
+      "catalog inputs differ from HEAD (" + res.stats.commit + ") — CI/publish evidence requires a clean source; commit the change and rebuild"
+    )], res.stats);
+  }
+  // `fresh` is normally precomputed by the caller — gateObservationFreshness
+  // also evaluates election degradation, so calling it twice would print the
+  // same staleness warning twice. The fallback keeps a forgotten call-site safe.
+  return { graph, text, fresh: fresh === undefined ? (gateObservationFreshness(res) || []) : fresh };
+}
+
+function out(obj, asJson) {
+  const text = asJson ? JSON.stringify(obj, null, 2) + "\n" : null;
+  if (text) assertNoSecretsInText(text, "output");
+  process.stdout.write(text || obj + "\n");
+}
+
+try {
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    console.log("agentdoc " + VERSION);
+    process.exit(0);
+  }
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    // `agentdoc help <command>` is the same as `agentdoc <command> --help`.
+    if (Object.prototype.hasOwnProperty.call(COMMANDS, argv[1])) {
+      process.stdout.write(commandHelp(argv[1]));
+      process.exit(0);
+    }
+    usage(0);
+  }
+  if (Object.prototype.hasOwnProperty.call(COMMANDS, cmd) && opt("help")) {
+    process.stdout.write(commandHelp(cmd));
+    process.exit(0);
+  }
+  if (cmd === "validate") {
+    const res = compile(ROOT);
+    printDiagnostics(res);
+    if (res.errors.length) fail(res.errors, res.stats);
+    console.log("agentdoc validate: PASS " + JSON.stringify(res.stats));
+  } else if (cmd === "compile") {
+    const res = compile(ROOT);
+    printDiagnostics(res);
+    if (res.errors.length) fail(res.errors, res.stats);
+    if (opt("require-clean") && res.stats.dirty) {
+      fail([new AgentDocError(CODES.DIRTY_SOURCE, "catalog inputs differ from HEAD — commit the change and rebuild")], res.stats);
+    }
+    fs.mkdirSync(path.dirname(path.join(ROOT, res.graphPath)), { recursive: true });
+    const tmp = path.join(ROOT, res.graphPath) + ".tmp-" + process.pid;
+    fs.writeFileSync(tmp, res.serialized);
+    fs.renameSync(tmp, path.join(ROOT, res.graphPath));
+    console.log("agentdoc compile: PASS " + JSON.stringify(res.stats));
+    console.log("graph: " + res.graphPath);
+  } else if (cmd === "check") {
+    const res = compile(ROOT);
+    printDiagnostics(res);
+    if (res.errors.length) fail(res.errors, res.stats);
+    const preFresh = gateObservationFreshness(res);
+    const { graph, text, fresh } = requireFresh(res, preFresh);
+    // `source.commit` records which checkout produced the graph, and a checkout
+    // without VCS — an extracted archive, a vendored dependency — compiles to
+    // `0000000`. That is a difference in provenance, not in content, and failing
+    // on it would make a committed graph unusable in exactly the situation it
+    // is most needed: shipped as a file, with no history. Everything else must
+    // still match byte for byte.
+    const withoutCommit = (t) => t.replace(/^(\s*)"commit": "[0-9a-f]*",$/m, '$1"commit": "<provenance>",');
+    if (withoutCommit(text) !== withoutCommit(res.serialized)) {
+      fail([new AgentDocError(
+        CODES.STALE_GRAPH,
+        "compiled graph differs from a fresh deterministic compile — commit the descriptor or authority change and rebuild"
+      )]);
+    }
+    const gj = JSON.stringify(graph, null, 2) + "\n";
+    if (gj !== text) {
+      fail([new AgentDocError(CODES.STALE_GRAPH, "compiled graph is not canonically serialized — rebuild the graph")]);
+    }
+    // `--strict` is the migration gate: the graph is current *and* nothing is
+    // left for a human. Every warning is either accepted with pinned evidence
+    // or the gate fails, so a normative section nobody reviewed or a
+    // requirement nothing proves cannot ride along in a green check. Opt-in, so
+    // plain `check` keeps meaning "the committed graph is fresh".
+    if (opt("strict")) {
+      const open = (res.diagnostics || []).filter((d) => d.severity === "warning" && !d.acceptance);
+      if (open.length) {
+        fail(
+          open.map((d) => new AgentDocError(d.code, (d.subject && !d.message.includes(d.subject) ? d.subject + ": " : "") + d.message)),
+          { ...res.stats, strict: true }
+        );
+      }
+    }
+    console.log("agentdoc check: PASS " + JSON.stringify({ ...res.stats, observationFreshness: fresh.length, ...(opt("strict") ? { strict: true } : {}) }));
+  } else if (cmd === "query") {
+    const needle = positional[0];
+    if (!needle) { console.error("usage: agentdoc query <repo-path|entity-ref> [--json] [--md] [--budget relations=10,verification=4]"); process.exit(2); }
+    const res = compile(ROOT);
+    if (res.errors.length) fail(res.errors, res.stats);
+    // Time-dependent gates first, for the same reason as `check`: a stale
+    // observation is a different problem from a stale graph and sends the reader
+    // somewhere else entirely.
+    const preFresh = gateObservationFreshness(res);
+    const { graph } = requireFresh(res, preFresh);
+    // `--budget` exists because the default budgets are generous enough that a
+    // focused query never truncates, which makes the truncation contract
+    // untestable and unreachable from the CLI. An agent working in a tight
+    // context needs to be able to say so.
+    let budget = {};
+    const raw = opt("budget");
+    if (raw === true || raw === "") {
+      console.error("usage: --budget section=limit,... (limits are positive integers)");
+      process.exit(2);
+    }
+    if (raw) {
+      for (const pair of raw.split(",")) {
+        const [k, v] = pair.split("=");
+        if (!k || !/^\d+$/.test(String(v))) {
+          console.error("usage: --budget section=limit,... (limits are positive integers)");
+          process.exit(2);
+        }
+        budget[k.trim()] = Number(v);
+      }
+    }
+    const ctx = queryContext(graph, needle, { budget });
+    if (opt("md")) out(renderContext(ctx));
+    else if (opt("json")) out(ctx, true);
+    else out(renderContext(ctx));
+  } else if (cmd === "impact") {
+    // Impact answers a question about the working tree, so it compiles in
+    // memory rather than reading the committed graph. Refusing a stale graph
+    // would be right for `query` (which feeds a prompt) and wrong here: the
+    // whole point of impact is to run *before* you rebuild.
+    const res = compile(ROOT);
+    if (res.errors.length) fail(res.errors, res.stats);
+    const graph = res.graph;
+    const fromRef = opt("diff") || opt("from");
+    let paths = positional;
+    if (fromRef && fromRef !== true) {
+      if (!res.repo.hasGit()) {
+        console.error("agentdoc impact --diff requires a git repository; this checkout has no VCS");
+        process.exit(2);
+      }
+      paths = res.repo.diffPaths(fromRef);
+      if (paths === null) {
+        console.error("cannot resolve diff ref '" + fromRef + "' — is it a valid commit, branch or range?");
+        process.exit(2);
+      }
+      if (!paths.length) {
+        console.error("no changed files between " + fromRef + " and HEAD");
+        process.exit(2);
+      }
+    }
+    if (!paths.length) {
+      console.error("usage: agentdoc impact <path...> | agentdoc impact --diff <git-ref>");
+      process.exit(2);
+    }
+    out(impact(graph, paths), true);
+  } else if (cmd === "audit") {
+    const res = compile(ROOT);
+    if (!res.graph) {
+      // An audit must work on a repository that cannot compile yet; report the
+      // compilation failures as part of the audit rather than aborting.
+      const report = {
+        compileErrors: res.errors.map((e) => ({ code: e.code, message: e.message, path: e.path || null, ref: e.ref || null })),
+        stats: res.stats,
+      };
+      out(report, true);
+      process.exit(0);
+    }
+    const report = audit(res.repo, res.cfg, res);
+    report.scaffold = scaffoldProposal(res.repo, res.cfg, report);
+    out(report, true);
+  } else if (cmd === "scaffold") {
+    const res = compile(ROOT);
+    const write = opt("write");
+    // Scaffolding is how a repository reaches a compiling state: requiring the
+    // compile to succeed first deadlocks CREATE on every repository whose units
+    // are discovered by adapters (go.work, pnpm-workspace, supplementalRoots)
+    // rather than already carrying descriptors. When a usable configuration
+    // exists, write what can be proven and report what still blocks the compile.
+    if (!res.cfg) {
+      out({
+        scaffolded: [],
+        blocked: res.errors.map((e) => ({ code: e.code, message: e.message })),
+        note: "the repository cannot compile yet; install the configuration first with `agentdoc init`",
+      }, true);
+      process.exit(1);
+    }
+    const report = res.graph ? audit(res.repo, res.cfg, res) : null;
+    const proposal = report ? scaffoldProposal(res.repo, res.cfg, report) : null;
+    const result = installTemplates(res.repo, res.cfg, {
+      write: Boolean(write),
+      eligible: res.discovery && res.discovery.eligible,
+    });
+    out({
+      ...result,
+      ...(proposal ? { proposal } : {}),
+      ...(res.errors.length
+        ? { blocked: res.errors.map((e) => ({ code: e.code, message: e.message })) }
+        : {}),
+    }, true);
+  } else if (cmd === "init") {
+    const result = installTemplates(null, null, { write: true, root: ROOT, force: opt("force") });
+    out(result, true);
+  } else if (cmd === "eval") {
+    const which = positional[0] || "routing";
+    if (which !== "routing") { console.error("usage: agentdoc eval routing [--json]"); process.exit(2); }
+    // The harness ships, but it is loaded lazily so a trimmed or damaged
+    // installation cannot make every other command fail on a module the user
+    // never asked for.
+    let runRoutingEval;
+    try {
+      ({ runRoutingEval } = await import("../evals/harness.mjs"));
+    } catch (e) {
+      if (e && e.code === "ERR_MODULE_NOT_FOUND") {
+        console.error("agentdoc eval: the evaluation harness is missing from this installation — reinstall the agentdoc CLI, or run it from a source checkout");
+        process.exit(1);
+      }
+      throw e;
+    }
+    const report = runRoutingEval(ROOT, { json: opt("json") });
+    if (opt("json")) { out(report, true); process.exit(report.verdict === "FAIL" ? 1 : 0); }
+    else {
+      console.log(JSON.stringify(report.metrics, null, 2));
+      console.log("thresholds: " + JSON.stringify(report.thresholds));
+      console.log("verdict: " + report.verdict + " (" + report.failures.join("; ") + ")");
+    }
+    if (report.verdict === "FAIL") process.exit(1);
+  } else if (cmd === "pin-evidence") {
+    // Reviewed overrides pin their evidence by content hash, and those digests
+    // are re-verified on every compile. That is only workable if an author can
+    // obtain the current digest without computing SHA-256 by hand — otherwise
+    // the discipline quietly becomes "delete the override", which is worse
+    // than not requiring it.
+    // Read the configuration directly rather than through `compile`: a stale
+    // digest is precisely the condition this command exists to report, and it
+    // must be reportable when `compile` refuses to run.
+    const repo = new Repo(ROOT);
+    const cfg = loadConfig(repo, loadSchemaBundle().bundle);
+    const results = [];
+    for (const o of cfg.reviewedOverrides || []) {
+      for (const ev of o.evidence || []) {
+        const p = path.join(ROOT, ev.path);
+        if (!fs.existsSync(p)) {
+          results.push({ subject: o.subject, path: ev.path, current: null, pinned: ev.sha256, status: "MISSING" });
+          continue;
+        }
+        const current = sha256Hex(fs.readFileSync(p));
+        results.push({
+          subject: o.subject, path: ev.path, current,
+          pinned: ev.sha256,
+          status: current === ev.sha256 ? "CURRENT" : "STALE",
+        });
+      }
+    }
+    if (opt("json")) { out({ evidence: results }, true); }
+    else {
+      for (const r of results) {
+        console.log(r.status.padEnd(8) + " " + r.path);
+        if (r.status === "STALE") {
+          console.log("         pinned:  " + r.pinned);
+          console.log("         current: " + r.current + "   <- update the digest after reviewing the change");
+        }
+      }
+      console.log(results.length + " evidence entries across " + (cfg.reviewedOverrides || []).length + " reviewed overrides");
+    }
+    if (results.some((r) => r.status !== "CURRENT")) process.exit(1);
+  } else if (cmd === "doctor") {
+    // Two scopes, kept explicit: `doctor` is a machine check — is this
+    // installation of the CLI itself healthy — and never fails because a
+    // project happens not to be configured yet. `doctor --project` adds the
+    // project checks and fails on those too.
+    const major = Number(process.versions.node.split(".")[0]);
+    const machine = {
+      agentdoc: VERSION,
+      node: process.version,
+      nodeSupported: major >= MIN_NODE_MAJOR,
+      nodeRequired: ">=" + MIN_NODE_MAJOR,
+      compiler: COMPILER_NAME + "@" + COMPILER_VERSION,
+      graphSchema: GRAPH_SCHEMA_VERSION,
+      installRoot: PACKAGE_ROOT,
+      schemaBundle: null,
+      gitAvailable: false,
+      externalRuntimeDependencies: [],
+    };
+    try {
+      const { versionInputs } = loadSchemaBundle();
+      machine.schemaBundle = { ok: true, schemas: versionInputs.length };
+    } catch (e) {
+      machine.schemaBundle = { ok: false, error: (e.code ? e.code + ": " : "") + e.message };
+    }
+    try {
+      execFileSync("git", ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+      machine.gitAvailable = true;
+    } catch {
+      machine.gitAvailable = false;
+    }
+    const machineOk = machine.nodeSupported && machine.schemaBundle.ok;
+
+    const report = { scope: "machine", ok: machineOk, machine };
+    if (opt("project")) {
+      const configFound = fs.existsSync(path.join(ROOT, "agentdoc", "agentdoc.config.yaml"));
+      const project = {
+        root: ROOT,
+        configurationFound: configFound,
+        configPath: "agentdoc/agentdoc.config.yaml",
+        writable: null,
+        graphPresent: false,
+      };
+      try {
+        fs.accessSync(ROOT, fs.constants.W_OK);
+        project.writable = true;
+      } catch {
+        project.writable = false;
+      }
+      if (configFound) {
+        try {
+          const cfg = loadConfig(new Repo(ROOT), loadSchemaBundle().bundle);
+          project.graphPath = cfg.output?.graph || ".agentdoc/graph.json";
+          project.graphPresent = fs.existsSync(path.join(ROOT, project.graphPath));
+        } catch (e) {
+          project.configError = (e.code ? e.code + ": " : "") + e.message;
+        }
+      }
+      report.scope = "machine+project";
+      report.project = project;
+      report.ok = machineOk && configFound && project.writable === true && !project.configError;
+    }
+    out(report, true);
+    if (!report.ok) process.exit(1);
+  } else {
+    usage(2);
+  }
+} catch (e) {
+  if (e instanceof AgentDocError) {
+    console.error("ERROR " + e.format());
+    process.exit(1);
+  }
+  console.error("agentdoc internal error: " + (e && e.stack ? e.stack : String(e)));
+  process.exit(1);
+}

package/bin/commands.mjs

@@ -0,0 +1,169 @@
+// Command and flag declarations.
+//
+// One table drives three things: which flags a command accepts, how they are
+// parsed, and what `agentdoc <command> --help` prints. Parsing and help read
+// the same rows, so they cannot drift. A flag that is not declared for the
+// command it is given to is a usage error, never silently ignored: a
+// misspelled gate flag (`check --strcit`) must not turn into a green,
+// non-strict gate.
+
+const JSON_FLAG = { json: { desc: "print the machine-readable report" } };
+// Commands whose output is always JSON accept --json too, as a no-op, so a
+// script that says what it expects is not rejected for being explicit.
+const JSON_ALWAYS = { json: { desc: "accepted for explicitness; the output is always JSON" } };
+
+export const COMMANDS = {
+  init: {
+    synopsis: "agentdoc init [--force]",
+    summary: "write a configuration and documentation skeleton",
+    flags: { force: { desc: "overwrite files that already exist" }, ...JSON_ALWAYS },
+  },
+  audit: {
+    synopsis: "agentdoc audit",
+    summary: "inventory the repository and classify every fact (JSON report)",
+    flags: { ...JSON_ALWAYS },
+  },
+  scaffold: {
+    synopsis: "agentdoc scaffold [--write]",
+    summary: "generate a CREATE-mode skeleton from the audit (dry run by default)",
+    flags: { write: { desc: "write the proposed files instead of listing them" }, ...JSON_ALWAYS },
+  },
+  validate: {
+    synopsis: "agentdoc validate",
+    summary: "sources, schemas and semantic checks",
+    flags: {},
+  },
+  compile: {
+    synopsis: "agentdoc compile [--require-clean]",
+    summary: "deterministic graph build (atomic write)",
+    flags: { "require-clean": { desc: "refuse when catalog inputs differ from HEAD" } },
+  },
+  check: {
+    synopsis: "agentdoc check [--strict] [--require-clean] [--allow-stale-observations]",
+    summary: "freshness, determinism and gate check",
+    flags: {
+      strict: { desc: "also fail on every warning not accepted in warningAcceptances (the end-of-MIGRATE gate)" },
+      "require-clean": { desc: "refuse a graph built from inputs that differ from HEAD" },
+      "allow-stale-observations": { desc: "let observations past maxAgeDays through, applying each rule's degradeOnStale" },
+    },
+  },
+  query: {
+    synopsis: "agentdoc query <path|ref> [--md] [--json] [--budget section=n,...]",
+    summary: "route minimal context for a task",
+    flags: {
+      md: { desc: "compact markdown context (the default)" },
+      ...JSON_FLAG,
+      budget: { value: "section=n,...", desc: "cap sections, e.g. relations=10,verification=4; truncation is reported" },
+      "require-clean": { desc: "refuse a graph built from inputs that differ from HEAD" },
+      "allow-stale-observations": { desc: "let observations past maxAgeDays through, applying each rule's degradeOnStale" },
+    },
+  },
+  impact: {
+    synopsis: "agentdoc impact <paths...> | agentdoc impact --diff <git-ref>",
+    summary: "what a change forces you to keep consistent",
+    flags: {
+      diff: { value: "git-ref", desc: "use the files changed since <git-ref> instead of paths" },
+      from: { value: "git-ref", desc: "alias of --diff" },
+      ...JSON_ALWAYS,
+    },
+  },
+  eval: {
+    synopsis: "agentdoc eval routing [--json]",
+    summary: "agent-routing evaluation against registered scenarios (SKIP when the repo has none)",
+    flags: { ...JSON_FLAG },
+  },
+  "pin-evidence": {
+    synopsis: "agentdoc pin-evidence [--json]",
+    summary: "verify digests pinned by reviewed overrides",
+    flags: { ...JSON_FLAG },
+  },
+  doctor: {
+    synopsis: "agentdoc doctor [--project]",
+    summary: "machine self-check: is this CLI install healthy",
+    flags: { project: { desc: "also check the current project's catalog health" }, ...JSON_ALWAYS },
+  },
+};
+
+// Accepted by every command.
+const COMMON_FLAGS = { help: { desc: "show this help" } };
+
+export function flagsOf(cmd) {
+  return { ...(COMMANDS[cmd] ? COMMANDS[cmd].flags : {}), ...COMMON_FLAGS };
+}
+
+export class UsageError extends Error {}
+
+// Parse argv (without the command) against the command's declaration.
+// Returns { flags: Map(name -> true|string), positional }.
+export function parseArgs(cmd, args) {
+  const declared = flagsOf(cmd);
+  const flags = new Map();
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "-h") { flags.set("help", true); continue; }
+    if (!a.startsWith("--")) { positional.push(a); continue; }
+    const eq = a.indexOf("=");
+    const name = a.slice(2, eq < 0 ? undefined : eq);
+    const spec = declared[name];
+    if (!spec) throw new UsageError(unknownFlagMessage(cmd, name));
+    if (!spec.value) {
+      if (eq >= 0) throw new UsageError("agentdoc " + cmd + ": --" + name + " does not take a value");
+      flags.set(name, true);
+      continue;
+    }
+    let v = eq >= 0 ? a.slice(eq + 1) : args[i + 1];
+    if (eq < 0) {
+      if (v === undefined || v.startsWith("--")) v = "";
+      else i++;
+    }
+    if (!v) throw new UsageError("agentdoc " + cmd + ": --" + name + " requires a value (" + spec.value + ")");
+    flags.set(name, v);
+  }
+  return { flags, positional };
+}
+
+function unknownFlagMessage(cmd, name) {
+  const own = Object.keys(flagsOf(cmd));
+  const near = own
+    .map((f) => [f, distance(f, name)])
+    .filter(([f, d]) => d <= Math.max(1, Math.floor(f.length / 3)))
+    .sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1))[0];
+  const elsewhere = Object.keys(COMMANDS).filter((c) => c !== cmd && COMMANDS[c].flags[name]);
+  let hint = "";
+  if (near) hint = " (did you mean --" + near[0] + "?)";
+  else if (elsewhere.length) hint = " (--" + name + " is accepted by: " + elsewhere.join(", ") + ")";
+  return "agentdoc " + cmd + ": unknown flag --" + name + hint +
+    "\nrun `agentdoc " + cmd + " --help` for the flags this command accepts";
+}
+
+function distance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      // Adjacent transposition: `strcit` is one slip away from `strict`.
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+export function commandHelp(cmd) {
+  const c = COMMANDS[cmd];
+  const flags = flagsOf(cmd);
+  const rows = Object.entries(flags).map(([name, spec]) => ["--" + name + (spec.value ? " <" + spec.value + ">" : ""), spec.desc]);
+  const width = Math.max(...rows.map((r) => r[0].length));
+  return [
+    "usage: " + c.synopsis,
+    "",
+    c.summary,
+    "",
+    "flags:",
+    ...rows.map(([f, d]) => "  " + f.padEnd(width) + "  " + d),
+    "",
+    "Exit codes: 0 ok, 1 failure, 2 usage.",
+    "",
+  ].join("\n");
+}