agent-doc-system 1.1.0 → 1.3.0

package/docs/EVALS.md

@@ -7,34 +7,182 @@ noise than exploring the repository unaided?
 
 The question is not "does it compile". A catalog can compile perfectly and still
 route an agent into the wrong corner of the repository. The measurement is
-retrieval quality, on the same scenarios, for two retrieval systems.
+retrieval quality on the same scenarios for three retrieval systems.
 
-**baseline-targeted** — what an agent that has no catalog and looks only where
-the change is: the touched component, its subtree, its relations, its documents
-and its checks.
+**baseline-targeted** — the historical, graph-assisted reference: the touched
+entity, its subtree, directly connected entities, documents, events and checks,
+plus the original repository-wide documentation sweep. It reads compiled
+relations and authority facts. It is not an agent without AgentDoc.
 
-**baseline-full** — what an agent with no routing ends up holding: every entity,
-every relation, every event subject, every check, every document in the
-repository. This is the honest cost of "just read the repository", and it is the
-size yardstick for reduction.
+**baseline-search** — a deterministic model of an agent with file reads and
+text search over the working tree, starting at the touched paths. It searches
+for importers and importees to a fixed point, then reads the reached components'
+docs, manifests and checks. It has no compiled graph or compiler-derived
+relations. Its complete heuristics are below.
 
 **catalog** — what `agentdoc query` returns for the touched paths, plus the
 context of the components `impact` says are affected.
 
-No model is involved. Retrieval sets are compared as sets, so the measurement
-is deterministic and cannot be moved by phrasing.
+**baseline-full** is retained only as a size yardstick: all graph entities,
+relations, event subjects, checks and documents. It is a graph inventory, not
+unaided repository exploration.
+
+No model is involved. Retrieval sets are compared as sets. All systems and the
+noise closure use `evals/facts.mjs`: resource links use `uses:` / `usedBy:`, API
+links use `provides:` / `consumes:` / `provider:` / `consumer:`, and component
+and placement links use bare entity refs. A relation also identifies its other
+endpoint, as query's neighbour summaries do. Inverse edges respect direction.
+An API subject supplies `provides:<its-ref>`, as query does. Documents use
+`doc:` throughout, including the old targeted sweep (formerly `repodoc:`).
+Compiler relation names are not separate facts. Tests pin this vocabulary.
 
 ## Metrics
 
 | metric | definition |
 |---|---|
-| recall | fraction of the scenario's ground-truth facts the catalog retrieved |
+| recall | fraction of the scenario's ground-truth facts retrieved by each system |
 | 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 every system |
+| 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.
+
+Targeted 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. Search discovers its own checks; it does not
+inherit this union. 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.
+
+`recall` is a scenario mean. `microRecall` instead divides total fact hits by
+total truth facts; per-scenario hit/total counts make this independently
+recomputable. Aggregate micro-recall uses these raw counts, not corpus means.
+The legacy JSON keys remain: catalog metrics are at the top level, targeted
+metrics are under `baseline`, and search metrics are under `searchBaseline`.
+
+Search returns scoped `(componentRef, command)` pairs without graph check IDs.
+Only the scorer matches these pairs to graph verification entries and gates,
+then counts their IDs for selectivity and `verify-id:` expectations. A root
+command matches only a repository-scoped check. Identical commands in different
+components remain distinct. Unregistered commands remain retrieved facts and
+can contribute noise, but do not select a registered ID. Read selectivity with
+verification recall; a low value can mean a missed check.
+
+### Search baseline heuristics
+
+`evals/baseline-search.mjs` imports only filesystem/path utilities, the existing
+YAML/TOML syntax readers and the shared fact helper. It never invokes adapters,
+routing, a package manager, a model or a shell search. The following rules are
+fixed independently of scenario truth:
+
+1. **Working tree.** Walk regular files in sorted name order, including
+   uncommitted files. Do not follow symlinks. Skip `.git`, `.agentdoc`,
+   `node_modules`, `.venv`, `venv`, `__pycache__`, `target`, `dist`, `build` and
+   `.next`, and any `graph.json`. Read JS/TS (including CJS/MJS/JSX/TSX), Go,
+   Rust, Python, proto, SQL, Markdown, RST, TXT, JSON, YAML, TOML, INI, CFG,
+   MOD, WORK, LOCK and Dockerfile text; skip NUL-containing files. This is a
+   literal exclusion list, not `.gitignore` or a tracked-file snapshot.
+2. **Ownership only.** YAML documents with `apiVersion: agentdoc.dev/...`
+   are excluded from search. For `Component` documents only, take the metadata
+   name/namespace as identity, the descriptor directory as source root, and
+   string arrays under `spec.context` as owned document paths. Explicit document
+   ownership wins, otherwise the longest component root wins. No placement,
+   relations, API/resource declarations, journeys, observations or authority
+   rules are used. Other files under `agentdoc/` are excluded too.
+3. **Import names.** Read each component's root `package.json` name, Cargo
+   package name and its underscore spelling, `go.mod` module path, Python
+   distribution names, and top-level Python packages with `__init__.py` or
+   `__main__.py` (under the root or `src/`). These are search terms, not
+   compiler-resolved units. A component without an import name can still own
+   touched paths and participate through relative imports or endpoint strings.
+4. **Importers and importees.** Search source for JS/TS `from`, `import` and
+   `require` quoted specifiers; Go quoted strings; Rust `use`, `extern crate`
+   and `name::`; Python line-leading `import` / `from` names. Match exact names
+   or slash/dot subpaths. Search manifests for names at word/path boundaries,
+   and for local `path =`, `file:` and `link:` dependencies relative to that
+   manifest. Relative source specifiers are resolved against their file's
+   directory and mapped to an owner. Rust names declared with `mod` in the
+   same file are suppressed; Python imports with a matching local `.py` file
+   anywhere in the importing component are suppressed. Ambiguous sibling names
+   may reach multiple components. There is no symbol resolver, alias resolver
+   or full import grammar (for example Python comma imports are incomplete).
+5. **Fixed point.** Import evidence connects components in both directions.
+   Start with owners of touched files (or explicitly touched component refs),
+   add all importers and importees, and repeat until no component is added.
+   API/endpoint text links described next participate in the same closure.
+   There is no hop limit or output cap.
+6. **APIs and endpoints.** Read OpenAPI YAML `info.title` and `paths`, and
+   protobuf `service` names. A lowercase hyphenated title plus `-api` (without
+   duplicating an existing `-api` suffix) names an OpenAPI fact; a hyphenated
+   service name names a protobuf fact. CamelCase boundaries are split. These
+   labels are guesses, not lookups in the API catalog; namespaces default to
+   `default`. Find readers by literal contract file paths in component files.
+   Find providers by exact endpoint strings in source, Next-style
+   `/app/<path>/route.ts` files, or `Register<Service>Server` text. Contract
+   readers/providers are connected. Touching a contract seeds them and emits
+   the API ref and `provides:` fact; reached readers/providers emit API roles,
+   with a provider excluded from the consumer set. Other API kinds, dynamic
+   routes, semantic serving roles and arbitrary catalog names are not inferred.
+   Also connect source/TOML files sharing an exact slash-prefixed endpoint or
+   HTTP(S) URL pathname; Next `route.js`/`route.ts` paths count. Ignore `/`.
+   Hostnames are ignored. Common paths such as `/api/health` can consequently
+   connect unrelated services; the measured noise includes this overreach.
+7. **Docs and events.** Read all text belonging to reached components. Markdown,
+   RST and TXT files count as `doc:`, except a basename containing `constraint`
+   gives `constraint:` and a path containing `runbook` gives `runbook:`.
+   In source lines mentioning subject, event, topic, publish or subscribe
+   (case insensitive), quoted lowercase-leading dotted strings with at least
+   three segments count as events. There are no configured event prefixes or
+   compiler event contracts. Imports reach a shared subject's defining file.
+8. **Resources and externals.** PostgreSQL URL schemes, `sql.Open("postgres"`,
+   `pg`, `psycopg`, `asyncpg`, `sqlx`, `diesel`, or SQL files under `migrations/`
+   suggest `resource:default/<component-name>-postgres`. The word `redis`
+   suggests `<component-name>-redis`. TOML-style `bucket =` / `queue_name =`
+   string literals supply their slugged names. These guesses emit resource refs
+   and `uses:`; no catalog resource names are read. Plain environment variable
+   names without one of these signals are insufficient to identify a resource.
+   External names come from Node dependency maps, Cargo dependency tables,
+   Go requirements, Python project dependencies/extras/dev groups and
+   requirements text. Names already identifying local units are excluded.
+   Conditional dependencies and comments are not semantically evaluated.
+9. **Checks.** Node scripts whose names mention test/lint/typecheck/check,
+   clippy/vet/pytest/ruff/mypy/unittest return their literal commands; root Turbo
+   tasks with those names generate `turbo run <task> --filter=<package>` for
+   reached packages. A Go manifest suggests `go test ./...` and `go vet ./...`;
+   a Cargo package suggests `cargo test -p <name>` and `cargo clippy -p <name>`.
+   Python component text mentioning pytest, ruff or mypy suggests that command
+   (`ruff check` for ruff); the nearest ancestor uv/Poetry lockfile selects
+   `uv run` / `poetry run`. Unittest without pytest suggests the standard-library
+   command `python -m unittest discover`. These are conventional suggestions,
+   not proof the checks pass. GitHub Actions YAML run steps are split by lines:
+   check-like lines select reached components through explicit package names
+   or step/job working directories; unscoped root lines are repository checks.
+   Filtered commands, `cd` and matrix expressions without a resolved scope are
+   skipped. Expressions, shell semantics and workflow matrices are not expanded.
+   Checks deduplicate by component and command.
+10. **No hidden knowledge.** There is no scenario-specific branch, truth-set
+    lookup or graph membership filter in retrieval. Unsupported constructs may
+    miss facts; naming guesses may add facts absent from the graph. Search does
+    not infer placement, runtime observations or authority conflicts from code.
+
 ### Why noise is measured against reachability, not against the truth set
 
 The first definition of noise was the complement of truth recall. It is
@@ -58,6 +206,65 @@ repository; a router that returned *every fact in the repository* then scored as
 precise, because everything was technically adjacent to something. The metric
 was measuring its own closure, not the router.
 
+## Measured comparison (2026-10-27)
+
+Values are scenario means; the aggregate weights corpora by scenario count.
+Recall is higher-is-better; noise and check selectivity are lower-is-better
+when read alongside recall. All three systems have verification recall 1.0 on
+these scenarios.
+
+| Corpus (scenarios) | System | Mean recall | Noise | Check selectivity |
+|---|---|---:|---:|---:|
+| Koda (9) | baseline-targeted (corrected) | 100.00% | 41.23% | 100.00% |
+| Koda (9) | baseline-search | 71.90% | 71.55% | 100.00% |
+| Koda (9) | catalog | 100.00% | 4.02% | 28.79% |
+| Node/TS (3) | baseline-targeted (corrected) | 100.00% | 17.86% | 100.00% |
+| Node/TS (3) | baseline-search | 91.67% | 30.64% | 83.33% |
+| Node/TS (3) | catalog | 100.00% | 0.00% | 100.00% |
+| Go (4) | baseline-targeted (corrected) | 93.75% | 28.94% | 100.00% |
+| Go (4) | baseline-search | 83.33% | 26.01% | 100.00% |
+| Go (4) | catalog | 100.00% | 5.88% | 66.67% |
+| Mixed monorepo (4) | baseline-targeted (corrected) | 100.00% | 37.82% | 100.00% |
+| Mixed monorepo (4) | baseline-search | 100.00% | 41.25% | 100.00% |
+| Mixed monorepo (4) | catalog | 100.00% | 5.88% | 54.17% |
+| Rust (4) | baseline-targeted (corrected) | 100.00% | 48.25% | 100.00% |
+| Rust (4) | baseline-search | 100.00% | 32.81% | 83.33% |
+| Rust (4) | catalog | 100.00% | 0.00% | 25.00% |
+| Python (6) | baseline-targeted (corrected) | 100.00% | 46.70% | 100.00% |
+| Python (6) | baseline-search | 100.00% | 23.68% | 41.67% |
+| Python (6) | catalog | 100.00% | 0.00% | 41.67% |
+| Aggregate (30) | baseline-targeted (corrected) | 99.17% | 38.83% | 100.00% |
+| Aggregate (30) | baseline-search | 88.51% | 42.61% | 84.44% |
+| Aggregate (30) | catalog | 100.00% | 2.77% | 46.42% |
+
+Corrected targeted micro-recall is **100/101 = 0.9901** (mean recall 0.9917).
+Its only missing truth fact is `component:default/ingest` in b-04. Search
+micro-recall is **85/101 = 0.8416** (mean recall 0.8851); catalog micro- and
+mean recall are both 1.0. These averages answer different questions and should
+not be interchanged.
+
+Search matches catalog recall in 21 scenarios: koda-04, koda-07, a-02, a-03,
+b-01, b-03, b-04, c-01, c-02, c-03, c-04, e-01, e-02, e-03, e-04, f-01,
+f-02, f-03, f-04, f-05 and f-06. It exceeds catalog recall in none.
+
+The label correction removes the old recall gap against targeted retrieval.
+Search recovers all expected facts in many import-related changes, but misses
+some catalog identity/placement and authority facts. Its broad fixed point
+also reads unrelated context, especially through common endpoint strings in
+Koda. These numbers compare deterministic retrieval rules on small authored
+corpora; they do not establish an agent productivity or token-saving benefit,
+or an upper bound on search. Noise is judged by the catalog's graph closure,
+so it is not independent evidence that every extra source fact is irrelevant.
+
+`recallNotWorseThanTargetedBaseline` still **passes**: catalog and corrected
+targeted recall tie in five corpora; catalog is higher in Go. Every other
+applicable pre-registered gate passes. No threshold or scenario changed and
+search has no new gate. Normalizing the vocabulary changes noise and deduplicates
+fact counts, so old noise/size figures are not directly comparable. The largest
+full inventory now has 86 facts (Koda), below the unchanged 100-fact floor.
+Aggregate retrieval reduction is therefore **not measured** (`null`), with no
+corpus included in that aggregate. Per-corpus raw ratios remain reported.
+
 ## Thresholds
 
 Pre-registered in `evals/thresholds.json`, dated, and not moved since:
@@ -101,6 +308,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 +326,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
 
@@ -157,9 +371,18 @@ Each was fixed in the engine, not by relaxing a threshold.
 - Ground truth is hand-authored per scenario. It is written from the
   repository's own manifests and contracts, not from the system's output, but it
   is still a human judgement about what matters.
-- The baseline is a model of unassisted exploration, not a record of a real
-  agent session. It is generous to the baseline by construction (baseline-full
-  is everything), which makes the reduction claim conservative.
+- Search is one explicit model of exploration, not a record of an agent
+  session or an upper bound on what search can find. Its import and endpoint
+  closure deliberately errs toward reading more; different heuristics can
+  produce different recall and noise.
+- The targeted baseline's old label mismatch is corrected. It still reads the
+  compiled graph, so its near-perfect recall does not measure unaided search.
+  The former 100%-versus-58% comparison remains withdrawn; see
+  [BENCHMARK.md](BENCHMARK.md#correction-the-fact-recall-comparison-is-withdrawn).
+- Noise is judged by the catalog's one-hop graph closure, including for search.
+  Useful source facts absent from that graph can count as noise, and legitimate
+  transitive importer context can fall outside one hop. This is not an
+  independent ground truth for irrelevant work or an agent time/token metric.
 - `retrievalReduction` is a fact-count proxy, not a token count. It does not
   weight a long constraint file against a short ref.
 - Scenarios touch one or two files. A change spanning twenty files is not

package/docs/MIGRATION.md

@@ -164,9 +164,27 @@ agentdoc check
 ```
 
 `init` writes `agentdoc/agentdoc.config.yaml`, the four central descriptor
-files, `agentdoc/journeys.yaml`, the documentation hierarchy
-(`docs/PRODUCT.md`, `docs/ARCHITECTURE.md`, `docs/CONSTRAINTS.md`,
-`docs/adr/`), the observations README, and a CI workflow. It never overwrites an
+files, `agentdoc/journeys.yaml`, the documentation hierarchy, the observations
+README, and a CI workflow. It never overwrites an existing file without
+`--force`, and reports every path it wrote or skipped.
+
+The documentation hierarchy goes where the configuration says. When
+`agentdoc/agentdoc.config.yaml` already exists, `init` and `scaffold --write`
+write `PRODUCT.md`, `ARCHITECTURE.md`, `CONSTRAINTS.md` and the ADR README to
+the configured `docs.product`, `docs.architecture`, `docs.constraints` and
+`docs.adrDir`. A role the configuration leaves out is not written anywhere and
+is listed under `notConfigured`. Without a configuration, `init` uses
+`agentdoc/docs/PRODUCT.md`, `agentdoc/docs/ARCHITECTURE.md`,
+`agentdoc/docs/CONSTRAINTS.md` and `agentdoc/docs/adr/`, and records those
+paths in the configuration it writes.
+
+Authored AgentDoc material lives in `agentdoc/`; generated output lives in
+`.agentdoc/`. `docs/` stays the product's own user documentation, which is
+often published as-is (MkDocs, Docusaurus, GitHub Pages). To keep the skeleton
+in `docs/`, or anywhere else, declare `docs.product`, `docs.architecture`,
+`docs.constraints` and `docs.adrDir` in `agentdoc/agentdoc.config.yaml` before
+running `init` or `scaffold --write`. A configuration that already declares
+`docs.*` keeps its paths, `docs/...` included, and nothing ever moves an
 existing file.
 
 `scaffold` is a dry run unless `--write` is passed.
@@ -204,8 +222,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.
@@ -237,7 +257,7 @@ worth discovering before documenting it.
 | `PRODUCT.md` | what it is, for whom, what it does not do | describe components |
 | `ARCHITECTURE.md` | why the shape is what it is | enumerate components or contracts |
 | `CONSTRAINTS.md` | repository-wide rules, one rule one reason one check | restate a component's constraints |
-| `docs/adr/NNNN-*.md` | one decision, its consequences, superseded not edited | be a design document |
+| `<docs.adrDir>/NNNN-*.md` | one decision, its consequences, superseded not edited | be a design document |
 | `<component>/CONSTRAINTS.md` | rules for that component only | duplicate a repository-wide rule |
 | `<component>/README.md` | how to run it, what it is for | restate the catalog |
 | runbooks | operational procedure | contain architectural decisions |

package/docs/PROVENANCE.md

@@ -89,6 +89,12 @@ record is complete by construction rather than by remembering to register files.
 A change to any input changes the hash; `check` refuses a graph whose hash
 disagrees.
 
+Paths git ignores are not inputs (SPEC §7.2): the tracked read path, probes and
+listings all treat them as absent, so local build output in an ignored
+directory cannot move the hash. Tracked files always count, even when they
+match an ignore pattern. Outside git the input set is the filesystem minus
+`discovery.generatedDirs`.
+
 ## Secrets
 
 Two independent layers, because derivation can synthesise a secret-shaped string

package/docs/QUERY.md

@@ -15,12 +15,29 @@ Resolution order:
 1. an exact entity ref;
 2. a documentation or constraint file a descriptor links, even outside the
    component's source root;
-3. a directory that is exactly a unit root;
-4. the longest unit root that is a prefix of the path;
-5. a canonical contract file, which routes to the API entity that claims it.
+3. the component whose source root most specifically owns the path: a
+   directory that is exactly a unit root, or else the longest unit root
+   containing it;
+4. a canonical contract file, which routes to the API entity that claims it;
+5. a root component (a descriptor at the repository root, `sourcePath: "."`),
+   which owns every file no step above claims.
+
+Paths are compared in one canonical, repository-relative form, the one git uses
+for pathspecs and `ls-files`: `./vite.config.ts`, `vite.config.ts` and
+`tooling//config.ts` are the same paths as `vite.config.ts` and
+`tooling/config.ts`. Ownership is decided on whole path segments, never on a
+raw string prefix, so a unit at `src` owns `src/x.ts` and never `src2/x.ts`.
+When several unit roots contain a path, the longest one wins, as in a routing
+table or a CODEOWNERS file. The repository root is the shortest possible root,
+so a nested component always takes precedence over a root component. A path
+that is absolute or climbs out of the repository with `..` resolves to nothing.
+A needle shaped like an entity ref (`kind:namespace/name`) that names no entity
+is unresolved; it is never treated as a file a root component owns.
 
 If nothing resolves, the command fails with `AGENTDOC_REF_UNRESOLVED` and exits
 non-zero. It never falls back to "the nearest component" or to a global dump.
+Without a root descriptor, a file outside every unit root stays unresolved: the
+repository root is owned only when a descriptor claims it.
 
 ## Freshness refusal
 
@@ -84,6 +101,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 +155,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 +208,37 @@ 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.
+Changed paths resolve to components with the same rules as `query`: a `./`
+prefix is ignored, the longest owning unit root wins, and a root component
+receives the files no other component owns. A file nothing owns is listed in
+`unmatchedFiles`.
+
+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

@@ -195,6 +195,34 @@ Every byte flows through the read tracker, so the record is complete by
 construction. A consumer must refuse a graph whose `inputHash` or `dirty` flag
 disagrees with the current checkout. There is no fallback.
 
+**The input set is the checkout as git sees it.** Reads, probes, listings and
+walks — and therefore discovery as well as the hash — never see a path git
+ignores: a local build writing into an ignored directory (`.astro/`, `build/`,
+`*.log`) changes nothing, and a graph compiled after that build is
+byte-identical to the one a clean checkout or CI produces. An ignored path is
+treated as absent: probed as `false`, left out of listings and walks, and a
+tracked read of it fails like a read of a missing file. Git is the oracle
+(`git status --ignored=matching`, one call per compile, shared with the dirty
+check), so its documented semantics apply exactly:
+
+- a tracked file stays an input even when it matches an ignore pattern;
+- nested `.gitignore` files, `$GIT_DIR/info/exclude` and the user's
+  `core.excludesFile` apply with gitignore(5) precedence, negations included,
+  and a file whose parent directory is excluded cannot be re-included;
+- `core.excludesFile` counts on purpose. An ignored untracked file is absent
+  from every clean checkout whatever rule ignored it, so excluding it only ever
+  brings the local input set closer to CI's — and it keeps the hash in step
+  with `git status`, which drives `dirty`;
+- an ignored *ancestor* of the project root (a project nested in a larger
+  checkout) is not honoured: the directory the compiler is pointed at is
+  compiled whole.
+
+`discovery.generatedDirs` (or its built-in list) is excluded in addition, in a
+git checkout or not. Without git — no repository, no git binary — there is no
+oracle: the input set is the filesystem minus those directories, and
+`.gitignore` files are not interpreted. `check` recomputes the hash by running
+the same compile, so compile and check cannot disagree on the input set.
+
 The recorded `commit` is **provenance, not a gate**: committing the graph changes
 `HEAD`, so a commit-equality check could never be satisfied by a committed graph.
 What determines whether the graph still describes the repository is the input
@@ -235,7 +263,31 @@ that references the contract file from a source or build-configuration file.
 
 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`.
+when it is listed in `discovery.supplementalRoots`. Discovery sees only the
+input set of §7.2: a descriptor or manifest under a git-ignored path is not
+discovered.
+
+`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`.
@@ -269,7 +321,7 @@ only the codes in `ACCEPTABLE_WARNING_CODES` may be accepted.
 | command | contract |
 |---|---|
 | `init [--force]` | write a configuration and documentation skeleton; never clobber unless `--force` |
-| `scaffold [--write]` | generate descriptors from provable evidence; dry run by default |
+| `scaffold [--write]` | generate descriptors from provable evidence; dry run by default; never clobbers |
 | `audit` | classify every fact; runs even when the repository cannot compile |
 | `validate` | sources, schemas, semantic checks; no artifact written |
 | `compile [--require-clean]` | deterministic build, atomic replace |
@@ -280,6 +332,21 @@ only the codes in `ACCEPTABLE_WARNING_CODES` may be accepted.
 | `pin-evidence [--json]` | check the digests pinned by reviewed overrides |
 | `doctor` | environment self-check: node version, schema bundle, git, writability |
 
+`init` and `scaffold` write the documentation skeleton to the paths an
+existing configuration declares in `docs.product`, `docs.architecture`,
+`docs.constraints` and `docs.adrDir`, read through the same loader as
+`compile` and `audit`. A role the configuration omits is not written and is
+reported in `notConfigured`; nothing falls back to a default. Only when no
+configuration exists does `init` use the defaults `agentdoc/docs/PRODUCT.md`,
+`agentdoc/docs/ARCHITECTURE.md`, `agentdoc/docs/CONSTRAINTS.md` and
+`agentdoc/docs/adr/`, and record them in the `docs:` block of the configuration
+it writes. Authored AgentDoc material lives in `agentdoc/`; generated output
+lives in `.agentdoc/`. `docs/` is left to the product's own user documentation:
+`init` and `scaffold` write there only when a configuration declares `docs.*`
+paths under it, and they never move an existing file. A target outside the
+repository, including through a symlink, fails with `AGENTDOC_PATH_ESCAPE`
+before anything is written.
+
 Exit codes: `0` ok, `1` failure, `2` usage.
 
 ## 13. Error codes

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.3.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile