agent-doc-system 1.0.0 → 1.2.0

package/docs/SPEC.md

@@ -237,6 +237,28 @@ The core has no knowledge of folder names. A directory is a unit when it holds
 a component descriptor, when an adapter recognises it from a workspace file, or
 when it is listed in `discovery.supplementalRoots`.
 
+`init` configures the recursive component descriptor glob `*/**/agentdoc.yaml`,
+so descriptors for adapter-discovered units and units added later are loaded
+without regenerating a path list. The scaffold layout scan supplements its
+shallow marker heuristics with adapter discovery: declared workspace members
+under `examples`, `example`, `test`, or `tests`, or beyond the scan depth, remain
+units. Those names alone do not create units. Scaffold selects artifact types
+from adapter shape: deployable (including both shapes) → `service`, importable
+only → `library`, neither → `other`. Placement remains a human choice.
+
+`discovery.notUnitRoots` excludes each listed root and its whole subtree from
+inferred units (adapter markers, adapter `roots()`, and supplemental roots) and
+from scaffold layout scans and descriptor proposals, in both dry run and
+`--write`. The defaults are `agentdoc`, `docs`, `scripts`, `node_modules`, and
+`.github`; a configured list replaces them, and `[]` disables these exclusions.
+An existing authored component descriptor strictly below an excluded root still
+claims that directory as a unit. Its own root must supply the usual adapter
+evidence for its artifact type; the exclusion does not waive corroboration.
+Scaffold preserves that descriptor and never proposes or writes one there.
+A descriptor exactly at an excluded root is refused with
+`AGENTDOC_COMPONENT_UNCORROBORATED` naming the exclusion: remove that root from
+`notUnitRoots` or move the descriptor.
+
 - Every discovered unit must have exactly one descriptor at its root, or
   `AGENTDOC_COVERAGE_ZERO`.
 - Two descriptors at one root, or a descriptor no adapter can corroborate, is an

package/docs/ci/github-actions.yml

@@ -21,7 +21,7 @@ jobs:
         with: { node-version: '24' }
       - name: Install the agentdoc CLI
         # Unpinned tracks main. For CI reproducibility pin a tag or commit:
-        #   github:lbframe/agent-doc-system#v1.0.0
+        #   github:lbframe/agent-doc-system#v1.2.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile

package/evals/harness.mjs

@@ -35,6 +35,7 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
 export function factsFromContext(ctx) {
   const out = new Set();
   out.add(ctx.entity.ref);
+  for (const n of ctx.neighbours) out.add(n.ref);
   for (const r of ctx.relations.items) out.add(r.type + ":" + r.other);
   for (const p of ctx.journeyPeers || []) out.add(p);
   for (const s2 of ctx.placement.systems) out.add(s2);
@@ -76,7 +77,10 @@ export function criticalFromContext(ctx) {
 }
 
 export function verificationFromContext(ctx) {
-  return new Set(ctx.verification.items.map((v) => "verify:" + v.command));
+  // Commands such as `go test ./...` recur in multiple modules. Scenarios can
+  // require a scoped check ID as well as a command to measure dependent checks
+  // without letting the library's identical command satisfy the expectation.
+  return new Set(ctx.verification.items.flatMap((v) => ["verify:" + v.command, "verify-id:" + v.id]));
 }
 
 // ── baseline: unassisted repository exploration ────────────────────────
@@ -154,7 +158,20 @@ export function fullRepositoryContext(graph) {
 // Baseline verification: without routing, an agent runs the union of every
 // check in the repository, because nothing narrows it.
 function baselineVerification(graph) {
-  return new Set(graph.verification.map((v) => "verify:" + v.command));
+  return new Set([...graph.verification, ...graph.gates].flatMap((v) => ["verify:" + v.command, "verify-id:" + v.id]));
+}
+
+export function verificationRecall(retrieved, expected) {
+  const { hit, total } = score(retrieved, expected);
+  return total ? hit / total : 1;
+}
+
+// Count scoped check IDs, not commands: identical commands in different
+// components are separate checks. Gates are repository-scoped checks too.
+export function checkSelectivity(graph, recommendedIds) {
+  const all = new Set([...graph.verification, ...graph.gates].map((v) => v.id));
+  const recommended = [...all].filter((id) => recommendedIds.has(id)).length;
+  return all.size ? recommended / all.size : 1;
 }
 
 function score(retrieved, truth) {
@@ -271,6 +288,10 @@ export function runRoutingEval(root, { json = false } = {}) {
     const retrieved = new Set();
     const critical = new Set();
     const verif = new Set();
+    const recommendedIds = new Set();
+    const collectChecks = (ctx) => {
+      for (const v of [...ctx.verification.items, ...ctx.globalGates]) recommendedIds.add(v.id);
+    };
     let unresolved = 0;
     for (const t of s.touch) {
       let ctx;
@@ -285,13 +306,16 @@ export function runRoutingEval(root, { json = false } = {}) {
       for (const x of factsFromContext(ctx)) retrieved.add(x);
       for (const x of criticalFromContext(ctx)) critical.add(x);
       for (const x of verificationFromContext(ctx)) verif.add(x);
+      collectChecks(ctx);
     }
     // Change impact is part of routing: it is what tells the agent which other
     // components a change reaches. Its output is legitimately part of context.
     const im = impact(graph, s.touch);
+    for (const v of im.recommendedVerification) recommendedIds.add(v.id);
     for (const c of im.affectedComponents) {
       const ctx = queryContext(graph, c.ref, {});
       for (const x of factsFromContext(ctx)) retrieved.add(x);
+      collectChecks(ctx);
     }
 
     const base = baselineContext(graph, s.touch);
@@ -303,8 +327,6 @@ export function runRoutingEval(root, { json = false } = {}) {
     const all = score(retrieved, new Set(s.truth));
     const baseAll = score(base, new Set(s.truth));
     const crit = score(critical, new Set(s.critical));
-    const vf = score(verif, new Set(s.verification));
-    const baseVf = score(baseV, new Set(s.verification));
     const noise = irrelevanceRatio(retrieved, closure);
     const baseNoise = irrelevanceRatio(base, baseClosure);
 
@@ -314,12 +336,14 @@ export function runRoutingEval(root, { json = false } = {}) {
       recall: all.hit / (all.total || 1),
       precision: 1 - noise,
       criticalRecall: crit.total ? crit.hit / crit.total : 1,
-      verificationRecall: vf.total ? vf.hit / vf.total : 1,
+      verificationRecall: verificationRecall(verif, new Set(s.verification)),
+      checkSelectivity: checkSelectivity(graph, recommendedIds),
       noise,
       baseline: {
         recall: baseAll.hit / (baseAll.total || 1),
         noise: baseNoise,
-        verificationRecall: baseVf.hit / (baseVf.total || 1),
+        verificationRecall: verificationRecall(baseV, new Set(s.verification)),
+        checkSelectivity: 1, // The baseline runs every verification entry and gate.
       },
       missed: all.missed.slice(0, 8),
       offClosure: [...retrieved].filter((r) => !closure.has(r)).slice(0, 8),
@@ -340,12 +364,14 @@ export function runRoutingEval(root, { json = false } = {}) {
     precision: round(mean("precision")),
     criticalRecall: round(mean("criticalRecall")),
     verificationRecall: round(mean("verificationRecall")),
+    checkSelectivity: round(mean("checkSelectivity")),
     noise: round(mean("noise")),
     retrievalReduction: 0,
     baseline: {
       recall: round(meanB("recall")),
       noise: round(meanB("noise")),
       verificationRecall: round(meanB("verificationRecall")),
+      checkSelectivity: round(meanB("checkSelectivity")),
     },
   };
   // Size proxy: retrieved fact count versus the whole-repository baseline.

package/evals/scenarios/fixture-b-03-change-shared-lib.json

@@ -5,5 +5,12 @@
   "touch": ["libs/protocol/ledger.pb.go"],
   "truth": ["component:default/protocol", "component:default/ingest", "component:default/gateway", "doc:libs/protocol/README.md"],
   "critical": [],
-  "verification": []
+  "verification": [
+    "verify:go test ./...",
+    "verify:go vet ./...",
+    "verify-id:component:default/gateway:go-test",
+    "verify-id:component:default/gateway:go-vet",
+    "verify-id:component:default/ingest:go-test",
+    "verify-id:component:default/ingest:go-vet"
+  ]
 }

package/evals/scenarios/fixture-c-03-shared-vocabulary.json

@@ -5,5 +5,11 @@
   "touch": ["shared/index.js"],
   "truth": ["component:default/shared", "component:default/edge", "component:default/console", "event:corp.telemetry.ingest.v1"],
   "critical": ["event:corp.telemetry.ingest.v1"],
-  "verification": []
+  "verification": [
+    "verify:vitest run",
+    "verify:tsc --noEmit",
+    "verify-id:component:default/console:test",
+    "verify-id:component:default/console:typecheck",
+    "verify-id:component:default/edge:test"
+  ]
 }

package/evals/scenarios/fixture-e-01-change-shared-lib.json

@@ -0,0 +1,14 @@
+{
+  "id": "e-01",
+  "repository": "fixture-e",
+  "title": "Change the shared engine crate",
+  "touch": ["crates/engine/src/lib.rs"],
+  "truth": ["component:default/engine", "component:default/cli"],
+  "critical": [],
+  "verification": [
+    "verify:cargo test -p engine",
+    "verify:cargo clippy -p engine",
+    "verify:cargo test -p cli",
+    "verify:cargo clippy -p cli"
+  ]
+}

package/evals/scenarios/fixture-e-02-change-manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "e-02",
+  "repository": "fixture-e",
+  "title": "Change the CLI crate manifest",
+  "touch": ["apps/cli/Cargo.toml"],
+  "truth": ["component:default/cli", "component:default/engine", "component:default/testutil", "external:serde"],
+  "critical": [],
+  "verification": ["verify:cargo test -p cli", "verify:cargo clippy -p cli"]
+}

package/evals/scenarios/fixture-e-03-local-module.json

@@ -0,0 +1,9 @@
+{
+  "id": "e-03",
+  "repository": "fixture-e",
+  "title": "Change CLI code that looks like the logging crate and an ambiguous foo_bar import",
+  "touch": ["apps/cli/src/logging.rs", "apps/cli/src/main.rs"],
+  "truth": ["component:default/cli", "component:default/engine"],
+  "critical": [],
+  "verification": ["verify:cargo test -p cli", "verify:cargo clippy -p cli"]
+}

package/evals/scenarios/fixture-e-04-ambiguous-crate.json

@@ -0,0 +1,14 @@
+{
+  "id": "e-04",
+  "repository": "fixture-e",
+  "title": "Change each crate of the foo-bar / foo_bar pair",
+  "touch": ["crates/foo-bar/src/lib.rs", "crates/foo_bar/src/lib.rs"],
+  "truth": ["component:default/foo-bar", "component:default/foo-u-bar"],
+  "critical": [],
+  "verification": [
+    "verify:cargo test -p foo-bar",
+    "verify:cargo clippy -p foo-bar",
+    "verify:cargo test -p foo_bar",
+    "verify:cargo clippy -p foo_bar"
+  ]
+}

package/evals/scenarios/fixture-f-01-change-shared-lib.json

@@ -0,0 +1,9 @@
+{
+  "id": "f-01",
+  "repository": "fixture-f",
+  "title": "Change the shared ledger-core library",
+  "touch": ["libs/ledger-core/src/ledger_core/models.py"],
+  "truth": ["component:default/ledger-core", "component:default/ledger-api"],
+  "critical": [],
+  "verification": ["verify:uv run pytest", "verify:uv run ruff check", "verify:uv run mypy"]
+}

package/evals/scenarios/fixture-f-02-change-manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "f-02",
+  "repository": "fixture-f",
+  "title": "Change the ledger API manifest",
+  "touch": ["services/ledger-api/pyproject.toml"],
+  "truth": ["component:default/ledger-api", "component:default/ledger-core", "component:default/ledger-testing", "external:sqlalchemy"],
+  "critical": [],
+  "verification": ["verify:uv run pytest", "verify:uv run ruff check", "verify:uv run mypy"]
+}

package/evals/scenarios/fixture-f-03-shadowed-import.json

@@ -0,0 +1,9 @@
+{
+  "id": "f-03",
+  "repository": "fixture-f",
+  "title": "Change the app that imports its own utils module",
+  "touch": ["services/b-app/b_app/main.py"],
+  "truth": ["component:default/b-app"],
+  "critical": [],
+  "verification": []
+}

package/evals/scenarios/fixture-f-04-nested-workspace.json

@@ -0,0 +1,9 @@
+{
+  "id": "f-04",
+  "repository": "fixture-f",
+  "title": "Change a nested workspace member, not its parent",
+  "touch": ["python/packages/api/src/api_svc/main.py"],
+  "truth": ["component:default/api-svc", "component:default/core-lib"],
+  "critical": [],
+  "verification": []
+}

package/evals/scenarios/fixture-f-05-alembic-database.json

@@ -0,0 +1,9 @@
+{
+  "id": "f-05",
+  "repository": "fixture-f",
+  "title": "Change the ledger API Alembic migration",
+  "touch": ["services/ledger-api/alembic/versions/0001_init.py"],
+  "truth": ["component:default/ledger-api", "uses:resource:default/ledger-api-postgres"],
+  "critical": ["uses:resource:default/ledger-api-postgres"],
+  "verification": ["verify:uv run pytest", "verify:uv run ruff check", "verify:uv run mypy"]
+}

package/evals/scenarios/fixture-f-06-unittest-job.json

@@ -0,0 +1,9 @@
+{
+  "id": "f-06",
+  "repository": "fixture-f",
+  "title": "Change the ledger job exercised by unittest",
+  "touch": ["jobs/ledger-jobs/tests/test_jobs.py"],
+  "truth": ["component:default/ledger-jobs"],
+  "critical": [],
+  "verification": ["verify:python -m unittest discover"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-doc-system",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Portable documentation and software-catalog system with an explicit authority model, for AI coding agents",
   "keywords": [
@@ -42,6 +42,7 @@
     "schemas",
     "skills",
     "templates",
+    "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md"
   ],
   "license": "MIT"

package/schemas/common.schema.json

@@ -66,6 +66,46 @@
         }
       }
     },
+    "normativeCitation": {
+      "description": "One section of a configured normative document, pinned by the digest it had when it was reviewed. `agentdoc audit` lists every section with its current digest.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "section", "sha256"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repoPath" },
+        "section": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S+$" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "requirementKey": { "type": "string", "maxLength": 80, "pattern": "^requirement\\.[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "requirementValue": { "type": "string", "maxLength": 80, "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "requirement": {
+      "description": "An implementation obligation a normative document places on this component. It is an AUTHORED fact that must be corroborated by implementation evidence on the same key; it never stands on its own word.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "key", "value", "source"],
+      "properties": {
+        "id": { "$ref": "#/$defs/name" },
+        "key": { "$ref": "#/$defs/requirementKey" },
+        "value": { "$ref": "#/$defs/requirementValue" },
+        "source": { "$ref": "#/$defs/normativeCitation" },
+        "satisfiedBy": {
+          "description": "Adapters able to derive the implementation side of this requirement. Named so a missing extractor is reported as such instead of as silence.",
+          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+        },
+        "expects": {
+          "description": "What an adapter in satisfiedBy must find for the requirement to be provided: a host path installed, or a service managed. Without it an adapter has nothing deterministic to compare.",
+          "type": "object",
+          "additionalProperties": false,
+          "oneOf": [{ "required": ["installs"] }, { "required": ["service"] }],
+          "properties": {
+            "installs": { "type": "string", "maxLength": 400, "pattern": "^/[^\\s{}]*[^\\s{}/]$" },
+            "service": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9@._-]+$" }
+          }
+        }
+      }
+    },
     "warningAcceptance": {
       "type": "object",
       "additionalProperties": false,

package/schemas/component.schema.json

@@ -27,7 +27,11 @@
           "description": "Published artifacts or remotes this component is consumed through.",
           "items": { "$ref": "common.json#/$defs/repoPath" }
         },
-        "context": { "$ref": "common.json#/$defs/context" }
+        "context": { "$ref": "common.json#/$defs/context" },
+        "requirements": {
+          "type": "array", "minItems": 1, "maxItems": 64,
+          "items": { "$ref": "common.json#/$defs/requirement" }
+        }
       },
       "oneOf": [
         { "required": ["system"], "not": { "anyOf": [{ "required": ["domain"] }, { "required": ["placementRationale"] }] } },

package/schemas/config.schema.json

@@ -358,7 +358,8 @@
               "capability",
               "component-placement",
               "event-producer",
-              "event-consumer"
+              "event-consumer",
+              "requirement-satisfaction"
             ]
           },
           "subject": {
@@ -416,6 +417,12 @@
             "minLength": 1,
             "maxLength": 200
           },
+          "key": {
+            "$ref": "common.json#/$defs/requirementKey"
+          },
+          "value": {
+            "$ref": "common.json#/$defs/requirementValue"
+          },
           "reason": {
             "$ref": "common.json#/$defs/rationale"
           },
@@ -633,6 +640,59 @@
                 ]
               }
             }
+          },
+          {
+            "if": {
+              "properties": {
+                "fact": {
+                  "const": "requirement-satisfaction"
+                }
+              },
+              "required": [
+                "fact"
+              ]
+            },
+            "then": {
+              "required": [
+                "key",
+                "value"
+              ],
+              "not": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "target"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "transport"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "role"
+                    ]
+                  }
+                ]
+              }
+            },
+            "else": {
+              "not": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "key"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "value"
+                    ]
+                  }
+                ]
+              }
+            }
           }
         ]
       }
@@ -644,6 +704,51 @@
         "$ref": "common.json#/$defs/warningAcceptance"
       }
     },
+    "normativeCoverage": {
+      "description": "Reviewed attestations that a normative section carries no implementation obligation. Pinned by the section digest; a changed section invalidates its attestation and forces a fresh review.",
+      "type": "array",
+      "maxItems": 2048,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "section",
+          "sha256",
+          "disposition",
+          "reason",
+          "reviewWhen"
+        ],
+        "properties": {
+          "path": {
+            "$ref": "common.json#/$defs/repoPath"
+          },
+          "section": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "pattern": "^\\S+$"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "disposition": {
+            "enum": [
+              "no-implementation-obligation",
+              "informative"
+            ]
+          },
+          "reason": {
+            "$ref": "common.json#/$defs/rationale"
+          },
+          "reviewWhen": {
+            "type": "string",
+            "minLength": 12
+          }
+        }
+      }
+    },
     "output": {
       "type": "object",
       "additionalProperties": false,
@@ -678,6 +783,17 @@
         },
         "runbookDir": {
           "$ref": "common.json#/$defs/repoPath"
+        },
+        "normative": {
+          "description": "Globs of normative documents (specifications, technical profiles). Every level-2 section of a matched Markdown document must be cited by a component requirement or attested in normativeCoverage; otherwise AGENTDOC_NORMATIVE_UNCOVERED.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       }
     }

package/skills/agent-doc-system/SKILL.md

@@ -96,7 +96,11 @@ not work around it: run `agentdoc compile`, review the diff, commit the graph.
 - **Never hand-edit `.agentdoc/graph.json`.** The gate rejects it, and it would
   be wrong anyway.
 - **Do not trust existing documentation.** In MIGRATE it is evidence of what
-  someone once believed; the audit says where that belief contradicts the code.
+  someone once believed. The audit flags only a narrow set of contradictions
+  automatically (negated components, port claims); it does not read prose for
+  meaning. Obligations in specifications are checked only once declared:
+  configure `docs.normative`, turn every section into a component requirement
+  or a reviewed attestation, and finish with `agentdoc check --strict`.
 
 ## Deeper references
 

package/skills/agent-doc-system/references/cli.md

@@ -5,13 +5,18 @@ operates on a catalog can be run from any subdirectory of the repository: the
 configuration is found by walking up to `agentdoc/agentdoc.config.yaml`. No
 command ever needs the agentdoc source tree or a path to it.
 
-Exit codes: `0` ok, `1` failure, `2` usage.
+Exit codes: `0` ok, `1` failure, `2` usage. Flags are declared per command:
+an unknown or misspelled flag is a usage error (`2`), with a suggestion when
+one is close — it is never silently ignored, so `check --strcit` cannot pass
+for `check --strict`. `agentdoc <command> --help` lists exactly what a command
+accepts.
 
 ## Meta
 
 ```bash
 agentdoc --version          # installed version
-agentdoc --help             # command list (also: agentdoc <command> --help)
+agentdoc --help             # command list
+agentdoc <command> --help   # every flag of one command (also: agentdoc help <command>)
 agentdoc doctor             # machine check: is this CLI install healthy
 agentdoc doctor --project   # the same, plus the current project's catalog health
 ```
@@ -42,13 +47,16 @@ failures as part of its output.
 ```bash
 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]
 ```
 
 `compile` writes `.agentdoc/graph.json` (or the path in `output.graph`).
 `check` is the gate: it fails on a stale or hand-edited graph, a compiler or
 schema version mismatch, an observation past its declared `maxAgeDays`, and —
-with `--require-clean` — catalog inputs that differ from `HEAD`.
+with `--require-clean` — catalog inputs that differ from `HEAD`. With
+`--strict` it also fails on every warning not accepted in `warningAcceptances`
+— the gate that ends a MIGRATE (unreviewed normative sections, unproven
+requirements, orphan documents).
 
 ## Query and impact
 

package/skills/agent-doc-system/references/create-migrate.md

@@ -40,9 +40,19 @@ never copies the agentdoc implementation into the repository.
 In `agentdoc.config.yaml`:
 
 - Set `namespace`, fix `discovery.componentDescriptors` to match the real
-  layout, and enable the adapters for the technologies present. `adapters: []`
-  is a valid but useless starting point: with no adapter, a component
-  descriptor is an unsupported claim and compilation fails on purpose.
+  layout, and enable the adapters for the technologies present. `init`
+  pre-selects the language and deployment adapters whose manifests it finds:
+  `node`, `go`, `rust` and `python`, plus `dockerfile` and `wrangler`. It also
+  adds `database`, `openapi`, `events` and `github-actions`. Add the rest
+  (`pnpm`, `turborepo`, `typescript`, `protobuf`, `graphql`, `ansible`, …) when
+  the repository uses them. `adapters: []` is a valid but useless starting
+  point: with no adapter, a component descriptor is an unsupported claim and
+  compilation fails on purpose.
+- An existing catalog does not gain new adapters on upgrade. After upgrading
+  the CLI, compare `adapters:` with the technologies present, for example a
+  repository with `Cargo.toml` or `pyproject.toml` units and no `rust` /
+  `python` entry. Then run `agentdoc audit`: newly visible units appear as
+  `AGENTDOC_COVERAGE_ZERO` until they have a descriptor.
 - Three example authority rules are written **commented out**. Uncomment only
   the ones you can justify, with the rationale in your own words. An authority
   rule is a governance decision; the scaffolder does not make it for you.
@@ -81,8 +91,14 @@ agentdoc audit > migration-report.json
 
 Then, in order:
 
-1. **Source-of-truth mapping.** For each major claim, record which inventory
-   supports it. Anything supported by none goes to `reviewedAmbiguity`.
+1. **Source-of-truth mapping.** Set `docs.normative` to the specifications and
+   profiles, then empty `normative.uncovered`: each section becomes a
+   `spec.requirements` entry on the component that must fulfil it, or a
+   `normativeCoverage` attestation that it obliges nothing. Prove each
+   requirement (adapter evidence or a `requirement-satisfaction` override);
+   an unproven one stays `REQUIREMENT_UNVERIFIED`. For other major claims,
+   record which inventory supports them; anything supported by none goes to
+   `reviewedAmbiguity`.
 2. **Contradictions.** Work `contradictions` and `documentationContradictions`.
    Each needs a human decision: fix the docs, fix the code, or add an authority
    rule saying which class wins for that key.
@@ -91,7 +107,13 @@ Then, in order:
 5. **Stale contracts.** Point the API descriptor at the current contract file.
 6. **Ownership.** Placement from code where unambiguous, from a human elsewhere.
 7. **Catalog.** `scaffold --write`, review every generated file.
-8. **Gate.** `validate` → `compile` → `check`, then install CI.
+8. **Gate.** `validate` → `compile` → `check --strict`, then install CI. Strict
+   fails on any unaccepted warning: an unreviewed section or an unproven
+   requirement cannot ship in a "complete" migration.
+
+**The audit does not read prose for meaning.** It checks only negated
+components and port claims automatically; every other documented obligation is
+caught only if it is declared as a requirement.
 
 **Do not trust existing documentation.** The single most common migration
 failure is copying existing prose into descriptions. If you cannot write a