@afokapu/atdd-bun 0.3.2 → 0.5.0

package/PLANNER_PORT.md

@@ -5,7 +5,7 @@ to port ATDD's full planner yet.
 
 ## Portable planner kernel
 
-The package ships 195 canonical convention nodes in `planner-nodes/` and
+The package ships 196 canonical convention nodes in `planner-nodes/` and
 21 schemas in `planner-schemas/`. It does not ship Python validator files:
 they are executable Python/pytest code, not portable package assets. Port each
 selected validator into Bun/TypeScript before enabling it in a `planner` profile.

package/README.md

@@ -98,11 +98,11 @@ name.
 |---|---|
 | `traceability` | plan acceptance, Bun test, and implementation closure |
 | `planner` | plan parsing/graph integrity plus the explicitly scoped planner rules |
-| `docs` | the optional documentation capability and its declared artifacts |
+| `docs` | the optional documentation capability and its declared artifacts, including the generated journey view |
 | `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions for that concern |
 | `interlocking` | declared train/interlocking binding, infrastructure, and coverage |
-| `htmx` | htmx-specific source and test conventions |
-| `design` | the design system: tokens ← primitives ← components ← templates, token-only colors, spacing, radii, and motion (also part of `coder`) |
+| `htmx` | htmx-specific source and test conventions, including browser specs |
+| `design` | the design system (tokens ← primitives ← components ← templates, token-only colors, spacing, radii, motion) and responsiveness (also part of `coder`) |
 | `all` | the complete package policy, normally used by CI |
 
 The package ships the canonical planner-node corpus as planning reference, but
@@ -146,6 +146,99 @@ every exported component has a consumer. Defining a custom property
 (`--accent: #0ea5e9`) is defining a token and is allowed anywhere. A repository
 without a design directory is not judged by these rules.
 
+### Journey documentation
+
+A plan describes behaviour on three levels. A journey (`plan/_journeys/`) enters
+at one interlocking and continues, through an artifact the selected train
+produces, into the next one. An interlocking chooses one route by its guards.
+A route runs one train, a linear sequence of handovers. Generate the view of all
+three from `plan/`:
+
+```sh
+bun run atdd-bun docs journeys          # writes docs/purpose/journeys/
+bun run atdd-bun docs journeys --check  # fails when the committed view differs from plan/
+```
+
+It writes `docs/purpose/journeys/index.adoc` and one SVG for each of:
+
+- **journey map:** the entry action, each interlocking, the routes it chooses
+  and their guards, the trains they run, continuations (labelled with the
+  artifact that carries control) and terminal outcomes;
+- **nominal path, end to end:** the journey's trains across all its
+  interlockings, joined into one sequence diagram;
+- **train:** each routed train as its own sequence diagram, under its
+  interlocking's route table.
+
+The page also tables every path with how it ends, and every **gap**: unreached
+interlockings, routes with no continuation or outcome, unrouted trains,
+unresolved guards. Participants are coloured by what they are (wagon, person,
+outside system) and arrows by the boundary they cross. Diagrams are inlined
+(`opts=inline`) and coloured with `var(--atdd-*, fallback)`, so a doc site can
+theme them by defining `--atdd-ink`, `--atdd-paper`, `--atdd-wagon`,
+`--atdd-person`, `--atdd-system`, `--atdd-nominal`, `--atdd-alternate`,
+`--atdd-error`, `--atdd-exception`, and the like. The output carries no
+timestamp and no package version, so it changes only when the plan does.
+
+The planner requires the journey level itself: `planner.journey.interlocking-composed`
+fails when a plan declares interlockings and no journey, or when an interlocking
+is neither a journey's entrypoint nor reached by one of its continuations.
+`planner.journey.continuation-closure` then checks each declared journey closes.
+
+**Required.** In a repository with `docs/` whose plan has journeys or
+interlockings, the `docs` profile's `planner.docs.journey-view-current` rule
+fails when any generated file is missing, stale, hand-edited, or extra. The
+generator refuses to overwrite a hand-written `index.adoc` unless you pass
+`--force`; use `--out <dir>` to preview elsewhere.
+
+### Every enforced rule is strict
+
+atdd-bun fails on every finding: it has no advisory mode and no ratchet
+baseline. Every convention with a validator is therefore `strict` (or `block`),
+and `tests/dispositions.test.ts` fails on any that promises otherwise. For the
+canonical planner nodes, which ship verbatim, the package states its own
+`disposition: strict` in `planner-nodes/ENFORCEMENT_SCOPE.yaml`.
+
+### Browser specs (Playwright)
+
+The `tester` and `htmx` profiles judge browser specs against the plan. A browser
+spec is a `*.e2e.ts` file run by Playwright, never `*.spec.ts`, which `bun test`
+would try to run itself. It binds to one plan subject and declares its layer
+and test URN:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+// Train: train:orders:place-order        (or // Journey: journey:buy)
+// Layer: assembly
+// URN: test:train:orders:place-order:E2E-001-places-an-order
+```
+
+The harness code in the URN (`E2E`, `SMOKE`, `A11Y`, `VIS`, `RESP`) says what
+the spec must do: an `A11Y` spec runs `@axe-core/playwright` and asserts on its
+violations, a `VIS` spec compares a screenshot, a `RESP` spec renders at every
+declared viewport and asserts on `scrollWidth`. Coverage is read from `plan/`:
+every train has a spec, every covered train is routed by an interlocking, every
+exposed journey has an E2E or SMOKE spec and a RESP spec, and every presentation
+component has a SMOKE spec naming its wagon. Route and Station Master coverage
+remain `tester.bun` rules; browser specs count toward them.
+
+### Responsiveness
+
+The `coder` and `design` profiles check the structural causes of screens that
+break on small devices: every HTML document declares
+`<meta name="viewport" content="width=device-width, initial-scale=1">` and
+never blocks zoom; no `width`/`min-width` is wider than the smallest viewport;
+and every `@media` width is a declared breakpoint (media queries cannot read
+CSS variables, so breakpoints are declared once). The browser proof is the
+`RESP` spec above. Both read the same settings:
+
+```yaml
+# atdd-bun.yaml
+frontend:
+  viewports: [375, 768, 1280]          # default; RESP specs render at each, the smallest bounds fixed widths
+  breakpoints: [480, 768, 1024, 1280]  # default; the only widths @media may use
+```
+
 ### Theme and contract registry
 
 Theme vocabulary belongs to the repository, not the package. When a plan uses
@@ -391,10 +484,24 @@ It creates no tag, makes no network request, and does not publish anything.
 The separate optional release workflow is where a repository may create a tag or
 publish using its own credentials and registry configuration.
 
+## Convention relationships
+
+`relationships.yaml` relates every convention the package ships (`planner-nodes/`
+and `conventions/`) to at least one other, as
+`planner.relationship.no-orphan-nodes` requires. Edges that touch a shipped
+convention are imported from the upstream ATDD graphs with their `origin`; the
+package adds its own for the conventions it introduces. A test fails when any
+shipped convention has no edge, when the node list drifts from the shipped
+conventions, or when an edge breaks `relationship.schema.json`, so a new
+convention cannot land without its relationships.
+
 ## Verification of this package
 
 `bun test` runs the package’s real-Git fixtures and detector clean/dirty corpora.
 The suite proves that every declared convention output has a matching convention
-and a deliberate failing case; it also covers hook isolation, the declarative
+and a deliberate failing case, and runs the frontend chain end to end: a Bun app
+built from a plan, its browser specs accepted by the detectors and passing in
+Chromium, and broken variants of the page failing both the static rules and the
+browser (Chromium must be installed: `bunx playwright install chromium`); it also covers hook isolation, the declarative
 registry policy, CI generation, agent-skill installation, planner scope, release
 validation, and linked-worktree policy.

package/conventions/coder.bun/coder.bun.complexity-cyclomatic.convention.yaml

@@ -35,15 +35,13 @@ content:
   exceptions:
   - Functions with fewer than 3 code lines are not scored.
   - Test files and vendored/build directories are outside the scan.
-  - Pre-existing counts are held flat by a ratchet baseline, not by lowering the threshold.
 metadata:
   aliases:
   # COMPLEXITY-CYCLOMATIC-TS-001 is the SHARED core alias, also carried by the agnostic node and by
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - COMPLEXITY-CYCLOMATIC-TS-001
   severity: 3
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

package/conventions/coder.bun/coder.bun.complexity-length.convention.yaml

@@ -34,8 +34,7 @@ metadata:
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - COMPLEXITY-LENGTH-TS-001
   severity: 2
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

package/conventions/coder.bun/coder.bun.complexity-nesting.convention.yaml

@@ -40,8 +40,7 @@ metadata:
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - COMPLEXITY-NESTING-TS-001
   severity: 3
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

package/conventions/coder.bun/coder.bun.dead-code-reachability.convention.yaml

@@ -40,8 +40,7 @@ metadata:
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - DEAD-CODE-REACHABILITY-TS-001
   severity: 2
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

package/conventions/coder.bun/coder.bun.design-token-color.convention.yaml

@@ -23,7 +23,7 @@ content:
   fix_hint: 'Define the color once as a custom property in the tokens layer and reference it: `color: var(--danger)`.'
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
-  - Custom property definitions (`--danger: #b91c1c`) define tokens wherever they live and are not flagged.
+  - 'Custom property definitions (`--danger: #b91c1c`) define tokens wherever they live and are not flagged.'
   - The tokens/foundations layer is where raw colors are defined and is not scanned.
   - Named colors (`red`, `white`) and `currentColor`/`transparent` are not flagged.
 metadata:

package/conventions/coder.bun/coder.bun.design-token-hardcoded.convention.yaml

@@ -25,7 +25,7 @@ content:
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - 0 and 1px (hairline borders) are not design decisions and are allowed.
-  - Custom property definitions (`--space-3: 12px`) define tokens wherever they live and are not flagged.
+  - 'Custom property definitions (`--space-3: 12px`) define tokens wherever they live and are not flagged.'
   - The tokens/foundations layer defines these values and is not scanned.
   - Widths, heights, and font sizes are out of scope for this rule.
 metadata:

package/conventions/coder.bun/coder.bun.dto-mapper.convention.yaml

@@ -31,7 +31,8 @@ metadata:
   # Core obligation: coder.dto.mapper
   - BUN-DTO-MAPPER-001
   severity: 3
-  disposition: advisory
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

package/conventions/coder.bun/coder.bun.dto-placement.convention.yaml

@@ -32,7 +32,8 @@ metadata:
   # Core obligation: coder.dto.placement
   - BUN-DTO-PLACEMENT-001
   severity: 3
-  disposition: advisory
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

package/conventions/coder.bun/coder.bun.dto-purity.convention.yaml

@@ -33,7 +33,8 @@ metadata:
   # Core obligation: coder.dto.purity
   - BUN-DTO-PURITY-001
   severity: 3
-  disposition: advisory
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

package/conventions/coder.bun/coder.bun.duplication-intra-layer.convention.yaml

@@ -38,8 +38,7 @@ metadata:
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - DUPLICATION-TS-001
   severity: 2
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

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

@@ -44,17 +44,8 @@ metadata:
   - GREEN-HEADER-004
   - BUN-GREEN-HEADER-ORDER-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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -38,17 +38,8 @@ metadata:
   - GREEN-HEADER-002
   - BUN-GREEN-HEADER-PURPOSE-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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -39,17 +39,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -46,17 +46,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -36,17 +36,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -37,7 +37,6 @@ content:
       <!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.
@@ -50,17 +49,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -29,7 +29,7 @@ content:
       // 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.
+  - '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:
@@ -40,17 +40,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -39,17 +39,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -37,17 +37,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

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

@@ -39,17 +39,8 @@ metadata:
   - 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
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

package/conventions/coder.bun/coder.bun.layer-naming.convention.yaml

@@ -34,7 +34,8 @@ metadata:
   # Core obligation: coder.backend.code-is-organized
   - BUN-LAYER-NAMING-001
   severity: 2
-  disposition: suppress-and-clean
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

package/conventions/coder.bun/coder.bun.logging-structured.convention.yaml

@@ -33,16 +33,14 @@ content:
   exceptions:
   - A call already passing a second argument is not flagged.
   - Non-logger receivers are out of scope.
-  - Disposition is `suppress-and-clean`, matching the Python sibling: a ratchet holds existing lines flat.
 metadata:
   aliases:
   # LOGGING-STRUCTURED-001 is the SHARED core alias, also carried by the agnostic node and its
   # python-pytest realization.
   - LOGGING-STRUCTURED-001
   severity: 2
-  # RE-REALIZED, not ported: the python-pytest sibling inspects a Python
-  # AST for constructs this stack does not have. Same obligation, new detector.
-  disposition: suppress-and-clean
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
   introduced_in: 0.1.0
 implementation:
   type: validator

package/conventions/coder.bun/coder.bun.quality-comments.convention.yaml

@@ -35,8 +35,7 @@ metadata:
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - REFACTOR-QUALITY-COMMENTS-TS-001
   severity: 2
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

package/conventions/coder.bun/coder.bun.quality-mi.convention.yaml

@@ -38,8 +38,7 @@ metadata:
   # its python-pytest realization. One obligation, two detectors, two runtimes.
   - REFACTOR-QUALITY-MI-TS-001
   severity: 2
-  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
-  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
   disposition: strict
   introduced_in: 0.1.0
 implementation:

package/conventions/coder.bun/coder.bun.responsive-breakpoints-declared.convention.yaml

@@ -0,0 +1,31 @@
+schema_version: 1.1.0
+rule_id: coder.bun.responsive-breakpoints-declared
+kind: rule
+status: active
+name: Media queries use only the declared breakpoints
+statement: Every width condition in an `@media` query, `min-width`/`max-width` or the range syntax (`width >= 768px`,
+  `768px <= width`), MUST use one of the breakpoints declared under `frontend.breakpoints` in `atdd-bun.yaml` (default
+  480, 768, 1024, 1280). A `max-width` within 1px below a breakpoint (`767px`, `767.98px`) counts as that breakpoint,
+  and `em`/`rem` convert at 16px. New in atdd-bun, strict.
+terms:
+- term_id: frontend_settings
+  text: '`atdd-bun.yaml` → `frontend.viewports` (the widths responsive specs render at; the smallest bounds fixed
+    widths) and `frontend.breakpoints` (the widths media queries may use).'
+content:
+  summary: Media queries use only the declared breakpoints.
+  normative_text: CSS custom properties cannot be used in media queries, so breakpoints cannot be tokens. Declaring
+    them once and requiring every query to use them keeps layouts switching at the same widths everywhere instead
+    of at a new one per component.
+  fix_hint: 'Use `@media (min-width: 768px)`, or add the width to `frontend.breakpoints` if the design system really
+    needs it.'
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+metadata:
+  aliases:
+  - BUN-RESPONSIVE-RESPONSIVE-BREAKPOINTS-DECLARED-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.5.0
+implementation:
+  type: validator
+  ref: bun_responsive_detector

package/conventions/coder.bun/coder.bun.responsive-no-fixed-width.convention.yaml

@@ -0,0 +1,30 @@
+schema_version: 1.1.0
+rule_id: coder.bun.responsive-no-fixed-width
+kind: rule
+status: active
+name: No width or min-width wider than the smallest viewport
+statement: A `width` or `min-width` declaration, in a stylesheet, a `<style>` block, a `style` attribute or a JSX
+  `style` object, MUST NOT exceed (with `rem` and `em` counted at 16px) the smallest viewport declared under `frontend.viewports`
+  in `atdd-bun.yaml` (default 375px). New in atdd-bun, strict.
+terms:
+- term_id: frontend_settings
+  text: '`atdd-bun.yaml` → `frontend.viewports` (the widths responsive specs render at; the smallest bounds fixed
+    widths) and `frontend.breakpoints` (the widths media queries may use).'
+content:
+  summary: No width or min-width wider than the smallest viewport.
+  normative_text: An element wider than the screen forces horizontal scrolling on every phone. Wide layouts are
+    expressed with `max-width`, percentages, or layouts that wrap.
+  fix_hint: 'Replace `width: 960px` with `width: 100%; max-width: 960px`.'
+  exceptions:
+  - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
+  - '`max-width` is not judged; it is how wide layouts are meant to be bounded.'
+  - 'Custom property definitions (`--page: 1200px`) define tokens and are not judged.'
+metadata:
+  aliases:
+  - BUN-RESPONSIVE-RESPONSIVE-NO-FIXED-WIDTH-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.5.0
+implementation:
+  type: validator
+  ref: bun_responsive_detector