agent-doc-system 1.2.0 → 1.4.0

package/docs/EVALS.md

@@ -7,30 +7,42 @@ 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 scenario's verification expectations returned; 1 when there are no expectations, for both catalog and baseline |
+| 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 |
@@ -52,13 +64,125 @@ graph, selectivity is 1 (there is nothing to narrow). Corpus values are scenario
 means; the aggregate is scenario-weighted across corpora. Both CLI reports
 include per-scenario values in their `--json` output.
 
-Baseline verification recall is 1 by construction: its verification strategy
+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. Selectivity is the meaningful comparison of
+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
@@ -82,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:
@@ -188,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.
@@ -239,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
 
@@ -191,12 +208,38 @@ 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.
 
+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.
+change is a Resource change. Which Resource is decided from the graph, most
+specific directory first, by whole path segment (`drizzle` never matches
+`drizzle-extra/`):
+
+1. **Declared.** Under a path a logical-database Resource lists in
+   `spec.migrationPaths`: that Resource, whichever component owns the file and
+   whatever that component is bound to. An authored declaration beats a
+   detected directory.
+2. **Detected.** Under a directory the `database` adapter recorded in a
+   component's `derived.migrationDirs` (a `migrations` directory, Alembic
+   `alembic/versions`, Drizzle Kit's `out`): the logical databases bound to
+   that component through existing `usesResource` / `resourceUsedBy`
+   relations. The changed path is listed too.
+3. **By name.** Under a `migrations/`, `migration/` or `alembic/versions/`
+   segment the graph does not record (the `database` adapter is off): the same
+   as detected, from the enclosing component.
+
+Every component bound to a reached Resource is affected, with the reason
+`resource change touches <ref>`. When the directory was declared or found
+through an ORM config, a second reason names the migration:
+`migration drizzle/0001_x.sql changes resource:default/app-db (migration
+directory drizzle, detected from drizzle-config in component:default/web)`.
+Migration authority alone never establishes ownership or invents a Resource
+binding: a detected directory whose component has no binding reaches no
+Resource, and a declaration routes changes without creating a relation.
 
 A component change reaches its reverse build/test dependency closure, plus
 direct runtime-call and schedule peers. Dependencies are not affected just

package/docs/SPEC.md

@@ -77,6 +77,47 @@ authored in exactly one file, and the location is validated.
 The namespace comes from the configuration, so two repositories in one graph
 never collide.
 
+### Resource migration paths
+
+A `logical-database` Resource may list the repository directories that hold its
+schema migrations:
+
+```yaml
+apiVersion: agentdoc.dev/v1
+kind: Resource
+metadata:
+  name: app-postgres
+  description: "Primary Postgres database of the application."
+spec:
+  type: logical-database
+  system: app
+  migrationPaths:
+    - frontend/apps/web/drizzle
+```
+
+Each entry is a repository path matched as a whole-segment prefix (the rules
+of `core/paths.mjs`): `frontend/apps/web/drizzle` covers every file below it,
+including `meta/_journal.json`, and never `frontend/apps/web/drizzle-extra/`.
+`impact` treats a change under it as a change to this Resource, whichever
+component owns the file, and reaches every component bound to the Resource.
+The declaration is AUTHORED: it beats a migration directory the `database`
+adapter detects, and it is pointed at by its own provenance subject
+(`/entities/<i>/entity/spec/migrationPaths`). It never creates a
+`usesResource` relation; which components use the database is still derived.
+
+Validation, at load time:
+
+| case | code |
+|---|---|
+| absolute, backslash, `.` or `..` segment, whitespace | `AGENTDOC_PATH_ESCAPE` |
+| a path that does not exist (or is git-ignored) | `AGENTDOC_PATH_UNRESOLVED` |
+| a glob (`*`, `?`, `[`, `{`, `!`): declare the directory itself | `AGENTDOC_MIGRATION_PATH` |
+| the field on a Resource whose type is not `logical-database` | `AGENTDOC_MIGRATION_PATH` |
+| the same path declared by two Resources | `AGENTDOC_MIGRATION_PATH` |
+
+Nested declarations on different Resources are allowed; the longest prefix
+wins.
+
 ### Why no further entities
 
 A `Team`, `Milestone` or `Tag` entity was considered and rejected: none of them
@@ -142,6 +183,7 @@ least one provenance id and an evidence class.
 ```
 schemaVersion, source{commit, dirty, inputHash}, compiler{name, version, adapters}
 entities[]      ref, kind, name, entity, source, sourcePaths[], derived?
+                (derived.migrationDirs[]: path, via[], provenanceIds[])
 relations[]     type, sourceRef, targetRef, evidenceClass, attributes, provenanceIds[]
 interfaces.events[]              pattern, producers, consumers, contract, resolution
 externalDependencies[]           componentRef, name, role, mechanism, evidenceClass
@@ -195,6 +237,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 +305,9 @@ 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
@@ -291,7 +363,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 |
@@ -302,6 +374,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.2.0
+        #   github:lbframe/agent-doc-system#v1.4.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile