@afokapu/atdd-bun 0.10.39 → 0.10.41

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.complexity-cyclomatic.convention.yaml

@@ -26,12 +26,33 @@ content:
   normative_text: |
     The obligation and its arithmetic are unchanged from the Python realization — deliberately, because a repo that switches providers must not see its numbers move. What changes is only WHO runs the count.
     Cyclomatic complexity is a proxy for how many test cases a function needs before its behaviour is pinned. Above roughly ten paths, complete coverage stops being written, and the untested paths are where defects settle.
+    Treat the score as a sensor for too many independent decisions inside one responsibility, not as an invitation to disguise branching. A useful refactor makes the decision structure easier to name, test, and reason about; moving the same decision tree behind another call or encoding it opaquely only hides the signal.
   fix_hint: |
-    Reduce the branching of the flagged function:
+    Diagnose which decisions belong together before reducing the score.
 
-      * extract nested decision blocks into named helpers,
-      * replace long if / else-if ladders or switch arms with a dispatch map,
-      * collapse compound &&/||/?? conditions into well-named predicates.
+    Diagnose:
+      * group branches by the policy or responsibility they implement,
+      * distinguish validation and guard conditions from the core operation,
+      * identify repeated compound conditions that represent a domain predicate.
+
+    Prefer:
+      * extract a coherent decision or policy into an intention-revealing function,
+      * replace repeated compound conditions with well-named predicates,
+      * use a dispatch table or strategy only when the domain genuinely represents a stable mapping from a key to behavior,
+      * keep the caller's control flow readable enough to reveal the important choices.
+
+    Avoid:
+      * moving the same branch tree unchanged into a generically named helper,
+      * replacing readable control flow with indirect data structures solely to lower the measured score,
+      * scattering one policy across many tiny functions whose interaction is harder to follow than the original,
+      * changing boolean semantics, branch order, or fallback behavior while refactoring.
+
+    Verify:
+      * existing behavior and path-focused tests remain green,
+      * the triggering complexity violation is gone,
+      * extracted code does not create a new nesting, duplication, or length violation,
+      * the resulting decision boundaries correspond to meaningful responsibilities,
+      * the refactor introduces no new ATDD Bun violations.
   exceptions:
   - Functions with fewer than 3 code lines are not scored.
   - Test files and vendored/build directories are outside the scan.

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

@@ -23,8 +23,33 @@ content:
   normative_text: |
     Length is the crudest of the three per-function metrics and the hardest to argue with: a function longer than a screen cannot be read as one unit, so it is read in fragments and its invariants are reconstructed from memory each time.
     It catches a different fault from complexity. A long function may be perfectly linear — fifty sequential assignments score 1 on cyclomatic complexity — and still be doing five things that wanted names.
+    Treat the threshold as a sensor for weak cohesion or multiple responsibilities, not as the design objective. A successful refactor identifies a responsibility or cohesive operation that deserves its own name and boundary. Merely moving enough contiguous lines elsewhere to cross the threshold removes the signal without repairing the smell.
   fix_hint: |
-    Split the function along its internal seams. The comment lines inside a long function usually mark them exactly: each block a comment introduces is a candidate helper, and its comment is the helper's name.
+    Diagnose the design problem before changing the code.
+
+    Diagnose:
+      * identify the distinct responsibilities, stages, or invariants managed by the function,
+      * look for semantic seams: blocks that can be described by one intention-revealing name,
+      * identify the data each candidate responsibility actually needs.
+
+    Prefer:
+      * extract one cohesive responsibility at a time,
+      * name helpers after the purpose they perform rather than the mechanics they contain,
+      * keep related state and decisions together,
+      * leave the original function as a readable description of the top-level flow.
+
+    Avoid:
+      * splitting at an arbitrary line boundary merely to satisfy the 50-line limit,
+      * helpers such as `part1`, `processRest`, `buildLinesAndTotal`, or equivalent names that expose extraction mechanics rather than responsibility,
+      * moving a long or complex block unchanged into another function,
+      * introducing a generalized abstraction unrelated to the responsibility being extracted.
+
+    Verify:
+      * existing behavior and tests remain green,
+      * the triggering length violation is gone,
+      * extracted functions satisfy the applicable complexity and nesting conventions,
+      * the resulting names and boundaries make the responsibilities easier to understand,
+      * the refactor introduces no new ATDD Bun violations.
   exceptions:
   - Blank lines and comment lines are not counted.
   - Test files and vendored/build directories are outside the scan.

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

@@ -24,12 +24,32 @@ content:
   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.
+    Treat excessive depth as a sensor for too much conditional context being carried at once. The objective is to make the execution conditions easier to understand, not merely to remove braces or encode the same nesting in expressions the metric counts differently.
   fix_hint: |
-    Flatten the control flow:
+    Flatten the control flow by removing unnecessary conditional context.
 
-      * 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.
+    Diagnose:
+      * identify conditions that reject work early and can become guards,
+      * identify an inner block that performs one cohesive operation,
+      * identify nested iteration that can be expressed as preparation followed by one clear pass.
+
+    Prefer:
+      * invert conditions into early-return guard clauses when doing so preserves cleanup, error, and ordering semantics,
+      * extract a cohesive inner operation into a named function with a small, meaningful input,
+      * prepare or filter a collection before iterating when that makes the algorithm clearer.
+
+    Avoid:
+      * converting statements into clever boolean or ternary expressions solely to evade the depth count,
+      * extracting an inner block that requires a long parameter list or still depends on the caller's hidden conditional context,
+      * duplicating cleanup, logging, or error handling across new guard clauses,
+      * changing evaluation order or exception behavior while flattening the function.
+
+    Verify:
+      * existing behavior and tests remain green, including error and boundary paths,
+      * the triggering nesting violation is gone,
+      * the flattened flow reads with fewer simultaneous preconditions,
+      * extracted functions satisfy the applicable length and complexity conventions,
+      * the refactor introduces no new ATDD Bun violations.
   exceptions:
   - Functions with fewer than 3 code lines are not scored.
   - Comment lines are ignored when measuring brace balance.

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.dead-code-reachability.convention.yaml

@@ -28,8 +28,32 @@ content:
     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.
+    Treat an unreachable file as a sensor for unclear ownership or incomplete integration, not as a request to manufacture an import edge. A meaningful repair either removes code that has no runtime responsibility or connects code through the module that genuinely owns and uses it.
   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.
+    Decide first whether the reported file should exist at runtime.
+
+    Diagnose:
+      * identify the responsibility the file claims to own,
+      * find the module that would naturally call or import it if that responsibility is required,
+      * determine whether the file is obsolete, incompletely integrated, or only carrying types.
+
+    Prefer:
+      * delete code that is genuinely unused,
+      * wire required runtime behavior through the module that owns that behavior,
+      * move a type into the module that uses it when the remaining file has no runtime values.
+
+    Avoid:
+      * adding a dummy import, barrel export, or other synthetic edge solely to make the file reachable,
+      * introducing a side-effect import unless the side effect is itself required runtime behavior,
+      * renaming or relocating a file merely to exploit structural-root detection,
+      * preserving obsolete code "just in case" instead of removing it.
+
+    Verify:
+      * existing behavior and tests remain green,
+      * any new import represents a real runtime dependency,
+      * deleted code has no required caller or entry point,
+      * the reachability finding is gone without creating a new architecture or dependency-flow violation,
+      * the refactor introduces no new ATDD Bun violations.
   exceptions:
   - "`index.ts` / `index.tsx` are structural (like `__init__.py`) and are never reported."
   - Test files are entrypoints, not dead code, and are excluded.

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.