agent-doc-system 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,402 @@
+# Changelog
+
+All notable changes to AgentDoc are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The
+compiler version is the package version: a graph compiled by one release is
+refused by the next with `AGENTDOC_COMPILER_MISMATCH` until it is recompiled.
+
+## [Unreleased]
+
+## [1.3.0] - 2026-11-07
+
+A graph compiled on your machine now passes `check` in CI and in a clean
+checkout. Files git ignores no longer count as compiler inputs, so a local
+build that fills an ignored directory no longer changes `inputHash`. A
+component whose descriptor sits at the repository root now owns the root files
+no other component owns, so `query` and `impact` route them. `init` and
+`scaffold --write` no longer write into your product's `docs/`: they follow the
+configured `docs.*` paths, and a new install without a configuration gets its
+skeleton under `agentdoc/docs/`. Releases are now published from CI with npm
+provenance, so `npm audit signatures` can verify that a release was built from
+this repository. The benchmark claim made in the 1.2.0 release notes is
+withdrawn, because its gap came from the evaluation and not from routing.
+
+Before you upgrade:
+
+- **Recompile committed graphs.** As with every release, a graph compiled by
+  1.2.0 is refused with `AGENTDOC_COMPILER_MISMATCH` until you run
+  `agentdoc compile` again.
+- **A descriptor or configuration path that points at a git-ignored file now
+  fails** with `AGENTDOC_PATH_UNRESOLVED`, as it would in a clean checkout.
+  Commit the file or stop ignoring it ([#45]).
+- **New installs write the documentation skeleton to `agentdoc/docs/`**
+  instead of `docs/`. A configuration that declares `docs.*` keeps its paths,
+  and no existing file is moved ([#59]).
+
+### Added
+
+- A deterministic `baseline-search` routing evaluation using working-tree file
+  reads and text search, without compiled relations ([#46]). CLI reports compare
+  catalog, corrected targeted and search recall/noise/check selectivity per
+  scenario, corpus and aggregate; `docs/EVALS.md` documents every heuristic.
+
+### Changed
+
+- Releases are now published only through a manual GitHub Actions workflow,
+  using npm trusted publishing (no token) with provenance, so `npm audit
+  signatures` can verify that a release was built from this repository
+  ([#51]). `RELEASING.md` in the repository describes the process.
+
+- **Behaviour change for new installs only:** without a configuration,
+  `agentdoc init` (and `scaffold --write`) now writes the documentation
+  skeleton to `agentdoc/docs/PRODUCT.md`, `agentdoc/docs/ARCHITECTURE.md`,
+  `agentdoc/docs/CONSTRAINTS.md` and `agentdoc/docs/adr/`, and records those
+  paths in the `docs:` block of the generated `agentdoc/agentdoc.config.yaml`
+  ([#59]). It used to write to `docs/`, which in many repositories is the
+  product's own user documentation and the source of a published docs site
+  (MkDocs, Docusaurus, GitHub Pages). Authored AgentDoc material now lives in
+  `agentdoc/`; generated output stays in `.agentdoc/`. Existing configurations
+  are unaffected: a configuration that declares `docs.*` keeps its paths,
+  `docs/...` included, and no existing file is moved. To keep `docs/` on a new
+  install, declare `docs.product`, `docs.architecture`, `docs.constraints` and
+  `docs.adrDir` in `agentdoc/agentdoc.config.yaml` before running `init`.
+
+### Fixed
+
+- A component whose descriptor sits at the repository root now owns the files
+  no nested component owns ([#50]). Before, `query vite.config.ts` failed with
+  `AGENTDOC_REF_UNRESOLVED` and `impact` listed the file in `unmatchedFiles`,
+  for both `vite.config.ts` and `./vite.config.ts`. Paths are now compared in
+  one canonical repository-relative form (no `./`), by whole path segment
+  (`src` never owns `src2/x`), and the longest owning root wins, so nested
+  components keep precedence and a contract file still routes to its API. A
+  root unit's derived paths (`README.md`, `package.json`, markers, provenance,
+  verification config paths) are no longer recorded as `./README.md`, so
+  `impact` now recognises them as documentation and compiler inputs. Without a
+  root descriptor, root files stay unmatched. Graphs of repositories without a
+  root component are unchanged.
+
+- `agentdoc scaffold --write` and `agentdoc init` now write the documentation
+  skeleton (`PRODUCT.md`, `ARCHITECTURE.md`, `CONSTRAINTS.md`, the ADR README)
+  to the configured `docs.product`, `docs.architecture`, `docs.constraints` and
+  `docs.adrDir` paths ([#49]). Both used to write to `docs/` even when the
+  configuration said otherwise, and `docs/` is often the product's own user
+  documentation. The paths are read through the same loader as `compile` and
+  `audit`. A role the configuration omits is listed under `notConfigured`
+  instead of falling back to `docs/`. An existing file is still skipped unless
+  `init --force` is given. A path that leaves the repository, including through
+  a symlink, fails with `AGENTDOC_PATH_ESCAPE` before anything is written.
+  Without a configuration, `init` uses the `agentdoc/docs/` defaults (see
+  [#59] under Changed).
+
+- Files git ignores no longer enter the compiler's inputs or `inputHash`
+  ([#45]). A local build writing into an ignored directory (`astro build`
+  filling `.astro/`, a `build/` tree, `*.log`) used to change the hash, so a
+  graph compiled after it failed `check` with `AGENTDOC_GRAPH_FRESHNESS` in CI
+  and in every clean checkout, while passing on the author's machine. Reads,
+  existence probes, listings and discovery now exclude git-ignored paths, with
+  git itself as the oracle: tracked files always count, and nested
+  `.gitignore`, `.git/info/exclude`, `core.excludesFile` and negations behave
+  exactly as in git. A non-ignored untracked file is still an input. Without
+  git the previous behaviour (filesystem minus `discovery.generatedDirs`)
+  holds. Committed graphs keep their hash. A descriptor or configuration
+  that points at a git-ignored file (for example a spec generated into an
+  ignored directory before `compile`) now fails with
+  `AGENTDOC_PATH_UNRESOLVED`, as it would in a clean checkout: commit the file
+  or stop ignoring it. The `git clean -fdX` before
+  `compile` documented as a workaround in lbframe/klozeo's `AGENTS.md` is no
+  longer needed.
+
+- `npm publish` no longer auto-corrects `package.json`: the `bin` path is
+  committed in npm's normalized form, `bin/agentdoc.mjs` ([#55]).
+
+- All routing evaluation systems and the noise closure now share fact labels
+  ([#46]). Corrected targeted micro-recall is 100/101 (0.9901), rather than
+  the previously reported gap. Search matches catalog recall in 21/30 scenarios;
+  measurements and limitations are in `docs/BENCHMARK.md`. Normalized full fact
+  counts fall below the existing size floor, so aggregate size reduction is
+  reported as unmeasured. Thresholds, scenarios and core routing are unchanged.
+
+- **Withdrawn benchmark claim.** The README, `docs/BENCHMARK.md` and the 1.2.0
+  release notes reported that routing retrieves 100% of the facts a change
+  needs against 58% for a baseline that reads only the touched component, with
+  noise under 9% against 40%, and an answer about 70% smaller than the whole
+  catalog. The gap came from the evaluation, not from
+  routing: the baseline already held almost every expected fact under a
+  different label, and it read relations from the compiled graph that an agent
+  without AgentDoc does not have. The size figure counted the same component
+  once per relation label; deduplicated, every corpus falls below the size
+  floor. Both claims are
+  removed. A baseline that finds
+  relations with search alone is now measured in the benchmark. The
+  [correction](docs/BENCHMARK.md#correction-the-fact-recall-comparison-is-withdrawn)
+  gives the details.
+
+## [1.2.0] - 2026-10-27
+
+Rust and Python are now supported at the same level as Node and Go. Before
+this release, a Cargo crate or a Python package was invisible to the compiler:
+`agentdoc audit` reported zero units, and a hand-written descriptor produced a
+component with no language, no dependency edges and no verification commands.
+
+The release also fixes how a change is routed. `impact` and `query` now follow
+the components that depend on the changed one, not the ones it depends on, and
+recommend those dependents' checks.
+
+### Added
+
+- **`rust` adapter** ([#17]). Reads `Cargo.toml` and never runs Cargo or reads
+  `Cargo.lock`.
+  - A `[package]` is a unit. `[[bin]]`, `src/main.rs` or `src/bin/` make it
+    deployable; `[lib]` or `src/lib.rs` make it importable.
+  - Workspace members come from every `[workspace]` manifest, including one
+    below the repository root (`rust/Cargo.toml` next to other languages).
+  - Sibling crates become `buildDependsOn` / `testDependsOn` edges when the
+    manifest says so: a `path`, `workspace = true` resolved through the nearest
+    `[workspace.dependencies]`, or a `[patch.<registry>]` / `[replace]` path
+    redirect inside the repository. `use`, `extern crate` and `<crate>::` paths
+    add provenance to those edges but never create one, because Rust cannot
+    use a crate the manifest does not declare.
+  - Verification commands: `cargo test -p <name>` and `cargo clippy -p <name>`.
+  - Resource vocabulary: sqlx, diesel (`diesel.toml`), tokio-postgres,
+    deadpool, sea-orm, the `redis` crate and `aws-sdk-s3`.
+- **`python` adapter** ([#18]). Reads `pyproject.toml` (PEP 621 and Poetry),
+  `setup.cfg`, `setup.py` and `requirements*.txt`. It never runs Python,
+  resolves a lockfile or inspects a virtualenv.
+  - Shape comes from evidence. An entrypoint (`[project.scripts]`,
+    `__main__.py`, `manage.py`, an ASGI/WSGI app object) makes a unit
+    deployable; a build backend plus a package makes it importable.
+  - uv workspace members come from the repository root and from workspaces
+    below it. A member with no build backend is still a unit.
+  - Sibling packages become edges from `[project] dependencies`,
+    `[tool.uv.sources]`, Poetry `path` dependencies, `-e <dir>` requirements,
+    and `import` / `from` statements. Dev groups and dev/test extras give
+    `testDependsOn`. An import that the importing unit provides itself, such
+    as a local `utils.py`, is not read as a sibling.
+  - Verification commands are derived only from evidence: `pytest`,
+    `python -m unittest discover` for unittest-only suites, `ruff check` and
+    `mypy`. `uv run` / `poetry run` is prefixed only when the lockfile names
+    the tool.
+  - Also derived: `requiresPython` when declared, and Alembic migrations as
+    database evidence.
+  - Resource vocabulary: SQLAlchemy, asyncpg, psycopg, Django `DATABASES`,
+    `redis.Redis` and boto3.
+- `agentdoc init` enables `rust` and `python` when it finds their manifests.
+  `agentdoc scaffold` names crates and distributions from their manifests and
+  types them from their artifact shape: `service`, `library`, or `other` when
+  neither is proven. A virtual Cargo or uv workspace manifest is not scaffolded.
+- A reproducible benchmark, `scripts/bench/run.mjs` ([docs/BENCHMARK.md]).
+  It clones four public repositories at pinned commits, runs a fresh
+  `init` → `scaffold` → `compile`, counts every hand edit the setup still
+  needs (zero for all four), checks that the graph is byte-identical across
+  compiles, and measures `query` answers.
+- The routing evaluation reports **check selectivity**: the share of the
+  repository's checks that the answer for a change contains ([#43]). The
+  baseline's verification recall is now scored with the same rule as the
+  catalog's. It is 1.0 by construction, because the baseline runs every check.
+- Rust and Python sample repositories (`fixtures/e-rust-workspace`,
+  `fixtures/f-python-workspace`), checked in CI and used to test context
+  routing ([#23]).
+
+### Changed
+
+- **Change routing follows dependents** ([#30], [#25]).
+  - A change to a component reaches the components that depend on it,
+    transitively, through reverse `buildDependsOn` / `testDependsOn` edges.
+    Before, `impact` also listed the components it depends on as affected,
+    and did not follow transitive dependents.
+  - Dependencies stay visible as typed relations in `query`. They are no
+    longer reported as affected components.
+  - `query` and `impact` recommend the dependents' checks after the changed
+    component's own: every tier for build dependents, unit checks only for test
+    dependents.
+  - `impact` adds `recommendedVerificationTotal` and
+    `recommendedVerificationTruncated`, so a capped list is never mistaken for
+    the whole.
+- **`query` markdown shows an entity's context** ([#28]). Resources and
+  Systems now list their `docs`, `CONSTRAINTS` and `runbooks`, as components
+  already did. Constraints are never capped by default. Docs and runbooks show
+  12 paths each, and `--budget docs=…,constraints=…,runbooks=…` sets explicit
+  caps with a `[truncated: x of y]` marker.
+- **`discovery.notUnitRoots` excludes a whole subtree from inferred units**
+  ([#27]). An adapter marker or a scaffold proposal at or below an excluded
+  root is no longer a unit. A hand-written descriptor below an excluded root
+  is still honoured. A descriptor exactly at an excluded root is refused with
+  a message that names the exclusion.
+- **GitHub Actions checks are scoped to the components they run for**
+  ([#29]). A step becomes a component check only when its command is a
+  recognised test, lint or build invocation, scoped by `working-directory`,
+  `cd <dir> &&`, a path argument, a package selector (`--filter`, turbo, nx,
+  `make -C`) or a `paths:` filter. Repository scripts whose names say what
+  they check (`./scripts/test.sh`, `bash scripts/lint.sh`) are recognised
+  with the same scoping ([#40]). Anything else is a repository gate.
+  - Before, every step was attached to every component whose path or package
+    name appeared anywhere in the workflow, including multi-line ops scripts.
+    A shell `test -n` was also recorded as a unit test.
+  - `impact` on a workflow file now names the components and gates derived
+    from it, plus their dependents' checks.
+- **The TOML reader conforms to TOML 1.0** ([#18], [#31]). It reads
+  `Cargo.toml`, `pyproject.toml` and `wrangler.toml`, and passes every case of
+  the official [toml-test](https://github.com/toml-lang/toml-test) 1.0.0
+  suite: 208 valid and 501 invalid documents. Before, it rejected valid
+  documents, such as multi-line strings and lowercase date-time delimiters,
+  which lost every fact in the file. It also accepted invalid ones, such as a
+  trailing comma in an inline table or a table declared twice. Invalid TOML
+  is rejected with `AGENTDOC_YAML_PARSE`.
+
+### Fixed
+
+- **A unit nested inside another unit no longer leaks its facts into the
+  parent** ([#21]). Every per-unit scan stops at nested units, so each file
+  belongs to the deepest unit that contains it. Before, an enclosing unit also
+  claimed its nested unit's health routes, ports, capabilities, resource and
+  migration evidence, imports, contract consumers, TypeScript routes, Ansible
+  playbooks and test markers. This affects any layout with nested units, such
+  as a service containing a tool package, a Cargo root package with member
+  crates below it, or a uv workspace root with its own `[project]`.
+- An Alembic `alembic/versions` directory was listed as a migration location
+  but never recognised. It now counts as migration evidence. The evidence file
+  is a qualifying `alembic.ini` or `[tool.alembic]` configuration when one
+  exists, and otherwise a revision file.
+- A changed migration, including an Alembic revision, now lists the logical
+  database its component uses in `impact`'s `affectedResources` ([#30]).
+  Before, the list stayed empty.
+- The audit no longer reports a document as orphaned when it is linked only
+  from a Resource's or System's `context` ([#28]).
+- `agentdoc scaffold --write` no longer writes descriptors into directories
+  listed in `discovery.notUnitRoots` ([#27]).
+- **A fresh setup compiles without hand edits** ([#37], [#38]).
+  - `scaffold` now types every unit from its artifact evidence: `service`,
+    `library`, or `other` when neither is proven. Before, a Node app without
+    `exports` or `main`, or a Go module, was written as `library` and failed
+    `validate` straight away.
+  - `init` now discovers descriptors with the `*/**/agentdoc.yaml` glob
+    instead of an explicit list, and `scaffold` covers every unit an adapter
+    declares, including workspace members under `examples/`.
+  - A `setup.py` unit is named after the distribution it declares, and the
+    `python` adapter reads `name`, `python_requires` and `install_requires`
+    inside a one-line `setup(…)` or `setuptools.setup(…)` call ([#41]).
+  - On the four public repositories used for benchmarking (tokio-rs/axum,
+    pydantic/pydantic-ai, fastapi/full-stack-fastapi-template and
+    t3-oss/create-t3-turbo), `init` + `scaffold --write` + `compile` now pass
+    with no edits other than choosing each component's placement.
+
+### Upgrading
+
+- The compiler version is now `1.2.0`. A graph committed with 1.1.0 fails
+  `agentdoc check` with `AGENTDOC_COMPILER_MISMATCH`. Run `agentdoc compile`
+  and commit the graph.
+- An existing catalog keeps its adapter list. To use the new adapters, add
+  `rust` and/or `python` to `adapters:` in `agentdoc/agentdoc.config.yaml`,
+  then run `agentdoc audit`: units that were invisible appear as
+  `AGENTDOC_COVERAGE_ZERO` until they have a descriptor.
+  `agentdoc scaffold --write` writes those descriptors.
+- If your repository has nested units, recompiling removes facts that were
+  wrongly attributed to an enclosing component. Review the affected facts,
+  dependency edges and verification commands, and any descriptor or document
+  that relied on them.
+- Tools that read `impact --json` will see fewer `affectedComponents`
+  (dependencies are gone) and more `recommendedVerification` entries
+  (dependents' checks).
+- A unit inferred below a `notUnitRoots` entry, with no descriptor, is no
+  longer reported as `AGENTDOC_COVERAGE_ZERO`. If it should be a component,
+  write its descriptor, or remove the directory from `notUnitRoots`.
+- If your workflows run checks for specific components, recompiling changes
+  which checks are attached to which component. Review the diff: checks that
+  were attached only because a path was mentioned elsewhere in the workflow
+  move to repository gates.
+- Recompiling always updates the compiler version, source commit and input
+  hash. Review the other derived changes, especially in repositories with
+  nested units, Alembic migrations or Wrangler TOML manifests: a manifest the
+  old TOML reader could not parse now yields facts.
+
+## [1.1.0] - 2026-10-18
+
+### Added
+
+- **MIGRATE gates normative requirements and section coverage** ([#5]).
+  Documentation checks now state their real scope, and the strict gate refuses
+  unverified requirements.
+- **`ansible` adapter** ([#6]). Reads playbooks without running anything and
+  derives installed paths and managed services. A requirement with
+  `satisfiedBy: [ansible]` and the new `expects` field
+  (`installs: <path>` | `service: <name>`) is checked against them, so a missing
+  install ends in a conflict instead of `AGENTDOC_REQUIREMENT_UNVERIFIED`.
+- `agentdoc <command> --help` lists each command's flags and exit codes ([#7]).
+
+### Changed
+
+- **The CLI rejects unknown flags** ([#7]) and names the closest valid flag. A
+  typo such as `check --strcit` no longer silently runs a non-strict check.
+  Scripts that passed flags a command does not accept now exit 2.
+
+### Fixed
+
+- A committed graph passes CI ([#11]). `check` no longer fails with
+  `AGENTDOC_GRAPH_FRESHNESS` after `compile` on a clean checkout, where the
+  graph file itself was counted as a changed input.
+- A nested `.github/workflows` directory no longer fails `validate` ([#12]).
+  Only the repository-root directory is read, as GitHub does.
+
+### Upgrading
+
+- A graph committed with 1.0.0 fails `agentdoc check` with
+  `AGENTDOC_COMPILER_MISMATCH` until it is recompiled.
+
+## [1.0.0] - 2026-09-29
+
+First public release.
+
+### Added
+
+- The machine-installed `agentdoc` CLI for Node 22, 24 and 26, with zero
+  runtime dependencies.
+- A deterministic repository graph: repeated compiles of the same tree are
+  byte-identical.
+- Evidence separation between AUTHORED documentation, DERIVED facts extracted
+  from code, and OBSERVED runtime evidence.
+- A fail-closed authority model: contradictions surface as conflicts and are
+  never silently overwritten.
+- `agentdoc query`, which routes minimal, budgeted context for a task, and
+  `agentdoc impact`, which reports what a change forces you to keep consistent.
+- CREATE and MIGRATE workflows through `init`, `audit`, `scaffold`,
+  `validate`, `compile` and `check`.
+- `agentdoc doctor` for machine diagnostics, and `agentdoc doctor --project`
+  for project health.
+- An Agent Skill under `skills/agent-doc-system/`.
+
+[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/lbframe/agent-doc-system/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/lbframe/agent-doc-system/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/lbframe/agent-doc-system/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/lbframe/agent-doc-system/releases/tag/v1.0.0
+[docs/BENCHMARK.md]: docs/BENCHMARK.md
+[#5]: https://github.com/lbframe/agent-doc-system/issues/5
+[#6]: https://github.com/lbframe/agent-doc-system/issues/6
+[#7]: https://github.com/lbframe/agent-doc-system/issues/7
+[#11]: https://github.com/lbframe/agent-doc-system/issues/11
+[#12]: https://github.com/lbframe/agent-doc-system/issues/12
+[#17]: https://github.com/lbframe/agent-doc-system/issues/17
+[#18]: https://github.com/lbframe/agent-doc-system/issues/18
+[#21]: https://github.com/lbframe/agent-doc-system/issues/21
+[#23]: https://github.com/lbframe/agent-doc-system/issues/23
+[#25]: https://github.com/lbframe/agent-doc-system/issues/25
+[#27]: https://github.com/lbframe/agent-doc-system/issues/27
+[#28]: https://github.com/lbframe/agent-doc-system/issues/28
+[#29]: https://github.com/lbframe/agent-doc-system/issues/29
+[#30]: https://github.com/lbframe/agent-doc-system/issues/30
+[#31]: https://github.com/lbframe/agent-doc-system/issues/31
+[#37]: https://github.com/lbframe/agent-doc-system/issues/37
+[#38]: https://github.com/lbframe/agent-doc-system/issues/38
+[#40]: https://github.com/lbframe/agent-doc-system/issues/40
+[#41]: https://github.com/lbframe/agent-doc-system/issues/41
+[#43]: https://github.com/lbframe/agent-doc-system/issues/43
+[#45]: https://github.com/lbframe/agent-doc-system/issues/45
+[#46]: https://github.com/lbframe/agent-doc-system/issues/46
+[#49]: https://github.com/lbframe/agent-doc-system/issues/49
+[#50]: https://github.com/lbframe/agent-doc-system/issues/50
+[#51]: https://github.com/lbframe/agent-doc-system/issues/51
+[#55]: https://github.com/lbframe/agent-doc-system/issues/55
+[#59]: https://github.com/lbframe/agent-doc-system/issues/59

package/README.md

@@ -69,6 +69,41 @@ AgentDoc turns scattered repository knowledge into task-specific context your co
 
 ![How AgentDoc works](docs/assets/readme/how-agentdoc-works.webp)
 
+## What it understands
+
+AgentDoc reads manifests, contracts and configuration. It never runs your toolchain.
+
+Support comes from adapters and from built-in contract validation (AsyncAPI needs no adapter).
+- `agentdoc init` picks `node`, `go`, `rust`, `python`, `dockerfile` and `wrangler` from the files it finds.
+- It always includes `database`, `openapi`, `events` and `github-actions`.
+- Add the others in `agentdoc/agentdoc.config.yaml`.
+
+| area | supported |
+|---|---|
+| languages & packages | Node (npm, pnpm workspaces, Turborepo), TypeScript, Go (modules, `go.work`), Rust (Cargo packages and workspaces), Python (`pyproject.toml` with PEP 621 or Poetry, uv workspaces, `setup.cfg` / `setup.py`, `requirements*.txt`) |
+| contracts | OpenAPI, protobuf, GraphQL, AsyncAPI, OIDC discovery |
+| deployment & CI | Dockerfile / Containerfile, `fly.toml`, `Procfile` and similar deploy configs, Cloudflare Wrangler, Ansible playbooks, GitHub Actions |
+| resources | databases (migrations, ORM config, connection evidence), caches, object stores, event subjects |
+
+For each language, AgentDoc derives:
+
+- the units;
+- whether each one is deployable or importable;
+- dependency edges between sibling units;
+- verification commands taken from the repository's own evidence (`go test`, `cargo test -p`, `pytest`, `python -m unittest`, npm scripts, …).
+
+What every adapter derives, and what it deliberately cannot see, is in [docs/ADAPTERS.md](docs/ADAPTERS.md).
+
+## By the numbers
+
+Measured, reproducible, and with no model in the loop. Method and caveats are in [docs/BENCHMARK.md](docs/BENCHMARK.md).
+
+- **The checks a change needs, not the whole suite.** Across 30 routing scenarios (Node, Go, Rust, Python), every check the change requires is in the answer, and that answer holds about half of the repository's checks (29% on the largest corpus), not all of them. The thresholds were fixed before the first run and have not moved since.
+- **Seconds to map a real repository.** A fresh `init` → `scaffold` → `compile` takes 1.0–4.6 s on four public repositories, from 141 to 5,142 files (axum, pydantic-ai, full-stack-fastapi-template, create-t3-turbo). No edit was needed beyond choosing each component's placement.
+- **A briefing, not a dump.** A `query` answer is about 100–260 tokens: what the change reaches, what to read, and which checks to run.
+- **The same graph every time.** Compiles are byte-identical, and CI can verify it.
+- **Small and strict.** Zero runtime dependencies, a package of about 285 kB packed, 21 adapters, and 709/709 cases on the official TOML 1.0 conformance suite.
+
 ## Install manually
 
 Requires Node.js 22+.
@@ -92,7 +127,10 @@ AgentDoc also ships with an Agent Skill at [`skills/agent-doc-system/`](skills/a
 - [Authority & conflicts](docs/AUTHORITY.md)
 - [CI & verification](docs/CI.md)
 - [Specification](docs/SPEC.md)
+- [Adapters](docs/ADAPTERS.md)
+- [Benchmark](docs/BENCHMARK.md)
 - [Agent Skill](skills/agent-doc-system/SKILL.md)
+- [Changelog](CHANGELOG.md)
 
 ## License
 

package/adapters/ansible.mjs

@@ -132,7 +132,7 @@ function isYaml(f) {
 
 function playbooks(repo, root) {
   const out = [];
-  for (const f of repo.walk(root)) {
+  for (const f of repo.walkUnit(root)) {
     if (!isYaml(f) || /(^|\/)(tasks|handlers|vars|defaults|meta|group_vars|host_vars|templates|files)\//.test(f.slice(root.length))) continue;
     const docs = parse(repo, f);
     if (!docs) continue;

package/adapters/cache.mjs

@@ -1,7 +1,8 @@
 // Cache adapter: Redis / in-memory cache client evidence as a derived binding.
 import { Adapter } from "./registry.mjs";
+import { joinPath } from "../core/paths.mjs";
 
-const CACHE_HINT = /(@upstash\/redis|ioredis|redis|go-redis|redis\.go|valkey|memcache|@memcached)/i;
+const CACHE_HINT = /(@upstash\/redis|ioredis|redis\.Redis|redis|go-redis|redis\.go|valkey|memcache|@memcached)/i;
 
 export class CacheAdapter extends Adapter {
   static adapterName = "cache";
@@ -10,7 +11,13 @@ export class CacheAdapter extends Adapter {
   }
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
-    const evFile = unit.goModule ? unit.root + "/go.mod" : unit.root + "/package.json";
+    const evFile = unit.goModule
+      ? joinPath(unit.root, "go.mod")
+      : unit.pythonManifest
+        ? unit.pythonManifest
+        : repo.exists(joinPath(unit.root, "package.json"))
+          ? joinPath(unit.root, "package.json")
+          : joinPath(unit.root, "Cargo.toml");
     if (!repo.exists(evFile)) return {};
     const text = repo.readText(evFile);
     if (!CACHE_HINT.test(text)) return {};

package/adapters/contract-consumers.mjs

@@ -18,7 +18,7 @@ const DOC_EXT = /\.(md|mdx|txt|adoc|rst)$/;
 
 export function contractReferenceSites(repo, unit) {
   const out = new Map(); // file -> true
-  for (const f of repo.walk(unit.root)) {
+  for (const f of repo.walkUnit(unit.root)) {
     const base = path.posix.basename(f);
     if (DOC_EXT.test(f)) continue;
     if (f.includes("/docs/") || f.startsWith("docs/")) continue;

package/adapters/database.mjs

@@ -9,12 +9,16 @@
 //     library shipped migrations but explicitly did not own a database.
 import { Adapter } from "./registry.mjs";
 import { firstExistingFile, findMigrationDirs } from "../core/sourcescan.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 const ORM_CONFIG = [
   "drizzle.config.ts", "drizzle.config.js", "drizzle.config.mjs",
   "prisma/schema.prisma", "schema.prisma",
   "knexfile.js", "knexfile.ts", "sequelize.config.js", "ormconfig.json",
 ];
+// Probed only for a Cargo package. Adding it to the list above would record
+// a new existence probe on every non-Rust unit and change those graphs.
+const RUST_ORM_CONFIG = ["diesel.toml"];
 
 export class DatabaseAdapter extends Adapter {
   static adapterName = "database";
@@ -25,12 +29,23 @@ export class DatabaseAdapter extends Adapter {
     const { repo, prov, compRef } = ctx;
     const root = unit.root;
     const migrationDirs = findMigrationDirs(repo, root);
-    const ormConfig = firstExistingFile(repo, root, ORM_CONFIG);
+    const ormConfig = firstExistingFile(repo, root, unit.cargoPackage ? ORM_CONFIG.concat(RUST_ORM_CONFIG) : ORM_CONFIG);
     if (!migrationDirs.length && !ormConfig) return {};
 
     let evidencePath = ormConfig;
     if (migrationDirs.length) {
-      evidencePath = repo.walk(migrationDirs[0])[0] || migrationDirs[0];
+      evidencePath = repo.walkUnit(root, migrationDirs[0])[0] || migrationDirs[0];
+    }
+    const alembicDir = migrationDirs.find((d) => d === "alembic/versions" || d.endsWith("/alembic/versions"));
+    if (alembicDir) {
+      const ini = joinPath(root, "alembic.ini");
+      const pyproject = joinPath(root, "pyproject.toml");
+      if (repo.exists(ini)) {
+        const text = repo.readText(ini);
+        if (/^\s*\[alembic\]/m.test(text) || /^\s*script_location\s*=/m.test(text)) evidencePath = ini;
+      } else if (repo.exists(pyproject) && /\[tool\.alembic\]/.test(repo.readText(pyproject))) {
+        evidencePath = pyproject;
+      }
     }
     const pr = prov.add("observed", evidencePath, "migration-extractor", ["der:" + compRef + ":/bindings"]);
 
@@ -93,10 +108,10 @@ export class DatabaseAdapter extends Adapter {
   }
 }
 
-const POOL_HINT = /(createPool|new Pool|pg\.Pool|psycopg2?\.connect|sql\.Open|mysql\.createConnection|Pool\(|DataSource|prisma\.(datasource|client)|DATABASE_URL|DB_DSN)/;
+const POOL_HINT = /(createPool|new Pool|pg\.Pool|PgPool|psycopg2?\.connect|asyncpg\.(?:connect|create_pool)|sql\.Open|mysql\.createConnection|Pool\(|DataSource|prisma\.(datasource|client)|DATABASE_URL|DB_DSN|sqlx::migrate!|tokio_postgres|tokio-postgres|deadpool|sea_orm|sea-orm|diesel::|create_engine\s*\(|\bDATABASES\s*=)/;
 
 function hasConnectionEvidence(ctx, unit) {
-  for (const f of ctx.repo.walk(unit.root)) {
+  for (const f of ctx.repo.walkUnit(unit.root)) {
     if (/\.(ts|tsx|js|mjs|go|py|rb|java|kt|rs|ex|cs|php)$/.test(f)) {
       if (/(^|\/)(tests?|__tests__)\//.test(f)) continue;
       if (POOL_HINT.test(ctx.repo.readText(f))) return true;

package/adapters/deploy-config.mjs

@@ -2,6 +2,7 @@
 // Only the file's existence is treated as evidence; no value from these files
 // is ever reported as deployed state.
 import { Adapter } from "./registry.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 const DEPLOY_FILES = [
   "fly.toml", "app.yaml", "render.yaml", "railway.json", "vercel.json",
@@ -16,7 +17,7 @@ export class DeployConfigAdapter extends Adapter {
   }
   detect(ctx, root) {
     for (const n of DEPLOY_FILES) {
-      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+      if (ctx.repo.exists(joinPath(root, n))) return { path: joinPath(root, n), shape: "deployable" };
     }
     return null;
   }
@@ -24,7 +25,7 @@ export class DeployConfigAdapter extends Adapter {
     const { repo, prov, compRef } = ctx;
     const out = { deployConfigs: [] };
     for (const n of DEPLOY_FILES) {
-      const p = unit.root + "/" + n;
+      const p = joinPath(unit.root, n);
       if (!repo.exists(p)) continue;
       prov.add("observed", p, "deploy-extractor", ["der:" + compRef + ":/artifact"]);
       out.deployConfigs.push(p);

package/adapters/dockerfile.mjs

@@ -1,5 +1,6 @@
 // Dockerfile adapter: a Dockerfile is deployable-artifact evidence.
 import { Adapter } from "./registry.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 export class DockerfileAdapter extends Adapter {
   static adapterName = "dockerfile";
@@ -8,7 +9,7 @@ export class DockerfileAdapter extends Adapter {
   }
   detect(ctx, root) {
     for (const n of ["Dockerfile", "Dockerfile.prod", "Containerfile"]) {
-      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+      if (ctx.repo.exists(joinPath(root, n))) return { path: joinPath(root, n), shape: "deployable" };
     }
     return null;
   }
@@ -16,7 +17,7 @@ export class DockerfileAdapter extends Adapter {
     const { repo, prov, compRef } = ctx;
     const out = { dockerfiles: [] };
     for (const n of ["Dockerfile", "Dockerfile.prod", "Containerfile"]) {
-      const p = unit.root + "/" + n;
+      const p = joinPath(unit.root, n);
       if (!repo.exists(p)) continue;
       prov.add("observed", p, "deploy-extractor", ["der:" + compRef + ":/artifact"]);
       out.dockerfiles.push(p);

package/adapters/events.mjs

@@ -70,7 +70,7 @@ export class EventsAdapter extends Adapter {
       if (other.component && visible.has(other.component.ref) && other.component.ref !== compRef) collectDecls(other.root);
     }
     const families = new Set();
-    for (const f of repo.walk(unit.root)) {
+    for (const f of repo.walkUnit(unit.root)) {
       if (!SRC_EXT.test(f)) continue;
       if (TEST_PATH.test(f) || TEST_FILE.test(f)) continue;
       const text = repo.readText(f);

package/adapters/generic.mjs

@@ -7,6 +7,7 @@
 import { Adapter } from "./registry.mjs";
 import { resolveClientResources } from "./resource-client.mjs";
 import { sourceFiles } from "../core/sourcescan.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 // Conservative: a health route is an absolute string literal that looks like a
 // liveness or readiness endpoint. Anything more specific belongs to a
@@ -50,7 +51,7 @@ export class GenericAdapter extends Adapter {
     // Provenance must name a file that exists. The dependency evidence is the
     // manifest when there is one, and otherwise the unit's descriptor.
     const manifest = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml", "pom.xml"]
-      .map((n) => unit.root + "/" + n)
+      .map((n) => joinPath(unit.root, n))
       .find((p) => repo.exists(p)) || ctx.componentEntity().file;
     const clientProv = prov.add("observed", manifest, "client-resolver", ["rel:pending", "der:" + compRef + ":/bindings"]);
     resolveClientResources(ctx, unit, compRef, clientProv);