@afokapu/atdd-bun 0.5.0 → 0.6.1

package/detectors/atdd_topology/detect.mjs

@@ -0,0 +1,182 @@
+#!/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", "_generated"].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)));
+  // The feature(s) that own each acceptance, through the WMBTs they list: a test is credited only to its owner.
+  const acceptanceOwners = new Map();
+  for (const feature of features) for (const wmbtUrn of list(feature.data, "wmbts").map(String)) for (const wmbt of wmbts.filter(w => w.urn === wmbtUrn))
+    for (const acceptance of list(wmbt.data, "acceptances").map(a => text(a?.identity, "urn")).filter(Boolean)) acceptanceOwners.set(acceptance, [...(acceptanceOwners.get(acceptance) || []), `${feature.wagon}:${feature.slug}`]);
+  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 if (acceptanceOwners.has(binding) && !acceptanceOwners.get(binding).includes(`${wagon}:${feature}`)) add("atdd-bun.topology.test-location", root, path, `${binding} belongs to feature:${acceptanceOwners.get(binding).join(", feature:")}, not feature:${wagon}:${feature}; a test lives beneath the feature whose acceptance it proves`, 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;
+    // A browser spec carries its journey identity as a test URN, not an Acceptance (tester.htmx forbids
+    // Acceptance on journey specs). It substitutes only when that URN is a valid E2E or SMOKE proof for the
+    // very train or journey it is bound to.
+    // The proof is the `// URN:` header, whole: a URN-shaped string elsewhere in the file (a decoy constant) proves nothing.
+    const proves = (subject) => h.urn.value.startsWith(`test:${subject}:`) && /^(E2E|SMOKE)-\d{3}-[a-z0-9][a-z0-9-]*$/.test(h.urn.value.slice(`test:${subject}:`.length));
+    if (h.train.value && proves(h.train.value)) browserTrains.add(h.train.value);
+    if (h.journey.value && proves(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);
+      else if (h.acceptance.value !== `acc:${match[1]}:${match[3]}` || !acceptances.has(h.acceptance.value)) add("atdd-bun.topology.e2e-location", root, path, `journey E2E test requires Acceptance: acc:${match[1]}:${match[3]}, declared by a WMBT in ${cfg.plan_root}/`, h.acceptance.line, h.acceptance.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,5 @@
+// URN: test:orders:place-order:E001-E2E-001
+// Acceptance: acc:orders: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,8 @@
+urn: wmbt:orders:E001
+acceptances:
+  - identity:
+      urn: acc:orders:E001-UNIT-001
+  - identity:
+      urn: acc:orders:E001-E2E-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/detectors/planner_docs_capability/atdd.implementation.yaml

@@ -34,6 +34,13 @@ emits_rule_ids:
   - planner.docs.adr-registry-derived   # disposition: advisory (registry drifted from :decides:)
   - planner.docs.journey-view-current  # disposition: strict (generated journey view differs from plan/)
 
+# Rules the capability API (checkDocumentation) emits and the filesystem report cannot: they need a
+# declaration, a change set, or a render. tests/docs-capability.test.ts triggers each one.
+api_emits_rule_ids:
+  - planner.docs.artifact-path-shape
+  - planner.docs.undeclared-change
+  - planner.docs.reference-integrity
+
 # TWO SURFACES, ONE DETECTOR.
 #
 #   entrypoint  the CAPABILITY seam. Core calls

package/detectors/planner_plan_integrity/atdd.implementation.yaml

@@ -9,6 +9,7 @@ contract_version: "1.0.0"
 # fail closed before convention validators can answer.
 emits_rule_ids:
   - atdd-bun.planner.parse
+  - atdd-bun.planner.identity-required
   - atdd-bun.planner.identity-unique
   - atdd-bun.planner.reference-resolves
   - atdd-bun.planner.train-wagon-resolves

package/detectors/planner_plan_integrity/detect.mjs

@@ -6,6 +6,7 @@ const roots = JSON.parse(process.env.ATDD_SCAN_ROOTS ?? "[]"), report = process.
 if (!report) throw new Error("ATDD_VIOLATIONS_REPORT is required");
 const ids = {
   "planner.kernel.parse": "atdd-bun.planner.parse",
+  "planner.kernel.identity-required": "atdd-bun.planner.identity-required",
   "planner.kernel.identity-unique": "atdd-bun.planner.identity-unique",
   "planner.kernel.reference-resolves": "atdd-bun.planner.reference-resolves",
   "planner.kernel.train-wagon-resolves": "atdd-bun.planner.train-wagon-resolves",
@@ -14,7 +15,9 @@ const ids = {
 };
 const violations = (await Promise.all(roots.map(validatePlan))).flatMap(graph => graph.findings).map(item => ({
   ...item,
-  rule_id: ids[item.rule_id] ?? item.rule_id,
+  // Every kernel finding reports under a declared package rule. An unmapped one is a new emission path:
+  // fail loudly rather than publish a rule id nothing declares (tests/rule-coverage.test.ts maps them all).
+  rule_id: ids[item.rule_id] ?? (() => { throw new Error(`planner_plan_integrity: kernel rule ${item.rule_id} has no declared package rule; map it in detect.mjs`); })(),
   line: 1,
   col: 1,
   source_line: "",