@afokapu/atdd-bun 0.1.0

package/conventions/coder.bun/coder.bun.green-header-runtime.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-header-runtime
+kind: rule
+status: active
+name: The header declares the runtime the file executes in
+statement: >-
+  Every implementation file MUST carry a `Runtime:` declaration naming `bun`, `browser` or `isomorphic`.
+  Stack-neutral obligation, Bun-specific vocabulary; realized by `bun_green_traceability_detector` (core
+  alias GREEN-HEADER-001).
+terms:
+- term_id: runtime_field
+  text: >-
+    the `Runtime:` header line naming where the file executes.
+- term_id: isomorphic
+  text: >-
+    a module that genuinely runs both server-side and in the browser. Bun decides at run time
+    what a bundler decides at build time, so the value must exist.
+content:
+  summary: >-
+    A "the file says where it runs" obligation. The vocabulary is this stack's: Vite reads
+    `vite|browser|node` and Python reads `python`.
+  normative_text: |
+    `isomorphic` has no Vite counterpart and is the substantive addition. A bundler stack decides at BUILD time which code reaches the browser, so a file is server or client by where the bundler puts it. Bun decides at RUN time, and a full-stack Bun app routinely runs one module in both places — a fragment renderer used server-side and again after a client-side swap. Without a value for that, authors would be forced to pick a wrong one, and every downstream reader would inherit the error.
+  fix_hint: |
+    Declare the runtime the file actually executes in:
+
+      // Runtime: deno         // ✗ not this stack
+      // Runtime: bun          // ✓ server-side
+      // Runtime: browser      // ✓ ships to the client
+      // Runtime: isomorphic   // ✓ genuinely runs in both
+  exceptions:
+  - A missing declaration is reported at the URN line (or the first meaningful line when there is no URN).
+  - Test files are excluded.
+metadata:
+  aliases:
+  # GREEN-HEADER-001 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-header-runtime. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-HEADER-001
+  - BUN-GREEN-HEADER-RUNTIME-001
+  severity: 2
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-header-tested-by.convention.yaml

@@ -0,0 +1,63 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-header-tested-by
+kind: rule
+status: active
+name: The header binds the file to at least one acceptance
+statement: >-
+  Every implementation file MUST carry a `Tested-By:` block containing at least one `- test:…` acceptance
+  URN. Stack-neutral obligation, Bun-specific detector; realized by `bun_green_traceability_detector`
+  (core alias GREEN-HEADER-003).
+terms:
+- term_id: tested_by_block
+  text: >-
+    the `Tested-By:` line followed by one or more `- test:` acceptance URNs.
+- term_id: empty_block
+  text: >-
+    a `Tested-By:` line with no entries. Treated as absent, because it is the shape a half-
+    finished backfill leaves and would otherwise report full coverage with zero bindings.
+content:
+  summary: >-
+    A "the file names the acceptances that cover it" obligation: the `Tested-By:` line must be present AND
+    followed by one or more `- test:` entries. A bare block with no entries fails.
+  normative_text: |
+    This is the rule that makes the whole header load-bearing rather than decorative. The URN says what the file IS; `Tested-By:` says what PROVES it. Together they close the loop from acceptance to implementation that ATDD exists to keep closed — which is exactly the loop that a stack migration breaks silently, because the new files are written without headers and nothing notices.
+    An empty block is treated as absent deliberately: it is the shape a half-finished backfill leaves behind, and accepting it would let a repo report full header coverage with zero acceptance bindings.
+  fix_hint: |
+    Name at least one acceptance:
+
+      // Tested-By:
+      // - test:orders:checkout:E001-SMOKE-001-renders-row
+
+    and in a template:
+
+      <!-- Tested-By: -->
+      <!-- - test:orders:checkout:E001-SMOKE-002-panel-loads -->
+
+    Whether the named acceptances EXIST is a plan-graph question this rule cannot answer; it enforces that the binding is declared.
+  exceptions:
+  - Test files are excluded — they are the other end of this binding.
+  - One entry satisfies the rule; more are encouraged.
+  - Entry resolution against `plan/` is out of scope for a per-file detector.
+metadata:
+  aliases:
+  # GREEN-HEADER-003 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-header-tested-by. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-HEADER-003
+  - BUN-GREEN-HEADER-TESTED-BY-001
+  severity: 2
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-urn-layer.convention.yaml

@@ -0,0 +1,53 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-urn-layer
+kind: rule
+status: active
+name: The URN layer segment is one of the five architectural layers
+statement: >-
+  The `{layer}` segment of a URN MUST be one of `domain`, `application`, `integration`, `presentation`,
+  `assembly`. Stack-neutral obligation, Bun-specific detector; realized by
+  `bun_green_traceability_detector` (core alias GREEN-URN-006).
+terms:
+- term_id: layer_segment
+  text: >-
+    segment 5: domain, application, integration, presentation or assembly.
+- term_id: layering_input
+  text: >-
+    the fact the boundary and dependency-flow rules read to judge an import. A layer outside the
+    vocabulary makes the file unreachable by every layering rule.
+content:
+  summary: >-
+    A "layer is declared from the closed vocabulary" obligation, checked against segment 5.
+  normative_text: |
+    The layer segment is what the boundary and dependency-flow rules read to decide whether an import is legal. A file declaring a layer outside the vocabulary is not merely mislabelled — it is unreachable by every layering rule, so it becomes a hole through which any dependency may pass unchallenged.
+  fix_hint: |
+    Use a layer from the vocabulary:
+
+      // URN: component:orders:checkout:OrderRow:backend:widgets       // ✗
+      // URN: component:orders:checkout:OrderRow:backend:presentation  // ✓
+  exceptions:
+  - URNs that are not six segments are skipped.
+  - The vocabulary is fixed by core, not by this extension; a new layer is a core change.
+metadata:
+  aliases:
+  # GREEN-URN-006 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-urn-layer. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-URN-006
+  - BUN-GREEN-URN-LAYER-001
+  severity: 3
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-urn-marker.convention.yaml

@@ -0,0 +1,67 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-urn-marker
+kind: rule
+status: active
+name: Every implementation file opens with its URN component marker
+statement: >-
+  A Bun/htmx implementation file — `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.mts` AND `.html`/`.htm`
+  template — MUST carry a `URN: component:…` marker as its first meaningful line. Stack-neutral obligation
+  (required in every implementation file), Bun-specific dual-syntax detector: `// URN:` in source, `<!--
+  URN: … -->` in a template. The Python realization writes `# URN:` and the Vite one `// URN:`; this is
+  the same obligation with a third comment syntax. Realized by the family validator
+  `bun_green_traceability_detector` (core alias GREEN-URN-001).
+terms:
+- term_id: traceability_header
+  text: >-
+    the leading comment block binding a file to the plan graph: URN, Tested-By, Runtime,
+    Purpose. `//` in source, `<!-- … -->` in an .html template.
+- term_id: first_meaningful_line
+  text: >-
+    the first line that is neither blank nor a preamble. A shebang or `<!doctype>` may precede
+    the marker without displacing it, because neither is content.
+content:
+  summary: >-
+    A "every file declares its component URN" obligation. The detector treats the leading run of blank
+    lines, an optional shebang or doctype, and single-line comments as the header region; the first real
+    content line ends it. A marker below the imports therefore reads as MISSING, which is the point.
+  normative_text: |
+    The URN is the only edge between a source file and the plan graph. Without it a file is invisible to traceability: no acceptance can claim it, no wagon owns it, and coverage reporting cannot see it exists.
+    "First meaningful line" excludes a shebang (`#!/usr/bin/env bun`) and an HTML doctype, because neither is content and neither should be able to displace the marker. The Vite sibling counts a shebang as the first non-empty line and so reports a header it actually has as missing; this realization does not.
+  fix_hint: |
+    Put the marker on the first meaningful line:
+
+      // URN: component:orders:checkout:OrderRow:backend:presentation
+
+    and in a template:
+
+      <!doctype html>
+      <!-- URN: component:orders:checkout:OrderPanel:frontend:presentation -->
+
+    Disposition is `documentation-only`, matching the Python and Vite realizations: a ratchet holds an existing repo flat while headers are backfilled.
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) are excluded — they are bound by their acceptance URNs instead.
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+  - A shebang or `<!doctype>` may precede the marker.
+metadata:
+  aliases:
+  # GREEN-URN-001 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-urn-marker. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-URN-001
+  - BUN-GREEN-URN-MARKER-001
+  severity: 3
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-urn-name-matches.convention.yaml

@@ -0,0 +1,57 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-urn-name-matches
+kind: rule
+status: active
+name: The URN name segment matches the filename
+statement: >-
+  The `{Name}` segment of a URN MUST match the file's basename, compared case- and separator-
+  insensitively, unless the name is a structural role. Stack-neutral obligation, Bun-specific detector;
+  realized by `bun_green_traceability_detector` (core alias GREEN-URN-004).
+terms:
+- term_id: name_segment
+  text: >-
+    segment 3 of the URN, which identifies the component the file implements.
+- term_id: structural_role_name
+  text: >-
+    a filename naming a ROLE rather than a component — index, server, routes, layout, partial,
+    composition, wagon. Exempt, because the file assembles rather than implements.
+content:
+  summary: >-
+    A "the URN names this file" obligation. The detector normalises both sides to lowercase alphanumerics
+    before comparing, and exempts a set of structural filenames that name a ROLE rather than a component.
+  normative_text: |
+    A URN naming a different component than the file it sits in is worse than a missing one: it binds the file's evidence to somebody else's component, so both are wrong and neither is obviously wrong. This is the failure a copy-pasted header produces, which is how it usually arises.
+    The exempt set is the Vite set plus this stack's idioms — `server`, `routes`, `layout`, `partial`, `fragment`, `middleware` — because a full-stack Bun app's entrypoint is `server.ts` and its htmx fragments are named for their role, not for a component.
+  fix_hint: |
+    Make the name segment agree with the filename, or use a structural role name:
+
+      // in OrderRow.ts
+      // URN: component:orders:checkout:SomethingElse:backend:presentation  // ✗
+      // URN: component:orders:checkout:OrderRow:backend:presentation       // ✓
+  exceptions:
+  - Structural names are exempt: composition, wagon, entrypoint, http, index, schema, router, routes, server, layout, partial, fragment, middleware.
+  - Comparison ignores case and non-alphanumerics, so `order-row.ts` matches `OrderRow`.
+  - URNs that are not six segments are skipped.
+metadata:
+  aliases:
+  # GREEN-URN-004 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-urn-name-matches. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-URN-004
+  - BUN-GREEN-URN-NAME-MATCHES-001
+  severity: 2
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-urn-pattern.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-urn-pattern
+kind: rule
+status: active
+name: The URN has all six segments in the canonical order
+statement: >-
+  A `URN:` marker MUST read `component:{wagon}:{feature}:{Name}:{side}:{layer}` — literal `component`
+  first, then exactly five non-empty segments. Stack-neutral obligation, Bun-specific detector; realized
+  by `bun_green_traceability_detector` (core alias GREEN-URN-002).
+terms:
+- term_id: six_segment_urn
+  text: >-
+    `component:{wagon}:{feature}:{Name}:{side}:{layer}` — the literal `component` plus five non-
+    empty segments.
+- term_id: join_key
+  text: >-
+    a URN segment used to resolve the file against plan/. A missing segment does not degrade: it
+    resolves to nothing while still looking traceable.
+content:
+  summary: >-
+    A "the URN is well-formed" obligation. The detector splits the marker on `:` and requires six
+    segments, the first literally `component`, none empty. Files with no marker are skipped — their
+    finding belongs to `green-urn-marker`, and reporting both would double-count one fault.
+  normative_text: |
+    Each segment is a join key. Wagon and feature locate the work item, name identifies the component, side and layer place it in the architecture. A URN missing a segment does not degrade gracefully — it resolves to nothing, and the file is as unbound as one with no marker at all, while LOOKING traceable in review.
+  fix_hint: |
+    Supply every segment:
+
+      // URN: component:orders:checkout:OrderRow                       // ✗ four segments
+      // URN: component:orders:checkout:OrderRow:backend:presentation  // ✓
+  exceptions:
+  - A file with no `URN:` marker is skipped (owned by `green-urn-marker`).
+  - Segment CONTENT is validated by the wagon-feature, name, side and layer rules; this rule checks shape only.
+metadata:
+  aliases:
+  # GREEN-URN-002 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-urn-pattern. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-URN-002
+  - BUN-GREEN-URN-PATTERN-001
+  severity: 3
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-urn-side.convention.yaml

@@ -0,0 +1,54 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-urn-side
+kind: rule
+status: active
+name: The URN side segment is frontend or backend
+statement: >-
+  The `{side}` segment of a URN MUST be `frontend` or `backend`. Stack-neutral obligation, Bun-specific
+  detector; realized by `bun_green_traceability_detector` (core alias GREEN-URN-005).
+terms:
+- term_id: side_segment
+  text: >-
+    segment 4: `frontend` or `backend`. Which half of the application the file belongs to.
+- term_id: stack_spanning_repo
+  text: >-
+    a repo where one language and one runtime serve both halves, so side cannot be inferred from
+    the stack and must be declared per file.
+content:
+  summary: >-
+    A "side is declared from the closed vocabulary" obligation, checked against segment 4.
+  normative_text: |
+    The vocabulary is unchanged from the Python and Vite realizations, and it matters MORE in a full-stack Bun app than in either. A Vite repo is frontend by construction and a python-pytest service is backend by construction, so the segment is close to redundant there. Here one repo, one language and one runtime span both halves, and the only thing that says which side a module belongs to is this segment — so it must be declared per file and cannot be inferred from the stack.
+  fix_hint: |
+    Declare the side explicitly:
+
+      // URN: component:orders:checkout:OrderRow:server:presentation    // ✗ not a side
+      // URN: component:orders:checkout:OrderRow:backend:presentation   // ✓
+
+    Server-rendered htmx fragments are `backend` (they are produced by the server); markup and behaviour that live in the browser are `frontend`.
+  exceptions:
+  - URNs that are not six segments are skipped.
+  - "`Runtime:` is a different axis — a `backend` file may declare `Runtime: isomorphic`."
+metadata:
+  aliases:
+  # GREEN-URN-005 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-urn-side. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-URN-005
+  - BUN-GREEN-URN-SIDE-001
+  severity: 3
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.green-urn-wagon-feature.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-urn-wagon-feature
+kind: rule
+status: active
+name: URN wagon and feature segments are kebab-case identifiers
+statement: >-
+  The `{wagon}` and `{feature}` segments of a URN MUST match `^[a-z][a-z0-9-]*$`. Stack-neutral
+  obligation, Bun-specific detector; realized by `bun_green_traceability_detector` (core alias GREEN-
+  URN-003).
+terms:
+- term_id: kebab_identifier
+  text: >-
+    `^[a-z][a-z0-9-]*$` — the plan's own grammar for wagon and feature names.
+- term_id: silent_join_failure
+  text: >-
+    the state where a header reads correctly to a human but binds to nothing, because a case- or
+    separator-sensitive key did not match.
+content:
+  summary: >-
+    A "URN identifiers are kebab-case" obligation. The detector applies the pattern to segments 1 and 2 of
+    a well-formed six-segment URN, naming whichever fail.
+  normative_text: |
+    Wagon and feature are join keys into `plan/`, and a join key that is case- or separator-sensitive fails silently: `Orders` and `orders` are two different wagons to a string match, so a header with the wrong casing binds to nothing while reading correctly to a human. Kebab-case is the plan's own grammar, so the header must use it exactly.
+  fix_hint: |
+    Lower-case and hyphenate:
+
+      // URN: component:Orders:Check_Out:OrderRow:backend:presentation  // ✗
+      // URN: component:orders:check-out:OrderRow:backend:presentation  // ✓
+
+    The `{Name}` segment is deliberately NOT kebab — it mirrors the filename and keeps its own casing.
+  exceptions:
+  - URNs that are not six well-formed segments are skipped (owned by `green-urn-pattern`).
+  - The name, side and layer segments are governed by their own rules.
+metadata:
+  aliases:
+  # GREEN-URN-003 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-urn-wagon-feature. One obligation, three
+  # per-stack detectors, found through this alias.
+  - GREEN-URN-003
+  - BUN-GREEN-URN-WAGON-FEATURE-001
+  severity: 3
+  # DIVERGENCE FROM THE VITE/PYTHON REALIZATIONS, deliberate and reversible.
+  # Those two carry `documentation-only`, which core's coverage_report treats as
+  # never-fails-the-build — the right call when RETROFITTING a large existing
+  # codebase, where day-one enforcement would red every file at once.
+  # A new Bun + htmx repo has no such debt: headers can be present from the first
+  # file, and a traceability rule that cannot fail is a rule that will quietly not
+  # be adopted. `suppress-and-clean` fails on violation AND is ratchetable, so an
+  # existing repo adopting this can still `--record-ratchet` a baseline and be held
+  # flat rather than blocked. Change this one field back to `documentation-only`
+  # for exact Vite parity.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

package/conventions/coder.bun/coder.bun.interlocking-bilateral-binding.convention.yaml

@@ -0,0 +1,132 @@
+schema_version: 1.1.0
+rule_id: coder.bun.interlocking-bilateral-binding
+kind: rule
+status: active
+name: Interlocking declarations and runtime route resolution are bilaterally bound (Bun)
+statement: >-
+  An interlocking system is systemic, not descriptive: it requires CLOSURE across declaration (the
+  interlocking YAML route space, core afokapu/atdd#1248), runtime resolution (InterlockingRunner,
+  core afokapu/atdd#1251), Station Master reachability (the `server.ts` JOURNEY_MAP), TrainRunner
+  delegation, and the execution trace. This convention binds those surfaces in FIVE directions so a
+  declared route, a runtime resolution, a Station Master action, and a recorded trace can never drift
+  apart silently. This is the Bun-stack realization of the agnostic core obligation
+  `coder.train.interlocking-bilateral-binding`; the JS detector `bun_interlocking_binding` realizes
+  all five directions and emits this single rule_id with the failing `direction` named in the evidence.
+
+# Machine-readable bilateral relationship (the five binding directions + the schema-drift signal).
+# Each direction names the fixture the JS detector fails on and passes the clean tree.
+bidirectional:
+  - direction: declaration_to_runtime
+    requirement: >-
+      Every declared route resolves through InterlockingRunner to the declared trainId — the route's
+      train artifact (train_path / plan/_trains/<train_id>.yaml) must exist so the runtime can load it.
+    fail_fixture: fixtures/dirty
+  - direction: runtime_to_declaration
+    requirement: >-
+      InterlockingRunner never resolves a routeId/trainId absent from the loaded YAML; a runtime that
+      returns a routeId/selectedTrainId literal not declared in any interlocking is a hidden route.
+    fail_fixture: fixtures/dirty_runtime_hidden
+  - direction: station_to_declaration
+    requirement: >-
+      Every Station Master interlocking mapping ({interlockingId, path}) points to an existing
+      interlocking YAML — a mapping whose path resolves to no file (or names an undeclared
+      interlockingId) is a dangling route.
+    fail_fixture: fixtures/dirty_station_missing
+  - direction: declaration_to_station
+    requirement: >-
+      Every interlocking with core entrypoint.exposed=true is Station-Master-reachable through one of
+      its core entrypoint.actions wired into the JOURNEY_MAP to that interlocking. CONSUMES core
+      afokapu/atdd#1248 entrypoint.exposed + entrypoint.actions; this extension defines NO parallel
+      reachability field (entrypoints, runtime_exposure, station_actions, exposed_actions, reachability).
+    fail_fixture: fixtures/dirty_unreachable
+  - direction: trace_to_declaration
+    requirement: >-
+      Every executed interlocking route emits trace metadata that resolves back to the source YAML — a
+      trace test asserting trace.routeId / trace.interlockingId values absent from the declared route
+      space does not bind the run to its declaration (core afokapu/atdd#1251 trace contract).
+    fail_fixture: fixtures/dirty_trace
+
+implementation:
+  type: validator
+  ref: coder.bun.interlocking-bilateral-binding
+
+content:
+  summary: >-
+    A bilateral-binding obligation that makes train interlocking SYSTEMIC, rendered for the Bun
+    backend. One JS detector (bun_interlocking_binding) walks a consumer tree's interlocking YAML
+    route space (plan/_trains/_interlockings/**), Station Master JOURNEY_MAP (server.ts),
+    InterlockingRunner runtime (src/trains/**), and e2e trace tests (e2e/**), and emits RAW v1.1
+    violations under this rule_id for any of the five binding directions that is broken — plus a
+    schema-drift signal when a parallel reachability field is used instead of core #1248's `entrypoint`.
+  normative_text: |
+    Core runtime spec afokapu/atdd#1251 — the additive call model whose closure this rule enforces:
+
+        plan/_trains/_interlockings/<id>.yaml          (declaration, core #1248)
+          -> entrypoint.actions[]                       (core #1248 entrypoint field — CONSUMED here)
+          -> Station Master JOURNEY_MAP action          (reachability, server.ts)
+          -> InterlockingRunner.resolveTrain(...)       (runtime, core #1251)
+          -> InterlockingResolution(routeId, trainId, category, guardId, resolutionStrategy, ...)
+          -> TrainRunner.execute(selectedTrainId)       (delegation)
+          -> trace(interlockingId, routeId, selectedTrainId, ...)
+          -> validator resolves the trace back to the YAML route
+
+    OWNERSHIP SPLIT (collision prevention): core afokapu/atdd#1248/#1249 own the interlocking YAML
+    schema and the SHAPE/allowed values of the `entrypoint` field. This extension only READS those
+    core fields to validate REACHABILITY against Station Master and runtime traces in a consumer repo.
+    It MUST NOT introduce `entrypoints`, `runtime_exposure`, `station_actions`, `exposed_actions`,
+    `reachability`, or any other parallel reachability field. If core #1248 changes the field name or
+    shape, this rule follows core and updates its detector/fixtures.
+  fix_hint: |
+    Close the broken binding direction named in the violation's evidence:
+
+      declaration_to_runtime  — add the missing train artifact the declared route resolves to.
+      runtime_to_declaration  — remove the hidden routeId/trainId literal, or declare it in the YAML.
+      station_to_declaration  — fix the JOURNEY_MAP interlocking path to point at the real YAML.
+      declaration_to_station  — wire the exposed interlocking's entrypoint.action into JOURNEY_MAP (or
+                                set entrypoint.exposed:false with a reason if it is genuinely internal).
+      trace_to_declaration    — assert the trace's interlockingId/routeId values that are declared.
+      schema drift            — replace any parallel reachability field with core #1248's `entrypoint`.
+
+    This rule is `strict`: a broken binding direction lets declaration, runtime, Station Master, and
+    trace drift apart silently and therefore blocks CI.
+  exceptions:
+    - Interlockings with entrypoint.exposed:false (internal-transition-only / library-only /
+      planned-not-exposed) carry no Station-Master-reachability obligation (declaration_to_station).
+    - A consumer tree with no interlocking route space and no InterlockingRunner is not an interlocking
+      system; the rule does not bite.
+    - Per-stack renderings other than Bun are owned by their own workspace packages.
+
+metadata:
+  aliases:
+    - BUN-INTERLOCKING-BILATERAL-BINDING-001
+  severity: 1
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1248
+    - afokapu/atdd#1249
+    - afokapu/atdd#1251
+
+notes: >-
+  DISPOSITION JUSTIFICATION (strict, severity 1). Bilateral binding is what makes interlocking a
+  route-control SYSTEM rather than a description. A broken binding direction — an unresolvable declared
+  route, a hidden runtime route, a dangling Station Master mapping, an unreachable exposed interlocking,
+  or a trace that does not resolve to its declaration — is the exact silent-drift failure class the
+  train-interlocking design (afokapu/atdd#1246) exists to close. The detector emits RAW facts only; the
+  strict verdict is applied by a downstream gate. Per boundary spec §6.2 the core contracts are
+  referenced NARRATIVELY, and the core `entrypoint` field is CONSUMED, never forked.
+
+terms:
+  - term_id: bilateral_binding
+    text: >-
+      the property that interlocking declaration, runtime resolution, Station Master reachability, and
+      execution trace are bound in both directions so none can drift from the others undetected.
+  - term_id: hidden_route
+    text: >-
+      a routeId/selectedTrainId the InterlockingRunner runtime resolves that is declared in no
+      interlocking YAML — a runtime-to-declaration binding break.
+  - term_id: parallel_reachability_field
+    text: >-
+      any non-core reachability field (entrypoints, runtime_exposure, station_actions, exposed_actions,
+      reachability) that forks core afokapu/atdd#1248's `entrypoint`; using one is schema drift.

package/conventions/coder.bun/coder.bun.interlocking-delegates-to-trainrunner.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.bun.interlocking-delegates-to-trainrunner
+kind: rule
+status: active
+name: InterlockingRunner delegates execution to TrainRunner and never executes wagons itself (Bun)
+statement: >-
+  An `InterlockingRunner` MUST NOT execute wagons directly or duplicate the TrainRunner step loop. The
+  InterlockingRunner-defining module MUST NOT import a `src/<wagon>/wagon.ts` module, call
+  `runTrain(...)`, loop over `<expr>.sequence` as an executor, or otherwise invoke wagon steps;
+  TrainRunner remains the only wagon-step executor. This is the Bun-stack realization of the agnostic
+  core obligation `coder.train.interlocking-delegates-to-trainrunner` (core afokapu/atdd#1251); the JS
+  detector that enforces it is the atdd.workspace.bun implementation referenced below.
+implementation:
+  type: validator
+  ref: coder.bun.interlocking-delegates-to-trainrunner
+content:
+  summary: >-
+    An agnostic "route-control, not execution" obligation, rendered for the Bun application. The JS
+    realization scans each InterlockingRunner-defining module under `src/trains/**` and flags a direct
+    wagon import, a `runTrain(...)` call, or a `for (... of <expr>.sequence)` executor loop. Member of the
+    `bun_interlocking_infrastructure` FAMILY detector (checks/interlocking_delegates.mjs).
+  normative_text: |
+    Core runtime spec afokapu/atdd#1251 — the InterlockingRunner "must not": execute wagon steps, choose
+    the next train step inside a train, bypass TrainRunner, or duplicate TrainRunner's execution loop. It
+    resolves one admissible train and DELEGATES to `TrainRunner.execute(selectedTrainId, ...)`. The
+    production TrainRunner is the single component that runs wagons and carries Cargo between them. WHICH
+    module is scanned (the InterlockingRunner-defining files) and HOW the forbidden patterns are
+    recognized is the per-stack detector's concern; the TrainRunner module's own step loop is legitimate
+    and not flagged.
+  fix_hint: |
+    Delegate instead of executing:
+
+      execute(action, inputs, state) {
+        const res = this.resolveTrain(action, inputs, state);
+        return new TrainRunner(res.trainPath).execute(res.trainId, inputs);  // delegate, do not loop
+      }
+
+    Do NOT import a wagon module, call `runTrain(...)`, or loop over `train.sequence` in interlocking code.
+    This rule is `strict`: a newly introduced direct-execution pattern is not suppressible and fails CI.
+  exceptions:
+    - The production `TrainRunner` module is the legitimate wagon-step executor; only
+      InterlockingRunner-defining modules are scanned for direct execution.
+metadata:
+  aliases:
+    - BUN-INTERLOCKING-DELEGATES-TRAINRUNNER-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: direct_wagon_execution
+    text: >-
+      an InterlockingRunner module importing a wagon module, calling `runTrain(...)`, or looping over
+      `<expr>.sequence` as a step executor — competing with TrainRunner.