agent-doc-system 1.0.0 → 1.2.0

package/docs/ADAPTERS.md

@@ -43,9 +43,18 @@ 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 |
-| `unitByPkgName`, `unitByGoModule` | cross-unit resolution built before extraction |
+| `requirements` | declared normative requirements (`subject`, `key`, `value`, `source`, `satisfiedBy`, `expects`) an adapter may derive the implementation side of |
+| `unitByPkgName`, `unitByGoModule`, `unitByCrateName` | cross-unit resolution built before extraction |
+| `unitByPythonDist`, `unitByPythonImport` | Python distribution names (PEP 503) and import names, built before extraction |
 | `errors.push({ code, message })` | a hard error, collected rather than thrown |
 
+For per-unit source inventories, use `sourceFiles(repo, unit.root)` or
+`repo.walkUnit(unit.root, directory = unit.root)`. Discovery computes ownership
+once from eligible units: these scans prune nested unit roots, so a file belongs
+only to its deepest enclosing unit. `repo.ownsUnitPath(unit.root, path)` applies
+the same boundary to custom traversals. Keep `repo.walk` for repository-wide
+discovery and authored inputs; explicit cross-unit references can still be read.
+
 ## The three rules
 
 ### 1. An adapter may not know the repository
@@ -89,10 +98,12 @@ cannot name the file a fact came from, you cannot add the fact.
 | `turborepo` | `turbo.json` (nearest ancestor) | per-package task commands |
 | `typescript` | `tsconfig.json` | language, project references, file-router routes |
 | `go` | `go.mod`, `go.work` | module roots, module graph, `go test`/`go vet` |
+| `rust` | `Cargo.toml` (`[package]`), workspace `members` (including a workspace below the repository root) | crate roots, path, workspace, and `[patch]`/`[replace]` dependency edges, `cargo test`/`cargo clippy` |
+| `python` | `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements*.txt` | distribution graph, import edges, evidence-backed test and static commands |
 | `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 +111,207 @@ 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.
 
+### `github-actions`
+
+Recognizable test, lint and build invocations in `run` steps contribute
+checks. The executable and task determine the tier; a shell `test`, a step
+name or text printed by `echo` does not. Turbo (including package-manager
+wrappers), Nx (`run`, `run-many`, `affected`), Make and Just tasks are resolved
+by task name. Multi-task commands contribute a check for each distinct tier.
+Repository scripts invoked directly (`./scripts/test.sh`) or through `bash`,
+`sh`, `node`, `python` or `python3` also contribute checks when their basename,
+without its extension, matches the task vocabulary (`test`, `lint`, `check`,
+`typecheck`, `build`, `e2e`, `integration`, `contract`, etc.). The script must
+resolve to a literal file inside the repository, relative to the current
+step directory. Its path and arguments use the same scope rules as other
+invocations; without component scope it is a repository gate. Scripts with
+other names, such as `deploy.sh`, are ignored. Script contents are not executed
+or interpreted.
+Simple scripts are split into individual commands, never copied wholesale or
+truncated. A literal `cd` updates the directory for following commands in the
+same step, including across lines. Shell control flow, pipelines,
+substitutions and heredocs are not interpreted; a non-literal `cd`, directory
+stack operation, `source`, `eval` or `export` stops extraction for that step.
+
+`uses` actions whose names contain lint, test, check, scan or audit also
+contribute checks. Setup, checkout, cache, upload, download and artifact
+actions are excluded. Action scope comes from `with.working-directory`,
+`with.working_directory` or `with.path`; run-step defaults do not apply. The
+action reference is recorded as its command, with the workflow as its evidence.
+
+Scope comes from the step's `working-directory` (including job and workflow
+defaults), a component path argument, an explicit package selector, or a
+workflow trigger's `paths` filter with a literal directory prefix. Paths match
+whole segments; a mention in another step cannot scope a check. Turbo filters
+match literal package names or directory paths; Nx project selectors match a
+package name, `project.json` name or component root; Make's `-C` resolves a
+directory relative to the step's working directory. Unscoped checks are
+repository gates. A working directory is retained in the recorded
+command so the check can be run from the repository root.
+
+`impact` on a workflow follows its recorded check configuration paths to the
+covered components, which seed the same reverse build/test dependency closure
+as directly changed components. Their own checks precede their dependents'
+checks, with test-only routes contributing only unit checks. Repository gates
+from that file appear in `affectedGates` and are appended after component
+checks in `recommendedVerification`. The combined list is capped at 25;
+`recommendedVerificationTotal` and `recommendedVerificationTruncated` include
+gates. A workflow matched by a check or gate is removed from `unmatchedFiles`.
+
+### `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.
+
+### `rust`
+
+Reads `Cargo.toml`. A `[package]` is a unit. A virtual workspace manifest (only
+`[workspace]`) is not. Nothing is executed, and `Cargo.lock` is not read.
+
+| it derives | from |
+|---|---|
+| `languages: rust`, `runtimes: rust` | the package manifest |
+| deployable | `[[bin]]`, `src/main.rs`, or a `src/bin/` directory |
+| importable | `[lib]` or `src/lib.rs`; both shapes when both are present |
+| `buildDependsOn` | `[dependencies]`, `[build-dependencies]`, and `[target.<cfg>.dependencies]` / `[target.<cfg>.build-dependencies]`, when the entry is a `path`, `workspace = true` resolved through the nearest `[workspace.dependencies]`, or a `[patch.<registry>]` / `[replace]` path redirect to a sibling inside the repository. A production `use`, `extern crate`, or `<crate>::` path (`-` and `_` are the same ident) adds provenance to that edge; it never creates one |
+| `testDependsOn` | `[dev-dependencies]` and target-specific dev-dependencies, resolved the same way |
+| `hasTests` | a `tests/` directory, or `#[test]` / `#[cfg(test)]` in a `.rs` file |
+| verification | `cargo test -p <name>` (unit) and `cargo clippy -p <name>` (static) |
+
+`-p <name>` is the whole scope of the recorded command. Cargo, run at a virtual
+workspace root, has no current package; `-p` is what makes the command mean
+this crate rather than every member. `configPaths` is that crate's
+`Cargo.toml`.
+
+Workspace roots come from every `Cargo.toml` that has `[workspace]`, not only
+the one at the repository root. The search is bounded to five directories
+down, stays inside the repository, and does not enter `discovery.notUnitRoots`
+or their descendants (the authored-descriptor exception is described below),
+`discovery.generatedDirs`, dot-directories, or `test` / `tests` / `examples` /
+`example`. `members` minus `exclude` are still relative to the manifest that
+declares them; `*` matches one path segment, and a member that leaves the
+repository is ignored. `workspace = true` resolves against the nearest
+enclosing workspace. A virtual manifest (no `[package]`) is not a unit and is
+not scaffolded. A manifest that has both `[package]` and `[workspace]` is a
+unit, the same as any other package. Scaffold types a crate from its shape: deployable-only
+(`[[bin]]`, `src/main.rs`, `src/bin/`) is `service`, importable-only is
+`library`, and a crate that is both follows the usual rule (deployable wins,
+so `service`).
+
+The manifest route and a corroborating import share the target crate's
+package name as their edge key, so one dependency is one edge. A rename
+(`package = "…"`) is the crates.io name; the `use` path is the table key.
+`[patch.<registry>]` and `[replace]` contribute only when the value is a
+`path` that stays inside the repository and the package is already a
+dependency. A path and a patch that name two different siblings is
+`AGENTDOC_BINDING_AMBIGUOUS` and no edge is created.
+
+**What it cannot see, and therefore never invents:** a dependency that exists
+only as a `use`, `extern crate`, or `<crate>::` path. Rust will not link a
+crate the manifest does not declare, and a local module (`mod engine;
+engine::run()`) is the same spelling as a crate path, so an import that the
+manifest did not already resolve creates no edge. An import whose ident
+matches two sibling crates (`foo-bar` and `foo_bar` are both `foo_bar`) is
+`AGENTDOC_BINDING_AMBIGUOUS` and still creates no edge. Also invisible: a
+`Cargo.lock` resolution or any version requirement that merely shares a name
+with a sibling; a workspace member outside the repository; a workspace
+manifest deeper than the search bound; a `#[cfg(test)]` or `#[test]` item,
+which is not a production import; a duplicate package name, which is not
+elected either. A `Cargo.toml` this TOML reader rejects yields
+`AGENTDOC_YAML_PARSE` and no dependency edges. The unit is still recognised when a `[package]` header is present, so
+a parse failure is not an empty unit and not a crash. Char literals and
+lifetimes are not strings: a lifetime does not hide the imports after it, and
+a `"` string that spans lines does not leak the idents inside it.
+
+### `python`
+
+Reads a unit's Python manifest and its `import` / `from` statements. It does
+not run Python, resolve a lockfile, or inspect a virtualenv.
+
+| it derives | from |
+|---|---|
+| deployable | `[project.scripts]`, `[project.gui-scripts]`, `[tool.poetry.scripts]`, a `console_scripts` entry point, `__main__.py`, `manage.py`, or an ASGI/WSGI app object (`app` / `application` assigned from `FastAPI`, `Flask`, `Starlette`, `Litestar`, `Sanic` or `Quart`, or a call to `get_asgi_application` / `get_wsgi_application`) |
+| importable | a build backend (`[build-system] build-backend`, or `setup.py` / `setup.cfg`) and a package |
+| the import name | an explicit package list (`[tool.setuptools] packages`, `[tool.poetry] packages`, `[tool.hatch.build.targets.wheel] packages`); otherwise the distribution name with `-` turned into `_` when that directory exists; otherwise the only package directory |
+| `buildDependsOn` | `[project] dependencies`, `[tool.uv.sources]` (`path`, or `workspace = true` resolved against the nearest enclosing uv workspace), Poetry `path`, `-e <dir>` in a production `requirements*.txt`, or a production `import` / `from` of a sibling's import name |
+| `testDependsOn` | `[dependency-groups]`, `[project.optional-dependencies]` groups named dev/test/lint/type, `[tool.poetry.group.*]`, or a requirements file whose name contains `dev` or `test` |
+| `languages` / `runtimes` | the manifest. `requiresPython` only when `requires-python`, `python_requires`, or Poetry's `python` dependency is written down |
+| `pytest` | a pytest dependency or group, `[tool.pytest.ini_options]`, `pytest.ini`, or `conftest.py` |
+| `python -m unittest discover` | test modules that import `unittest`, and only when nothing above proves pytest |
+| `ruff check` / `mypy` | the tool declared as a dependency or configured (`[tool.ruff]`, `ruff.toml`, `[tool.mypy]`, `mypy.ini`) |
+
+`uv run` or `poetry run` is prefixed only when that lockfile contains a
+`name = "<tool>"` entry. Both lockfiles proving the same tool is ambiguous:
+the command is left unprefixed. PEP 508 extras, versions and markers are
+parsed and not evaluated. Two import packages and no explicit list, or two
+units publishing the same distribution or import name, produce
+`AGENTDOC_BINDING_AMBIGUOUS` and no cross-unit link.
+
+An import under `if TYPE_CHECKING:` is still an import. The adapter does not
+evaluate control flow, so the name is classified like any other import:
+`buildDependsOn` when it resolves to a sibling, or `testDependsOn` when the
+manifest puts that distribution in a dev group. It is not a separate edge.
+
+A uv workspace manifest is read at the repository root and below it, to a
+fixed depth, in path order, staying inside the repository. `notUnitRoots`, their
+descendants, and generated directories are not searched; the authored-descriptor
+exception is described below. `workspace = true` names the member of
+the nearest enclosing workspace whose distribution name matches; another unit
+with the same name is not substituted. Every declared member that has a Python
+manifest is a unit, including one with no build backend and no entrypoint.
+Its shape is still only the evidence, so scaffold writes `other` when the
+manifest is neither deployable nor importable. A manifest that only declares
+the workspace, with no distribution of its own, is not a unit.
+
+A `.py` file uses the shared source inventory and is indexed for the deepest
+eligible unit that contains it. Package, entrypoint and test discovery use the
+same ownership boundaries; workspace-member discovery remains repository-wide. A
+parent unit does not gain an import edge from a file that lives in a nested
+member.
+
+An import is not evidence of a sibling when the importing unit itself provides
+that top-level module or package — at the unit root, under `src/`, or in the
+importing file's own directory. If a sibling publishes the same import name,
+the result is `AGENTDOC_BINDING_AMBIGUOUS` and no edge.
+
+**What it cannot see:** a namespace package with no `__init__.py`; a
+`setup.py` dependency that is not a list of string literals; a `requirements`
+file pulled in with `-r` / `-c`; a lockfile's resolved versions; a PDM
+workspace; a workspace manifest deeper than the search bound.
+
 `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: [...]`.
@@ -151,16 +359,33 @@ vocabulary. It does, however, know the shape of a manifest filename in three
 places, and those are the honest exceptions worth naming:
 
 - `core/compile.mjs` builds a manifest pre-pass over `package.json`, `go.mod`
-  and `go.work`, so `unitByPkgName`, `unitByGoModule` and
+  and `go.work`, and, when the `rust` adapter is enabled, over `Cargo.toml`.
+  `unitByPkgName`, `unitByGoModule`, `unitByCrateName` and
   `transitiveDependencies` are available to every adapter regardless of
-  execution order.
+  execution order. Cargo is probed only when `rust` is enabled: an existence
+  probe is part of the input hash, and probing `Cargo.toml` in every unit
+  would change every graph that does not ask for it.
+- The same pre-pass reads a Python manifest (`pyproject.toml`, otherwise
+  `setup.cfg` / `setup.py` / `requirements*.txt`) into `unitByPythonDist` and
+  `unitByPythonImport`, and feeds those siblings into `dependencyMap` and
+  `productionDependencies`, only when the `python` adapter is enabled. Each
+  unit root is then listed so `requirements*.txt` is visible; that listing is
+  part of the input hash. A repository that does not enable `python` is not
+  probed, and its graph does not change.
 - `core/impact.mjs` classifies a changed file by consulting the compiled graph —
   its contracts, its provenance paths, its extractor identities — rather than a
   hand-written list of technology filenames. A list would silently under-report
   for every repository that is not Node-and-Go.
-- `core/discover.mjs` has a default list of directories that are never units
-  (`agentdoc`, `docs`, `scripts`, `.github`), overridable through
-  `discovery.notUnitRoots`.
+- `core/discover.mjs` excludes `agentdoc`, `docs`, `scripts`, `node_modules`, and
+  `.github` by default. `discovery.notUnitRoots` replaces that list (`[]`
+  disables it). These roots and their descendants cannot be inferred from
+  adapter markers, adapter `roots()`, or supplemental roots, and scaffold never
+  proposes or writes descriptors there in dry run or `--write`. An existing
+  authored descriptor strictly below an excluded root still claims a unit and
+  is preserved; the adapter must corroborate its artifact type at that unit's
+  own root as usual. A descriptor exactly at an excluded root is refused with
+  `AGENTDOC_COMPONENT_UNCORROBORATED` naming `notUnitRoots` and asking the author
+  to remove the exclusion or move the descriptor.
 
 Each is a place a future change should push outward, not a licence to add more.
 

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/BENCHMARK.md

@@ -0,0 +1,68 @@
+# BENCHMARK
+
+Two measurements back the numbers in the README. Both are reproducible from a
+checkout. Neither involves a model, so phrasing cannot move them.
+
+## Routing quality: `node evals/run-all.mjs`
+
+The routing evaluation is described in [EVALS.md](EVALS.md). It has 30 scenarios
+on six repositories (Node, TypeScript, Go, Rust and Python), with thresholds
+registered on 2026-09-28 and not moved since. For each scenario, it compares
+the context `agentdoc query` + `agentdoc impact` returns with what an agent
+gets by reading only the component it is changing.
+
+| | reading the touched component | AgentDoc |
+|---|---|---|
+| facts the change needs, retrieved | 58% | **100%** |
+| retrieved facts that are unrelated (noise) | 40% | **8.7%** |
+| share of the repository's checks returned (selectivity) | 100% | **46%** (29% on the golden corpus) |
+| context size vs. reading the whole catalog | — | **−70%** |
+
+Every check a scenario requires is in AgentDoc's answer (verification recall
+1.0). The baseline never misses one either, because it runs every check in the
+repository. Selectivity is therefore the meaningful comparison: the share of
+the repository's checks the answer contains, counting everything the agent is
+shown. It is reported, not gated; small corpora inflate it, and a
+one-component corpus scores 100% because there is nothing to narrow.
+
+The size reduction is measured on the golden corpus (`examples/koda`). The
+smaller fixtures hold fewer than 100 facts, so the harness reports their
+reduction but does not aggregate it.
+
+## Fresh setup on public repositories: `node scripts/bench/run.mjs`
+
+[`scripts/bench/run.mjs`](../scripts/bench/run.mjs) clones each repository in
+[`repos.json`](../scripts/bench/repos.json) at a pinned commit, then does the
+following:
+
+1. Runs `agentdoc init` and `agentdoc scaffold --write`.
+2. Fills in the one line AgentDoc refuses to decide: each component's placement.
+3. Counts every other edit a human would need before the catalog validates. That
+   number is the "setup ok" column, and the target is zero.
+4. Compiles three times, and checks that the graph is byte-identical.
+5. For each component with a matching file, samples the first tracked source
+   file whose path does not contain `test` (benchmarks and examples may be
+   included). It measures the `agentdoc query` answer, at about 4 characters per
+   token, and the `agentdoc impact` result.
+
+Measured with AgentDoc 1.2.0 on Node 24, on a 2019 Intel Core i9 laptop (load average about 4):
+
+| repository | files | setup ok | components | dependency edges | checks | init + scaffold + median compile | median compile | deterministic | `query` answer, median / max |
+|---|---|---|---|---|---|---|---|---|---|
+| [tokio-rs/axum](https://github.com/tokio-rs/axum) @ 86aa615 (Rust) | 505 | yes | 4 | 11 | 9 | 1.0 s | 0.5 s | yes | ~151 / 153 tokens |
+| [pydantic/pydantic-ai](https://github.com/pydantic/pydantic-ai) @ 5a4d576 (Python, TS) | 5,142 | yes | 8 | 9 | 5 | 4.6 s | 1.9 s | yes | ~112 / 144 tokens |
+| [fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) @ f4bcfab (Python, TS) | 252 | yes | 3 | 0 | 9 | 1.0 s | 0.4 s | yes | ~100 / 126 tokens |
+| [t3-oss/create-t3-turbo](https://github.com/t3-oss/create-t3-turbo) @ 8f945b7 (TypeScript) | 141 | yes | 13 | 47 | 25 | 1.0 s | 0.4 s | yes | ~158 / 263 tokens |
+
+Timings depend on the machine and its load, so run the script yourself. The
+other columns are deterministic for a given AgentDoc version and commit.
+
+### What these numbers do not say
+
+- A `query` answer is a map of what to read, what the change reaches, and which
+  checks to run. It does not replace the code, so its size is not a "tokens
+  saved" figure.
+- "Checks" counts the commands AgentDoc can prove from the repository. For
+  example, pydantic-ai's tests live outside the package roots, so AgentDoc
+  records none for those packages rather than guess one.
+- Four repositories are a smoke test of the setup path, not a survey.

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.2.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
 ```
 

package/docs/EVALS.md

@@ -30,11 +30,35 @@ is deterministic and cannot be moved by phrasing.
 |---|---|
 | recall | fraction of the scenario's ground-truth facts the catalog retrieved |
 | critical recall | the same, restricted to critical context: constraints, conflicts, observations, resources, API boundaries, event subjects |
-| verification recall | fraction of the checks that must be run, that were returned |
+| verification recall | fraction of the scenario's verification expectations returned; 1 when there are no expectations, for both catalog and baseline |
+| check selectivity | distinct recommended check IDs / distinct check IDs in the repository graph (`verification` + `gates`); reported only, not gated; lower means fewer checks recommended |
 | precision | `1 - irrelevance` |
 | irrelevance (noise) | fraction of retrieved facts outside the graph's one-hop closure of the touched entities |
 | retrieval reduction | `1 - catalog facts / baseline-full facts` |
 
+Scenario verification expectations accept `verify:<command>` and
+`verify-id:<check-id>`. Use check IDs when multiple components have the same
+command (for example `go test ./...`), so the library's own check cannot stand in
+for a dependent's. Retrieved context includes the entity refs already returned
+in query's neighbour summaries, even when those neighbours are dependencies and
+therefore absent from impact's affected components.
+
+Check selectivity counts the union of checks returned by queries for touched
+and impact-affected entities (`verification.items` and `globalGates`), plus
+impact's `recommendedVerification`. It measures the returned lists, respecting
+their output caps. IDs deduplicate repeated recommendations while preserving
+separate scoped checks that happen to share a command. With no checks in the
+graph, selectivity is 1 (there is nothing to narrow). Corpus values are scenario
+means; the aggregate is scenario-weighted across corpora. Both CLI reports
+include per-scenario values in their `--json` output.
+
+Baseline verification recall is 1 by construction: its verification strategy
+runs every graph verification entry and repository gate, so it cannot miss a
+registered expectation. Empty expectations also score 1 on both sides. Its
+check selectivity is therefore 1. Selectivity is the meaningful comparison of
+how much routing narrows the check set, read alongside catalog verification
+recall so that omitting a required check is not mistaken for an improvement.
+
 ### Why noise is measured against reachability, not against the truth set
 
 The first definition of noise was the complement of truth recall. It is
@@ -101,6 +125,8 @@ Two additional gates use the same numbers:
 | `fixtures/a-node-ts-postgres` | 3 | single Node/TypeScript service, REST, Postgres, GitHub Actions |
 | `fixtures/b-go-multi-service` | 4 | multi-service Go, protobuf contracts, shared library, resources |
 | `fixtures/c-alt-monorepo` | 4 | a layout that is deliberately not `apps`+`packages`+`workers`, mixed runtimes, inconsistent pre-existing documentation |
+| `fixtures/e-rust-workspace` | 4 | Cargo workspace, shared crate and its dependent, member manifest, local module, ambiguous crate names |
+| `fixtures/f-python-workspace` | 6 | uv workspace, shared library and its dependent, member manifest, shadowed import, nested workspace, Alembic database, unittest |
 
 Scenarios are repository-scoped: a scenario only runs against the corpus it was
 written for, declared by a `repository` tag in a `.agentdoc-fixture.json` at the
@@ -117,7 +143,12 @@ cron; debug a production mismatch.
 The synthetic fixtures add: change an API contract; change a write path; change
 the only-writer rule; break an end-to-end journey; change an edge worker's flush
 schedule; follow stale documentation while debugging; change a subject vocabulary
-shared across runtimes; add an operation to a contract.
+shared across runtimes; add an operation to a contract. The Rust workspace adds
+a shared crate, the manifest that declares its dependents, a local module that
+shares a name with another crate, and a hyphenated crate beside its underscored
+twin. The Python workspace adds a shared library, a service manifest, an import
+shadowed by a local module, a nested workspace member, an Alembic migration
+bound to its database, and a job whose check is `python -m unittest discover`.
 
 ## Running it
 

package/docs/MIGRATION.md

@@ -41,6 +41,7 @@ independently:
   "counts":     { "CONFIRMED": 4, "DERIVED": 38 },
   "contradictions": [ ... ],
   "documentationContradictions": [ ... ],
+  "normative":  { "sections": [ { "path", "section", "heading", "sha256", "coveredBy" } ], "uncovered": [ ... ], "requirements": [ ... ] },
   "reviewedAmbiguity": [ ... ],
   "documentation": { "orphanDocs", "undocumentedComponents", "unverifiedComponents" },
   "contracts":  { "inventory", "unclaimed" },
@@ -77,6 +78,64 @@ be checked at all.
 The rule for extending this: only check vocabulary the graph owns. A check that
 guesses is a check that cries wolf.
 
+**These are the only automatic documentation checks.** The audit does not read
+prose for meaning, so it does not find where an arbitrary sentence contradicts
+the code. A specification saying "the verifier runtime is installed on the
+production host" is invisible to it until someone turns that sentence into a
+requirement — which is what the next section makes mandatory.
+
+### Normative requirements
+
+A specification that is linked to a component is *routed*; that says nothing
+about whether anyone checked the implementation against it. List the documents
+that state obligations in `docs.normative`:
+
+```yaml
+docs:
+  normative:
+    - specs/**
+    - verification_layer/*_PROFILE.md
+```
+
+Every level-2 (`##`) section of those documents is then pinned by digest and
+must be accounted for in one of two ways:
+
+- **a requirement** on the component that must fulfil it, citing the section:
+
+  ```yaml
+  # provisioning/agentdoc.yaml
+  spec:
+    requirements:
+      - id: verification-runtime-on-host
+        key: requirement.provides.verification-runtime
+        value: provided
+        source:
+          path: specs/EXECUTION_LAYER_SPEC.md
+          section: 13-host-configuration
+          sha256: <digest from `agentdoc audit` → normative.sections>
+        satisfiedBy: [ansible]
+        expects:
+          installs: /var/lib/agent-platform-runtime/verification-python-v1
+  ```
+
+- **an attestation** in `normativeCoverage` that the section carries no
+  implementation obligation (`disposition: no-implementation-obligation` or
+  `informative`), with a reason and a review condition.
+
+A section that is neither raises `AGENTDOC_NORMATIVE_UNCOVERED`. A requirement
+is an `AUTHORED` fact that can only be *corroborated*: until implementation
+evidence on the same key agrees with it — a `DERIVED` fact from an adapter
+named in `satisfiedBy` that finds what `expects` names (see `ADAPTERS.md`,
+`ansible`), or a
+`requirement-satisfaction` reviewed override citing the implementation — it is
+`UNRESOLVED` and raises `AGENTDOC_REQUIREMENT_UNVERIFIED`, naming the adapter in
+`satisfiedBy` that is missing. Implementation evidence that disagrees is a
+conflict no authority rule may settle (see `AUTHORITY.md`). Editing a cited
+section invalidates its requirement or attestation
+(`AGENTDOC_NORMATIVE_SOURCE_STALE`): the review has to be redone.
+
+A missing adapter lowers coverage; it never makes an obligation disappear.
+
 ### Reviewed ambiguity
 
 The list a human must work through:
@@ -88,6 +147,8 @@ The list a human must work through:
 | `UNCLAIMED_CONTRACT` | which API owns this contract, or is it dead? |
 | `REVIEWED_OVERRIDE` | is this interpretation still true? |
 | `NEGATED_COMPONENT`, `PORT_MISMATCH`, `UNLINKED_PORT_CLAIM` | which source is right? |
+| `NORMATIVE_UNCOVERED` | what does this section oblige, and which component must do it? |
+| `REQUIREMENT_UNVERIFIED` | where is the implementation — or is this a gap to fix before release? |
 
 ## CREATE
 
@@ -132,16 +193,21 @@ agentdoc audit > migration-report.json
 
 Then, in order:
 
-1. **Source-of-truth mapping.** For each major claim, record which of the four
-   inventories supports it. Anything supported by none goes to
-   `reviewedAmbiguity`.
+1. **Source-of-truth mapping.** Configure `docs.normative`, then work
+   `normative.uncovered`: every section of every normative document becomes a
+   component requirement or a reviewed attestation. Prove each requirement
+   with implementation evidence, or leave it `REQUIREMENT_UNVERIFIED` for a
+   human. For other major claims, record which of the four inventories
+   supports them; anything supported by none goes to `reviewedAmbiguity`.
 2. **Contradiction detection.** Work `contradictions` and
    `documentationContradictions`. Each one needs a human decision: fix the
    documentation, fix the code, or record an authority rule saying which class
    wins for that key.
 3. **Orphan documentation.** `documentation.orphanDocs`. For each: link it to a
-   component via `context.docs`, or delete it. An orphan is a document nothing
-   will ever route to.
+   Component, Resource or System via `context.docs`, `context.constraints` or
+   `context.runbooks`, or delete it. Conventional component documents and
+   configured repository-wide roles also count as routed. An orphan is a
+   document nothing will ever route to.
 4. **Missing documentation.** `documentation.undocumentedComponents` and
    `documentation.unverifiedComponents`. These are the components an agent will
    get wrong.
@@ -152,7 +218,11 @@ Then, in order:
    from a human everywhere else.
 7. **Catalog proposal.** `scaffold` lists what it would write.
 8. **Migration.** `scaffold --write`, then review every generated file.
-9. **Validation.** `validate` → `compile` → `check`.
+9. **Validation.** `validate` → `compile` → `check --strict`. The strict gate
+   fails on every warning not accepted with pinned evidence, so a migration
+   cannot finish with an unreviewed normative section or an unproven
+   requirement. A known gap is accepted explicitly (`warningAcceptances`) and
+   stays `UNRESOLVED` in the audit.
 
 ### Do not trust the documentation
 

package/docs/QUERY.md

@@ -84,6 +84,17 @@ withheld.
 endpoint is proved by running their suites, so `verification` for an API subject
 is the union over the provider and its consumers.
 
+**A component change carries its dependents' checks.** Verification follows the
+reverse `buildDependsOn` / `testDependsOn` closure (including their inverse
+`buildDependencyOf` / `testDependencyOf` spellings). Build dependents contribute
+all tiers; a route containing a test dependency contributes only `unit` checks.
+If an all-build route also reaches that dependent, all tiers apply. Cycles are
+visited safely. The subject's own checks come first, then the dependents', with
+each group sorted by check ID. A check shared by multiple components appears
+once by ID; identical command text in different component checks remains scoped
+by its ID and `configPaths`. The usual verification budget and truncation fields
+apply to the combined list.
+
 **Journey peers are named.** If a component appears in a journey, the other
 components in that journey are in scope and are listed explicitly rather than
 left for the agent to rediscover.
@@ -127,9 +138,25 @@ the slice is never mistaken for the whole.
 | assertions | 25 |
 | provenance | 20 |
 | contracts | 10 |
+| docs (markdown) | 12 |
+| constraints (markdown) | uncapped |
+| runbooks (markdown) | 12 |
 
 ## Markdown rendering
 
+Component, Resource and System descriptors may carry `spec.context`. Their
+documentation, constraints and runbooks appear under `docs`, `CONSTRAINTS` and
+`runbooks`, respectively. Components also include conventional files discovered
+in their source root. API and Domain schemas do not allow `context`.
+
+Markdown docs and runbooks default to 12 paths each. Constraints are uncapped by
+default so critical routing context is preserved. Set an explicit cap with, for
+example, `--budget docs=1,constraints=5,runbooks=1`. A shortened line ends with
+`[truncated: 1 of 2]`, reporting the number shown and the total. JSON retains the
+complete arrays under `constraints.docs`, `constraints.constraints` and
+`constraints.runbooks`; these markdown-only caps do not shorten the JSON arrays
+or `entity.spec.context`.
+
 `--md` (the default) produces a compact block suitable for a prompt or a human:
 
 ```
@@ -164,10 +191,32 @@ contracts, documentation, resources, verification and catalog sources; whether
 the graph will be invalidated; the recommended verification commands; any open
 conflicts on the affected subjects; and related journeys.
 
-Reachability rules: a contract change reaches its provider and every consumer; a
-component change reaches its transitive dependents two hops out, and everything
-connected to it by a runtime call or a schedule. Two hops is deliberate — a
-third hop is where the graph stops being a routing aid and becomes a dump.
+Reachability rules: a contract change reaches its provider and every consumer;
+a Resource change reaches components bound to that exact Resource. A migration
+change (including Alembic `alembic/versions`) reports its changed path and the
+logical databases bound to its enclosing component through existing
+`usesResource` / `resourceUsedBy` relations. Migration authority alone never
+establishes ownership or invents a Resource binding.
+
+A component change reaches its reverse build/test dependency closure, plus
+direct runtime-call and schedule peers. Dependencies are not affected just
+because the changed component uses them; they remain explicitly typed context
+in query's `relations`. The dependent closure has no hop cutoff, so a long chain
+cannot silently omit an affected consumer.
+
+Changing a workflow file follows recorded verification `configPaths` to the
+components its checks cover. Those components seed the reverse build/test
+dependency closure just like directly changed components. Matching repository
+gates appear in `affectedGates`; a workflow matched by any check or gate is
+removed from `unmatchedFiles`.
+
+Impact uses the same verification selection and ordering as query, including
+the test-only tier restriction. Directly affected components' checks precede
+their dependents' checks, followed by the matching repository gates. The
+combined `recommendedVerification` array is capped at 25;
+`recommendedVerificationTotal` gives the uncapped count including gates and
+`recommendedVerificationTruncated` reports overflow. Query's default cap is 12
+and can be adjusted with `--budget verification=...`.
 
 ## Using it in a prompt