agent-doc-system 1.1.0 → 1.3.0

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.walk(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));
@@ -275,9 +275,9 @@ try {
       }
     }
     const ctx = queryContext(graph, needle, { budget });
-    if (opt("md")) out(renderContext(ctx));
+    if (opt("md")) out(renderContext(ctx, { budget }));
     else if (opt("json")) out(ctx, true);
-    else out(renderContext(ctx));
+    else out(renderContext(ctx, { budget }));
   } else if (cmd === "impact") {
     // Impact answers a question about the working tree, so it compiles in
     // memory rather than reading the committed graph. Refusing a stale graph
@@ -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,
@@ -160,7 +162,9 @@ export function audit(repo, cfg, res) {
     if (!DOC_EXT.test(f)) continue;
     const owners = graph.entities.filter((e) => {
       const d = e.derived || {};
-      return (d.docs || []).includes(f) || (d.constraints || []).includes(f) || (d.runbooks || []).includes(f);
+      const context = e.entity.spec?.context || {};
+      return [d, context].some((c) =>
+        ["docs", "constraints", "runbooks"].some((key) => (c[key] || []).includes(f)));
     }).map((e) => e.ref);
     const role = (configured.find((h) => h.path === f) || {}).role || null;
     docInventory.push({ path: f, linkedTo: owners.sort(), role });
@@ -193,9 +197,9 @@ export function audit(repo, cfg, res) {
       subject: d.path,
       refs: [d.path],
       message:
-        "document is claimed by no component" +
+        "document is claimed by no entity" +
         (d.role ? " and its configured role (" + d.role + ") is not a repository-wide role" : "") +
-        ". Link it from a component descriptor, or remove it.",
+        ". Link it from an entity descriptor, or remove it.",
     });
   }
   for (const h of hierarchyDocs) {

package/core/codes.mjs

@@ -77,6 +77,9 @@ export const CODES = {
   WARNING_ACCEPTANCE: "AGENTDOC_WARNING_ACCEPTANCE",
   OVERRIDE_STALE: "AGENTDOC_OVERRIDE_STALE",
   JOURNEY: "AGENTDOC_JOURNEY",
+
+  // language manifests
+  PYTHON_SPECIFIER: "AGENTDOC_PYTHON_SPECIFIER",
 };
 
 // Warning codes that a reviewer may explicitly accept. Anything outside this
@@ -94,6 +97,7 @@ export const ACCEPTABLE_WARNING_CODES = Object.freeze([
   "AGENTDOC_VERIFICATION_UNTIERED",
   "AGENTDOC_NORMATIVE_UNCOVERED",
   "AGENTDOC_REQUIREMENT_UNVERIFIED",
+  "AGENTDOC_PYTHON_SPECIFIER",
 ]);
 
 export class AgentDocError extends Error {

package/core/compile.mjs

@@ -17,11 +17,14 @@ import { redactCommand } from "./secrets.mjs";
 import { formatErrors } from "./jsonschema.mjs";
 import { validateContractFile } from "./contracts.mjs";
 import { sourceFiles, importSpecifiers } from "./sourcescan.mjs";
+import { readPythonUnit, pythonImportNames } from "../adapters/python.mjs";
 import { applyWarningAcceptances } from "./acceptances.mjs";
 import {
   loadNormativeDocuments, verifyCitation, normativeCoverage, isNormative, isRequirementKey, NORMATIVE_SEMANTICS_PREFIX,
 } 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,
@@ -130,11 +133,6 @@ export function compile(root, opts = {}) {
   for (const api of sources.entities.filter((e) => e.kind === "API")) {
     collect(() => validateContractFile(repo, bundle, api), res.errors);
   }
-  res.errors.push(...validateOidcProviders({ repo, sources, discovery: null }));
-
-  if (res.errors.length) {
-    return earlyOut(res, { entities: sources.entities.length });
-  }
 
   let adapters;
   try {
@@ -147,16 +145,22 @@ export function compile(root, opts = {}) {
     throw e;
   }
   const discovery = discoverUnits(repo, cfg, adapters);
+  repo.nestedUnitRoots = discovery.nestedRoots;
   // Eligibility is the compiler's own answer to "which directories are units" —
   // exposed on the result so scaffold can write descriptors for exactly these
   // roots rather than re-deriving them from filesystem markers.
   res.discovery = discovery;
-  const match = matchComponents(discovery.eligible, sources.entities.filter((e) => e.kind === "Component"));
-  res.errors.push(...match.errors);
 
-  // OIDC discovery must be exposed by the provider's own source. Re-check now
-  // that component -> unit bindings are known.
+  // A provider descriptor sits at its unit root. Check its source only after
+  // ownership is known, while still reporting this error alongside other
+  // descriptor/contract errors rather than hiding it behind an early return.
   res.errors.push(...validateOidcProviders({ repo, sources, discovery }));
+  if (res.errors.length) {
+    return earlyOut(res, { entities: sources.entities.length });
+  }
+
+  const match = matchComponents(discovery.eligible, sources.entities.filter((e) => e.kind === "Component"), cfg);
+  res.errors.push(...match.errors);
 
   if (res.errors.length) {
     return earlyOut(res, { entities: sources.entities.length, units: discovery.eligible.length });
@@ -285,8 +289,19 @@ export function compile(root, opts = {}) {
   // ── manifest pre-pass: identify each unit's package / module namespace ────
   // Done before extraction so cross-unit resolution never depends on the order
   // in which units happen to be processed.
+  // Cargo.toml is read only when the rust adapter is on. An existence probe is
+  // part of the input hash, so probing it for every unit would change every
+  // graph that does not enable rust.
+  const rustOn = adapters.some((a) => a.name === "rust");
+  ctx.unitByCrateName = new Map();
+  ctx.ambiguousCrateNames = new Map();
+  ctx.rustAmbiguity = new Map();
+  // A Python manifest is read only when the python adapter is on. An existence
+  // probe is part of the input hash, so probing one for every unit would change
+  // 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);
@@ -296,20 +311,73 @@ 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;
     }
+    if (rustOn) loadCargoUnit(repo, unit);
+    if (pythonOn) {
+      const py = readPythonUnit(repo, unit.root);
+      if (py.manifest) {
+        unit.pythonMarker = py.manifest;
+        unit.pythonManifest = py.manifest;
+        unit.pythonDist = py.dist;
+        unit.pythonImports = py.ambiguousImports ? null : py.importNames;
+        unit.pythonProdDeps = [...new Set([
+          ...py.prodDeps,
+          ...py.sourceDeps.filter((n) => !py.devDeps.includes(n) && !py.prodDeps.includes(n)),
+        ])].sort();
+        unit.pythonDevDeps = py.devDeps;
+        unit.pythonPathDeps = py.pathDeps;
+        if (py.error) res.errors.push(py.error);
+      }
+    }
   }
   const unitByPkgName = new Map();
   const unitByGoModule = new Map();
+  const unitByPythonDist = new Map();
+  const unitByPythonImport = new Map();
+  const distOwners = new Map();
+  const importOwners = new Map();
   for (const unit of discovery.eligible) {
     if (unit.pkgName && !unitByPkgName.has(unit.pkgName)) unitByPkgName.set(unit.pkgName, unit);
     if (unit.goModule && !unitByGoModule.has(unit.goModule)) unitByGoModule.set(unit.goModule, unit);
+    if (unit.pythonDist) {
+      if (!distOwners.has(unit.pythonDist)) distOwners.set(unit.pythonDist, []);
+      distOwners.get(unit.pythonDist).push(unit);
+    }
+    if (Array.isArray(unit.pythonImports)) {
+      for (const name of unit.pythonImports) {
+        if (!importOwners.has(name)) importOwners.set(name, []);
+        importOwners.get(name).push(unit);
+      }
+    }
+  }
+  for (const [name, owners] of distOwners) {
+    if (owners.length === 1) unitByPythonDist.set(name, owners[0]);
+    else for (const u of owners) u.pythonDistConflict = true;
+  }
+  for (const [name, owners] of importOwners) {
+    if (owners.length === 1) unitByPythonImport.set(name, owners[0]);
+    else for (const u of owners) u.pythonImportConflict = true;
   }
   ctx.unitByPkgName = unitByPkgName;
   ctx.unitByGoModule = unitByGoModule;
+  if (rustOn) {
+    const owners = new Map();
+    for (const unit of discovery.eligible) {
+      if (!unit.crateName) continue;
+      if (!owners.has(unit.crateName)) owners.set(unit.crateName, []);
+      owners.get(unit.crateName).push(unit);
+    }
+    for (const [name, list] of [...owners.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+      if (list.length === 1) ctx.unitByCrateName.set(name, list[0]);
+      else ctx.ambiguousCrateNames.set(name, list.slice().sort((a, b) => (a.root < b.root ? -1 : 1)));
+    }
+  }
+  ctx.unitByPythonDist = unitByPythonDist;
+  ctx.unitByPythonImport = unitByPythonImport;
 
   // Manifest-declared unit dependencies, computed before any adapter runs so
   // that cross-unit reasoning never depends on adapter execution order.
@@ -317,6 +385,7 @@ export function compile(root, opts = {}) {
   // matches a dependency name rather than a blob of source.
   const productionDependencies = new Map();
   const dependencyMap = new Map();
+  const unitsByRoot = new Map(discovery.eligible.map((u) => [u.root, u]));
   for (const unit of discovery.eligible) {
     if (!unit.component) continue;
     const deps = new Set();
@@ -330,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)) {
@@ -338,6 +407,32 @@ export function compile(root, opts = {}) {
         if (t && t.component && t.component.ref !== unit.component.ref) deps.add(t.component.ref);
       }
     }
+    if (rustOn && unit.cargoPackage) {
+      const cargo = analyzeCargoDeps(unit, unitsByRoot);
+      productionDependencies.set(unit.component.ref, [
+        ...(productionDependencies.get(unit.component.ref) || []),
+        ...cargo.prodNames,
+      ]);
+      for (const hit of cargo.resolved) {
+        if (hit.ambiguous || !hit.target || !hit.target.component) continue;
+        if (hit.target.component.ref !== unit.component.ref) deps.add(hit.target.component.ref);
+      }
+    }
+    if (unit.pythonMarker) {
+      const pyNames = [...new Set([...(unit.pythonProdDeps || []), ...(unit.pythonDevDeps || [])])];
+      productionDependencies.set(unit.component.ref, [
+        ...(productionDependencies.get(unit.component.ref) || []),
+        ...(unit.pythonProdDeps || []),
+      ]);
+      for (const name of pyNames) {
+        const t = unitByPythonDist.get(name);
+        if (t && t.component && t.component.ref !== unit.component.ref) deps.add(t.component.ref);
+      }
+      for (const p of unit.pythonPathDeps || []) {
+        const t = discovery.eligible.find((u) => u.root === p.dir);
+        if (t && t.component && t.component.ref !== unit.component.ref) deps.add(t.component.ref);
+      }
+    }
     dependencyMap.set(unit.component.ref, deps);
   }
   ctx.dependencyMap = dependencyMap;
@@ -702,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 };
 
@@ -942,9 +1038,13 @@ const GO_IMPORT_RE = /["`]([a-z0-9]+\.[a-z0-9.-]+\/[a-z0-9./_-]+|[a-z0-9]+\.[a-z
 function buildImportIndex(repo, discovery) {
   const byUnit = new Map();
   const goPathsByUnit = new Map();
+  const rustIdentsByUnit = new Map();
+  const pythonImportsByUnit = new Map();
   for (const unit of discovery.eligible) {
     const map = new Map();
     const goPaths = new Set();
+    const rustIdents = new Map();
+    const pyImports = new Map();
     for (const f of sourceFiles(repo, unit.root, { test: false })) {
       const specifiers = importSpecifiers(repo.readText(f));
       for (const s of specifiers) {
@@ -958,11 +1058,26 @@ function buildImportIndex(repo, discovery) {
         // importing it, with no require line at all.
         for (const m of text.matchAll(GO_IMPORT_RE) ) goPaths.add(m[1]);
       }
+      if (unit.cargoPackage && f.endsWith(".rs")) {
+        const text = repo.readText(f);
+        for (const ident of rustIdentsInSource(text)) {
+          if (!rustIdents.has(ident)) rustIdents.set(ident, new Set());
+          rustIdents.get(ident).add(f);
+        }
+      }
+      if (unit.pythonMarker && f.endsWith(".py")) {
+        for (const name of pythonImportNames(repo.readText(f))) {
+          if (!pyImports.has(name)) pyImports.set(name, new Set());
+          pyImports.get(name).add(f);
+        }
+      }
     }
     byUnit.set(unit, map);
     goPathsByUnit.set(unit, goPaths);
+    rustIdentsByUnit.set(unit, rustIdents);
+    pythonImportsByUnit.set(unit, pyImports);
   }
-  return { byUnit, goPathsByUnit };
+  return { byUnit, goPathsByUnit, rustIdentsByUnit, pythonImportsByUnit };
 }
 
 function mergeDerived(target, extra) {
@@ -995,7 +1110,7 @@ function validateOidcProviders({ repo, sources, discovery }) {
     const roots = unit ? [unit.root] : [dirOf(provider.file)];
     let found = false;
     for (const root of roots) {
-      for (const f of repo.walk(root)) {
+      for (const f of repo.walkUnit(root)) {
         if (!/\.(ts|tsx|js|mjs|jsx|py|go|rb|java|kt|rs)$/.test(f)) continue;
         if (/(^|\/)(test|tests|__tests__)\//.test(f) || /\.(test|spec)\./.test(f)) continue;
         if (repo.readText(f).includes(dp)) { found = true; break; }

package/core/dependents.mjs

@@ -0,0 +1,42 @@
+// Change routing follows dependency edges in reverse. Normalize inverse edges
+// here so query and impact agree even when the graph includes both spellings.
+export function dependentScope(graph, seeds) {
+  const reverse = new Map();
+  for (const r of graph.relations) {
+    let dependency, dependent;
+    if (r.type === "buildDependsOn" || r.type === "testDependsOn") {
+      dependency = r.targetRef;
+      dependent = r.sourceRef;
+    } else if (r.type === "buildDependencyOf" || r.type === "testDependencyOf") {
+      dependency = r.sourceRef;
+      dependent = r.targetRef;
+    } else continue;
+    if (!reverse.has(dependency)) reverse.set(dependency, []);
+    reverse.get(dependency).push({ ref: dependent, unitOnly: r.type.startsWith("test") });
+  }
+
+  // false means all tiers; true means only unit checks. An all-build route
+  // upgrades a prior test-only route, including its downstream dependents.
+  const scope = new Map(seeds.map((ref) => [ref, false]));
+  const queue = [...scope.keys()];
+  for (let i = 0; i < queue.length; i++) {
+    const current = queue[i];
+    for (const edge of reverse.get(current) || []) {
+      const unitOnly = scope.get(current) || edge.unitOnly;
+      if (!scope.has(edge.ref) || (scope.get(edge.ref) && !unitOnly)) {
+        scope.set(edge.ref, unitOnly);
+        queue.push(edge.ref);
+      }
+    }
+  }
+  return scope;
+}
+
+export function verificationForChange(graph, seeds, priorityRefs = seeds) {
+  const own = new Set(priorityRefs);
+  const scope = dependentScope(graph, seeds);
+  const rank = (v) => v.componentRefs.some((ref) => own.has(ref)) ? 0 : 1;
+  return graph.verification
+    .filter((v) => v.componentRefs.some((ref) => scope.has(ref) && (!scope.get(ref) || v.tier === "unit")))
+    .sort((a, b) => rank(a) - rank(b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

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,