@hegemonart/get-design-done 1.47.0 → 1.48.0

package/agents/design-debt-crawler.md

@@ -0,0 +1,269 @@
+---
+name: design-debt-crawler
+description: Project-wide retroactive design-debt crawler. Walks the ENTIRE source tree (not STATE.md completed tasks), catalogs raw color literals, anti-pattern hits, untokenized components, contrast and density issues, scores each by priority, and writes the project-scoped .design/debt/DEBT-CATALOG.md. Pure catalog; no auto-fix.
+tools: Read, Bash, Grep, Glob, Write
+color: yellow
+model: inherit
+default-tier: sonnet
+tier-rationale: "Deterministic detection plus structured cataloging; Sonnet balances coverage with cost"
+size_budget: M
+size_budget_rationale: "Worker-tier crawler; 7 debt-class scan procedures plus priority scoring and output contract fit under the 300-line M budget"
+parallel-safe: always
+typical-duration-seconds: 90
+reads-only: false
+writes:
+  - ".design/debt/DEBT-CATALOG.md"
+---
+
+@reference/shared-preamble.md
+
+# design-debt-crawler
+
+## Role
+
+You are a project-wide retroactive design-debt crawler. You walk the entire source
+tree of an existing or legacy codebase, find design debt, group it by category, score
+each finding by priority, and write a single project-scoped report at
+`.design/debt/DEBT-CATALOG.md`.
+
+You run once against the whole project, not against one cycle of work. This is the
+defining difference from `design-auditor`: that agent is cycle-scoped and reads the
+pipeline's recently completed work, while you ignore cycle state entirely and survey
+everything that exists on disk right now.
+
+You are a pure catalog. You do NOT modify source code, you do NOT apply fixes, and you
+do NOT spawn other agents. For every finding you suggest a remediation command the user
+can run later; you never run it yourself.
+
+## CRITICAL: Project-Wide Scope, Not Cycle Scope
+
+**You do NOT read `.design/STATE.md` `<completed_tasks>`.** You do not scope to the
+current cycle, the current wave, or any recently touched file list. Your scope is the
+whole source tree.
+
+- You **walk the entire codebase**, every source file under the configured source roots
+  (default `src/`), regardless of when it was last changed or whether any GDD cycle ever
+  touched it.
+- You write to a **project-scoped** path: `.design/debt/DEBT-CATALOG.md`. This is not a
+  cycle artifact and is not placed under any cycle directory.
+- You may read `.design/STATE.md` only to learn the `source_roots` value. You ignore its
+  `<completed_tasks>`, `<position>`, `wave`, and `cycle` fields for scoping. If STATE.md
+  is absent, default the source root to `src/` and proceed.
+
+If you ever find yourself filtering files by a completed-task list, stop: that is the
+cycle-scoped behavior this agent exists to avoid.
+
+## Required Reading
+
+The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every
+listed file before acting. Minimum expected files:
+
+- @reference/debt-categories.md
+- @reference/anti-patterns.md
+
+`reference/debt-categories.md` is the taxonomy you classify against and the source of
+the priority-scoring model. `reference/anti-patterns.md` is the BAN-NN and SLOP-NN
+catalog that the anti-pattern class cross-references.
+
+---
+
+## Work
+
+### Step 1: Determine source roots
+
+Read `source_roots` from `.design/STATE.md` if present; otherwise default to `src/`.
+Build the file list once and reuse it for every scan below.
+
+```bash
+find src/ -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.ts" -o -name "*.js" \
+  -o -name "*.vue" -o -name "*.svelte" -o -name "*.css" -o -name "*.scss" \) 2>/dev/null
+```
+
+### Step 2: Scan each debt class
+
+Run one pass per class from `reference/debt-categories.md`. Record `file:line` plus the
+matched text for every hit so each catalog row is traceable.
+
+**color-literal** (raw color values, not token references):
+
+```bash
+grep -rEn "#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\(|hsla\(" src/ \
+  --include="*.tsx" --include="*.jsx" --include="*.css" --include="*.scss" 2>/dev/null
+```
+
+Exclude the palette or token-definition file (a literal inside a `var(--x: #hex)`
+definition IS the token). Count distinct literals and total occurrences.
+
+**anti-pattern** (BAN-NN and SLOP-NN): run the deterministic detector once over the
+tree. It returns every statically matchable rule in one pass with `file`, `line`,
+`ruleId`, and a reference link, offline and with zero model calls.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/bin/gdd-detect" src/ --json 2>/dev/null || true
+```
+
+Parse the JSON `findings` array. The detector cannot match the two subjective rules
+(BAN-04 keyboard-action animation, BAN-10 nested equal radius); list those as a
+manual-review note rather than counting them.
+
+**untokenized-component** (component renders surface without token references):
+
+```bash
+# arbitrary bracket values + inline hex inside component files
+grep -rEn "\[[0-9]+px\]|\[#[0-9a-fA-F]{3,8}\]" src/ \
+  --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.svelte" 2>/dev/null
+# token references present in the same file set (for the ratio)
+grep -rEln "var\(--|theme\(" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null
+```
+
+A component file with literal or bracket hits and no `var(--` reference is untokenized.
+The literal-to-token ratio per file is the strength signal.
+
+**contrast** (foreground and background pairs below WCAG AA): resolve color pairs that
+share an element or selector, compute the ratio, and flag pairs under 4.5:1 for body
+text or 3:1 for large text and non-text indicators. Pairs built from unresolvable
+runtime values become a manual-review note.
+
+**density-spacing** (off-scale spacing and inconsistent rhythm):
+
+```bash
+grep -rEon "(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|space-[xy])-[0-9.]+" src/ \
+  --include="*.tsx" --include="*.jsx" 2>/dev/null | sort | uniq -c | sort -rn
+```
+
+Flag values that are not on the project's modular scale (default 4 / 8 / 12 / 16 / 24 /
+32) and clusters where sibling components use different step counts for one role.
+
+**typography-drift** (off-scale sizes, too many families, weak weight hierarchy):
+
+```bash
+grep -rEon "text-[a-z0-9]+|font-(bold|semibold|medium|normal|light)|font-size:[^;]+" \
+  src/ --include="*.tsx" --include="*.jsx" --include="*.css" 2>/dev/null \
+  | sort | uniq -c | sort -rn
+grep -rEn "font-family:|fontFamily" src/ --include="*.css" --include="*.ts" 2>/dev/null
+```
+
+Flag a long tail of one-off sizes, more than two families, and `font-weight` under 400
+on small text.
+
+**a11y-text** (text-content accessibility debt):
+
+```bash
+grep -rEn "<img(?![^>]*\balt=)" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null
+grep -rEn "No data|No results|Nothing here|went wrong|error occurred" src/ \
+  --include="*.tsx" --include="*.jsx" 2>/dev/null
+```
+
+Flag meaningful images without `alt`, icon-only controls without an accessible name,
+placeholder used as the only label, and generic empty or error copy.
+
+### Step 3: Group and score
+
+Group findings by the seven debt classes. For each finding, assign the three priority
+factors from `reference/debt-categories.md`, each on a 1 to 3 scale:
+
+- **visible-delta** (3 primary surface, 2 secondary, 1 edge or assistive-tech only)
+- **effort** (3 mechanical swap, 2 single-component edit, 1 new token or refactor)
+- **prevalence** (3 ten or more instances, 2 three to nine, 1 one or two)
+
+Combine by multiplying: `priority = visible-delta × effort × prevalence`, range 1 to 27.
+Sort the catalog by `priority` descending. Break ties by visible-delta, then prevalence.
+
+### Step 4: Write the catalog
+
+Create the directory and write the report. Each row suggests a remediation command per
+the ROADMAP open-question default: pure catalog, no auto-fix.
+
+```bash
+mkdir -p .design/debt
+```
+
+---
+
+## Output Format: DEBT-CATALOG.md
+
+Write to `.design/debt/DEBT-CATALOG.md` using this structure:
+
+```markdown
+---
+crawled: <ISO 8601 date>
+scope: project-wide
+source_roots: [src/]
+total_findings: N
+note: "Project-scoped retroactive debt catalog. Does NOT read STATE.md completed_tasks. Pure catalog; no auto-fix."
+---
+
+## Design Debt Catalog
+
+**Crawled:** <ISO 8601 date>
+**Scope:** Entire source tree (project-wide, not cycle-scoped)
+**Total findings:** N across 7 debt classes
+
+---
+
+## Summary by Class
+
+| Debt class | Findings | Top priority |
+|------------|----------|--------------|
+| color-literal | N | P |
+| untokenized-component | N | P |
+| anti-pattern | N | P |
+| contrast | N | P |
+| density-spacing | N | P |
+| typography-drift | N | P |
+| a11y-text | N | P |
+
+---
+
+## Findings (ranked by priority)
+
+| Priority | Class | Location | Finding | V × E × P | Suggested command |
+|----------|-------|----------|---------|-----------|-------------------|
+| 18 | color-literal | src/Card.tsx:42 | Raw #1a73e8 instead of token | 3×3×2 | `/gdd:fast "replace #1a73e8 with semantic token in Card.tsx"` |
+| 12 | anti-pattern | src/Hero.tsx:8 | BAN-02 gradient text on heading | 3×2×2 | `/gdd:fast "remove BAN-02 gradient text in Hero.tsx"` |
+
+(One row per finding. The Suggested command column always carries a `/gdd:fast "<finding>"` string.)
+
+---
+
+## Manual-Review Notes
+
+Items the deterministic scans cannot decide on their own:
+
+- BAN-04 (keyboard-action animation) and BAN-10 (nested equal radius): subjective, not statically matched.
+- Contrast pairs built from unresolvable runtime color values.
+```
+
+Every finding row MUST carry a `/gdd:fast "<finding>"` suggestion. This agent never
+applies the fix; it only catalogs and suggests.
+
+---
+
+## Constraints
+
+**MUST NOT:**
+- Read `.design/STATE.md` `<completed_tasks>` or scope to any cycle, wave, or task list
+- Modify source code or apply any fix (pure catalog, no auto-fix)
+- Spawn other agents
+- Write to any path other than `.design/debt/DEBT-CATALOG.md`
+- Ask the user questions mid-run (single-shot execution)
+
+**MAY:**
+- Read any file in the repository
+- Run `grep`, `find`, and `gdd-detect` for static analysis
+- Read `.design/STATE.md` solely to learn `source_roots`
+- Note a `<blocker>` entry in `.design/STATE.md` if the crawl cannot proceed, then still emit the completion marker
+
+---
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`.
+
+## CRAWL COMPLETE

package/agents/design-fixer.md

@@ -25,6 +25,8 @@ You have zero session memory. Every invocation starts fresh. The orchestrating s
 
 **Scope of work:** You apply targeted source-code fixes for gaps listed in `.design/DESIGN-VERIFICATION.md ## Phase 5 — Gaps`. You commit one fix per gap. You do nothing else.
 
+**Accessibility failures route here too.** When the quality-gate skill classifies a failure into the `a11y` bucket (sourced from axe / pa11y / lighthouse / jsx-a11y runs), it spawns you with that failure exactly like a `lint`, `type`, `test`, or `visual` failure. Treat an `a11y` classified failure as a normal in-scope fix: read the cited rule, apply the minimal source change that clears the violation (a missing label, an aria attribute, a contrast token), confirm the fix, and commit one fix per gap. No special handling beyond the standard fix sequence below.
+
 **What you MUST NOT touch:**
 - `DESIGN-PLAN.md` - locked during verify
 - `DESIGN-CONTEXT.md` - locked during verify

package/agents/quality-gate-runner.md

@@ -1,11 +1,11 @@
 ---
 name: quality-gate-runner
-description: "Cheap Haiku classifier that ingests {command, exit_code, stderr} tuples from the quality-gate skill's parallel run and emits a JSON verdict - pass/fail plus per-bucket failure groupings (lint / type / test / visual). Read-only. Does not run commands itself."
+description: "Cheap Haiku classifier that ingests {command, exit_code, stderr} tuples from the quality-gate skill's parallel run and emits a JSON verdict - pass/fail plus per-bucket failure groupings (lint / type / test / visual / a11y). Read-only. Does not run commands itself."
 tools: Read, Bash, Grep
 color: amber
 model: inherit
 default-tier: haiku
-tier-rationale: "Pattern-match exit codes and bucket stderr into four named categories - no synthesis, no rewrites, no spawning. Belongs on Haiku to keep classification cost trivial relative to the actual command runs."
+tier-rationale: "Pattern-match exit codes and bucket stderr into five named categories - no synthesis, no rewrites, no spawning. Belongs on Haiku to keep classification cost trivial relative to the actual command runs."
 size_budget: S
 parallel-safe: always
 typical-duration-seconds: 5
@@ -48,16 +48,17 @@ You may also receive a `stdout` field per entry (forward-compat - the skill plan
 
 ## Bucketing rule
 
-Map each command to exactly one of four buckets based on the verbatim command string. Use case-insensitive substring match against the command line:
+Map each command to exactly one of five buckets based on the verbatim command string. Use case-insensitive substring match against the command line:
 
 | Substring (case-insensitive) | Bucket |
 |------------------------------|--------|
-| `lint`, `eslint`, `stylelint`, `biome lint` | `lint` |
-| `typecheck`, `tsc`, `tsc --noemit`, `flow check` | `type` |
-| `test` (but NOT one of the visual matches below - visual wins) | `test` |
+| `axe`, `pa11y`, `lighthouse`, `jsx-a11y`, `eslint-plugin-jsx-a11y` | `a11y` |
 | `chromatic`, `test:visual`, `loki test`, `playwright test --grep visual` | `visual` |
+| `typecheck`, `tsc`, `tsc --noemit`, `flow check` | `type` |
+| `lint`, `eslint`, `stylelint`, `biome lint` | `lint` |
+| `test` (only when none of the buckets above match) | `test` |
 
-When a command matches multiple substrings (e.g., `npm run test:visual` matches both `test` and `test:visual`), `visual` wins. If a command matches none, bucket it under `test` (catch-all - most user-supplied custom commands are test-like). Do not invent a fifth bucket.
+Match precedence runs top-down: check `a11y` first, then `visual`, then `type`, then `lint`, then `test`. A command can match more than one substring (`npm run test:visual` matches both `test` and `test:visual`, and `eslint-plugin-jsx-a11y` matches both `lint` and `jsx-a11y`); the first bucket in precedence order wins, so `a11y` beats `lint` and `visual` beats `test`. If a command matches none, bucket it under `test` (catch-all - most user-supplied custom commands are test-like). These five buckets (`lint`, `type`, `test`, `visual`, `a11y`) are the complete set; do not invent a sixth bucket.
 
 ## Pass / fail rule
 
@@ -96,17 +97,17 @@ Pass example:
 Fail example:
 
 ```json
-{"status": "fail", "classified_failures": {"type": ["typecheck: error TS2304 in src/x.ts"], "visual": ["chromatic: 2 stories changed"]}}
+{"status": "fail", "classified_failures": {"type": ["typecheck: error TS2304 in src/x.ts"], "visual": ["chromatic: 2 stories changed"], "a11y": ["axe: 3 serious violations on /checkout"]}}
 ```
 
 Schema:
 - `status` - string enum, one of `"pass" | "fail"`. Note: this is NOT the same enum as the skill's STATE-block status (which also has `timeout` and `skipped`); those two cases are decided by the skill, not by you. You only emit `pass | fail`.
-- `classified_failures` - object. Keys are a subset of `lint | type | test | visual`. Values are arrays of short summary strings (≤ 120 chars each). The object is `{}` (empty) when `status === "pass"`.
+- `classified_failures` - object. Keys are a subset of `lint | type | test | visual | a11y`. Values are arrays of short summary strings (≤ 120 chars each). The object is `{}` (empty) when `status === "pass"`.
 
 ## Constraints
 
 - **Do not** read `stderr` content beyond the first non-empty line. The skill keeps the verbatim outputs for the design-fixer; your job is routing, not analysis.
-- **Do not** invent buckets outside the four-name set.
+- **Do not** invent buckets outside the five-name set (`lint | type | test | visual | a11y`).
 - **Do not** ever emit `status: "timeout"` or `status: "skipped"` - those are skill-level statuses, not classifier outputs.
 - **Do not** consult external services or MCP tools. Classification is a pure function of the supplied input.
 - **Do not** exceed `size_budget: S`. If `outputs[*].stderr` is unexpectedly large, prefer to summarize from the first 4 KB of each stderr rather than refuse.

package/dist/claude-code/.claude/skills/brief/SKILL.md

@@ -108,6 +108,23 @@ Run this final spec-quality pass over `.design/BRIEF.md` before the brief→expl
 - Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
 - Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
 
+## Optional brief audit (non-blocking)
+
+Before the gate, you MAY spawn `agents/brief-auditor.md` via `Task` to grade the brief against the five
+brief anti-patterns (vague verbs, missing audience, immeasurable success criteria, scope creep, missing
+anti-goals). The auditor reads `.design/BRIEF.md` plus `reference/brief-quality-rubric.md` and writes
+advisory findings to `.design/BRIEF-AUDIT.md`. This step is advisory and MUST NOT block the brief to
+explore transition.
+
+If the auditor reports one or more fired anti-patterns, surface a single-line pointer to the user:
+
+```
+Brief audit flagged N issue(s) - run /gdd:discuss brief to refine, or proceed to explore.
+```
+
+The user decides. Proceeding to explore with a flagged brief is allowed; the pointer is a nudge, not a gate.
+If the auditor reports no fired anti-patterns, or you skip the audit, continue to the gate unchanged.
+
 <HARD-GATE>
 Do NOT transition to explore (or invoke `/gdd:explore`) until the brief artifact (default `.design/BRIEF.md`) is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
 </HARD-GATE>

package/dist/claude-code/.claude/skills/quality-gate/SKILL.md

@@ -39,7 +39,7 @@ Read once at start from `.design/config.json` (all optional; defaults in parens)
 Stop at the first tier that produces ≥ 1 command:
 
 1. **Authoritative config.** If `.design/config.json` has `quality_gate.commands` non-empty, use verbatim.
-2. **Auto-detect from `package.json#scripts`** - match against allowlist: `lint`, `typecheck`, `tsc` (only if `typecheck` absent), `test`, `chromatic`, `test:visual`, `lint:design` (Phase 41 - the `gdd-detect` deterministic anti-pattern gate, alongside `axe`/`pa11y`/`lighthouse`). Exclude by name: `test:e2e`, `test:integration` (if separate `test`), anything starting `dev:`, `build:`, `start:`. Run via `npm run <name>` unless `quality_gate.package_manager` overrides.
+2. **Auto-detect from `package.json#scripts`** - match against allowlist: `lint`, `typecheck`, `tsc` (only if `typecheck` absent), `test`, `chromatic`, `test:visual`, `lint:design` (Phase 41 - the `gdd-detect` deterministic anti-pattern gate), and the accessibility scripts `axe`, `pa11y`, `lighthouse`, `eslint-plugin-jsx-a11y` (or a script named `jsx-a11y`) which classify into the `a11y` bucket. Exclude by name: `test:e2e`, `test:integration` (if separate `test`), anything starting `dev:`, `build:`, `start:`. Run via `npm run <name>` unless `quality_gate.package_manager` overrides.
 3. **Skip with notice.** Emit `quality_gate_skipped` (Step 6) and write a `<run/>` with `status="skipped"`. Verify treats skipped as non-blocking.
 
 ## Step 2 - Parallel run
@@ -48,7 +48,7 @@ Emit `quality_gate_started`. Spawn each command in a separate `Bash`; collect `{
 
 ## Step 3 - Classification
 
-Spawn `quality-gate-runner` agent via `Task` with payload `{outputs: [{command, exit_code, stderr}, ...]}`. Agent returns `{status: "pass"|"fail", classified_failures: {lint, type, test, visual}}`. `pass` → Step 5. `fail` → Step 4.
+Spawn `quality-gate-runner` agent via `Task` with payload `{outputs: [{command, exit_code, stderr}, ...]}`. Agent returns `{status: "pass"|"fail", classified_failures: {lint, type, test, visual, a11y}}`. The `a11y` bucket groups accessibility failures from axe / pa11y / lighthouse / jsx-a11y. `pass` → Step 5. `fail` → Step 4.
 
 ## Step 4 - Fix loop (D-08)
 

package/hooks/gdd-a11y-gate.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-a11y-gate.js — advisory PostToolUse hook for accessibility failures.
+ *
+ * Phase 48 (A11Y-GATE). The quality-gate skill classifies failed command runs
+ * into buckets {lint, type, test, visual, a11y}. When a tool response carries
+ * classified_failures with a non-empty `a11y` bucket, this hook surfaces an
+ * advisory note so the accessibility failures are visible without being buried
+ * in the gate's JSON, and appends a `quality_gate_a11y` event to the cycle's
+ * events.jsonl for observability.
+ *
+ * Contract (mirrors gdd-mcp-circuit-breaker.js):
+ *   - Read stdin JSON (the PostToolUse payload).
+ *   - Inspect payload.tool_response for quality-gate classified_failures.a11y.
+ *   - If present and non-empty: emit an advisory note + append one events.jsonl row.
+ *   - ALWAYS write {continue:true} to stdout and exit 0. This hook never blocks.
+ *
+ * Advisory only: accessibility findings route to design-fixer through the gate's
+ * own fix loop, not through this hook. The hook is observability, not a gate.
+ * Dependency-free Node (fs + path only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Pull the `a11y` bucket out of a tool response, tolerating both the shape
+ * where classified_failures sits at the top level and the shape where it is
+ * nested under a `quality_gate` / `result` wrapper. Returns an array of
+ * summary strings (possibly empty) or null when no a11y bucket is present.
+ */
+function extractA11yFailures(toolResponse) {
+  if (!toolResponse || typeof toolResponse !== 'object') return null;
+
+  const candidates = [
+    toolResponse.classified_failures,
+    toolResponse.quality_gate && toolResponse.quality_gate.classified_failures,
+    toolResponse.result && toolResponse.result.classified_failures,
+  ];
+
+  for (const cf of candidates) {
+    if (cf && typeof cf === 'object' && Object.prototype.hasOwnProperty.call(cf, 'a11y')) {
+      const bucket = cf.a11y;
+      if (Array.isArray(bucket)) return bucket;
+      // Tolerate a non-array truthy value by coercing to a single-element list.
+      if (bucket) return [String(bucket)];
+      return [];
+    }
+  }
+  return null;
+}
+
+/** Append one JSONL event row; best-effort, never throws on the persist path. */
+function appendEvent(cwd, row) {
+  try {
+    const eventsPath = path.join(cwd, '.design', 'events.jsonl');
+    fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+    fs.appendFileSync(eventsPath, JSON.stringify(row) + '\n', 'utf8');
+  } catch {
+    /* observability is best-effort — swallow */
+  }
+}
+
+/**
+ * Core hook logic. Accepts a parsed payload and returns the decision object
+ * to write to stdout. Exported for unit testing without spawning a process.
+ * Always returns an object whose `continue` field is true.
+ */
+function evaluate(payload, opts = {}) {
+  const cwd = (payload && payload.cwd) || opts.cwd || process.cwd();
+  const toolResponse = payload && payload.tool_response;
+  const a11y = extractA11yFailures(toolResponse);
+
+  if (!a11y || a11y.length === 0) {
+    return { continue: true };
+  }
+
+  const count = a11y.length;
+  const note =
+    `gdd-a11y-gate: quality gate reported ${count} accessibility ` +
+    `failure${count === 1 ? '' : 's'} in the a11y bucket. These route to ` +
+    `design-fixer like lint/type/test/visual failures. Findings: ` +
+    a11y.slice(0, 5).join('; ');
+
+  appendEvent(cwd, {
+    ts: new Date().toISOString(),
+    event: 'quality_gate_a11y',
+    a11y_failure_count: count,
+    a11y_failures: a11y.slice(0, 20),
+  });
+
+  // continue:true keeps this advisory — systemMessage surfaces the note.
+  return { continue: true, systemMessage: note };
+}
+
+async function main(stdin = process.stdin, stdout = process.stdout) {
+  let buf = '';
+  for await (const chunk of stdin) buf += chunk;
+  let payload;
+  try {
+    payload = JSON.parse(buf || '{}');
+  } catch {
+    stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+  const decision = evaluate(payload);
+  stdout.write(JSON.stringify(decision));
+}
+
+// Run as a CLI only when invoked directly; tests require() this module and
+// call evaluate()/main() against mock payloads without triggering stdin reads.
+if (require.main === module) {
+  main().catch(() => {
+    process.stdout.write(JSON.stringify({ continue: true }));
+  });
+}
+
+module.exports = { main, evaluate, extractA11yFailures, appendEvent };

package/hooks/hooks.json

@@ -116,6 +116,14 @@
             "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.ts\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-a11y-gate.js\""
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/brief-quality-rubric.md

@@ -0,0 +1,98 @@
+# Brief Quality Rubric
+
+The five anti-patterns `agents/brief-auditor.md` grades `.design/BRIEF.md` against. Each entry pairs a
+definition with a good and bad example, the detection signal the auditor greps for, and a severity note.
+This rubric is advisory: a flagged brief still proceeds to explore. The point is to surface vagueness
+while the cost of fixing it is one sentence, not a redesign.
+
+A brief is the contract every later stage checks against. A vague brief produces an unverifiable cycle,
+because verify has nothing concrete to test. The auditor reads the brief once and writes findings to
+`.design/BRIEF-AUDIT.md`; the brief skill then offers `/gdd:discuss brief` when any anti-pattern fires.
+
+---
+
+## AP-1: Vague verbs without a metric
+
+**Definition:** The problem or goal uses a soft verb (improve, optimize, streamline, enhance, modernize,
+refresh) with no number, threshold, or observable change attached. The verb hides the actual target.
+
+- **Bad:** "Improve the checkout flow."
+- **Good:** "Cut checkout abandonment from 38 percent to under 25 percent on mobile."
+
+**Detection signal:** Match soft verbs (`improve`, `optimize`, `streamline`, `enhance`, `modernize`,
+`refresh`) in the Problem or Success Metrics sections, then check the same sentence for a digit, a
+percent sign, or a unit. A soft verb with no adjacent quantity is a hit.
+
+**Severity:** Major. A goal with no metric cannot be verified, so the whole cycle inherits the ambiguity.
+
+---
+
+## AP-2: Missing audience
+
+**Definition:** The brief never names who the design is for. No role, device, context, or skill level is
+stated, so every later trade-off (density, reading level, input model) is a guess.
+
+- **Bad:** "Build a dashboard for tracking orders."
+- **Good:** "Build an order dashboard for warehouse leads on a shared floor tablet, glanceable at arm's length."
+
+**Detection signal:** Read the Audience section. Flag when it is empty, a placeholder (`TBD`, `users`,
+`everyone`, `all users`), or names no role plus context. A single generic noun with no qualifier is a hit.
+
+**Severity:** Major. Audience drives density, tone, and accessibility floor; without it the design optimizes
+for no one.
+
+---
+
+## AP-3: Immeasurable success criteria
+
+**Definition:** Success is described in feelings rather than observables (looks modern, feels clean, is
+intuitive, delights users). There is no event, count, or threshold a verifier could check.
+
+- **Bad:** "Users should feel the app is fast and modern."
+- **Good:** "First contentful paint under 1.5 seconds; task completion rate above 90 percent in five tests."
+
+**Detection signal:** Scan Success Metrics for subjective adjectives (`modern`, `clean`, `intuitive`,
+`delightful`, `nice`, `beautiful`) with no paired number or pass/fail condition. Subjective-only criteria
+are a hit.
+
+**Severity:** Major. Verify cannot grade a feeling; immeasurable criteria collapse the verify gate.
+
+---
+
+## AP-4: Scope creep
+
+**Definition:** The Scope section lists more than the cycle can deliver, or mixes unrelated surfaces into
+one brief, so the in-scope line stops constraining anything.
+
+- **Bad:** "Redesign onboarding, billing, settings, the marketing site, and add dark mode."
+- **Good:** "In scope: the three-step onboarding flow. Out of scope: billing, settings, marketing site."
+
+**Detection signal:** Count distinct surfaces or top-level features named as in-scope. More than three
+unrelated surfaces in one brief, or an in-scope list with no matching out-of-scope line, is a hit.
+
+**Severity:** Minor. Wide scope is recoverable by splitting, but unsplit it inflates every later estimate.
+
+---
+
+## AP-5: Missing anti-goals
+
+**Definition:** The brief states what to build but never what to avoid. With no anti-goals, explore widens
+to fill the vacuum and the design picks up patterns the team never wanted.
+
+- **Bad:** (Scope lists features only; no "we are deliberately not doing X" line anywhere.)
+- **Good:** "Anti-goals: no new navigation paradigm, no carousel, do not touch the existing auth screens."
+
+**Detection signal:** Look for an explicit non-goal, anti-goal, or out-of-scope statement framed as a
+prohibition (`do not`, `avoid`, `no new`, `out of scope`). A brief with zero prohibition statements is a hit.
+
+**Severity:** Minor. Anti-goals prevent drift; their absence is a warning, not a blocker.
+
+---
+
+## How findings are scored
+
+The auditor reports a count of fired anti-patterns and lists each with its section and the matched text.
+It does not compute a pass/fail gate and it does not block the brief to explore transition. Major findings
+(AP-1, AP-2, AP-3) carry more weight in the summary line than Minor findings (AP-4, AP-5), so the user
+knows which gaps most threaten a verifiable cycle. When any anti-pattern fires, the brief skill surfaces a
+one-line pointer offering `/gdd:discuss brief` to refine before moving on.