agent-doc-system 1.1.0 → 1.2.0

package/docs/ADAPTERS.md

@@ -44,9 +44,17 @@ Available on `ctx`:
 | `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 |
+| `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
@@ -90,6 +98,8 @@ 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 |
@@ -106,6 +116,53 @@ cannot name the file a fact came from, you cannot add the fact.
 `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,
@@ -139,6 +196,122 @@ 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: [...]`.
@@ -186,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/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,7 +20,7 @@ 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.1.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

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

@@ -204,8 +204,10 @@ Then, in order:
    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.

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
 

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.1.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"
+  ]
 }