agent-doc-system 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -9,6 +9,131 @@ refused by the next with `AGENTDOC_COMPILER_MISMATCH` until it is recompiled.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-11-07
+
+A graph compiled on your machine now passes `check` in CI and in a clean
+checkout. Files git ignores no longer count as compiler inputs, so a local
+build that fills an ignored directory no longer changes `inputHash`. A
+component whose descriptor sits at the repository root now owns the root files
+no other component owns, so `query` and `impact` route them. `init` and
+`scaffold --write` no longer write into your product's `docs/`: they follow the
+configured `docs.*` paths, and a new install without a configuration gets its
+skeleton under `agentdoc/docs/`. Releases are now published from CI with npm
+provenance, so `npm audit signatures` can verify that a release was built from
+this repository. The benchmark claim made in the 1.2.0 release notes is
+withdrawn, because its gap came from the evaluation and not from routing.
+
+Before you upgrade:
+
+- **Recompile committed graphs.** As with every release, a graph compiled by
+  1.2.0 is refused with `AGENTDOC_COMPILER_MISMATCH` until you run
+  `agentdoc compile` again.
+- **A descriptor or configuration path that points at a git-ignored file now
+  fails** with `AGENTDOC_PATH_UNRESOLVED`, as it would in a clean checkout.
+  Commit the file or stop ignoring it ([#45]).
+- **New installs write the documentation skeleton to `agentdoc/docs/`**
+  instead of `docs/`. A configuration that declares `docs.*` keeps its paths,
+  and no existing file is moved ([#59]).
+
+### Added
+
+- A deterministic `baseline-search` routing evaluation using working-tree file
+  reads and text search, without compiled relations ([#46]). CLI reports compare
+  catalog, corrected targeted and search recall/noise/check selectivity per
+  scenario, corpus and aggregate; `docs/EVALS.md` documents every heuristic.
+
+### Changed
+
+- Releases are now published only through a manual GitHub Actions workflow,
+  using npm trusted publishing (no token) with provenance, so `npm audit
+  signatures` can verify that a release was built from this repository
+  ([#51]). `RELEASING.md` in the repository describes the process.
+
+- **Behaviour change for new installs only:** without a configuration,
+  `agentdoc init` (and `scaffold --write`) now writes the documentation
+  skeleton to `agentdoc/docs/PRODUCT.md`, `agentdoc/docs/ARCHITECTURE.md`,
+  `agentdoc/docs/CONSTRAINTS.md` and `agentdoc/docs/adr/`, and records those
+  paths in the `docs:` block of the generated `agentdoc/agentdoc.config.yaml`
+  ([#59]). It used to write to `docs/`, which in many repositories is the
+  product's own user documentation and the source of a published docs site
+  (MkDocs, Docusaurus, GitHub Pages). Authored AgentDoc material now lives in
+  `agentdoc/`; generated output stays in `.agentdoc/`. Existing configurations
+  are unaffected: a configuration that declares `docs.*` keeps its paths,
+  `docs/...` included, and no existing file is moved. To keep `docs/` on a new
+  install, declare `docs.product`, `docs.architecture`, `docs.constraints` and
+  `docs.adrDir` in `agentdoc/agentdoc.config.yaml` before running `init`.
+
+### Fixed
+
+- A component whose descriptor sits at the repository root now owns the files
+  no nested component owns ([#50]). Before, `query vite.config.ts` failed with
+  `AGENTDOC_REF_UNRESOLVED` and `impact` listed the file in `unmatchedFiles`,
+  for both `vite.config.ts` and `./vite.config.ts`. Paths are now compared in
+  one canonical repository-relative form (no `./`), by whole path segment
+  (`src` never owns `src2/x`), and the longest owning root wins, so nested
+  components keep precedence and a contract file still routes to its API. A
+  root unit's derived paths (`README.md`, `package.json`, markers, provenance,
+  verification config paths) are no longer recorded as `./README.md`, so
+  `impact` now recognises them as documentation and compiler inputs. Without a
+  root descriptor, root files stay unmatched. Graphs of repositories without a
+  root component are unchanged.
+
+- `agentdoc scaffold --write` and `agentdoc init` now write the documentation
+  skeleton (`PRODUCT.md`, `ARCHITECTURE.md`, `CONSTRAINTS.md`, the ADR README)
+  to the configured `docs.product`, `docs.architecture`, `docs.constraints` and
+  `docs.adrDir` paths ([#49]). Both used to write to `docs/` even when the
+  configuration said otherwise, and `docs/` is often the product's own user
+  documentation. The paths are read through the same loader as `compile` and
+  `audit`. A role the configuration omits is listed under `notConfigured`
+  instead of falling back to `docs/`. An existing file is still skipped unless
+  `init --force` is given. A path that leaves the repository, including through
+  a symlink, fails with `AGENTDOC_PATH_ESCAPE` before anything is written.
+  Without a configuration, `init` uses the `agentdoc/docs/` defaults (see
+  [#59] under Changed).
+
+- Files git ignores no longer enter the compiler's inputs or `inputHash`
+  ([#45]). A local build writing into an ignored directory (`astro build`
+  filling `.astro/`, a `build/` tree, `*.log`) used to change the hash, so a
+  graph compiled after it failed `check` with `AGENTDOC_GRAPH_FRESHNESS` in CI
+  and in every clean checkout, while passing on the author's machine. Reads,
+  existence probes, listings and discovery now exclude git-ignored paths, with
+  git itself as the oracle: tracked files always count, and nested
+  `.gitignore`, `.git/info/exclude`, `core.excludesFile` and negations behave
+  exactly as in git. A non-ignored untracked file is still an input. Without
+  git the previous behaviour (filesystem minus `discovery.generatedDirs`)
+  holds. Committed graphs keep their hash. A descriptor or configuration
+  that points at a git-ignored file (for example a spec generated into an
+  ignored directory before `compile`) now fails with
+  `AGENTDOC_PATH_UNRESOLVED`, as it would in a clean checkout: commit the file
+  or stop ignoring it. The `git clean -fdX` before
+  `compile` documented as a workaround in lbframe/klozeo's `AGENTS.md` is no
+  longer needed.
+
+- `npm publish` no longer auto-corrects `package.json`: the `bin` path is
+  committed in npm's normalized form, `bin/agentdoc.mjs` ([#55]).
+
+- All routing evaluation systems and the noise closure now share fact labels
+  ([#46]). Corrected targeted micro-recall is 100/101 (0.9901), rather than
+  the previously reported gap. Search matches catalog recall in 21/30 scenarios;
+  measurements and limitations are in `docs/BENCHMARK.md`. Normalized full fact
+  counts fall below the existing size floor, so aggregate size reduction is
+  reported as unmeasured. Thresholds, scenarios and core routing are unchanged.
+
+- **Withdrawn benchmark claim.** The README, `docs/BENCHMARK.md` and the 1.2.0
+  release notes reported that routing retrieves 100% of the facts a change
+  needs against 58% for a baseline that reads only the touched component, with
+  noise under 9% against 40%, and an answer about 70% smaller than the whole
+  catalog. The gap came from the evaluation, not from
+  routing: the baseline already held almost every expected fact under a
+  different label, and it read relations from the compiled graph that an agent
+  without AgentDoc does not have. The size figure counted the same component
+  once per relation label; deduplicated, every corpus falls below the size
+  floor. Both claims are
+  removed. A baseline that finds
+  relations with search alone is now measured in the benchmark. The
+  [correction](docs/BENCHMARK.md#correction-the-fact-recall-comparison-is-withdrawn)
+  gives the details.
+
 ## [1.2.0] - 2026-10-27
 
 Rust and Python are now supported at the same level as Node and Go. Before
@@ -242,7 +367,8 @@ First public release.
   for project health.
 - An Agent Skill under `skills/agent-doc-system/`.
 
-[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/lbframe/agent-doc-system/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/lbframe/agent-doc-system/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/lbframe/agent-doc-system/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/lbframe/agent-doc-system/releases/tag/v1.0.0
@@ -267,3 +393,10 @@ First public release.
 [#40]: https://github.com/lbframe/agent-doc-system/issues/40
 [#41]: https://github.com/lbframe/agent-doc-system/issues/41
 [#43]: https://github.com/lbframe/agent-doc-system/issues/43
+[#45]: https://github.com/lbframe/agent-doc-system/issues/45
+[#46]: https://github.com/lbframe/agent-doc-system/issues/46
+[#49]: https://github.com/lbframe/agent-doc-system/issues/49
+[#50]: https://github.com/lbframe/agent-doc-system/issues/50
+[#51]: https://github.com/lbframe/agent-doc-system/issues/51
+[#55]: https://github.com/lbframe/agent-doc-system/issues/55
+[#59]: https://github.com/lbframe/agent-doc-system/issues/59

package/README.md

@@ -98,7 +98,7 @@ What every adapter derives, and what it deliberately cannot see, is in [docs/ADA
 
 Measured, reproducible, and with no model in the loop. Method and caveats are in [docs/BENCHMARK.md](docs/BENCHMARK.md).
 
-- **The right context: 100% vs. 58%.** Across 30 routing scenarios (Node, Go, Rust, Python), `query` + `impact` retrieves every fact the change needs. Reading only the touched component retrieves 58%. Noise stays under 9%, against 40%. Every check the change requires is in the answer, and that answer holds about half of the repository's checks (29% on the largest corpus), not all of them. The thresholds were fixed before the first run and have not moved since.
+- **The checks a change needs, not the whole suite.** Across 30 routing scenarios (Node, Go, Rust, Python), every check the change requires is in the answer, and that answer holds about half of the repository's checks (29% on the largest corpus), not all of them. The thresholds were fixed before the first run and have not moved since.
 - **Seconds to map a real repository.** A fresh `init` → `scaffold` → `compile` takes 1.0–4.6 s on four public repositories, from 141 to 5,142 files (axum, pydantic-ai, full-stack-fastapi-template, create-t3-turbo). No edit was needed beyond choosing each component's placement.
 - **A briefing, not a dump.** A `query` answer is about 100–260 tokens: what the change reaches, what to read, and which checks to run.
 - **The same graph every time.** Compiles are byte-identical, and CI can verify it.

package/adapters/cache.mjs

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

package/adapters/database.mjs

@@ -9,6 +9,7 @@
 //     library shipped migrations but explicitly did not own a database.
 import { Adapter } from "./registry.mjs";
 import { firstExistingFile, findMigrationDirs } from "../core/sourcescan.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 const ORM_CONFIG = [
   "drizzle.config.ts", "drizzle.config.js", "drizzle.config.mjs",
@@ -37,8 +38,8 @@ export class DatabaseAdapter extends Adapter {
     }
     const alembicDir = migrationDirs.find((d) => d === "alembic/versions" || d.endsWith("/alembic/versions"));
     if (alembicDir) {
-      const ini = root + "/alembic.ini";
-      const pyproject = root + "/pyproject.toml";
+      const ini = joinPath(root, "alembic.ini");
+      const pyproject = joinPath(root, "pyproject.toml");
       if (repo.exists(ini)) {
         const text = repo.readText(ini);
         if (/^\s*\[alembic\]/m.test(text) || /^\s*script_location\s*=/m.test(text)) evidencePath = ini;

package/adapters/deploy-config.mjs

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

package/adapters/dockerfile.mjs

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

package/adapters/generic.mjs

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

package/adapters/github-actions.mjs

@@ -4,6 +4,7 @@
 import path from "node:path";
 import { Adapter } from "./registry.mjs";
 import { parseYamlDocuments } from "../core/yaml.mjs";
+import { ownsPath } from "../core/paths.mjs";
 
 export class GitHubActionsAdapter extends Adapter {
   static adapterName = "github-actions";
@@ -224,7 +225,7 @@ function literalPath(value) {
   const p = path.posix.normalize(value);
   return p === ".." || p.startsWith("../") ? null : p.replace(/\/$/, "");
 }
-function within(p, root) { return root === "." || p === root || p.startsWith(root + "/"); }
+function within(p, root) { return ownsPath(root, p); }
 function shellQuote(p) { return /^[A-Za-z0-9_./-]+$/.test(p) ? p : "'" + p.replace(/'/g, "'\\''") + "'"; }
 
 function scopedTo(unit, args, cwd, filters, units, repo) {

package/adapters/go.mjs

@@ -1,6 +1,7 @@
 // Go adapter: go.mod / go.work as unit markers, module graph as build
 // relations, and the go toolchain's own verification commands.
 import { Adapter } from "./registry.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 export class GoAdapter extends Adapter {
   static adapterName = "go";
@@ -26,13 +27,13 @@ export class GoAdapter extends Adapter {
     return out;
   }
   detect(ctx, root) {
-    const p = root + "/go.mod";
+    const p = joinPath(root, "go.mod");
     if (!ctx.repo.exists(p)) return null;
-    return { path: p, shape: ctx.repo.isDir(root + "/cmd") ? "deployable" : "importable" };
+    return { path: p, shape: ctx.repo.isDir(joinPath(root, "cmd")) ? "deployable" : "importable" };
   }
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
-    const p = unit.root + "/go.mod";
+    const p = joinPath(unit.root, "go.mod");
     if (!repo.exists(p)) return {};
     const derived = { languages: new Set(["go"]), runtimes: new Set(["go"]) };
     const text = repo.readText(p);

package/adapters/node.mjs

@@ -1,5 +1,6 @@
 // Node adapter: package.json as the unit marker and manifest authority.
 import { Adapter } from "./registry.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 // A script name maps to a verification tier. Deliberately conservative and
 // project-neutral: a script that does not look like a check is not a check.
@@ -20,7 +21,7 @@ export class NodeAdapter extends Adapter {
     super({ name: "node", version: "1.0.0", kind: "unit-marker" });
   }
   detect(ctx, root) {
-    const p = root + "/package.json";
+    const p = joinPath(root, "package.json");
     if (!ctx.repo.exists(p)) return null;
     let pkg;
     try {
@@ -34,7 +35,7 @@ export class NodeAdapter extends Adapter {
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
     const root = unit.root;
-    const manifestPath = root + "/package.json";
+    const manifestPath = joinPath(root, "package.json");
     if (!repo.exists(manifestPath)) return {};
     const derived = { languages: new Set(["javascript"]), runtimes: new Set(["node"]) };
     const pkg = unit.pkg || repo.readJson(manifestPath);

package/adapters/rust.mjs

@@ -225,6 +225,9 @@ function childDirectoryNames(repo, dir) {
     if (ent.isSymbolicLink() || !ent.isDirectory()) continue;
     if (!ent.name || ent.name.startsWith(".")) continue;
     if (generated.has(ent.name) || WORKSPACE_SKIP_DIRS.has(ent.name)) continue;
+    // Each child is probed for Cargo.toml, and a probe is an input: a
+    // git-ignored directory must not even be visited (issue #45).
+    if (repo.isIgnored && repo.isIgnored(dir ? dir + "/" + ent.name : ent.name)) continue;
     names.push(ent.name);
   }
   names.sort();

package/adapters/turborepo.mjs

@@ -4,6 +4,7 @@
 // verification answer available for a monorepo unit.
 import { Adapter } from "./registry.mjs";
 import { parseYamlDocuments } from "../core/yaml.mjs";
+import { isRepoRoot, joinPath } from "../core/paths.mjs";
 
 // Whether a declared task is a check is decided by `taskTier` alone, not by a
 // second, narrower pattern. Two lists meant two places to disagree: a task that
@@ -19,7 +20,7 @@ export class TurborepoAdapter extends Adapter {
     super({ name: "turborepo", version: "1.0.0", kind: "ci" });
   }
   detect(ctx, root) {
-    const p = root + "/turbo.json";
+    const p = joinPath(root, "turbo.json");
     if (!ctx.repo.exists(p)) return null;
     return { path: p, shape: "importable" };
   }
@@ -122,7 +123,7 @@ function taskTier(t) {
 
 // A task graph normally lives at the workspace root, not in each package.
 function nearestTurboConfig(repo, root) {
-  let dir = root;
+  let dir = isRepoRoot(root) ? "" : root;
   for (let i = 0; i < 12; i++) {
     const p = dir ? dir + "/turbo.json" : "turbo.json";
     if (repo.exists(p)) return p;

package/adapters/typescript.mjs

@@ -6,6 +6,7 @@
 import path from "node:path";
 import { Adapter } from "./registry.mjs";
 import { parseYamlDocuments } from "../core/yaml.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 export class TypeScriptAdapter extends Adapter {
   static adapterName = "typescript";
@@ -13,13 +14,13 @@ export class TypeScriptAdapter extends Adapter {
     super({ name: "typescript", version: "1.0.0", kind: "unit-marker" });
   }
   detect(ctx, root) {
-    const p = root + "/tsconfig.json";
+    const p = joinPath(root, "tsconfig.json");
     if (!ctx.repo.exists(p)) return null;
     return { path: p, shape: "importable" };
   }
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
-    const p = unit.root + "/tsconfig.json";
+    const p = joinPath(unit.root, "tsconfig.json");
     if (!repo.exists(p)) return {};
     const derived = { languages: new Set(["typescript"]), runtimes: new Set(["node"]) };
     let ts;
@@ -43,8 +44,9 @@ export class TypeScriptAdapter extends Adapter {
     // real HTTP surface and must be visible to the query surface.
     const routes = [];
     for (const base of ["src/app", "app", "src/pages", "pages"]) {
-      if (!repo.isDir(unit.root + "/" + base)) continue;
-      for (const f of repo.walkUnit(unit.root, unit.root + "/" + base)) {
+      const dir = joinPath(unit.root, base);
+      if (!repo.isDir(dir)) continue;
+      for (const f of repo.walkUnit(unit.root, dir)) {
         const routePath = routeFor(unit.root, base, f);
         if (!routePath) continue;
         const rpr = prov.add("observed", f, "route-extractor", ["der:" + compRef + ":/routes"]);
@@ -63,7 +65,7 @@ export class TypeScriptAdapter extends Adapter {
 }
 
 function routeFor(root, base, file) {
-  const rel = file.slice((root + "/" + base).length + 1);
+  const rel = file.slice(joinPath(root, base).length + 1);
   if (base.endsWith("app")) {
     if (!rel.endsWith("/route.ts") && !rel.endsWith("/route.tsx") && !rel.endsWith("/route.js")) return null;
     const segs = rel.split("/").slice(0, -1);

package/adapters/wrangler.mjs

@@ -11,6 +11,7 @@
 import { Adapter } from "./registry.mjs";
 import { parse as parseToml } from "../core/toml.mjs";
 import { sourceFiles } from "../core/sourcescan.mjs";
+import { joinPath } from "../core/paths.mjs";
 
 const MANIFESTS = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"];
 
@@ -21,13 +22,13 @@ export class WranglerAdapter extends Adapter {
   }
   detect(ctx, root) {
     for (const n of MANIFESTS) {
-      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+      if (ctx.repo.exists(joinPath(root, n))) return { path: joinPath(root, n), shape: "deployable" };
     }
     return null;
   }
   extract(ctx, unit) {
     const { repo, prov, compRef } = ctx;
-    const file = MANIFESTS.map((n) => unit.root + "/" + n).find((p) => repo.exists(p));
+    const file = MANIFESTS.map((n) => joinPath(unit.root, n)).find((p) => repo.exists(p));
     if (!file) return {};
     let toml;
     try {

package/bin/agentdoc.mjs

@@ -19,7 +19,7 @@ import { observationFreshness, stalenessDiagnostics } from "../core/observations
 import { assertNoSecretsInText } from "../core/secrets.mjs";
 import { installTemplates } from "../core/scaffold.mjs";
 import { COMMANDS, flagsOf, parseArgs, commandHelp, UsageError } from "./commands.mjs";
-import { loadSchemaBundle, loadConfig } from "../core/descriptors.mjs";
+import { loadSchemaBundle, loadConfig, CONFIG_PATH } from "../core/descriptors.mjs";
 import { execFileSync } from "node:child_process";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -353,7 +353,14 @@ try {
         : {}),
     }, true);
   } else if (cmd === "init") {
-    const result = installTemplates(null, null, { write: true, root: ROOT, force: opt("force") });
+    // An existing configuration is the authority on where documentation lives
+    // (issue #49). Load it through the compiler's own loader, so init, scaffold,
+    // audit and compile cannot disagree, and so an invalid or escaping docs path
+    // is rejected before anything is written.
+    const docsConfig = fs.existsSync(path.join(ROOT, CONFIG_PATH))
+      ? loadConfig(new Repo(ROOT, { noGit: true }), loadSchemaBundle().bundle)
+      : null;
+    const result = installTemplates(null, null, { write: true, root: ROOT, force: opt("force"), docsConfig });
     out(result, true);
   } else if (cmd === "eval") {
     const which = positional[0] || "routing";

package/bin/usage.txt

@@ -5,6 +5,8 @@ agentdoc — portable documentation & software-catalog system
   agentdoc <command> --help          every flag one command accepts (also: agentdoc help <command>)
 
   agentdoc init [--force]            write a configuration and documentation skeleton
+                                     (docs skeleton goes to the configured docs.* paths;
+                                     agentdoc/docs/ when there is no configuration yet)
   agentdoc audit                     inventory the repository, classify every fact
   agentdoc scaffold [--write]        generate a CREATE-mode skeleton from the audit
   agentdoc validate                  sources + schemas + semantic checks

package/core/audit.mjs

@@ -19,6 +19,7 @@ import { classifyContractFile } from "./contracts.mjs";
 import { ContextIndex } from "./query.mjs";
 import { expandGlob, isRepoPath } from "./fsx.mjs";
 import { isNormative, NORMATIVE_SEMANTICS_PREFIX } from "./normative.mjs";
+import { isRepoRoot, longestOwner } from "./paths.mjs";
 
 const DOC_EXT = /\.(md|mdx|adoc|rst|txt)$/;
 
@@ -143,11 +144,12 @@ export function audit(repo, cfg, res) {
       configured.push({ role, path: dir, configured: false });
     }
   }
-  const unitRoots = new Set(res.discovery.units.map((u) => u.root));
-  const insideComponent = (p) => {
-    for (const r of unitRoots) if (p === r || p.startsWith(r + "/")) return r;
-    return null;
-  };
+  // The most specific unit root containing the path. A root unit is left out
+  // on purpose: it contains the whole repository, so counting it would make
+  // every repository-wide hierarchy document "component-scoped" and the
+  // distinction this check draws would disappear.
+  const unitRoots = [...new Set(res.discovery.units.map((u) => u.root))].filter((r) => !isRepoRoot(r));
+  const insideComponent = (p) => longestOwner(unitRoots, p);
 
   // The audit reports; it does not gate. These are therefore collected as audit
   // findings on the report rather than pushed into the compile-time diagnostics,

package/core/compile.mjs

@@ -24,6 +24,7 @@ import {
 } from "./normative.mjs";
 import { loadAdapters } from "../adapters/index.mjs";
 import { loadCargoUnit, analyzeCargoDeps, rustIdentsInSource } from "../adapters/rust.mjs";
+import { joinPath, ownsPath } from "./paths.mjs";
 import {
   COMPILER_NAME, COMPILER_VERSION, GRAPH_SCHEMA_VERSION,
   assembleGraph, serializeGraph, finalizeSerialization, subjectResolver,
@@ -300,7 +301,7 @@ export function compile(root, opts = {}) {
   // every graph that does not enable python.
   const pythonOn = adapters.some((a) => a.name === "python");
   for (const unit of discovery.eligible) {
-    const pkgPath = unit.root + "/package.json";
+    const pkgPath = joinPath(unit.root, "package.json");
     if (repo.exists(pkgPath)) {
       try {
         const pkg = repo.readJson(pkgPath);
@@ -310,7 +311,7 @@ export function compile(root, opts = {}) {
         res.errors.push(new AgentDocError(CODES.SCHEMA, "package.json is not valid JSON: " + pkgPath, { path: pkgPath }));
       }
     }
-    const gomodPath = unit.root + "/go.mod";
+    const gomodPath = joinPath(unit.root, "go.mod");
     if (repo.exists(gomodPath)) {
       const m = /^module\s+(\S+)/m.exec(repo.readText(gomodPath));
       unit.goModule = m ? m[1] : null;
@@ -398,7 +399,7 @@ export function compile(root, opts = {}) {
       if (t && t.component && t.component.ref !== unit.component.ref) deps.add(t.component.ref);
     }
     if (unit.goModule) {
-      const gomod = repo.exists(unit.root + "/go.mod") ? repo.readText(unit.root + "/go.mod") : "";
+      const gomod = repo.exists(joinPath(unit.root, "go.mod")) ? repo.readText(joinPath(unit.root, "go.mod")) : "";
       const goReqs = [...gomod.matchAll(/^\s*(?:require\s+)?([a-z0-9.]+\.[a-z0-9./-]+)\s+v[0-9]/gm)].map((m) => m[1]);
       productionDependencies.set(unit.component.ref, [...(productionDependencies.get(unit.component.ref) || []), ...goReqs]);
       for (const m of gomod.matchAll(/^\s*(?:require\s+)?([a-z0-9.]+\.[a-z0-9./-]+)\s+v[0-9]/gm)) {
@@ -796,14 +797,15 @@ export function compile(root, opts = {}) {
     ...schemaInputs,
     ...adapters.map((a) => ADAPTER_VERSION_INPUT_PREFIX + a.name + "@" + a.version),
   ]);
-  const dirtySet = new Set(repo.dirtyPaths().filter((p) => p !== graphPath));
+  // The same git status snapshot the ignore oracle answered from (fsx.mjs).
+  const dirtySet = new Set(repo.dirtyPaths({ snapshot: true }).filter((p) => p !== graphPath));
   const walkedDirs = [...repo.walks.keys()];
   const dirty = [...dirtySet].some(
     (p) =>
       repo.readPaths.has(p) ||
       repo.probes.has(p) ||
       repo.listings.has(p) ||
-      walkedDirs.some((d) => (d === "." ? true : p === d || p.startsWith(d + "/")))
+      walkedDirs.some((d) => ownsPath(d, p))
   );
   graph.source = { commit, dirty, inputHash };
 

package/core/derive.mjs

@@ -7,6 +7,7 @@
 import path from "node:path";
 import { assertRepoPath } from "./fsx.mjs";
 import { CODES } from "./codes.mjs";
+import { joinPath } from "./paths.mjs";
 
 const DEFAULT_DOC_CANDIDATES = ["README.md", "ARCHITECTURE.md", "AGENTS.md", "CONTRIBUTING.md", "DESIGN.md", "OVERVIEW.md"];
 const DEFAULT_CONSTRAINT_CANDIDATES = ["CONSTRAINTS.md", "INVARIANTS.md"];
@@ -33,15 +34,15 @@ export function genericFacts(ctx, unit) {
   const constraints = [];
   const runbooks = [];
   for (const n of docNames) {
-    const p = root + "/" + n;
+    const p = joinPath(root, n);
     if (repo.exists(p)) { docs.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/docs"]); }
   }
   for (const n of constraintNames) {
-    const p = root + "/" + n;
+    const p = joinPath(root, n);
     if (repo.exists(p)) { constraints.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/constraints"]); }
   }
   for (const n of runbookNames) {
-    const p = root + "/" + n;
+    const p = joinPath(root, n);
     if (repo.exists(p)) { runbooks.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/runbooks"]); }
   }
   const spec = ctx.componentEntity().doc.spec || {};

package/core/descriptors.mjs

@@ -20,6 +20,7 @@ import { parseYamlDocuments } from "./yaml.mjs";
 import { scanForSecrets } from "./secrets.mjs";
 import { formatErrors } from "./jsonschema.mjs";
 import { SchemaBundle } from "./jsonschema.mjs";
+import { joinPath, ownsPath } from "./paths.mjs";
 
 export const KINDS = Object.freeze(["Domain", "System", "Component", "API", "Resource"]);
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -177,7 +178,7 @@ function descriptorGlobs(repo, cfg) {
   // glob — its descriptor lives at a fixed path and must be loaded even when
   // no componentDescriptors glob happens to cover that directory.
   for (const r of cfg.discovery.supplementalRoots || []) {
-    const f = String(r).replace(/\/+$/, "") + "/" + cfg.discovery.componentDescriptorName;
+    const f = joinPath(String(r), cfg.discovery.componentDescriptorName);
     if (repo.exists(f)) componentFiles.add(f);
   }
   const centralFiles = new Set();
@@ -473,7 +474,7 @@ export function loadReviewedOverrides(repo, cfg, refs, byRef) {
         : null;
       for (const ev of o.evidence) {
         const p = ev.path;
-        const scoped = p === o.contractRef || p.startsWith(subjectRoot + "/") || (targetRoot && p.startsWith(targetRoot + "/"));
+        const scoped = p === o.contractRef || ownsPath(subjectRoot, p) || (targetRoot !== null && ownsPath(targetRoot, p));
         if (!scoped) {
           throw new AgentDocError(
             CODES.RELATION_KIND,