agent-doc-system 1.2.0 → 1.4.0

package/core/query.mjs

@@ -10,6 +10,7 @@
 import { AgentDocError, CODES } from "./codes.mjs";
 import { assertNoSecretsInText } from "./secrets.mjs";
 import { verificationForChange } from "./dependents.mjs";
+import { canonicalPath, longestOwner, ownsPath, REPO_ROOT } from "./paths.mjs";
 
 const DEFAULT_BUDGET = {
   relations: 40,
@@ -28,13 +29,13 @@ export class ContextIndex {
   constructor(graph) {
     this.graph = graph;
     this.byRef = new Map(graph.entities.map((e) => [e.ref, e]));
+    // Keyed by canonical source path, so a root unit's "." and any other
+    // spelling of the same directory land on one key.
     this.byPath = new Map();
     for (const e of graph.entities) {
-      const sp = e.derived && e.derived.sourcePath;
-      if (!sp) continue;
+      const sp = e.derived && canonicalPath(e.derived.sourcePath);
+      if (sp === null || sp === undefined) continue;
       this.byPath.set(sp, e);
-      // Longest path first so a nested path resolves to its own component
-      // rather than to a parent.
     }
     // Documentation and constraint files a descriptor links resolve to their
     // component, even when they live outside the source root. Following a
@@ -49,9 +50,12 @@ export class ContextIndex {
         ...(e.derived || {}).constraints || [],
         ...(e.derived || {}).runbooks || [],
       ];
-      for (const p of ctxPaths) if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+      for (const raw of ctxPaths) {
+        const p = canonicalPath(raw) ?? raw;
+        if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+      }
     }
-    this.paths = [...this.byPath.keys()].sort((a, b) => b.length - a.length);
+    this.paths = [...this.byPath.keys()];
     this.relationsByRef = new Map();
     for (const r of graph.relations) {
       if (!this.relationsByRef.has(r.sourceRef)) this.relationsByRef.set(r.sourceRef, []);
@@ -62,34 +66,64 @@ export class ContextIndex {
   }
 
   // A contract file resolves to the API entity that claims it, so "change this
-  // endpoint" routes to the boundary rather than to nothing.
+  // endpoint" routes to the boundary rather than to nothing. A contract ref
+  // names a file, a directory or a module prefix (`events` covering
+  // `events.go`, `events.proto`), the same coverage `Repo.filesWithPrefix`
+  // gives it — never a raw string prefix such as `events2/x`.
   contractFor(needle) {
-    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    const norm = canonicalPath(needle);
+    if (norm === null) return null;
     let best = null;
     for (const c of (this.graph.contracts || [])) {
-      if (norm === c.ref || norm.startsWith(c.ref)) {
+      if (contractCovers(c.ref, norm)) {
         if (!best || c.ref.length > best.ref.length) best = c;
       }
     }
     return best;
   }
+  // The component whose source root most specifically owns a repository path:
+  // the longest owning sourcePath, with a root component (".") as the
+  // lowest-precedence fallback. Null when no component owns the path.
+  ownerOf(file) {
+    const p = longestOwner(this.paths, file);
+    return p === null ? null : this.byPath.get(p);
+  }
   resolve(needle) {
     if (this.byRef.has(needle)) return this.byRef.get(needle);
-    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (looksLikeRef(needle)) return null;
+    // One canonical spelling for every path: `./a/b`, `a//b` and `a/b/` are
+    // all `a/b`. A path escaping the repository resolves to nothing.
+    const norm = canonicalPath(needle);
+    if (norm === null) return null;
     if (this.byDoc.has(norm)) return this.byDoc.get(norm);
-    if (this.byPath.has(norm)) return this.byPath.get(norm);
-    for (const p of this.paths) {
-      if (norm === p || norm.startsWith(p + "/")) return this.byPath.get(p);
-    }
-    for (const p of this.paths) {
-      if (needle.startsWith(p + "/")) return this.byPath.get(p);
-    }
-    if (this.byDoc.has(needle)) return this.byDoc.get(needle);
-    const c = this.contractFor(needle);
-    return c ? this.byRef.get(c.apiRef) || null : null;
+    // Precedence, most specific first: a linked document, a component source
+    // root, a contract's API, and only then a root component. The root owns
+    // every path, so it is the fallback for files nothing else claims; it
+    // must not take a contract file away from the API that declares it.
+    const owner = this.ownerOf(norm);
+    if (owner && canonicalPath(owner.derived.sourcePath) !== REPO_ROOT) return owner;
+    const c = this.contractFor(norm);
+    const api = c ? this.byRef.get(c.apiRef) || null : null;
+    return api || owner || null;
   }
 }
 
+export function contractCovers(ref, file) {
+  const r = canonicalPath(ref);
+  const f = canonicalPath(file);
+  if (r === null || f === null) return false;
+  if (ownsPath(r, f)) return true;
+  const cut = r.lastIndexOf("/");
+  const dir = r.slice(0, cut + 1);
+  return f.startsWith(dir) && f.slice(dir.length).startsWith(r.slice(cut + 1) + ".");
+}
+
+// An entity ref is `kind:namespace/name`. A needle shaped like one that names
+// no entity is an unresolved ref, not a repository path a root component owns.
+function looksLikeRef(needle) {
+  return /^[A-Za-z][\w-]*:/.test(needle);
+}
+
 function contractsOf(graph) {
   return graph.contracts || [];
 }
@@ -136,14 +170,15 @@ export function queryContext(graph, needle, opts = {}) {
   const apiProvider = entity.kind === "API" ? providerOf(ref) : null;
 
   const apiRefs = new Set([...providedApis, ...consumedApis]);
-  const srcPath = (entity.derived && entity.derived.sourcePath) || null;
   const events = g.interfaces.events.filter(
     (e) =>
       e.producers.includes(ref) ||
       e.consumers.includes(ref) ||
       // A contract library that ships the subject catalog owns those subjects,
-      // even when another component is the one that subscribes to them.
-      (srcPath && e.contract && e.contract.ref.startsWith(srcPath + "/"))
+      // even when another component is the one that subscribes to them. The
+      // owner is the component that most specifically owns the contract file,
+      // so a root component does not claim a nested library's catalog.
+      (e.contract && e.contract.ref && idx.ownerOf(e.contract.ref) === entity)
   );
   const externals = g.externalDependencies.filter((e) => e.componentRef === ref);
   const capabilities = g.capabilities.filter((e) => e.componentRef === ref);

package/core/scaffold.mjs

@@ -13,7 +13,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { AgentDocError, CODES } from "./codes.mjs";
-import { Repo } from "./fsx.mjs";
+import { Repo, assertRepoPath } from "./fsx.mjs";
+import { CONFIG_PATH } from "./descriptors.mjs";
 import { discoverUnits, isNotUnitRoot } from "./discover.mjs";
 import { classifyContractFile } from "./contracts.mjs";
 import { parse as parseToml } from "./toml.mjs";
@@ -45,23 +46,96 @@ function sentence(s) {
   return /[.!?]$/.test(t) ? t : t + ".";
 }
 
-export function installTemplates(repo, cfg, { write, root, force = false, eligible = null } = {}) {
+// Where the documentation skeleton goes when no configuration exists yet. Once
+// a configuration exists, it is the only authority: `docs.*` is what audit and
+// compile read, so the scaffolder writes there and nowhere else (issue #49 —
+// `docs/` is often the product's own user documentation).
+//
+// The default lives under `agentdoc/` (issue #59): authored AgentDoc material
+// lives in `agentdoc/`, generated output in `.agentdoc/`. Not `docs/`, which is
+// the product's user documentation (and a MkDocs/Docusaurus/Pages source), and
+// not `.agentdoc/`, which the compiler skips and many repositories git-ignore.
+export const DEFAULT_DOCS = Object.freeze({
+  product: "agentdoc/docs/PRODUCT.md",
+  architecture: "agentdoc/docs/ARCHITECTURE.md",
+  constraints: "agentdoc/docs/CONSTRAINTS.md",
+  adrDir: "agentdoc/docs/adr",
+});
+
+// The skeleton roles that have a template. `runbookDir` and `normative` are
+// honoured by never writing anything for them: there is no runbook template,
+// and normative documents are the project's own.
+const SKELETON_ROLES = [
+  { key: "product", template: "PRODUCT.md", file: (p) => p },
+  { key: "architecture", template: "ARCHITECTURE.md", file: (p) => p },
+  { key: "constraints", template: "CONSTRAINTS.md", file: (p) => p },
+  { key: "adrDir", template: "ADR.md", file: (p) => p.replace(/\/+$/, "") + "/README.md" },
+];
+
+// Resolve the documentation skeleton for a loaded configuration (`null` when
+// there is none). A configured role is written to its configured path; a role
+// a configuration leaves out is not written anywhere and is reported, so an
+// omitted role can never fall back into `docs/`.
+export function docsSkeleton(cfg) {
+  const docs = cfg ? cfg.docs || {} : DEFAULT_DOCS;
+  const targets = [];
+  const notConfigured = [];
+  for (const role of SKELETON_ROLES) {
+    const configured = docs[role.key];
+    if (!configured) { notConfigured.push("docs." + role.key); continue; }
+    // loadConfig already validated these; re-asserting keeps this function
+    // safe for any caller that hands it an unvalidated object.
+    assertRepoPath(configured, CONFIG_PATH);
+    const rel = role.file(configured);
+    assertRepoPath(rel, CONFIG_PATH);
+    targets.push({ key: role.key, path: rel, template: role.template });
+  }
+  return { targets, notConfigured, docs: cfg ? docs : DEFAULT_DOCS };
+}
+
+// Refuse a write target that leaves the repository, including through a
+// symlinked directory or a (possibly dangling) symlink at the target itself.
+// Lexical checks alone (`isRepoPath`) cannot see a symlink.
+function assertWritableInside(root, rel) {
+  const abs = path.resolve(root, rel);
+  const inside = path.relative(path.resolve(root), abs);
+  if (!inside || inside === ".." || inside.startsWith(".." + path.sep) || path.isAbsolute(inside)) {
+    throw new AgentDocError(CODES.PATH_ESCAPE, "path escapes repository: " + rel, { path: rel });
+  }
+  const realRoot = fs.realpathSync(root);
+  let cur = path.resolve(root);
+  for (const seg of inside.split(path.sep)) {
+    cur = path.join(cur, seg);
+    let st;
+    try { st = fs.lstatSync(cur); } catch { return; } // nothing further exists yet
+    if (!st.isSymbolicLink()) continue;
+    let real = null;
+    try { real = fs.realpathSync(cur); } catch { /* dangling */ }
+    if (real === null || (real !== realRoot && !real.startsWith(realRoot + path.sep))) {
+      throw new AgentDocError(CODES.PATH_ESCAPE, "refusing to write through a symlink that leaves the repository: " + rel, { path: rel });
+    }
+  }
+}
+
+// `cfg` is the loaded configuration (scaffold) or null (init). `docsConfig`
+// overrides the configuration the documentation paths are read from: init
+// writes no component descriptors, but it must still honour an existing
+// configuration's `docs.*` paths.
+export function installTemplates(repo, cfg, { write, root, force = false, eligible = null, docsConfig } = {}) {
   const written = [];
   const skipped = [];
   const targetRoot = root || (repo ? repo.root : process.cwd());
   const r = repo || new Repo(targetRoot, { noGit: false });
+  const docsSource = docsConfig === undefined ? cfg : docsConfig;
+  const skeleton = docsSkeleton(docsSource);
 
-  const put = (rel, content) => {
-    const abs = path.join(targetRoot, rel);
-    if (fs.existsSync(abs) && !force) { skipped.push(rel); return; }
-    if (!write) { written.push(rel + " (dry run)"); return; }
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, content.endsWith("\n") ? content : content + "\n");
-    written.push(rel);
-  };
+  // Plan every file first and check every target before writing anything, so
+  // a refused path leaves the repository exactly as it was.
+  const plan = [];
+  const put = (rel, content) => { plan.push([rel, content]); };
 
   // ── configuration ───────────────────────────────────────────────────────
-  const config = buildConfig(scanLayout(r, cfg));
+  const config = buildConfig(scanLayout(r, cfg), skeleton.docs);
   put("agentdoc/agentdoc.config.yaml", config);
   put("agentdoc/journeys.yaml", "schemaVersion: agentdoc.dev/journeys/v1\njourneys: []\n");
   for (const f of ["domains.yaml", "systems.yaml", "apis.yaml", "resources.yaml"]) {
@@ -69,12 +143,10 @@ export function installTemplates(repo, cfg, { write, root, force = false, eligib
   }
   put("agentdoc/observations/README.md", OBSERVATIONS_README);
 
-  // ── documentation hierarchy ──────────────────────────────────────────────
-  for (const f of ["PRODUCT.md", "ARCHITECTURE.md", "CONSTRAINTS.md"]) {
-    const tpl = fs.readFileSync(path.join(TEMPLATES_DIR, f), "utf8");
-    put("docs/" + f, tpl);
+  // ── documentation hierarchy (configured docs.* paths) ───────────────────
+  for (const t of skeleton.targets) {
+    put(t.path, fs.readFileSync(path.join(TEMPLATES_DIR, t.template), "utf8"));
   }
-  put("docs/adr/README.md", fs.readFileSync(path.join(TEMPLATES_DIR, "ADR.md"), "utf8"));
   put(".github/workflows/agentdoc.yml", fs.readFileSync(path.join(TEMPLATES_DIR, "ci.yml"), "utf8"));
 
   // ── per-unit component descriptors ──────────────────────────────────────
@@ -88,7 +160,30 @@ export function installTemplates(repo, cfg, { write, root, force = false, eligib
       put(u.root + "/" + cfg.discovery.componentDescriptorName, componentDescriptor(u));
     }
   }
-  return { written, skipped, note: write ? "files written" : "dry run: pass --write to apply" };
+
+  const seen = new Set();
+  for (const [rel] of plan) assertWritableInside(targetRoot, rel);
+  for (const [rel, content] of plan) {
+    if (seen.has(rel)) continue; // two roles configured onto one file: first wins
+    seen.add(rel);
+    const abs = path.join(targetRoot, rel);
+    if (fs.existsSync(abs) && !force) { skipped.push(rel); continue; }
+    if (!write) { written.push(rel + " (dry run)"); continue; }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content.endsWith("\n") ? content : content + "\n");
+    written.push(rel);
+  }
+  return {
+    written,
+    skipped,
+    ...(docsSource && skeleton.notConfigured.length
+      ? {
+          notConfigured: skeleton.notConfigured,
+          notConfiguredNote: "the configuration declares no path for these roles, so no skeleton was written for them; add them under docs: to scaffold them",
+        }
+      : {}),
+    note: write ? "files written" : "dry run: pass --write to apply",
+  };
 }
 
 // Layout inference for CREATE mode: which directories look like unit roots.
@@ -108,6 +203,7 @@ function scanLayout(repo, cfg) {
     for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
       if (e.isSymbolicLink() || skip.has(e.name)) continue;
       const rel = dir ? dir + "/" + e.name : e.name;
+      if (repo.isIgnored && repo.isIgnored(rel)) continue;
       if (e.isDirectory()) {
         if (e.name.startsWith(".")) continue;
         walk(rel, depth + 1);
@@ -269,7 +365,7 @@ const ADAPTER_FOR_MARKER = {
   platform: "wrangler",
 };
 
-function buildConfig(layout) {
+function buildConfig(layout, docs = DEFAULT_DOCS) {
   const roots = layout.map((l) => l.root);
   const groups = new Map();
   for (const r of roots) {
@@ -346,15 +442,26 @@ function buildConfig(layout) {
     "  graph: .agentdoc/graph.json",
     "  observations: agentdoc/observations",
     "",
-    "docs:",
-    "  product: docs/PRODUCT.md",
-    "  architecture: docs/ARCHITECTURE.md",
-    "  constraints: docs/CONSTRAINTS.md",
-    "  adrDir: docs/adr",
+    ...docsSection(docs),
     "",
   ].join("\n");
 }
 
+// The `docs:` block of a generated configuration. It repeats the configured
+// paths (init --force regenerates the file and must not move documentation
+// elsewhere), or the agentdoc/docs/ defaults when there is no configuration yet.
+function docsSection(docs) {
+  const scalar = (v) => (/^[A-Za-z0-9._/-]+$/.test(v) ? v : yamlStr(v));
+  const lines = [];
+  for (const key of ["product", "architecture", "constraints", "adrDir", "runbookDir"]) {
+    if (docs[key]) lines.push("  " + key + ": " + scalar(docs[key]));
+  }
+  if (Array.isArray(docs.normative) && docs.normative.length) {
+    lines.push("  normative:", ...docs.normative.map((g) => "    - " + yamlStr(g)));
+  }
+  return lines.length ? ["docs:", ...lines] : ["# docs: {}  # no documentation roles configured"];
+}
+
 const OBSERVATIONS_README = `# Runtime observations
 
 An ObservationSet records what an authoritative external system actually said,

package/core/sourcescan.mjs

@@ -7,6 +7,7 @@
 // knows the namespace convention.
 import path from "node:path";
 import fs from "node:fs";
+import { joinPath } from "./paths.mjs";
 
 const SPECIFIER_RE = /["'`]([A-Za-z@][A-Za-z0-9@._/+-]*(?:\.[A-Za-z0-9@._/+-]+)*(?:\/[A-Za-z0-9@._+*-]+)*)["'`]/g;
 
@@ -66,6 +67,7 @@ export function findMigrationDirs(repo, root, maxDepth = 5) {
       const abs = path.join(dirAbs, e.name);
       const rel = path.relative(repo.root, abs).split(path.sep).join("/");
       if (!repo.ownsUnitPath(root, rel)) continue;
+      if (repo.isIgnored && repo.isIgnored(rel)) continue;
       if (e.name === "migrations" || e.name === "migration") {
         out.push(rel);
         continue;
@@ -86,7 +88,8 @@ export function findMigrationDirs(repo, root, maxDepth = 5) {
 
 export function firstExistingFile(repo, root, names) {
   for (const n of names) {
-    if (repo.ownsUnitPath(root, root + "/" + n) && repo.exists(root + "/" + n)) return root + "/" + n;
+    const p = joinPath(root, n);
+    if (repo.ownsUnitPath(root, p) && repo.exists(p)) return p;
   }
   return null;
 }

package/docs/ADAPTERS.md

@@ -107,7 +107,7 @@ cannot name the file a fact came from, you cannot add the fact.
 | `dockerfile` | `Dockerfile`, `Containerfile` | deployable evidence |
 | `deploy-config` | `fly.toml`, `Procfile`, … | deployable evidence |
 | `wrangler` | `wrangler.toml/json` | bindings, crons, service bindings, trigger targets |
-| `database` | migrations, ORM config, pool evidence | logical-database ownership, or a candidate |
+| `database` | migrations, ORM config, pool evidence | logical-database ownership, or a candidate; the unit's migration directories |
 | `object-store` | bucket literals | logical-dataset edges, or an ambiguity |
 | `cache` | cache client evidence | cache bindings |
 | `events` | subject literals, declared constants, event-contract files | producers, consumers, reserved subjects |
@@ -220,7 +220,7 @@ Workspace roots come from every `Cargo.toml` that has `[workspace]`, not only
 the one at the repository root. The search is bounded to five directories
 down, stays inside the repository, and does not enter `discovery.notUnitRoots`
 or their descendants (the authored-descriptor exception is described below),
-`discovery.generatedDirs`, dot-directories, or `test` / `tests` / `examples` /
+`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
@@ -312,6 +312,45 @@ the result is `AGENTDOC_BINDING_AMBIGUOUS` and no edge.
 file pulled in with `-r` / `-c`; a lockfile's resolved versions; a PDM
 workspace; a workspace manifest deeper than the search bound.
 
+### `database`
+
+Migration authority and a connection string in one unit resolve to an authored
+logical-database Resource (by name: `<component>-postgres`, `-database`,
+`-db`, or the single Resource whose name starts with the component's).
+Migrations alone give a candidate and `AGENTDOC_RESOURCE_CANDIDATE`, never an
+edge.
+
+The adapter also records where the unit's migrations live, as
+`derived.migrationDirs` (`path`, `via`, `provenanceIds`). `impact` classifies a
+change under one of them as a resource change. Two routes, each with its own
+evidence:
+
+| `via` | directory | evidence |
+|---|---|---|
+| `directory-name` | a directory named `migrations` or `migration` inside the unit, at most five levels down; Prisma Migrate's `prisma/migrations` is one | the first file in it |
+| `alembic-versions` | `alembic/versions` | the first file in it |
+| `drizzle-config` | Drizzle Kit's `out` in the unit-root `drizzle.config.ts`, `.js` or `.mjs`; `./drizzle` when `out` is absent | the config file |
+
+The Drizzle config is code and is never executed. `out` is read only as a
+single string literal (a template literal without `${...}` counts), after
+comments are removed, and resolved against the config's directory. An `out`
+that is an expression, an environment variable, a shorthand property, set more
+than once, or possibly brought in by a spread is not guessed: the adapter
+records nothing and reports `AGENTDOC_MIGRATION_DIR_UNRESOLVED`, a warning that
+can be accepted. An `out` outside the unit is reported the same way. An `out`
+directory that does not exist yet records nothing; the existence probe is an
+input, so generating the first migration invalidates the graph.
+
+A recorded directory is migration authority, not ownership: it creates no
+binding. A migration change reaches a database only through the enclosing
+component's existing `usesResource` relations, or through a Resource that
+declares the directory in `spec.migrationPaths` (see `SPEC.md`).
+
+**What it cannot see:** a Drizzle config passed with `--config` under another
+name, a config below the unit root, and the migration layouts of Knex, Goose,
+Sequelize or TypeORM outside a `migrations` directory. Declare those with
+`spec.migrationPaths`.
+
 `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: [...]`.
@@ -373,9 +412,14 @@ places, and those are the honest exceptions worth naming:
   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.
+  its contracts, its provenance paths, its extractor identities, its declared
+  and detected migration directories — rather than a hand-written list of
+  technology filenames. A list would silently under-report for every
+  repository that is not Node-and-Go. One name rule remains as a fallback: a
+  path under a `migrations/`, `migration/` or `alembic/versions/` segment is a
+  resource change even where the graph records no migration directory (the
+  `database` adapter is off, or the directory is deeper than its walk), so
+  those repositories keep the answer they had.
 - `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

package/docs/BENCHMARK.md

@@ -1,7 +1,7 @@
 # BENCHMARK
 
-Two measurements back the numbers in the README. Both are reproducible from a
-checkout. Neither involves a model, so phrasing cannot move them.
+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`
 
@@ -9,25 +9,87 @@ The routing evaluation is described in [EVALS.md](EVALS.md). It has 30 scenarios
 on six repositories (Node, TypeScript, Go, Rust and Python), with thresholds
 registered on 2026-09-28 and not moved since. For each scenario, it compares
 the context `agentdoc query` + `agentdoc impact` returns with what an agent
-gets by reading only the component it is changing.
-
-| | reading the touched component | AgentDoc |
-|---|---|---|
-| facts the change needs, retrieved | 58% | **100%** |
-| retrieved facts that are unrelated (noise) | 40% | **8.7%** |
-| share of the repository's checks returned (selectivity) | 100% | **46%** (29% on the golden corpus) |
-| context size vs. reading the whole catalog | — | **−70%** |
-
-Every check a scenario requires is in AgentDoc's answer (verification recall
-1.0). The baseline never misses one either, because it runs every check in the
-repository. Selectivity is therefore the meaningful comparison: the share of
-the repository's checks the answer contains, counting everything the agent is
-shown. It is reported, not gated; small corpora inflate it, and a
-one-component corpus scores 100% because there is nothing to narrow.
-
-The size reduction is measured on the golden corpus (`examples/koda`). The
-smaller fixtures hold fewer than 100 facts, so the harness reports their
-reduction but does not aggregate it.
+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`
 

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.2.0 —
+      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.4.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
@@ -87,6 +93,8 @@ YAML or schema error names its file and line and needs no table.
 | `AGENTDOC_COMPILER_MISMATCH` | the compiler was upgraded | `compile` and commit |
 | `AGENTDOC_OVERRIDE_STALE` | a reviewed override's cited evidence changed | review the interpretation, then `pin-evidence` and update the digest |
 | `AGENTDOC_VERIFICATION_UNTIERED` | a check task has no recognisable tier | name the task, or extend the adapter |
+| `AGENTDOC_MIGRATION_PATH` | a Resource's `spec.migrationPaths` is a glob, is on a non-database Resource, or is shared by two Resources | declare the directory itself, once, on the logical database it migrates |
+| `AGENTDOC_MIGRATION_DIR_UNRESOLVED` | a Drizzle config's `out` is not a single string literal inside the unit | declare the directory with `spec.migrationPaths`, or accept the warning |
 
 ## Ordering inside `check`