@afokapu/atdd-bun 0.10.39 → 0.10.41

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

@@ -20,7 +20,23 @@ content:
     raw color literals in their values.
   normative_text: A raw color is a theme decision made in one place. It does not follow dark mode, it drifts from
     the palette, and nobody can find it when the palette changes.
-  fix_hint: 'Define the color once as a custom property in the tokens layer and reference it: `color: var(--danger)`.'
+  fix_hint: |
+    Canonical path:
+      * define the required color once in the tokens layer and reference that token from UI code.
+    
+    During GREEN:
+      * reuse an existing semantic color token when it already expresses the required role,
+      * add the smallest new semantic token only when the current visual behavior needs a distinct value,
+      * change only the affected UI reference.
+    
+    Do not broaden:
+      * do not retheme unrelated components,
+      * do not duplicate an existing token under a new name,
+      * do not use a raw literal as a temporary shortcut.
+    
+    Prove:
+      * the current visual or behavioral acceptance passes,
+      * affected UI files contain no raw color literal outside the tokens layer.
   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.'

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

@@ -20,8 +20,23 @@ content:
     the design system's own primitives and components.
   normative_text: Spacing and motion are the rhythm of an interface. Each hardcoded `13px` is a new step on a scale
     nobody chose, and the rhythm erodes one component at a time.
-  fix_hint: 'Use the foundations scale: `padding: var(--space-3)`, `border-radius: var(--radius)`, `transition:
-    opacity var(--fast)`. Add a step to the scale in the tokens layer if none fits.'
+  fix_hint: |
+    Canonical path:
+      * take spacing, inset, radius, and duration values from the existing foundations scale.
+    
+    During GREEN:
+      * reuse the nearest existing semantic or scale token,
+      * add a new foundation value only when the current design genuinely requires a distinct value,
+      * change only the declaration needed by the acceptance.
+    
+    Do not broaden:
+      * do not normalize unrelated styling,
+      * do not create one-off tokens that merely rename a hardcoded literal,
+      * do not bypass the scale for speed.
+    
+    Prove:
+      * the current visual or behavioral acceptance passes,
+      * affected UI values come from the declared foundations.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - 0 and 1px (hairline borders) are not design decisions and are allowed.

package/conventions/coder.bun/coder.bun.design-tokens-pure.convention.yaml

@@ -18,8 +18,24 @@ content:
   summary: Scans token/foundation code files for renderer imports, rendered markup, and control flow.
   normative_text: Tokens are what every other layer depends on. Once they render or decide, the bottom of the hierarchy
     has behaviour, and every primitive inherits it.
-  fix_hint: Keep the value in the token file and move the markup to `primitives/` or the logic to the component
-    that needs it.
+  fix_hint: |
+    Canonical path:
+      * keep tokens and foundations as values only,
+      * move markup to primitives/components and behavior to the layer that owns it.
+    
+    During GREEN:
+      * leave the value in the token or foundation file,
+      * move only the markup or logic required by the current behavior to the nearest existing owning layer,
+      * reuse an existing primitive or component before creating a new one.
+    
+    Do not broaden:
+      * do not reorganize unrelated tokens,
+      * do not move behavior into a different layer merely to silence the rule,
+      * do not create a generalized component unrelated to the current acceptance.
+    
+    Prove:
+      * the current behavioral or rendering acceptance passes,
+      * token and foundation files remain value-only.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - '`.css` token files are values by construction and are not scanned by this rule.'

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

@@ -17,8 +17,24 @@ content:
   summary: Flags relative imports from a design-system file that leave the design root.
   normative_text: 'A design system that reaches into a wagon has become part of that wagon: it cannot be reused
     by the next one, and a change to the wagon breaks the system.'
-  fix_hint: Pass the value in as a prop, or move the shared type or constant into the design system (or a shared
-    commons module) so the dependency points inward.
+  fix_hint: |
+    Canonical path:
+      * keep the design system independent of application and wagon code,
+      * pass app-specific values into design components or move genuinely shared, design-owned types/constants inward.
+    
+    During GREEN:
+      * prefer props or existing design-system contracts for the current value,
+      * add only the smallest input surface required by the acceptance,
+      * move a type or constant only when it is truly owned by the design system.
+    
+    Do not broaden:
+      * do not import a wagon through a barrel or alias,
+      * do not relocate app-specific concepts into design code just to make the import legal,
+      * do not generalize unrelated design APIs.
+    
+    Prove:
+      * the current behavioral or rendering acceptance passes,
+      * design-system files import nothing from app or wagon code.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - Bare package specifiers (`hono/jsx`) are outside the project graph and are not judged.

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

@@ -20,7 +20,22 @@ content:
   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.
+    Canonical path:
+      * keep DTO-to-domain and domain-to-DTO translation in the integration layer where both shapes are legitimately visible.
+    
+    During GREEN:
+      * reuse an existing mapper for the same boundary when one exists,
+      * add only the field mapping required by the current acceptance,
+      * create a new mapper only for a genuinely new boundary translation.
+    
+    Do not broaden:
+      * do not move domain behavior into the mapper,
+      * do not migrate unrelated mappings,
+      * do not place translation in presentation or domain as a shortcut.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the mapper lives in integration and preserves the intended boundary.
   exceptions:
   - Test files and vendored/build directories are never scanned.
   - Bare npm specifiers resolve outside the project graph and are not layer-checked.

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

@@ -21,7 +21,22 @@ content:
   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.
+    Canonical path:
+      * declare a DTO in `contracts/` and import that shared boundary shape from both sides.
+    
+    During GREEN:
+      * reuse an existing contract type when it already represents the required payload,
+      * add only the fields required by the current acceptance,
+      * create a new DTO only when the behavior introduces a genuinely distinct boundary shape.
+    
+    Do not broaden:
+      * do not move unrelated internal types into contracts,
+      * do not add speculative fields for future callers,
+      * do not declare the DTO inside a feature layer as a temporary shortcut.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * every affected DTO declaration lives under `contracts/`.
   exceptions:
   - Test files and vendored/build directories are never scanned.
   - Bare npm specifiers resolve outside the project graph and are not layer-checked.

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

@@ -22,7 +22,23 @@ content:
     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`.
+    Canonical path:
+      * keep DTOs as immutable data: readonly fields and no methods,
+      * put behavior in the layer that consumes or produces the DTO.
+    
+    During GREEN:
+      * add only the readonly data fields required by the current boundary behavior,
+      * reuse existing functions for transformation or behavior when available,
+      * add a small free function only when the current acceptance needs it.
+    
+    Do not broaden:
+      * do not attach convenience methods to the DTO,
+      * do not make fields mutable to simplify implementation,
+      * do not introduce unrelated helpers or abstractions.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the affected DTO remains pure immutable data.
   exceptions:
   - Test files and vendored/build directories are never scanned.
   - Bare npm specifiers resolve outside the project graph and are not layer-checked.

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

@@ -26,8 +26,32 @@ content:
   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.
+    Treat a duplicate fingerprint as a sensor that two sites may share one responsibility or change reason. The goal is not to make the fingerprints differ; it is to decide whether the two fragments represent one concept that should be owned once or two concepts whose real semantic differences should remain independent.
   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.
+    Compare the duplicated sites semantically before extracting anything.
+
+    Diagnose:
+      * determine whether both fragments implement the same responsibility and should change for the same reason,
+      * identify the smallest stable behavior they genuinely share,
+      * check that the shared behavior belongs inside the same architectural layer.
+
+    Prefer:
+      * extract a focused function or module within that layer when both sites represent one concept,
+      * give the shared behavior a domain- or responsibility-revealing name,
+      * when the sites represent different responsibilities, preserve their independence and express any real semantic differences directly.
+
+    Avoid:
+      * renaming identifiers, changing literals, reordering harmless statements, or making other cosmetic edits solely to defeat normalization,
+      * creating a cross-layer abstraction just because two layers contain similar-shaped code,
+      * extracting a highly parameterized generic helper that obscures the two callers' intent,
+      * forcing distinct responsibilities into one abstraction merely to remove the finding.
+
+    Verify:
+      * existing behavior and tests remain green,
+      * the duplicate is removed because ownership became clearer or because genuine semantic differences are now explicit,
+      * dependency direction and layer boundaries remain valid,
+      * the extracted abstraction has one coherent reason to change,
+      * the refactor introduces no new ATDD Bun violations.
   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.

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

@@ -25,13 +25,21 @@ content:
     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
+    Canonical path:
+      * order present traceability fields as URN -> Tested-By -> Runtime -> Purpose.
+    
+    During GREEN:
+      * keep the existing field values unless another convention proves one is wrong,
+      * reorder only the header lines needed to restore the canonical sequence,
+      * preserve unrelated comments.
+    
+    Do not broaden:
+      * do not rewrite identifiers, acceptance bindings, runtime, or purpose merely while fixing order,
+      * do not move implementation code to satisfy a header-order finding.
+    
+    Prove:
+      * the current behavioral acceptance still passes,
+      * the present header fields appear in canonical order.
   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.

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

@@ -21,11 +21,22 @@ content:
   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.
+    Canonical path:
+      * state the file's one actual job in a single `Purpose:` line of at most 80 characters.
+    
+    During GREEN:
+      * derive the purpose from the responsibility introduced for the current acceptance,
+      * use concrete responsibility language rather than implementation mechanics,
+      * if the purpose genuinely cannot fit because the new file owns multiple jobs, split only the responsibilities required by the current behavior.
+    
+    Do not broaden:
+      * do not invent a vague purpose just to meet the length cap,
+      * do not perform unrelated decomposition,
+      * do not describe hypothetical future responsibilities.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the purpose truthfully names one job and fits the limit.
   exceptions:
   - Exactly 80 characters passes; 81 does not.
   - A missing description is reported at the URN line.

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

@@ -22,12 +22,21 @@ content:
   normative_text: |
     `isomorphic` has no Vite counterpart and is the substantive addition. A bundler stack decides at BUILD time which code reaches the browser, so a file is server or client by where the bundler puts it. Bun decides at RUN time, and a full-stack Bun app routinely runs one module in both places — a fragment renderer used server-side and again after a client-side swap. Without a value for that, authors would be forced to pick a wrong one, and every downstream reader would inherit the error.
   fix_hint: |
-    Declare the runtime the file actually executes in:
-
-      // Runtime: deno         // ✗ not this stack
-      // Runtime: bun          // ✓ server-side
-      // Runtime: browser      // ✓ ships to the client
-      // Runtime: isomorphic   // ✓ genuinely runs in both
+    Canonical path:
+      * declare the runtime where the file actually executes: `bun`, `browser`, or `isomorphic`.
+    
+    During GREEN:
+      * derive the value from the real execution path created or used by the current acceptance,
+      * keep an existing correct runtime declaration,
+      * change only the header when the implementation already executes in the correct place.
+    
+    Do not broaden:
+      * do not move code between server and browser merely to fit a preferred label,
+      * do not guess `isomorphic` because the file could theoretically run in both places.
+    
+    Prove:
+      * the current behavioral acceptance passes in its real runtime,
+      * the declaration matches where the file actually executes.
   exceptions:
   - A missing declaration is reported at the URN line (or the first meaningful line when there is no URN).
   - Test files are excluded.

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

@@ -23,17 +23,22 @@ content:
     This is the rule that makes the whole header load-bearing rather than decorative. The URN says what the file IS; `Tested-By:` says what PROVES it. Together they close the loop from acceptance to implementation that ATDD exists to keep closed — which is exactly the loop that a stack migration breaks silently, because the new files are written without headers and nothing notices.
     An empty block is treated as absent deliberately: it is the shape a half-finished backfill leaves behind, and accepting it would let a repo report full header coverage with zero acceptance bindings.
   fix_hint: |
-    Name at least one acceptance:
-
-      // Tested-By:
-      // - test:orders:checkout:E001-SMOKE-001-renders-row
-
-    and in a template:
-
-      <!-- Tested-By: -->
-      <!-- - test:orders:checkout:E001-SMOKE-002-panel-loads -->
-
-    Whether the named acceptances EXIST is a plan-graph question this rule cannot answer; it enforces that the binding is declared.
+    Canonical path:
+      * bind the implementation file to at least one real acceptance URN in its `Tested-By:` block.
+    
+    During GREEN:
+      * derive the binding from the acceptance currently being implemented,
+      * keep existing valid bindings and add only the acceptance that genuinely covers this file,
+      * use the exact declared acceptance URN.
+    
+    Do not broaden:
+      * do not invent acceptance IDs,
+      * do not add unrelated tests merely to make the block non-empty,
+      * do not claim coverage from an acceptance that does not exercise the implementation.
+    
+    Prove:
+      * the named behavioral acceptance passes,
+      * the file's `Tested-By:` block names the acceptance that actually proves it.
   exceptions:
   - Test files are excluded — they are the other end of this binding.
   - One entry satisfies the rule; more are encouraged.

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

@@ -21,10 +21,22 @@ content:
   normative_text: |
     The layer segment is what the boundary and dependency-flow rules read to decide whether an import is legal. A file declaring a layer outside the vocabulary is not merely mislabelled — it is unreachable by every layering rule, so it becomes a hole through which any dependency may pass unchallenged.
   fix_hint: |
-    Use a layer from the vocabulary:
-
-      // URN: component:orders:checkout:OrderRow:backend:widgets       // ✗
-      // URN: component:orders:checkout:OrderRow:backend:presentation  // ✓
+    Canonical path:
+      * declare one of `domain`, `application`, `integration`, `presentation`, or `assembly` according to the file's real responsibility.
+    
+    During GREEN:
+      * derive the layer from the existing architecture and the responsibility required by the current acceptance,
+      * follow the nearest existing compliant feature pattern,
+      * if the file is actually misplaced, move only the affected implementation to its proper layer.
+    
+    Do not broaden:
+      * do not invent a new layer,
+      * do not relabel a misplaced module to make dependency checks disappear,
+      * do not reorganize adjacent features.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the URN layer matches the implementation's actual architectural layer.
   exceptions:
   - URNs that are not six segments are skipped.
   - The vocabulary is fixed by core, not by this extension; a new layer is a core change.

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

@@ -28,15 +28,22 @@ content:
     The URN is the only edge between a source file and the plan graph. Without it a file is invisible to traceability: no acceptance can claim it, no wagon owns it, and coverage reporting cannot see it exists.
     "First meaningful line" excludes a shebang (`#!/usr/bin/env bun`) and an HTML doctype, because neither is content and neither should be able to displace the marker. The Vite sibling counts a shebang as the first non-empty line and so reports a header it actually has as missing; this realization does not.
   fix_hint: |
-    Put the marker on the first meaningful line:
-
-      // URN: component:orders:checkout:OrderRow:backend:presentation
-
-    and in a template:
-
-      <!doctype html>
-      <!-- URN: component:orders:checkout:OrderPanel:frontend:presentation -->
-
+    Canonical path:
+      * put the component URN on the first meaningful line, after only an allowed shebang or HTML doctype.
+    
+    During GREEN:
+      * derive the URN from the plan ownership of the implementation being added,
+      * use source-comment syntax for code and HTML-comment syntax for templates,
+      * add only the marker; do not restructure the file when the implementation is otherwise correctly placed.
+    
+    Do not broaden:
+      * do not invent a wagon, feature, component, side, or layer,
+      * do not copy a nearby file's URN without verifying ownership,
+      * do not move code merely to make the marker easier to write.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the file is traceable from its real component URN.
   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.

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

@@ -23,11 +23,22 @@ content:
     A URN naming a different component than the file it sits in is worse than a missing one: it binds the file's evidence to somebody else's component, so both are wrong and neither is obviously wrong. This is the failure a copy-pasted header produces, which is how it usually arises.
     The exempt set is the Vite set plus this stack's idioms — `server`, `routes`, `layout`, `partial`, `fragment`, `middleware` — because a full-stack Bun app's entrypoint is `server.ts` and its htmx fragments are named for their role, not for a component.
   fix_hint: |
-    Make the name segment agree with the filename, or use a structural role name:
-
-      // in OrderRow.ts
-      // URN: component:orders:checkout:SomethingElse:backend:presentation  // ✗
-      // URN: component:orders:checkout:OrderRow:backend:presentation       // ✓
+    Canonical path:
+      * make the URN `{Name}` identify the component implemented by the file and match its basename under the rule's normalization, unless the file has an exempt structural role.
+    
+    During GREEN:
+      * derive the name from the actual file/component being implemented,
+      * correct a copied or stale header before considering a file rename,
+      * keep structural-role filenames as structural roles when that is their real responsibility.
+    
+    Do not broaden:
+      * do not rename a correctly named component merely to preserve a wrong URN,
+      * do not use an exempt structural name to evade component identity,
+      * do not change unrelated identity segments.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the URN name and implementation identity agree.
   exceptions:
   - 'Structural names are exempt: composition, wagon, entrypoint, http, index, schema, router, routes, server, layout, partial, fragment, middleware.'
   - Comparison ignores case and non-alphanumerics, so `order-row.ts` matches `OrderRow`.

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

@@ -24,10 +24,22 @@ content:
   normative_text: |
     Each segment is a join key. Wagon and feature locate the work item, name identifies the component, side and layer place it in the architecture. A URN missing a segment does not degrade gracefully — it resolves to nothing, and the file is as unbound as one with no marker at all, while LOOKING traceable in review.
   fix_hint: |
-    Supply every segment:
-
-      // URN: component:orders:checkout:OrderRow                       // ✗ four segments
-      // URN: component:orders:checkout:OrderRow:backend:presentation  // ✓
+    Canonical path:
+      * use exactly `component:{wagon}:{feature}:{Name}:{side}:{layer}` with every segment present.
+    
+    During GREEN:
+      * derive each segment from the plan, filename, execution side, and architectural responsibility,
+      * fix only the malformed or missing segment,
+      * keep already-correct identity segments unchanged.
+    
+    Do not broaden:
+      * do not invent placeholder segments,
+      * do not rename implementation artifacts solely to make a guessed URN fit,
+      * do not alter plan ownership while fixing URN grammar.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the URN has the canonical six-segment shape.
   exceptions:
   - A file with no `URN:` marker is skipped (owned by `green-urn-marker`).
   - Segment CONTENT is validated by the wagon-feature, name, side and layer rules; this rule checks shape only.

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

@@ -20,12 +20,21 @@ content:
   normative_text: |
     The vocabulary is unchanged from the Python and Vite realizations, and it matters MORE in a full-stack Bun app than in either. A Vite repo is frontend by construction and a python-pytest service is backend by construction, so the segment is close to redundant there. Here one repo, one language and one runtime span both halves, and the only thing that says which side a module belongs to is this segment — so it must be declared per file and cannot be inferred from the stack.
   fix_hint: |
-    Declare the side explicitly:
-
-      // URN: component:orders:checkout:OrderRow:server:presentation    // ✗ not a side
-      // URN: component:orders:checkout:OrderRow:backend:presentation   // ✓
-
-    Server-rendered htmx fragments are `backend` (they are produced by the server); markup and behaviour that live in the browser are `frontend`.
+    Canonical path:
+      * declare `frontend` for browser-owned implementation and `backend` for server-owned implementation.
+    
+    During GREEN:
+      * derive side from where responsibility lives, not merely from file syntax,
+      * treat server-rendered htmx fragments as backend and browser-resident behavior as frontend,
+      * change only the side segment when the rest of the URN is correct.
+    
+    Do not broaden:
+      * do not move implementation between client and server just to fix a header,
+      * do not use `Runtime:` as a substitute for the side decision.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the side segment matches the implementation's real ownership.
   exceptions:
   - URNs that are not six segments are skipped.
   - "`Runtime:` is a different axis — a `backend` file may declare `Runtime: isomorphic`."

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

@@ -22,12 +22,21 @@ content:
   normative_text: |
     Wagon and feature are join keys into `plan/`, and a join key that is case- or separator-sensitive fails silently: `Orders` and `orders` are two different wagons to a string match, so a header with the wrong casing binds to nothing while reading correctly to a human. Kebab-case is the plan's own grammar, so the header must use it exactly.
   fix_hint: |
-    Lower-case and hyphenate:
-
-      // URN: component:Orders:Check_Out:OrderRow:backend:presentation  // ✗
-      // URN: component:orders:check-out:OrderRow:backend:presentation  // ✓
-
-    The `{Name}` segment is deliberately NOT kebab — it mirrors the filename and keeps its own casing.
+    Canonical path:
+      * use the exact plan wagon and feature identifiers in lowercase kebab-case.
+    
+    During GREEN:
+      * derive both values from the feature currently being implemented,
+      * normalize only casing or separators when the identity is already correct,
+      * keep the component name, side, and layer untouched.
+    
+    Do not broaden:
+      * do not invent or rename plan wagons/features to satisfy the source header,
+      * do not copy identifiers from a neighboring feature without checking ownership.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * wagon and feature segments match the plan's canonical identifiers.
   exceptions:
   - URNs that are not six well-formed segments are skipped (owned by `green-urn-pattern`).
   - The name, side and layer segments are governed by their own rules.

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

@@ -23,7 +23,22 @@ content:
     ADDED TO THE MIRROR, and worth flagging: the Convex sibling accepts only the FILENAME form, because its function tree is flat. A full-stack Bun repo commonly nests (`features/orders/domain/total.ts`), so accepting only filenames would refuse the idiomatic layout. This realization accepts BOTH.
     The obligation is unchanged: a reader should know a file's role before opening it, and the layering rules need something to read.
   fix_hint: |
-    Either rename the file to its layer, or move it into the layer directory it belongs to.
+    Canonical path:
+      * place the module in the architectural layer that owns its responsibility, or name the file with that layer when the repository uses the filename form.
+    
+    During GREEN:
+      * derive the layer from the responsibility the current behavior actually implements,
+      * follow the nearest existing feature layout,
+      * move or rename only the affected module when placement is wrong.
+    
+    Do not broaden:
+      * do not reorganize sibling features,
+      * do not invent a new layer name,
+      * do not choose a layer merely to make another import rule pass.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the file's declared location or name matches its actual architectural responsibility.
   exceptions:
   - Test files and vendored/build directories are never scanned.
   - Bare npm specifiers resolve outside the project graph and are not layer-checked.