@afokapu/atdd-bun 0.1.0

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

@@ -0,0 +1,49 @@
+schema_version: 1.1.0
+rule_id: coder.bun.complexity-nesting
+kind: rule
+status: active
+name: TypeScript function nesting depth stays at or below 4
+statement: >-
+  Every TypeScript/TSX function MUST keep its maximum control-flow nesting depth at or below 4. Stack-
+  neutral obligation, NATIVE BUN detector transcribed from the python-pytest sibling
+  `coder.refactor.complexity-nesting-typescript` and verified numerically identical. Realized by
+  `bun_ts_metrics_detector` (core alias COMPLEXITY-NESTING-TS-001).
+terms:
+- term_id: control_depth
+  text: >-
+    the maximum brace depth reached on lines carrying a control keyword, measured relative to
+    the function's own base depth.
+- term_id: guard_clause
+  text: >-
+    an inverted condition returning early. The usual way to remove a level without changing
+    behaviour.
+content:
+  summary: >-
+    Depth is measured by brace balance on lines that also carry a control keyword (if / else / for / while
+    / do / switch / try / catch / finally), relative to the function's own base depth.
+  normative_text: |
+    Nesting is the metric readers feel most directly: at depth five a reader must hold five simultaneous conditions to know whether a line executes, which is past what working memory does reliably.
+    It is also the most mechanically fixable — a guard clause or an extracted helper usually removes a level without changing behaviour, which is why the threshold is enforced rather than advised.
+  fix_hint: |
+    Flatten the control flow:
+
+      * invert conditions into early-return guard clauses,
+      * extract the innermost block into its own function,
+      * replace a nested loop with a single pass over a prepared collection.
+  exceptions:
+  - Functions with fewer than 3 code lines are not scored.
+  - Comment lines are ignored when measuring brace balance.
+  - Test files and vendored/build directories are outside the scan.
+metadata:
+  aliases:
+  # COMPLEXITY-NESTING-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-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.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector

package/conventions/coder.bun/coder.bun.composition-consumer.convention.yaml

@@ -0,0 +1,40 @@
+schema_version: 1.1.0
+rule_id: coder.bun.composition-consumer
+kind: rule
+status: active
+name: Consumer layers receive their collaborators
+statement: >-
+  A module in the `presentation/` or `application/` layer MUST receive its collaborators by injection
+  rather than constructing them. Bun realization mirroring `coder.convex.composition-consumer`; core
+  obligation `coder.refactor.composition-consumer`.
+terms:
+- term_id: consumer_layer
+  text: >-
+    presentation or application — a layer that USES collaborators rather than assembling them.
+- term_id: injection
+  text: >-
+    receiving a collaborator as a parameter or pre-wired. A consumer that builds its own cannot
+    be tested without them.
+content:
+  summary: >-
+    Flags a `new <Collaborator>()` inside a consumer layer.
+  normative_text: |
+    The sibling of `composition-root`, and the half that makes the discipline pay. That rule says where wiring MAY happen; this one says consumers must accept what they are given.
+    A consumer that builds its own collaborators cannot be tested without them — which is exactly how a unit test acquires a database.
+  fix_hint: |
+    Take the collaborator as a parameter, and let the composition root supply it.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.composition-consumer
+  # Core obligation: coder.refactor.composition-consumer
+  - BUN-COMPOSITION-CONSUMER-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.composition-root.convention.yaml

@@ -0,0 +1,42 @@
+schema_version: 1.1.0
+rule_id: coder.bun.composition-root
+kind: rule
+status: active
+name: Wiring is confined to a composition root
+statement: >-
+  Instantiation of a feature's collaborators (`*Repository`, `*Client`, `*Service`, `*Adapter`,
+  `*Gateway`, `*Store`, `*Provider`, `*Factory`) MUST happen only in a composition root —
+  `composition.ts`, `wagon.ts`, `server.ts`, `index.ts`. Bun realization mirroring
+  `coder.convex.composition-root`; core obligation `coder.refactor.composition-root`.
+terms:
+- term_id: composition_root
+  text: >-
+    composition.ts, wagon.ts, server.ts or index.ts. server.ts counts because Bun.serve IS the
+    assembly point of a full-stack Bun app.
+- term_id: collaborator
+  text: >-
+    a *Repository, *Client, *Service, *Adapter, *Gateway, *Store, *Provider or *Factory — the
+    things whose wiring must be confined.
+content:
+  summary: >-
+    Flags a `new <Collaborator>()` outside a composition root, over string- and comment-masked source.
+  normative_text: |
+    `server.ts` is a root in this stack specifically because `Bun.serve` IS the assembly point of a full-stack Bun app — the place routes and their dependencies are wired. The Convex sibling has no equivalent because its function tree has no single entry.
+    Wiring scattered across a codebase is not a style problem: it is why a test cannot substitute anything, and why a second deployment shape becomes a rewrite.
+  fix_hint: |
+    Construct the collaborator in the composition root and pass it to whatever needs it.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.composition-root
+  # Core obligation: coder.refactor.composition-root
+  - BUN-COMPOSITION-ROOT-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

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

@@ -0,0 +1,49 @@
+schema_version: 1.1.0
+rule_id: coder.bun.dead-code-reachability
+kind: rule
+status: active
+name: Every TypeScript file is reachable from a structural root
+statement: >-
+  Every TypeScript/TSX file MUST be reachable, forwards or backwards, from a structural root (`index`,
+  `wagon`, `composition`, `main`, `app`) through the module import graph. Stack-neutral obligation, NATIVE
+  BUN detector; the traversal and root vocabulary are transcribed from the python-pytest sibling
+  `coder.dead-code.reachability-typescript`, but the import graph is built by Bun's in-process TypeScript
+  parser rather than by regex. Realized by `bun_ts_metrics_detector` (core alias DEAD-CODE-REACHABILITY-
+  TS-001).
+terms:
+- term_id: structural_root
+  text: >-
+    a file the graph is walked from: index, wagon, composition, main or app.
+- term_id: type_only_import
+  text: >-
+    an `import type` edge. Erased at compile time, so it creates no runtime edge and cannot keep
+    a module alive — a distinction a regex cannot make and Bun's parser can.
+content:
+  summary: >-
+    Builds the file import graph, walks it from the structural roots in both directions, and reports every
+    file in neither reachable set. Import specifiers resolve relative or through the `@/` alias; npm
+    specifiers are outside the graph.
+  normative_text: |
+    This rule is MORE ACCURATE than its Python sibling, and the difference is worth stating because it is the one place the port is not a transcription.
+    The Python detector reads imports with five regexes — the best a Python process can do without a TypeScript parser. A regex cannot distinguish `import type { T } from "./t"` from a value import, so a module whose only referrer is a TYPE import is counted as reachable. But a type-only import is erased at compile time and creates no runtime edge, so that module is dead and the regex reports it alive.
+    Bun ships a real TypeScript parser in-process, which returns the actual import records and omits type-only ones. Same obligation, measured correctly — and available only because the runtime is Bun. Verified on a fixture where the Python detector finds one dead file and this one finds two.
+  fix_hint: |
+    Either wire the file into the graph — import it from the module that should own it — or delete it. A file reachable only through a type import is a types module whose values have already been removed; move the type into the module that uses it.
+  exceptions:
+  - "`index.ts` / `index.tsx` are structural (like `__init__.py`) and are never reported."
+  - Test files are entrypoints, not dead code, and are excluded.
+  - A scan root containing no structural root is skipped rather than reporting every file as dead.
+  - npm/bare specifiers are outside the graph by construction.
+metadata:
+  aliases:
+  # DEAD-CODE-REACHABILITY-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.
+  - 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.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector

package/conventions/coder.bun/coder.bun.design-hierarchy-import.convention.yaml

@@ -0,0 +1,42 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-hierarchy-import
+kind: rule
+status: active
+name: Imports point inward through the layer hierarchy
+statement: >-
+  A module MUST import only inward: presentation -> application -> domain; integration -> application,
+  domain; assembly (the composition root) may reach any layer. Bun realization mirroring
+  `coder.convex.design-hierarchy-import`; core obligation `coder.backend.imports-respect-dependency-
+  allowed`.
+terms:
+- term_id: inward_import
+  text: >-
+    presentation -> application -> domain; integration -> application, domain. The permitted
+    direction.
+- term_id: assembly_exemption
+  text: >-
+    the composition root's freedom to reach any layer. Something must know about everything;
+    confining that to one place is the point of having a root.
+content:
+  summary: >-
+    Resolves each import to its target layer and flags an edge the hierarchy does not permit.
+  normative_text: |
+    This is the general rule the commons rules apply to one tree. It is stated separately because it governs FEATURE code as well, where most layering damage actually happens.
+    The assembly exemption is what makes the rest workable: something must be allowed to know about everything, and confining that to the composition root is the whole point of having one.
+  fix_hint: |
+    Depend inward, or invert the dependency with a port. If neither is possible the two modules probably belong in one layer.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.design-hierarchy-import
+  # Core obligation: coder.backend.imports-respect-dependency-allowed
+  - BUN-DESIGN-HIERARCHY-IMPORT-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

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

@@ -0,0 +1,38 @@
+schema_version: 1.1.0
+rule_id: coder.bun.dto-mapper
+kind: rule
+status: active
+name: DTO mappers live in integration/
+statement: >-
+  A function mapping between a DTO and a domain entity (`to*DTO`, `from*DTO`, `map*DTO*`) MUST live in the
+  `integration/` layer. Bun realization mirroring `coder.convex.dto-mapper`; core obligation
+  `coder.dto.mapper`.
+terms:
+- term_id: dto_mapper
+  text: >-
+    a function translating between a DTO and a domain entity: `to*DTO`, `from*DTO`, `map*DTO*`.
+- term_id: translation_layer
+  text: >-
+    integration — where a boundary crossing legitimately sees both sides.
+content:
+  summary: >-
+    Flags a DTO-mapper function declared in any layer other than integration.
+  normative_text: |
+    Mapping is translation across a boundary, which is precisely what the integration layer is for. A mapper in the domain drags the wire format inward; a mapper in presentation duplicates itself once a second caller appears.
+  fix_hint: |
+    Move the mapper to `integration/`, where both the DTO and the entity are legitimately visible.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.dto-mapper
+  # Core obligation: coder.dto.mapper
+  - BUN-DTO-MAPPER-001
+  severity: 3
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

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

@@ -0,0 +1,39 @@
+schema_version: 1.1.0
+rule_id: coder.bun.dto-placement
+kind: rule
+status: active
+name: DTOs are declared in contracts/
+statement: >-
+  A `*DTO` type MUST be declared inside a `contracts/` module, not inside a feature's internal layer. Bun
+  realization mirroring `coder.convex.dto-placement`; core obligation `coder.dto.placement`.
+terms:
+- term_id: contracts_module
+  text: >-
+    a path segment `contracts` — where a boundary shape belongs, since it is owned by neither
+    side.
+- term_id: private_type_leak
+  text: >-
+    a DTO declared inside one feature's layer that another feature imports anyway, running the
+    boundary through somebody's internals.
+content:
+  summary: >-
+    Flags a `*DTO` declaration in a file whose path contains no `contracts` segment.
+  normative_text: |
+    A DTO belongs to the contract, not to either side of it. Declared inside one feature's layer it becomes that feature's private type that another feature imports anyway — and the boundary it was meant to define now runs through somebody's internals.
+  fix_hint: |
+    Move the type to `contracts/` and import it from both sides.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.dto-placement
+  # Core obligation: coder.dto.placement
+  - BUN-DTO-PLACEMENT-001
+  severity: 3
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

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

@@ -0,0 +1,40 @@
+schema_version: 1.1.0
+rule_id: coder.bun.dto-purity
+kind: rule
+status: active
+name: DTOs are pure immutable data
+statement: >-
+  A `*DTO` type or interface MUST have no method members and no non-`readonly` fields. Bun realization
+  mirroring `coder.convex.dto-purity`; core obligation `coder.dto.purity`.
+terms:
+- term_id: dto
+  text: >-
+    a `*DTO` type or interface — the shape crossing a boundary.
+- term_id: pure_data
+  text: >-
+    no method members, every field readonly. A method means behaviour crossed too; a mutable
+    field means the receiver can change what the sender said.
+content:
+  summary: >-
+    Parses each `*DTO` declaration body, splits its members on `;`/newline/`,`, and flags method members
+    or non-readonly fields.
+  normative_text: |
+    A DTO is the shape crossing a boundary. A method on it means behaviour crossed too, and the two sides are now coupled to an implementation rather than to data. A mutable field means the receiver can change what the sender said.
+    Both faults look harmless in one file and become impossible to unpick once a second consumer exists.
+  fix_hint: |
+    Strip methods to free functions in the layer that needs them, and mark every field `readonly`.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.dto-purity
+  # Core obligation: coder.dto.purity
+  - BUN-DTO-PURITY-001
+  severity: 3
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

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

@@ -0,0 +1,47 @@
+schema_version: 1.1.0
+rule_id: coder.bun.duplication-intra-layer
+kind: rule
+status: active
+name: No duplicated code fragments within one architectural layer
+statement: >-
+  No run of 7 or more non-trivial normalized lines may appear in two different TypeScript files of the
+  SAME architectural layer. Stack-neutral obligation, NATIVE BUN detector transcribed from the python-
+  pytest sibling `coder.duplication.no-intra-layer-code-typescript`, including the normalization table and
+  the sha256-prefix fingerprint. Realized by `bun_ts_metrics_detector` (core alias DUPLICATION-TS-001).
+terms:
+- term_id: normalized_fragment
+  text: >-
+    a window of 7 non-trivial lines with comments stripped, string literals folded to "S",
+    numbers to 0 and non-keyword identifiers to ID, so renaming a variable cannot hide a
+    duplicate.
+- term_id: intra_layer
+  text: >-
+    within one architectural layer. The same shape in two different layers is usually two
+    obligations that happen to look alike.
+content:
+  summary: >-
+    Each line is normalized — comments stripped, string literals folded to "S", numbers to 0, non-keyword
+    identifiers to ID — trivial lines dropped, then every sliding window of 7 lines is fingerprinted and
+    compared within a layer.
+  normative_text: |
+    Normalization is what makes the rule useful: because identifiers are folded, renaming a variable does not hide a duplicate, so the fingerprint tracks STRUCTURE rather than text.
+    The intra-layer restriction is equally deliberate. The same shape appearing in `domain/` and in `presentation/` is usually two different obligations that happen to look alike, and merging them couples layers that should move independently. Twice inside one layer is the shape that genuinely wanted extracting.
+  fix_hint: |
+    Extract the duplicated fragment into a shared function within that layer and call it from both sites. If the two copies are drifting apart on purpose, they are not duplicates — make the difference explicit so the normalized fingerprints stop matching.
+  exceptions:
+  - Test, spec, and `.d.ts` files are excluded, as are `index.ts` barrels and `__tests__` directories.
+  - Trivial lines (bare braces, closing punctuation) are not counted toward the 7.
+  - Files whose layer cannot be determined are compared only against each other.
+metadata:
+  aliases:
+  # DUPLICATION-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.
+  - 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.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector

package/conventions/coder.bun/coder.bun.error-response-bare-string.convention.yaml

@@ -0,0 +1,47 @@
+schema_version: 1.1.0
+rule_id: coder.bun.error-response-bare-string
+kind: rule
+status: active
+name: Error responses return a structured payload, not a bare string
+statement: >-
+  A `Response` with a 4xx or 5xx status MUST NOT have a bare string literal as its body; it MUST carry a
+  structured payload with an error code. Stack-neutral obligation, RE-REALIZED for Bun: the python-pytest
+  sibling matches FastAPI's `HTTPException(detail="...")`, which does not exist here — a Bun error IS a
+  `Response` with a status. Realized by `bun_security_hygiene_detector` (core alias ERROR-BARE-
+  STRING-001).
+terms:
+- term_id: error_response
+  text: >-
+    a `Response` carrying a 4xx or 5xx status.
+- term_id: rendered_verbatim
+  text: >-
+    what htmx does with a bare error string: swaps it into the live DOM, internal detail
+    included. The structured payload is also the boundary that stops leakage.
+content:
+  summary: >-
+    Flags `new Response("<literal>", { status: 4xx|5xx })`.
+  normative_text: |
+    This obligation is sharper in an htmx application than in a JSON API, and the difference is the reason it is worth enforcing rather than advising.
+    htmx swaps the response body into the live DOM. A bare error string is therefore not merely unstructured data that a client must parse — it is markup RENDERED TO THE USER verbatim, including whatever internal detail it happens to carry (a stack frame, a table name, an upstream message). The structured payload is both the machine-readable contract and the boundary that stops internals leaking into the page.
+  fix_hint: |
+    Return a coded payload, and render a fragment for the user separately:
+
+      return new Response("order not found", { status: 404 });            // wrong
+      return Response.json({ error_code: "ORDER_NOT_FOUND" }, { status: 404 });  // right
+  exceptions:
+  - 2xx and 3xx responses are out of scope.
+  - A response whose body is a variable or a rendered fragment is not a bare literal.
+  - Test files are excluded.
+metadata:
+  aliases:
+  # ERROR-BARE-STRING-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - ERROR-BARE-STRING-001
+  severity: 4
+  # RE-REALIZED, not ported: the python-pytest sibling inspects a Python
+  # AST for constructs this stack does not have. Same obligation, new detector.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

package/conventions/coder.bun/coder.bun.error-response-code-format.convention.yaml

@@ -0,0 +1,46 @@
+schema_version: 1.1.0
+rule_id: coder.bun.error-response-code-format
+kind: rule
+status: active
+name: Error codes are UPPER_SNAKE_CASE
+statement: >-
+  An `error_code` value MUST be UPPER_SNAKE_CASE. Stack-neutral obligation, and the second of only two
+  rules in this family that PORTS verbatim: the payload is JSON, so the pattern and the case test carry
+  over from the python-pytest sibling `coder.error-response.code-format` unchanged. Realized by
+  `bun_security_hygiene_detector` (core alias ERROR-CODE-FORMAT-001).
+terms:
+- term_id: error_code
+  text: >-
+    the machine key a client branches on. Once it does, the spelling is API surface.
+- term_id: upper_snake_case
+  text: >-
+    `^[A-Z][A-Z0-9_]+$`. The convention itself is arbitrary; that it is uniform is not.
+content:
+  summary: >-
+    Matches `"error_code": "<value>"` (and the `errorCode` spelling) and tests the value against
+    `^[A-Z][A-Z0-9_]+$`.
+  normative_text: |
+    An error code is a machine key, and the moment a client branches on it its spelling becomes API surface. An inconsistent set — `notFound` beside `NOT_FOUND` — produces two codes for one condition, and no amount of testing reconciles them because both are 'working'.
+    The case convention itself is arbitrary; that it is uniform is not.
+  fix_hint: |
+    Use UPPER_SNAKE_CASE consistently:
+
+      { error_code: "orderNotFound" }   // wrong
+      { error_code: "ORDER_NOT_FOUND" } // right
+  exceptions:
+  - Only the `error_code` / `errorCode` key is checked; other string values are out of scope.
+  - Human-readable messages belong in a separate field and are not constrained.
+  - Test files are excluded.
+metadata:
+  aliases:
+  # ERROR-CODE-FORMAT-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - ERROR-CODE-FORMAT-001
+  severity: 4
+  # PORTED verbatim from the python-pytest sibling — the pattern is
+  # language-neutral, so both providers produce the same findings.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

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

@@ -0,0 +1,61 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-header-order
+kind: rule
+status: active
+name: Header fields appear in the canonical order
+statement: >-
+  Where present, header fields MUST appear as URN -> Tested-By -> Runtime -> Purpose. Stack-neutral
+  obligation, Bun-specific detector; realized by `bun_green_traceability_detector` (core alias GREEN-
+  HEADER-004).
+terms:
+- term_id: canonical_order
+  text: >-
+    URN -> Tested-By -> Runtime -> Purpose. Identity, then proof, then execution context, then
+    intent.
+- term_id: present_field
+  text: >-
+    a header field the file actually carries. Absent fields are skipped so this rule never
+    double-reports what another rule owns.
+content:
+  summary: >-
+    An "ordered header" obligation. The detector collects the line numbers of the fields that are present
+    and reports the first that appears before its predecessor. Absent fields are skipped — their absence
+    belongs to the field's own rule.
+  normative_text: |
+    The order is the same in Python, Vite and here, and its value is that a reader — human or tool — knows where to look without parsing. Identity first, then proof, then execution context, then intent: each field answers the question the previous one raises.
+    The rule judges only fields that are present, so it never double-reports a missing field that another rule already owns.
+  fix_hint: |
+    Order the fields URN -> Tested-By -> Runtime -> Purpose:
+
+      // URN: component:orders:checkout:OrderRow:backend:presentation
+      // Tested-By:
+      // - test:orders:checkout:E001-SMOKE-001-renders-row
+      // Runtime: bun
+      // Purpose: render one order row fragment for htmx to swap
+  exceptions:
+  - Files with no URN are skipped — there is nothing to order against.
+  - Fields that are absent are not considered; presence is each field's own rule.
+  - Other comment lines may be interleaved.
+metadata:
+  aliases:
+  # GREEN-HEADER-004 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-header-order. One obligation, three
+  # per-stack detectors, found through this alias.
+  - 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
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector

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

@@ -0,0 +1,55 @@
+schema_version: 1.1.0
+rule_id: coder.bun.green-header-purpose
+kind: rule
+status: active
+name: The header states the file's purpose in one line
+statement: >-
+  Every implementation file MUST carry a `Purpose:` description of at most 80 characters. Stack-neutral
+  obligation, Bun-specific detector; realized by `bun_green_traceability_detector` (core alias GREEN-
+  HEADER-002).
+terms:
+- term_id: purpose_line
+  text: >-
+    a single `Purpose:` line of at most 80 characters stating the file's one job.
+- term_id: length_cap
+  text: >-
+    the 80-character limit. It forces one job to be named, and a purpose that will not fit is
+    evidence the file has more than one.
+content:
+  summary: >-
+    A "one-line purpose" obligation: present, and 80 characters or fewer.
+  normative_text: |
+    The 80-character cap is the whole rule. An unbounded field becomes a paragraph, a paragraph goes stale, and a stale paragraph is worse than no description because it is believed. A single line that must fit forces the author to name the file's one job — and a file whose job will not fit in 80 characters is usually a file doing more than one thing, which makes this a design signal as much as a documentation rule.
+  fix_hint: |
+    State the one job in a single line:
+
+      // Purpose: render one order row fragment for htmx to swap
+
+    If it will not fit, that is evidence the file has more than one responsibility; split it rather than expanding the line.
+  exceptions:
+  - Exactly 80 characters passes; 81 does not.
+  - A missing description is reported at the URN line.
+  - Test files are excluded.
+metadata:
+  aliases:
+  # GREEN-HEADER-002 is the SHARED core alias — the same one carried by the Python
+  # realization and by coder.vite.green-header-purpose. One obligation, three
+  # per-stack detectors, found through this alias.
+  - 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
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_green_traceability_detector