agent-doc-system 1.1.0 → 1.2.0

package/core/impact.mjs

@@ -3,8 +3,8 @@
 // When an agent edits a file, the question is not "what does this file do" but
 // "what must I keep consistent, and which gate proves it". This answers that
 // from the graph alone, so the answer is available before any exploration.
-import path from "node:path";
 import { ContextIndex } from "./query.mjs";
+import { dependentScope, verificationForChange } from "./dependents.mjs";
 
 // The affected-file classification is derived from the compiled graph, not from
 // a hand-written list of technology filenames. A list would go stale for every
@@ -26,7 +26,7 @@ function classify(graph, p, idx) {
     for (const x of d.runbooks || []) if (x === p) return "documentation";
   }
   if (/\.(md|mdx|adoc|rst|txt)$/.test(p)) return "documentation";
-  if (/(^|\/)migrations?\//.test(p)) return "resource";
+  if (/(^|\/)(migrations?|alembic\/versions)\//.test(p)) return "resource";
   // A Resource named directly — by ref, or by the descriptor file that declares
   // it — is a resource change. Without this, `impact resource:default/x` reported
   // nothing at all, and a change to a dataset's owner was invisible. The loop
@@ -44,7 +44,7 @@ export function impact(graph, changedPaths) {
   const idx = new ContextIndex(graph);
   const affectedComponents = new Map(); // ref -> Set(reason)
   const add = (ref, reason) => {
-    if (!idx.byRef.has(ref)) return;
+    if (idx.byRef.get(ref)?.kind !== "Component") return;
     if (!affectedComponents.has(ref)) affectedComponents.set(ref, new Set());
     affectedComponents.get(ref).add(reason);
   };
@@ -56,6 +56,7 @@ export function impact(graph, changedPaths) {
   const dependencyPaths = new Set();
   const catalogPaths = new Set();
   const unmatched = [];
+  const matchedVerification = new Set();
 
   for (const raw of changedPaths) {
     const p = raw.replace(/^\.\//, "");
@@ -68,12 +69,36 @@ export function impact(graph, changedPaths) {
     const kind = classify(graph, p, idx);
     if (kind === "contract") contracts.add(p);
     if (kind === "documentation") docs.add(p);
-    if (kind === "resource") resources.add(p);
+    if (kind === "resource") {
+      resources.add(entity?.kind === "Resource" ? entity.ref : p);
+      // Migration authority is not ownership. Only follow an existing binding
+      // from the component containing this migration to a logical database.
+      if (entity?.kind === "Component") {
+        for (const rel of graph.relations) {
+          const bound = rel.type === "usesResource" && rel.sourceRef === entity.ref ? rel.targetRef
+            : rel.type === "resourceUsedBy" && rel.targetRef === entity.ref ? rel.sourceRef : null;
+          if (idx.byRef.get(bound)?.entity.spec.type === "logical-database") resources.add(bound);
+        }
+      }
+    }
     if (kind === "verification") verificationPaths.add(p);
     if (kind === "input") dependencyPaths.add(p);
     if (p.startsWith("agentdoc/")) catalogPaths.add(p);
   }
 
+  // A check's configuration is evidence of the components it covers, even
+  // when the file lives outside every component root (for example CI). Add
+  // these before taking the seeds so their dependents' checks follow too.
+  for (const v of graph.verification) {
+    for (const p of verificationPaths) {
+      if (!v.configPaths?.includes(p)) continue;
+      matchedVerification.add(p);
+      for (const ref of v.componentRefs) add(ref, "verification configuration " + p + " changed");
+    }
+  }
+  const gates = graph.gates.filter((g) => g.configPaths?.some((p) => verificationPaths.has(p)));
+  for (const g of gates) for (const p of g.configPaths) if (verificationPaths.has(p)) matchedVerification.add(p);
+
   // A contract change reaches its provider and every consumer.
   for (const c of contracts) {
     for (const api of graph.entities.filter((e) => e.kind === "API")) {
@@ -84,36 +109,6 @@ export function impact(graph, changedPaths) {
     }
   }
 
-  // Changing a component reaches the components that depend on it, and the
-  // components it schedules or is scheduled by. Two hops: a direct dependent
-  // and a dependent-of-a-dependent is the practical blast radius; beyond that
-  // the graph stops being a routing aid and becomes a dump.
-  for (const start of [...affectedComponents.keys()]) {
-    for (let hop = 0; hop < 2; hop++) {
-      for (const r of graph.relations) {
-        if (r.type === "buildDependencyOf" || r.type === "testDependencyOf" || r.type === "buildDependsOn" || r.type === "testDependsOn") {
-          if (r.targetRef === start) add(r.sourceRef, "depends on a changed component");
-          if (r.sourceRef === start) add(r.targetRef, "a dependent of a changed component");
-        }
-        if (r.type === "schedules" || r.type === "scheduledBy" || r.type === "runtimeCalls" || r.type === "runtimeCalledBy") {
-          if (r.sourceRef === start) add(r.targetRef, "connected to a changed component by " + r.type);
-          if (r.targetRef === start) add(r.sourceRef, "connected to a changed component by " + r.type);
-        }
-      }
-    }
-  }
-
-  // A dependency manifest change reaches both directions of the edge.
-  for (const d of dependencyPaths) {
-    for (const r of graph.relations) {
-      if (r.type !== "buildDependsOn" && r.type !== "testDependsOn") continue;
-      if (r.attributes?.package === path.basename(d)) {
-        add(r.sourceRef, "dependency manifest " + d + " changed");
-        add(r.targetRef, "depended on by a component whose manifest changed");
-      }
-    }
-  }
-
   // A documentation change reaches the component that owns it.
   for (const d of docs) {
     for (const e of graph.entities) {
@@ -125,43 +120,59 @@ export function impact(graph, changedPaths) {
     }
   }
 
-  // A resource change reaches every component bound to it. Matched on the full
-  // ref or on a path that lies under the Resource's own source root, so a
-  // Resource ref and its migration directory both reach the same components.
+  // A resource change reaches every component bound to that exact Resource.
+  // Never match a name as a substring of a migration path.
   for (const r of resources) {
-    const refMatch = r.match(/^[a-z]+:[^/]+\/(.+)$/);
-    const refName = refMatch ? refMatch[1] : null;
     for (const rel of graph.relations) {
       if (rel.type !== "usesResource" && rel.type !== "resourceUsedBy") continue;
       const bound = rel.type === "usesResource" ? rel.targetRef : rel.sourceRef;
       const user = rel.type === "usesResource" ? rel.sourceRef : rel.targetRef;
-      const name = bound.split("/").slice(1).join("/");
-      if ((refName && name === refName) || r.includes(name)) {
+      if (r === bound) {
         add(user, "resource change touches " + bound);
       }
     }
   }
 
+  // Preserve the existing direct runtime/schedule context, then follow only
+  // reverse build/test edges. Dependencies remain context in query's explicitly
+  // typed relations; they are never affected components just for being inputs.
+  const directlyAffected = [...affectedComponents.keys()];
+  for (const start of directlyAffected) {
+    for (const r of graph.relations) {
+      if (r.type === "schedules" || r.type === "scheduledBy" || r.type === "runtimeCalls" || r.type === "runtimeCalledBy") {
+        if (r.sourceRef === start) add(r.targetRef, "connected to a changed component by " + r.type);
+        if (r.targetRef === start) add(r.sourceRef, "connected to a changed component by " + r.type);
+      }
+    }
+  }
+  const seeds = [...affectedComponents.keys()];
+  for (const ref of dependentScope(graph, seeds).keys()) {
+    if (!affectedComponents.has(ref)) add(ref, "depends on a changed component");
+  }
+
   const refs = [...affectedComponents.keys()].sort();
-  const verification = graph.verification.filter((v) => v.componentRefs.some((r) => refs.includes(r)));
+  const verification = verificationForChange(graph, seeds, directlyAffected);
   const conflicts = graph.conflicts.filter((c) => refs.includes(c.subject));
   const journeys = graph.journeys.filter((j) => j.components.some((r) => refs.includes(r)));
 
   return {
     changedFiles: changedPaths.slice().sort(),
-    unmatchedFiles: unmatched.sort(),
+    unmatchedFiles: unmatched.filter((p) => !matchedVerification.has(p)).sort(),
     affectedComponents: refs.map((ref) => ({ ref, reasons: [...affectedComponents.get(ref)].sort() })),
     affectedContracts: [...contracts].sort(),
     affectedDocs: [...docs].sort(),
     affectedResources: [...resources].sort(),
     affectedInputs: [...dependencyPaths].sort(),
     affectedVerification: [...verificationPaths].sort(),
+    affectedGates: gates.map((v) => ({ id: v.id, tier: v.tier, command: v.command })),
     affectedCatalog: [...catalogPaths].sort(),
     catalogSourceChanged: catalogPaths.size > 0,
     // Any file the compiler read is a graph input: changing it invalidates the
     // committed graph even when no descriptor changed.
     graphWillBeStale: graphAffected(graph, changedPaths),
-    recommendedVerification: verification.map((v) => ({ id: v.id, tier: v.tier, command: v.command })).slice(0, 25),
+    recommendedVerification: [...verification, ...gates].map((v) => ({ id: v.id, tier: v.tier, command: v.command })).slice(0, 25),
+    recommendedVerificationTotal: verification.length + gates.length,
+    recommendedVerificationTruncated: verification.length + gates.length > 25,
     openConflicts: conflicts.map((c) => ({ id: c.id, subject: c.subject, key: c.key, status: c.status, kind: c.kind })),
     relatedJourneys: journeys.map((j) => ({ id: j.id, description: j.description })),
   };

package/core/query.mjs

@@ -9,6 +9,7 @@
 // than silently dropped, so an agent can see that it is seeing a slice.
 import { AgentDocError, CODES } from "./codes.mjs";
 import { assertNoSecretsInText } from "./secrets.mjs";
+import { verificationForChange } from "./dependents.mjs";
 
 const DEFAULT_BUDGET = {
   relations: 40,
@@ -151,7 +152,7 @@ export function queryContext(graph, needle, opts = {}) {
   const verificationScope = entity.kind === "API"
     ? [ref, ...apiConsumers, ...(apiProvider ? [apiProvider] : [])]
     : [ref];
-  const verification = g.verification.filter((e) => e.componentRefs.some((r) => verificationScope.includes(r)));
+  const verification = verificationForChange(g, verificationScope);
   const journeys = g.journeys.filter((j) => j.components.includes(ref));
   const contracts = g.contracts.filter((c) => c.apiRef && apiRefs.has(c.apiRef));
   const conflicts = g.conflicts.filter((c) => c.subject === ref);
@@ -231,9 +232,11 @@ export function queryContext(graph, needle, opts = {}) {
     ),
     capabilities: take(capabilities.map((c) => ({ name: c.name, evidenceClass: c.evidenceClass })), budget.capabilities),
     constraints: {
-      docs: (entity.derived && entity.derived.docs) || [],
-      constraints: (entity.derived && entity.derived.constraints) || [],
-      runbooks: (entity.derived && entity.derived.runbooks) || [],
+      // Components derive these lists (including conventional files); central
+      // entities such as Resources and Systems carry them only in their spec.
+      docs: entity.derived?.docs || entity.entity.spec?.context?.docs || [],
+      constraints: entity.derived?.constraints || entity.entity.spec?.context?.constraints || [],
+      runbooks: entity.derived?.runbooks || entity.entity.spec?.context?.runbooks || [],
     },
     verification: take(
       verification.map((v) => ({ id: v.id, tier: v.tier, command: v.command, configPaths: v.configPaths })),
@@ -329,7 +332,7 @@ function contractRef(graph, apiRef) {
 }
 
 // Compact markdown rendering for a prompt or a human. Same routing, less tokens.
-export function renderContext(ctx) {
+export function renderContext(ctx, opts = {}) {
   const L = [];
   const e = ctx.entity;
   L.push("# " + e.ref + " (" + e.kind + ")");
@@ -345,9 +348,16 @@ export function renderContext(ctx) {
   if (ctx.events.items.length) L.push("- events: " + ctx.events.items.map((x) => x.pattern + " [" + x.resolution + "]").join(", "));
   if (ctx.externalDependencies.items.length) L.push("- external: " + ctx.externalDependencies.items.map((x) => x.name + " (" + x.role + ")").join(", "));
   if (ctx.capabilities.items.length) L.push("- capabilities: " + ctx.capabilities.items.map((x) => x.name).join(", "));
-  if (ctx.constraints.constraints.length) L.push("- CONSTRAINTS: " + ctx.constraints.constraints.join(", "));
-  if (ctx.constraints.docs.length) L.push("- docs: " + ctx.constraints.docs.join(", "));
-  if (ctx.constraints.runbooks.length) L.push("- runbooks: " + ctx.constraints.runbooks.join(", "));
+  for (const key of ["constraints", "docs", "runbooks"]) {
+    const paths = ctx.constraints[key];
+    if (!paths.length) continue;
+    // Constraints are critical routing context; cap them only on request.
+    const limit = opts.budget?.[key] ?? (key === "constraints" ? paths.length : 12);
+    const shown = paths.slice(0, limit);
+    const label = key === "constraints" ? "CONSTRAINTS" : key;
+    L.push("- " + label + ": " + shown.join(", ") +
+      (shown.length < paths.length ? " [truncated: " + shown.length + " of " + paths.length + "]" : ""));
+  }
   if (ctx.verification.items.length) {
     L.push("- verify:");
     for (const v of ctx.verification.items) L.push("  - [" + v.tier + "] " + v.command);

package/core/scaffold.mjs

@@ -14,7 +14,12 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { AgentDocError, CODES } from "./codes.mjs";
 import { Repo } from "./fsx.mjs";
+import { discoverUnits, isNotUnitRoot } from "./discover.mjs";
 import { classifyContractFile } from "./contracts.mjs";
+import { parse as parseToml } from "./toml.mjs";
+import { cargoUnitShape, isExcludedWorkspaceMember, isVirtualWorkspaceManifest } from "../adapters/rust.mjs";
+import { readPythonUnit } from "../adapters/python.mjs";
+import { loadAdapters } from "../adapters/index.mjs";
 
 const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "templates");
 
@@ -56,7 +61,7 @@ export function installTemplates(repo, cfg, { write, root, force = false, eligib
   };
 
   // ── configuration ───────────────────────────────────────────────────────
-  const config = buildConfig(scanLayout(r));
+  const config = buildConfig(scanLayout(r, cfg));
   put("agentdoc/agentdoc.config.yaml", config);
   put("agentdoc/journeys.yaml", "schemaVersion: agentdoc.dev/journeys/v1\njourneys: []\n");
   for (const f of ["domains.yaml", "systems.yaml", "apis.yaml", "resources.yaml"]) {
@@ -87,17 +92,17 @@ export function installTemplates(repo, cfg, { write, root, force = false, eligib
 }
 
 // Layout inference for CREATE mode: which directories look like unit roots.
-// Uses only file-presence heuristics that any repository can answer.
-function scanLayout(repo) {
+// Combines shallow marker heuristics with the compiler's adapter discovery.
+function scanLayout(repo, cfg) {
   const candidates = new Map();
   const note = (root, kind) => {
     if (!candidates.has(root)) candidates.set(root, { root, kinds: new Set(), evidence: [] });
     candidates.get(root).kinds.add(kind);
     candidates.get(root).evidence.push(kind);
   };
-  const skip = new Set(["node_modules", ".git", "dist", "build", "vendor", "target", "agentdoc", "docs", "scripts", ".github", "test", "tests", "examples", "example"]);
+  const skip = new Set(["node_modules", ".git", "dist", "build", "vendor", "target", "test", "tests", "examples", "example"]);
   const walk = (dir, depth) => {
-    if (depth > 3) return;
+    if (depth > 3 || isNotUnitRoot(dir, cfg)) return;
     let entries;
     try { entries = fs.readdirSync(path.join(repo.root, dir), { withFileTypes: true }); } catch { return; }
     for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
@@ -114,15 +119,62 @@ function scanLayout(repo) {
       const parent = () => rel.slice(0, -("/" + e.name).length);
       if (e.name === "package.json") note(parent(), "node");
       if (e.name === "go.mod") note(parent(), "go");
+      if (e.name === "Cargo.toml" && cargoUnitShape(repo, parent()) && !isExcludedWorkspaceMember(repo, parent())) note(parent(), "rust");
+      if (e.name === "pyproject.toml" || e.name === "setup.py" || e.name === "setup.cfg") note(parent(), "python");
+      if (/^requirements.*\.txt$/.test(e.name)) note(parent(), "python");
       if (e.name === "Dockerfile") note(parent(), "docker");
       if (/^wrangler\.(toml|json|jsonc)$/.test(e.name)) note(parent(), "platform");
       if (e.name === "go.mod") note(rel.slice(0, -"/go.mod".length), "go");
     }
   };
   walk("", 0);
+  // Directory-name/depth heuristics must not hide units declared by adapters
+  // (for example a uv or Cargo member under examples/). During init there is
+  // no config yet: probe supported marker adapters so those members can also
+  // select their adapter in the generated configuration.
+  const discoveryCfg = cfg || { discovery: { componentDescriptors: [] } };
+  const adapters = loadAdapters(cfg ? cfg.adapters : Object.values(ADAPTER_FOR_MARKER));
+  for (const unit of discoverUnits(repo, discoveryCfg, adapters).eligible) {
+    if (!unit.root || unit.root === "." || isNotUnitRoot(unit.root, cfg)) continue;
+    for (const [kind, adapter] of Object.entries(ADAPTER_FOR_MARKER)) {
+      if (unit.markers.some((marker) => marker.adapter === adapter)) note(unit.root, kind);
+    }
+  }
+  for (const u of [...candidates.values()]) {
+    // Layout-only candidates need the same artifact evidence as units already
+    // discovered by the compiler. A technology name alone proves no shape.
+    u.deployable = false;
+    u.importable = false;
+    for (const adapter of loadAdapters([...u.kinds].map((k) => ADAPTER_FOR_MARKER[k]))) {
+      const marker = adapter.detect({ repo, cfg }, u.root || ".");
+      if (!marker) continue;
+      const shape = marker.shape || "both";
+      u.deployable ||= shape === "deployable" || shape === "both";
+      u.importable ||= shape === "importable" || shape === "both";
+    }
+    if (!u.kinds.has("python")) continue;
+    const info = readPythonUnit(repo, u.root);
+    // A uv workspace root with no distribution is not a unit. Scaffolding it
+    // would invent a component for the virtual manifest.
+    if (!info.dist && !info.deployable && !info.importable && !info.error && virtualUvWorkspace(repo, u.root)) {
+      candidates.delete(u.root);
+    }
+  }
   return [...candidates.values()].sort((a, b) => (a.root < b.root ? -1 : 1));
 }
 
+function virtualUvWorkspace(repo, root) {
+  const file = !root || root === "." ? "pyproject.toml" : root + "/pyproject.toml";
+  if (!repo.exists(file)) return false;
+  try {
+    const doc = parseToml(repo.readText(file), file);
+    const ws = doc.tool && doc.tool.uv && doc.tool.uv.workspace;
+    return Boolean(ws && typeof ws === "object" && !Array.isArray(ws));
+  } catch {
+    return false;
+  }
+}
+
 function discoverUnitNames(repo, cfg, eligible = null) {
   const out = [];
   const nameFor = (root) => {
@@ -138,6 +190,18 @@ function discoverUnitNames(repo, cfg, eligible = null) {
       const m = /^module\s+(\S+)/m.exec(repo.readText(gomod));
       if (m) return kebab(m[1].split("/").pop());
     }
+    const cargo = root + "/Cargo.toml";
+    if (repo.exists(cargo)) {
+      try {
+        const doc = parseToml(repo.readText(cargo));
+        const n = doc && doc.package && typeof doc.package.name === "string" ? doc.package.name : "";
+        // `_` becomes `-u-` before kebab, so `foo_bar` does not collapse into
+        // the same component name as `foo-bar`.
+        if (n) return kebab(n.replace(/_/g, "-u-"));
+      } catch { /* a manifest that does not parse is not a name */ }
+    }
+    const python = readPythonUnit(repo, root);
+    if (python.dist) return kebab(python.dist);
     return kebab(path.basename(root));
   };
   const seen = new Set();
@@ -152,27 +216,32 @@ function discoverUnitNames(repo, cfg, eligible = null) {
       deployable: Boolean(u.deployable),
       importable: Boolean(u.importable),
     })),
-    ...scanLayout(repo).map((u) => ({ root: u.root, kinds: [...u.kinds].sort(), deployable: false, importable: false })),
+    ...scanLayout(repo, cfg).map((u) => ({
+      root: u.root,
+      kinds: [...u.kinds].sort(),
+      deployable: Boolean(u.deployable),
+      importable: Boolean(u.importable),
+    })),
   ];
-  for (const u of units) {
-    if (u.root === "." || !u.root || seenRoots.has(u.root)) continue;
+  for (const found of units) {
+    if (found.root === "." || !found.root || seenRoots.has(found.root)) continue;
+    if (isNotUnitRoot(found.root, cfg)) continue;
+    if (isVirtualWorkspaceManifest(repo, found.root)) continue;
+    const u = found;
     seenRoots.add(u.root);
     const name = nameFor(u.root);
     if (seen.has(name)) continue;
     seen.add(name);
     out.push({ ...u, name });
   }
-  void cfg;
   return out;
 }
 
 function componentDescriptor(u) {
-  const deployable = u.deployable || u.kinds.some((k) => k === "docker" || k === "platform");
-  const importable = u.importable || u.kinds.some((k) => k === "node" || k === "go");
   // "library" and "service" both have to be corroborated by artifact evidence
   // (AGENTDOC_ARTIFACT_TYPE); a unit the compiler only knows from configuration
   // shows neither, so claiming a concrete type would manufacture an error.
-  const type = deployable ? "service" : importable ? "library" : "other";
+  const type = u.deployable ? "service" : u.importable ? "library" : "other";
   return [
     "apiVersion: agentdoc.dev/v1",
     "kind: Component",
@@ -194,6 +263,8 @@ function componentDescriptor(u) {
 const ADAPTER_FOR_MARKER = {
   node: "node",
   go: "go",
+  rust: "rust",
+  python: "python",
   docker: "dockerfile",
   platform: "wrangler",
 };
@@ -206,13 +277,6 @@ function buildConfig(layout) {
     if (!groups.has(head)) groups.set(head, []);
     groups.get(head).push(r);
   }
-  // A manifest at the repository root yields an empty head; emitting
-  // "/agentdoc.yaml" would be an absolute glob, which the loader rejects.
-  const componentGlobs = [...groups.entries()]
-    .filter(([head]) => head.length > 0)
-    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
-    .map(([head, list]) => (list.length === 1 && list[0] === head ? head + "/agentdoc.yaml" : head + "/**/agentdoc.yaml"));
-  if (!componentGlobs.length) componentGlobs.push("*/**/agentdoc.yaml");
 
   const adapters = new Set(["generic"]);
   for (const l of layout) {
@@ -239,9 +303,10 @@ function buildConfig(layout) {
     "discovery:",
     "  componentDescriptorName: agentdoc.yaml",
     "  componentDescriptors:",
-    // Globs are quoted: an unquoted leading "*" is an alias in strict YAML,
-    // and a configuration the compiler cannot parse is worse than none.
-    ...componentGlobs.map((g) => "    - " + yamlStr(g)),
+    // Discover every scaffolded descriptor, including adapter roots outside
+    // the shallow layout and units added after init. Keep the leading glob
+    // quoted because an unquoted "*" is an alias in strict YAML.
+    '    - "*/**/agentdoc.yaml"',
     "  centralDescriptors:",
     "    - agentdoc/domains.yaml",
     "    - agentdoc/systems.yaml",

package/core/sourcescan.mjs

@@ -27,7 +27,7 @@ export function sourceFiles(repo, root, { test = false, extensions } = {}) {
   const DEFAULT_EXT = /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|go|py|rb|java|kt|rs|ex|exs|cs|php|swift|scala|sh)$/;
   const re = extensions || DEFAULT_EXT;
   const out = [];
-  for (const f of repo.walk(root)) {
+  for (const f of repo.walkUnit(root)) {
     if (!re.test(f)) continue;
     const isTest = TEST_PATH.test(f) || TEST_FILE.test(f) || /_test\.[a-z]+$/.test(f);
     if (isTest !== test) continue;
@@ -64,7 +64,16 @@ export function findMigrationDirs(repo, root, maxDepth = 5) {
       if (!e.isDirectory() || e.isSymbolicLink()) continue;
       if (["node_modules", ".git", "vendor", "target", "dist", "build", ".next", "__pycache__"].includes(e.name)) continue;
       const abs = path.join(dirAbs, e.name);
+      const rel = path.relative(repo.root, abs).split(path.sep).join("/");
+      if (!repo.ownsUnitPath(root, rel)) continue;
       if (e.name === "migrations" || e.name === "migration") {
+        out.push(rel);
+        continue;
+      }
+      // Alembic keeps revisions in versions/ under a directory named alembic.
+      // The directory is the migration root; the adapter still reads alembic.ini
+      // (or [tool.alembic]) before treating it as ownership evidence.
+      if (e.name === "versions" && path.basename(dirAbs) === "alembic") {
         out.push(path.relative(repo.root, abs).split(path.sep).join("/"));
         continue;
       }
@@ -77,7 +86,7 @@ export function findMigrationDirs(repo, root, maxDepth = 5) {
 
 export function firstExistingFile(repo, root, names) {
   for (const n of names) {
-    if (repo.exists(root + "/" + n)) return root + "/" + n;
+    if (repo.ownsUnitPath(root, root + "/" + n) && repo.exists(root + "/" + n)) return root + "/" + n;
   }
   return null;
 }