@afokapu/atdd-bun 0.10.40 → 0.10.42

package/conventions/_profiles/coder.yaml

@@ -91,6 +91,8 @@ conventions:
     path: "conventions/coder.bun/coder.bun.green-urn-wagon-feature.convention.yaml"
   - rule_id: "coder.bun.layer-naming"
     path: "conventions/coder.bun/coder.bun.layer-naming.convention.yaml"
+  - rule_id: "coder.bun.phase-discipline"
+    path: "conventions/coder.bun/coder.bun.phase-discipline.convention.yaml"
   - rule_id: "coder.bun.quality-comments"
     path: "conventions/coder.bun/coder.bun.quality-comments.convention.yaml"
   - rule_id: "coder.bun.quality-mi"
@@ -602,6 +604,76 @@ relationships:
     strength: "critical"
     target_ref: "coder.bun.design-hierarchy-import"
     type: "enables"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.complexity-cyclomatic"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.complexity-length"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.complexity-nesting"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.dead-code-reachability"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.duplication-intra-layer"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.quality-comments"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.quality-mi"
+    type: "runs_alongside"
   - confidence: 1
     constraint: "mandatory"
     control: "internal"

package/conventions/_profiles/metrics.yaml

@@ -58,6 +58,76 @@ relationships:
     strength: "minor"
     target_ref: "coder.bun.dead-code-reachability"
     type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.complexity-cyclomatic"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.complexity-length"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.complexity-nesting"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.dead-code-reachability"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.duplication-intra-layer"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.quality-comments"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "phase discipline directs the response to each refactor sensor without weakening its enforcement"
+    source_ref: "coder.bun.phase-discipline"
+    strength: "important"
+    target_ref: "coder.bun.quality-mi"
+    type: "runs_alongside"
   - confidence: 1
     constraint: "mandatory"
     control: "internal"

package/conventions/coder.bun/coder.bun.boundaries-http-client.convention.yaml

@@ -25,7 +25,23 @@ content:
     A centralized client is where retries, timeouts, auth headers, tracing and error translation live. Every bare `fetch` is a call site that has none of them and will not acquire them, because nobody remembers it exists.
     In an htmx app this matters on the SERVER side particularly: the fragments a handler renders often depend on an upstream call, and a bare fetch there fails in a way the user sees as a blank swap.
   fix_hint: |
-    Call the client in `integration/` and let it own the cross-cutting concerns.
+    Canonical path:
+      * use the existing integration-layer HTTP client or adapter,
+      * let that boundary own transport concerns such as headers, retries, decoding, and error translation.
+    
+    During GREEN:
+      * make only the outbound call and mapping required by the current acceptance,
+      * reuse an existing client or port before introducing another abstraction,
+      * if no compliant boundary exists, add the smallest integration adapter the behavior requires.
+    
+    Do not broaden:
+      * do not migrate unrelated callers,
+      * do not create a generalized HTTP framework for hypothetical endpoints,
+      * do not call `fetch()` or `axios` directly just to make the test pass.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the affected source satisfies this boundary rule.
   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.commons-application-no-integration.convention.yaml

@@ -22,7 +22,23 @@ content:
   normative_text: |
     The application layer orchestrates through ports it defines. Reaching into integration inverts the dependency and welds orchestration to a specific transport, so changing the transport changes the orchestration.
   fix_hint: |
-    Define the port in `application/` and let `integration/` implement it; the composition root supplies the implementation.
+    Canonical path:
+      * keep commons application code dependent on an application-facing port,
+      * let integration implement that port and let the composition root supply it.
+    
+    During GREEN:
+      * first reuse an existing port that already represents the required capability,
+      * add the smallest missing port only when the current behavior genuinely needs an outer capability,
+      * pass only the data or collaborator required by the acceptance.
+    
+    Do not broaden:
+      * do not reorganize unrelated commons modules,
+      * do not introduce a generalized service layer for future callers,
+      * do not import integration directly as a shortcut to GREEN.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * commons application has no integration dependency.
   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.commons-cross-feature-imports-in.convention.yaml

@@ -21,7 +21,22 @@ content:
   normative_text: |
     A feature's internals are its own. The layer root is the surface it deliberately exposes, and reaching past it couples two features through a path that neither of them chose to publish — which is how a shared module quietly becomes unsplittable.
   fix_hint: |
-    Import from the layer root, and if the thing you need is not exported there, that is the decision to make explicit — export it, or move it.
+    Canonical path:
+      * consume another commons feature through the layer root, never through that sibling's internals.
+    
+    During GREEN:
+      * reuse an export that already represents the required capability,
+      * if the capability is intentionally shared, expose the smallest stable surface from the layer root,
+      * if it is not a shared responsibility, keep the implementation local instead of reaching across.
+    
+    Do not broaden:
+      * do not export a sibling's internals wholesale,
+      * do not create a generic shared module merely to make the import legal,
+      * do not move unrelated code between features.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the cross-feature dependency goes through the intended public 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.commons-domain-no-framework-import.convention.yaml

@@ -22,7 +22,23 @@ content:
     The Vite sibling forbids react/preact/@tanstack/gsap because those are ITS frameworks. The obligation is identical — the domain expresses rules, not machinery — and only the list of machinery changes with the stack. For a full-stack Bun app the machinery is the server and transport primitives.
     The practical test: the domain must be runnable with no server started. `Bun.` in a domain module means it is not.
   fix_hint: |
-    Move the machinery to `integration/` and pass the result in. A domain function should take data and return data.
+    Canonical path:
+      * keep domain code as data-in / data-out logic,
+      * move Bun, Node, htmx, server, or framework machinery to an outer layer and pass the needed value inward.
+    
+    During GREEN:
+      * adapt at the nearest existing integration or presentation boundary,
+      * pass the smallest value or domain-facing collaborator the behavior needs,
+      * add a new boundary only when no existing one can express the current behavior correctly.
+    
+    Do not broaden:
+      * do not wrap a framework API in a domain-named helper and keep the coupling,
+      * do not redesign adjacent layers,
+      * do not import runtime machinery just to satisfy the acceptance quickly.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the domain remains executable without runtime machinery.
   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.commons-domain-no-outbound.convention.yaml

@@ -23,7 +23,23 @@ content:
     Dependencies point INWARD only. The domain is the centre: it holds the rules, and it must not know what orchestrates them or what transports them.
     An outward import inverts that and makes the rules unusable without the machinery — which shows up first as a domain test that needs a database.
   fix_hint: |
-    Move the shared thing into the domain, or invert the dependency by defining a port in the domain that the outer layer implements.
+    Canonical path:
+      * keep commons domain dependencies inward,
+      * move genuinely domain-owned data or behavior into domain, or invert an outer capability behind a domain-facing port.
+    
+    During GREEN:
+      * prefer existing domain types, functions, and ports,
+      * introduce a new port only when the current behavior requires the domain to request an outer capability,
+      * keep the port as narrow as the acceptance requires.
+    
+    Do not broaden:
+      * do not move unrelated application or integration behavior into domain,
+      * do not invent a future-proof abstraction,
+      * do not import outward as a temporary shortcut.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * commons domain imports no application or integration code.
   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.composition-consumer.convention.yaml

@@ -22,7 +22,22 @@ content:
     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.
+    Canonical path:
+      * receive collaborators through parameters or already-wired construction,
+      * let the composition root decide which concrete collaborator is supplied.
+    
+    During GREEN:
+      * reuse the consumer's existing injection shape when one exists,
+      * add only the collaborator required by the current behavior,
+      * prefer the narrowest existing contract over a new generalized interface.
+    
+    Do not broaden:
+      * do not instantiate a repository, client, service, adapter, gateway, store, provider, or factory inside the consumer,
+      * do not redesign unrelated constructor or function signatures.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * the consumer can be exercised with its collaborator supplied from outside.
   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.composition-root.convention.yaml

@@ -24,7 +24,23 @@ content:
     `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.
+    Canonical path:
+      * construct collaborators in `composition.ts`, `wagon.ts`, `server.ts`, or `index.ts`,
+      * pass the constructed collaborator to the consumer that needs it.
+    
+    During GREEN:
+      * add only the wiring required by the current behavior,
+      * reuse existing factories, instances, and composition patterns before creating new ones,
+      * keep construction separate from application or presentation behavior.
+    
+    Do not broaden:
+      * do not centralize unrelated wiring merely because the root is being edited,
+      * do not add speculative factories or service locators,
+      * do not instantiate the collaborator in the consumer as a shortcut.
+    
+    Prove:
+      * the current behavioral acceptance passes through the real wiring,
+      * collaborator construction remains confined to a composition root.
   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.design-connected.convention.yaml

@@ -18,7 +18,23 @@ content:
   summary: Flags rendering component files outside the design root that import nothing from it.
   normative_text: A screen built without the system is where the next one-off style lands. Requiring one design
     import makes the connection explicit and reviewable.
-  fix_hint: Compose the screen from a template, component, or primitive — at minimum wrap it in the page template.
+  fix_hint: |
+    Canonical path:
+      * compose application UI from the existing design-system template, component, or primitive that owns the required role.
+    
+    During GREEN:
+      * reuse the nearest existing design-system surface before creating a new one,
+      * add only the connection required by the current rendered behavior,
+      * if no suitable surface exists, introduce the smallest design-system component that expresses the current need.
+    
+    Do not broaden:
+      * do not redesign the screen or migrate unrelated markup,
+      * do not create a generic component library for hypothetical callers,
+      * do not add a meaningless import merely to satisfy connectivity.
+    
+    Prove:
+      * the current behavioral or rendering acceptance passes,
+      * the rendered app component is genuinely composed from the design system.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - Non-rendering modules (routes, handlers, data) are not judged.

package/conventions/coder.bun/coder.bun.design-dependency-flow.convention.yaml

@@ -19,8 +19,23 @@ content:
   summary: Resolves each import of a design-system file to its target layer and flags any edge that points upward.
   normative_text: A hierarchy is only a hierarchy if dependencies flow one way. A primitive that imports a component
     can no longer be reused without dragging that component along, and the layers collapse into one tangle.
-  fix_hint: 'Move the shared piece down to the lowest layer that needs it, or compose upward: the component imports
-    the primitive, never the reverse.'
+  fix_hint: |
+    Canonical path:
+      * keep design-system imports at the same layer or pointing downward through tokens -> foundations -> primitives -> components -> templates.
+    
+    During GREEN:
+      * reuse an existing lower-layer value or component when possible,
+      * move a genuinely shared piece only to the lowest layer that actually owns it,
+      * compose upward rather than importing upward.
+    
+    Do not broaden:
+      * do not reshuffle unrelated design-system files,
+      * do not create a new layer or generic abstraction for one dependency,
+      * do not hide an upward dependency behind a barrel.
+    
+    Prove:
+      * the current behavioral or rendering acceptance passes,
+      * all affected design-system imports follow the declared direction.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - Imports within the same layer are allowed.

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

@@ -24,7 +24,23 @@ content:
     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.
+    Canonical path:
+      * depend inward through presentation -> application -> domain, with integration depending on application/domain and assembly allowed to wire all layers,
+      * when an inner layer needs an outer capability, use an existing inward-facing port.
+    
+    During GREEN:
+      * reuse the nearest existing compliant dependency path,
+      * introduce the smallest missing port only when the current behavior cannot otherwise be implemented correctly,
+      * keep the new contract limited to what the acceptance requires.
+    
+    Do not broaden:
+      * do not reclassify or merge layers merely to make one import legal,
+      * do not redesign adjacent modules,
+      * do not add a dependency that points outward as a temporary step.
+    
+    Prove:
+      * the current behavioral acceptance passes,
+      * every affected import still points in an allowed direction.
   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.design-orphan-export.convention.yaml

@@ -18,8 +18,23 @@ content:
   summary: Collects capitalized exports of primitives/components/templates and flags those no other file imports.
   normative_text: Unused components still have to be maintained, themed, and migrated. A design system grows by
     adjudication, not by accretion of pieces nobody uses.
-  fix_hint: 'Use the component where it was meant to be used, or delete it. Unused chains surface one layer at a
-    time: remove the unused template and its component is reported next.'
+  fix_hint: |
+    Canonical path:
+      * export a design-system component only when a real consumer uses it; otherwise remove the unused export.
+    
+    During GREEN:
+      * if the current acceptance needs the component, wire that actual consumer to it,
+      * if the export was introduced speculatively and has no required consumer, delete it,
+      * keep only the smallest export surface the current behavior needs.
+    
+    Do not broaden:
+      * do not add a dummy consumer or synthetic import,
+      * do not keep speculative components "for later",
+      * do not expose unrelated internals from a barrel to make the graph look connected.
+    
+    Prove:
+      * the current behavioral or rendering acceptance passes,
+      * every affected export has a genuine consumer.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - Token/foundation values and `index.*` barrels are not judged.

package/conventions/coder.bun/coder.bun.design-primitives.convention.yaml

@@ -17,8 +17,23 @@ content:
   summary: Flags raw interactive platform elements in component source outside the design root.
   normative_text: Controls are where focus, disabled, error, and loading states live. Each raw control re-implements
     them, and each re-implementation diverges.
-  fix_hint: 'Render the primitive and pass htmx attributes through it: `<Button hx-post="/orders">Place</Button>`.
-    Add the primitive to `design/primitives/` if it does not exist yet.'
+  fix_hint: |
+    Canonical path:
+      * render interactive controls through the existing design-system primitive and pass required htmx or DOM attributes through it.
+    
+    During GREEN:
+      * reuse the primitive that already represents the control,
+      * extend only the smallest prop or attribute surface required by the current interaction,
+      * create a new primitive only when no existing primitive represents the control correctly.
+    
+    Do not broaden:
+      * do not restyle or migrate unrelated controls,
+      * do not bypass the primitive with raw interactive markup just to pass the acceptance,
+      * do not add generic props that the current behavior does not need.
+    
+    Prove:
+      * the interaction acceptance passes,
+      * the rendered interactive control comes through the design-system primitive.
   exceptions:
   - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
   - The design system's own primitives render the raw elements and are not scanned.

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.