@afokapu/atdd-bun 0.5.0 → 0.6.0

package/README.md

@@ -97,6 +97,7 @@ name.
 | Profile | Use it when you need to check |
 |---|---|
 | `traceability` | plan acceptance, Bun test, and implementation closure |
+| `topology` | feature decomposition and canonical plan, source, test, and E2E locations |
 | `planner` | plan parsing/graph integrity plus the explicitly scoped planner rules |
 | `docs` | the optional documentation capability and its declared artifacts, including the generated journey view |
 | `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions for that concern |
@@ -123,6 +124,35 @@ carry Station Master actions; the Bun interlocking family checks those actions r
 Hooks, direct CLI use, and CI invoke this same profile and therefore share the
 same schema source.
 
+### Repository topology
+
+The topology gate makes a feature a required plan artifact instead of an
+optional label on a WMBT. Its default layout is:
+
+```text
+plan/<wagon>/{_<wagon>,<feature>,<WMBT>}.yaml
+src/wagons/<wagon>/features/<feature>/{domain,application,infrastructure,presentation}/
+tests/wagons/<wagon>/features/<feature>/{unit,contract,integration}/
+e2e/interlockings/<interlocking>/<route>.routes.test.ts
+e2e/journeys/<journey>.journey.test.ts
+```
+
+Each feature must be declared by exactly one wagon and each WMBT by exactly one
+feature. Source and test headers must name the feature in their path; tests bind
+with `Acceptance:`, while exposed journey E2E tests bind with `Train:`. The
+component-URN `integration` layer maps to the `infrastructure/` directory.
+
+Change the four roots for an existing repository in `atdd-bun.yaml`; the same
+validation then follows the configured locations:
+
+```yaml
+topology:
+  plan_root: plan
+  source_root: src/wagons
+  test_root: tests/wagons
+  e2e_root: e2e
+```
+
 ### Design system
 
 The `design` profile (also part of `coder`) is the Bun realization of the core

package/detectors/atdd_topology/atdd.implementation.yaml

@@ -0,0 +1,13 @@
+kind: implementation
+subtype: guard
+implementation_id: atdd_topology
+emits_rule_ids:
+- planner.wagon.features
+- planner.feature.wagon-link
+- atdd-bun.topology.plan-location
+- atdd-bun.topology.source-location
+- atdd-bun.topology.test-location
+- atdd-bun.topology.e2e-location
+- atdd-bun.topology.feature-source-coverage
+- atdd-bun.topology.feature-test-coverage
+entrypoint: detect.mjs

package/detectors/atdd_topology/detect.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env bun
+// Configurable plan/source/test/E2E topology and feature-decomposition gate.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { topologyFor } from "../../src/topology.ts";
+
+const roots = JSON.parse(process.env.ATDD_SCAN_ROOTS || "[]"), report = process.env.ATDD_VIOLATIONS_REPORT;
+if (!report) process.exit(2);
+const sourceExt = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts", ".cts", ".cjs", ".html", ".htm"]);
+const testName = /(?:^test_.*|.*(?:\.test|\.spec|_test))\.(?:[cm]?[jt]sx?)$/;
+const slug = "[a-z][a-z0-9-]*";
+const componentUrn = new RegExp(`^component:(${slug}):(${slug}):[A-Za-z0-9.]+:(frontend|backend):(domain|application|integration|presentation)$`);
+const testUrn = new RegExp(`^test:(${slug}):(${slug}):([A-Za-z0-9][A-Za-z0-9._-]*)$`);
+const violations = [];
+const rel = (root, path) => relative(root, path).split(sep).join("/");
+const read = path => { try { return readFileSync(path, "utf8"); } catch { return ""; } };
+const text = (data, key) => data && typeof data === "object" && !Array.isArray(data) && typeof data[key] === "string" ? data[key] : "";
+const list = (data, key) => data && typeof data === "object" && Array.isArray(data[key]) ? data[key] : [];
+const urns = values => values.map(value => typeof value === "string" ? value : text(value, "urn")).filter(Boolean);
+function add(rule_id, root, path, evidence, line = 1, source_line = "") { violations.push({ rule_id, file: rel(root, path), line, col: 1, evidence, source_line }); }
+function walk(dir, predicate, found = []) {
+  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return found; }
+  for (const entry of entries) {
+    if (["node_modules", ".git", ".atdd", "dist", "build", ".next"].includes(entry.name)) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) walk(path, predicate, found); else if (predicate(path)) found.push(path);
+  }
+  return found;
+}
+async function topology(root) { const value = await topologyFor(root); return { plan_root: value.planRoot, source_root: value.sourceRoot, test_root: value.testRoot, e2e_root: value.e2eRoot }; }
+function header(path) {
+  const lines = read(path).split(/\r?\n/).slice(0, 60);
+  const field = name => {
+    const index = lines.findIndex(line => new RegExp(`^\\s*//\\s*${name}:\\s*(\\S.*?)\\s*$`).test(line));
+    return index < 0 ? { value: "", line: 1, raw: "" } : { value: lines[index].replace(new RegExp(`^\\s*//\\s*${name}:\\s*`), "").trim(), line: index + 1, raw: lines[index].trim() };
+  };
+  return { urn: field("URN"), acceptance: field("Acceptance"), train: field("Train"), journey: field("Journey") };
+}
+
+for (const root of roots) {
+  const cfg = await topology(root), planRoot = join(root, cfg.plan_root), docs = [];
+  for (const path of walk(planRoot, path => /\.ya?ml$/.test(path))) {
+    try { const data = Bun.YAML.parse(read(path)); if (data && typeof data === "object" && !Array.isArray(data)) docs.push({ path, data }); } catch { /* schema validation owns parse errors */ }
+  }
+  const wagons = docs.filter(doc => text(doc.data, "urn").startsWith("wagon:")).map(doc => ({ ...doc, slug: text(doc.data, "urn").slice(6) }));
+  const features = docs.filter(doc => text(doc.data, "urn").startsWith("feature:")).map(doc => { const [,, wagon, slug] = ["", ...text(doc.data, "urn").split(":")]; return { ...doc, wagon, slug, urn: text(doc.data, "urn") }; });
+  const wmbts = docs.filter(doc => text(doc.data, "urn").startsWith("wmbt:")).map(doc => { const [, wagon, code] = text(doc.data, "urn").split(":"); return { ...doc, wagon, code, urn: text(doc.data, "urn") }; });
+  const featureByUrn = new Map(features.map(feature => [feature.urn, feature])), memberships = new Map(), wmbtOwners = new Map(), sourceByFeature = new Map(), testByFeature = new Map();
+  const acceptances = new Set(wmbts.flatMap(wmbt => list(wmbt.data, "acceptances").map(acceptance => text(acceptance?.identity, "urn")).filter(Boolean)));
+  const trains = new Set(docs.map(doc => text(doc.data, "train_id")).filter(Boolean));
+
+  for (const wagon of wagons) {
+    const expected = `${cfg.plan_root}/${wagon.slug}/_${wagon.slug}.yaml`;
+    if (rel(root, wagon.path) !== expected) add("atdd-bun.topology.plan-location", root, wagon.path, `wagon:${wagon.slug} must be declared at ${expected}`);
+    const declared = urns(list(wagon.data, "features"));
+    if ((Number(wagon.data.wmbt?.total) > 0 || wmbts.some(wmbt => wmbt.wagon === wagon.slug)) && !declared.length) add("planner.wagon.features", root, wagon.path, `wagon:${wagon.slug} has WMBTs but no feature decomposition`);
+    for (const urn of declared) {
+      const feature = featureByUrn.get(urn);
+      if (!feature) { add("planner.wagon.features", root, wagon.path, `wagon:${wagon.slug} lists ${urn}, but no feature document declares it`); continue; }
+      memberships.set(urn, [...(memberships.get(urn) || []), wagon.slug]);
+      if (feature.wagon !== wagon.slug || text(feature.data, "wagon") !== `wagon:${wagon.slug}`) add("planner.feature.wagon-link", root, feature.path, `${urn} must belong to wagon:${wagon.slug}`);
+    }
+  }
+  for (const feature of features) {
+    const expected = `${cfg.plan_root}/${feature.wagon}/${feature.slug}.yaml`, owners = memberships.get(feature.urn) || [];
+    if (rel(root, feature.path) !== expected) add("atdd-bun.topology.plan-location", root, feature.path, `${feature.urn} must be declared at ${expected}`);
+    if (owners.length !== 1) add("planner.feature.wagon-link", root, feature.path, `${feature.urn} must be listed by exactly one wagon; found ${owners.length}`);
+    for (const urn of urns(list(feature.data, "wmbts"))) wmbtOwners.set(urn, [...(wmbtOwners.get(urn) || []), feature.urn]);
+  }
+  for (const wmbt of wmbts) {
+    const expected = `${cfg.plan_root}/${wmbt.wagon}/${wmbt.code}.yaml`, owners = wmbtOwners.get(wmbt.urn) || [];
+    if (rel(root, wmbt.path) !== expected) add("atdd-bun.topology.plan-location", root, wmbt.path, `${wmbt.urn} must be declared at ${expected}`);
+    if (owners.length !== 1) add("planner.wagon.features", root, wmbt.path, `${wmbt.urn} must belong to exactly one feature; found ${owners.length}`);
+  }
+
+  const declaredFeatures = new Set(features.map(feature => `${feature.wagon}:${feature.slug}`));
+  // A repository can ship an independent frontend or infrastructure fixture with journeys but
+  // no wagon/feature plan. Feature layout begins only when the plan models a feature; this
+  // preserves that boundary while making every modeled feature strict.
+  const modelsFeatures = wagons.length > 0 || features.length > 0 || wmbts.length > 0;
+  if (modelsFeatures) for (const path of walk(join(root, cfg.source_root), path => sourceExt.has(path.slice(path.lastIndexOf("."))) && !testName.test(path))) {
+    const h = header(path), match = componentUrn.exec(h.urn.value);
+    if (!match) { add("atdd-bun.topology.source-location", root, path, "source requires URN: component:{wagon}:{feature}:{name}:{frontend|backend}:{domain|application|integration|presentation}", h.urn.line, h.urn.raw); continue; }
+    const wagon = match[1], feature = match[2], layer = match[4], expected = `${cfg.source_root}/${wagon}/features/${feature}/${layer === "integration" ? "infrastructure" : layer}/`;
+    if (!rel(root, path).startsWith(expected)) add("atdd-bun.topology.source-location", root, path, `${h.urn.value} must live beneath ${expected}`, h.urn.line, h.urn.raw);
+    else sourceByFeature.set(`${wagon}:${feature}`, [...(sourceByFeature.get(`${wagon}:${feature}`) || []), path]);
+    if (wagon && feature && !declaredFeatures.has(`${wagon}:${feature}`)) add("planner.feature.wagon-link", root, path, `${h.urn.value} names undeclared feature:${wagon}:${feature}`, h.urn.line, h.urn.raw);
+  }
+  if (modelsFeatures) for (const path of walk(join(root, cfg.test_root), path => testName.test(path))) {
+    const h = header(path), match = testUrn.exec(h.urn.value);
+    if (!match) { add("atdd-bun.topology.test-location", root, path, "test requires URN: test:{wagon}:{feature}:{acceptance}", h.urn.line, h.urn.raw); continue; }
+    const [, wagon, feature, acceptance] = match, expected = `${cfg.test_root}/${wagon}/features/${feature}/`;
+    if (!rel(root, path).startsWith(expected) || !/(unit|contract|integration)\//.test(rel(root, path).slice(expected.length))) add("atdd-bun.topology.test-location", root, path, `${h.urn.value} must live beneath ${expected}{unit,contract,integration}/`, h.urn.line, h.urn.raw);
+    if (wagon && feature && !declaredFeatures.has(`${wagon}:${feature}`)) add("planner.feature.wagon-link", root, path, `${h.urn.value} names undeclared feature:${wagon}:${feature}`, h.urn.line, h.urn.raw);
+    const binding = `acc:${wagon}:${acceptance}`;
+    if (h.acceptance.value !== binding) add("atdd-bun.topology.test-location", root, path, `${h.urn.value} must bind Acceptance: ${binding}`, h.acceptance.line, h.acceptance.raw);
+    else if (!acceptances.has(binding)) add("atdd-bun.topology.test-location", root, path, `${binding} is not declared by a WMBT in ${cfg.plan_root}/`, h.acceptance.line, h.acceptance.raw);
+    else testByFeature.set(`${wagon}:${feature}`, [...(testByFeature.get(`${wagon}:${feature}`) || []), path]);
+  }
+  for (const feature of features) if (list(feature.data, "wmbts").length) {
+    const key = `${feature.wagon}:${feature.slug}`;
+    if (!sourceByFeature.get(key)?.length) add("atdd-bun.topology.feature-source-coverage", root, feature.path, `${feature.urn} owns WMBTs but has no source component beneath ${cfg.source_root}/${feature.wagon}/features/${feature.slug}/`);
+    if (!testByFeature.get(key)?.length) add("atdd-bun.topology.feature-test-coverage", root, feature.path, `${feature.urn} owns WMBTs but has no test bound to one of its acceptances`);
+  }
+  const e2eRoot = join(root, cfg.e2e_root);
+  // A browser test is the E2E proof for a frontend behavior. It deliberately
+  // substitutes for the Bun E2E path below, never supplements it: one behavior,
+  // one runner. htmx_e2e_detector (included in the tester profile) owns the
+  // stricter Playwright naming, header, subject, and harness validation.
+  const browserTrains = new Set(), browserJourneys = new Set();
+  for (const path of walk(e2eRoot, path => /\.e2e\.[cm]?[jt]sx?$/.test(path))) {
+    const content = read(path), h = header(path);
+    if (!/from\s+["']@playwright\/test["']/.test(content) || !/(^|[^.\w])test(\.(describe|only|skip|fixme|fail|slow|step))?\s*\(/m.test(content)) continue;
+    if (h.train.value) browserTrains.add(h.train.value);
+    if (h.journey.value) browserJourneys.add(h.journey.value);
+  }
+  const interlockingRoutes = new Set();
+  const interlockings = new Map(docs.filter(doc => text(doc.data, "interlocking_id").startsWith("interlocking:")).map(doc => [text(doc.data, "interlocking_id"), doc]));
+  const journeys = docs.filter(doc => text(doc.data, "journey_id").startsWith("journey:"));
+  const journeyReachability = journey => {
+    const continuations = list(journey.data, "continuations"), reachable = new Set(), queue = [text(journey.data.entrypoint, "interlocking_id")].filter(Boolean);
+    while (queue.length) {
+      const interlockingId = queue.shift(); if (!interlockingId || reachable.has(interlockingId)) continue;
+      reachable.add(interlockingId);
+      for (const continuation of continuations) if (text(continuation?.from, "interlocking_id") === interlockingId && text(continuation?.to, "interlocking_id")) queue.push(text(continuation.to, "interlocking_id"));
+    }
+    return reachable;
+  };
+  const hasFrontendSurface = entry => !Array.isArray(entry?.surfaces) || entry.surfaces.map(String).includes("frontend");
+  const frontendInterlockings = new Set(journeys.filter(journey => {
+    const entry = journey.data.entrypoint;
+    return entry && typeof entry === "object" && entry.exposed === true && hasFrontendSurface(entry);
+  }).flatMap(journey => [...journeyReachability(journey)]));
+  for (const interlocking of interlockings.values()) {
+    const id = text(interlocking.data, "interlocking_id").slice(13);
+    for (const route of list(interlocking.data, "routes")) {
+      const routeId = text(route, "route_id"); if (!routeId) continue;
+      const expected = join(e2eRoot, "interlockings", id, `${routeId}.routes.test.ts`);
+      interlockingRoutes.add(rel(root, expected));
+      const browserEligible = frontendInterlockings.has(text(interlocking.data, "interlocking_id"));
+      if (!existsSync(expected) && !(browserEligible && browserTrains.has(text(route, "train_id")))) add("atdd-bun.topology.e2e-location", root, interlocking.path, browserEligible
+        ? `${text(interlocking.data, "interlocking_id")} route ${routeId} requires ${rel(root, expected)} or a Playwright E2E spec bound to Train: ${text(route, "train_id")}`
+        : `${text(interlocking.data, "interlocking_id")} route ${routeId} is not on an exposed frontend journey and requires ${rel(root, expected)}`);
+    }
+  }
+  for (const journey of journeys) {
+    const entry = journey.data.entrypoint, id = text(journey.data, "journey_id").slice(8), path = join(e2eRoot, "journeys", `${id}.journey.test.ts`);
+    const reachable = journeyReachability(journey), journeyTrains = new Set([...reachable].flatMap(interlockingId => list(interlockings.get(interlockingId)?.data, "routes").map(route => text(route, "train_id")).filter(Boolean)));
+    const browserEligible = entry && typeof entry === "object" && hasFrontendSurface(entry);
+    if (entry && typeof entry === "object" && entry.exposed === true && !existsSync(path) && !(browserEligible && browserJourneys.has(`journey:${id}`))) add("atdd-bun.topology.e2e-location", root, journey.path, browserEligible
+      ? `exposed journey:${id} requires ${cfg.e2e_root}/journeys/${id}.journey.test.ts or a Playwright E2E spec bound to Journey: journey:${id}`
+      : `exposed backend journey:${id} requires ${cfg.e2e_root}/journeys/${id}.journey.test.ts`);
+    else if (entry && typeof entry === "object" && entry.exposed === true && existsSync(path)) {
+      const h = header(path), match = testUrn.exec(h.urn.value);
+      if (!match || !declaredFeatures.has(`${match[1]}:${match[2]}`)) add("atdd-bun.topology.e2e-location", root, path, "journey E2E test requires a test:{wagon}:{feature}:{acceptance} URN naming a declared feature", h.urn.line, h.urn.raw);
+      if (!trains.has(h.train.value) || !journeyTrains.has(h.train.value)) add("atdd-bun.topology.e2e-location", root, path, `journey E2E Train: must resolve to a reachable selected train; found ${h.train.value || "<missing>"}`, h.train.line, h.train.raw);
+    }
+  }
+  for (const path of walk(e2eRoot, path => testName.test(path))) {
+    const location = rel(root, path), h = header(path);
+    if (location.startsWith(`${cfg.e2e_root}/journeys/`) && !/\.journey\.test\.[cm]?[jt]sx?$/.test(path)) add("atdd-bun.topology.e2e-location", root, path, "journey E2E tests must end in .journey.test.ts", h.urn.line, h.urn.raw);
+    if (location.startsWith(`${cfg.e2e_root}/interlockings/`) && !/\.routes\.test\.[cm]?[jt]sx?$/.test(path)) add("atdd-bun.topology.e2e-location", root, path, "interlocking E2E tests must end in .routes.test.ts", h.urn.line, h.urn.raw);
+    if (location.startsWith(`${cfg.e2e_root}/interlockings/`) && /\.routes\.test\.[cm]?[jt]sx?$/.test(path) && interlockingRoutes.size && !interlockingRoutes.has(location)) add("atdd-bun.topology.e2e-location", root, path, "interlocking E2E test does not name a declared route", h.urn.line, h.urn.raw);
+    if (location.startsWith(`${cfg.e2e_root}/interlockings/`) && /\.routes\.test\.[cm]?[jt]sx?$/.test(path)) {
+      const match = testUrn.exec(h.urn.value);
+      if (!match || !declaredFeatures.has(`${match[1]}:${match[2]}`)) add("atdd-bun.topology.e2e-location", root, path, "interlocking E2E test requires a test:{wagon}:{feature}:{acceptance} URN naming a declared feature", h.urn.line, h.urn.raw);
+      else if (h.acceptance.value !== `acc:${match[1]}:${match[3]}` || !acceptances.has(h.acceptance.value)) add("atdd-bun.topology.e2e-location", root, path, "interlocking E2E test requires an Acceptance: binding declared by a WMBT", h.acceptance.line, h.acceptance.raw);
+    }
+  }
+}
+writeFileSync(report, JSON.stringify({ violations }, null, 2));

package/detectors/atdd_topology/fixtures/clean/atdd-bun.yaml

@@ -0,0 +1,2 @@
+topology:
+  source_root: implementation

package/detectors/atdd_topology/fixtures/clean/e2e/interlockings/checkout/nominal.routes.test.ts

@@ -0,0 +1,4 @@
+// URN: test:orders:place-order:E001-E2E-002
+// Acceptance: acc:orders:E001-E2E-002
+import { test } from "bun:test";
+test("nominal", () => {});

package/detectors/atdd_topology/fixtures/clean/e2e/journeys/checkout.journey.test.ts

@@ -0,0 +1,4 @@
+// URN: test:orders:place-order:E001-E2E-001
+// Train: train:orders:checkout
+import { test } from "bun:test";
+test("checkout", () => {});

package/detectors/atdd_topology/fixtures/clean/implementation/orders/features/place-order/domain/order.ts

@@ -0,0 +1,4 @@
+// URN: component:orders:place-order:Order:backend:domain
+// Tested-By:
+// - test:orders:place-order:E001-UNIT-001
+export class Order {}

package/detectors/atdd_topology/fixtures/clean/plan/_journeys/checkout.yaml

@@ -0,0 +1,4 @@
+journey_id: journey:checkout
+entrypoint:
+  exposed: true
+  interlocking_id: interlocking:checkout

package/detectors/atdd_topology/fixtures/clean/plan/_trains/_interlockings/checkout.yaml

@@ -0,0 +1,4 @@
+interlocking_id: interlocking:checkout
+routes:
+  - route_id: nominal
+    train_id: train:orders:checkout

package/detectors/atdd_topology/fixtures/clean/plan/_trains/checkout.yaml

@@ -0,0 +1 @@
+train_id: train:orders:checkout

package/detectors/atdd_topology/fixtures/clean/plan/orders/E001.yaml

@@ -0,0 +1,6 @@
+urn: wmbt:orders:E001
+acceptances:
+  - identity:
+      urn: acc:orders:E001-UNIT-001
+  - identity:
+      urn: acc:orders:E001-E2E-002

package/detectors/atdd_topology/fixtures/clean/plan/orders/_orders.yaml

@@ -0,0 +1,5 @@
+urn: wagon:orders
+wmbt:
+  total: 1
+features:
+  - urn: feature:orders:place-order

package/detectors/atdd_topology/fixtures/clean/plan/orders/place-order.yaml

@@ -0,0 +1,3 @@
+urn: feature:orders:place-order
+wagon: wagon:orders
+wmbts: [wmbt:orders:E001]

package/detectors/atdd_topology/fixtures/clean/tests/wagons/orders/features/place-order/unit/order.test.ts

@@ -0,0 +1,4 @@
+// URN: test:orders:place-order:E001-UNIT-001
+// Acceptance: acc:orders:E001-UNIT-001
+import { test } from "bun:test";
+test("order", () => {});

package/detectors/atdd_topology/fixtures/dirty/plan/_journeys/checkout.yaml

@@ -0,0 +1,3 @@
+journey_id: journey:checkout
+entrypoint:
+  exposed: true

package/detectors/atdd_topology/fixtures/dirty/plan/orders/E001.yaml

@@ -0,0 +1,4 @@
+urn: wmbt:orders:E001
+acceptances:
+  - identity:
+      urn: acc:orders:E001-UNIT-001

package/detectors/atdd_topology/fixtures/dirty/plan/orders/_orders.yaml

@@ -0,0 +1,4 @@
+urn: wagon:orders
+wmbt:
+  total: 1
+features: []

package/detectors/atdd_topology/fixtures/dirty/plan/orders/features/place-order.yaml

@@ -0,0 +1,3 @@
+urn: feature:orders:place-order
+wagon: wagon:orders
+wmbts: [wmbt:orders:E001]

package/detectors/atdd_topology/fixtures/dirty/src/wagons/orders/features/place-order/domain/forged.ts

@@ -0,0 +1,2 @@
+// URN: forged:orders:place-order:Forged:backend:domain
+export class Forged {}

package/detectors/atdd_topology/fixtures/dirty/src/wagons/orders/features/place-order/domain/order.ts

@@ -0,0 +1,2 @@
+// URN: component:orders:missing:Order:backend:domain
+export class Order {}

package/detectors/atdd_topology/fixtures/dirty/tests/wagons/orders/features/place-order/unit/order.test.ts

@@ -0,0 +1,4 @@
+// URN: test:orders:place-order:E001-UNIT-001
+// Acceptance: acc:orders:WRONG
+import { test } from "bun:test";
+test("order", () => {});

package/detectors/atdd_traceability_closure/detect.mjs

@@ -2,6 +2,7 @@
 // Bun-native closure gate for plan -> test -> implementation traceability.
 import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
+import { topologyFor } from "../../src/topology.ts";
 
 const roots = JSON.parse(process.env.ATDD_SCAN_ROOTS || "[]");
 const excludes = new Set(JSON.parse(process.env.ATDD_SCAN_EXCLUDES || "[]"));
@@ -14,6 +15,7 @@ const violations = [];
 const plans = { acc: new Set(), wmbt: new Set(), train: new Set() };
 const tests = new Map();
 const sources = [];
+let planDisplay = "plan/";
 
 function ignored(path) {
   return [...excludes].some((needle) => path.includes(needle));
@@ -33,10 +35,11 @@ function add(rule_id, file, line, evidence, source_line = "") {
 function lineOf(content, token) { return content.slice(0, content.indexOf(token)).split("\n").length; }
 
 for (const root of roots) {
+  const topology = await topologyFor(root), planPrefix = topology.planRoot.replace(/\/$/, "") + "/"; planDisplay = planPrefix;
   walk(root, (path) => {
     const name = path.split("/").pop() || "";
     const content = text(path);
-    if (/\.ya?ml$/i.test(name) && /(?:^|\/)plan(?:\/|$)/.test(path)) {
+    if (/\.ya?ml$/i.test(name) && relative(root, path).replaceAll("\\", "/").startsWith(planPrefix)) {
       for (const [kind, re] of Object.entries({
         acc: /\bacc:[A-Za-z0-9_.:-]+/g,
         wmbt: /\bwmbt:[A-Za-z0-9_.:-]+/g,
@@ -70,7 +73,7 @@ for (const test of tests.values()) {
 }
 const boundAcceptances = new Set([...tests.values()].map((test) => test.binding).filter((id) => id?.startsWith("acc:")));
 for (const acceptance of plans.acc) {
-  if (!boundAcceptances.has(acceptance)) add("traceability.plan.executable-acceptance-has-test", "plan/", 1, `${acceptance} has no Bun test binding`, acceptance);
+  if (!boundAcceptances.has(acceptance)) add("traceability.plan.executable-acceptance-has-test", planDisplay, 1, `${acceptance} has no Bun test binding`, acceptance);
 }
 for (const source of sources) {
   if (!source.testedBy.length) {

package/detectors/bun_interlocking_binding/checks/interlocking_runtime_executes.mjs

@@ -30,6 +30,7 @@ const LOADS_DECLARATION =
   /\breadFileSync\s*\(|\breadFile\s*\(|\bBun\s*\.\s*file\s*\(|\bcreateReadStream\s*\(|\bfs\s*\.\s*promises\s*\.\s*readFile\b/;
 const RESOLVES = /\bInterlockingResolution\b|\bresolveTrain\s*\(/;
 const EXCLUDES = ["node_modules", "dist", "build", ".next", "_generated"];
+const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
 
 const readText = (p) => { try { return readFileSync(p, "utf8"); } catch { return ""; } };
 
@@ -53,7 +54,7 @@ export function findConsumerRoots(scanRoot) {
   (function rec(d) {
     let st; try { st = statSync(d); } catch { return; }
     if (!st.isDirectory()) return;
-    for (const marker of ["src", "plan", "e2e"]) {
+    for (const marker of ["src", PLAN_ROOT, "e2e"]) {
       try { if (statSync(join(d, marker)).isDirectory()) { roots.add(d); break; } } catch {}
     }
     let entries; try { entries = readdirSync(d).sort(); } catch { return; }
@@ -111,7 +112,7 @@ export function maskComments(text) {
 export function scanExecution(scanRoot) {
   const violations = [];
   for (const croot of findConsumerRoots(scanRoot)) {
-    const ilFiles = walk(join(croot, "plan"), (f) => /_interlockings[/\\].*\.ya?ml$/.test(f));
+    const ilFiles = walk(join(croot, PLAN_ROOT), (f) => /_interlockings[/\\].*\.ya?ml$/.test(f));
     const declared = [...new Set(ilFiles.flatMap((f) => declaredValues(readText(f))))];
     if (!declared.length) continue;
     const rtFiles = walk(join(croot, "src/trains"), (f) => /\.(ts|tsx|mjs|js)$/.test(f))

package/detectors/bun_interlocking_binding/detect.mjs

@@ -28,6 +28,7 @@ import { join, sep, resolve } from "node:path";
 const RULE = "coder.bun.interlocking-bilateral-binding";
 const DEFAULT_EXCLUDES = ["_generated", "node_modules", "dist", "build", ".next"];
 const PARALLEL_FIELDS = ["entrypoints", "runtime_exposure", "station_actions", "exposed_actions", "reachability"];
+const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
 
 // ── generic IO / masking ─────────────────────────────────────────────────────
 
@@ -147,7 +148,7 @@ function* walkDirs(root) {
 function findConsumerRoots(scanRoot) {
   const roots = new Set();
   for (const d of walkDirs(scanRoot)) {
-    if (hasChildDir(d, "src") || hasChildDir(d, "plan") || hasChildDir(d, "e2e")) roots.add(d);
+    if (hasChildDir(d, "src") || hasChildDir(d, PLAN_ROOT) || hasChildDir(d, "e2e")) roots.add(d);
   }
   return [...roots];
 }
@@ -181,9 +182,9 @@ const isYaml = (f) => f.endsWith(".yaml") || f.endsWith(".yml");
 const isTs = (f) => f.endsWith(".ts") || f.endsWith(".tsx");
 
 function interlockingFiles(croot) {
-  const base = join(croot, "plan", "_trains", "_interlockings");
+  const base = join(croot, PLAN_ROOT, "_trains", "_interlockings");
   const out = [...walkFiles(base, isYaml)];
-  const idx = join(croot, "plan", "_trains", "_interlockings.yaml");
+  const idx = join(croot, PLAN_ROOT, "_trains", "_interlockings.yaml");
   try {
     if (statSync(idx).isFile()) out.push(idx);
   } catch {
@@ -377,7 +378,7 @@ function trainArtifactExists(croot, route) {
   }
   if (route.trainId) {
     try {
-      return statSync(join(croot, "plan", "_trains", `${route.trainId}.yaml`)).isFile();
+      return statSync(join(croot, PLAN_ROOT, "_trains", `${route.trainId}.yaml`)).isFile();
     } catch {
       return false;
     }
@@ -413,7 +414,7 @@ function scanConsumerRoot(croot) {
   for (const rec of records) {
     for (const route of rec.routes) {
       if (trainArtifactExists(croot, route)) continue;
-      const target = route.trainPath || (route.trainId ? `plan/_trains/${route.trainId}.yaml` : "<no train_id>");
+      const target = route.trainPath || (route.trainId ? `${PLAN_ROOT}/_trains/${route.trainId}.yaml` : "<no train_id>");
       violations.push(
         mk(
           rel(rec.file, croot),

package/detectors/bun_interlocking_coverage/_shared/interlocking.mjs

@@ -10,6 +10,7 @@ import { readFileSync, statSync, readdirSync, writeFileSync } from "node:fs";
 import { join, sep } from "node:path";
 
 export const DEFAULT_EXCLUDES = ["_generated", "node_modules", "dist", "build", ".next"];
+export const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
 
 // Production runner symbols (core #1251 call model).
 export const PROD_INTERLOCKING = "InterlockingRunner";
@@ -220,7 +221,7 @@ function* walkDirs(root) {
 export function findConsumerRoots(scanRoot) {
   const roots = new Set();
   for (const d of walkDirs(scanRoot)) {
-    if (hasChildDir(d, "plan") || hasChildDir(d, "e2e") || hasChildDir(d, "src")) roots.add(d);
+    if (hasChildDir(d, PLAN_ROOT) || hasChildDir(d, "e2e") || hasChildDir(d, "src")) roots.add(d);
   }
   return [...roots];
 }
@@ -254,9 +255,9 @@ const isYaml = (f) => f.endsWith(".yaml") || f.endsWith(".yml");
 const isTs = (f) => f.endsWith(".ts") || f.endsWith(".tsx");
 
 export function interlockingFiles(croot) {
-  const base = join(croot, "plan", "_trains", "_interlockings");
+  const base = join(croot, PLAN_ROOT, "_trains", "_interlockings");
   const out = [...walkFiles(base, isYaml)];
-  const idx = join(croot, "plan", "_trains", "_interlockings.yaml");
+  const idx = join(croot, PLAN_ROOT, "_trains", "_interlockings.yaml");
   try {
     if (statSync(idx).isFile()) out.push(idx);
   } catch {

package/detectors/bun_interlocking_coverage/checks/interlocking_train_sequence.mjs

@@ -16,7 +16,7 @@
 // suite green. The runtime obeyed the new plan; no test looked.
 import {
   parseJsonEnv, readText, findConsumerRoots, interlockingFiles, e2eFiles,
-  parseInterlocking, tokenCovered, rel, mk,
+  parseInterlocking, tokenCovered, rel, mk, PLAN_ROOT,
 } from "../_shared/interlocking.mjs";
 import { writeFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -69,7 +69,7 @@ export function declaresASequence(croot, trainId) {
       if (st.isDirectory()) { if (name !== "_interlockings") rec(full); continue; }
       if (/\.ya?ml$/.test(name)) found.push(full);
     }
-  })(join(croot, "plan"));
+  })(join(croot, PLAN_ROOT));
   for (const f of found) {
     const text = readText(f);
     if (!text.includes(trainId)) continue;

package/detectors/bun_interlocking_infrastructure/_shared/interlocking.mjs

@@ -25,6 +25,7 @@ import { readFileSync, statSync, readdirSync, writeFileSync } from "node:fs";
 import { join, sep, basename } from "node:path";
 
 export const DEFAULT_EXCLUDES = ["_generated", "node_modules", "dist", "build", ".next"];
+export const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
 
 // Structured-resolution model contract, TS camelCase, transcribed from core's own
 // InterlockingResolution (src/atdd/runtime/interlocking/runner.py).
@@ -127,7 +128,7 @@ function* walkDirs(root) {
 export function findConsumerRoots(scanRoot) {
   const roots = new Set();
   for (const d of walkDirs(scanRoot)) {
-    if (hasChildDir(d, "src") || hasChildDir(d, "plan") || hasChildDir(d, "e2e")) roots.add(d);
+    if (hasChildDir(d, "src") || hasChildDir(d, PLAN_ROOT) || hasChildDir(d, "e2e")) roots.add(d);
   }
   return [...roots];
 }

package/detectors/bun_interlocking_infrastructure/checks/journey_runner_boundary.mjs

@@ -18,6 +18,7 @@ import {
   mk,
   writeReport,
   maskComments,
+  PLAN_ROOT,
 } from "../_shared/interlocking.mjs";
 
 const RULE = "coder.bun.journey-runner-boundary";
@@ -25,7 +26,7 @@ const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
 const violations = [];
 
 function hasJourneyTopology(root) {
-  const base = join(root, "plan", "_journeys");
+  const base = join(root, PLAN_ROOT, "_journeys");
   if (!existsSync(base)) return false;
   const stack = [base];
   while (stack.length) {
@@ -88,7 +89,7 @@ for (const scanRoot of roots) {
     if (modules.length === 0) {
       violations.push(mk(
         RULE,
-        "plan/_journeys",
+        `${PLAN_ROOT}/_journeys`,
         1,
         0,
         "missing-journey-runner: journey topology is declared but no JourneyRunner class exists under src/trains/",

package/detectors/bun_interlocking_infrastructure/checks/journey_station_routing.mjs

@@ -13,6 +13,7 @@ import {
   mk,
   writeReport,
   maskComments,
+  PLAN_ROOT,
 } from "../_shared/interlocking.mjs";
 
 const RULE = "coder.bun.station-master-journey-routing";
@@ -24,7 +25,7 @@ function escapeRegExp(value) {
 }
 
 function journeyDocuments(croot) {
-  const base = join(croot, "plan", "_journeys");
+  const base = join(croot, PLAN_ROOT, "_journeys");
   if (!existsSync(base)) return [];
   const out = [], stack = [base];
   while (stack.length) {

package/detectors/bun_interlocking_infrastructure/checks/wagon_contract_honoured.mjs

@@ -30,6 +30,7 @@ const RULE = "coder.bun.wagon-honours-its-contract";
 const EXCLUDES = ["node_modules", "dist", "build", ".next", ".git", "_generated"];
 const TS = /\.(ts|tsx|mjs|js)$/;
 const TEST = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
 
 const read = (p) => { try { return readFileSync(p, "utf8"); } catch { return ""; } };
 
@@ -61,7 +62,7 @@ function consumerRoots(root, excludes) {
     let st;
     try { st = statSync(d); } catch { return; }
     if (!st.isDirectory()) return;
-    try { if (statSync(join(d, "plan")).isDirectory()) { roots.push(d); return; } } catch {}
+    try { if (statSync(join(d, PLAN_ROOT)).isDirectory()) { roots.push(d); return; } } catch {}
     let entries;
     try { entries = readdirSync(d).sort(); } catch { return; }
     for (const n of entries) if (!excludes.includes(n)) rec(join(d, n));
@@ -111,7 +112,7 @@ const violations = [];
 for (const root of parseJsonEnv("ATDD_SCAN_ROOTS", [])) {
   for (const croot of consumerRoots(root, excludes)) {
     const contracts = [];
-    for (const f of walk(join(croot, "plan"), (p) => /\.ya?ml$/.test(p), excludes)) {
+    for (const f of walk(join(croot, PLAN_ROOT), (p) => /\.ya?ml$/.test(p), excludes)) {
       const c = wagonContract(read(f));
       if (c) contracts.push({ file: f, ...c });
     }

package/detectors/bun_tester_discipline_detector/checks/t_acceptance_resolves.mjs

@@ -48,9 +48,9 @@ function planFiles(dir, excludes) {
 // and WMBT documents, and a reference is resolvable if the plan states that URN
 // anywhere. Over-accepting here is safe — the failure this rule exists to catch is a
 // reference to something the plan never mentions at all.
-function declaredUrns(croot, excludes) {
+function declaredUrns(croot, excludes, planRoot) {
   const urns = new Set();
-  for (const f of planFiles(join(croot, "plan"), excludes)) {
+  for (const f of planFiles(join(croot, planRoot), excludes)) {
     for (const m of read(f).matchAll(/\b((?:acc|wmbt):[a-z0-9][\w.-]*(?::[\w.-]+)?)/gi)) {
       urns.add(m[1]);
     }
@@ -58,13 +58,13 @@ function declaredUrns(croot, excludes) {
   return urns;
 }
 
-function consumerRoots(root, excludes) {
+function consumerRoots(root, excludes, planRoot) {
   const roots = [];
   (function rec(d) {
     let st;
     try { st = statSync(d); } catch { return; }
     if (!st.isDirectory()) return;
-    try { if (statSync(join(d, "plan")).isDirectory()) { roots.push(d); return; } } catch {}
+    try { if (statSync(join(d, planRoot)).isDirectory()) { roots.push(d); return; } } catch {}
     let entries;
     try { entries = readdirSync(d).sort(); } catch { return; }
     for (const n of entries) if (!excludes.includes(n)) rec(join(d, n));
@@ -79,10 +79,11 @@ if (!reportPath) {
 }
 const excludes = [...DEFAULT_EXCLUDES, ...parseJsonEnv("ATDD_SCAN_EXCLUDES", [])];
 const violations = [];
+const planRoot = process.env.ATDD_PLAN_ROOT || "plan";
 
 for (const root of parseJsonEnv("ATDD_SCAN_ROOTS", [])) {
-  for (const croot of consumerRoots(root, excludes)) {
-    const declared = declaredUrns(croot, excludes);
+  for (const croot of consumerRoots(root, excludes, planRoot)) {
+    const declared = declaredUrns(croot, excludes, planRoot);
     if (!declared.size) continue;          // nothing declared: nothing to resolve against
     for (const file of walkTests(croot, excludes)) {
       const H = parseHeader(read(file));

package/integrity.json

@@ -1,9 +1,9 @@
 {
-  "version": "0.5.0",
+  "version": "0.6.0",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
-    "README.md": "1b2ad5a7a1cc0a5e8f135dd819d077a44b94b549c5d2bbe5f45360221c232863",
+    "README.md": "622e7768f567099b0e30ac82f2053c165b8023e571966fc327f77f985ae1be0d",
     "bunfig.toml": "b9fc65eca9014c5179380259d70e76385a6a80788fa9a2df5fb3eaa5554fd2fe",
     "conventions/coder.bun/coder.bun.boundaries-http-client.convention.yaml": "b846bb6ced2c4c967466520d52b00ff1ca802dafcdbb2ec2adbd0ce19e752a28",
     "conventions/coder.bun/coder.bun.commons-application-no-integration.convention.yaml": "f63e7f6442bcdf5cf79f58a091547a1a990d0ee7c006b797fd5187d6f8bf8712",
@@ -124,8 +124,28 @@
     "conventions/traceability/traceability.source.tested-by-present.convention.yaml": "27a2340a9dae9eee67a3fbdcea0d2f8f35f222f22dbce7f84b2a0c6ab6321018",
     "conventions/traceability/traceability.source.tested-by-resolves.convention.yaml": "ad4516670934dc82f1ebf9dc057110313059110302f88b4747dde89dd060870b",
     "conventions/traceability/traceability.test.binding-resolves.convention.yaml": "03c118f498b1e824d457d25c060c8f9689ccbcca49c58d8bcd158e3cd3144ee9",
+    "detectors/atdd_topology/atdd.implementation.yaml": "e5121dfd24c8dff4a3d471c90946e995c1efb3d56433d5739c289e77c7dd13ec",
+    "detectors/atdd_topology/detect.mjs": "ab79df467d12423c8c851fae198b97adaef6fc5b66681b2460b8aeb84a210b36",
+    "detectors/atdd_topology/fixtures/clean/atdd-bun.yaml": "85049c05fb624037e1e2200a117b07d6c8d089d4e81fd784ade15a860a444f59",
+    "detectors/atdd_topology/fixtures/clean/e2e/interlockings/checkout/nominal.routes.test.ts": "be769e192e8165d4d36be743e8df578c1790b900c6b89acc7d2046ba40105135",
+    "detectors/atdd_topology/fixtures/clean/e2e/journeys/checkout.journey.test.ts": "330dd13694d4b53b1ee261dd8d37e0610ef0cf4e92bc70ccf3039878bfee90a7",
+    "detectors/atdd_topology/fixtures/clean/implementation/orders/features/place-order/domain/order.ts": "b81c0630a2c518749ed6d81741ba4e1503ffdbc64f232747518a17e8e8a46927",
+    "detectors/atdd_topology/fixtures/clean/plan/_journeys/checkout.yaml": "c61021d0bf2f7f3bfe306b18c4b34563292de02acce47326db71ac4f8d67bc8d",
+    "detectors/atdd_topology/fixtures/clean/plan/_trains/_interlockings/checkout.yaml": "99ee3ef93e3098943878c947a584d93fec1407f0a5bd85c5383129229a98d0bc",
+    "detectors/atdd_topology/fixtures/clean/plan/_trains/checkout.yaml": "d022cd946cced5961d16535f93cc875b76e2cad872625e5e040242810f8cfad1",
+    "detectors/atdd_topology/fixtures/clean/plan/orders/E001.yaml": "94797b2afa85962a16673a92d15bf4796fd00cf2223c9d4106e06ba28c89599e",
+    "detectors/atdd_topology/fixtures/clean/plan/orders/_orders.yaml": "33f0f30b31e3fb1bedf1ba8d2071dc7cea02749b48d18196038c9d2321aaf628",
+    "detectors/atdd_topology/fixtures/clean/plan/orders/place-order.yaml": "cccbad80a40da7bbb52c475fe73f5cd6e523994b428dc133aefc37225b04a80c",
+    "detectors/atdd_topology/fixtures/clean/tests/wagons/orders/features/place-order/unit/order.test.ts": "01a9a560d3d977346e39b88a88e7112d9f47f02e8dc8d995ba5fb45f77842153",
+    "detectors/atdd_topology/fixtures/dirty/plan/_journeys/checkout.yaml": "407eeb607a94b08d3d48da6b28b6c6102ffe2f5d11a58b9557a3f3a4d1dda1bd",
+    "detectors/atdd_topology/fixtures/dirty/plan/orders/E001.yaml": "c3e3fc4784a034a4af8fd5babb6cfae39047e58131d204f76ad838a199ba92f9",
+    "detectors/atdd_topology/fixtures/dirty/plan/orders/_orders.yaml": "1d533ed773dd1a6317dfd24abf6aeddd13469321bd07ae60743ee9af58b6531a",
+    "detectors/atdd_topology/fixtures/dirty/plan/orders/features/place-order.yaml": "cccbad80a40da7bbb52c475fe73f5cd6e523994b428dc133aefc37225b04a80c",
+    "detectors/atdd_topology/fixtures/dirty/src/wagons/orders/features/place-order/domain/forged.ts": "313bff608d93a1a6790932e21d17b4582160df3b4f04642f1cbb04a67fc2131d",
+    "detectors/atdd_topology/fixtures/dirty/src/wagons/orders/features/place-order/domain/order.ts": "6fdaad52671ef25b47d93f9b4e97e12c62eb78f5b4cde727435c3ac135a1c0e5",
+    "detectors/atdd_topology/fixtures/dirty/tests/wagons/orders/features/place-order/unit/order.test.ts": "f117e6c8b034700e1f00889bea48cb1528f0003d699cfd3e279cd9164b264a38",
     "detectors/atdd_traceability_closure/atdd.implementation.yaml": "82e56cc85539476e42fc8d58e718bc998f1eff6c325a0cd240c0284625834d68",
-    "detectors/atdd_traceability_closure/detect.mjs": "e83fa23070fcbe91ee88aa37b965129575fa0f8472eba169491ec737ab4045ec",
+    "detectors/atdd_traceability_closure/detect.mjs": "b8c454d7e136cdcc82524fea407490eefc8c2b8c9448831d94d51253f00a38a9",
     "detectors/atdd_traceability_closure/fixtures/clean/plan/orders/E001.yaml": "0ddad928dde10c2ab690558259a6975125af540a1f30eca9aa0c615bf0ad69fb",
     "detectors/atdd_traceability_closure/fixtures/clean/src/order.ts": "efe6db7e3f723c7b6096abdf58dec9c88b27ec8978d434a10135b3e77bfce321",
     "detectors/atdd_traceability_closure/fixtures/clean/test/order.test.ts": "bee451198d472749616f85c1f1e97c0a06ad28255b9a6a2cc8701bd2e8d56562",
@@ -268,8 +288,8 @@
     "detectors/bun_green_traceability_detector/fixtures/dirty/green_urn_wagon_feature/OrderRow.ts": "eed3e99b3a582a41e7179228ca8c33987fdf0ca1c06d78710951057a2355d902",
     "detectors/bun_green_traceability_detector/urn_header.mjs": "004b0ed1f71ec476fb57a959d302da4b5869ff91be049865a806bedca40f55b9",
     "detectors/bun_interlocking_binding/atdd.implementation.yaml": "8df233a7c337d38ab4fc92a309273b91fe713b27507a4b2cfa66ffc7a948d520",
-    "detectors/bun_interlocking_binding/checks/interlocking_runtime_executes.mjs": "68414ad43c70fae78f703344c98b9d163ddfb078ffa09c268764fc0adb295877",
-    "detectors/bun_interlocking_binding/detect.mjs": "ca7f35d5ffdc28056c602a178020eba4f7a165d6b65faaecb5e86492320ca724",
+    "detectors/bun_interlocking_binding/checks/interlocking_runtime_executes.mjs": "ea4c32914a007962012e9062cc64063fa939ff0a59c07960c34872d058720955",
+    "detectors/bun_interlocking_binding/detect.mjs": "42767b7d329b5b2623de37f450c416fe6feb4a7ae737201376e93aa74d493dea",
     "detectors/bun_interlocking_binding/fixtures/clean/e2e/interlockings/match-resolution/trace.test.ts": "5dadc041ca9825f404340ca428e14bbff5e00824ca6c25464f21cd2ce56044d8",
     "detectors/bun_interlocking_binding/fixtures/clean/plan/_trains/_interlockings/match-resolution.yaml": "11884309beb9bcceccfeda7917ea73d51a530366db5eb60772b03cf5eeb239cd",
     "detectors/bun_interlocking_binding/fixtures/clean/plan/_trains/train:match:match-resolution-standard.yaml": "a7067661a723e02e0e844e6b90ad187f620dd328e1b9be45163c04db1919ce77",
@@ -319,14 +339,14 @@
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/server.ts": "d5bc34c5b1b2b0a511e0c4604ce6f9c77491dca9aee994be720540f3052babc1",
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/src/trains/interlocking.ts": "9bcfdb4ecff6efd1f658b9fd587342615179924e25468c75daa07c2626d4d8ab",
     "detectors/bun_interlocking_binding/fixtures/dirty_transcribed_runtime/src/trains/runner.ts": "0e4b885e50f12cc2a8c8f6740bf83e7b2e7137a28e1e143586e9a8550ea5bd45",
-    "detectors/bun_interlocking_coverage/_shared/interlocking.mjs": "5586a9e2f0f1a253ed2e9555784113e130eaed3db80bffa492cb63a1d7802602",
+    "detectors/bun_interlocking_coverage/_shared/interlocking.mjs": "dd484cec27919f342aa5a3ba631cf197acab4f359e7fe0ffd1123f968954fc52",
     "detectors/bun_interlocking_coverage/atdd.implementation.yaml": "f160517a8138ba3ca05e3d130e6fbfb796e643376f25743fdef4fc210196525b",
     "detectors/bun_interlocking_coverage/checks/_map.json": "0a218ea319cc6258af7bd721c2154cb9561fe67e80d80ef32d08fc77bc9403c3",
     "detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs": "136eb0955052f2485740adfb888f5ba6f1414dcdb53d505034b8db40420a611a",
     "detectors/bun_interlocking_coverage/checks/interlocking_route_coverage.mjs": "55716c706818d3f724cdd5f1f16a67b92dacdc4bb4a2d23a037039ddd869acea",
     "detectors/bun_interlocking_coverage/checks/interlocking_smoke_coverage.mjs": "ea4b0155c4f151a36979d850aa2482901b37eacc0fe01cecc0a736089a3e15ce",
     "detectors/bun_interlocking_coverage/checks/interlocking_trace_binds.mjs": "61dcb8a8d04e9764aab7920f346bd3684fc98e2c294aa5c58eefec555145a1d0",
-    "detectors/bun_interlocking_coverage/checks/interlocking_train_sequence.mjs": "f64b331a3dc6f8d5c8519049ba18cc2e4f84e26c1e9471b468aba4e4a39b6c35",
+    "detectors/bun_interlocking_coverage/checks/interlocking_train_sequence.mjs": "ab00524af6cce2a95c3a1232f2e6304c761533c2ac3f42d34683b2c0dc5f9c6a",
     "detectors/bun_interlocking_coverage/detect.mjs": "a124418dc29aaf8fda9cd09427230d25768206b3f563d516774667e8cf75b66e",
     "detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/e2e/interlockings/match-resolution/routes.test.ts": "ba6ea85b3fbe15e3c49332da3ad2921a0ff3436a6fe3b5a5035fb35fdc874720",
     "detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/e2e/interlockings/match-resolution/trace.test.ts": "aee4ea93ceb8636846344e915cd7e66f7e8f99ba08596f83266590fa2b9ff58e",
@@ -367,7 +387,7 @@
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_train_sequence/plan/_trains/_interlockings/match-resolution.yaml": "9e0f02cb0889826f2ac2fb88cd8c118c97d4321dcc5fccc0b767a511606841e6",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_train_sequence/plan/_trains/train:match:match-resolution-standard.yaml": "9ea90f674e5fc565d8893e74ad2e47f273c971ca29284dbce58a366a3e832428",
     "detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_train_sequence/plan/_trains/train:match:match-resolution-timeout.yaml": "aa1b7682f99f3a9a25ec0d3d03f3798ddda8c74eb728e148b38197ddab292493",
-    "detectors/bun_interlocking_infrastructure/_shared/interlocking.mjs": "02b4ad53d52eece9fa892eff3a048ed0ccd991427f61fd64570659ff97c4739f",
+    "detectors/bun_interlocking_infrastructure/_shared/interlocking.mjs": "433977b3b8242c0f061924c53e9f7488cd5cc7368edacbe007c14d749cc805f4",
     "detectors/bun_interlocking_infrastructure/atdd.implementation.yaml": "fa7a1de97b19dff6515100131a3b6fc2dacf2766cd2bd44bc9dd792f6b01590d",
     "detectors/bun_interlocking_infrastructure/checks/_map.json": "5f86408f98de8f1562e679e2bd3a2194a8eb297fecf677ca774f19905942ec71",
     "detectors/bun_interlocking_infrastructure/checks/interlocking_delegates.mjs": "1aa4c87e234643e99ba5a2ff1fab3db8bfc7cbc9618c8e1a014eef2c11cce9c7",
@@ -375,9 +395,9 @@
     "detectors/bun_interlocking_infrastructure/checks/interlocking_resolution_model.mjs": "e761495b19eed0af09fcb4db34126d0e2398e91f086e04f5ef84d0b5c1c3ec16",
     "detectors/bun_interlocking_infrastructure/checks/interlocking_runner_exists.mjs": "6b63d3f26a51f2dd27847edd27c4d9c9f15c1f02747dba611cebccfc76f13169",
     "detectors/bun_interlocking_infrastructure/checks/interlocking_station_routing.mjs": "0221f5a8b49763388affefff670bc2a452e539e7658b08f6230a52f13edd36bd",
-    "detectors/bun_interlocking_infrastructure/checks/journey_runner_boundary.mjs": "336d56f0dd3c0c7f3769a3f41689003e43de51066dbc25e364915fdf50e859bd",
-    "detectors/bun_interlocking_infrastructure/checks/journey_station_routing.mjs": "018d28eed330b85b0699435158face40a31e0e94d63ae3c4df05cb87400fa152",
-    "detectors/bun_interlocking_infrastructure/checks/wagon_contract_honoured.mjs": "88f8cf80e526beaa829860f78d1b1578aaf47e2a3fc680e60a957aa91cc0217d",
+    "detectors/bun_interlocking_infrastructure/checks/journey_runner_boundary.mjs": "8c7225f5ee387cbf7ba1e536f91c67c331a86025b4b2b38b961488d949cbdb21",
+    "detectors/bun_interlocking_infrastructure/checks/journey_station_routing.mjs": "b297f3f677e0239c5d14cf36218fc39ec23024a0f29620dd02945601aad20516",
+    "detectors/bun_interlocking_infrastructure/checks/wagon_contract_honoured.mjs": "728f710827295472dadec182fcdf6c3e8fc44cdedeae53a669754be8435fdd7f",
     "detectors/bun_interlocking_infrastructure/detect.mjs": "54c02f428596e057f828def0d68360b220b55dbf962b46694a21bc423ce57218",
     "detectors/bun_interlocking_infrastructure/fixtures/clean/interlocking_delegates/server.ts": "36913357fdd3c5e375829a0554c605d70f5c05e2e83349f47505741598f6eb15",
     "detectors/bun_interlocking_infrastructure/fixtures/clean/interlocking_delegates/src/match/wagon.ts": "ea202fa15fdf9d1391b1ae23343c9d1b09fcf8ef14f1dccfb8114ffaedea97c1",
@@ -476,7 +496,7 @@
     "detectors/bun_tester_discipline_detector/checks/_map.json": "d28273b975c4fbcda64026178b918dc9a84315d6312f29ae5221a0a9cb4c0b44",
     "detectors/bun_tester_discipline_detector/checks/t_acceptance_binding.mjs": "17861380275433ff79e191803456417454e2efa23801d9ac72bf6f8206337522",
     "detectors/bun_tester_discipline_detector/checks/t_acceptance_covers_tag.mjs": "2116c9936cb5863df643b968dece23c29e145ede30cf7c7862e5c17ac7beb6dd",
-    "detectors/bun_tester_discipline_detector/checks/t_acceptance_resolves.mjs": "4fb51a28fd2e546cbe551dbe997ad29d8d2eb07451491d0220bb8e559514e96b",
+    "detectors/bun_tester_discipline_detector/checks/t_acceptance_resolves.mjs": "fe7047cc069be0d8ad85ebb701916a30eca667483d34bc75d4b95baf3b26c168",
     "detectors/bun_tester_discipline_detector/checks/t_isolation_no_live_state.mjs": "de2c396b83bc2e5317f6b8eee31c98103e7360d1cd25e7c1c53db6ff7627203f",
     "detectors/bun_tester_discipline_detector/checks/t_red_behavioral.mjs": "ac0b77bbf10a08d991272fbce41db2a34187c8f5faf1e04c5b1a858ecfbcc4ef",
     "detectors/bun_tester_discipline_detector/checks/t_red_fails_first.mjs": "06cb66f5ccf7d59e1d21f6d3a9db29ca7f3182c096b17ddb50b85b319b97208b",
@@ -1050,17 +1070,18 @@
     "src/ci.ts": "899125ec76d14f7d0126a5db2249913e373e3a325cbc98d7f053e1351bdf47af",
     "src/cli.ts": "bb2047cee60f48bfe3eaee4c1b3dcd3538a0e1edc170cf58e87686117bea07a7",
     "src/docs-capability.ts": "65ef91658664b41b78184b395e57e5d28bda16128caa9e314f26e63568abc6cd",
-    "src/enforce.ts": "828aa0ba0422e565fb99908d70ed1769f606dcfacee63900c9602e57471172c3",
-    "src/hooks.ts": "88f78d9aa7b8182a3d7080cb94dab2a17a934c7437b5dd861dd428694908e72c",
-    "src/index.ts": "67ea1a791b3a625882d3ff6b981092f3764b694e660194736ecf53dac0890563",
+    "src/enforce.ts": "43ef276e1c4465ec32e5a431d9a5b1825c6168180e695280fd6d208fd583bac9",
+    "src/hooks.ts": "54d70d7d6923f1e39b259e3b9f377c43609aecdc64ff4d1232da595950d7b1aa",
+    "src/index.ts": "2743b7969526d0aaf21179048e9896141e97d89c45c4a503b795f41fed57f6cc",
     "src/integrity.ts": "48d7adce486ece1885a95aac6867d286bb972d7a97bdbc32222fd6d75c2e2b49",
     "src/journey-docs.ts": "994d229376244c84212cff951032823068a76565dd2fd427b9d44e341bd14853",
-    "src/planner-kernel.ts": "b201fe5a76e5298a3a3fcd11adbf0f47bfd8a565246c84d23db5d4d7bf0a3356",
-    "src/planner-schema-validator.ts": "881ee4eb39db13471684854f9d1a667a5ef4451b104af2f6574ff0c237922217",
-    "src/planner-validators.ts": "882c12c7ce4f8bf98eda71cd33c23ac8c224c28703e10ebef63288c1017757d5",
+    "src/planner-kernel.ts": "87ffbabc60d7868df52e6e060fcb36b41e90c9d6a47fa9a99f16aa263d61a528",
+    "src/planner-schema-validator.ts": "ce529c0936171075e93c7539b3655fe895a98dd2973ebda5775958e6ebc316d9",
+    "src/planner-validators.ts": "99adeb65f579af923c11f21a8f55cfb9993b007fd8df59c5f764696b55379cfc",
     "src/register.ts": "6a2f1c6b8df0dc9c8f45df8ec9fac2be29044e048b08c8ffe423410e94dadedd",
     "src/release.ts": "7b0fe444ee81f476f53b9c21b6c347ef588ee616c60211419cf984132be768ba",
     "src/setup.ts": "0a6f1a9aeff31dcf17f6bd036168b909c1841c11bbbb452105d8debf64a6bc78",
+    "src/topology.ts": "ff86fc7923793c727196e6f8459db4f071fcaa6844268c2e3b232bb18801c43d",
     "templates/agents/AGENTS.block.md": "bfd8769bc42b8c4c91a70777e056624e37acb1037c7fd1497fcb59f007567336",
     "templates/agents/atdd-bun.integrity.test.ts": "dec6f6e5f65a08d9512fc703b367c163f8c9da1f6aa7fd466835c1ec30348a41",
     "templates/agents/atdd/SKILL.md": "b621abe22851a75b30fc0e6c339a2c0a3ed6bbf78b8c17000a4ce301e05df96d",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/enforce.ts

@@ -1,8 +1,9 @@
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { topologyFor } from "./topology";
 
-export type Profile = "traceability" | "docs" | "planner" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "design" | "all";
+export type Profile = "traceability" | "topology" | "docs" | "planner" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "design" | "all";
 
 export type Violation = {
   rule_id: string;
@@ -22,10 +23,11 @@ export type EnforcementConfig = {
 
 const profiles: Record<Exclude<Profile, "all">, string[]> = {
   traceability: ["atdd_traceability_closure"],
+  topology: ["atdd_topology"],
   docs: ["planner_docs_capability"],
-  planner: ["planner_plan_integrity", "planner_schema_validation", "planner_static_validators"],
-  coder: ["bun_green_traceability_detector", "bun_clean_architecture_detector", "bun_ts_metrics_detector", "bun_fullstack_detector", "bun_design_system_detector", "bun_responsive_detector"],
-  tester: ["bun_tester_discipline_detector", "htmx_e2e_detector"],
+  planner: ["planner_plan_integrity", "planner_schema_validation", "planner_static_validators", "atdd_topology"],
+  coder: ["bun_green_traceability_detector", "bun_clean_architecture_detector", "bun_ts_metrics_detector", "bun_fullstack_detector", "bun_design_system_detector", "bun_responsive_detector", "atdd_topology"],
+  tester: ["bun_tester_discipline_detector", "htmx_e2e_detector", "atdd_topology"],
   security: ["bun_security_hygiene_detector"],
   architecture: ["bun_clean_architecture_detector"],
   metrics: ["bun_ts_metrics_detector"],
@@ -63,7 +65,7 @@ export async function runImplementation(
   const scratch = await mkdtemp(join(tmpdir(), "atdd-bun-"));
   const report = join(scratch, "violations.json");
   try {
-    const bun = Bun.which("bun") ?? process.execPath;
+    const bun = Bun.which("bun") ?? process.execPath, topology = await topologyFor(config.scanRoots[0] ?? process.cwd());
     const child = Bun.spawn({
       cmd: [bun, detector],
       cwd: config.scanRoots[0] ?? process.cwd(),
@@ -73,6 +75,7 @@ export async function runImplementation(
         ...process.env,
         ATDD_SCAN_ROOTS: JSON.stringify(config.scanRoots),
         ATDD_SCAN_EXCLUDES: JSON.stringify(config.excludes),
+        ATDD_PLAN_ROOT: topology.planRoot,
         ATDD_VIOLATIONS_REPORT: report,
       },
     });

package/src/hooks.ts

@@ -2,6 +2,7 @@ import { chmod, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:f
 import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { enforce } from "./enforce";
+import { topologyFor } from "./topology";
 
 export type WorktreePolicy = { enabled: boolean; root: string; primary_directory: string; primary_branch: string; require_linked_worktree: boolean };
 export type HookPolicy = { max_staged_files: number; max_staged_changed_lines: number; max_uncommitted_files: number; max_commits_per_push: number; max_registry_removed_lines: number; registry_paths: string[]; protected_branches: string[]; require_plan_reference: boolean; require_traceability: boolean; worktrees: WorktreePolicy };
@@ -18,7 +19,7 @@ const isRegistry = (cfg: HookPolicy, path: string) => cfg.registry_paths.some(pa
 const stagedStats = async (root: string) => (await git(root, ["diff", "--cached", "--numstat", "--no-renames"])).out.split("\n").filter(Boolean).map(row => { const [added, removed, ...path] = row.split("\t"); return { added: Number(added) || 0, removed: Number(removed) || 0, path: path.join("\t") }; });
 
 export async function policy(root: string): Promise<HookPolicy> { const file = join(root, "atdd-bun.yaml"); if (!existsSync(file)) return defaultHookPolicy; const data = Bun.YAML.parse(await readFile(file, "utf8")) as Record<string, unknown>; const configuredWorktrees = data?.worktrees && typeof data.worktrees === "object" && !Array.isArray(data.worktrees) ? data.worktrees as Record<string, unknown> : {}; return { ...defaultHookPolicy, ...Object.fromEntries(Object.entries(data ?? {}).filter(([key, value]) => key in defaultHookPolicy && key !== "worktrees" && typeof value === typeof (defaultHookPolicy as any)[key])), protected_branches: strings(data?.protected_branches) ?? defaultHookPolicy.protected_branches, registry_paths: strings(data?.registry_paths) ?? defaultHookPolicy.registry_paths, worktrees: { ...defaultWorktreePolicy, ...Object.fromEntries(Object.entries(configuredWorktrees).filter(([key, value]) => key in defaultWorktreePolicy && typeof value === typeof (defaultWorktreePolicy as any)[key])) } }; }
-async function validation(root: string, changed: string[], full: boolean, registryChanged = false) { const profiles: any[] = []; if (registryChanged || changed.some(path => path.startsWith("plan/"))) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const findings = await enforce({ root, profiles: full ? ["all"] : [...new Set(profiles)] }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
+async function validation(root: string, changed: string[], full: boolean, registryChanged = false) { const profiles: any[] = [], topology = await topologyFor(root); if (registryChanged || changed.some(path => path.startsWith(`${topology.planRoot}/`)) || changed.includes("atdd-bun.yaml")) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (changed.includes("atdd-bun.yaml") || changed.some(path => /\.ya?ml$/.test(path))) profiles.push("topology"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const findings = await enforce({ root, profiles: full ? ["all"] : [...new Set(profiles)] }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
 
 const inside = (parent: string, child: string) => { const path = relative(parent, child); return path === "" || (path !== ".." && !path.startsWith("../") && !path.startsWith("..\\")); };
 async function primaryRoot(root: string): Promise<string | null> { const result = await git(root, ["rev-parse", "--git-common-dir"]); if (result.code) return null; return dirname(resolve(root, result.out)); }

package/src/index.ts

@@ -15,3 +15,5 @@ export type { Gap, Journey, JourneyModel, JourneyPath } from "./journey-docs";
 export { checkIntegrity, checkInstalledPackage, formatIntegrity, integrityInit, loosenedPolicy, writeManifest } from "./integrity";
 export type { IntegrityFinding, IntegrityOptions } from "./integrity";
 export { releaseCheck } from "./release";
+export { defaultTopology, topologyFor } from "./topology";
+export type { Topology } from "./topology";

package/src/planner-kernel.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { topologyFor } from "./topology";
 
 export type PlanKind = "wagon" | "feature" | "wmbt" | "acceptance" | "train" | "interlocking" | "journey" | "contract";
 export type PlanFinding = { rule_id: string; file: string; evidence: string };
@@ -65,7 +66,7 @@ function structuralRefs(artifact: PlanArtifact): string[] {
 /** Load plan artifacts with Bun's native YAML parser. It is read-only and deliberately
  * excludes authoring/session/store behavior from ATDD core. */
 export async function loadPlan(root = process.cwd()): Promise<PlanGraph> {
-  const absolute = resolve(root), plan = join(absolute, "plan"), artifacts: PlanArtifact[] = [], findings: PlanFinding[] = [];
+  const absolute = resolve(root), topology = await topologyFor(absolute), plan = join(absolute, topology.planRoot), artifacts: PlanArtifact[] = [], findings: PlanFinding[] = [];
   for (const path of await walk(plan)) {
     const file = relative(absolute, path).replaceAll("\\", "/");
     try {

package/src/planner-schema-validator.ts

@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { loadPlan, type PlanArtifact, type PlanFinding } from "./planner-kernel";
+import { topologyFor } from "./topology";
 
 type SchemaKind = Extract<PlanArtifact["kind"], "wagon" | "feature" | "wmbt" | "train" | "interlocking" | "journey">;
 
@@ -16,10 +17,11 @@ const schemaFiles: Record<SchemaKind, string> = {
   journey: "journey.schema.json",
 };
 const supportingSchemaFiles = ["appendix.schema.json", "acceptance.schema.json"];
-const repositorySchemas = [
-  { file: "plan/_themes.yaml", schema: "theme-registry.schema.json", rule: "planner.theme.must-be-canonical" },
+const repositorySchemas = (planRoot: string) => [
+  { file: `${planRoot}/_themes.yaml`, schema: "theme-registry.schema.json", rule: "planner.theme.must-be-canonical" },
   { file: "contracts/_contracts.yaml", schema: "contract-registry.schema.json", rule: "planner.contract.registry-coherence" },
 ] as const;
+const repositorySchemaFiles = ["theme-registry.schema.json", "contract-registry.schema.json"];
 const schemaDirectory = join(resolve(import.meta.dir, ".."), "planner-schemas");
 const ruleId = "atdd-bun.planner.schema";
 
@@ -39,23 +41,23 @@ function formatError(error: ErrorObject): string {
 async function validators(): Promise<{ artifacts: Map<SchemaKind, ValidateFunction>; repositories: Map<string, ValidateFunction> }> {
   const ajv = new Ajv({ allErrors: true, allowUnionTypes: true, strict: false });
   addFormats(ajv);
-  const files = [...supportingSchemaFiles, ...Object.values(schemaFiles), ...repositorySchemas.map(item => item.schema)];
+  const files = [...supportingSchemaFiles, ...Object.values(schemaFiles), ...repositorySchemaFiles];
   for (const file of files) ajv.addSchema(JSON.parse(await readFile(join(schemaDirectory, file), "utf8")), file);
   const artifacts = new Map(Object.entries(schemaFiles).map(([kind, file]) => {
     const validator = ajv.getSchema(file);
     if (!validator) throw new Error("could not compile planner schema " + file);
     return [kind as SchemaKind, validator];
   }));
-  const repositories = new Map(repositorySchemas.map(item => {
-    const validator = ajv.getSchema(item.schema);
-    if (!validator) throw new Error("could not compile planner schema " + item.schema);
-    return [item.schema, validator];
+  const repositories = new Map(repositorySchemaFiles.map(schema => {
+    const validator = ajv.getSchema(schema);
+    if (!validator) throw new Error("could not compile planner schema " + schema);
+    return [schema, validator];
   }));
   return { artifacts, repositories };
 }
 
 function repositoryRule(file: string, fallback: string, error: ErrorObject): string {
-  if (file === "plan/_themes.yaml" && (error.instancePath === "/themes" || error.instancePath === "/themes/0" || error.params.missingProperty === "0")) {
+  if (file.endsWith("/_themes.yaml") && (error.instancePath === "/themes" || error.instancePath === "/themes/0" || error.params.missingProperty === "0")) {
     return "planner.theme.theme-zero-mandatory";
   }
   return fallback;
@@ -64,7 +66,7 @@ function repositoryRule(file: string, fallback: string, error: ErrorObject): str
 /** Validate every recognized plan artifact against the package-shipped canonical
  * JSON Schema. Cross-artifact relationships remain planner validator concerns. */
 export async function validatePlannerSchemas(root = process.cwd()): Promise<PlanFinding[]> {
-  const absolute = resolve(root), graph = await loadPlan(absolute);
+  const absolute = resolve(root), topology = await topologyFor(absolute), graph = await loadPlan(absolute), repositories = repositorySchemas(topology.planRoot);
   const byKind = await validators();
   const findings: PlanFinding[] = [];
   for (const artifact of graph.artifacts) {
@@ -79,7 +81,7 @@ export async function validatePlannerSchemas(root = process.cwd()): Promise<Plan
       });
     }
   }
-  for (const item of repositorySchemas) {
+  for (const item of repositories) {
     const path = join(absolute, item.file);
     if (!existsSync(path)) continue;
     try {

package/src/planner-validators.ts

@@ -2,6 +2,7 @@ import { validatePlan, type PlanArtifact, type PlanFinding } from "./planner-ker
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { topologyFor } from "./topology";
 
 const finding = (rule_id: string, file: string, evidence: string): PlanFinding => ({ rule_id, file, evidence });
 const records = (value: unknown): Record<string, unknown>[] => Array.isArray(value) ? value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object") : [];
@@ -16,13 +17,13 @@ async function yamlFiles(root: string): Promise<string[]> {
 }
 
 async function trainRegistryFindings(root: string): Promise<PlanFinding[]> {
-  const absolute = resolve(root), registryPath = join(absolute, "plan/_trains.yaml"); if (!existsSync(registryPath)) return [];
+  const absolute = resolve(root), topology = await topologyFor(absolute), file = `${topology.planRoot}/_trains.yaml`, registryPath = join(absolute, file); if (!existsSync(registryPath)) return [];
   const registry = Bun.YAML.parse(await readFile(registryPath, "utf8")) as { trains?: Record<string, Record<string, unknown[]>> };
   const rows = Object.values(registry?.trains ?? {}).flatMap(buckets => Object.values(buckets ?? {}).flat()).filter((row): row is Record<string, unknown> => Boolean(row) && typeof row === "object");
   const registered = new Set<string>(), findings: PlanFinding[] = [];
-  for (const row of rows) { const path = text(row.path), train = text(row.train_id); if (!path || !train) continue; registered.add(path); if (!existsSync(join(absolute, path))) findings.push(finding("planner.train.registry-coherence", "plan/_trains.yaml", `registry train ${train} points to missing ${path}`)); }
-  const trainRoot = join(absolute, "plan/_trains");
-  for (const path of await yamlFiles(trainRoot)) { const rel = relative(absolute, path).replaceAll("\\", "/"), pieces = relative(trainRoot, path).split(/[\\/]/); if (pieces.some(piece => piece.startsWith("_")) || registered.has(rel)) continue; findings.push(finding("planner.train.registry-coherence", rel, `train document is not registered in plan/_trains.yaml`)); }
+  for (const row of rows) { const path = text(row.path), train = text(row.train_id); if (!path || !train) continue; registered.add(path); if (!existsSync(join(absolute, path))) findings.push(finding("planner.train.registry-coherence", file, `registry train ${train} points to missing ${path}`)); }
+  const trainRoot = join(absolute, topology.planRoot, "_trains");
+  for (const path of await yamlFiles(trainRoot)) { const rel = relative(absolute, path).replaceAll("\\", "/"), pieces = relative(trainRoot, path).split(/[\\/]/); if (pieces.some(piece => piece.startsWith("_")) || registered.has(rel)) continue; findings.push(finding("planner.train.registry-coherence", rel, `train document is not registered in ${file}`)); }
   return findings;
 }
 
@@ -44,7 +45,7 @@ async function contractRegistry(root: string): Promise<ContractRegistry | null>
 }
 
 async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typeof validatePlan>>, registry: ContractRegistry | null): Promise<PlanFinding[]> {
-  const absolute = resolve(root), file = "plan/_themes.yaml", path = join(absolute, file);
+  const absolute = resolve(root), topology = await topologyFor(absolute), file = `${topology.planRoot}/_themes.yaml`, path = join(absolute, file);
   const declared: Array<{ theme: string; file: string }> = [];
   for (const artifact of graph.artifacts) {
     if (artifact.kind === "wagon" || artifact.kind === "interlocking") {
@@ -54,7 +55,7 @@ async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typ
     }
   }
   for (const row of registry?.rows ?? []) { const theme = text(row.theme); if (theme) declared.push({ theme, file: registry?.file ?? file }); }
-  if (!existsSync(path)) return declared.length ? [finding("planner.theme.must-be-canonical", file, "themes are declared but plan/_themes.yaml is absent; add themes: { '0': commons } and repository-defined entries")] : [];
+  if (!existsSync(path)) return declared.length ? [finding("planner.theme.must-be-canonical", file, `themes are declared but ${file} is absent; add themes: { '0': commons } and repository-defined entries`)] : [];
   try {
     const doc = Bun.YAML.parse(await readFile(path, "utf8")) as { themes?: unknown };
     const themes = doc?.themes && typeof doc.themes === "object" && !Array.isArray(doc.themes) ? doc.themes as Record<string, unknown> : {};
@@ -63,7 +64,7 @@ async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typ
     if (themes["0"] !== "commons") findings.push(finding("planner.theme.theme-zero-mandatory", file, "theme index 0 must be the reserved token commons"));
     for (const name of duplicate(values)) findings.push(finding("planner.theme.must-be-canonical", file, `theme ${name} is declared at more than one index`));
     const known = new Set(values);
-    for (const item of declared) if (!known.has(item.theme)) findings.push(finding("planner.theme.must-be-canonical", item.file, `theme ${item.theme} is not declared in plan/_themes.yaml`));
+    for (const item of declared) if (!known.has(item.theme)) findings.push(finding("planner.theme.must-be-canonical", item.file, `theme ${item.theme} is not declared in ${file}`));
     for (const artifact of graph.artifacts.filter(item => item.kind === "wagon")) {
       const wagonTheme = text(artifact.data.theme);
       for (const produced of records(artifact.data.produce)) {
@@ -82,7 +83,7 @@ async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typ
     }
     return findings;
   } catch {
-    return [finding("planner.theme.must-be-canonical", file, "could not parse plan/_themes.yaml")];
+    return [finding("planner.theme.must-be-canonical", file, `could not parse ${file}`)];
   }
 }
 
@@ -247,7 +248,7 @@ function journeyContinuationFindings(graph: Awaited<ReturnType<typeof validatePl
 }
 
 /** Every interlocking is reached by a journey: as an entrypoint or through a continuation reachable from one. */
-function journeyCompositionFindings(graph: Awaited<ReturnType<typeof validatePlan>>): PlanFinding[] {
+function journeyCompositionFindings(graph: Awaited<ReturnType<typeof validatePlan>>, planRoot: string): PlanFinding[] {
   const interlockings = graph.artifacts.filter(item => item.kind === "interlocking"), journeys = graph.artifacts.filter(item => item.kind === "journey");
   const reached = new Set<string>();
   for (const journey of journeys) {
@@ -270,7 +271,7 @@ function journeyCompositionFindings(graph: Awaited<ReturnType<typeof validatePla
     interlocking.file,
     journeys.length
       ? `${interlocking.id} is reached by none of the ${journeys.length} journey(s): no journey enters at it and no reachable continuation leads to it`
-      : `${interlocking.id} is not composed into any journey: the plan declares ${interlockings.length} interlocking(s) and no journey under plan/_journeys/`,
+      : `${interlocking.id} is not composed into any journey: the plan declares ${interlockings.length} interlocking(s) and no journey under ${planRoot}/_journeys/`,
   ));
 }
 
@@ -280,11 +281,11 @@ export async function validateStaticPlannerConventions(root = process.cwd()): Pr
   // Plan-graph integrity is a package guard with its own implementation contract.
   // This validator emits only the canonical convention ids declared by
   // planner.static.validators.bun.
-  const graph = await validatePlan(root), findings: PlanFinding[] = [], wagons = graph.artifacts.filter(artifact => artifact.kind === "wagon");
+  const topology = await topologyFor(root), graph = await validatePlan(root), findings: PlanFinding[] = [], wagons = graph.artifacts.filter(artifact => artifact.kind === "wagon");
   const wagonSlugs = new Set(wagons.map(wagon => text(wagon.data.wagon)));
   const wagonBySlug = new Map(wagons.map(wagon => [text(wagon.data.wagon), wagon]));
   const wagonIds = wagons.map(wagon => text(wagon.data.wagon));
-  for (const slug of duplicate(wagonIds)) findings.push(finding("planner.wagon.urn", wagonBySlug.get(slug)?.file ?? "plan/", `wagon slug ${slug} is declared more than once`));
+  for (const slug of duplicate(wagonIds)) findings.push(finding("planner.wagon.urn", wagonBySlug.get(slug)?.file ?? `${topology.planRoot}/`, `wagon slug ${slug} is declared more than once`));
 
   const contractOwners = new Map<string, string[]>(), telemetryOwners = new Map<string, string[]>();
   for (const wagon of wagons) {
@@ -305,13 +306,13 @@ export async function validateStaticPlannerConventions(root = process.cwd()): Pr
     }
   }
   const registry = await contractRegistry(root);
-  for (const [contract, owners] of contractOwners) if (owners.length > 1) findings.push(finding("planner.contract.registry-coherence", wagonBySlug.get(owners[0])?.file ?? "plan/", `contract ${contract} is produced by ${owners.join(", ")}`));
-  for (const [telemetry, owners] of telemetryOwners) if (owners.length > 1) findings.push(finding("planner.wagon.telemetry-filesystem", wagonBySlug.get(owners[0])?.file ?? "plan/", `telemetry ${telemetry} is produced by ${owners.join(", ")}`));
+  for (const [contract, owners] of contractOwners) if (owners.length > 1) findings.push(finding("planner.contract.registry-coherence", wagonBySlug.get(owners[0])?.file ?? `${topology.planRoot}/`, `contract ${contract} is produced by ${owners.join(", ")}`));
+  for (const [telemetry, owners] of telemetryOwners) if (owners.length > 1) findings.push(finding("planner.wagon.telemetry-filesystem", wagonBySlug.get(owners[0])?.file ?? `${topology.planRoot}/`, `telemetry ${telemetry} is produced by ${owners.join(", ")}`));
   findings.push(...contractRegistryFindings(root, wagons, registry));
   findings.push(...await themeRegistryFindings(root, graph, registry));
   findings.push(...await trainRegistryFindings(root));
   findings.push(...journeyContinuationFindings(graph));
-  findings.push(...journeyCompositionFindings(graph));
+  findings.push(...journeyCompositionFindings(graph, topology.planRoot));
 
   return findings;
 }

package/src/topology.ts

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+export type Topology = { planRoot: string; sourceRoot: string; testRoot: string; e2eRoot: string };
+
+export const defaultTopology: Topology = {
+  planRoot: "plan",
+  sourceRoot: "src/wagons",
+  testRoot: "tests/wagons",
+  e2eRoot: "e2e",
+};
+
+const configuredKeys: Array<[keyof Topology, string]> = [
+  ["planRoot", "plan_root"],
+  ["sourceRoot", "source_root"],
+  ["testRoot", "test_root"],
+  ["e2eRoot", "e2e_root"],
+];
+
+function safeRelative(value: unknown): string | null {
+  if (typeof value !== "string" || !value || value.startsWith("/")) return null;
+  const normalized = value.replaceAll("\\", "/").replace(/\/$/, "");
+  return normalized && !normalized.split("/").includes("..") ? normalized : null;
+}
+
+/** Read the one shared topology configuration used by every plan consumer. Invalid
+ * location overrides deliberately fall back to the strict defaults; the topology
+ * detector reports the bad configuration as a violation. */
+export async function topologyFor(root = process.cwd()): Promise<Topology> {
+  const absolute = resolve(root), file = join(absolute, "atdd-bun.yaml");
+  if (!existsSync(file)) return { ...defaultTopology };
+  try {
+    const data = Bun.YAML.parse(await readFile(file, "utf8")) as { topology?: Record<string, unknown> } | null;
+    const supplied = data?.topology && typeof data.topology === "object" && !Array.isArray(data.topology) ? data.topology : {};
+    const topology = { ...defaultTopology };
+    for (const [property, key] of configuredKeys) topology[property] = safeRelative(supplied[key]) ?? topology[property];
+    return topology;
+  } catch { return { ...defaultTopology }; }
+}