agent-doc-system 1.0.0 → 1.1.0

package/core/compile.mjs

@@ -18,6 +18,9 @@ import { formatErrors } from "./jsonschema.mjs";
 import { validateContractFile } from "./contracts.mjs";
 import { sourceFiles, importSpecifiers } from "./sourcescan.mjs";
 import { applyWarningAcceptances } from "./acceptances.mjs";
+import {
+  loadNormativeDocuments, verifyCitation, normativeCoverage, isNormative, isRequirementKey, NORMATIVE_SEMANTICS_PREFIX,
+} from "./normative.mjs";
 import { loadAdapters } from "../adapters/index.mjs";
 import {
   COMPILER_NAME, COMPILER_VERSION, GRAPH_SCHEMA_VERSION,
@@ -115,6 +118,13 @@ export function compile(root, opts = {}) {
     evidence: o.evidence.map((ev) => ({ path: ev.path, sha256: ev.sha256 })),
   });
 
+  // ── normative requirements ───────────────────────────────────────────────
+  // Checked before discovery so a stale citation is reported alongside every
+  // other authored-input error rather than hiding behind a coverage failure.
+  const normative = loadNormative(repo, cfg, sources, overrides.overrides);
+  res.errors.push(...normative.errors);
+  res.normative = { sections: normative.sections, uncovered: normative.uncovered, requirements: normative.requirements };
+
   res.errors.push(...checkContractCoverage({ repo, cfg, sources }));
 
   for (const api of sources.entities.filter((e) => e.kind === "API")) {
@@ -165,6 +175,9 @@ export function compile(root, opts = {}) {
     repo, cfg, refs, bundle, prov, diagnostics, facts,
     sources: { ...sources, journeys: journeys.journeys }, discovery, journeys: journeys.journeys, journeysPath: journeys.path,
     observations, overrides: overrides.overrides,
+    // Declared normative requirements, so an adapter named in `satisfiedBy`
+    // can derive the implementation side on the same key.
+    requirements: normative.requirements,
     edges, events, externals, capabilities, verification,
     errors: [],
     unitByComponent: new Map(),
@@ -436,6 +449,21 @@ export function compile(root, opts = {}) {
     }
   }
 
+  // A requirement is an AUTHORED claim that the implementation must make true.
+  // It is a fact like any other so the authority engine compares it with the
+  // implementation evidence on the same key — and it carries its citation, so
+  // every report can say which section of which document it came from.
+  for (const r of normative.requirements) {
+    facts.add({
+      subject: r.subject, key: r.key, value: r.value, evidenceClass: "AUTHORED", confidence: "declared",
+      provRecs: [
+        prov.add("declared", r.file, "requirement-extractor", ["ass:pending"]),
+        prov.add("declared", r.source.path, "requirement-extractor", ["ass:pending"]),
+      ],
+      semantics: NORMATIVE_SEMANTICS_PREFIX + r.source.path + "#" + r.source.section,
+    });
+  }
+
   // ── reviewed overrides → relations and facts ─────────────────────────────
   const overrideEdges = [];
   for (const o of overrides.overrides) {
@@ -503,6 +531,13 @@ export function compile(root, opts = {}) {
         evidenceClass: "REVIEWED_OVERRIDE", confidence: "reviewed", provRecs: provs, semantics: o.reason,
         review: reviewed(o),
       });
+    } else if (o.fact === "requirement-satisfaction") {
+      facts.add({
+        subject: o.subject, key: o.key, value: o.value,
+        evidenceClass: "REVIEWED_OVERRIDE", confidence: "reviewed", provRecs: provs,
+        semantics: o.reason,
+        review: reviewed(o),
+      });
     } else if (o.fact === "component-placement") {
       const key = o.system ? "placement.system" : "placement.domain";
       facts.add({
@@ -557,6 +592,7 @@ export function compile(root, opts = {}) {
 
   const { conflicts: rawConflicts } = resolveAssertions(facts.facts, authority);
   pushConflictDiagnostics(rawConflicts, diagnostics, facts);
+  pushNormativeDiagnostics(normative, facts, adapters, diagnostics);
 
   // ── relations ────────────────────────────────────────────────────────────
   const rel = buildRelations(ctx);
@@ -753,7 +789,13 @@ function pushConflictDiagnostics(rawConflicts, diagnostics, facts) {
       .filter(Boolean)
       .map((f) => f.evidenceClass + "=" + JSON.stringify(f.value))
       .sort();
-    const detail = c.subject + " " + c.key + ": " + values.join(" vs ");
+    let detail = c.subject + " " + c.key + ": " + values.join(" vs ");
+    // For a requirement, say where each side comes from: the cited section and
+    // what the extractor actually found. Two bare values send a reader hunting.
+    if (isRequirementKey(c.key)) {
+      const why = c.assertionIds.map((id) => byId.get(id)).filter((f) => f && f.semantics).map((f) => f.semantics).sort();
+      if (why.length) detail += " (" + why.join("; ") + ")";
+    }
     if (c.kind === "ambiguity" && c.status === "unresolved") {
       diagnostics.push({
         severity: "warning",
@@ -775,7 +817,7 @@ function pushConflictDiagnostics(rawConflicts, diagnostics, facts) {
         message:
           "unresolved " + c.kind + " — " + detail + ". " +
           (c.election.rationale || "no authority rule governs this fact") +
-          ". Add an authority rule and, if deterministic discovery cannot settle it, a reviewed override.",
+          (isRequirementKey(c.key) ? "." : ". Add an authority rule and, if deterministic discovery cannot settle it, a reviewed override."),
       });
     } else {
       diagnostics.push({
@@ -794,6 +836,101 @@ function pushConflictDiagnostics(rawConflicts, diagnostics, facts) {
   }
 }
 
+// Normative documents, the requirements components declare against them, and
+// which sections nobody has accounted for. Every citation is re-verified
+// against the section's current digest: a requirement or an attestation
+// written against an older wording of the specification is a review that has
+// not happened yet.
+function loadNormative(repo, cfg, sources, overrides) {
+  const errors = [];
+  const out = { errors, sections: [], uncovered: [], requirements: [] };
+  let docs;
+  try {
+    docs = loadNormativeDocuments(repo, cfg);
+  } catch (e) {
+    if (!(e instanceof AgentDocError)) throw e;
+    errors.push(e);
+    return out;
+  }
+  for (const e of sources.entities) {
+    if (e.kind !== "Component") continue;
+    const seen = new Set();
+    for (const r of e.doc.spec.requirements || []) {
+      collect(() => {
+        if (seen.has(r.id) || seen.has(r.key)) {
+          throw new AgentDocError(CODES.CONFIG, "duplicate requirement id or key on " + e.ref + ": " + r.id + " / " + r.key, { path: e.file, ref: e.ref });
+        }
+        seen.add(r.id);
+        seen.add(r.key);
+        verifyCitation(docs, r.source, e.file, e.ref);
+        out.requirements.push({ ...r, subject: e.ref, file: e.file, satisfiedBy: r.satisfiedBy || [] });
+      }, errors);
+    }
+  }
+  // A satisfaction override must answer a requirement someone declared. One
+  // that answers nothing would be an implementation claim with no obligation
+  // behind it, which no report could ever surface.
+  const declared = new Set(out.requirements.map((r) => r.subject + "\u0000" + r.key));
+  for (const o of overrides) {
+    if (o.fact !== "requirement-satisfaction") continue;
+    if (!declared.has(o.subject + "\u0000" + o.key)) {
+      errors.push(new AgentDocError(
+        CODES.CONFIG,
+        "requirement-satisfaction override answers no declared requirement: " + o.subject + " " + o.key,
+        { path: CONFIG_PATH, ref: o.subject }
+      ));
+    }
+  }
+  const cov = normativeCoverage(docs, out.requirements, cfg.normativeCoverage || [], errors);
+  out.sections = cov.sections;
+  out.uncovered = cov.uncovered;
+  return out;
+}
+
+function pushNormativeDiagnostics(normative, facts, adapters, diagnostics) {
+  for (const s of normative.uncovered) {
+    const id = s.path + "#" + s.section;
+    diagnostics.push({
+      severity: "warning",
+      code: CODES.NORMATIVE_UNCOVERED,
+      subject: id,
+      paths: [s.path],
+      refs: [],
+      message:
+        "normative section " + id + " (sha256 " + s.sha256 + ") is routed but not reviewed: " +
+        "declare the requirement it places on a component (spec.requirements), or attest in normativeCoverage " +
+        "that it carries no implementation obligation.",
+    });
+  }
+  const enabled = new Set(adapters.map((a) => a.name));
+  for (const r of normative.requirements) {
+    const group = facts.facts.filter((f) => f.subject === r.subject && f.key === r.key && f.status !== "superseded");
+    if (group.some((f) => !isNormative(f) && f.confidence !== "candidate")) continue;
+    const candidate = group.find((f) => !isNormative(f));
+    const missing = r.satisfiedBy.filter((a) => !enabled.has(a));
+    const why = candidate
+      ? "only a heuristic candidate exists, which is never elected — " + (candidate.semantics || JSON.stringify(candidate.value))
+      : !r.satisfiedBy.length
+        ? "no adapter is named as able to derive it"
+        : missing.length
+          ? "the adapter able to derive it is not enabled or not available: " + missing.join(", ")
+          : !r.expects
+            ? "the requirement has no `expects`, so " + r.satisfiedBy.join(", ") + " has nothing to look for"
+            : "the enabled adapter (" + r.satisfiedBy.join(", ") + ") derived no evidence for it";
+    diagnostics.push({
+      severity: "warning",
+      code: CODES.REQUIREMENT_UNVERIFIED,
+      subject: r.subject + "#" + r.key,
+      paths: [r.source.path],
+      refs: [r.subject],
+      message:
+        "requirement " + r.key + " = " + r.value + " on " + r.subject + " (from " + r.source.path + "#" + r.source.section +
+        ") has no implementation evidence; " + why + ". Add a requirement-satisfaction reviewed override citing the " +
+        "implementation, or accept the gap with review.",
+    });
+  }
+}
+
 // A Go import is either host.tld/owner/repo/path or host.tld/owner/repo. The
 // second form is what a Go *workspace* member uses, and it has only two dots —
 // a pattern that requires three silently loses every workspace-only dependency.

package/core/descriptors.mjs

@@ -15,7 +15,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { AgentDocError, CODES, collect } from "./codes.mjs";
-import { assertRepoPath, expandGlob, sha256Hex } from "./fsx.mjs";
+import { assertGlob, assertRepoPath, expandGlob, sha256Hex } from "./fsx.mjs";
 import { parseYamlDocuments } from "./yaml.mjs";
 import { scanForSecrets } from "./secrets.mjs";
 import { formatErrors } from "./jsonschema.mjs";
@@ -160,10 +160,13 @@ export function loadConfig(repo, bundle) {
     cfg.output.graph, cfg.output.observations,
     ...(cfg.discovery.supplementalRoots || []),
     ...(cfg.discovery.contractRoots || []),
-    ...(cfg.docs ? Object.values(cfg.docs) : []),
+    ...(cfg.docs ? Object.entries(cfg.docs).filter(([k]) => k !== "normative").map(([, v]) => v) : []),
   ].filter(Boolean)) {
     assertRepoPath(p, CONFIG_PATH);
   }
+  // `docs.normative` holds globs, not paths: the only role that names a set of
+  // documents rather than one.
+  for (const g of (cfg.docs && cfg.docs.normative) || []) assertGlob(g, CONFIG_PATH);
   return cfg;
 }
 

package/core/fsx.mjs

@@ -175,16 +175,17 @@ export class Repo {
     return names;
   }
 
-  git(args) {
+  git(args, { trim = true } = {}) {
     // stderr must be piped, not inherited: every caller treats a non-zero exit
     // as a signal to degrade (unborn HEAD, detached worktree, missing remote),
     // and execFileSync would otherwise print git's own "fatal:" line to the
     // user's terminal while the command reports success.
-    return execFileSync("git", args, {
+    const out = execFileSync("git", args, {
       cwd: this.root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
-    }).trim();
+    });
+    return trim ? out.trim() : out;
   }
   hasGit() {
     if (this.noGit) return false;
@@ -239,7 +240,12 @@ export class Repo {
     if (this.noGit || !this.hasGit()) return [];
     let raw;
     try {
-      raw = this.git(["status", "--porcelain", "-z", "--untracked-files=all"]);
+      // Untrimmed: a porcelain record is `XY <path>` with fixed columns, and an
+      // unstaged change has X = " ". Trimming would eat that space from the
+      // first record, so `.slice(3)` would drop the path's first character —
+      // ` M .agentdoc/graph.json` became `agentdoc/graph.json`, slipped past
+      // the output exclusion and counted as a dirty input (issue #11).
+      raw = this.git(["status", "--porcelain", "-z", "--untracked-files=all"], { trim: false });
     } catch {
       return [];
     }

package/core/graph.mjs

@@ -9,7 +9,7 @@ import { assertDeterministic, structuralProjection } from "./determinism.mjs";
 import { sha256Hex } from "./fsx.mjs";
 
 export const COMPILER_NAME = "agentdoc-compiler";
-export const COMPILER_VERSION = "1.0.0";
+export const COMPILER_VERSION = "1.1.0";
 export const GRAPH_SCHEMA_VERSION = "agentdoc.dev/graph/v1";
 
 // Resolve symbolic provenance subjects to RFC 6901 pointers into the graph.

package/core/normative.mjs

@@ -0,0 +1,171 @@
+// Normative requirement coverage.
+//
+// A normative document (a specification, a technical profile) states what the
+// implementation must do. Routing it to a component is not reviewing it: the
+// incident behind this module was a migration that linked every specification,
+// passed every gate, and still never noticed that a "must be reproduced on the
+// production host" had no implementation at all.
+//
+// This module does not read prose for meaning. It does two deterministic
+// things:
+//
+//   - it cuts every configured normative document into sections and pins each
+//     one by content hash, so "which parts of the specification were reviewed"
+//     becomes a question with an exact answer;
+//   - it requires every section to be accounted for, either by a structured
+//     requirement (a fact the authority engine can compare against evidence)
+//     or by an explicit, reviewed attestation that it carries no
+//     implementation obligation.
+//
+// Deciding *what* a section obliges is a human act. Making sure that act
+// happened, and is re-done when the section changes, is the machine's.
+import { AgentDocError, CODES } from "./codes.mjs";
+import { expandGlob, sha256Hex } from "./fsx.mjs";
+import { CONFIG_PATH } from "./descriptors.mjs";
+
+export const REQUIREMENT_KEY_PREFIX = "requirement.";
+export const NORMATIVE_SEMANTICS_PREFIX = "normative: ";
+
+// Sections are the level-2 headings of a Markdown document. Level 1 is the
+// document title; deeper levels belong to the section that contains them, so a
+// reviewer attests a unit that is large enough to carry one obligation and
+// small enough to be re-reviewed when it changes. Headings inside fenced code
+// blocks are not headings.
+export function splitSections(text) {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const sections = [];
+  const slugs = new Map();
+  let cur = null;
+  let fence = null;
+  for (const line of lines) {
+    const f = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (f) {
+      if (!fence) fence = f[1][0];
+      else if (f[1][0] === fence) fence = null;
+    }
+    const h = !fence && /^##(?!#)\s+(.+?)\s*#*\s*$/.exec(line);
+    if (h) {
+      if (cur) sections.push(cur);
+      const base = slugify(h[1]);
+      // Duplicate headings get the same suffixes a Markdown renderer gives
+      // their anchors, so a citation can be the link a reader would follow.
+      const n = slugs.get(base) || 0;
+      slugs.set(base, n + 1);
+      cur = { section: n ? base + "-" + n : base, heading: h[1], lines: [line] };
+      continue;
+    }
+    if (/^#(?!#)\s/.test(line) && !fence) {
+      if (cur) sections.push(cur);
+      cur = null;
+      continue;
+    }
+    if (cur) cur.lines.push(line);
+  }
+  if (cur) sections.push(cur);
+  return sections.map((s) => {
+    // Trailing blank lines are layout, not content: appending a section must
+    // not invalidate the review of the one before it.
+    while (s.lines.length > 1 && s.lines[s.lines.length - 1].trim() === "") s.lines.pop();
+    const body = s.lines.join("\n") + "\n";
+    return { section: s.section, heading: s.heading, sha256: sha256Hex(Buffer.from(body, "utf8")) };
+  });
+}
+
+export function slugify(heading) {
+  return String(heading)
+    .trim()
+    .toLowerCase()
+    .replace(/[`*_~[\]()]/g, "")
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .replace(/\s/g, "-");
+}
+
+// Every configured normative document, cut into sections. Reading through the
+// repository handle keeps these files in the compile's input hash, so a change
+// to a specification makes the committed graph stale like any other input.
+export function loadNormativeDocuments(repo, cfg) {
+  const globs = (cfg.docs && cfg.docs.normative) || [];
+  const paths = new Set();
+  for (const g of globs) for (const p of expandGlob(repo, g)) paths.add(p);
+  const docs = [];
+  for (const p of [...paths].sort()) {
+    if (!/\.(md|mdx)$/.test(p)) continue;
+    docs.push({ path: p, sections: splitSections(repo.readText(p)) });
+  }
+  return docs;
+}
+
+// A citation of one section: a requirement's `source`, or a coverage
+// attestation. Both must name a section that exists *now*, with the digest it
+// had when someone reviewed it.
+export function verifyCitation(docs, cite, where, ref) {
+  const doc = docs.find((d) => d.path === cite.path);
+  if (!doc) {
+    throw new AgentDocError(
+      CODES.CONFIG,
+      "cites " + cite.path + ", which is not a configured normative document (docs.normative)",
+      { path: where, ref }
+    );
+  }
+  const s = doc.sections.find((x) => x.section === cite.section);
+  if (!s) {
+    throw new AgentDocError(
+      CODES.NORMATIVE_SOURCE_STALE,
+      "cited section " + cite.path + "#" + cite.section + " no longer exists — re-review what replaced it",
+      { path: where, ref }
+    );
+  }
+  if (s.sha256 !== cite.sha256) {
+    throw new AgentDocError(
+      CODES.NORMATIVE_SOURCE_STALE,
+      "cited section " + cite.path + "#" + cite.section + " changed since it was reviewed — " +
+        "re-review it before updating the digest to " + s.sha256,
+      { path: where, ref }
+    );
+  }
+  return s;
+}
+
+// Coverage: which sections are cited by a requirement, which are attested, and
+// which nobody has looked at. Returned rather than pushed so the audit can show
+// the same table the gate enforces.
+export function normativeCoverage(docs, requirements, attestations, errors) {
+  const coveredBy = new Map();
+  const mark = (path, section, by) => {
+    const k = path + "#" + section;
+    if (!coveredBy.has(k)) coveredBy.set(k, []);
+    coveredBy.get(k).push(by);
+  };
+  for (const r of requirements) {
+    mark(r.source.path, r.source.section, "requirement:" + r.subject + " " + r.key);
+  }
+  const seen = new Set();
+  for (const a of attestations) {
+    const k = a.path + "#" + a.section;
+    try {
+      if (seen.has(k)) throw new AgentDocError(CODES.CONFIG, "duplicate normativeCoverage entry for " + k, { path: CONFIG_PATH });
+      seen.add(k);
+      verifyCitation(docs, a, CONFIG_PATH, null);
+      mark(a.path, a.section, "attestation:" + a.disposition);
+    } catch (e) {
+      if (!(e instanceof AgentDocError)) throw e;
+      errors.push(e);
+    }
+  }
+  const sections = [];
+  for (const d of docs) {
+    for (const s of d.sections) {
+      const by = (coveredBy.get(d.path + "#" + s.section) || []).sort();
+      sections.push({ path: d.path, section: s.section, heading: s.heading, sha256: s.sha256, coveredBy: by });
+    }
+  }
+  return { sections, uncovered: sections.filter((s) => !s.coveredBy.length) };
+}
+
+export function isRequirementKey(key) {
+  return typeof key === "string" && key.startsWith(REQUIREMENT_KEY_PREFIX);
+}
+
+export function isNormative(assertion) {
+  return typeof assertion.semantics === "string" && assertion.semantics.startsWith(NORMATIVE_SEMANTICS_PREFIX);
+}

package/core/yaml.mjs

@@ -425,8 +425,10 @@ class Reader {
 }
 
 // Parse a multi-document YAML stream. Returns [{doc, line}] with 1-based line
-// numbers of each document root.
-export function parseYamlDocuments(src, path) {
+// numbers of each document root. Catalog sources must be mappings; a reader of
+// third-party files whose root is a list (an Ansible playbook or task file)
+// opts in with `allowSequenceRoot`.
+export function parseYamlDocuments(src, path, { allowSequenceRoot = false } = {}) {
   if (typeof src !== "string") throw new AgentDocError(CODES.UTF8, "expected text for " + path, { path });
   if (src.charCodeAt(0) === 0xfeff) src = src.slice(1);
   scanBanned(src, path);
@@ -458,7 +460,7 @@ export function parseYamlDocuments(src, path) {
       throw new AgentDocError(CODES.YAML_PARSE, "unparsed trailing content", { path, line: r.peek().lineNo });
     }
     if (value === null) continue;
-    if (typeof value !== "object" || Array.isArray(value)) {
+    if (typeof value !== "object" || (Array.isArray(value) && !allowSequenceRoot)) {
       throw new AgentDocError(CODES.YAML_NON_MAP_ROOT, "document root must be a mapping", { path, line: rootLine });
     }
     out.push({ doc: value, line: rootLine });

package/docs/ADAPTERS.md

@@ -43,6 +43,7 @@ Available on `ctx`:
 | `transitiveDependencies(ref)` | manifest-declared dependencies, order-independent |
 | `productionDependencies(ref)` | production dependency names, for client-of-resource rules |
 | `deferSecondPass(fn)` | run after every unit is known |
+| `requirements` | declared normative requirements (`subject`, `key`, `value`, `source`, `satisfiedBy`, `expects`) an adapter may derive the implementation side of |
 | `unitByPkgName`, `unitByGoModule` | cross-unit resolution built before extraction |
 | `errors.push({ code, message })` | a hard error, collected rather than thrown |
 
@@ -92,7 +93,7 @@ cannot name the file a fact came from, you cannot add the fact.
 | `openapi` | `*.openapi.y[a]ml` | operation inventory, deterministic consumers |
 | `protobuf` / `graphql` | contract files | method/type inventory, consumers |
 | `oidc` | discovery-path literals | OIDC client consumers |
-| `github-actions` | `.github/workflows` | component-scoped checks and repository gates |
+| `github-actions` | repository-root `.github/workflows` (not a unit marker; a nested one is ignored, as GitHub ignores it) | component-scoped checks and repository gates |
 | `dockerfile` | `Dockerfile`, `Containerfile` | deployable evidence |
 | `deploy-config` | `fly.toml`, `Procfile`, … | deployable evidence |
 | `wrangler` | `wrangler.toml/json` | bindings, crons, service bindings, trigger targets |
@@ -100,10 +101,44 @@ cannot name the file a fact came from, you cannot add the fact.
 | `object-store` | bucket literals | logical-dataset edges, or an ambiguity |
 | `cache` | cache client evidence | cache bindings |
 | `events` | subject literals, declared constants, event-contract files | producers, consumers, reserved subjects |
+| `ansible` | playbooks (YAML lists of plays) | deployable evidence, installed paths and managed services, the DERIVED side of provisioning requirements |
 
 `generic` is always on. Everything else is opt-in through `adapters: [...]`, and
 an unknown name is `AGENTDOC_CONFIG`, not a silent no-op.
 
+### `ansible`
+
+Reads playbooks under a unit root and follows what they reach — plays,
+`roles:`, `include_role`/`import_role`, `include_tasks`/`import_tasks`,
+`import_playbook`, `block`/`rescue`/`always` — inside the repository only.
+Nothing is executed and no Jinja is evaluated.
+
+| it derives | from |
+|---|---|
+| an installed path | `copy`/`template`/`get_url`/`git`/`synchronize` `dest`, `unarchive` `dest`/`creates`, `pip` `virtualenv`, `file` with `state: directory\|touch\|link\|hard`, `lineinfile`/`blockinfile` with `create: true`, a command's literal `creates` |
+| a managed service | `systemd`, `systemd_service`, `service` `name` |
+
+The inventory lands on the component as `derived.provisioning`. For a normative
+requirement on that component with `satisfiedBy: [ansible]` and an `expects`
+(`installs: <path>` or `service: <name>`), it adds a `DERIVED` fact on the
+requirement key:
+
+| value | confidence | when |
+|---|---|---|
+| `provided` | deterministic | a reachable task without `when` installs the path (or a path below it), or manages the service |
+| `provided` | candidate | the only matching task is conditional (`when`, `rescue`, a conditional role or include) |
+| `absent` | deterministic | no reachable task matches **and** every reachable task is transparent |
+| `absent` | candidate | no task matches, but something opaque was reached |
+
+**What it cannot see, and therefore never rules out:** a command
+(`shell`/`command`/`script`/`raw`) without a literal `creates`; a module it does
+not model (`apt`, `dnf`, `package`, collections, …); a templated path or a
+`loop`; a role, include or imported playbook that is not in the repository or is
+templated; a file that does not parse. Any of these makes an absence a
+candidate, which is never elected — the requirement stays
+`AGENTDOC_REQUIREMENT_UNVERIFIED` and the diagnostic names what was opaque.
+Inventory files, `group_vars`/`host_vars` and variables are not read.
+
 `asyncapi` is a contract **type** (declared on an API descriptor, validated by
 the contract layer), not an adapter — there is no `asyncapi` entry in
 `adapters: [...]`.

package/docs/AUTHORITY.md

@@ -175,7 +175,16 @@ For a group of assertions on one `(subject, key)`:
    - `recency` — only when the rule names `OBSERVED_RUNTIME` and more than one
      dated observation exists. The newest wins, and the rule is cited.
    - otherwise `basis: none`, status `unresolved`, and an **error**.
-3. Every non-elected assertion is kept with `status: contradicted` (or
+3. **Normative requirements are never elected on their own word.** An
+   assertion from a component's `spec.requirements` (`requirement.*` keys) is a
+   claim about what the implementation *must* do:
+   - alone on its key it stays `unresolved` (`AGENTDOC_REQUIREMENT_UNVERIFIED`);
+   - with agreeing implementation evidence it is corroborated and `elected`;
+   - with disagreeing evidence **no basis is attempted** — not even a
+     `reviewed-override` rule. Electing the implementation would waive the
+     specification; electing the requirement would hide the missing
+     implementation. The conflict is an error until one of them changes.
+4. Every non-elected assertion is kept with `status: contradicted` (or
    `candidate`). **The contradicted value stays in the graph.** A system that
    discards the repository's own claim cannot explain the divergence to a human.
 

package/docs/CI.md

@@ -20,13 +20,15 @@ jobs:
         with: { fetch-depth: 0 }
       - uses: actions/setup-node@v4
         with: { node-version: '24' }
-      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.0.0 —
+      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.1.0 —
       # a compiler upgrade intentionally invalidates every committed graph.
       - run: npm install -g github:lbframe/agent-doc-system
       - run: agentdoc validate
       - run: agentdoc compile
       - run: agentdoc check
       - run: agentdoc check --require-clean
+      # Once MIGRATE is done: no unaccepted warning may remain.
+      - run: agentdoc check --strict
       - run: agentdoc eval routing
 ```