agent-doc-system 1.2.0 → 1.3.0

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

@@ -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

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.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