@hegemonart/get-design-done 1.47.0 → 1.49.0

package/reference/debt-categories.md

@@ -0,0 +1,148 @@
+---
+name: debt-categories
+type: reference
+version: 1.0.0
+phase: 48
+tags: [debt, taxonomy, audit, crawler, priority-scoring, retroactive]
+last_updated: 2026-06-03
+---
+
+# Debt Categories
+
+The taxonomy `agents/design-debt-crawler.md` uses to classify and rank design debt
+found across an entire codebase. Each class has a definition, the detection signal
+that surfaces it, and the typical fix shape. The priority model at the end converts
+every finding into one comparable score so the catalog reads top to bottom by impact.
+
+This taxonomy is detection-oriented, not a style guide. The reason behind each rule
+lives in `reference/anti-patterns.md` (the BAN-NN and SLOP-NN catalog) and the domain
+references `reference/color.md`, `reference/typography.md`, and `reference/spatial.md`.
+This file is the catalog of what to look for and how to weigh it.
+
+---
+
+## Debt Classes
+
+### color-literal
+
+**Definition:** A raw color value written directly in source instead of a token
+reference. Includes `#rgb` / `#rrggbb` / `#rrggbbaa` hex, `rgb()` / `rgba()`, and
+`hsl()` / `hsla()` function literals that flow to a rendered surface.
+**Detection signal:** Grep for `#[0-9a-fA-F]{3,8}`, `rgb\(`, `rgba\(`, `hsl\(`,
+`hsla\(` in source files. Exclude token-definition files (the palette source itself)
+and comments. A literal inside a `var(--token: #hex)` definition is the token, not debt.
+**Fix shape:** Replace the literal with the matching semantic token. If no token
+exists for that role, the fix is to define one first.
+
+### untokenized-component
+
+**Definition:** A component file that renders visual surface (color, spacing, type
+size) using inline values or arbitrary utility classes rather than referencing the
+design system's tokens or scale.
+**Detection signal:** A component file (`.tsx` / `.jsx` / `.vue` / `.svelte`) that
+contains color-literal or arbitrary-bracket utility hits (`\[[0-9]+px\]`,
+`\[#[0-9a-f]+\]`) and zero `var(--` references or scale-class references. The ratio
+of literal uses to token uses inside one file is the strength signal.
+**Fix shape:** Route the component's visual values through tokens and the spacing
+or type scale; remove the arbitrary brackets.
+
+### anti-pattern
+
+**Definition:** A confirmed instance of a banned construct (BAN-NN) or an AI-slop
+tell (SLOP-NN) from `reference/anti-patterns.md`.
+**Detection signal:** Run `gdd-detect <path> --json`. Each finding carries its
+`ruleId`, `file`, `line`, and a link back to the matching paragraph. The detector
+covers the statically matchable BAN rules; the two subjective rules it cannot match
+(BAN-04 keyboard-action animation, BAN-10 nested equal radius) are noted as a
+manual-review item, not auto-counted.
+**Fix shape:** Apply the rule's documented rewrite. Hard bans take precedence over
+SLOP tells when both touch the same element.
+
+### contrast
+
+**Definition:** A foreground and background pairing that falls below the WCAG 2.1 AA
+contrast floor (4.5:1 for body text, 3:1 for large text and non-text indicators).
+**Detection signal:** Resolve text-color and background-color pairs that share an
+element or selector, compute the ratio, and flag pairs under the threshold. Pairs
+built from unresolvable runtime values are a manual-review item.
+**Fix shape:** Adjust the token or the role assignment so the pair clears AA. Never
+rely on color alone to carry meaning; pair it with text or an icon.
+
+### density-spacing
+
+**Definition:** Spacing values that sit off the project's modular scale (for example
+the 4 / 8 / 12 / 16 / 24 / 32 series), or inconsistent density between sibling
+components that should share rhythm.
+
+**Detection signal:** Collect every padding, margin, and gap value, then flag values
+that are not on the declared scale and clusters where neighboring components use
+different step counts for the same structural role.
+
+**Fix shape:** Snap off-grid values to the nearest scale step; align sibling density.
+
+### typography-drift
+
+**Definition:** Font sizes, weights, or families that drift from a systematic type
+scale: arbitrary pixel sizes, more than the agreed family count, or weight choices
+that break the heading-to-body hierarchy.
+
+**Detection signal:** Tally the distinct font-size and font-weight values and the
+family count. A long tail of one-off sizes, more than two families, or `font-weight`
+under 400 on small text are the drift markers.
+
+**Fix shape:** Map each one-off value onto the nearest scale step; cap families at two.
+
+### a11y-text
+
+**Definition:** Text-content accessibility debt: missing `alt` on meaningful images,
+icon-only controls without an accessible name, placeholder used as the only label,
+and generic or developer-facing copy in empty and error states.
+
+**Detection signal:** Grep for `<img` without `alt`, interactive elements without
+`aria-label` or visible text, inputs with `placeholder` and no `<label>`, and
+empty-state strings such as "No data" or raw error codes.
+
+**Fix shape:** Add the accessible name or label; rewrite generic copy to be specific
+and actionable. Copy-quality detail lives in `reference/copy-quality.md`.
+
+---
+
+## Priority Scoring Model
+
+Every finding gets one priority score so the catalog ranks by impact, not by the
+order files were walked. Three ordinal factors combine, each on a 1 to 3 scale.
+
+**Visible-delta** (how much a user notices the fix):
+
+| Value | Meaning |
+|-------|---------|
+| 3 | Changes a primary surface a user sees on first load |
+| 2 | Changes a secondary or interior surface |
+| 1 | Invisible at rest; shows only in an edge state or to assistive tech |
+
+**Effort** (how cheap the fix is; cheaper scores higher so quick wins float up):
+
+| Value | Meaning |
+|-------|---------|
+| 3 | Mechanical one-line swap (literal to token) |
+| 2 | Localized edit across a single component |
+| 1 | Needs a new token, scale decision, or cross-file refactor |
+
+**Prevalence** (how many instances share this root cause):
+
+| Value | Meaning |
+|-------|---------|
+| 3 | Ten or more instances of the same finding |
+| 2 | Three to nine instances |
+| 1 | One or two instances |
+
+**Combine** by multiplying the three factors:
+
+```
+priority = visible-delta × effort × prevalence
+```
+
+The product ranges from 1 (low) to 27 (high). Sort the catalog by `priority`
+descending so the highest-impact, lowest-cost, most-widespread debt sits at the top.
+On ties, break by visible-delta first, then prevalence. Record the three factors next
+to the score in each catalog row so the ranking is auditable, not opaque.

package/reference/registry.json

@@ -1100,6 +1100,41 @@
       "type": "domain-index",
       "phase": 45,
       "description": "Phase 45 domain-index: UX-writing + voice - brand-voice, style-vocabulary, anti-patterns."
+    },
+    {
+      "name": "copy-quality",
+      "path": "reference/copy-quality.md",
+      "type": "heuristic",
+      "phase": 48,
+      "description": "Phase 48 copy-quality pillar rubric: microcopy (button/CTA labels, error messages, empty states, ARIA/alt text, loading copy), voice alignment, i18n overflow lens."
+    },
+    {
+      "name": "debt-categories",
+      "path": "reference/debt-categories.md",
+      "type": "taxonomy",
+      "phase": 48,
+      "description": "Phase 48 design-debt taxonomy: debt classes (color-literal, untokenized-component, anti-pattern, contrast, density-spacing, typography-drift, a11y-text) + visible-delta x effort x prevalence priority scoring."
+    },
+    {
+      "name": "brief-quality-rubric",
+      "path": "reference/brief-quality-rubric.md",
+      "type": "output-contract",
+      "phase": 48,
+      "description": "Phase 48 brief-quality rubric: 5 anti-patterns (vague verbs, missing audience, immeasurable success criteria, scope creep, missing anti-goals) the brief-auditor surfaces."
+    },
+    {
+      "name": "visual-tells",
+      "path": "reference/visual-tells.md",
+      "type": "heuristic",
+      "phase": 49,
+      "description": "Phase 49 visual-tells catalog: 8 default-AI-aesthetic categories (default-AI-hero, gradient-spam, isometric-illustration-fallback, centered-everything-syndrome, inter-everything, purple-violet-default, glassmorphism-spam, decorative-motion-without-intent) with diagnostic regex + remediation; backs the gdd-design-quality-check hook."
+    },
+    {
+      "name": "reviewer-confidence-gate",
+      "path": "reference/reviewer-confidence-gate.md",
+      "type": "meta-rules",
+      "phase": 49,
+      "description": "Phase 49 reviewer confidence gate: 4-question Pre-Report Gate + confidence 0.0-1.0 field; HIGH/CRITICAL require >=0.8 + cited proof, <0.5 stays Tentative and never reaches design-fixer."
     }
   ]
 }

package/reference/reviewer-confidence-gate.md

@@ -0,0 +1,108 @@
+---
+name: reviewer-confidence-gate
+type: meta-rules
+version: 1.0.0
+phase: 49
+tags: [review, confidence, audit, verify, gap, routing, anti-slop]
+last_updated: 2026-06-03
+---
+
+# Reviewer Confidence Gate
+
+Audit and verify findings can inflate severity without proof. A grep hit gets reported as a BLOCKER; a single line read out of context becomes a MAJOR. This contract adds a confidence discipline so review agents (`design-auditor`, `design-verifier`, `design-debt-crawler`) earn the severity they assign, and so `design-fixer` only auto-applies fixes that are backed by evidence.
+
+Every emitting agent runs the Pre-Report Gate before writing a finding, stamps each finding with a `confidence` score, and parks weak findings in a `## Tentative` section that the fixer never reads. The routing helper `scripts/lib/confidence-route.cjs` encodes the same rule in code.
+
+## Pre-Report Gate
+
+Before you emit any finding or gap, answer these four questions. If you cannot answer all four with a clear yes, the finding is not ready to ship at its stated severity.
+
+- **a. Can I cite `file:line`?** Point at the exact location. A finding with no concrete location is a hunch, not a defect.
+- **b. Can I state the failure mode in one sentence?** Name what breaks for the user or the build. If the sentence needs an "and" plus a "maybe", the finding is two findings or none.
+- **c. Did I read context beyond the modified file?** Confirm the call site, the token definition, or the parent component. A value that looks wrong in isolation is often correct once you read what feeds it.
+- **d. Is the severity defensible?** A BLOCKER blocks shipping. A MAJOR is a real deviation from intent. If you would not defend the label to the author, lower it.
+
+## The `confidence` field
+
+Every finding carries a `confidence: 0.0-1.0` field. It records how sure you are that the finding is real and correctly classified, not how bad the issue is. Severity and confidence are independent axes: a cosmetic issue can be high confidence, and a suspected BLOCKER can be low confidence.
+
+| Range | Meaning | Where it goes |
+|-------|---------|---------------|
+| `>= 0.8` | Cited `file:line`, one-sentence failure mode, context read. | Reported at full severity; eligible for auto-fix. |
+| `0.5 - 0.8` | Real signal, but evidence is partial or context is incomplete. | Reported, routed to user review, never auto-fixed. |
+| `< 0.5` | A hunch, a guess, or a pattern match you could not confirm. | Moved to `## Tentative`; never reaches `design-fixer`. |
+
+## Routing rule
+
+The gate controls what reaches the fixer. The rule is:
+
+- A HIGH severity finding (BLOCKER or MAJOR) requires `confidence >= 0.8` **and** a `file:line` citation **and** a one-sentence failure mode. Below `0.8`, a HIGH finding is surfaced for user review instead of auto-fix.
+- A finding with `confidence < 0.5` stays in the `## Tentative` section and never reaches `design-fixer`.
+- A finding with `confidence` in the `0.5 - 0.8` band is surfaced in the report but routed to user review, not auto-fix.
+
+`scripts/lib/confidence-route.cjs` exports `route({ severity, confidence, tentative })` and returns `'fix'`, `'user-review'`, or `'drop'`. Agents and the fixer share this single decision so the matrix stays consistent.
+
+### Routing matrix
+
+The full decision table the helper encodes:
+
+| Severity | `tentative` | confidence | Destination |
+|----------|-------------|------------|-------------|
+| any | `true` | any | `drop` (never reaches fixer) |
+| any | `false` | `< 0.5` | `drop` (stays tentative) |
+| BLOCKER or MAJOR | `false` | `0.5 - 0.8` | `user-review` |
+| BLOCKER or MAJOR | `false` | `>= 0.8` | `fix` |
+| MINOR or COSMETIC | `false` | `0.5 - 0.8` | `user-review` |
+| MINOR or COSMETIC | `false` | `>= 0.8` | `fix` |
+
+Read the table as: tentative wins first, then the `0.5` floor, then the severity-specific `0.8` auto-fix gate.
+
+## How to emit a finding
+
+After the Pre-Report Gate passes, write the finding with the `confidence` field on its own line inside the existing locked format. For `design-verifier` gaps this sits alongside the other gap fields:
+
+```text
+### BLOCKER G-01: raw error object rendered on payment failure
+- Phase: 2
+- Description: Checkout.tsx renders the error object directly
+- Expected: a human-readable failure message
+- Actual: users see "[object Object]"
+- Location: src/Checkout.tsx:88
+- Suggested fix: render error.message with a fallback string
+- confidence: 0.85
+```
+
+A finding that scores `< 0.5` is not written in the gap list at all. It goes under a `## Tentative` heading in the same report, in plain prose, so a human can promote it later if context proves it real.
+
+## Paired examples
+
+Each pair shows a raw finding (before the gate) and the same finding after the gate corrects it.
+
+### Example 1: severity inflated, no context read
+
+**Before:** `BLOCKER: hardcoded color #1a73e8 in Button.tsx breaks theming.`
+
+**After:** `MINOR G-04: raw #1a73e8 instead of a semantic token. confidence: 0.9`. Reading context (question c) showed `Button.tsx:42` is the token definition file, so theming is not broken; the issue is a style-coherence nit, not a shipping blocker. High confidence, low severity.
+
+### Example 2: a grep guess that could not be confirmed
+
+**Before:** `MAJOR: missing reduced-motion guard, animations will trigger vestibular issues.`
+
+**After:** moved to `## Tentative` with `confidence: 0.4`. The grep matched `framer-motion` but question a failed: no single `file:line` proves the guard is absent app-wide, and a root `MotionConfig` may cover it. Parked as tentative; the fixer never sees it.
+
+### Example 3: real defect, evidence complete
+
+**Before:** `error states look weak somewhere in the checkout flow.`
+
+**After:** `BLOCKER G-01: Checkout.tsx:88 renders the raw error object, so users see "[object Object]" on a failed payment. confidence: 0.85`. All four questions pass: cited location, one-sentence failure mode, call site read, severity defensible. Auto-fix eligible.
+
+### Example 4: partial evidence, honest mid-band score
+
+**Before:** `MAJOR: empty state copy is generic across the app.`
+
+**After:** `MINOR G-06: Inbox.tsx:30 empty state reads "No data". confidence: 0.65`. One real instance is cited, but question c is only half done: the "across the app" claim was not verified. Scored mid-band, surfaced for user review rather than auto-fixed, and the severity was lowered to match the single confirmed instance.
+
+## Agent integration
+
+- `design-auditor`, `design-verifier`, and `design-debt-crawler` run the Pre-Report Gate, stamp each finding with `confidence`, and route sub-0.5 findings to `## Tentative`.
+- `design-fixer` skips every gap in `## Tentative` and skips BLOCKER or MAJOR gaps whose `confidence < 0.8`, routing those to user review instead of auto-fix.

package/reference/visual-tells.md

@@ -0,0 +1,237 @@
+# Visual Tells Catalog (v1)
+
+The default-AI aesthetic has a fingerprint. When a model generates a front-end
+without a brand brief, it falls back to the same handful of moves it saw most in
+its training set. This catalog names those moves so the cheap regex floor in
+`hooks/gdd-design-quality-check.js` can flag them on every `.tsx` / `.vue` /
+`.svelte` / `.astro` write.
+
+Severity here is WARN (advisory), in the vocabulary of `reference/audit-scoring.md`.
+A WARN is not a FLAG: it does not block the write and it does not fail a gate. It
+is a nudge that asks "did you choose this, or did the model default to it?" Each
+category below maps 1:1 to a rule id in the hook. For the harder bans behind some
+of these tells, see `reference/anti-patterns.md` (BAN-NN and SLOP-NN).
+
+How to read each entry: a short description, three to five concrete instances of
+the tell in the wild, the diagnostic regex the hook runs (where one applies), and
+a remediation pattern you can paste in.
+
+---
+
+## default-AI-hero
+
+Rule id: `generic-cta`
+
+The stock landing-page hero: a centered headline, one line of filler subtext, and
+a button that says "Get Started". The copy carries no subject and no verb specific
+to the product. It reads like every template because it is every template.
+
+Instances:
+
+1. Button label "Get Started" with no object ("Get started with what?").
+2. Headline opener "Welcome to [Product]" instead of a value statement.
+3. "Learn More" as the secondary call to action, pointing nowhere specific.
+4. "Lorem ipsum" body copy shipped past the mockup stage.
+5. The triplet subhead with no verb (see SLOP-11 in `reference/anti-patterns.md`).
+
+Diagnostic regex (hook): `\b(?:Get Started|Welcome to|Lorem ipsum|Learn More)\b`
+(case-insensitive, word-boundaried).
+
+Remediation: write the specific promise and the specific next step. "Start a free
+trial" beats "Get Started". "Ship your first audit in ten minutes" beats "Welcome
+to GDD". Name the noun and the verb. Delete placeholder copy before review.
+
+---
+
+## gradient-spam
+
+Rule id: `gradient-spam`
+
+One tasteful gradient can anchor a page. Three or more on a single screen reads as
+decoration standing in for hierarchy. The model reaches for `bg-gradient-to-r` on
+the hero, again on the cards, again on the footer, because gradients look busy and
+busy looks "designed".
+
+Instances:
+
+1. Hero background, card backgrounds, and a CTA all using a direction gradient.
+2. `bg-gradient-to-br` on every feature tile in a grid.
+3. A gradient on text plus a gradient on its container (double application).
+4. Gradient borders faked with a gradient background and an inset child.
+
+Diagnostic regex (hook): `\bbg-gradient-to-(?:r|br|tr|b|bl|l|tl|t)\b`, flagged at
+a count of three or more occurrences in one file.
+
+Remediation: pick one surface to carry a gradient and make the rest solid. Use
+weight, size, and spacing for hierarchy instead of color washes. If you keep a
+gradient, give it a documented role (one hero, one accent) rather than spraying it.
+For the gradient-text ban specifically, see BAN-02.
+
+---
+
+## isometric-illustration-fallback
+
+Rule id: `isometric-illustration-fallback`
+
+Pastel isometric scenes with floating icons, usually pulled straight from a free
+clip-art set. The undraw.co style is the strongest tell: flat shapes, two-tone
+palette, no brand character. It signals that no real screenshot or photography was
+available, so a stock scene filled the hole.
+
+Instances:
+
+1. `src="/illustrations/undraw_dashboard.svg"` in an empty state.
+2. An `isometric-hero.png` asset behind the headline.
+3. A row of undraw spot illustrations as feature icons.
+4. The same illustration set reused across unrelated products.
+
+Diagnostic regex (hook): `\b(?:undraw|isometric)[\w./-]*` (matches the marker in an
+asset path or `src`).
+
+Remediation: show the actual product. A real screenshot, a short screen capture,
+or a purpose-drawn illustration with brand character all beat stock clip art. See
+SLOP-12 in `reference/anti-patterns.md` for the longer argument.
+
+---
+
+## centered-everything-syndrome
+
+Rule id: `centered-everything-syndrome`
+
+`mx-auto` plus `text-center` on block after block. Centered text is fine for a
+single short hero line. Applied to body copy, feature lists, and multi-line cards
+it destroys the reading edge: the eye loses the left margin it scans against, and
+every block competes for the same axis.
+
+Instances:
+
+1. A hero, a feature grid, and a testimonial section all centered.
+2. Centered multi-line paragraphs longer than two lines.
+3. A centered card with centered heading, centered body, and a centered button.
+4. Centered form labels above left-aligned inputs (axis mismatch).
+
+Diagnostic regex (hook): a quoted class string containing both `mx-auto` and
+`text-center`, in either order.
+
+Remediation: center the hero line only. Left-align body copy and lists so they
+share a reading edge. Reserve centering for short, single-line, high-emphasis text.
+Center the container for width control, but left-align its text content.
+
+---
+
+## inter-everything
+
+Rule id: `inter-everything`
+
+Inter as the default with no documented reason. Inter is a fine typeface, which is
+exactly why it is the safe pick a model makes when no brand font is specified. The
+tell is not Inter itself: it is Inter used alone, with no second font and no token
+that records a choice.
+
+Instances:
+
+1. `font-inter` on the root with no display or brand font anywhere.
+2. `font-family: 'Inter'` in CSS with no second family in the stack file.
+3. Inter paired with no `--font-display` or `--font-body` token.
+4. DM Sans, Space Grotesk, or Plus Jakarta Sans in the same role (see SLOP-05).
+
+Diagnostic regex (hook): `\bfont-inter\b` or `font-family:\s*['"]?Inter`, warned
+only when no sibling custom-font token (a `font-<name>` utility, a `--font-*`
+variable, or a second `font-family`) appears in the same file.
+
+Remediation: choose a typeface you can defend in three sentences against the brand,
+and record it as a token (`--font-display`, `--font-body`). If Inter is the right
+call, pair it with a distinct display face or a deliberate weight system so the
+choice is visible. Keeping the token is what turns a default into a decision.
+
+---
+
+## purple-violet-default
+
+Rule id: `purple-violet-default`
+
+`bg-purple-600` and `bg-violet-600` are the colors a model picks when no palette is
+given. Combined with indigo and cyan they form the exact accent set that ships on a
+large share of generated UIs (SLOP-01). The tell is the raw Tailwind shade used as
+the brand color with no theme token in sight.
+
+Instances:
+
+1. `bg-violet-600` on the primary button with no `bg-primary` token defined.
+2. `bg-purple-500` headers across the app, hardcoded per component.
+3. Purple-to-blue accent pairing on hero plus buttons (SLOP-02).
+4. `text-violet-600` links with no semantic link color.
+
+Diagnostic regex (hook): `\bbg-(?:purple|violet)-(?:500|600|700)\b`, warned only
+when no theme-token class (`bg-primary`, `bg-brand`, `bg-accent`, or a
+`bg-[var(--...)]` / `oklch` / `hsl` arbitrary value) is present in the file.
+
+Remediation: route color through a token (`bg-primary`, `--color-accent`) so the
+brand hue lives in one place. If purple is genuinely the brand, define it as the
+token and reference the token, not the raw shade. Pick one primary accent and apply
+it consistently. See the Color System rubric in `reference/audit-scoring.md`.
+
+---
+
+## glassmorphism-spam
+
+Rule id: `glassmorphism-spam`
+
+Frosted-glass panels stacked everywhere: `backdrop-blur` on cards, on the nav, on
+modals, plus `bg-white/10` fills. One blurred overlay over busy content is a valid
+move. Three or more blur or low-alpha-white treatments in one file is glass used as
+the default surface, which hides the fact that no real layout system exists.
+
+Instances:
+
+1. `backdrop-blur-lg` on every card in a grid.
+2. `bg-white/10` panels layered three deep.
+3. A blurred nav over a blurred hero over a blurred section.
+4. Glass cards on a flat background where there is nothing to blur.
+
+Diagnostic regex (hook): `\bbackdrop-blur(?:-\w+)?\b` or `\bbg-white\/(?:10|20|30)\b`,
+flagged at a count of three or more occurrences in one file.
+
+Remediation: keep blur for cases where it has a job, such as a modal dimming the
+content behind it, a floating command palette, or a sticky header over scrolling
+content. Give other surfaces solid fills and a real elevation system. See SLOP-04
+for the valid-use list.
+
+---
+
+## decorative-motion-without-intent
+
+Rule id: `decorative-motion-without-intent`
+
+`animate-pulse`, `animate-bounce`, and `animate-spin` are loading affordances. The
+tell is using them as ambient decoration: a pulsing hero badge, a bouncing arrow
+that never stops, a spinning accent that encodes no progress. Motion that loops
+forever with no state behind it reads as filler and fights `prefers-reduced-motion`.
+
+Instances:
+
+1. `animate-pulse` on a static "New" badge in the hero.
+2. `animate-bounce` on a scroll-down chevron looping with no end.
+3. `animate-spin` on a decorative ring that is not a spinner.
+4. A pulsing gradient blob behind the headline.
+
+Diagnostic regex (hook, conservative): a quoted class string containing
+`animate-(pulse|bounce|spin)` that does not also contain a loading signal
+(`loading`, `loader`, `spinner`, `skeleton`, `icon`, `i-`, or `sr-only`).
+
+Remediation: tie motion to a state. Use `animate-pulse` on skeletons while data
+loads, `animate-spin` on a real spinner during a request, and drop ambient loops.
+Respect `prefers-reduced-motion`. Enter with `ease-out`, exit shorter than enter,
+and never animate keyboard-driven actions. See the Motion Anti-Patterns section of
+`reference/anti-patterns.md`.
+
+---
+
+## Notes
+
+This is a v1 floor, not a ceiling. The regexes favor precision over recall: they
+aim to fire only on the obvious cases so the WARN stays trustworthy. A clean pass
+here does not mean the design is good. It means the eight loudest default-AI tells
+are absent. Real review still applies the full rubric in
+`reference/audit-scoring.md` and the BAN / SLOP catalog in
+`reference/anti-patterns.md`.

package/scripts/lib/confidence-route.cjs

@@ -0,0 +1,60 @@
+'use strict';
+/**
+ * scripts/lib/confidence-route.cjs — pure routing helper for the reviewer
+ * confidence gate (Phase 49). Decides where a single finding/gap goes based on
+ * its severity, its `confidence` score (0.0-1.0), and whether the reviewer
+ * parked it in the `## Tentative` section.
+ *
+ * Canonical rule (mirrors reference/reviewer-confidence-gate.md):
+ *   - A finding in `## Tentative`            -> 'drop'         (never reaches design-fixer)
+ *   - confidence < 0.5                       -> 'drop'         (low-confidence floor; stays tentative)
+ *   - HIGH/CRITICAL (BLOCKER|MAJOR) needs    -> 'fix' only when confidence >= 0.8,
+ *                                               otherwise 'user-review'
+ *   - confidence in [0.5, 0.8)               -> 'user-review'  (surfaced, not auto-fixed)
+ *   - confidence >= 0.8                       -> 'fix'
+ *
+ * Returns one of: 'fix' | 'user-review' | 'drop'. Dependency-free and side
+ * effect free so the routing matrix is unit-testable in isolation.
+ */
+
+const HIGH_FLOOR = 0.8; // BLOCKER/MAJOR must clear this to auto-fix
+const SURFACE_FLOOR = 0.5; // below this a finding is dropped (stays tentative)
+
+// Severity labels that count as HIGH/CRITICAL for the auto-fix floor.
+const HIGH_SEVERITIES = new Set(['blocker', 'major', 'high', 'critical']);
+
+function isHighSeverity(severity) {
+  if (typeof severity !== 'string') return false;
+  return HIGH_SEVERITIES.has(severity.trim().toLowerCase());
+}
+
+/**
+ * Route a finding/gap.
+ * @param {object} finding
+ * @param {string} finding.severity   - BLOCKER | MAJOR | MINOR | COSMETIC (case-insensitive).
+ * @param {number} finding.confidence - 0.0-1.0 confidence score.
+ * @param {boolean} [finding.tentative] - true when the finding sits in `## Tentative`.
+ * @returns {'fix'|'user-review'|'drop'}
+ */
+function route({ severity, confidence, tentative = false } = {}) {
+  // 1. Tentative findings never reach the fixer, regardless of score.
+  if (tentative === true) return 'drop';
+
+  // 2. A missing/non-numeric confidence is treated as the lowest tier: surface
+  //    for user review rather than silently auto-fixing or dropping.
+  const c = typeof confidence === 'number' && Number.isFinite(confidence) ? confidence : 0;
+
+  // 3. Low-confidence floor: anything under 0.5 is dropped (stays tentative).
+  if (c < SURFACE_FLOOR) return 'drop';
+
+  // 4. HIGH/CRITICAL findings must clear the 0.8 floor to auto-fix; otherwise
+  //    they are routed to the user instead of the fixer.
+  if (isHighSeverity(severity)) {
+    return c >= HIGH_FLOOR ? 'fix' : 'user-review';
+  }
+
+  // 5. Lower-severity findings: 0.5-0.8 surfaces for review, >= 0.8 auto-fixes.
+  return c >= HIGH_FLOOR ? 'fix' : 'user-review';
+}
+
+module.exports = { route, isHighSeverity, HIGH_FLOOR, SURFACE_FLOOR };