@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/STATE-TEMPLATE.md

@@ -8,8 +8,8 @@ This is the canonical template for the design pipeline's runtime state file.
 - `.design/` is gitignored (not distributed with the plugin); only this template ships.
 
 **Distinction from `.planning/STATE.md`:**
-- `.planning/STATE.md` is GSD development state — used by the developers building this plugin.
-- `.design/STATE.md` is pipeline runtime state — used by the pipeline when it runs in a user's project.
+- `.planning/STATE.md` is GSD development state - used by the developers building this plugin.
+- `.design/STATE.md` is pipeline runtime state - used by the pipeline when it runs in a user's project.
 - Keep them strictly separate. Cross-references between them are deferred to Phase 6 per CONTEXT.md.
 
 ---
@@ -140,22 +140,22 @@ verify_completed_at: ~
 | Field | Type | Set by | Purpose |
 |-------|------|--------|---------|
 | `pipeline_state_version` | float | fixed at `1.0` | Forward-compat marker for future format changes |
-| `stage` | enum | every stage at entry | Current stage — one of: `brief|explore|plan|design|verify` |
+| `stage` | enum | every stage at entry | Current stage - one of: `brief|explore|plan|design|verify` |
 | `cycle` | string | lifecycle commands | Cycle identifier for Wave B multi-cycle projects (default: empty string) |
 | `wave` | int | every stage | Wave number within current stage |
-| `started_at` | ISO 8601 | scan at creation | Immutable — never updated after creation |
+| `started_at` | ISO 8601 | scan at creation | Immutable - never updated after creation |
 | `last_checkpoint` | ISO 8601 | every stage at exit | Updated on every stage transition and on mid-stage checkpoint |
 
 ### `<position>`
 
-Mirrors frontmatter stage/wave plus progress and status. Duplication is intentional — frontmatter is scannable by tooling; `<position>` is scannable by prose reading.
+Mirrors frontmatter stage/wave plus progress and status. Duplication is intentional - frontmatter is scannable by tooling; `<position>` is scannable by prose reading.
 
-- `task_progress`: `<completed>/<total>` — e.g. `3/7` means 3 of 7 tasks in the current stage complete
+- `task_progress`: `<completed>/<total>` - e.g. `3/7` means 3 of 7 tasks in the current stage complete
 - `status`: one of
-  - `initialized` — scan just created the file, no work done
-  - `in_progress` — stage is actively running
-  - `completed` — stage finished successfully; next stage may begin
-  - `blocked` — stage cannot proceed; see `<blockers>`
+  - `initialized` - scan just created the file, no work done
+  - `in_progress` - stage is actively running
+  - `completed` - stage finished successfully; next stage may begin
+  - `blocked` - stage cannot proceed; see `<blockers>`
 
 ### `<decisions>`
 
@@ -173,25 +173,25 @@ Discover stage populates with observable behaviors. Verify stage updates status.
 
 ### `<prototyping>`
 
-Phase 25 surface (D-01). A checkpoint log — NOT a stage. Tracks sketch and spike outcomes plus cycle-scoped skip suppressions for the prototype gate.
+Phase 25 surface (D-01). A checkpoint log - NOT a stage. Tracks sketch and spike outcomes plus cycle-scoped skip suppressions for the prototype gate.
 
-- `<sketch slug=… cycle=… decision=D-XX status=resolved/>` — written by `sketch-wrap-up` after a sketch resolves into a D-XX decision.
-- `<spike slug=… cycle=… decision=D-XX verdict=yes|no|partial status=resolved/>` — written by `spike-wrap-up` after a spike resolves; `verdict` captures the answer.
-- `<skipped at=… cycle=… reason=…/>` — written by the prototype gate when the user declines to sketch/spike at a firing point. Cycle-scoped suppression (D-02): a `<skipped/>` entry suppresses re-asking for the rest of the named cycle.
+- `<sketch slug=… cycle=… decision=D-XX status=resolved/>` - written by `sketch-wrap-up` after a sketch resolves into a D-XX decision.
+- `<spike slug=… cycle=… decision=D-XX verdict=yes|no|partial status=resolved/>` - written by `spike-wrap-up` after a spike resolves; `verdict` captures the answer.
+- `<skipped at=… cycle=… reason=…/>` - written by the prototype gate when the user declines to sketch/spike at a firing point. Cycle-scoped suppression (D-02): a `<skipped/>` entry suppresses re-asking for the rest of the named cycle.
 
-The block is **optional** — fresh STATE.md files do not carry it. The serializer omits the block entirely when no entries exist; appending the first entry is what materializes the block.
+The block is **optional** - fresh STATE.md files do not carry it. The serializer omits the block entirely when no entries exist; appending the first entry is what materializes the block.
 
 ### `<quality_gate>`
 
-Phase 25 surface (Plan 25-03 / D-06..D-09). Captures the most recent run of the Stage 4.5 quality gate (lint / typecheck / test / visual-regression) between Design and Verify. The block houses a single self-closing `<run/>` element — append-mode is overkill, so each gate completion overwrites the entry.
+Phase 25 surface (Plan 25-03 / D-06..D-09). Captures the most recent run of the Stage 4.5 quality gate (lint / typecheck / test / visual-regression) between Design and Verify. The block houses a single self-closing `<run/>` element - append-mode is overkill, so each gate completion overwrites the entry.
 
-- `started_at` — ISO 8601 at which the parallel command run entered.
-- `completed_at` — ISO 8601 at which the gate produced its terminal status.
-- `status` — `pass | fail | timeout | skipped`. `pass` clears the verify-entry gate; `fail` blocks; `timeout` warns + proceeds (D-07); `skipped` indicates the detection chain resolved zero commands.
-- `iteration` — non-negative integer fix-loop count (D-08). `1` = single clean pass; `N === max_iters` with `status === 'fail'` = bounded exhaustion.
-- `commands_run` — comma-separated names of the commands actually executed in Step 2 (e.g., `lint,typecheck,test`). Empty string when `status === 'skipped'`.
+- `started_at` - ISO 8601 at which the parallel command run entered.
+- `completed_at` - ISO 8601 at which the gate produced its terminal status.
+- `status` - `pass | fail | timeout | skipped`. `pass` clears the verify-entry gate; `fail` blocks; `timeout` warns + proceeds (D-07); `skipped` indicates the detection chain resolved zero commands.
+- `iteration` - non-negative integer fix-loop count (D-08). `1` = single clean pass; `N === max_iters` with `status === 'fail'` = bounded exhaustion.
+- `commands_run` - comma-separated names of the commands actually executed in Step 2 (e.g., `lint,typecheck,test`). Empty string when `status === 'skipped'`.
 
-The block is **optional** — fresh STATE.md files do not carry it. The serializer omits the block entirely when `quality_gate === null`; the SKILL writes the first `<run/>` to materialize it.
+The block is **optional** - fresh STATE.md files do not carry it. The serializer omits the block entirely when `quality_gate === null`; the SKILL writes the first `<run/>` to materialize it.
 
 ### `<connections>`
 
@@ -202,7 +202,7 @@ One line per external connection. Detected at scan entry via MCP availability pr
 
 ### `<blockers>`
 
-Append-only log of active blockers. Format: `[stage] [ISO date]: [description]`. Cleared manually when blocker resolves (do not auto-clear — preserve the record).
+Append-only log of active blockers. Format: `[stage] [ISO date]: [description]`. Cleared manually when blocker resolves (do not auto-clear - preserve the record).
 
 ### `<timestamps>`
 
@@ -217,7 +217,7 @@ Every stage that runs in the pipeline MUST follow this contract when reading and
 **At entry:**
 1. Read `.design/STATE.md`. If the file does not exist and the current stage is `scan`, create it from this template with `started_at` = now and `last_checkpoint` = now; otherwise abort with a clear error ("run scan first").
 2. Parse frontmatter `stage` and `<position>` `status`.
-3. If `stage == current_stage` and `status == in_progress`: RESUME — pick up from `task_progress` offset; do not reset progress.
+3. If `stage == current_stage` and `status == in_progress`: RESUME - pick up from `task_progress` offset; do not reset progress.
 4. If `stage != current_stage`: this is a normal stage transition. Set frontmatter `stage = current_stage`, `<position>` `stage = current_stage`, `<position>` `status = in_progress`, `<position>` `task_progress = 0/<total>`.
 5. Update `<connections>` by probing each MCP tool; write the detected status.
 6. Update `last_checkpoint` to now.
@@ -248,6 +248,6 @@ Every stage that runs in the pipeline MUST follow this contract when reading and
 ## Notes for Phase 2 implementors
 
 - Do not add new top-level XML sections without updating this template.
-- The write contract is non-negotiable — stages that skip the read-at-entry step break resume.
+- The write contract is non-negotiable - stages that skip the read-at-entry step break resume.
 - `<decisions>` and `<must_haves>` identifiers are sequential per-project, not globally unique. A new pipeline run on the same project starts at `D-01` / `M-01`.
-- When in doubt, prefer appending new fields to existing sections over introducing new sections — preserves compatibility with `pipeline_state_version: 1.0`.
+- When in doubt, prefer appending new fields to existing sections over introducing new sections - preserves compatibility with `pipeline_state_version: 1.0`.

package/reference/accessibility.md

@@ -1,10 +1,10 @@
-# Accessibility — Thresholds and Requirements
+# Accessibility - Thresholds and Requirements
 
 These are concrete, measurable standards. WCAG 2.1 AA is the minimum baseline for all design work unless the client explicitly requires AAA or specifies otherwise.
 
 ---
 
-## WCAG 2.1 AA — Required Thresholds
+## WCAG 2.1 AA - Required Thresholds
 
 ### Color Contrast
 
@@ -12,20 +12,20 @@ These are concrete, measurable standards. WCAG 2.1 AA is the minimum baseline fo
 |---|---|---|
 | Normal text (< 18pt / < 14pt bold) | **4.5 : 1** | 7 : 1 |
 | Large text (≥ 18pt or ≥ 14pt bold) | **3 : 1** | 4.5 : 1 |
-| UI components and graphical objects | **3 : 1** | — |
-| Decorative elements | No requirement | — |
+| UI components and graphical objects | **3 : 1** | - |
+| Decorative elements | No requirement | - |
 
 **Calculate contrast**: `(L1 + 0.05) / (L2 + 0.05)` where L1 is the lighter luminance.
 
 Common pitfalls:
-- Placeholder text in inputs: must meet 4.5:1 (often doesn't — gray placeholders fail)
+- Placeholder text in inputs: must meet 4.5:1 (often doesn't - gray placeholders fail)
 - Disabled state text: WCAG exempts disabled elements, but aim for ≥ 3:1 anyway
 - Link color vs body text: must be distinguishable by more than color alone (underline or 3:1 ratio vs background)
 - Focus ring color vs its background: must meet 3:1
 
 Tools: Use browser DevTools > Accessibility tab, or pass hex values through contrast calculation.
 
-**See also:** [`./contrast-advanced.md`](./contrast-advanced.md) — APCA (WCAG 3 draft) for perceptual contrast when WCAG 2.1 4.5:1 misranks thin/large/colored text. Recommended dual-target pattern: enforce WCAG 2.1 AA as a floor + APCA Lc-thresholds (75 / 60 / 45 / 30) for perceptual accuracy.
+**See also:** [`./contrast-advanced.md`](./contrast-advanced.md) - APCA (WCAG 3 draft) for perceptual contrast when WCAG 2.1 4.5:1 misranks thin/large/colored text. Recommended dual-target pattern: enforce WCAG 2.1 AA as a floor + APCA Lc-thresholds (75 / 60 / 45 / 30) for perceptual accuracy.
 
 ### Touch Target Size
 
@@ -34,7 +34,7 @@ Tools: Use browser DevTools > Accessibility tab, or pass hex values through cont
 | iOS (Apple HIG) | **44 × 44 pt** |
 | Android (Material Design) | **48 × 48 dp** |
 | Web (WCAG 2.5.5 AAA) | **44 × 44 px** |
-| Web (WCAG 2.5.8 AA — WCAG 2.2) | **24 × 24 px** (minimum, with spacing) |
+| Web (WCAG 2.5.8 AA - WCAG 2.2) | **24 × 24 px** (minimum, with spacing) |
 
 Recommended target: 44 × 44 px on all platforms. Never smaller for primary actions.
 
@@ -49,7 +49,7 @@ hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
 
 All interactive elements must have a visible focus indicator.
 
-**Required for WCAG 2.4.11 (AA — WCAG 2.2):**
+**Required for WCAG 2.4.11 (AA - WCAG 2.2):**
 - Focus indicator at minimum: **2px solid** outline, encloses the component
 - Contrast between focused and unfocused: **3:1**
 - Focus indicator doesn't overlap component content
@@ -71,13 +71,13 @@ Recommended focus ring: **3px solid**, `2px offset`, brand primary or `#2563eb`.
 
 ### Semantic Structure
 
-- One `<h1>` per page. Headings are sequential: `h1` → `h2` → `h3` — never skip levels.
-- Interactive elements are focusable: use `<button>` for buttons, `<a href>` for links — never `<div onClick>`.
-- Form inputs have associated `<label for="id">` — not just placeholder text.
+- One `<h1>` per page. Headings are sequential: `h1` → `h2` → `h3` - never skip levels.
+- Interactive elements are focusable: use `<button>` for buttons, `<a href>` for links - never `<div onClick>`.
+- Form inputs have associated `<label for="id">` - not just placeholder text.
 - Images have descriptive `alt=""` for meaningful images; `alt=""` for decorative.
 - Icon-only buttons have `aria-label`: `<button aria-label="Close dialog">×</button>`.
 
-**See:** [`./i18n.md`](./i18n.md) §WCAG i18n for SC 3.1.1 (`<html lang>`) and SC 3.1.2 (`<span lang="…">` language-of-parts) patterns — screen readers select voice/pronunciation packs from these attributes; a missing or wrong `lang` value forces the user to hear French announced in an English accent.
+**See:** [`./i18n.md`](./i18n.md) §WCAG i18n for SC 3.1.1 (`<html lang>`) and SC 3.1.2 (`<span lang="…">` language-of-parts) patterns - screen readers select voice/pronunciation packs from these attributes; a missing or wrong `lang` value forces the user to hear French announced in an English accent.
 
 ### Color Must Not Be The Only Differentiator
 
@@ -154,7 +154,7 @@ font-size: 16px;
 
 All animations must respect `prefers-reduced-motion: reduce`. See `reference/motion.md`.
 
-The `prefers-reduced-motion` check is an accessibility requirement (WCAG 2.3.3 AAA; WCAG 2.2 reduces to recommendation — but implement it regardless).
+The `prefers-reduced-motion` check is an accessibility requirement (WCAG 2.3.3 AAA; WCAG 2.2 reduces to recommendation - but implement it regardless).
 
 ---
 

package/reference/adr-format.md

@@ -7,13 +7,13 @@ tags: [adr, decision, project-scoped, architecture, offer-gate]
 last_updated: 2026-05-18
 ---
 
-Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+Source: mattpocock/skills (MIT) - adapted with permission. See `../NOTICE` for the full attribution block.
 
 # ADR Format
 
 An Architecture Decision Record (ADR) is a project-scoped record of a decision that
 outlives the current cycle. ADRs live at `docs/adr/NNNN-<slug>.md` (zero-padded sequence,
-kebab-case slug) and are offered SPARINGLY — only when all three criteria of the offer
+kebab-case slug) and are offered SPARINGLY - only when all three criteria of the offer
 gate hold (D-04). Most decisions stay in `STATE.md` and roll over with the cycle; ADRs
 are the rare exception. See `./context-md-format.md` for the lighter glossary form that
 shares the same project-scoped lifetime.
@@ -31,12 +31,12 @@ the decision in `STATE.md` instead.
   stated reasons. Decisions with no plausible alternative (e.g., "use HTTPS") do not
   qualify.
 
-Worked example — **qualifier:** "Switch from REST to GraphQL for the public API."
+Worked example - **qualifier:** "Switch from REST to GraphQL for the public API."
 Hard-to-reverse (clients integrate against the schema), surprising-without-context (most
 greenfield APIs default to REST), real-tradeoff (tRPC and gRPC were rejected for stated
 reasons). Ship an ADR.
 
-Worked example — **disqualifier:** "Rename the `users` table to `accounts`." Hard-to-reverse,
+Worked example - **disqualifier:** "Rename the `users` table to `accounts`." Hard-to-reverse,
 but the rationale is obvious from the rename and there is no real alternative once the
 domain has settled on the word. Log in `STATE.md`, not an ADR.
 
@@ -63,14 +63,14 @@ supersedes: <optional — ADR number this one replaces, e.g., "0042">
 ## Body structure
 
 The ADR body uses four `##` sections in the following order. Each section is a thin
-paragraph or short bullet list — ADRs are decision records, not design docs.
+paragraph or short bullet list - ADRs are decision records, not design docs.
 
-- `## Context` — what situation made this decision necessary; cite the originating
+- `## Context` - what situation made this decision necessary; cite the originating
   cycle's `BRIEF.md` or `STATE.md` if relevant.
-- `## Decision` — what was chosen, stated as an imperative.
-- `## Alternatives` — what was considered and rejected, with brief rationale per
+- `## Decision` - what was chosen, stated as an imperative.
+- `## Alternatives` - what was considered and rejected, with brief rationale per
   alternative.
-- `## Consequences` — what this enables, what it costs, what it constrains downstream.
+- `## Consequences` - what this enables, what it costs, what it constrains downstream.
 
 ## Status lifecycle
 
@@ -81,16 +81,16 @@ truth; transitions are explicit, never silent.
   does not cite Proposed ADRs.
 - **Accepted.** Decision active; downstream work cites this ADR by number.
 - **Superseded.** Replaced by a later ADR. The later ADR's `supersedes:` field points
-  here, and this ADR's status is flipped to Superseded. NEVER delete a Superseded ADR —
+  here, and this ADR's status is flipped to Superseded. NEVER delete a Superseded ADR -
   the audit trail is the point.
 - **Deprecated.** No longer relevant (e.g., the system the ADR governed was removed).
   Kept for history.
 
 ## Cross-references
 
-- Domain terms used in the ADR body should already appear in `CONTEXT.md` — see
+- Domain terms used in the ADR body should already appear in `CONTEXT.md` - see
   `./context-md-format.md`. If a term is missing, the writer adds it before referencing it.
-- Cycle-scoped decisions (most routine choices) stay in `STATE.md` — see
+- Cycle-scoped decisions (most routine choices) stay in `STATE.md` - see
   `./STATE-TEMPLATE.md`.
-- Skill structural rules (length cap, frontmatter, progressive disclosure) — see
+- Skill structural rules (length cap, frontmatter, progressive disclosure) - see
   `./skill-authoring-contract.md`.

package/reference/ai-native-tool-interface.md

@@ -1,4 +1,4 @@
-# AI-Native Design Tool Interface — Capability Contract
+# AI-Native Design Tool Interface - Capability Contract
 
 This file defines the capability-based contract that AI-native design tools must implement to integrate with the get-design-done pipeline. Two sub-categories are defined: **canvas** and **component-generator**. Future tools implement one sub-category and plug in via the same probe/read/write or probe/generate/adopt surface.
 
@@ -26,8 +26,8 @@ write(proposal) → { confirmed | rejected }
 ```
 
 **Implementations:**
-- `connections/paper-design.md` — MCP-based; 24-tool server; budget: 100 calls/week (free)
-- `connections/pencil-dev.md` — file-based; `.pen` YAML spec files; git-tracked; no MCP
+- `connections/paper-design.md` - MCP-based; 24-tool server; budget: 100 calls/week (free)
+- `connections/pencil-dev.md` - file-based; `.pen` YAML spec files; git-tracked; no MCP
 
 **Pipeline stages:** `explore` (read) + `verify` (screenshot) + `design` (write via writer agent)
 
@@ -53,8 +53,8 @@ adopt(variant: object) → { confirmed | rejected }
 ```
 
 **Implementations:**
-- `connections/21st-dev.md` — Magic MCP; `npx @21st-dev/magic@latest init`; marketplace prior-art gate
-- `connections/magic-patterns.md` — Claude connector (`mcp__magic_patterns*`) + API key fallback; DS-aware generation
+- `connections/21st-dev.md` - Magic MCP; `npx @21st-dev/magic@latest init`; marketplace prior-art gate
+- `connections/magic-patterns.md` - Claude connector (`mcp__magic_patterns*`) + API key fallback; DS-aware generation
 
 **Pipeline stages:** `explore` (prior-art gate for 21st.dev) + `design` (generate + adopt)
 

package/reference/anti-patterns.md

@@ -8,7 +8,7 @@ Use during Discover (baseline audit), Design (prevention), and Verify (complianc
 
 Before shipping any artifact: **"If I told someone 'AI made this,' would they believe me immediately?"**
 
-If yes — redo. The training-set monoculture has specific fingerprints. Learn them all.
+If yes - redo. The training-set monoculture has specific fingerprints. Learn them all.
 
 ---
 
@@ -28,7 +28,7 @@ border-right: 3px solid #6366f1;
 
 **Why**: The border-left accent card is the most recognizable AI default. It signals no design thinking happened.
 
-**Fix**: Use different element structure — colored icon, colored background section, or inline accent element.
+**Fix**: Use different element structure - colored icon, colored background section, or inline accent element.
 
 **Grep**: `border-left:\s*[2-9][0-9]*px|border-right:\s*[2-9][0-9]*px`
 
@@ -89,7 +89,7 @@ background: rgb(0, 0, 0);
 
 **Why**: Pure black in dark mode creates harsh contrast and looks amateur.
 
-**Fix**: oklch(12% 0 0) through oklch(18% 0.005 [hue]) — slightly warm or cool near-black.
+**Fix**: oklch(12% 0 0) through oklch(18% 0.005 [hue]) - slightly warm or cool near-black.
 
 **Grep**: `background.*#000000|background.*rgb\(0,\s*0,\s*0\)`
 
@@ -194,7 +194,7 @@ Glassmorphism as the default card treatment signals no layout thinking.
 
 Using Inter, DM Sans, Space Grotesk, or Plus Jakarta Sans without a documented brand reason.
 
-**Test**: Can you give 3 concrete reasons this font matches the product's brand? If not — choose again.
+**Test**: Can you give 3 concrete reasons this font matches the product's brand? If not - choose again.
 
 ### SLOP-06: Card-in-Card
 
@@ -235,7 +235,7 @@ Pastel-colored isometric illustrations with floating icons. Figma community temp
 ### Color Errors
 
 - Gray on colored backgrounds (fails contrast, not "subtle")
-- Pure gray neutrals — add 0.005–0.015 chroma toward brand hue
+- Pure gray neutrals - add 0.005–0.015 chroma toward brand hue
 - Red + green as the only meaning carrier (colorblind failure)
 - Text over image without scrim or overlay
 - Alpha-heavy transparency everywhere (incomplete palette signal)
@@ -274,7 +274,7 @@ Pastel-colored isometric illustrations with floating icons. Figma community temp
 
 - `ease-in` on entrances (use `ease-out`)
 - Same duration for enter and exit (exit should be 60–70% of enter)
-- Animating `width`/`height` (triggers layout — use `transform` only)
+- Animating `width`/`height` (triggers layout - use `transform` only)
 - No `prefers-reduced-motion` media query
 - Popover origin `transform-origin: center` (should come from trigger element)
 - Button with no `:active` press feedback
@@ -292,11 +292,11 @@ Pastel-colored isometric illustrations with floating icons. Figma community temp
 - No progressive disclosure on long forms (show all fields upfront)
 
 ### Feedback
-- Instant (0ms) state transitions — feels broken
+- Instant (0ms) state transitions - feels broken
 - "Loading..." spinners with no context ("Loading contacts..." is better)
 - Success toast that blocks the next interaction
 - Destructive action with no undo and no confirmation
-- Confirmation dialog for reversible action (annoyance — use undo instead)
+- Confirmation dialog for reversible action (annoyance - use undo instead)
 
 ### Navigation
 - Browser back button breaks app state
@@ -359,7 +359,7 @@ If YES to any → rewrite that element before proceeding.
 
 bdId: BAN-10
 
-Applying the same `border-radius` to a container and an element inside it (when the element is separated by padding) makes the inner element appear to "float" — the radii should be concentric, not equal.
+Applying the same `border-radius` to a container and an element inside it (when the element is separated by padding) makes the inner element appear to "float" - the radii should be concentric, not equal.
 
 **Grep (Tailwind):**
 ```

package/reference/architecture-vocabulary.md

@@ -7,11 +7,11 @@ tags: [architecture, ousterhout, module, interface, depth, seam, adapter, levera
 last_updated: 2026-05-18
 ---
 
-Source: mattpocock/skills (MIT) via Ousterhout, *A Philosophy of Software Design* — adapted with permission. See `../NOTICE` for the full attribution block.
+Source: mattpocock/skills (MIT) via Ousterhout, *A Philosophy of Software Design* - adapted with permission. See `../NOTICE` for the full attribution block.
 
 # Architecture Vocabulary
 
-A shared vocabulary for architectural reasoning across GDD skills. Same words mean the same things across `zoom-out`, `debug`, `analyze-dependencies`, `map`, `quality-gate`, and the planning skills — so agents and humans do not re-litigate "what did you mean by *module*" every conversation. Drawn from John Ousterhout's *A Philosophy of Software Design* via mattpocock's `improve-codebase-architecture/LANGUAGE.md`. GDD design-engineering analogs are surfaced where applicable — a UI component is a module, a design-token API is an interface, a token theme is an adapter.
+A shared vocabulary for architectural reasoning across GDD skills. Same words mean the same things across `zoom-out`, `debug`, `analyze-dependencies`, `map`, `quality-gate`, and the planning skills - so agents and humans do not re-litigate "what did you mean by *module*" every conversation. Drawn from John Ousterhout's *A Philosophy of Software Design* via mattpocock's `improve-codebase-architecture/LANGUAGE.md`. GDD design-engineering analogs are surfaced where applicable - a UI component is a module, a design-token API is an interface, a token theme is an adapter.
 
 This file is the canonical reference; skills cite it instead of re-defining terms inline.
 
@@ -19,13 +19,13 @@ This file is the canonical reference; skills cite it instead of re-defining term
 
 A unit of code that hides implementation behind an interface. The module's value to its caller is everything inside that the caller no longer has to think about.
 
-- A React component is a module — props are the interface, internal state and effects are the implementation.
-- A skill is a module — frontmatter + workflow are the interface, the SKILL.md body is the implementation.
+- A React component is a module - props are the interface, internal state and effects are the implementation.
+- A skill is a module - frontmatter + workflow are the interface, the SKILL.md body is the implementation.
 - See `./design-system-guidance.md` for the design-system-level analog: a component is a module; the token contract is its interface.
 
 ## Interface
 
-What a module exposes to callers — function signatures, props, return types, error contracts, side-effect promises. The interface is what callers depend on; everything else they must NOT depend on. Small, stable interfaces are the goal.
+What a module exposes to callers - function signatures, props, return types, error contracts, side-effect promises. The interface is what callers depend on; everything else they must NOT depend on. Small, stable interfaces are the goal.
 
 - `function fetchUser(id: string): Promise<User>` is the interface. How `fetchUser` calls the database is implementation.
 - A React component's `props` plus its rendered DOM contract is the interface; useState, useEffect, internal helpers are not.
@@ -33,27 +33,27 @@ What a module exposes to callers — function signatures, props, return types, e
 
 ## Implementation
 
-What the module hides — the code that does the work. Callers must not depend on it. Implementation is free to change as long as the interface holds.
+What the module hides - the code that does the work. Callers must not depend on it. Implementation is free to change as long as the interface holds.
 
 - Switching `fetchUser` from REST to GraphQL without changing the call site = implementation change without interface change. Healthy.
 - Renaming a private helper inside a React component does not break callers. Healthy.
-- Exposing a class's "private" field that callers started reading turns implementation into de-facto interface. Unhealthy — fix by either formalizing the field as interface or stopping the leak.
+- Exposing a class's "private" field that callers started reading turns implementation into de-facto interface. Unhealthy - fix by either formalizing the field as interface or stopping the leak.
 
 ## Depth
 
-A module is **deep** when the interface is simple and the implementation hides genuine complexity. A module is **shallow** when the interface is as complex as the implementation — the wrapper adds no leverage and just shuffles the caller's mental load sideways.
+A module is **deep** when the interface is simple and the implementation hides genuine complexity. A module is **shallow** when the interface is as complex as the implementation - the wrapper adds no use and just shuffles the caller's mental load sideways.
 
-- `Array.sort()` is deep — one method name hides ~50 lines of comparison-sort logic plus stable-ordering guarantees.
-- `class Wrapper { getX() { return this.x; } }` is shallow — the wrapper adds no leverage; the caller has to know about `Wrapper` AND `x`.
+- `Array.sort()` is deep - one method name hides ~50 lines of comparison-sort logic plus stable-ordering guarantees.
+- `class Wrapper { getX() { return this.x; } }` is shallow - the wrapper adds no use; the caller has to know about `Wrapper` AND `x`.
 - Asymmetry in the caller's favor is the goal. Shallow modules cost the caller mental complexity without paying it back.
-- See `./component-authoring.md` "Minimal API" — a 1-prop `<Image src=... />` that handles preload, lazy load, srcset, blur placeholder, error fallback is the depth principle applied to component design.
+- See `./component-authoring.md` "Minimal API" - a 1-prop `<Image src=... />` that handles preload, lazy load, srcset, blur placeholder, error fallback is the depth principle applied to component design.
 
 ## Seam
 
-The boundary where two abstractions meet — where one module's interface is consumed by another. Seams are where you can replace one side without touching the other.
+The boundary where two abstractions meet - where one module's interface is consumed by another. Seams are where you can replace one side without touching the other.
 
-- **Hypothetical seam.** Only one implementation exists behind the boundary. Nothing yet validates the abstraction is meaningful — the seam is a possibility statement.
-- **Real seam.** Two or more implementations exist; the boundary has been proved load-bearing by actual substitution. The seam is evidence.
+- **Hypothetical seam.** Only one implementation exists behind the boundary. Nothing yet validates the abstraction is meaningful - the seam is a possibility statement.
+- **Real seam.** Two or more implementations exist; the boundary has been proved essential by actual substitution. The seam is evidence.
 - "One adapter = hypothetical seam; two adapters = real seam." See `## Principles` below.
 - A `fetchUser` function backed only by Postgres is hypothetical; once a test double + a Postgres impl coexist, the seam is real.
 
@@ -61,42 +61,42 @@ The boundary where two abstractions meet — where one module's interface is con
 
 A module that transforms one interface into another to enable substitution behind a seam. Adapters create seams; the count of distinct adapters approximates the seam's realism.
 
-- A Redux-to-Zustand adapter exposes Redux's `store.dispatch` while wrapping a Zustand store underneath — callers keep their Redux API; the implementation moved.
+- A Redux-to-Zustand adapter exposes Redux's `store.dispatch` while wrapping a Zustand store underneath - callers keep their Redux API; the implementation moved.
 - A design-token theme is an adapter: it transforms one token contract (`--color-bg`) into specific concrete values (`oklch(98% 0 0)` in light theme, `oklch(15% 0 0)` in dark).
-- An `acp-client` plus an `asp-client` are two adapters over the same "peer-CLI" seam — the second one proves the seam is meaningful (Phase 27).
+- An `acp-client` plus an `asp-client` are two adapters over the same "peer-CLI" seam - the second one proves the seam is meaningful (Phase 27).
 
-## Leverage
+## Use
 
-The ratio of work-the-system-does to interface-the-caller-touches. High leverage = high depth = the caller buys a lot of work for a little API. Architectural choices that maximize leverage reduce future cost across all callers.
+The ratio of work-the-system-does to interface-the-caller-touches. High use = high depth = the caller buys a lot of work for a little API. Architectural choices that maximize use reduce future cost across all callers.
 
-- `<Image />` with a `src` prop that handles preload, lazy load, srcset generation, blur placeholder, error fallback — high leverage from a 1-prop API. Every caller benefits.
-- A 5-prop `<Button variant size leftIcon rightIcon onClick />` that only renders a styled `<button>` — low leverage; the caller is still doing most of the configuration work.
-- Leverage compounds. A high-leverage primitive used by 20 components multiplies the original investment 20×.
+- `<Image />` with a `src` prop that handles preload, lazy load, srcset generation, blur placeholder, error fallback - high use from a 1-prop API. Every caller benefits.
+- A 5-prop `<Button variant size leftIcon rightIcon onClick />` that only renders a styled `<button>` - low use; the caller is still doing most of the configuration work.
+- Use compounds. A high-impact primitive used by 20 components multiplies the original investment 20×.
 
 ## Locality
 
-Related changes happen in the same place; unrelated changes do not ripple. Spatial cohesion of the change footprint. Locality is what makes a codebase "easy to modify" — you can find the thing and change just the thing.
+Related changes happen in the same place; unrelated changes do not ripple. Spatial cohesion of the change footprint. Locality is what makes a codebase "easy to modify" - you can find the thing and change just the thing.
 
 - Healthy: adding a new chart type touches `chart-types/<new-type>.ts` only.
 - Broken: adding a new chart type touches `chart-types.ts` AND `chart-renderer.ts` AND `chart-config.ts` AND `chart-styles.css` AND `chart-icons.svg`. The system is forcing the author to remember 5 files for a 1-concept change.
-- Test it with the **deletion test** (see `## Principles`) — if removing the feature requires touching the same N files, locality is asymmetric and the abstraction is leaking.
+- Test it with the **deletion test** (see `## Principles`) - if removing the feature requires touching the same N files, locality is asymmetric and the abstraction is leaking.
 
 ## Principles
 
-Three load-bearing rules that operationalize the vocabulary above. Each one is a question you can ask during review.
+Three essential rules that operationalize the vocabulary above. Each one is a question you can ask during review.
 
-- **Deletion test.** Can you delete the implementation and the interface still tells callers what they could do? If yes, the interface is well-defined and the module is properly encapsulated. If no, the interface is leaking implementation — callers are reaching past the abstraction. Apply this when reviewing a new module: imagine deleting the body; can a reader still describe the surface from the signature alone?
-- **Interface is the test surface.** Tests target the interface; implementation churn does not churn tests. If a refactor that preserves behavior breaks tests, the test was implementation-coupled — fix the test, not the refactor. This is also the diagnostic for whether you have a real interface at all: if you cannot test through it, the interface is too narrow or the implementation is leaking.
-- **One adapter = hypothetical seam; two adapters = real seam.** One substitution is a possibility statement; two substitutions are evidence the boundary is meaningful. Do not over-design seams without ≥2 implementations — the second one teaches you what the seam actually needs. This is YAGNI for boundaries: ship the first impl, extract the seam when the second one arrives.
+- **Deletion test.** Can you delete the implementation and the interface still tells callers what they could do? If yes, the interface is well-defined and the module is properly encapsulated. If no, the interface is leaking implementation - callers are reaching past the abstraction. Apply this when reviewing a new module: imagine deleting the body; can a reader still describe the surface from the signature alone?
+- **Interface is the test surface.** Tests target the interface; implementation churn does not churn tests. If a refactor that preserves behavior breaks tests, the test was implementation-coupled - fix the test, not the refactor. This is also the diagnostic for whether you have a real interface at all: if you cannot test through it, the interface is too narrow or the implementation is leaking.
+- **One adapter = hypothetical seam; two adapters = real seam.** One substitution is a possibility statement; two substitutions are evidence the boundary is meaningful. Do not over-design seams without ≥2 implementations - the second one teaches you what the seam actually needs. This is YAGNI for boundaries: ship the first impl, extract the seam when the second one arrives.
 
 ## How this applies to skill authoring
 
-Skills are modules. The frontmatter (`name`, `description`, `tags`) plus the workflow signature is the interface; the SKILL.md body is the implementation. A deep skill has a small, predictable interface (clear when to invoke, clear output shape) hiding genuine workflow value. A shallow skill is one whose body adds little beyond what the frontmatter already implies — those skills should be either deepened or deleted. The skill-authoring contract's 100-line cap is the depth principle applied to skills: if the implementation cannot fit in 100 lines, either the workflow is too broad (split it) or supporting domain content should move to `reference/*.md` (extract-then-link, D-10). See `./skill-authoring-contract.md` for the full spec.
+Skills are modules. The frontmatter (`name`, `description`, `tags`) plus the workflow signature is the interface; the SKILL.md body is the implementation. A deep skill has a small, predictable interface (clear when to invoke, clear output shape) hiding genuine workflow value. A shallow skill is one whose body adds little beyond what the frontmatter already implies - those skills should be either deepened or deleted. The skill-authoring contract's 100-line cap is the depth principle applied to skills: if the implementation cannot fit in 100 lines, either the workflow is too broad (split it) or supporting domain content should move to `reference/*.md` (extract-then-link, D-10). See `./skill-authoring-contract.md` for the full spec.
 
 ## Cross-references
 
-- Design-system-level analog — component-as-module, design-token-as-interface: see `./design-system-guidance.md`.
-- Component-library-level analog — the 6-principle quality standard (Minimal API, Composability, ...): see `./component-authoring.md`.
-- Skill-authoring application — extract-then-link, 100-line cap, refs-one-level-deep: see `./skill-authoring-contract.md`.
+- Design-system-level analog - component-as-module, design-token-as-interface: see `./design-system-guidance.md`.
+- Component-library-level analog - the 6-principle quality standard (Minimal API, Composability, ...): see `./component-authoring.md`.
+- Skill-authoring application - extract-then-link, 100-line cap, refs-one-level-deep: see `./skill-authoring-contract.md`.
 - `CONTEXT.md` glossary format (project-scoped ubiquitous language alongside this vocabulary): see `./context-md-format.md`.
 - ADR format (heavier project-scoped decisions about architectural seams): see `./adr-format.md`.

package/reference/audit-scoring.md

@@ -8,7 +8,7 @@ Use during Discover (establishing baseline) and Verify (measuring improvement).
 
 | Level | Code | Impact | Action |
 |---|---|---|---|
-| Blocker | **P0** | Breaks functionality or violates a hard requirement | Fix before shipping — no exceptions |
+| Blocker | **P0** | Breaks functionality or violates a hard requirement | Fix before shipping - no exceptions |
 | Major | **P1** | Significantly degrades UX or fails accessibility standard | Fix in this design pass |
 | Minor | **P2** | Noticeable issue but doesn't break flows | Fix if time allows |
 | Cosmetic | **P3** | Polish item only, subjective quality issue | Deferred to polish pass |
@@ -24,10 +24,10 @@ Score each category 0–10. Overall score = weighted average.
 | Score | Criteria |
 |---|---|
 | 10 | All WCAG 2.1 AA criteria pass. Keyboard nav works end-to-end. Focus rings visible. No color-only meaning. |
-| 8–9 | Minor issues — 1–2 non-critical violations, no contrast failures on primary text |
-| 5–7 | Several violations — contrast issues on secondary text, some missing labels |
-| 3–4 | Multiple failures — some interactive elements inaccessible, missing alt text |
-| 0–2 | Critical failures — primary text fails contrast, keyboard nav broken, missing form labels |
+| 8–9 | Minor issues - 1–2 non-critical violations, no contrast failures on primary text |
+| 5–7 | Several violations - contrast issues on secondary text, some missing labels |
+| 3–4 | Multiple failures - some interactive elements inaccessible, missing alt text |
+| 0–2 | Critical failures - primary text fails contrast, keyboard nav broken, missing form labels |
 
 Auto-checkable:
 - Body text contrast ≥ 4.5:1
@@ -73,7 +73,7 @@ grep -rEn "(padding|margin|gap):\s*(8|12|16)px" src/ --include="*.css" 2>/dev/nu
 grep -rEn "(margin-top|margin-bottom|gap):\s*(32|40|48|64)px" src/ --include="*.css" 2>/dev/null | head -5
 ```
 
-These patterns supplement the qualitative rubric above — they cannot replace
+These patterns supplement the qualitative rubric above - they cannot replace
 visual inspection but reduce false positives during automated audit passes.
 
 ### 3. Typography (Weight: 15%)
@@ -162,11 +162,11 @@ Score = (Accessibility × 0.25)
 
 | Grade | Score | Meaning |
 |---|---|---|
-| A | 90–100 | Excellent — production ready |
-| B | 75–89 | Good — minor polish needed |
-| C | 60–74 | Acceptable — notable issues to address |
-| D | 45–59 | Poor — significant redesign needed |
-| F | 0–44 | Failing — fundamental problems |
+| A | 90–100 | Excellent - production ready |
+| B | 75–89 | Good - minor polish needed |
+| C | 60–74 | Acceptable - notable issues to address |
+| D | 45–59 | Poor - significant redesign needed |
+| F | 0–44 | Failing - fundamental problems |
 
 ---
 
@@ -226,7 +226,7 @@ Check for (see `reference/checklists.md` Micro-Polish Check gate):
 - Font smoothing at `:root` only
 - Dynamic numbers: `font-variant-numeric: tabular-nums`
 - Nested elements: concentric radius (`innerRadius = outerRadius − padding`)
-- Images: `outline: 1px solid rgba(0,0,0,0.08)` — no tinted outlines
+- Images: `outline: 1px solid rgba(0,0,0,0.08)` - no tinted outlines
 - Interactive elements <40px: `::after` hit-area extension to 40×40
 - Press feedback: `scale(0.96)` exactly
 - `AnimatePresence` on persistent UI: `initial={false}`
@@ -239,7 +239,7 @@ Check for (see `reference/checklists.md` Micro-Polish Check gate):
 
 ## Lens-Tags (Orthogonal)
 
-Tags auditors attach to findings under existing pillars to record cross-cutting dimensions without changing the pillar structure or weights. Same orthogonal pattern as Phase 19.6 `emotion_levels` and `authoring_principles`. Adding a lens-tag does NOT change pillar weights, scoring math, or audit output format — it is a label on an existing finding.
+Tags auditors attach to findings under existing pillars to record cross-cutting dimensions without changing the pillar structure or weights. Same orthogonal pattern as Phase 19.6 `emotion_levels` and `authoring_principles`. Adding a lens-tag does NOT change pillar weights, scoring math, or audit output format - it is a label on an existing finding.
 
 ### `composition_alignment`