agent-doc-system 1.1.0 → 1.3.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`, git-ignored directories, 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,130 @@
+# BENCHMARK
+
+Two measurements are reproducible from a checkout. Neither involves a model;
+both depend on the measurement rules described here.
+
+## 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 without routing.
+
+The measured systems are catalog routing, a corrected graph-assisted targeted
+reference, and working-tree search. Their current results appear below. The
+pre-registered thresholds and scenario truth are unchanged.
+
+### Correction: the fact-recall comparison is withdrawn
+
+Until 2026-10-27 this page, the README and the 1.2.0 release notes reported
+that AgentDoc 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%. That comparison does not hold, and it is withdrawn.
+
+- The targeted baseline already holds almost every expected fact, under a
+  different label from the ground truth. It records `usesResource:<ref>` where
+  the truth says `uses:<ref>`, and `buildDependencyOf:<ref>` where the truth
+  names the component `<ref>`. Relabelled, it retrieves about 99% of the
+  expected facts.
+- The baseline also takes those relations from the compiled graph, which an
+  agent without AgentDoc does not have. A fair baseline has to find them with
+  search over the repository's files.
+
+The search comparison is now measured. The targeted reference's corrected
+micro-recall is 100/101 (99.01%); its scenario-mean recall is 99.17%. The
+100%-versus-58% comparison remains withdrawn.
+
+### Search baseline
+
+`baseline-search` starts with touched files, searches source/manifests for
+import names and local paths in both directions to a fixed point, and reads
+the reached components' docs and checks. Contracts, endpoint strings, event
+subjects and resource evidence are found in working-tree files. Catalog
+descriptors supply only component identity and path ownership. Retrieval never
+reads the compiled graph or compiler relations. All naming guesses, exclusions
+and check conventions are listed in [EVALS.md](EVALS.md#search-baseline-heuristics).
+
+| 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% |
+
+These are scenario means, aggregated by scenario count. Search micro-recall is
+85/101 (84.16%), compared with 100/101 (99.01%) for corrected targeted and
+101/101 for catalog routing. All three systems retrieve every scenario-required
+verification expectation. Selectivity counts distinct registered check IDs,
+including repository gates, after matching search's discovered scoped commands.
+
+Search matches catalog fact recall in 21 of 30 scenarios, including all Rust,
+Python and mixed-monorepo scenarios. It beats catalog recall in none. The
+remaining misses include authored placement, authority conflicts/runtime
+observations, and API identities/roles not recoverable by these lexical rules.
+Its broad closure can also overreach through shared endpoint strings. This is
+a comparison of deterministic retrieval rules on authored corpora, not an agent
+session, a limit on search quality, or evidence of time/token savings. Noise is
+scored against the catalog's one-hop graph closure and can penalize useful
+source facts absent from that graph.
+
+The unchanged relative recall gate passes: corrected targeted ties catalog in
+five corpora and trails it in Go. All applicable gates pass. Normalization also
+changes noise and deduplicates fact counts: the full Koda inventory now has 86
+facts, below the unchanged 100-fact size floor. Aggregate retrieval reduction
+is **not measured**, so the former 70% size figure is not a current result.
+
+## 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.3.0 —
       # a compiler upgrade intentionally invalidates every committed graph.
       - run: npm install -g github:lbframe/agent-doc-system
       - run: agentdoc validate
@@ -47,6 +47,12 @@ compare the graph's recorded commit with `HEAD`: committing the graph changes
 The commit is recorded as provenance — which checkout produced this graph — not
 as a gate.
 
+Files git ignores are not inputs, so a graph compiled after a local build
+(`astro build`, `next build`, anything writing into an ignored directory) is the
+graph CI reproduces from a clean checkout. No `git clean -fdX` is needed before
+`compile`. An untracked file that is *not* ignored still counts, and marks the
+graph dirty: commit it or ignore it.
+
 Two things to decide per repository:
 
 - **Commit the graph or ignore it.** Both work. Committing it makes the