@afokapu/atdd-bun 0.10.41 → 0.10.43

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

@@ -21,12 +21,28 @@ content:
     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.
+    The binding is a claim, not bookkeeping. A syntactically valid Acceptance or Train header is truthful only when the test actually exercises that declared subject and asserts the outcome it requires. Binding a convenient existing acceptance to an unrelated case creates false coverage while satisfying the structural detector.
+    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. The same principle applies in reverse: never select or invent a binding merely to make the test attributable.
   fix_hint: |
-    Name the acceptance the test discharges, or the train it walks:
+    Derive the binding from the plan artifact the test actually proves.
 
-      // Acceptance: acc:orders:E001-SMOKE-001-renders-row
-      // Train: train:orders:checkout-journey
+    Claim:
+      * identify the declared acceptance whose behavior this file exercises and asserts, or the declared train the journey actually walks.
+
+    Bind:
+      * use that exact plan identity in the header:
+
+        // Acceptance: acc:orders:E001-SMOKE-001-renders-row
+        // Train: train:orders:checkout-journey
+
+    Avoid:
+      * picking any resolvable acceptance merely to satisfy coverage,
+      * changing the claimed binding to match a test that proves different behavior,
+      * inventing a new acceptance or train solely so an otherwise orphaned test can bind.
+
+    Verify:
+      * the test stimulus exercises the bound subject,
+      * its behavioral witness proves the bound obligation rather than an adjacent implementation detail.
   exceptions:
   - A `Train:` binding satisfies the rule for journey and E2E tests.
   - Files with no URN are owned by `test-carries-urn-identity`.

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

@@ -21,14 +21,20 @@ content:
     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.
+    A `@covers` tag is therefore a semantic claim as well as a token. The case should name only acceptances whose behavior it directly exercises and whose outcome it actually asserts. Adding a valid acceptance URN merely to increase apparent coverage turns precise traceability into fiction.
+    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. A well-formed but semantically false tag is outside this detector's static reach, so the convention guidance must prevent that form of gaming.
   fix_hint: |
-    Use the full acceptance URN, not a bare id:
+    Use the full acceptance URN and bind only behavior this case actually proves:
 
-      // @covers E005-UNIT-001                    // wrong — no scheme, no wagon
-      // @covers acc:orders:E005-UNIT-001         // right
+      // @covers E005-UNIT-001                     // wrong — no scheme, no wagon
+      // @covers acc:orders:E005-UNIT-001          // structurally valid
 
-    Several tags on one line are allowed; a case may cover more than one acceptance.
+    Before adding a valid tag:
+      * identify the acceptance claim exercised by this exact case,
+      * confirm the case's stimulus reaches that behavior,
+      * confirm at least one behavioral assertion witnesses its declared outcome.
+
+    Several tags on one line are allowed when one case genuinely proves more than one acceptance. Do not add extra tags for coverage credit when the case does not exercise and assert those obligations.
   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.

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

@@ -19,29 +19,32 @@ content:
     `// 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.
+    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.
+
+    Resolution is still only the structural half of truth. A header can resolve to a real acceptance and still be semantically false if the case exercises or asserts something else. During test authoring, the plan is authoritative: repair a stale or mistaken binding to the acceptance the case genuinely proves. Do not create, rename, or repurpose a plan acceptance merely to make an already-written test resolve; adding behavior to the plan is planner work and must be justified by the behavior itself, not by this detector.
+
+    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:
+    Repair the binding from the plan, not the plan from the test.
+
+    If the acceptance was renamed or the header is stale:
+      * point the test at the declared acceptance it actually exercises and proves.
+
+        // 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
+
+    If the test proves different behavior:
+      * bind it to that behavior's existing declared acceptance,
+      * adjust the test rather than the label when the current case does not prove the claimed 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
+    If no declared acceptance represents the intended behavior:
+      * do not invent one merely to clear this tester finding,
+      * return to the authorized planning flow so the behavior can be declared deliberately before the test claims coverage.
 
-    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.
+    A renamed acceptance is the common mechanical cause; a convenient but semantically unrelated acceptance is the dangerous gaming case. 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

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

@@ -25,6 +25,10 @@ content:
     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.
+    Referencing both production symbols is the detector's structural proxy; it is not sufficient semantic
+    proof by itself. The case must drive the production objects with guard-relevant inputs and observe the
+    route/train behavior it claims. Importing or instantiating the real runners while obtaining the asserted
+    result from a parallel fake path would be another descriptive green.
 
     REQUIRED production symbols an interlocking test must reference:
       - InterlockingRunner
@@ -43,13 +47,31 @@ content:
     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.
+    Rewrite the flagged case so the production runner path is the path that produces the asserted evidence.
+
+    Boundary:
+      * import and call `new InterlockingRunner(interlockingYamlPath).resolveTrain(action, inputs)`,
+      * pass its selected `trainId` into the production `TrainRunner`,
+      * execute the selected train through the real runtime path.
+
+    Witness:
+      * assert the selected train and the route- or acceptance-specific result produced by its execution.
+
+    Remove:
+      * `MockInterlockingRunner` / `MockTrainRunner`,
+      * `mock.module` / `spyOn` / `mock` / `mock.restore` aimed at the runners,
+      * `vi.mock` / `vi.spyOn` / Jest equivalents around runner behavior,
+      * any locally hand-built route resolver standing in for InterlockingRunner.
+
+    Avoid:
+      * importing the production symbols only to satisfy this detector while assertions still depend on a fake path,
+      * asserting a plan literal without driving production resolution and execution.
+
+    Verify:
+      * breaking production `resolveTrain` or `execute` behavior would make the test red,
+      * the evidence comes from the real runner chain.
+
+    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.

package/conventions/tester.bun/tester.bun.interlocking-route-coverage.convention.yaml

@@ -28,17 +28,42 @@ content:
     The interlocking YAML is authoritative for the guarded route space (afokapu/atdd#1248): every entry
     under `routes:` is an admissible route the InterlockingRunner can resolve to exactly one `trainId`
     (afokapu/atdd#1251). Coverage of that route space is a tester obligation — an unexercised route is a
-    branch of production route control that no test ever drives. A route is COVERED when at least one
-    `e2e/**/*.ts` test references it by its `routeId` or by the `trainId` it resolves to. WHICH per-stack
-    discovery applies (here: Bun `e2e/**/*.ts` scanned for the route/train tokens) is delegated to
-    this realization; other stacks render the same obligation in their own e2e layout.
+    branch of production route control that no test ever drives. A route is COVERED to the detector when at
+    least one `e2e/**/*.ts` test references it by its `routeId` or by the `trainId` it resolves to.
+    That token is a discovery proxy, not the testing objective. A meaningful route proof must construct the
+    route's guard-relevant inputs, drive production resolution, and assert that the declared route selects
+    the expected train before that train is executed. Merely mentioning the route or train in executable
+    test text can satisfy lexical discovery while proving no route behavior.
+    WHICH per-stack discovery applies (here: Bun `e2e/**/*.ts` scanned for the route/train tokens) is
+    delegated to this realization; other stacks render the same obligation in their own e2e layout.
   fix_hint: |
-    Add an end-to-end test that exercises the flagged route through the production runners. Place it
-    under `e2e/interlockings/<interlocking_slug>/<slug>.routes.test.ts` and drive
-    `new InterlockingRunner(...).resolveTrain(...)` so the route's guard-true case resolves to its
-    expected `trainId`, then have `TrainRunner` execute it. Reference the route by its `routeId` or
-    `trainId` so coverage is machine-discoverable. Do NOT satisfy this with a mock resolver or a
-    descriptive assertion. This rule is `strict`: an admissible route with no covering e2e test blocks.
+    Add an end-to-end proof of the flagged route rather than merely adding a discoverable token.
+
+    Claim:
+      * read the declared route, its guard, and its resolved `trainId`,
+      * identify the guard-true inputs that distinguish this route from its alternatives.
+
+    Stimulus:
+      * place the test under `e2e/interlockings/<interlocking_slug>/<slug>.routes.test.ts`,
+      * drive `new InterlockingRunner(...).resolveTrain(action, inputs)` with those inputs,
+      * pass the selected train into `TrainRunner` and execute it.
+
+    Witness:
+      * assert that production resolution selected the route's declared `trainId`,
+      * assert the route- or acceptance-specific execution outcome when one is declared.
+
+    Avoid:
+      * inserting a `routeId` / `trainId` literal solely so lexical coverage sees it,
+      * a mock resolver or hand-built substitute for production route control,
+      * a descriptive assertion that restates the plan without exercising resolution,
+      * bypassing TrainRunner after proving only selection.
+
+    Verify:
+      * the case would fail if the route guard or route-to-train mapping regressed,
+      * the production runners actually execute the selected path,
+      * the discoverable route/train token corresponds to behavior the case genuinely proves.
+
+    This rule is `strict`: an admissible route with no covering e2e test blocks.
   exceptions:
     - YAML under the interlocking scope that declares no `routes:` (the `_interlockings.yaml` registry
       index and generated projections) carries no admissible route space and is out of scope.

package/conventions/tester.bun/tester.bun.red-behavioral-assertion.convention.yaml

@@ -22,13 +22,47 @@ content:
     For each `it()` in a RED-phase file, brace-matches the case body and reports it when it contains no
     `expect(` at all, or when every `expect(` is an existence matcher.
   normative_text: |
-    RED's entire job is to fail before the implementation exists. `expect(checkout).toBeDefined()` passes the moment an empty function is exported, so it goes green against a stub — the test was never RED in any meaningful sense, and the acceptance it claims to prove is unproven from that point forward.
-    The rule is deliberately narrow: it fires only when EVERY assertion in the case is vacuous. A case that checks existence and then checks behaviour is fine, because the behavioural assertion is the one that must fail.
+    RED's entire job is not merely to be red; it is to construct the smallest executable proof of the declared acceptance before implementation makes that proof pass. `expect(checkout).toBeDefined()` passes the moment an empty function is exported, so it goes green against a stub — the acceptance it claims to prove is unproven from that point forward.
+    Treat the acceptance as the source of the test, not the implementation. The acceptance identifies the claim; any declared harness and execution context constrain the proof boundary; its Given supplies only required preconditions; its When supplies the primary stimulus; and its Then supplies the behavioral witness. The assertion should observe the consequence the acceptance promises, not an implementation mechanism used to produce it.
+    A useful RED sensor is counterfactually sensitive: if the named behavior were absent, inverted, or replaced by a stub, the behavioral assertion would fail. Expected values computed by the production subject, assertions on mocks that replace the behavior being proved, or unrelated assertions added only to satisfy this detector can all produce structurally acceptable tests that prove the wrong thing.
+    The detector is deliberately narrower than that semantic obligation: it fires only when EVERY assertion in the case is vacuous. A case that checks existence and then checks behaviour is not flagged, because the behavioral assertion is the machine-visible proxy. The convention guidance defines what that assertion is for.
   fix_hint: |
-    Assert the behaviour that does not yet exist:
+    Construct the RED case from the declared acceptance rather than from the code you expect to write.
 
-      expect(checkout).toBeDefined();                        // passes against a stub
-      expect(() => checkout({ items: [] })).toThrow("CART_EMPTY");  // must fail first
+    Claim:
+      * read the bound Acceptance / @covers declaration and identify the one behavior this case is meant to prove,
+      * derive the expected outcome from the acceptance's Then; do not invent a more convenient assertion from the current implementation.
+
+    Boundary:
+      * honor the planned harness and execution context when they are declared,
+      * enter through the narrowest boundary that still proves the declared behavior,
+      * do not move inward to an easier internal seam when that would stop exercising the thing the acceptance claims.
+
+    Stimulus:
+      * translate the acceptance's When into one primary action,
+      * create only the Given state required for that action.
+
+    Witness:
+      * assert the observable consequence named by the acceptance — for example an exact error, status/body, state change, emitted item, or other declared outcome,
+      * prefer a witness that would turn red if the behavior were removed or inverted.
+
+    Avoid:
+      * existence-only assertions such as `toBeDefined()` as the behavioral proof,
+      * mocking or substituting the subject or collaboration whose behavior the acceptance is meant to prove,
+      * asserting incidental implementation details instead of the declared outcome,
+      * computing the expected value with the production code under test,
+      * copying the production algorithm into the test,
+      * adding an unrelated behavioral assertion merely to clear this detector,
+      * broadening one case to prove several unrelated behaviors.
+
+    Verify:
+      * run the target case against the current implementation,
+      * confirm execution reaches the intended stimulus and behavioral oracle,
+      * confirm the behavioral expectation is red because the required behavior is absent or wrong — not because of syntax, imports, fixture setup, unavailable infrastructure, or an unrelated exception,
+      * ask the counterfactual: if the acceptance behavior disappeared, would this case definitely turn red?
+
+      expect(checkout).toBeDefined();                                 // passes against a stub
+      expect(() => checkout({ items: [] })).toThrow("CART_EMPTY");   // behavioral witness
   exceptions:
   - Only RED-phase files are scanned.
   - A case mixing existence and behavioural assertions is not flagged.

package/conventions/tester.bun/tester.bun.red-fails-first.convention.yaml

@@ -24,16 +24,33 @@ content:
     Flags any `Phase: RED` file containing none of the core TypeScript RED markers. `test.failing(` is
     bun:test's spelling of vitest's `it.fails(` and is accepted identically.
   normative_text: |
-    Whether a test ACTUALLY fails first is a RUNTIME property no static detector can observe. Core supplies the decidable STRUCTURAL proxy — a guaranteed-fail marker must be present — and that proxy is exactly what a per-stack detector can check. The obligation is agnostic; only the marker syntax is stack-specific.
-    This rule and `red-behavioral-assertion` are complementary, not redundant. That one asks whether the assertions are about behaviour; this one asks whether anything guarantees the test is red at all.
+    Whether a test ACTUALLY fails first is a RUNTIME property no static detector can observe. Core therefore supplies a decidable STRUCTURAL proxy — a guaranteed-fail marker must be present — and that proxy is exactly what this per-stack detector checks. The obligation is agnostic; only the marker syntax is stack-specific.
+    The marker is a detector aid, not the RED objective and not the behavioral oracle. A test whose only meaningful reason for failing is `expect.fail(...)`, an unconditional throw before the stimulus, or a failing wrapper around an otherwise passing case is mechanically red while the acceptance remains unproven. The case must also contain the behavioral witness required by `red-behavioral-assertion`.
+    The two rules are therefore complementary: `red-behavioral-assertion` asks whether the case encodes the missing behavior; this rule gives the static gate evidence that the artifact is intentionally in RED. The strongest local check is causal: apart from the structural marker, the behavioral witness itself should fail for the expected missing-behavior reason.
   fix_hint: |
-    Add a marker that cannot pass until the implementation exists:
+    Establish the behavioral oracle first, then add the guaranteed-fail marker required by the static RED gate.
 
-      expect.fail("checkout rejection not implemented yet");
-      // or
-      throw new Error("Not implemented: checkout rejection");
+    Behavioral proof:
+      * derive the case from the bound acceptance's Given / When / Then,
+      * include an assertion that would fail because the required behavior is not implemented correctly.
 
-    Remove it in GREEN, when the behavioural assertion carries the test on its own.
+    Structural proxy:
+      * add one accepted RED marker so the static detector can recognize the phase:
+
+        expect.fail("checkout rejection not implemented yet");
+        // or
+        throw new Error("Not implemented: checkout rejection");
+
+    Avoid:
+      * using the marker as the only meaningful reason the test is red,
+      * throwing before the declared stimulus is exercised,
+      * wrapping a vacuous or already-passing case in `it.fails` / `test.failing`,
+      * weakening the behavioral assertion because the marker already guarantees failure.
+
+    Verify:
+      * run the target case and confirm it reaches the intended behavior,
+      * confirm the behavioral oracle would still fail for the expected reason without relying on the unconditional marker,
+      * remove the marker in GREEN only when the behavioral assertion itself carries the proof and passes.
   exceptions:
   - Only RED-phase files are scanned.
   - "`it.fails` / `test.failing` are markers, NOT self-skips — `no-self-skip` deliberately does not flag them."

package/conventions/tester.bun/tester.bun.security-auth.convention.yaml

@@ -21,13 +21,31 @@ content:
     Identifies security tests from the URN and flags those whose body contains no denial assertion.
   normative_text: |
     A security test that only walks the happy path is a SILENT GREEN GAP — the worst shape a test can have. It passes CI, the gate counts it as covering the security acceptance, and it proves nothing about the denial path, which is the only path the acceptance is actually about.
+    The denial assertion should be the witness for the specific security claim, not a generic refusal added to satisfy the detector. Construct the unauthorized or under-privileged stimulus described by the acceptance and assert the refusal it requires. When the acceptance protects a mutation or other side effect, also observe that the protected effect did not occur; returning 403 after performing the mutation is still a security failure.
     Identification is by URN kind segment rather than filename, consistent with the rest of this package: the header is authoritative.
   fix_hint: |
-    Assert the refusal, not the permission:
+    Prove the refusal named by the security acceptance.
+
+    Stimulus:
+      * construct the missing, invalid, or insufficient authorization state the acceptance describes,
+      * exercise the real protected boundary.
+
+    Witness:
+      * assert the expected denial signal — for example 401, 403, a permission error, rejection, or throw,
+      * when the acceptance protects a side effect, also assert that the protected state or action remains unchanged.
 
       const res = await fetch("/orders", { method: "POST" });   // anonymous
       expect(res.status).toBe(403);
 
+    Avoid:
+      * using a happy-path permission case as the only security proof,
+      * adding an unrelated 403 assertion that does not come from the bound protected operation,
+      * mocking away the authorization decision the acceptance is meant to prove.
+
+    Verify:
+      * the case would turn red if authorization were accidentally removed,
+      * where applicable, a denied request cannot still perform the protected effect.
+
     A happy-path case is welcome too — but it cannot be the only one.
   exceptions:
   - Only tests whose URN carries a SEC / RLS / AUTH kind segment are scanned.

package/conventions/tester.bun/tester.bun.security-input.convention.yaml

@@ -21,13 +21,31 @@ content:
     Identifies input-validation tests from the URN and flags those with no rejection assertion.
   normative_text: |
     A test that submits a well-formed payload and checks it succeeds proves the parser works on good input. The obligation an input-validation acceptance carries is about BAD input — malformed, missing, adversarial — and that is precisely what a happy-path test does not touch.
+    The rejection assertion should witness the specific invalid condition declared by the acceptance, not merely any error. Construct the malformed input named by the claim, drive it through the intended boundary, and assert the refusal. When accepting the bad input could create or mutate state, also verify that the rejected request left that protected effect absent.
     Same silent-green-gap shape as `security-auth`, and it is grouped with the security family for the same reason: unvalidated input is the entry point for most of what the security rules defend against.
   fix_hint: |
-    Assert the rejection:
+    Prove rejection of the invalid input the acceptance actually names.
+
+    Stimulus:
+      * construct the malformed, missing, boundary, or adversarial value from the acceptance,
+      * send it through the same boundary production receives.
+
+    Witness:
+      * assert the acceptance-specific rejection — exact error, 400/422 response, rejection, or throw,
+      * when invalid input could mutate state, assert that the invalid operation produced no protected side effect.
 
       expect(() => parseOrder({ sku: null })).toThrow("INVALID_SKU");
       // or over HTTP
       expect(res.status).toBe(422);
+
+    Avoid:
+      * testing only a well-formed payload,
+      * triggering some unrelated error and treating any rejection as proof,
+      * bypassing the production validation boundary with a direct fixture assertion.
+
+    Verify:
+      * the case would turn red if validation for the declared bad input were removed,
+      * the observed failure is caused by the intended validation rule, not by test setup.
   exceptions:
   - Only tests whose URN carries an INPUT / VALIDATION / VALIDATE kind segment are scanned.
   - Any of the listed rejection signals satisfies the rule.

package/conventions/tester.bun/tester.bun.smoke-no-collaborator-substitution.convention.yaml

@@ -21,9 +21,29 @@ content:
     Flags any substitution call in a SMOKE-phase file, reporting the exact line.
   normative_text: |
     Substituting a collaborator turns a SMOKE test into a unit test wearing a SMOKE label. The damage is not that the test is bad — it may be an excellent unit test — but that the gate counts it as evidence the real path works, when the real path is precisely the part that was replaced.
+    In a SMOKE proof the boundary is part of the claim. The test must enter through the real assembled path and preserve the collaborators whose behavior constitutes that path. Replacing one because it is expensive, inconvenient, or difficult to arrange changes the question the test answers rather than making the same proof cheaper.
     This is the failure that makes a green suite compatible with a broken deployment, which is the specific outcome ATDD's phase separation exists to prevent.
   fix_hint: |
-    Let the SMOKE test exercise the real collaborator against real infrastructure, and move the substituted version into a UNIT-phase test where the substitution is honest and expected.
+    Preserve the real proof boundary.
+
+    Boundary:
+      * exercise the production collaborator through the assembled path required by the SMOKE acceptance,
+      * use the real infrastructure or environment that the declared smoke proof is meant to verify.
+
+    Prefer:
+      * arrange only the minimum preconditions needed for the declared stimulus,
+      * observe the acceptance-specific external result after the real collaborator runs.
+
+    Avoid:
+      * replacing the collaborator whose behavior the SMOKE claim depends on,
+      * moving the test inward to a unit seam merely because that path is easier to control,
+      * relabeling the case as SMOKE after using mocks or spies that bypass production behavior.
+
+    Verify:
+      * the case would fail if the real collaborator or production wiring were broken,
+      * the observable assertion proves the bound acceptance rather than the test fixture.
+
+    If substitution is the intended proof technique, move that case into a UNIT-phase test where the substitution is honest and expected.
   exceptions:
   - Only SMOKE-phase files are scanned; UNIT tests may substitute freely.
 metadata:

package/conventions/tester.bun/tester.bun.smoke-observable-assertion.convention.yaml

@@ -21,17 +21,34 @@ content:
   summary: >-
     Reports a SMOKE case that makes assertions but touches none of the observable channels.
   normative_text: |
-    A SMOKE test exists to prove the system does something a person could witness. A case that builds an object and asserts on its fields has proven that the constructor works — which is a unit test's job — while carrying the label that tells the gate real behaviour was exercised.
-    The observable vocabulary is stack-specific and that is the whole reason this rule is re-realized rather than shared: for this stack the canonical observation is an HTTP response and the markup inside it, because that markup is what htmx puts in front of the user.
+    A SMOKE test exists to prove the system does something a person or operator could witness. A case that builds an object and asserts on its fields has proven that the constructor works — which is a unit test's job — while carrying the label that tells the gate real behaviour was exercised.
+    Merely touching an observable channel is not enough semantically. The witness must correspond to the bound acceptance's promised outcome. A generic `200` can prove that a server answered while leaving the actual acceptance — for example that the newly created order is visible — completely unproven.
+    The observable vocabulary is stack-specific and that is the whole reason this rule is re-realized rather than shared: for this stack the canonical observation is often an HTTP response and the markup inside it, because that markup is what htmx puts in front of the user. The detector recognizes the channel; the convention tells the agent to choose the acceptance-specific evidence on that channel.
   fix_hint: |
-    Assert what an operator would see:
+    Assert what an operator would observe about the bound acceptance.
+
+    Claim:
+      * read the acceptance's Then and identify the externally visible consequence that discharges it.
+
+    Witness:
+      * assert on the real HTTP response, rendered markup, stdout/stderr, exit code, persisted state, or other observable channel,
+      * make the assertion specific enough that the acceptance behavior disappearing would turn the case red.
 
       const order = buildOrder({ sku: "x" });
-      expect(order.sku).toBe("x");       // internal
+      expect(order.sku).toBe("x");                     // internal; not SMOKE evidence
 
       const res = await fetch("/orders");
-      expect(res.status).toBe(200);
-      expect(await res.text()).toContain("order-1");   // observable
+      expect(res.status).toBe(200);                    // useful transport evidence
+      expect(await res.text()).toContain("order-1");   // acceptance-specific observable witness
+
+    Avoid:
+      * treating any observable assertion as sufficient when it does not prove the declared outcome,
+      * asserting only on objects the test constructed itself,
+      * checking internal calls or mocks instead of the resulting system behavior.
+
+    Verify:
+      * the real path was exercised,
+      * the witness would fail if the bound acceptance behavior regressed.
   exceptions:
   - Only SMOKE-phase files are scanned.
   - Cases with no assertions are skipped — other rules own that.

package/conventions/tester.bun/tester.bun.test-phase-declared.convention.yaml

@@ -19,11 +19,17 @@ content:
     Requires a `Phase:` field from the closed vocabulary.
   normative_text: |
     The phase is not documentation — it is what selects which other rules apply. A RED test must fail first and must assert behaviour; a SMOKE test must assert something operator-observable and must not substitute collaborators. Without a declared phase none of those obligations can be evaluated, so an undeclared test is exempt from the entire quality surface by omission.
-    That is why this rule exists separately from the URN rule: a test can be perfectly identified and still be ungoverned.
+    Phase selection is part of the proof contract, not a way to choose the easiest rule set. Declare the phase that matches what the test is actually doing and the proof boundary it exercises. In particular, do not relabel a real-path SMOKE or assembled E2E proof as UNIT merely to permit substitution, and do not label a passing or vacuous case RED merely because a RED marker is easy to add.
+    That is why this rule exists separately from the URN rule: a test can be perfectly identified and still be ungoverned or governed by the wrong obligations.
   fix_hint: |
-    Declare the phase the test belongs to:
+    Derive the phase from the test's actual role; do not choose a weaker label to silence a phase-gated rule.
 
-      // Phase: SMOKE
+      // Phase: RED     // the current acceptance proof is intentionally failing first
+      // Phase: UNIT    // isolated local behavior
+      // Phase: SMOKE   // real assembled path / infrastructure with operator-observable evidence
+      // Phase: E2E     // end-to-end journey through the assembled system
+
+    Verify that the declared phase matches the boundary the case really exercises and that the corresponding phase-specific conventions now apply.
   exceptions:
   - Files with no URN are skipped.
   - The vocabulary is fixed by core; a new phase is a core change, not an extension one.

package/conventions/tester.htmx/tester.htmx.e2e-binds-declared-subject.convention.yaml

@@ -12,9 +12,26 @@ terms:
     A unit test that merely mentions a journey URN in a string is not one.'
 content:
   summary: A journey spec binds to a train or journey plan/ declares.
-  normative_text: 'A spec bound to an undeclared subject is orphaned: it can pass forever while the plan it claims
-    to cover says nothing about it.'
-  fix_hint: Bind the spec to the declared id, or declare the train or journey.
+  normative_text: |
+    The binding is how a browser test is traced to the plan it exercises. A spec with no binding, two bindings, or an id the planner would reject cannot be traced.
+    Resolution is necessary but not sufficient: the declared train or journey must also be the subject the spec actually walks. Binding an arbitrary declared subject merely to make the file resolvable creates false journey coverage. Conversely, do not declare a new train or journey solely to rescue an already-written spec; the plan should change only because the product behavior requires that subject.
+  fix_hint: |
+    Bind the spec to the declared train or journey it actually exercises.
+
+    Derive:
+      * identify the plan subject reached by the spec's entrypoint and interactions,
+      * use that exact declared id in the header.
+
+    Avoid:
+      * choosing any resolvable subject merely to clear this finding,
+      * changing the binding to match a convenient test that proves another journey,
+      * declaring a new train or journey solely so the spec has something to bind.
+
+    Verify:
+      * the browser path actually walks the bound subject,
+      * the final observable assertion proves that subject's user-facing behavior.
+
+    If the intended subject is genuinely absent from the plan, return to the authorized planning flow rather than inventing it inside the tester repair.
   exceptions:
   - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
   - A repository with no plan (no trains, no journeys) is out of scope.

package/conventions/tester.htmx/tester.htmx.train-e2e-coverage.convention.yaml

@@ -13,9 +13,30 @@ terms:
     A unit test that merely mentions a journey URN in a string is not one.'
 content:
   summary: Every declared train has a browser spec.
-  normative_text: 'A train with no browser spec is a silent gap: the journey it declares can regress with nothing
-    turning red.'
-  fix_hint: 'Add `e2e/<train-slug>.e2e.ts` bound with `// Train: <train id>`.'
+  normative_text: |
+    A train with no browser spec is a silent gap: the journey it declares can regress with nothing turning red.
+    The `// Train:` binding is the detector's coverage handle, not the proof itself. A meaningful browser spec starts from the declared user-facing entrypoint, performs the interactions that make the train relevant, and asserts the user-observable business outcome the journey promises. A spec that only binds the train, navigates successfully, or mentions its identifier can satisfy structural coverage while leaving the journey behavior unproven.
+  fix_hint: |
+    Add `e2e/<train-slug>.e2e.ts` bound with `// Train: <train id>`, then make that spec prove the train rather than merely name it.
+
+    Claim:
+      * read the declared train/journey behavior and identify the user-observable outcome it is meant to deliver.
+
+    Stimulus:
+      * enter through the declared user-facing entrypoint,
+      * perform the real browser interactions that exercise the train.
+
+    Witness:
+      * assert the final user-visible business outcome, not only navigation, a 200 response, or an internal state token.
+
+    Avoid:
+      * adding the Train header solely for coverage credit,
+      * calling an internal handler instead of walking the assembled journey,
+      * seeding the final result directly,
+      * asserting only that the page loaded while the train behavior itself remains unobserved.
+
+    Verify:
+      * the spec would turn red if the train's user-facing behavior regressed.
   exceptions:
   - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
   - The rule reports at the train's plan file, where the gap was declared.

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.41",
+  "version": "0.10.43",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
@@ -122,21 +122,21 @@
     "conventions/planner.telemetry/planner.telemetry.logical-ownership.convention.yaml": "6dd666a22fd7fd0cb6e5fe5505665c8889a504ee929fdebf3aee019df4aac2b4",
     "conventions/planner.telemetry/planner.telemetry.metric-cardinality.convention.yaml": "e61831f207ad4f09be983b300cbedc40f6ad08a4b2483612fc195e2343be93f6",
     "conventions/planner.telemetry/planner.telemetry.tracking-plan-schema.convention.yaml": "5453cdf438dc5bdc72bbe5828b089e4090b865112f6a1550bb70e2c7c72a0cdf",
-    "conventions/tester.bun/tester.bun.acceptance-binding-declared.convention.yaml": "46b9db88cdb978bc75b85b17d19a627233263da5b4fc6456a21fa870646ae1d0",
-    "conventions/tester.bun/tester.bun.acceptance-covers-tag-well-formed.convention.yaml": "8dd55d2dc36d255ab553fba8cf6f5cd7de1ba286e687d290458d3b5681fbb40f",
-    "conventions/tester.bun/tester.bun.acceptance-resolves-to-declared.convention.yaml": "6c5cc0719749dbcdd3eb02877799a40998e77b433b2f17d27ac1dbca44292610",
-    "conventions/tester.bun/tester.bun.interlocking-production-runner-used.convention.yaml": "7cfa67f19ae6b88be40d2facdf2a83440bca3c2a8b3824c75eb25fda8438297c",
-    "conventions/tester.bun/tester.bun.interlocking-route-coverage.convention.yaml": "7c21809613d74cd38368238f82a35853bf74ab34cfacc07354e62f83b8514881",
+    "conventions/tester.bun/tester.bun.acceptance-binding-declared.convention.yaml": "4bc5489f8cca53eb9145decb07e3a74565c3856274fce1495338a1f3cd89d0c3",
+    "conventions/tester.bun/tester.bun.acceptance-covers-tag-well-formed.convention.yaml": "a7095e17f003ab3e08202f49408f4de7c834cc917b0946d6bc68036afdcdc265",
+    "conventions/tester.bun/tester.bun.acceptance-resolves-to-declared.convention.yaml": "44b77a6ae4b4a92d5b51b5bb3444a4db280f74dc1ed25d158e20e79cd16a2bb3",
+    "conventions/tester.bun/tester.bun.interlocking-production-runner-used.convention.yaml": "c2fee925c16946314bdebf30fe2130cfc76f62bb64d714bdc37b7311e932f788",
+    "conventions/tester.bun/tester.bun.interlocking-route-coverage.convention.yaml": "e75b1285aa650cf2a5d94d9c98b6351df4a24e3942dcf01e2faa9ed6676f1ca6",
     "conventions/tester.bun/tester.bun.interlocking-smoke-coverage-for-station-master.convention.yaml": "ae2e53865fe3f53982d5d1d9fca73dd116ee932e00c4c4f1184235415b1dd794",
     "conventions/tester.bun/tester.bun.interlocking-trace-binds-declared-route.convention.yaml": "8aea28e250368ed800a97d5e7e2f293c2935b198eb87be1422eef029223d71a4",
     "conventions/tester.bun/tester.bun.interlocking-train-sequence-is-exercised.convention.yaml": "3172abf9256efd8f831ed5f8f11872e17cf847114769bba0c42270507254e241",
-    "conventions/tester.bun/tester.bun.red-behavioral-assertion.convention.yaml": "5ce6b2460d8796b0b921600aa54129e192de4c4dd8229c8e574ae1cf55388b60",
-    "conventions/tester.bun/tester.bun.red-fails-first.convention.yaml": "0506c7fae92a85161df8e190e5c01c595d66c376d3ad5f16f1faf38d9503ac7c",
+    "conventions/tester.bun/tester.bun.red-behavioral-assertion.convention.yaml": "b604c0836eeff46df9a9e53195696c17f7997c6b2732c6c759b5207162a33d97",
+    "conventions/tester.bun/tester.bun.red-fails-first.convention.yaml": "232c42033cea8f935a84cd86769cfd273bf6e4772e2d2ff3ed66117a3c8e689d",
     "conventions/tester.bun/tester.bun.routing-runtime-family.convention.yaml": "6deeb37235ebe500c491aea9e06695c08df718a371114b1a6394bd1988fb66b1",
-    "conventions/tester.bun/tester.bun.security-auth.convention.yaml": "eb192aa29ce0f2976a92c20d32fc425b5685b15d9bb384d52101646b08cb9c2e",
-    "conventions/tester.bun/tester.bun.security-input.convention.yaml": "3118299e1e6a71b21be730f26377baab922b1c3d8b175b9b35f10d38d9ebaeb0",
-    "conventions/tester.bun/tester.bun.smoke-no-collaborator-substitution.convention.yaml": "76187d91e6298ae9b89a39c2ebf9cb6f769e1d3ce08d7a9ea21727aadc6a019a",
-    "conventions/tester.bun/tester.bun.smoke-observable-assertion.convention.yaml": "1d35f17221b7de3f9ad6bb3c1ced486bec401e1d024e2476147f4f9e52f05674",
+    "conventions/tester.bun/tester.bun.security-auth.convention.yaml": "b8224269911ae477756e6c160e1ed72d1438574277109f77704326251e720449",
+    "conventions/tester.bun/tester.bun.security-input.convention.yaml": "6f089d2641f264e59ab38973f848644bb48d6e254613dba62c2616f1edb82a68",
+    "conventions/tester.bun/tester.bun.smoke-no-collaborator-substitution.convention.yaml": "6ae2bdfdf3c842f855c02b9c776feaa0ac11efa1365a0b8f0b9c8343afd11102",
+    "conventions/tester.bun/tester.bun.smoke-observable-assertion.convention.yaml": "ba7c3981fd9b8860abb88eaeefde0a87bc696309a2d31e2bc9c637832d0fe1cb",
     "conventions/tester.bun/tester.bun.telemetry-captured-sink.convention.yaml": "7f1156dc041fc44d4becd18f379cd1fb68b99cd1e888b9a8f6dee4201ad5337b",
     "conventions/tester.bun/tester.bun.telemetry-emit.convention.yaml": "440ba54de6c23e25786d363d80a9c337f29aa2eaf59bc8b5c24d391cc1c3d3b7",
     "conventions/tester.bun/tester.bun.telemetry-identity-assertion.convention.yaml": "25f7cc3dcb21e70a183638be9416802ef081323482a98eba604223fabf389b55",
@@ -147,10 +147,10 @@
     "conventions/tester.bun/tester.bun.test-imports-bun-test.convention.yaml": "6eef1c745315a69357d23bf07d318e504d425f76fcfdc120166b8ef2d4c820d6",
     "conventions/tester.bun/tester.bun.test-isolation-no-live-state.convention.yaml": "3488af16431ea461e9128d15dbb0ad86324f4446bf36d5a662fab73687e8860e",
     "conventions/tester.bun/tester.bun.test-no-self-skip.convention.yaml": "23fca575611f9c0740bcf64849a3c1600ef4cc1cc64df3c106d328b67283d8a3",
-    "conventions/tester.bun/tester.bun.test-phase-declared.convention.yaml": "cd22101bfcbc2eeca3da1aa2907ba6c944674c31cfaac5305f2149c6c429cf87",
+    "conventions/tester.bun/tester.bun.test-phase-declared.convention.yaml": "f6daa660417bdc07fe87765ac17bc5606cd2d8a5c8dbe456f9e4327ddd77fe73",
     "conventions/tester.htmx/tester.htmx.a11y-harness.convention.yaml": "e74328600b89761a8740ace465e3a5d5e38f967dcbeda7fe7023af53dd0089d4",
     "conventions/tester.htmx/tester.htmx.covered-train-is-routed.convention.yaml": "e70d05055733644addd63db11c6cb39cf38a34adc4cc39f7c7ee9964eb2391a4",
-    "conventions/tester.htmx/tester.htmx.e2e-binds-declared-subject.convention.yaml": "48bb5a45380d80161c09e872a769020b3ea10a05a4c34a71a1a585f89a434583",
+    "conventions/tester.htmx/tester.htmx.e2e-binds-declared-subject.convention.yaml": "fa2b9079bc15ffab47d57c80cb804fb4c1b19fc377434226ef9e46e586890cbc",
     "conventions/tester.htmx/tester.htmx.e2e-spec-naming.convention.yaml": "4bd46400706bbe9b453784ca2811ef04ffb25871a762791e653da3d9a0fa07f2",
     "conventions/tester.htmx/tester.htmx.exposed-journey-e2e-coverage.convention.yaml": "eca949b38da805c9654d483fce4e06fe19292bd72b5b286af982f13c5782e1d4",
     "conventions/tester.htmx/tester.htmx.fragment-asserts-returned-markup.convention.yaml": "b8de8e893b582d8ec4b7c24acfa16da0eccd14e6e58e92baf9e9c10c9749ea0c",
@@ -162,7 +162,7 @@
     "conventions/tester.htmx/tester.htmx.responsive-harness.convention.yaml": "cec312935ab592c2c7a5c6a94623a02df771a9e2ca2035b721ef1006c4800fdf",
     "conventions/tester.htmx/tester.htmx.responsive-journey-coverage.convention.yaml": "2004d0a8975178475d792702e164f335b07407f36e83a09ceadef3fe49037111",
     "conventions/tester.htmx/tester.htmx.swap-oob-asserts-destination-id.convention.yaml": "65d8ffa62732ec0578d4999234b89f692e9c5e234ecd30e620bee7c44f053caa",
-    "conventions/tester.htmx/tester.htmx.train-e2e-coverage.convention.yaml": "99096eaab1b6891eb66306d904624c7c28ab9bd2c0f7f9f68a515e3be45961f5",
+    "conventions/tester.htmx/tester.htmx.train-e2e-coverage.convention.yaml": "8d36a1e06985262a5d431678f9baef67b5625825f4cc843ac3d3cbff13022373",
     "conventions/tester.htmx/tester.htmx.verb-endpoint-coverage.convention.yaml": "41b6ff2a519040a5eb9834bcdee88ad1d470a69430bc9a39be667dc321dcd14c",
     "conventions/tester.htmx/tester.htmx.visual-harness.convention.yaml": "a2419b784202fc807558d0182e26d3d8c777aa9ec4ef4c252467a979dd903d50",
     "conventions/traceability/traceability.plan.executable-acceptance-has-test.convention.yaml": "52eca528c9dbdb82f3c1a13e4e1a3d5d21a9dd511b66e6f8c4135298412427f5",
@@ -1196,7 +1196,7 @@
     "src/ci.ts": "67e54d2cbfc44a9e42837d5e750af526d6255c539d3c452a4d5fca3226c0d9ac",
     "src/cli.ts": "cbc50f1e7fc7d0935f78230b7da6e232ed7ee6f04828e015c599fb6f6edcbfa2",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
-    "src/enforce.ts": "2f624f2aa272466f44c552d77ce3976cb2a518491d3ec3c47815583fdd0f7ad8",
+    "src/enforce.ts": "33e2b17ad1f8c46af439dd433918d4c0724b9bffa077305a32b800494fa0886a",
     "src/hooks.ts": "0b4ca8c857e637bbd144e737e78eda924e3cba7b038c0abe5e6916d200d73068",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
     "src/integrity.ts": "556976a42bae298df14b73675102d83b6bf4df0674d8e7211aad5315548f005f",

package/package.json

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

package/src/enforce.ts

@@ -44,7 +44,7 @@ export const profileImplementations: Record<ConcreteProfile, string[]> = {
 
 /** Additional policy conventions a profile loads, whether local or contributed by an installed companion package. */
 export const profileConventions: Record<ConcreteProfile, Array<{ rule_id: string; path: string }>> = {
-  traceability: [], topology: [], docs: [], planner: [], telemetry: [], coder: [{ rule_id: ["coder.bun", "phase-discipline"].join("."), path: "conventions/coder.bun/coder.bun.phase-discipline.convention.yaml" }], tester: [], security: [],
+  traceability: [], topology: [], docs: [], planner: [], telemetry: [], coder: [{ rule_id: "coder.bun.phase-discipline", path: "conventions/coder.bun/coder.bun.phase-discipline.convention.yaml" }], tester: [], security: [],
   architecture: [], metrics: [], runtime: [], interlocking: [], htmx: [], design: [],
   workflow: [{ rule_id: "atdd-workflow.workflow.lifecycle", path: "../atdd-workflow/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml" }],
 };