@afokapu/atdd-bun 0.6.0 → 0.6.2

package/conventions/atdd-bun.planner/atdd-bun.planner.identity-required.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.identity-required
+kind: rule
+status: active
+name: Plan artifacts carry their identity
+statement: Every plan artifact whose kind the planner recognizes carries its canonical identity (`train_id`, `interlocking_id`,
+  `journey_id`, or `urn`). Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan artifacts carry their identity.
+  normative_text: An artifact without an identity cannot be referenced, bound, or traced; every rule that resolves
+    references silently skips it.
+  fix_hint: 'Add the identity field for the artifact kind, for example `interlocking_id: interlocking:checkout`.'
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-IDENTITY-REQUIRED
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.identity-unique.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.identity-unique
+kind: rule
+status: active
+name: Plan identities are unique
+statement: No two plan artifacts declare the same identity (`train_id`, `interlocking_id`, `journey_id`, `urn`,
+  …). Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan identities are unique.
+  normative_text: A reference to a duplicated identity resolves to whichever file was read first.
+  fix_hint: Rename one of the artifacts, or merge them.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-IDENTITY-UNIQUE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.interlocking-participant-resolves.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.interlocking-participant-resolves
+kind: rule
+status: active
+name: Interlocking participants resolve
+statement: Every participant and lifeline an interlocking lists is either an external actor (`user:…`, `system:…`)
+  or a typed reference to an artifact the plan declares. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Interlocking participants resolve.
+  normative_text: A routing decision between participants the plan does not declare cannot be traced to anything
+    that implements it.
+  fix_hint: Declare the participant, or correct the lifeline.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-INTERLOCKING-PARTICIPANT-RESOLVES
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.parse.convention.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.parse
+kind: rule
+status: active
+name: Plan artifacts parse
+statement: Every `.yaml`, `.yml` or `.json` file under `plan/` parses. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan artifacts parse.
+  normative_text: An artifact that does not parse is invisible to every other rule, so its defects hide behind one
+    error.
+  fix_hint: Fix the syntax the finding reports.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-PARSE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.reference-resolves.convention.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.reference-resolves
+kind: rule
+status: active
+name: Typed plan references resolve
+statement: Every typed reference an artifact makes (`wagon:`, `feature:`, `wmbt:`, `train:`, `interlocking:`, `journey:`)
+  names an artifact the plan declares. `contract:` references are resolved by the contract registry rules instead.
+  Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Typed plan references resolve.
+  normative_text: A reference to nothing is a relationship the plan claims and cannot show.
+  fix_hint: Declare the referenced artifact, or correct the reference.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-REFERENCE-RESOLVES
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.planner/atdd-bun.planner.schema.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.schema
+kind: rule
+status: active
+name: Plan artifacts satisfy their package-shipped schema
+statement: Every recognized plan artifact (wagon, feature, WMBT and its acceptances, train, train interlocking,
+  journey topology, registries) satisfies its JSON Schema in `planner-schemas/`. A violation that belongs to a canonical
+  rule is reported under that rule (for example `planner.train.naming`); every other violation is reported here.
+  Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Plan artifacts satisfy their package-shipped schema.
+  normative_text: The schemas are the shape every other rule assumes. An artifact that breaks its schema breaks
+    those assumptions silently.
+  fix_hint: Correct the field the finding names, as the schema requires.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-SCHEMA
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_schema_validation

package/conventions/atdd-bun.planner/atdd-bun.planner.train-wagon-resolves.convention.yaml

@@ -0,0 +1,26 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.planner.train-wagon-resolves
+kind: rule
+status: active
+name: Train wagons resolve
+statement: Every wagon a train lists under `wagons:` is declared as `wagon:<slug>`. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+content:
+  summary: Train wagons resolve.
+  normative_text: A train ordering a wagon that does not exist cannot run.
+  fix_hint: Declare the wagon, or remove it from the train.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-PLANNER-TRAIN-WAGON-RESOLVES
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: planner_plan_integrity

package/conventions/atdd-bun.topology/atdd-bun.topology.e2e-location.convention.yaml

@@ -0,0 +1,38 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.e2e-location
+kind: rule
+status: active
+name: Every interlocking route and exposed journey has an end-to-end test at its canonical path
+statement: 'Every interlocking route has `<e2e_root>/interlockings/<interlocking>/<route>.routes.test.ts`, and every
+  exposed journey `<e2e_root>/journeys/<journey>.journey.test.ts`, each carrying a `test:{wagon}:{feature}:{acceptance}`
+  URN for a declared feature and binding `Acceptance: acc:{wagon}:{acceptance}` declared by a WMBT. On an exposed
+  journey whose surfaces include `frontend`, a Playwright spec (`*.e2e.ts`) substitutes for the Bun test when it
+  is bound to the route''s train (`// Train:`) or the journey (`// Journey:`) and carries a valid E2E or SMOKE test
+  URN for that same subject (`test:train:<id>:E2E-NNN-…`, `test:journey:<id>:SMOKE-NNN-…`). A browser spec carries
+  its identity as that URN instead of an `Acceptance:` line, which `tester.htmx.journey-no-acceptance-marker` forbids
+  on journey specs. Package rule, strict.'
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Every interlocking route and exposed journey has an end-to-end test at its canonical path.
+  normative_text: 'One behaviour, one end-to-end proof at a path derived from the plan: a missing proof is found
+    by path, not by searching.'
+  fix_hint: Add the test at the path the finding names, or, on a frontend journey, a Playwright spec bound with
+    `// Train:` or `// Journey:`.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-E2E-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.feature-source-coverage.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.feature-source-coverage
+kind: rule
+status: active
+name: A feature with WMBTs has source
+statement: A feature that owns WMBTs has at least one source component beneath `<source_root>/<wagon>/features/<feature>/`.
+  Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: A feature with WMBTs has source.
+  normative_text: A feature with behaviour to deliver and no implementation is a gap the plan already names.
+  fix_hint: Implement the feature beneath its directory, or move the WMBTs to the feature that delivers them.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-FEATURE-SOURCE-COVERAGE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.feature-test-coverage.convention.yaml

@@ -0,0 +1,29 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.feature-test-coverage
+kind: rule
+status: active
+name: A feature with WMBTs has a test bound to one of its acceptances
+statement: A feature that owns WMBTs has at least one test bound to one of its acceptances. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: A feature with WMBTs has a test bound to one of its acceptances.
+  normative_text: Behaviour declared and never tested is a silent gap.
+  fix_hint: Add a test beneath the feature bound to one of its acceptances.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-FEATURE-TEST-COVERAGE
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.plan-location.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.plan-location
+kind: rule
+status: active
+name: Wagons, features and WMBTs live at their canonical plan paths
+statement: Every wagon is declared at `<plan_root>/<wagon>/_<wagon>.yaml`, every feature at `<plan_root>/<wagon>/<feature>.yaml`,
+  and every WMBT at `<plan_root>/<wagon>/<WMBT>.yaml`. Package rule, strict.
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Wagons, features and WMBTs live at their canonical plan paths.
+  normative_text: The plan is navigated by path as much as by identity. A document at a non-canonical path is found
+    by nothing that walks the layout, and two layouts in one repository make every tool guess.
+  fix_hint: Move the document to the path the finding names.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-PLAN-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.source-location.convention.yaml

@@ -0,0 +1,33 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.source-location
+kind: rule
+status: active
+name: Feature source lives beneath its feature and carries a component URN
+statement: 'When the plan models at least one wagon, feature or WMBT, every source file beneath `<source_root>`
+  carries `URN: component:{wagon}:{feature}:{name}:{frontend|backend}:{domain|application|integration|presentation}`
+  and lives beneath `<source_root>/<wagon>/features/<feature>/`, for a feature the plan declares. Package rule,
+  strict.'
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Feature source lives beneath its feature and carries a component URN.
+  normative_text: Source is traced to the feature that owns it by its URN and found by its path. Either missing,
+    the feature cannot be shown to have an implementation.
+  fix_hint: Add the component URN header and move the file beneath its feature's directory.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-SOURCE-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/conventions/atdd-bun.topology/atdd-bun.topology.test-location.convention.yaml

@@ -0,0 +1,34 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.topology.test-location
+kind: rule
+status: active
+name: Feature tests live beneath their feature and bind a declared acceptance
+statement: 'When the plan models at least one wagon, feature or WMBT, every test beneath `<test_root>` carries `URN:
+  test:{wagon}:{feature}:{acceptance}`, lives beneath `<test_root>/<wagon>/features/<feature>/{unit,contract,integration}/`,
+  and binds `Acceptance: acc:{wagon}:{acceptance}` declared by a WMBT that the test''s own feature lists. Package
+  rule, strict.'
+terms:
+- term_id: package_rule
+  text: 'a rule of this package''s own gates (`atdd-bun.*`), realized by a package guard rather than a canonical
+    planner node. It is held to the same per-rule checks as every convention: a convention, strict, a failing fixture,
+    relationship edges.'
+- term_id: topology_settings
+  text: the `topology:` keys `plan_root`, `source_root`, `test_root`, `e2e_root` in `atdd-bun.yaml` (defaults `plan`,
+    `src/wagons`, `tests/wagons`, `e2e`).
+content:
+  summary: Feature tests live beneath their feature and bind a declared acceptance.
+  normative_text: A test proves an acceptance only when it names one that exists; its path says which feature and
+    which kind of test it is.
+  fix_hint: Add the test URN and Acceptance header, and move the test beneath its feature under unit/, contract/
+    or integration/.
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - ATDD-BUN-TOPOLOGY-TEST-LOCATION
+  severity: 3
+  disposition: strict
+  introduced_in: 0.6.0
+implementation:
+  type: validator
+  ref: atdd_topology

package/detectors/atdd_topology/atdd.implementation.yaml

@@ -10,4 +10,7 @@ emits_rule_ids:
 - atdd-bun.topology.e2e-location
 - atdd-bun.topology.feature-source-coverage
 - atdd-bun.topology.feature-test-coverage
+realizes_convention:
+  - planner.wagon.features
+  - planner.feature.wagon-link
 entrypoint: detect.mjs

package/detectors/atdd_topology/detect.mjs

@@ -21,7 +21,7 @@ function add(rule_id, root, path, evidence, line = 1, source_line = "") { violat
 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;
+    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);
   }
@@ -47,6 +47,10 @@ for (const root of roots) {
   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) {
@@ -95,6 +99,7 @@ for (const root of roots) {
     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) {
@@ -111,8 +116,13 @@ for (const root of roots) {
   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);
+    // 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]));
@@ -153,6 +163,7 @@ for (const root of roots) {
     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);
     }
   }

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

@@ -1,4 +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/plan/orders/E001.yaml

@@ -2,5 +2,7 @@ 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_traceability_closure/detect.mjs

@@ -14,6 +14,7 @@ const testName = /(?:^test_.*|.*(?:\.test|\.spec|_test))\.(?:[cm]?[jt]sx?)$/;
 const violations = [];
 const plans = { acc: new Set(), wmbt: new Set(), train: new Set() };
 const tests = new Map();
+const declaredAt = new Map();
 const sources = [];
 let planDisplay = "plan/";
 
@@ -32,10 +33,14 @@ function text(path) { try { return readFileSync(path, "utf8"); } catch { return
 function add(rule_id, file, line, evidence, source_line = "") {
   violations.push({ rule_id, file, line, col: 1, evidence, source_line });
 }
-function lineOf(content, token) { return content.slice(0, content.indexOf(token)).split("\n").length; }
+function lineOf(content, token) { return lineAt(content, content.indexOf(token)); }
+function lineAt(content, index) { return content.slice(0, index).split("\n").length; }
+// The identity each binding header must carry.
+const PREFIX = { Acceptance: "acc:", WMBT: "wmbt:", Train: "train:" };
 
 for (const root of roots) {
-  const topology = await topologyFor(root), planPrefix = topology.planRoot.replace(/\/$/, "") + "/"; planDisplay = planPrefix;
+  // `plan_root: .` (or `./`) must still match root-relative paths, which never start with `./`.
+  const topology = await topologyFor(root), planDir = topology.planRoot.replace(/^\.(?:\/|$)/, "").replace(/\/$/, ""), planPrefix = planDir ? planDir + "/" : ""; planDisplay = planPrefix || "./";
   walk(root, (path) => {
     const name = path.split("/").pop() || "";
     const content = text(path);
@@ -45,43 +50,53 @@ for (const root of roots) {
         wmbt: /\bwmbt:[A-Za-z0-9_.:-]+/g,
         train: /\btrain:[A-Za-z0-9_.:-]+/g,
       })) for (const match of content.matchAll(re)) plans[kind].add(match[0]);
+      // Where each acceptance is DECLARED (its `urn:` line), so a missing test is reported on the artifact to fix.
+      for (const m of content.matchAll(/["']?\burn["']?[ \t]*:[ \t]*["']?(acc:[A-Za-z0-9_.:-]+)/g)) if (!declaredAt.has(m[1])) declaredAt.set(m[1], { path, line: lineAt(content, m.index) });
       return;
     }
     if (!sourceExtensions.has(name.slice(name.lastIndexOf(".")))) return;
     const head = content.split("\n").slice(0, 40).join("\n");
     if (testName.test(name)) {
       const urn = head.match(/^\s*\/\/\s*URN:\s*(test:[^\s]+)/m);
-      const binding = head.match(/^\s*\/\/\s*(Acceptance|WMBT|Train):\s*((?:acc|wmbt|train):[^\s]+)/m);
       if (!urn) return;
-      tests.set(urn[1], { path, binding: binding?.[2], bindingKind: binding?.[1] });
-      if (!binding) add("traceability.test.binding-resolves", path, lineOf(head, urn[0]), "test has a URN but no Acceptance:, WMBT:, or Train: binding", urn[0]);
+      // EVERY binding header is judged, not only the first: a valid Acceptance: must not carry an unresolved Train:.
+      const headers = [...head.matchAll(/^[ \t]*\/\/[ \t]*(Acceptance|WMBT|Train):[ \t]*(\S*)/gm)].map((m) => ({ kind: m[1], id: m[2], raw: m[0].trim(), line: lineAt(head, m.index) }));
+      const bindings = headers.filter((h) => h.id.startsWith(PREFIX[h.kind]));
+      tests.set(urn[1], { path, bindings });
+      if (!headers.length) add("traceability.test.binding-resolves", path, lineOf(head, urn[0]), "test has a URN but no Acceptance:, WMBT:, or Train: binding", urn[0]);
+      for (const h of headers) if (!bindings.includes(h)) add("traceability.test.binding-resolves", path, h.line, `${h.kind}: ${h.id || "<empty>"} is not a ${PREFIX[h.kind]} identity`, h.raw);
       return;
     }
     const component = head.match(/^\s*\/\/\s*URN:\s*(component:[^\s]+)/m);
     if (!component) return;
-    const testedBy = [...head.matchAll(/^\s*\/\/\s*-\s*(test:[^\s]+)/gm)].map((match) => match[1]);
+    // Only list entries directly under a `// Tested-By:` header count, and EVERY one of them is judged: a
+    // malformed `- not-a-test` after a valid entry fails too. A stray list item elsewhere declares nothing.
+    const testedBy = [];
+    let under = false;
+    for (const line of head.split("\n")) {
+      if (/^\s*\/\/\s*Tested-By:\s*$/.test(line)) { under = true; continue; }
+      const entry = under && line.match(/^\s*\/\/\s*-\s*(\S*)/);
+      if (entry) testedBy.push(entry[1] || "<empty>"); else under = false;
+    }
     sources.push({ path, head, component: component[1], testedBy });
   });
 }
 
-for (const test of tests.values()) {
-  if (!test.binding) continue;
-  const kind = test.binding.startsWith("acc:") ? "acc" : test.binding.startsWith("wmbt:") ? "wmbt" : "train";
-  if (!plans[kind].has(test.binding)) {
-    add("traceability.test.binding-resolves", test.path, lineOf(text(test.path), test.binding), `${test.binding} is not declared in plan/`, `// ${test.bindingKind}: ${test.binding}`);
-  }
+for (const test of tests.values()) for (const binding of test.bindings) {
+  if (!plans[binding.id.split(":", 1)[0]].has(binding.id)) add("traceability.test.binding-resolves", test.path, binding.line, `${binding.id} is not declared in plan/`, binding.raw);
 }
-const boundAcceptances = new Set([...tests.values()].map((test) => test.binding).filter((id) => id?.startsWith("acc:")));
+const boundAcceptances = new Set([...tests.values()].flatMap((test) => test.bindings.map((binding) => binding.id)).filter((id) => id.startsWith("acc:")));
 for (const acceptance of plans.acc) {
-  if (!boundAcceptances.has(acceptance)) add("traceability.plan.executable-acceptance-has-test", planDisplay, 1, `${acceptance} has no Bun test binding`, acceptance);
+  const at = declaredAt.get(acceptance);
+  if (!boundAcceptances.has(acceptance)) add("traceability.plan.executable-acceptance-has-test", at?.path ?? planDisplay, at?.line ?? 1, `${acceptance} has no Bun test binding`, acceptance);
 }
 for (const source of sources) {
-  if (!source.testedBy.length) {
+  if (!source.testedBy.some((entry) => entry.startsWith("test:"))) {
     add("traceability.source.tested-by-present", source.path, lineOf(source.head, source.component), `${source.component} has no Tested-By: test:... declaration`, source.component);
     continue;
   }
   for (const testUrn of source.testedBy) {
-    if (!tests.has(testUrn)) add("traceability.source.tested-by-resolves", source.path, lineOf(source.head, testUrn), `${testUrn} does not resolve to a Bun test`, testUrn);
+    if (!tests.has(testUrn)) add("traceability.source.tested-by-resolves", source.path, lineOf(source.head, testUrn), testUrn.startsWith("test:") ? `${testUrn} does not resolve to a Bun test` : `Tested-By entry ${testUrn} is not a test: URN`, testUrn);
   }
 }
 writeFileSync(report, JSON.stringify({ violations }, null, 2));

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: "",

package/detectors/planner_plan_integrity/fixtures/dirty/plan/_trains/_interlockings/checkout.yaml

@@ -0,0 +1,6 @@
+schema_version: 1.0.0
+interlocking_id: interlocking:checkout
+title: Checkout
+lifelines:
+  - ref: wagon:nobody
+routes: []

package/detectors/planner_plan_integrity/fixtures/dirty/plan/_trains/_interlockings/unnamed.yaml

@@ -0,0 +1,2 @@
+participants: []
+routes: []