@afokapu/atdd-bun 0.1.0

package/conventions/planner.docs/planner.docs.doc-id-unique.convention.yaml

@@ -0,0 +1,65 @@
+schema_version: 1.1.0
+rule_id: planner.docs.doc-id-unique
+kind: rule
+status: active
+name: doc-id is unique across the corpus
+statement: >-
+  No two authored documents beneath `docs/` may declare the same `:doc-id:`. Uniqueness is what makes
+  `doc-id` an identity rather than a label, and it is the precondition for resolving any relationship
+  edge to exactly one target (spec 2 §5.1).
+terms:
+- term_id: corpus
+  text: >-
+    every authored `.adoc` beneath `docs/`, across all areas, excluding `docs/dist/`. Uniqueness is
+    global — `archive/` is part of the corpus, not a separate id space.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '0 .adoc files, therefore 0 declared ids and 0 collisions. Not evidence of health: the corpus does not exist yet. Re-measure after migration, which is exactly when collisions appear.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: 'find . -name ''*.adoc'' -not -path ''./.git/*'' | wc -l'
+    escalate_when: 'The corpus has been migrated and a full scan reports zero duplicate ids — the scale test spec 2 §1 names, since 89 documents is the first corpus large enough to collide.'
+content:
+  summary: >-
+    A duplicated id makes edge resolution ambiguous: `:supersedes: architecture.foo` cannot say which
+    `architecture.foo` it means. The detector reports EVERY file carrying a duplicated id, not just
+    the second one, because there is no principled basis for calling one of them the original.
+  normative_text: |
+    Archived documents share the id space with current ones ON PURPOSE. The tempting alternative —
+    letting `archive/` re-use an id held by a current document — would make `:supersedes:` unusable
+    in precisely the case it exists for, since the superseding and superseded documents would then
+    be indistinguishable to the resolver.
+
+    When a document is archived and a new one takes its place, the two need DIFFERENT ids and a
+    `:supersedes:` edge between them. That is the shape spec 2 §5.2 calls load-bearing for #1782.
+  fix_hint: |
+    Give the archived document a distinct id and link the succession explicitly:
+
+      docs/architecture/shared-control-root.adoc
+        :doc-id: architecture.shared-control-root
+        :status: current
+        :supersedes: archive.2025-control-root
+
+      docs/archive/2025-control-root.adoc
+        :doc-id: archive.2025-control-root
+        :status: superseded
+
+    Do not resolve a duplicate by deleting one of the documents. Preserving history is the point
+    (spec 2 §2, *Out of scope*).
+  exceptions:
+  - Generated output beneath `docs/dist/` is never scanned.
+  - A document with no `doc-id` is reported by `planner.docs.identity-required`, not here; this rule
+    only compares ids that were actually declared.
+metadata:
+  aliases:
+  - DOCS-IDENTITY-002
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.graph-target-resolves.convention.yaml

@@ -0,0 +1,87 @@
+schema_version: 1.1.0
+rule_id: planner.docs.graph-target-resolves
+kind: rule
+status: active
+name: Every relationship target resolves against a declared doc-id, and no node is ever fabricated
+statement: >-
+  Every relationship attribute on an authored document (`:decides:`, `:supersedes:`, `:implements:`,
+  `:depends-on:`) MUST name a `doc-id` that some document in the corpus actually declares. A target
+  outside that set is a REPORTED finding. It is NEVER synthesized into a node, and never silently
+  dropped. This is the one hard requirement of spec 2 §5.4 and the flagship rule of this extension.
+terms:
+- term_id: declared_id_set
+  text: >-
+    the set of `:doc-id:` values read from the authored corpus, built BEFORE any edge is resolved.
+    It is closed and enumerable — which is precisely why the documentation graph can hold a
+    discipline the traceability graph does not.
+- term_id: relationship_attribute
+  text: >-
+    one of the four confirmed verbs of spec 2 §5.2 — `decides`, `supersedes`, `implements`,
+    `depends-on`. `refines` is deliberately NOT shipped (spec 2 §9 Decision 3).
+- term_id: fabrication
+  text: >-
+    creating a graph node for a target no document declares, so that an edge appears to resolve. The
+    defect this rule exists to make impossible.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '0 .adoc files, so 0 authored edges and 0 unresolved targets. The number that motivates this rule is the OTHER graph''s, quoted in full under normative_text and measured on the same date: 147 of 168 containment edges invented, 44 fabricated nodes out of 3208.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: 'find . -name ''*.adoc'' -not -path ''./.git/*'' | wc -l'
+    escalate_when: 'A full corpus scan reports zero unresolved relationship targets. The no-fabrication half is NOT subject to escalation — it is a property of the resolver, true from the first commit, and is asserted by the #1758 regression test rather than deferred to a disposition flip.'
+content:
+  summary: >-
+    Resolve or report — never invent. The graph is DERIVED from the `.adoc` attributes and rebuilt on
+    demand (spec 2 §5.3); a persisted graph would be a second registry, and a second registry drifts.
+    The resolver builds the declared-id set first, then admits an edge only if its target is in that
+    set, and reports every edge that is not.
+  normative_text: |
+    This is not a stylistic preference. It is a defect that has ALREADY HAPPENED in this
+    repository's other graph, and the reason spec 2 §5.4 states it as non-negotiable.
+
+    Reproduced live on the ATDD working tree, 2026-09-06 (#1758):
+
+      total nodes                                 : 3208
+      fabricated nodes                            :   44   (feature 28 · wagon 6 · train 6 · test 4)
+      feature -> component CONTAINS (urn-structure):  168
+        parent DECLARED                           :   21   ( 12.5% )
+        parent INVENTED                           :  147   ( 87.5% )
+
+    147 of 168 containment edges point at features no file declares, hanging off 28 invented nodes.
+    The mechanism is four lines in `src/atdd/coach/utils/graph/graph_builder.py:215` — `_ensure_node`
+    synthesizes a bare node for any URN the graph has not seen, `add_edge` calls it on BOTH endpoints
+    of every edge, and so any edge naming a non-existent target conjures the target into being.
+
+    WHY FABRICATION IS WORSE THAN ABSENCE. An absent parent leaves a node orphaned, and an orphan
+    check catches it. A fabricated parent makes the node look CONNECTED. Fabrication defeats the
+    check more thoroughly than absence does — which is why the test for this rule asserts the NODE
+    COUNT directly and not merely the finding.
+
+    Do NOT reuse `graph_builder.py`. It is the substrate that lacks this discipline. The resolver
+    lives in this extension, and there is exactly ONE of it (spec 2 §5.4, citing #1755 on the seven
+    reimplementations of lifecycle resolution).
+  fix_hint: |
+    Either declare the target, or fix the reference:
+
+      :implements: purpose.wortrees      # ✗ typo; nothing declares this id — REPORTED
+      :implements: purpose.worktrees     # ✓ resolves against a declared doc-id
+
+    When the target genuinely does not exist yet, the reference is premature. Author the target
+    document first. An edge to a document you intend to write is indistinguishable, to every reader
+    and every tool, from an edge to a document that was deleted.
+  exceptions:
+  - An attribute that is absent is not an unresolved edge. Only declared relationships are resolved.
+  - Nothing is exempt from the no-fabrication half. There is no configuration that permits synthesis.
+metadata:
+  aliases:
+  - DOCS-GRAPH-001
+  severity: 1
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.identity-required.convention.yaml

@@ -0,0 +1,68 @@
+schema_version: 1.1.0
+rule_id: planner.docs.identity-required
+kind: rule
+status: active
+name: Every authored document declares a doc-id and a status
+statement: >-
+  An authored `.adoc` beneath `docs/` MUST declare both a `:doc-id:` and a `:status:` attribute with
+  non-empty values. `doc-id` is the document's node identity in the relationship graph (spec 2 §5.1);
+  `status` is what makes the current-versus-historical boundary readable at all.
+terms:
+- term_id: doc_id
+  text: >-
+    the value of the `:doc-id:` AsciiDoc attribute — a dotted identifier such as
+    `architecture.shared-control-root`. It is the ONLY node identity the documentation graph uses;
+    paths are never node identities.
+- term_id: status
+  text: >-
+    the value of the `:status:` attribute — `current`, `superseded`, or `historical`. It answers "is
+    this accepted truth today?" and is the flag issue #1782 exists to introduce.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '0 .adoc files exist, so 0 documents declare a doc-id and the rule currently has an empty corpus to check. It ships advisory because it will fire on every file the moment conversion begins and before the attributes are backfilled.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: 'find . -name ''*.adoc'' -not -path ''./.git/*'' | wc -l'
+    escalate_when: 'Every authored `.adoc` beneath `docs/` declares both attributes — reachable only after the migration lands, since the attribute is authored during conversion.'
+content:
+  summary: >-
+    Identity and currency, declared in the document itself. Without `doc-id` there is no graph:
+    `planner.docs.graph-target-resolves` resolves every edge against the set of DECLARED ids, and a
+    document that declares none can neither be pointed at nor be found missing.
+  normative_text: |
+    `status:` alone is deliberately NOT sufficient to make archive/ honest, and this node should not
+    be read as claiming otherwise. Spec 2 §5.2 is explicit: a status attribute says *this is
+    superseded*; it cannot say *by what*. The `supersedes` edge carries that, and it is validated by
+    planner.docs.graph-target-resolves. This rule establishes the identity that edge needs; it does
+    not by itself discharge #1782.
+
+    Both attributes are required TOGETHER because a document with an id and no status is a node
+    whose currency is unknown, and a document with a status and no id is a claim nothing can
+    reference. Each half is useless alone.
+  fix_hint: |
+    Declare both in the document header, above the first section:
+
+      = Shared Control Root
+      :doc-id: architecture.shared-control-root
+      :status: current
+
+    Choose the id from the area the document lives in (`architecture.`, `purpose.`, `delivery.`,
+    `archive.`) so that the id and the tree agree. Nothing enforces that agreement today; it is a
+    convention that keeps ids readable, not a checked rule.
+  exceptions:
+  - Generated output beneath `docs/dist/` is never scanned.
+  - A file with no AsciiDoc header at all is still a violation, not a skip. Silence about a document
+    that declares nothing is the failure mode this extension exists to refuse.
+metadata:
+  aliases:
+  - DOCS-IDENTITY-001
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.reference-integrity.convention.yaml

@@ -0,0 +1,74 @@
+schema_version: 1.1.0
+rule_id: planner.docs.reference-integrity
+kind: rule
+status: active
+name: The site builds deterministically and every internal reference resolves
+statement: >-
+  The corpus MUST render with asciidoctor, and every internal cross-reference MUST resolve. A build
+  failure or an unresolvable internal reference is a FAIL. An ABSENT toolchain, or a build failure
+  the capability cannot attribute to a specific document, is `COULD_NOT_CHECK` — never `PASS`, and
+  never `FAIL` (spec 2 §3, *What the capability owes core*, and §7).
+terms:
+- term_id: internal_reference
+  text: >-
+    a cross-reference from one document in the corpus to another (`xref:`, `<<anchor>>`). External
+    links are out of scope; their liveness is a network property, not a corpus property.
+- term_id: unattributable_failure
+  text: >-
+    a render failure the capability cannot pin to a document — a crashed renderer, an unreadable
+    tree, a toolchain that is not installed. It is reported as `COULD_NOT_CHECK`, which BLOCKS.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: 'ABSENT — `command -v asciidoctor` exits 1 on this machine. The capability therefore returns COULD_NOT_CHECK here today, which BLOCKS, and that is the specified behaviour rather than a defect. Re-take this probe in the CI image before escalating; asciidoctor absence on a developer machine is expected and is not a reason to weaken the rule.'
+    measurement_target: 'this machine (the extension''s own toolchain probe)'
+    measurement_command: 'command -v asciidoctor'
+    escalate_when: 'asciidoctor is available in CI and a full render of the migrated corpus completes with zero unresolvable internal references. Note that the COULD_NOT_CHECK path already BLOCKS at the capability seam regardless of this disposition — advisory governs the reported findings, not the capability''s verdict contract.'
+content:
+  summary: >-
+    Reference integrity is why asciidoctor (Ruby) is the reference implementation rather than a pure
+    Python renderer: unresolvable internal references must be VALIDATION FAILURES, and the Python
+    options detect them weakly. A Ruby runtime in CI is the cost, accepted deliberately (spec 2 §9
+    Decision 4).
+  normative_text: |
+    THE VERDICT DISTINCTION IS THE POINT OF THIS RULE, and it is the thing most likely to be got
+    wrong. *There is no obligation here* (`NOT_APPLICABLE`, permits) and *I could not see whether the
+    obligation was met* (`COULD_NOT_CHECK`, blocks) must never collapse into one another.
+
+    This repository has that bug in at least three places, which is why spec 2 §3 states it so
+    emphatically: #1745, where `coach.pr.merge-blocks-on-pre-smoke-close` degrades to advisory on a
+    lookup failure and REPORTS IT AS A PASS; #1774, where *no mirror found* is read as *nothing to
+    lose* and 15 nodes are invisible to the succession guard; #1716, where checks pass when they
+    cannot observe and C011 compares the store against itself.
+
+    An unresolvable lookup must remain DATA — a named, reportable state that reaches the report,
+    never an empty clean result. A missing asciidoctor is not a clean corpus. It is an unexamined one.
+  fix_hint: |
+    For a reported reference, fix the target or the reference:
+
+      xref:architecture/shared-control-rooot.adoc[]   # ✗ unresolvable — FAIL
+      xref:architecture/shared-control-root.adoc[]    # ✓ resolves
+
+    For `COULD_NOT_CHECK`, install the toolchain rather than suppressing the verdict:
+
+      gem install asciidoctor
+
+    Do not "fix" a COULD_NOT_CHECK by making the capability return PASS when the renderer is absent.
+    That is the #1745 defect, re-committed.
+  exceptions:
+  - External links are not resolved. Their liveness is a network property and checking it would make
+    the gate non-deterministic.
+  - '`docs/dist/**` is the render OUTPUT and is never an input to the render.'
+metadata:
+  aliases:
+  - DOCS-RENDER-001
+  severity: 1
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.undeclared-change.convention.yaml

@@ -0,0 +1,80 @@
+schema_version: 1.1.0
+rule_id: planner.docs.undeclared-change
+kind: rule
+status: active
+name: A change touching docs/ is covered by a declared artifact
+statement: >-
+  Any path in the change set beneath `docs/`, outside `docs/dist/`, MUST be covered by an artifact in
+  the documentation declaration. An undeclared documentation change is a violation. This rule lives in
+  the extension and NOT in core, because it requires knowing `docs/` (spec 2 §4; companion §4,
+  *Deliberately excluded*).
+terms:
+- term_id: change_set
+  text: >-
+    the paths added, modified or deleted under evaluation, handed to the capability by core
+    (companion §5). The capability reads it; it does not compute it.
+- term_id: covered
+  text: >-
+    a changed path equals the `path` of some declared artifact, or the `from` of an `archive`
+    artifact. Coverage is exact-path, not prefix or glob.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '0 declarations exist, so every `docs/**` change in the repository today is undeclared and this rule would fire on all of them. That is the reason it ships advisory rather than strict: escalating before the declaration exists would block every commit touching documentation.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: '(requires the core declaration, companion §3, which is not yet implemented)'
+    escalate_when: 'Declarations are being recorded at RATIFY and a full pass over recent merges reports zero undeclared `docs/**` changes.'
+content:
+  summary: >-
+    The enforceable inverse. Detecting that a change SHOULD HAVE BEEN declared is semantic and not
+    deterministically decidable; detecting that a declared-documentation repository touched `docs/`
+    without declaring it is deterministic, and it catches the same class of drift from the other side.
+  normative_text: |
+    #1782 reasoned this correctly and spec 2 §4 keeps the reasoning: the deterministic inverse is
+    enforceable, and it requires knowing the tree. Core's half — every declared path appears in the
+    change set — asks *you said you would touch these paths, did you?*. This half asks *you touched
+    these paths, did you say you would?*. Together they close the loop; neither alone does.
+
+    `docs/dist/**` is excluded because it is build output. A rendered site changing is a consequence
+    of an authored change, not an authored change, and requiring it to be declared would make every
+    declaration carry generated paths.
+
+    A DELETED path under `docs/` is in scope. Removing a document is a documentation change, and the
+    declaration form for it is an `archive` artifact — which is how spec 2 §2's *migration preserves
+    history* survives contact with a repository where deleting a file is one keystroke.
+  fix_hint: |
+    Declare the artifact at RATIFY, before the work:
+
+      documentation:
+        impact: change
+        artifacts:
+          - action: modify
+            path: docs/delivery/release.adoc
+
+    If the change is genuinely not a documentation change — a typo fix in a rendered artefact, a
+    path you did not mean to touch — the fix is to not touch `docs/`, not to widen the declaration.
+    If it IS one and you did not plan it, the declaration was wrong at RATIFY and re-ratifying is
+    the honest correction.
+  exceptions:
+  - '`docs/dist/**` is generated output and is never required to be declared.'
+  - A repository with no documentation declaration recorded at all is core's concern (companion §4,
+    check 1), not this rule's. This rule fires when a declaration exists and does not cover the diff.
+  - >-
+    An ABSENT change set is not an empty one. If core supplies no change set at all, this rule
+    cannot be evaluated and the capability returns COULD_NOT_CHECK, which BLOCKS — it does not
+    report "nothing undeclared", because that is a claim it is in no position to make. An empty
+    change set is core saying nothing changed, which IS actionable and permits. The two must stay
+    distinct for the same reason NOT_APPLICABLE and COULD_NOT_CHECK must (spec 2 §3).
+metadata:
+  aliases:
+  - DOCS-DECLARATION-002
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/tester.bun/tester.bun.acceptance-binding-declared.convention.yaml

@@ -0,0 +1,49 @@
+schema_version: 1.1.0
+rule_id: tester.bun.acceptance-binding-declared
+kind: rule
+status: active
+name: Every test declares what it proves
+statement: >-
+  A test file carrying a URN MUST also declare `// Acceptance: acc:…` or, for a journey/E2E test, `//
+  Train: …`. Stack-neutral obligation, Bun-specific detector. Realized by
+  `bun_tester_discipline_detector`.
+terms:
+- term_id: acceptance_binding
+  text: >-
+    `// Acceptance: acc:…`, naming the obligation this test discharges.
+- term_id: train_binding
+  text: >-
+    `// Train: …` — the alternative for a journey test, which proves a train rather than a
+    single acceptance.
+content:
+  summary: >-
+    Requires an `Acceptance:` or `Train:` field beside the URN. Files with no URN are skipped — that
+    finding belongs to `test-carries-urn-identity`.
+  normative_text: |
+    A URN says which test this is; the acceptance binding says which OBLIGATION it discharges. Only the second one closes the loop the gate reads.
+    Two binding kinds are accepted because a journey test legitimately proves a train rather than a single acceptance. Forcing every test to name an acceptance would push authors to invent one, which pollutes the plan graph with acceptances that exist only to satisfy a linter.
+  fix_hint: |
+    Name the acceptance the test discharges, or the train it walks:
+
+      // Acceptance: acc:orders:E001-SMOKE-001-renders-row
+      // Train: train:orders:checkout-journey
+  exceptions:
+  - A `Train:` binding satisfies the rule for journey and E2E tests.
+  - Files with no URN are owned by `test-carries-urn-identity`.
+  - Whether the named acceptance EXISTS is a plan-graph question this per-file detector cannot answer.
+metadata:
+  aliases:
+  # Bun realization of the core obligation `tester.coverage.every-acceptance-criterion-must`. Core carries no
+  # shared alias for it, so the lineage is stated here and in the statement.
+  - BUN-ACCEPTANCE-BINDING-DECLARED-001
+  severity: 2
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.acceptance-covers-tag-well-formed.convention.yaml

@@ -0,0 +1,50 @@
+schema_version: 1.1.0
+rule_id: tester.bun.acceptance-covers-tag-well-formed
+kind: rule
+status: active
+name: Per-case @covers tags are well-formed acceptance URNs
+statement: >-
+  A `// @covers` tag above an `it()` MUST name a well-formed `acc:{wagon}:{ACCEPTANCE-ID}` URN. Stack-
+  neutral obligation, Bun-specific detector implementing the two-level binding model. Realized by
+  `bun_tester_discipline_detector`.
+terms:
+- term_id: covers_tag
+  text: >-
+    `// @covers acc:…` above an `it()`, binding one CASE rather than the file.
+- term_id: two_level_binding
+  text: >-
+    file header plus per-case tags. Gives many-cases-to-one-acceptance precision without forcing
+    one acceptance per file.
+content:
+  summary: >-
+    Collects the `// @covers` comment block immediately above each `it()` / `test()` and validates every
+    tag against `acc:{wagon}:{ACCEPTANCE-ID}`.
+  normative_text: |
+    The two-level model is the point. The file header binds the FILE to its acceptances; a `@covers` tag binds ONE test case. That gives many-cases-to-one-acceptance precision without forcing one acceptance per file — the design issue #1783 argued for, and the reason a real 65-spec suite can adopt ATDD without a rename.
+    A malformed tag is `strict` because it is the worst of both worlds: it binds nothing, while looking to a reviewer exactly like a binding that works.
+  fix_hint: |
+    Use the full acceptance URN, not a bare id:
+
+      // @covers E005-UNIT-001                    // wrong — no scheme, no wagon
+      // @covers acc:orders:E005-UNIT-001         // right
+
+    Several tags on one line are allowed; a case may cover more than one acceptance.
+  exceptions:
+  - Cases with no `@covers` tag are not required to have one — the file header binding still applies.
+  - Only the tag's SHAPE is validated; resolution against `plan/` is a graph-level concern.
+metadata:
+  aliases:
+  # Bun realization of the core obligation `tester.coverage.every-acceptance-criterion-must`. Core carries no
+  # shared alias for it, so the lineage is stated here and in the statement.
+  - BUN-COVERS-TAG-WELL-FORMED-001
+  severity: 3
+  # Core's tester nodes are largely `documentation-only`, which core's
+  # coverage_report treats as never-fails-the-build. That is right for retrofitting
+  # and wrong for a new stack: a coverage-binding rule that cannot fail is a rule
+  # that will not be adopted. Gating dispositions here; a repo adopting on an
+  # existing suite records a ratchet baseline instead.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_tester_discipline_detector

package/conventions/tester.bun/tester.bun.acceptance-resolves-to-declared.convention.yaml

@@ -0,0 +1,61 @@
+schema_version: 1.1.0
+rule_id: tester.bun.acceptance-resolves-to-declared
+kind: rule
+status: active
+name: A test's Acceptance / WMBT binding names an artifact the plan declares (Bun)
+statement: >-
+  A test's `// Acceptance:` and `// WMBT:` headers MUST name artifacts the plan actually declares.
+  Declaring a binding is not the same as having one: a suite bound to an acceptance that exists
+  nowhere is attributed to nothing, and every coverage figure computed from it is fiction. Core owns
+  the shape of these artifacts; only a per-stack detector can see whether a Bun test resolves into
+  them.
+implementation:
+  type: validator
+  ref: tester.bun.acceptance-resolves-to-declared
+content:
+  summary: >-
+    Resolves each Bun test's declared binding against the plan. The JS realization collects every
+    `acc:` / `wmbt:` URN stated anywhere under `plan/**`, then flags a test whose `// Acceptance:` or
+    `// WMBT:` header names one the plan never mentions. Member of the `bun_tester_discipline_detector`
+    FAMILY detector (checks/t_acceptance_resolves.mjs).
+  normative_text: |
+    Its sibling `tester.bun.acceptance-binding-declared` asks only whether a header is PRESENT, which
+    a test satisfies by naming anything at all. Measured on a consumer, a test bound to
+    `acc:does-not-exist:E999-NEVER-DECLARED` passed every gated rule in this workspace. That is the
+    recurring defect this hub keeps finding: a NAME accepted where a CLAIM is required. The two rules
+    are complementary — one requires the binding to exist, this one requires it to be true.
+
+    Declared URNs are read as TOKENS rather than parsed structurally, on purpose: acceptances are
+    stated under several keys across wagon, feature and WMBT documents, and a reference resolves if
+    the plan states that URN anywhere. Over-accepting is the safe direction — the failure this rule
+    exists to catch is a reference to something the plan never mentions.
+
+    NOT_APPLICABLE when the consumer declares no acceptances at all: a repository with no plan has
+    nothing to resolve against, and reporting there would fire on every unplanned project rather than
+    on a broken reference.
+  fix_hint: |
+    Point the header at an acceptance the plan declares, or declare the acceptance:
+
+      // URN: test:orders:checkout:E001-SMOKE-001-renders-row
+      // Acceptance: acc:orders:E001-SMOKE-001-renders-row   # stated in plan/orders/E001.yaml
+      // WMBT: wmbt:orders:E001
+
+    A renamed acceptance is the common cause — the plan moved and the header did not. This rule is
+    `strict`: a test bound to an artifact that does not exist is not suppressible and fails CI.
+  exceptions:
+    - A test carrying no binding header at all is NOT reported here; that is
+      `tester.bun.acceptance-binding-declared`'s obligation, and reporting both would double-count
+      one defect.
+metadata:
+  aliases:
+    - BUN-ACCEPTANCE-RESOLVES-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.2.0
+  core_design_refs:
+    - afokapu/atdd#1246
+terms:
+  - term_id: resolvable_binding
+    text: >-
+      an `// Acceptance:` or `// WMBT:` header whose URN is stated somewhere in the consumer's plan,
+      so the test is attributable to a declared obligation rather than to a name.

package/conventions/tester.bun/tester.bun.interlocking-production-runner-used.convention.yaml

@@ -0,0 +1,76 @@
+schema_version: 1.1.0
+rule_id: tester.bun.interlocking-production-runner-used
+kind: rule
+status: active
+name: Interlocking tests exercise the production runners, not mocks (Bun)
+statement: >-
+  A test that exercises an interlocking MUST drive the production runtime objects — `InterlockingRunner`
+  (route resolution) and `TrainRunner` (linear train execution), the core afokapu/atdd#1251 call model —
+  and MUST NOT substitute a mock, a substituted runner, or a
+  hand-built route resolver for them. This is the Bun-stack realization of the agnostic core
+  obligation `tester.interlocking.production-runner-used`; its JS detector (a member of the
+  `bun_interlocking_coverage` FAMILY) scans the consumer's `e2e/**/*.ts` interlocking tests and flags
+  any that fail to reference both production runner symbols or that carry a forbidden substitution
+  pattern. An interlocking test that mocks the route-control path is a DESCRIPTIVE green.
+implementation:
+  type: validator
+  ref: tester.bun.interlocking-production-runner-used
+content:
+  summary: >-
+    A "interlocking tests use the production runners, not mocks" obligation, rendered for the Bun
+    backend. The JS realization scans each interlocking-related `e2e/**/*.ts` test and enforces two
+    checks: it references both `InterlockingRunner` and `TrainRunner`, and it carries none of the
+    forbidden substitution patterns (comments masked).
+  normative_text: |
+    The core runtime call model (afokapu/atdd#1251) is `Station Master -> InterlockingRunner.resolveTrain
+    -> TrainRunner.execute`. A test that claims to exercise an interlocking route but replaces either
+    runner with a test double exercises the double, not production route control.
+
+    REQUIRED production symbols an interlocking test must reference:
+      - InterlockingRunner
+      - TrainRunner
+
+    FORBIDDEN substitution patterns (any one is a violation):
+      - MockInterlockingRunner / MockTrainRunner
+      - mock.module(...) replacing a runner module — bun:test's own idiom, and the one that
+        matters most here: it swaps the ENTIRE route-control module
+      - spyOn(...) / mock(...) / mock.restore(...) aimed at a runner (bun:test)
+      - vi.mock(...) / jest.mock(...) around a runner module, for a suite migrating in
+      - vi.spyOn(...) / jest.spyOn(...) replacing runner behavior (resolveTrain / execute)
+      - a hand-built route resolver replacing InterlockingRunner (a locally defined `resolveTrain`
+        function or a `*Resolver` class standing in for the production runner)
+
+    WHICH per-stack discovery applies (here: Bun `e2e/**/*.ts` scanned for the production symbols and
+    the forbidden patterns) is delegated to this realization.
+  fix_hint: |
+    Rewrite the flagged interlocking test to drive the real runners: import and call
+    `new InterlockingRunner(interlockingYamlPath).resolveTrain(action, inputs)` to get the selected
+    trainId, then `new TrainRunner(selectedTrainId).execute(...)`. Delete any `MockInterlockingRunner` /
+    `MockTrainRunner`, any `mock.module` / `spyOn` / `mock` / `mock.restore` (bun:test) or
+    `vi.mock` / `vi.spyOn` / jest equivalent aimed at the runners or their `resolveTrain` / `execute`
+    methods, and any locally hand-built route resolver. This rule is `strict`: an interlocking test that
+    mocks the route-control path is a descriptive green proving nothing about production and blocks.
+  exceptions:
+    - Non-interlocking e2e tests (no reference to any interlocking route/train/interlocking token and no
+      runner symbol) are out of scope — they are not interlocking tests.
+    - Per-stack renderings other than Bun are owned by their own workspace packages.
+metadata:
+  aliases:
+    - BUN-TESTER-INTERLOCKING-PRODUCTION-RUNNER-USED-001
+  severity: 1
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: production_runner
+    text: >-
+      one of the two runtime objects in the core afokapu/atdd#1251 call model — `InterlockingRunner`
+      (resolves a guarded route to exactly one trainId) and `TrainRunner` (executes the selected train).
+  - term_id: forbidden_substitution
+    text: >-
+      a test double that replaces a production runner: `MockInterlockingRunner`/`MockTrainRunner`, a
+      `mock.module`/`spyOn`/`mock` (bun:test) or `vi.mock`/`vi.spyOn` (or jest) aimed at a runner
+      or its `resolveTrain`/`execute`, or a hand-built
+      route resolver standing in for InterlockingRunner.