@afokapu/atdd-bun 0.10.40 → 0.10.42

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.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.

package/conventions/coder.bun/coder.bun.phase-discipline.convention.yaml

@@ -0,0 +1,111 @@
+schema_version: 1.1.0
+rule_id: coder.bun.phase-discipline
+kind: policy
+status: active
+name: GREEN establishes behavior before REFACTOR optimizes design
+statement: >-
+  During governed coding work, GREEN MUST target the smallest correct implementation that makes the current
+  behavioral acceptance pass while respecting active construction constraints. REFACTOR begins only after
+  behavioral GREEN and uses quality findings as design sensors. Phase ordering never waives strict
+  enforcement: review-ready work MUST pass all active profiles.
+terms:
+- term_id: behavioral_green
+  text: >-
+    the point where the current RED behavioral acceptance passes against the implementation. It proves the
+    requested behavior exists; it is not yet the end of the coding loop.
+- term_id: construction_constraint
+  text: >-
+    a rule that constrains what counts as a legal implementation while behavior is being discovered:
+    traceability and topology, architecture and dependency direction, runtime, design-system and responsive
+    boundaries, plus every other active non-refactor profile such as security.
+- term_id: refactor_sensor
+  text: >-
+    a quality finding whose metric is evidence of a design smell rather than the design objective itself.
+    In the Bun coder profile these are the seven bun_ts_metrics_detector rules: complexity-cyclomatic,
+    complexity-length, complexity-nesting, dead-code-reachability, duplication-intra-layer,
+    quality-comments, and quality-mi.
+- term_id: review_ready
+  text: >-
+    the point after behavioral GREEN and REFACTOR when the required behavior still passes and all active
+    ATDD Bun profiles are green. Only this state is completion.
+content:
+  summary: >-
+    Keep GREEN and REFACTOR as different search problems without changing enforcement. GREEN finds the
+    smallest legal implementation of the required behavior; REFACTOR then uses the seven metrics findings
+    as guided design sensors while preserving that behavior.
+  normative_text: |
+    The `green-*` rule prefix is a traceability family name, not a phase assignment. Those conventions
+    declare implementation identity, proof, runtime, purpose, side and layer; they stay where they are and
+    remain construction constraints during GREEN.
+
+    GREEN starts from one failing behavioral acceptance. Its objective is the smallest correct implementation
+    that makes that acceptance pass while respecting the active system constraints. Reuse existing contracts,
+    components, dependencies and patterns. Add only the boundary or abstraction the current behavior actually
+    needs. Do not redesign adjacent systems, generalize for hypothetical callers, or perform unrelated cleanup
+    while behavior is still being discovered.
+
+    Within the coder profile, the construction-constraint families are the rules emitted by
+    `atdd_topology`, `bun_green_traceability_detector`, `bun_clean_architecture_detector`,
+    `bun_fullstack_detector`, `bun_design_system_detector`, and `bun_responsive_detector`. They constrain the
+    solution during GREEN; they are not debts to knowingly violate and repair later. Other active profiles,
+    especially tester, traceability and security, remain equally binding.
+
+    The refactor-sensor family is `bun_ts_metrics_detector`:
+      * coder.bun.complexity-cyclomatic
+      * coder.bun.complexity-length
+      * coder.bun.complexity-nesting
+      * coder.bun.dead-code-reachability
+      * coder.bun.duplication-intra-layer
+      * coder.bun.quality-comments
+      * coder.bun.quality-mi
+
+    These sensors may run at any time and remain strict. The phase distinction changes the agent's response,
+    not the validator. While the acceptance is still red, do not broaden the implementation merely to optimize
+    a quality metric and do not game a finding. Prefer a naturally simple implementation, but keep the search
+    objective on the missing behavior. Once the acceptance first passes, hold behavior fixed and use each
+    sensor's smell-specific Diagnose / Prefer / Avoid / Verify guidance to improve the design.
+
+    `dead-code-reachability` is the one sensor that can expose a false GREEN: a unit-level acceptance can pass
+    against code that no production root can reach. When the finding applies to the newly implemented behavior,
+    wire it through the real owner before treating the behavior as complete; never manufacture an import edge.
+
+    GREEN is therefore not permission to write deliberately poor code, and REFACTOR is not permission to add
+    behavior. The intended loop is RED -> smallest legal behavioral GREEN -> guided REFACTOR -> full-profile
+    proof. A task is not review-ready until the target behavior still passes and every active strict finding is
+    cleared.
+  fix_hint: |
+    During GREEN:
+      * start from the current failing behavioral acceptance,
+      * derive traceability metadata from the plan and the acceptance rather than inventing it,
+      * reuse the nearest existing compliant pattern, contract and dependency,
+      * implement the smallest path that makes the required behavior pass,
+      * introduce a new boundary only when no existing compliant path can express the behavior,
+      * stop expanding scope once the behavior passes and the construction constraints are satisfied.
+
+    During REFACTOR:
+      * keep the now-green behavior fixed,
+      * address the seven refactor sensors one finding at a time,
+      * follow the finding's smell-specific Diagnose / Prefer / Avoid / Verify guidance,
+      * reject metric gaming and unrelated redesign.
+
+    Before review:
+      * rerun the behavioral proof,
+      * run the applicable ATDD Bun profiles,
+      * correct every strict finding caused by or exposed by the work.
+  exceptions:
+  - >-
+    A narrow structural change may precede behavioral GREEN when the existing design makes the required
+    behavior impossible to implement correctly. Preserve already-proven behavior and change only the verified
+    blocker.
+  - >-
+    Phase ordering never suppresses a validator, weakens a threshold, or permits a security, architecture,
+    runtime, traceability or other active constraint to remain violated in review-ready work.
+  - >-
+    If a refactor sensor is already satisfied by the smallest correct implementation, keep that result; do not
+    force a violation merely to preserve a ceremonial phase boundary.
+metadata:
+  aliases:
+  - BUN-CODER-PHASE-DISCIPLINE-001
+  introduced_in: 0.10.10
+implementation:
+  type: none

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

@@ -16,8 +16,23 @@ content:
   normative_text: CSS custom properties cannot be used in media queries, so breakpoints cannot be tokens. Declaring
     them once and requiring every query to use them keeps layouts switching at the same widths everywhere instead
     of at a new one per component.
-  fix_hint: 'Use `@media (min-width: 768px)`, or add the width to `frontend.breakpoints` if the design system really
-    needs it.'
+  fix_hint: |
+    Canonical path:
+      * use only widths declared in `frontend.breakpoints` for media-query conditions.
+    
+    During GREEN:
+      * reuse an existing breakpoint that expresses the required layout transition,
+      * add one breakpoint only when the current design genuinely requires a distinct transition width,
+      * change only the affected media query or configuration entry.
+    
+    Do not broaden:
+      * do not add speculative breakpoints for future devices,
+      * do not normalize unrelated responsive rules,
+      * do not use an undeclared one-off width as a shortcut.
+    
+    Prove:
+      * the current responsive acceptance passes at the relevant viewports,
+      * every affected media-query width is declared.
   exceptions:
   - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
 metadata:

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

@@ -14,7 +14,23 @@ content:
   summary: No width or min-width wider than the smallest viewport.
   normative_text: An element wider than the screen forces horizontal scrolling on every phone. Wide layouts are
     expressed with `max-width`, percentages, or layouts that wrap.
-  fix_hint: 'Replace `width: 960px` with `width: 100%; max-width: 960px`.'
+  fix_hint: |
+    Canonical path:
+      * make content fluid at small viewports, usually with `width: 100%` plus an appropriate `max-width` rather than an oversized fixed `width` or `min-width`.
+    
+    During GREEN:
+      * fix only the element responsible for the current overflow,
+      * reuse existing layout containers and responsive primitives,
+      * preserve the intended large-screen cap while allowing the element to shrink.
+    
+    Do not broaden:
+      * do not redesign unrelated layout,
+      * do not hide overflow to mask an oversized element,
+      * do not remove useful max-width constraints merely to pass the detector.
+    
+    Prove:
+      * the current responsive acceptance passes at the smallest governed viewport,
+      * the affected declaration no longer forces horizontal overflow.
   exceptions:
   - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
   - '`max-width` is not judged; it is how wide layouts are meant to be bounded.'

package/conventions/coder.bun/coder.bun.responsive-viewport-meta.convention.yaml

@@ -14,7 +14,22 @@ content:
   summary: Every HTML document declares a device-width viewport and allows zoom.
   normative_text: Without a device-width viewport a phone renders the page as a zoomed-out desktop layout, whatever
     the CSS says. Blocking zoom fails users who need to enlarge text, which is also an accessibility failure.
-  fix_hint: '`<meta name="viewport" content="width=device-width, initial-scale=1">`'
+  fix_hint: |
+    Canonical path:
+      * declare `<meta name="viewport" content="width=device-width, initial-scale=1">` in each full HTML document and keep zoom available.
+    
+    During GREEN:
+      * add or correct the single viewport declaration in the document/layout that serves the current behavior,
+      * reuse the existing shared layout when one owns the document head.
+    
+    Do not broaden:
+      * do not duplicate viewport tags across fragments,
+      * do not disable zoom with `user-scalable=no` or restrictive scale limits,
+      * do not restructure unrelated head markup.
+    
+    Prove:
+      * the current browser acceptance passes,
+      * the full document declares device width and permits zoom.
   exceptions:
   - Vendored and generated trees (`node_modules`, `dist`, `build`, `_generated`) are never scanned.
   - HTML fragments that are not full documents (no `<html>`) are out of scope.

package/conventions/coder.bun/coder.bun.runtime-server-is-bun-serve.convention.yaml

@@ -35,19 +35,22 @@ content:
     HTML transformer available only through the Bun server, and it is the natural place to assemble and
     post-process fragments.
   fix_hint: |
-    Replace the framework server with the native one:
-
-      const app = express();                       // ✗ node-compat path
-      app.get("/orders", (req, res) => …);
-      app.listen(3000);
-
-      Bun.serve({                                   // ✓ native
-        port: 3000,
-        routes: { "/orders": (req) => new Response(renderOrders(), htmlHeaders) },
-      });
-
-    Middleware becomes plain function composition around the handler. `strict` — the rule exists to
-    hold the stack decision, so it is not suppressible.
+    Canonical path:
+      * serve HTTP with `Bun.serve` and express middleware behavior as ordinary function composition around handlers.
+    
+    During GREEN:
+      * add only the route, handler, or middleware composition required by the current acceptance,
+      * reuse the existing `Bun.serve` instance and routing pattern,
+      * when replacing a forbidden framework in new work, migrate only the path required to make the behavior correct.
+    
+    Do not broaden:
+      * do not introduce Express, Fastify, Koa, or `node:http` for convenience,
+      * do not rewrite unrelated routes,
+      * do not build a compatibility abstraction over a forbidden server.
+    
+    Prove:
+      * the current behavioral acceptance passes through the real Bun server,
+      * the application server remains `Bun.serve`.
   exceptions:
   - A `createServer(` call that is not an HTTP server (a test double, an unrelated factory) is a known
     imprecision of the name-based match; rename it (atdd-bun has no per-rule scope).

package/conventions/coder.bun/coder.bun.runtime-single-lockfile.convention.yaml

@@ -34,12 +34,22 @@ content:
     diverge — someone runs `npm install` out of habit, the trees fork, and the divergence is discovered
     much later in a failing deploy.
   fix_hint: |
-    Delete the foreign lockfile and let Bun own resolution:
-
-      rm package-lock.json     # or yarn.lock / pnpm-lock.yaml
-      bun install              # regenerates bun.lock from package.json
-
-    Add the foreign names to `.gitignore` so a stray `npm install` cannot reintroduce one. `strict`.
+    Canonical path:
+      * keep Bun's lockfile as the single dependency-resolution source and remove npm, Yarn, or pnpm lockfiles.
+    
+    During GREEN:
+      * if the current change adds a dependency, install it with Bun,
+      * remove only foreign lockfiles and regenerate `bun.lock` when dependency state actually changed,
+      * keep package-manager behavior otherwise untouched.
+    
+    Do not broaden:
+      * do not switch package managers,
+      * do not update unrelated dependencies,
+      * do not keep a second lockfile as a temporary convenience.
+    
+    Prove:
+      * the current behavioral acceptance and install/check path pass,
+      * only Bun's lockfile governs dependency resolution.
   exceptions:
   - A vendored or fixture lockfile inside an excluded tree (`node_modules`, `dist`, `build`,
     `_generated`) is never scanned.