agent-doc-system 1.0.0 → 1.1.0

package/bin/agentdoc.mjs

@@ -3,7 +3,8 @@
 //
 // 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.
+// 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";
@@ -17,6 +18,7 @@ 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";
 
@@ -41,36 +43,27 @@ function findRoot(start) {
 const ROOT = findRoot(process.cwd());
 const argv = process.argv.slice(2);
 const cmd = argv[0];
-// Flags that consume the next token as a value. Anything else is boolean; a
-// `--flag value` pair must not leak the value into `positional`
-// (`agentdoc query --budget relations=10 svc/api` must query svc/api).
-const VALUE_FLAGS = new Set(["budget", "diff", "from"]);
-const flags = new Set();
-const positional = [];
-for (let i = 1; i < argv.length; i++) {
-  const a = argv[i];
-  if (a.startsWith("--")) {
-    const name = a.replace(/^--/, "").split("=")[0];
-    if (a.includes("=") && !VALUE_FLAGS.has(name)) {
-      console.error("agentdoc: --" + name + " does not take a value");
-      process.exit(2);
-    }
-    flags.add(name);
-    if (!a.includes("=") && VALUE_FLAGS.has(name) && argv[i + 1] && !argv[i + 1].startsWith("--")) i++;
-    continue;
+// 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);
   }
-  positional.push(a);
 }
-const flag = (name, dflt = null) => {
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--" + name) {
-      const next = argv[i + 1];
-      return next && !next.startsWith("--") ? next : true;
-    }
-    if (argv[i].startsWith("--" + name + "=")) return argv[i].slice(name.length + 3);
+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 dflt;
-};
+  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));
@@ -103,7 +96,7 @@ function gateObservationFreshness(res) {
   const fresh = observationFreshness(graph.observations || [], new Date());
   const stale = stalenessDiagnostics(fresh);
   if (!stale.length) return fresh;
-  if (!flags.has("allow-stale-observations")) {
+  if (!opt("allow-stale-observations")) {
     for (const d of stale) console.error("ERROR " + d.code + ": " + d.message);
     process.exit(1);
   }
@@ -160,7 +153,7 @@ function requireFresh(res, fresh) {
   } catch (e) {
     fail([e]);
   }
-  if (graph.source.dirty && (flags.has("require-clean") || flag("require-clean"))) {
+  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"
@@ -183,9 +176,18 @@ try {
     console.log("agentdoc " + VERSION);
     process.exit(0);
   }
-  if (cmd === "--help" || cmd === "-h" || cmd === "help" || flags.has("help") || argv.includes("-h")) {
+  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);
@@ -195,7 +197,7 @@ try {
     const res = compile(ROOT);
     printDiagnostics(res);
     if (res.errors.length) fail(res.errors, res.stats);
-    if ((flags.has("require-clean") || flag("require-clean")) && res.stats.dirty) {
+    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 });
@@ -227,7 +229,21 @@ try {
     if (gj !== text) {
       fail([new AgentDocError(CODES.STALE_GRAPH, "compiled graph is not canonically serialized — rebuild the graph")]);
     }
-    console.log("agentdoc check: PASS " + JSON.stringify({ ...res.stats, observationFreshness: fresh.length }));
+    // `--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); }
@@ -243,7 +259,7 @@ try {
     // untestable and unreachable from the CLI. An agent working in a tight
     // context needs to be able to say so.
     let budget = {};
-    const raw = flag("budget");
+    const raw = opt("budget");
     if (raw === true || raw === "") {
       console.error("usage: --budget section=limit,... (limits are positive integers)");
       process.exit(2);
@@ -259,8 +275,8 @@ try {
       }
     }
     const ctx = queryContext(graph, needle, { budget });
-    if (flags.has("md") || flag("md")) out(renderContext(ctx));
-    else if (flags.has("json")) out(ctx, true);
+    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
@@ -270,7 +286,7 @@ try {
     const res = compile(ROOT);
     if (res.errors.length) fail(res.errors, res.stats);
     const graph = res.graph;
-    const fromRef = flag("diff") || flag("from");
+    const fromRef = opt("diff") || opt("from");
     let paths = positional;
     if (fromRef && fromRef !== true) {
       if (!res.repo.hasGit()) {
@@ -309,7 +325,7 @@ try {
     out(report, true);
   } else if (cmd === "scaffold") {
     const res = compile(ROOT);
-    const write = flags.has("write") || flag("write");
+    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)
@@ -337,7 +353,7 @@ try {
         : {}),
     }, true);
   } else if (cmd === "init") {
-    const result = installTemplates(null, null, { write: true, root: ROOT, force: flags.has("force") });
+    const result = installTemplates(null, null, { write: true, root: ROOT, force: opt("force") });
     out(result, true);
   } else if (cmd === "eval") {
     const which = positional[0] || "routing";
@@ -355,8 +371,8 @@ try {
       }
       throw e;
     }
-    const report = runRoutingEval(ROOT, { json: flags.has("json") });
-    if (flags.has("json")) { out(report, true); process.exit(report.verdict === "FAIL" ? 1 : 0); }
+    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));
@@ -390,7 +406,7 @@ try {
         });
       }
     }
-    if (flags.has("json")) { out({ evidence: results }, true); }
+    if (opt("json")) { out({ evidence: results }, true); }
     else {
       for (const r of results) {
         console.log(r.status.padEnd(8) + " " + r.path);
@@ -435,7 +451,7 @@ try {
     const machineOk = machine.nodeSupported && machine.schemaBundle.ok;
 
     const report = { scope: "machine", ok: machineOk, machine };
-    if (flags.has("project")) {
+    if (opt("project")) {
       const configFound = fs.existsSync(path.join(ROOT, "agentdoc", "agentdoc.config.yaml"));
       const project = {
         root: ROOT,

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");
+}

package/bin/usage.txt

@@ -1,14 +1,15 @@
 agentdoc — portable documentation & software-catalog system
 
   agentdoc --version                 print the installed version
-  agentdoc --help                    show this help (also: agentdoc <command> --help)
+  agentdoc --help                    show this help
+  agentdoc <command> --help          every flag one command accepts (also: agentdoc help <command>)
 
   agentdoc init [--force]            write a configuration and documentation skeleton
   agentdoc audit                     inventory the repository, classify every fact
   agentdoc scaffold [--write]        generate a CREATE-mode skeleton from the audit
   agentdoc validate                  sources + schemas + semantic checks
   agentdoc compile [--require-clean] deterministic graph build (atomic write)
-  agentdoc check [--require-clean] [--allow-stale-observations]
+  agentdoc check [--strict] [--require-clean] [--allow-stale-observations]
                                      freshness, determinism and gate check
   agentdoc query <path|ref> [--md] [--json] [--budget k=n]
                                      route minimal context for a task
@@ -23,4 +24,5 @@ agentdoc — portable documentation & software-catalog system
 Commands that operate on a catalog run from anywhere inside the repository;
 the configuration is found by walking up to agentdoc/agentdoc.config.yaml.
 
-Exit codes: 0 ok, 1 failure, 2 usage.
+Exit codes: 0 ok, 1 failure, 2 usage. An unknown flag is a usage error (2),
+never ignored.

package/core/audit.mjs

@@ -18,6 +18,7 @@
 import { classifyContractFile } from "./contracts.mjs";
 import { ContextIndex } from "./query.mjs";
 import { expandGlob, isRepoPath } from "./fsx.mjs";
+import { isNormative, NORMATIVE_SEMANTICS_PREFIX } from "./normative.mjs";
 
 const DOC_EXT = /\.(md|mdx|adoc|rst|txt)$/;
 
@@ -28,7 +29,11 @@ export function audit(repo, cfg, res) {
   const note = (fact, cls, why) => {
     if (!classes.has(fact)) classes.set(fact, { cls, why: [] });
     const cur = classes.get(fact);
+    // Strongest class wins regardless of the order sources are visited in:
+    // corroboration outranks a single derivation, and a conflict or an open
+    // question outranks both.
     if (cls === "CONFLICT" || cls === "UNRESOLVED") cur.cls = cls;
+    else if (cls === "CONFIRMED" && cur.cls === "DERIVED") cur.cls = cls;
     if (why) cur.why.push(why);
   };
 
@@ -53,8 +58,35 @@ export function audit(repo, cfg, res) {
   }
 
   // 2. facts and conflicts
+  const normative = res.normative || { sections: [], uncovered: [], requirements: [] };
+  const enabledAdapters = new Set((graph.compiler.adapters || []).map((a) => a.name));
   for (const a of graph.assertions) {
     const f = a.subject + " " + a.key;
+    if (isNormative(a)) {
+      // A requirement names where it came from, and — when nothing proves it —
+      // what could have: a missing extractor reduces coverage, it does not
+      // make an obligation disappear.
+      const cite = a.semantics.slice(NORMATIVE_SEMANTICS_PREFIX.length);
+      const all = graph.assertions.filter((b) => b.subject === a.subject && b.key === a.key && b !== a && !isNormative(b));
+      const peers = all.filter((b) => b.confidence !== "candidate");
+      const candidates = all.filter((b) => b.confidence === "candidate");
+      if (!peers.length) {
+        const r = normative.requirements.find((x) => x.subject === a.subject && x.key === a.key) || { satisfiedBy: [] };
+        const missing = r.satisfiedBy.filter((n) => !enabledAdapters.has(n));
+        note(f, "UNRESOLVED", "normative: " + cite + " requires " + JSON.stringify(a.value));
+        note(f, "UNRESOLVED",
+          "no implementation evidence" +
+          (candidates.length ? "; heuristic candidate only: " + (candidates[0].semantics || JSON.stringify(candidates[0].value))
+            : missing.length ? "; adapter not enabled: " + missing.join(", ")
+              : r.satisfiedBy.length ? "; " + r.satisfiedBy.join(", ") + " derived nothing" : "; no adapter named in satisfiedBy"));
+      } else if (a.status === "elected") {
+        note(f, "CONFIRMED", "normative: " + cite + " corroborated by " + peers.map((b) => b.evidenceClass).join(", "));
+      } else {
+        note(f, "CONFLICT", "normative: " + cite + " requires " + JSON.stringify(a.value) + "; implementation evidence says " +
+          peers.map((b) => b.evidenceClass + "=" + JSON.stringify(b.value)).join(", "));
+      }
+      continue;
+    }
     if (a.evidenceClass === "OBSERVED_RUNTIME") note(f, "OBSERVED", a.observed ? a.observed.sourceSystem + " at " + a.observed.at : "runtime");
     else if (a.status === "unresolved") note(f, "UNRESOLVED", "no deterministic resolution");
     else if (a.status === "candidate") note(f, "UNRESOLVED", "heuristic candidate only");
@@ -96,7 +128,7 @@ export function audit(repo, cfg, res) {
   // loop below; letting one through as a "document" makes `exists: true` for a
   // directory, which is a check that can never fail.
   const configured = Object.entries(cfg.docs || {})
-    .filter(([role]) => !role.endsWith("Dir"))
+    .filter(([role]) => !role.endsWith("Dir") && role !== "normative")
     .map(([role, p]) => ({ role, path: p, configured: true }));
   // Directory-shaped roles are enumerated rather than listed as a single entry:
   // a directory is not a document, and reporting it as one is a dead check.
@@ -303,6 +335,13 @@ export function audit(repo, cfg, res) {
     }
   }
 
+  // ── 9. normative coverage ───────────────────────────────────────────────
+  // Every section of a normative document, with the digest a reviewer cites,
+  // and whether a requirement or an attestation accounts for it. Linking a
+  // specification to a component routes it; only this says it was reviewed.
+  const unverifiedRequirements = normative.requirements.filter((r) =>
+    !graph.assertions.some((b) => b.subject === r.subject && b.key === r.key && !isNormative(b) && b.confidence !== "candidate"));
+
   const rows = [...classes.entries()].map(([fact, v]) => ({ fact, classification: v.cls, evidence: v.why.slice(0, 4) }));
   rows.sort((a, b) => (a.fact < b.fact ? -1 : 1));
   const counts = rows.reduce((acc, r) => { acc[r.classification] = (acc[r.classification] || 0) + 1; return acc; }, {});
@@ -333,7 +372,17 @@ export function audit(repo, cfg, res) {
       .filter((c) => c.status !== "unresolved")
       .map((c) => ({ kind: c.kind, subject: c.subject, key: c.key, status: c.status, basis: c.election.basis, ruleId: c.election.ruleId })),
     documentationContradictions: docContradictions,
+    normative: {
+      sections: normative.sections,
+      uncovered: normative.uncovered,
+      requirements: normative.requirements.map((r) => ({
+        subject: r.subject, id: r.id, key: r.key, value: r.value,
+        source: r.source.path + "#" + r.source.section, satisfiedBy: r.satisfiedBy,
+      })),
+    },
     reviewedAmbiguity: [
+      ...normative.uncovered.map((s) => ({ kind: "NORMATIVE_UNCOVERED", subject: s.path + "#" + s.section })),
+      ...unverifiedRequirements.map((r) => ({ kind: "REQUIREMENT_UNVERIFIED", subject: r.subject + " " + r.key })),
       ...unresolvedEvents.map((pattern) => ({ kind: "EVENT_WITHOUT_PRODUCER", subject: pattern })),
       ...ambiguousOwnership.map((ref) => ({ kind: "COMPONENT_OWNERSHIP", subject: ref })),
       ...unclaimedContracts.map((p) => ({ kind: "UNCLAIMED_CONTRACT", subject: p })),

package/core/authority/engine.mjs

@@ -10,6 +10,7 @@
 // fail-closed default: silence is not a resolution.
 import { AgentDocError, CODES } from "../codes.mjs";
 import { EVIDENCE_CLASSES, CONFIDENCE } from "./classes.mjs";
+import { isNormative } from "../normative.mjs";
 
 export class AuthorityEngine {
   constructor(rules) {
@@ -75,6 +76,18 @@ export function resolveAssertions(assertions, authority) {
     const [subject, key] = gk.split("\u0000");
     const distinct = distinctValues(list);
 
+    // A normative requirement is a claim about what the implementation must
+    // do, so it can only be corroborated, never elected on its own word. With
+    // no implementation evidence beside it, it stays unresolved: the gap the
+    // migration must surface.
+    const normative = list.some(isNormative);
+    if (normative && list.every((a) => isNormative(a) || a.confidence === "candidate")) {
+      // A heuristic candidate is not evidence either way: it stays a candidate,
+      // and the requirement stays unverified.
+      for (const a of list) a.status = isNormative(a) ? "unresolved" : "candidate";
+      continue;
+    }
+
     if (distinct.length === 1) {
       // Agreement across evidence classes is corroboration, not a conflict —
       // but a lone heuristic candidate is not agreement with anything. It stays
@@ -121,9 +134,19 @@ export function resolveAssertions(assertions, authority) {
     };
     let status = "unresolved";
 
+    // 0. A normative requirement and the implementation disagree. No rule may
+    //    settle that: electing the implementation waives the specification,
+    //    electing the requirement hides the missing implementation. Only a
+    //    change to one of them resolves it.
+    if (normative) {
+      election.rationale =
+        "a normative requirement disagrees with the implementation evidence; no authority rule may settle it — " +
+        "change the implementation, or change the specification and re-review its section";
+    }
+
     // 1. reviewed override wins outright, but the divergence is still recorded.
     const reviewed = candidates.filter((a) => a.evidenceClass === "REVIEWED_OVERRIDE");
-    if (rule && rule.elect.length === 1 && rule.elect[0] === "REVIEWED_OVERRIDE" && reviewed.length === 1) {
+    if (!normative && rule && rule.elect.length === 1 && rule.elect[0] === "REVIEWED_OVERRIDE" && reviewed.length === 1) {
       election.elected = reviewed[0];
       election.basis = "reviewed-override";
       election.rationale = rule.rationale;
@@ -131,7 +154,7 @@ export function resolveAssertions(assertions, authority) {
     }
 
     // 2. authority rule with a single elected class present among candidates.
-    if (!election.elected && rule) {
+    if (!normative && !election.elected && rule) {
       const allowed = rule.elect.filter((c) => candidates.some((a) => a.evidenceClass === c));
       if (allowed.length === 1) {
         const winners = candidates.filter((a) => a.evidenceClass === allowed[0]);
@@ -149,7 +172,7 @@ export function resolveAssertions(assertions, authority) {
     }
 
     // 3. superset: one candidate's value contains every other candidate's value.
-    if (!election.elected && candidates.length > 1) {
+    if (!normative && !election.elected && candidates.length > 1) {
       const sup = candidates.find((c) => candidates.every((o) => o === c || containsValue(c.value, o.value)));
       if (sup) {
         election.elected = sup;
@@ -160,7 +183,7 @@ export function resolveAssertions(assertions, authority) {
     }
 
     // 4. recency: only when the rule names recency and the winner is a runtime fact.
-    if (!election.elected && rule && rule.elect.includes("OBSERVED_RUNTIME")) {
+    if (!normative && !election.elected && rule && rule.elect.includes("OBSERVED_RUNTIME")) {
       const runtime = candidates.filter((a) => a.evidenceClass === "OBSERVED_RUNTIME");
       const dated = runtime.filter((a) => a.observed && a.observed.at);
       if (dated.length > 1) {

package/core/codes.mjs

@@ -58,6 +58,11 @@ export const CODES = {
   ELECTION_STALE: "AGENTDOC_ELECTION_STALE",
   UNRESOLVED_FACT: "AGENTDOC_UNRESOLVED_FACT",
 
+  // normative requirements
+  NORMATIVE_UNCOVERED: "AGENTDOC_NORMATIVE_UNCOVERED",
+  NORMATIVE_SOURCE_STALE: "AGENTDOC_NORMATIVE_SOURCE_STALE",
+  REQUIREMENT_UNVERIFIED: "AGENTDOC_REQUIREMENT_UNVERIFIED",
+
   // provenance & determinism
   PROVENANCE: "AGENTDOC_PROVENANCE",
   NONDETERMINISTIC: "AGENTDOC_NONDETERMINISTIC",
@@ -87,6 +92,8 @@ export const ACCEPTABLE_WARNING_CODES = Object.freeze([
   "AGENTDOC_EXTERNAL_DEPENDENCY_UNCLASSIFIED",
   "AGENTDOC_DOC_ORPHANED",
   "AGENTDOC_VERIFICATION_UNTIERED",
+  "AGENTDOC_NORMATIVE_UNCOVERED",
+  "AGENTDOC_REQUIREMENT_UNVERIFIED",
 ]);
 
 export class AgentDocError extends Error {