agent-doc-system 1.0.0 → 1.2.0

package/core/compile.mjs

@@ -17,8 +17,13 @@ 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 {
   COMPILER_NAME, COMPILER_VERSION, GRAPH_SCHEMA_VERSION,
   assembleGraph, serializeGraph, finalizeSerialization, subjectResolver,
@@ -115,16 +120,18 @@ export function compile(root, opts = {}) {
     evidence: o.evidence.map((ev) => ({ path: ev.path, sha256: ev.sha256 })),
   });
 
+  // ── normative requirements ───────────────────────────────────────────────
+  // Checked before discovery so a stale citation is reported alongside every
+  // other authored-input error rather than hiding behind a coverage failure.
+  const normative = loadNormative(repo, cfg, sources, overrides.overrides);
+  res.errors.push(...normative.errors);
+  res.normative = { sections: normative.sections, uncovered: normative.uncovered, requirements: normative.requirements };
+
   res.errors.push(...checkContractCoverage({ repo, cfg, sources }));
 
   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 {
@@ -137,16 +144,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 });
@@ -165,6 +178,9 @@ export function compile(root, opts = {}) {
     repo, cfg, refs, bundle, prov, diagnostics, facts,
     sources: { ...sources, journeys: journeys.journeys }, discovery, journeys: journeys.journeys, journeysPath: journeys.path,
     observations, overrides: overrides.overrides,
+    // Declared normative requirements, so an adapter named in `satisfiedBy`
+    // can derive the implementation side on the same key.
+    requirements: normative.requirements,
     edges, events, externals, capabilities, verification,
     errors: [],
     unitByComponent: new Map(),
@@ -272,6 +288,17 @@ 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";
     if (repo.exists(pkgPath)) {
@@ -288,15 +315,68 @@ export function compile(root, opts = {}) {
       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.
@@ -304,6 +384,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();
@@ -325,6 +406,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;
@@ -436,6 +543,21 @@ export function compile(root, opts = {}) {
     }
   }
 
+  // A requirement is an AUTHORED claim that the implementation must make true.
+  // It is a fact like any other so the authority engine compares it with the
+  // implementation evidence on the same key — and it carries its citation, so
+  // every report can say which section of which document it came from.
+  for (const r of normative.requirements) {
+    facts.add({
+      subject: r.subject, key: r.key, value: r.value, evidenceClass: "AUTHORED", confidence: "declared",
+      provRecs: [
+        prov.add("declared", r.file, "requirement-extractor", ["ass:pending"]),
+        prov.add("declared", r.source.path, "requirement-extractor", ["ass:pending"]),
+      ],
+      semantics: NORMATIVE_SEMANTICS_PREFIX + r.source.path + "#" + r.source.section,
+    });
+  }
+
   // ── reviewed overrides → relations and facts ─────────────────────────────
   const overrideEdges = [];
   for (const o of overrides.overrides) {
@@ -503,6 +625,13 @@ export function compile(root, opts = {}) {
         evidenceClass: "REVIEWED_OVERRIDE", confidence: "reviewed", provRecs: provs, semantics: o.reason,
         review: reviewed(o),
       });
+    } else if (o.fact === "requirement-satisfaction") {
+      facts.add({
+        subject: o.subject, key: o.key, value: o.value,
+        evidenceClass: "REVIEWED_OVERRIDE", confidence: "reviewed", provRecs: provs,
+        semantics: o.reason,
+        review: reviewed(o),
+      });
     } else if (o.fact === "component-placement") {
       const key = o.system ? "placement.system" : "placement.domain";
       facts.add({
@@ -557,6 +686,7 @@ export function compile(root, opts = {}) {
 
   const { conflicts: rawConflicts } = resolveAssertions(facts.facts, authority);
   pushConflictDiagnostics(rawConflicts, diagnostics, facts);
+  pushNormativeDiagnostics(normative, facts, adapters, diagnostics);
 
   // ── relations ────────────────────────────────────────────────────────────
   const rel = buildRelations(ctx);
@@ -753,7 +883,13 @@ function pushConflictDiagnostics(rawConflicts, diagnostics, facts) {
       .filter(Boolean)
       .map((f) => f.evidenceClass + "=" + JSON.stringify(f.value))
       .sort();
-    const detail = c.subject + " " + c.key + ": " + values.join(" vs ");
+    let detail = c.subject + " " + c.key + ": " + values.join(" vs ");
+    // For a requirement, say where each side comes from: the cited section and
+    // what the extractor actually found. Two bare values send a reader hunting.
+    if (isRequirementKey(c.key)) {
+      const why = c.assertionIds.map((id) => byId.get(id)).filter((f) => f && f.semantics).map((f) => f.semantics).sort();
+      if (why.length) detail += " (" + why.join("; ") + ")";
+    }
     if (c.kind === "ambiguity" && c.status === "unresolved") {
       diagnostics.push({
         severity: "warning",
@@ -775,7 +911,7 @@ function pushConflictDiagnostics(rawConflicts, diagnostics, facts) {
         message:
           "unresolved " + c.kind + " — " + detail + ". " +
           (c.election.rationale || "no authority rule governs this fact") +
-          ". Add an authority rule and, if deterministic discovery cannot settle it, a reviewed override.",
+          (isRequirementKey(c.key) ? "." : ". Add an authority rule and, if deterministic discovery cannot settle it, a reviewed override."),
       });
     } else {
       diagnostics.push({
@@ -794,6 +930,101 @@ function pushConflictDiagnostics(rawConflicts, diagnostics, facts) {
   }
 }
 
+// Normative documents, the requirements components declare against them, and
+// which sections nobody has accounted for. Every citation is re-verified
+// against the section's current digest: a requirement or an attestation
+// written against an older wording of the specification is a review that has
+// not happened yet.
+function loadNormative(repo, cfg, sources, overrides) {
+  const errors = [];
+  const out = { errors, sections: [], uncovered: [], requirements: [] };
+  let docs;
+  try {
+    docs = loadNormativeDocuments(repo, cfg);
+  } catch (e) {
+    if (!(e instanceof AgentDocError)) throw e;
+    errors.push(e);
+    return out;
+  }
+  for (const e of sources.entities) {
+    if (e.kind !== "Component") continue;
+    const seen = new Set();
+    for (const r of e.doc.spec.requirements || []) {
+      collect(() => {
+        if (seen.has(r.id) || seen.has(r.key)) {
+          throw new AgentDocError(CODES.CONFIG, "duplicate requirement id or key on " + e.ref + ": " + r.id + " / " + r.key, { path: e.file, ref: e.ref });
+        }
+        seen.add(r.id);
+        seen.add(r.key);
+        verifyCitation(docs, r.source, e.file, e.ref);
+        out.requirements.push({ ...r, subject: e.ref, file: e.file, satisfiedBy: r.satisfiedBy || [] });
+      }, errors);
+    }
+  }
+  // A satisfaction override must answer a requirement someone declared. One
+  // that answers nothing would be an implementation claim with no obligation
+  // behind it, which no report could ever surface.
+  const declared = new Set(out.requirements.map((r) => r.subject + "\u0000" + r.key));
+  for (const o of overrides) {
+    if (o.fact !== "requirement-satisfaction") continue;
+    if (!declared.has(o.subject + "\u0000" + o.key)) {
+      errors.push(new AgentDocError(
+        CODES.CONFIG,
+        "requirement-satisfaction override answers no declared requirement: " + o.subject + " " + o.key,
+        { path: CONFIG_PATH, ref: o.subject }
+      ));
+    }
+  }
+  const cov = normativeCoverage(docs, out.requirements, cfg.normativeCoverage || [], errors);
+  out.sections = cov.sections;
+  out.uncovered = cov.uncovered;
+  return out;
+}
+
+function pushNormativeDiagnostics(normative, facts, adapters, diagnostics) {
+  for (const s of normative.uncovered) {
+    const id = s.path + "#" + s.section;
+    diagnostics.push({
+      severity: "warning",
+      code: CODES.NORMATIVE_UNCOVERED,
+      subject: id,
+      paths: [s.path],
+      refs: [],
+      message:
+        "normative section " + id + " (sha256 " + s.sha256 + ") is routed but not reviewed: " +
+        "declare the requirement it places on a component (spec.requirements), or attest in normativeCoverage " +
+        "that it carries no implementation obligation.",
+    });
+  }
+  const enabled = new Set(adapters.map((a) => a.name));
+  for (const r of normative.requirements) {
+    const group = facts.facts.filter((f) => f.subject === r.subject && f.key === r.key && f.status !== "superseded");
+    if (group.some((f) => !isNormative(f) && f.confidence !== "candidate")) continue;
+    const candidate = group.find((f) => !isNormative(f));
+    const missing = r.satisfiedBy.filter((a) => !enabled.has(a));
+    const why = candidate
+      ? "only a heuristic candidate exists, which is never elected — " + (candidate.semantics || JSON.stringify(candidate.value))
+      : !r.satisfiedBy.length
+        ? "no adapter is named as able to derive it"
+        : missing.length
+          ? "the adapter able to derive it is not enabled or not available: " + missing.join(", ")
+          : !r.expects
+            ? "the requirement has no `expects`, so " + r.satisfiedBy.join(", ") + " has nothing to look for"
+            : "the enabled adapter (" + r.satisfiedBy.join(", ") + ") derived no evidence for it";
+    diagnostics.push({
+      severity: "warning",
+      code: CODES.REQUIREMENT_UNVERIFIED,
+      subject: r.subject + "#" + r.key,
+      paths: [r.source.path],
+      refs: [r.subject],
+      message:
+        "requirement " + r.key + " = " + r.value + " on " + r.subject + " (from " + r.source.path + "#" + r.source.section +
+        ") has no implementation evidence; " + why + ". Add a requirement-satisfaction reviewed override citing the " +
+        "implementation, or accept the gap with review.",
+    });
+  }
+}
+
 // A Go import is either host.tld/owner/repo/path or host.tld/owner/repo. The
 // second form is what a Go *workspace* member uses, and it has only two dots —
 // a pattern that requires three silently loses every workspace-only dependency.
@@ -805,9 +1036,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) {
@@ -821,11 +1056,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) {
@@ -858,7 +1108,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/descriptors.mjs

@@ -15,7 +15,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { AgentDocError, CODES, collect } from "./codes.mjs";
-import { assertRepoPath, expandGlob, sha256Hex } from "./fsx.mjs";
+import { assertGlob, assertRepoPath, expandGlob, sha256Hex } from "./fsx.mjs";
 import { parseYamlDocuments } from "./yaml.mjs";
 import { scanForSecrets } from "./secrets.mjs";
 import { formatErrors } from "./jsonschema.mjs";
@@ -160,10 +160,13 @@ export function loadConfig(repo, bundle) {
     cfg.output.graph, cfg.output.observations,
     ...(cfg.discovery.supplementalRoots || []),
     ...(cfg.discovery.contractRoots || []),
-    ...(cfg.docs ? Object.values(cfg.docs) : []),
+    ...(cfg.docs ? Object.entries(cfg.docs).filter(([k]) => k !== "normative").map(([, v]) => v) : []),
   ].filter(Boolean)) {
     assertRepoPath(p, CONFIG_PATH);
   }
+  // `docs.normative` holds globs, not paths: the only role that names a set of
+  // documents rather than one.
+  for (const g of (cfg.docs && cfg.docs.normative) || []) assertGlob(g, CONFIG_PATH);
   return cfg;
 }
 

package/core/discover.mjs

@@ -8,12 +8,22 @@ import path from "node:path";
 import { AgentDocError, CODES } from "./codes.mjs";
 import { expandGlob, globToRegExp, assertGlob } from "../core/fsx.mjs";
 
-// Directories that are never units. Overridable, because "infra" or "tools"
-// may be a legitimate unit in another project.
+// Roots excluded from inference and scaffolding. Authored descriptors strictly
+// below them can still claim units; descriptors at these exact roots cannot.
 export const DEFAULT_NOT_UNIT_ROOTS = ["agentdoc", "docs", "scripts", "node_modules", ".github"];
 
+function notUnitRoots(cfg) {
+  return cfg?.discovery.notUnitRoots || DEFAULT_NOT_UNIT_ROOTS;
+}
+
+// Inference excludes the whole subtree, not similarly named siblings. CREATE
+// mode shares this policy even for units with an existing authored descriptor.
+export function isNotUnitRoot(root, cfg) {
+  return notUnitRoots(cfg)
+    .some((excluded) => root === excluded || root.startsWith(excluded + "/"));
+}
+
 export function discoverUnits(repo, cfg, adapters) {
-  const notUnit = new Set(cfg.discovery.notUnitRoots || DEFAULT_NOT_UNIT_ROOTS);
   const extraDeployable = new Set();
   const extraImportable = new Set();
   const units = new Map();
@@ -35,13 +45,17 @@ export function discoverUnits(repo, cfg, adapters) {
     assertGlob(g, "agentdoc config");
     for (const f of expandGlob(repo, g)) {
       const dir = path.posix.dirname(f);
-      if (!notUnit.has(dir) && repo.isDir(dir)) {
+      if (repo.isDir(dir)) {
         candidates.add(dir);
         descriptorRoots.add(dir);
       }
     }
   }
-  for (const r of cfg.discovery.supplementalRoots || []) candidates.add(r);
+  for (const r of cfg.discovery.supplementalRoots || []) {
+    candidates.add(r);
+    // The descriptor loader also reads these fixed paths outside the globs.
+    if (repo.exists(r + "/" + cfg.discovery.componentDescriptorName)) descriptorRoots.add(r);
+  }
 
   // Adapters may contribute roots the descriptor globs cannot know about: a
   // Go workspace member, a workspace file member with no descriptor yet. The
@@ -59,7 +73,10 @@ export function discoverUnits(repo, cfg, adapters) {
   }
 
   for (const root of [...candidates].sort()) {
-    if (notUnit.has(root)) continue;
+    // Preserve explicit human claims below an exclusion, while keeping inferred
+    // roots out of the subtree and refusing descriptors at the exact root.
+    if (notUnitRoots(cfg).includes(root)) continue;
+    if (isNotUnitRoot(root, cfg) && !descriptorRoots.has(root)) continue;
     if (!repo.isDir(root)) continue;
     const u = get(root);
     u.explicit = (cfg.discovery.supplementalRoots || []).includes(root) || descriptorRoots.has(root);
@@ -72,13 +89,38 @@ export function discoverUnits(repo, cfg, adapters) {
         const shape = markerShape(marker);
         if (shape === "deployable" || shape === "both") u.deployable = true;
         if (shape === "importable" || shape === "both") u.importable = true;
+        // A manifest with no artifact shape is still a unit. deployable and
+        // importable stay false, so scaffold does not invent a service or a
+        // library. A descriptor is not required before the unit is recognised.
+        if (shape === "present") u.present = true;
       }
     }
   }
 
   const list = [...units.values()].sort((a, b) => (a.root < b.root ? -1 : 1));
-  const eligible = list.filter((u) => u.deployable || u.importable || u.explicit);
-  return { units: list, eligible };
+  const eligible = list.filter((u) => u.deployable || u.importable || u.explicit || u.present);
+  // Only eligible units create ownership boundaries. Record immediate children
+  // once; pruning one of them also prunes every deeper descendant. Normalise
+  // the repository root so descriptor roots (".") and workspace roots agree.
+  const nestedRoots = new Map(eligible.map((u) => [unitRoot(u.root), new Set()]));
+  for (const root of nestedRoots.keys()) {
+    if (!root) continue;
+    let parent = unitRoot(path.posix.dirname(root));
+    while (true) {
+      if (nestedRoots.has(parent)) {
+        nestedRoots.get(parent).add(root);
+        break;
+      }
+      if (!parent) break;
+      parent = unitRoot(path.posix.dirname(parent));
+    }
+  }
+  return { units: list, eligible, nestedRoots };
+}
+
+function unitRoot(root) {
+  const normalized = path.posix.normalize(root || ".");
+  return normalized === "." ? "" : normalized;
 }
 
 function markerShape(marker) {
@@ -93,7 +135,7 @@ export function descriptorDir(file) {
 }
 
 // Exactly one descriptor per eligible unit, and no descriptor outside one.
-export function matchComponents(eligible, componentEntities) {
+export function matchComponents(eligible, componentEntities, cfg) {
   const errors = [];
   const byDir = new Map();
   for (const e of componentEntities) {
@@ -124,6 +166,15 @@ export function matchComponents(eligible, componentEntities) {
   for (const e of componentEntities) {
     const dir = descriptorDir(e.file);
     if (unitRoots.has(dir)) continue;
+    if (notUnitRoots(cfg).includes(dir)) {
+      errors.push(new AgentDocError(
+        CODES.COMPONENT_UNCORROBORATED,
+        "component descriptor at '" + dir + "' is in discovery.notUnitRoots (or a default not-unit root); " +
+          "remove it from notUnitRoots or move the descriptor",
+        { path: e.file, ref: e.ref }
+      ));
+      continue;
+    }
     // A descriptor is a human claim that a component exists. When no adapter
     // can corroborate a deployable or importable artifact in that source root,
     // the claim is unsupported. This is reported rather than ignored: it is

package/core/fsx.mjs

@@ -59,6 +59,7 @@ export class Repo {
     this.probes = new Map();
     this.walks = new Map();
     this.listings = new Map();
+    this.nestedUnitRoots = new Map();
     this.generatedDirs = new Set(opts.generatedDirs || DEFAULT_GENERATED_DIRS);
     this.noGit = Boolean(opts.noGit);
   }
@@ -140,6 +141,22 @@ export class Repo {
     this.walks.set(relDir || ".", out);
     return out;
   }
+  // Per-unit scans use the discovery result, never filesystem heuristics.
+  // Keep walk() repository-wide for discovery, contracts and authored inputs.
+  ownsUnitPath(unitRoot, rel) {
+    const normalize = (p) => path.posix.normalize(p || ".").replace(/^\.$/, "");
+    const root = normalize(unitRoot);
+    const target = normalize(rel);
+    if (root && target !== root && !target.startsWith(root + "/")) return false;
+    for (const child of this.nestedUnitRoots.get(root) || []) {
+      if (target === child || target.startsWith(child + "/")) return false;
+    }
+    return true;
+  }
+  walkUnit(unitRoot, relDir = unitRoot, { exclude = () => false } = {}) {
+    if (!this.ownsUnitPath(unitRoot, relDir)) return [];
+    return this.walk(relDir, { exclude: (rel, ent) => !this.ownsUnitPath(unitRoot, rel) || exclude(rel, ent) });
+  }
   // Files under a path or a path *prefix*. A contract is often named by a module
   // prefix rather than a single file (`events.go`, `events/*.go`), and
   // requiring an exact directory would reject a perfectly good contract.
@@ -175,16 +192,17 @@ export class Repo {
     return names;
   }
 
-  git(args) {
+  git(args, { trim = true } = {}) {
     // stderr must be piped, not inherited: every caller treats a non-zero exit
     // as a signal to degrade (unborn HEAD, detached worktree, missing remote),
     // and execFileSync would otherwise print git's own "fatal:" line to the
     // user's terminal while the command reports success.
-    return execFileSync("git", args, {
+    const out = execFileSync("git", args, {
       cwd: this.root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
-    }).trim();
+    });
+    return trim ? out.trim() : out;
   }
   hasGit() {
     if (this.noGit) return false;
@@ -239,7 +257,12 @@ export class Repo {
     if (this.noGit || !this.hasGit()) return [];
     let raw;
     try {
-      raw = this.git(["status", "--porcelain", "-z", "--untracked-files=all"]);
+      // Untrimmed: a porcelain record is `XY <path>` with fixed columns, and an
+      // unstaged change has X = " ". Trimming would eat that space from the
+      // first record, so `.slice(3)` would drop the path's first character —
+      // ` M .agentdoc/graph.json` became `agentdoc/graph.json`, slipped past
+      // the output exclusion and counted as a dirty input (issue #11).
+      raw = this.git(["status", "--porcelain", "-z", "--untracked-files=all"], { trim: false });
     } catch {
       return [];
     }