@hegemonart/get-design-done 1.27.7 → 1.28.5

package/reference/shared-preamble.md

@@ -1,11 +1,29 @@
+---
+name: shared-preamble
+type: preamble
+version: 2.0.0
+phase: 28.5
+tags: [shared, preamble, principles, design-quality, agent-import, cache-prefix, extracted]
+last_updated: 2026-05-18
+---
+
 # GSD Agent Shared Preamble
 
-> **This file is imported via `@reference/shared-preamble.md` as the first line of every agent body in `agents/*.md`. Its placement is load-bearing for Anthropic's 5-minute prompt cache (see `reference/model-tiers.md` and Phase 10.1 decision D-08 Layer A): because every agent opens with the identical preamble prefix, the second and subsequent agent spawns in a session pay `cached_input_per_1m` rates rather than full `input_per_1m` rates for these bytes. Do not inline this content into agent bodies — always import.**
+> **This file is imported via `@reference/shared-preamble.md` as the first line of every agent body in `agents/*.md`. Its placement is load-bearing for Anthropic's 5-minute prompt cache (see `./model-tiers.md` and Phase 10.1 decision D-08 Layer A): because every agent opens with the identical preamble prefix, the second and subsequent agent spawns in a session pay `cached_input_per_1m` rates rather than full `input_per_1m` rates for these bytes. Do not inline this content into agent bodies — always import.**
+>
+> **As of Phase 14.5 this file is an aggregator.** The framework-invariant subsections (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget awareness) live in `./meta-rules.md` (tier L0) so the L2 heuristics/anti-patterns/checklists churn never invalidates the L0 prefix.
 >
-> **As of Phase 14.5 this file is an aggregator.** The framework-invariant subsections (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget awareness) live in `reference/meta-rules.md` (tier L0) so the L2 heuristics/anti-patterns/checklists churn never invalidates the L0 prefix.
+> **As of Phase 28.5 this file also serves the design-family skills.** Sections below the agent-preamble block (## Design Quality Pillars, ## Token-First Reasoning, ## Output Contract Reminders, ## Connection Handshake Summary) are the canonical home for principle-recitation that previously inlined across `skills/audit`, `skills/style`, `skills/darkmode`, `skills/compare`, `skills/figma-write`, `skills/connections`, `skills/benchmark`. Skills cross-link here instead of restating these lists.
 
 @reference/meta-rules.md
 
+## When to use this file
+
+Two distinct consumers, one canonical home:
+
+1. **Agents** (`agents/*.md`) import this file via `@reference/shared-preamble.md` to inherit the GSD framework identity + L0 invariants (cache-stable prefix). Agents do not "read" the design-family sections below; those are passive content the cache covers for free.
+2. **Skills** (`skills/<name>/SKILL.md`) cross-link to specific sections (`./shared-preamble.md#design-quality-pillars`, etc.) instead of restating recurring principle lists inline. This is the D-10 extract-then-link discipline from Phase 28.5: principle text lives in one place; skills point at it.
+
 ## Framework Identity
 
 You are a GSD agent operating under the `get-design-done` plugin contract (see `agents/README.md` for the full authoring contract). You are spawned by a pipeline stage (or by another agent) via the Claude Code `Task` tool with a fully self-contained prompt. You have **zero session memory** — everything you need is in the prompt string and the files listed inside its `<required_reading>` block.
@@ -30,12 +48,66 @@ The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical p
 
 The framework is anchored to three design philosophy references that agents may read during brief, audit, and verify stages:
 
-- `reference/first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
-- `reference/emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
-- `reference/component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
+- `./first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
+- `./emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
+- `./component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
 
 These references encode *why* the heuristics and anti-patterns exist — not rules to follow, but constraints derived from human biology and cognition. Agents that read these files apply them as lenses, not checklists.
 
 ---
 
-*Imported by: every file under `agents/*.md` (except `agents/README.md`). Maintained as part of Phase 10.1 (OPT-07) and Phase 14.5 (L0/L2 split). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*
+## Design Quality Pillars
+
+Seven pillars score every design audit (see `./audit-scoring.md` for the weighted-rubric detail; this section is the one-paragraph summary that the design-family skills cross-link). Used by `skills/audit`, `skills/style`, `skills/compare`.
+
+1. **Accessibility** — WCAG 2.1 AA threshold compliance; keyboard navigation; non-color signalling. See also `./contrast-advanced.md` (APCA / WCAG 3 perceptual layer).
+2. **Visual hierarchy** — F/Z scanning paths; primary action prominence; section pacing. See `./visual-hierarchy-layout.md`.
+3. **Typography** — type scale ratio (1.125 → 1.5), font-pair count cap (≤2), reading rhythm (`./typography.md`).
+4. **Color** — palette source-of-truth, contrast pair density, OKLCH discipline, semantic-token coverage (`./palette-catalog.md`, `./color-theory.md`).
+5. **Spacing & rhythm** — 4 px or 8 px modular scale, vertical-rhythm consistency (`./composition.md`, `./proportion-systems.md`).
+6. **Component coherence** — minimal API surface, animation as state, edge honesty (`./component-authoring.md`).
+7. **Anti-patterns** — BAN-*, SLOP-* tags from `./anti-patterns.md`; emotional design conflict patterns from `./emotional-design.md`.
+
+Score range per pillar: 0–10. Audit-overall = weighted average per `./audit-scoring.md` weights.
+
+## Token-First Reasoning
+
+Design tokens are the discipline that prevents the 60+ raw-hex `#5C5C5C` audit-failure pattern. The rule:
+
+> **Every reachable color, spacing, type-scale value must be a token reference, not a raw literal.**
+
+Three audit signals:
+
+- **Raw-hex ratio** — `grep -rEo "#[0-9a-fA-F]{6}" src/` divided by total color uses. Healthy < 5 %.
+- **Token coverage** — every semantic role (primary, surface, on-surface, etc.) has a defined token. Cross-check with `./palette-catalog.md` for naming convention.
+- **Light/dark parity** — every light-mode color token has a dark-mode override (see `skills/darkmode` audit for the contrast-pair check, and `./color-theory.md` §OKLCH for the modern hue-rotation contract).
+
+Used by: `skills/style`, `skills/darkmode`, `skills/figma-write`, `skills/audit`, `skills/compare`.
+
+## Output Contract Reminders
+
+Every design-family skill writes ONE artifact (D-06 / utility-skill discipline). Recurring constraints (cited by `skills/audit`, `skills/compare`, `skills/darkmode`, `skills/figma-write`, `skills/style`):
+
+- **MUST NOT write** to pipeline-reserved paths: `DESIGN.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `.design/STATE.md` (unless the skill IS a pipeline stage — design-family skills are NOT).
+- **MUST write** the declared artifact name with a non-conflicting prefix (`DESIGN-STYLE-*`, `DARKMODE-AUDIT.md`, `COMPARE-REPORT.md`, etc.).
+- **MUST emit** a completion marker line (e.g., `## STYLE COMPLETE`, `## DARKMODE AUDIT COMPLETE`, `## COMPARE COMPLETE`) so the orchestrator can detect skill exit.
+- **MUST NOT invoke** the pipeline router (these are leaf skills, not pipeline stages).
+- **MUST NOT mutate** source files (audit-only — fixes belong in the design pipeline's color/typography/etc. task types).
+
+Reference paths used by completion-marker probes: see each skill's `## Completion` section for the literal artifact path.
+
+## Connection Handshake Summary
+
+The 12 external integrations (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`) share a probe pattern. The single-source spec lives in `connections/connections.md` (capability matrix + probe-pattern); per-connection setup lives in `connections/<name>.md`. The `skills/connections` skill orchestrates probes; the AI-native interface contract is `./ai-native-tool-interface.md`.
+
+Probe pattern (used by `skills/darkmode`, `skills/compare`, `skills/figma-write`, `skills/connections`, `skills/benchmark`):
+
+1. **ToolSearch first** — `ToolSearch({ query: "<server-name>", max_results: 5 })`. Empty result → `not_configured`. Non-empty → step 2.
+2. **Live tool call** — invoke a metadata endpoint (e.g., `preview_list`, `get_metadata`). Success → `available`. Error → `unavailable`.
+3. **Write to STATE.md `<connections>`** — three-value schema (`available | unavailable | not_configured`). Never add new values.
+
+For full per-connection probe scripts (figma, refero, preview, etc.) see the individual `connections/<name>.md` files. For the onboarding wizard flow, see `./connections-onboarding.md` (Phase 28.5 extract).
+
+---
+
+*Imported by: every file under `agents/*.md` (except `agents/README.md`). Cross-linked by: design-family skills under `skills/{audit,style,darkmode,compare,figma-write,connections,benchmark}/SKILL.md`. Maintained as part of Phase 10.1 (OPT-07), Phase 14.5 (L0/L2 split), and Phase 28.5 (Bucket 2 design-family rework — D-10). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*

package/reference/skill-authoring-contract.md

@@ -0,0 +1,128 @@
+---
+name: skill-authoring-contract
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [skill, authoring, contract, length-cap, description, frontmatter, progressive-disclosure]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Skill Authoring Contract
+
+This file codifies the structural discipline that every `skills/<name>/SKILL.md` in this repo
+must obey. It exists because a 2026-05-02 audit found skill lengths ranging from 23 to 731
+lines, descriptions oscillating between under-spec and over-cap, and no shared rule for when
+to extract domain content out of a SKILL.md and into a centralized reference. The contract
+pulls every skill into a predictable band so agent context stays small and first-token latency
+stays low. Validator: `node scripts/validate-skill-length.cjs --quiet --json`. See
+`./context-md-format.md` and `./adr-format.md` for the project-scoped artifact contracts that
+ship in the same phase.
+
+## Length cap
+
+Two-tier threshold, enforced by the validator (D-01):
+
+- **Warn at `≥100` lines.** Validator emits a warning. CI does NOT fail. Treat as a forcing
+  function: a 110-line skill is fine; a 180-line skill needs a hard look at what can be
+  extracted.
+- **Block at `≥250` lines.** Validator emits an error. CI FAILS. No exceptions —
+  multi-stage orchestrator skills push extraction harder, they do not waive the cap.
+
+When a skill exceeds the cap, use the extract-then-link discipline (D-10) — NEVER delete
+content. Move it. Steps:
+
+1. Identify load-bearing workflow + decision-tree content. Keep this in `SKILL.md`.
+2. Identify domain content — heuristics, framework matrices, glossaries, extended examples.
+   Extract to an existing `reference/<topic>.md` if the topic matches; create a new
+   `reference/<topic>.md` if it does not.
+3. Replace the extracted content with a single-sentence summary + cross-link.
+
+Concrete callouts at the time of writing: `skills/scan/SKILL.md` (731 lines) is the
+worst-offender and is scheduled for Bucket 1 rework in plan `28.5-04`. `skills/help/SKILL.md`
+(86 lines) is an in-band example of a well-scoped utility shortcut.
+
+## Description format
+
+Two rules:
+
+- **Length cap is STRICT.** `description ≤ 1024 chars` — no flag, no override. Under 20 chars
+  is also blocked as under-specification.
+- **Recommended form is LAX by default.** `<what>. Use when <triggers>.` — third person,
+  first sentence what the skill does, second sentence the trigger conditions. Validator
+  enforces the form regex only under `--strict-description` or `STRICT_DESCRIPTION=1`. Default
+  is length-only.
+
+Why lax-by-default (D-02): `obra/superpowers/skills/writing-skills/SKILL.md` documents a
+shortcut-effect where an agent reads the description and skips the body — the more
+load-bearing the description summary, the more often this happens. Phase 33 ships an A/B
+study at `.design/research/description-format-ab.md`; until then the regex stays advisory.
+
+Examples (both 20–1024 chars, both pass the length check):
+
+```text
+# Strict-mode-compliant
+Renders an OKLCH gamut comparison chart. Use when the user asks to see the visible difference between a target gamut and sRGB.
+
+# Lax-mode-only acceptable
+Compares OKLCH gamut coverage against sRGB and prints a visual diff chart.
+```
+
+## Frontmatter
+
+Required fields (validator blocks if absent):
+
+- `name` — kebab-case skill identifier; matches `^[a-z0-9][a-z0-9-._]*$`.
+- `description` — 20–1024 chars; see `## Description format` above.
+
+Optional fields (recognized by the Claude Code agent loader):
+
+- `argument-hint` — usage hint shown in the slash-command picker.
+- `tools` — comma-separated allowed tool list (e.g. `Read, Grep`).
+- `disable-model-invocation: true|false` — when `true`, the skill fires ONLY on explicit
+  user invocation and the router will not auto-trigger it. Allowed ONLY on the D-09
+  whitelist (pure shortcuts like `help`, `stats`, `note`, `health`, `zoom-out`). The
+  validator blocks if a non-whitelisted skill sets this field to `true`.
+- `user-invocable: true|false` — whether the slash-command picker exposes the skill.
+
+Concrete example:
+
+```yaml
+---
+name: help
+description: "Lists all available get-design-done commands with one-line descriptions. Use when the user asks for help, a command list, or wants to know what is available."
+tools: Read
+disable-model-invocation: true
+---
+```
+
+## Progressive disclosure
+
+References-one-level-deep is the rule (D-06):
+
+- **One level deep.** `SKILL.md` may cross-link into `reference/<topic>.md`. A reference may
+  cross-link into another reference. `SKILL.md` does NOT instruct the agent to follow a
+  reference's references — load the first level only.
+- **Centralized refs.** `reference/typography.md`, `reference/palette-catalog.md`,
+  `reference/audit-scoring.md` and friends are consumed by 15+ skills each. NEVER bundle
+  them per-skill. Per-skill folders are allowed ONLY for content that is truly
+  single-skill-private (rare; typically a fixture or schema only the owning skill reads).
+- **When to add `scripts/`.** Per mattpocock's three criteria, add a script only when the
+  step is deterministic, repeated across runs, and the failure mode needs explicit error
+  handling. Anything ad-hoc or once-off stays inline as agent prose.
+
+Concrete example: a skill that lists 10 framework matrices inline (~150 lines) extracts the
+matrices to `reference/<framework>-matrices.md` and replaces them with a one-sentence
+summary + cross-link. SKILL.md drops to ~80 lines, the matrices stay discoverable, no
+institutional knowledge is lost.
+
+## Validator usage
+
+```text
+node scripts/validate-skill-length.cjs --quiet --json
+```
+
+Exit codes: `0` clean, `1` warnings only, `2` blockers present. Flags: `--quiet` suppresses
+per-skill output, `--strict-description` adds the form regex check, `--json` emits
+machine-readable output. Env: `STRICT_DESCRIPTION=1` and `SKILLS_DIR=<path>` are honored.

package/reference/start-procedure.md

@@ -0,0 +1,115 @@
+---
+name: start-procedure
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [start, first-run, proof-path, scan, writer-agent, handoff]
+last_updated: 2026-05-18
+---
+
+# Start Skill — Full Procedure
+
+Extracted from `skills/start/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete
+content). The skill keeps its arguments table, step headings, and non-goals; the per-step
+operational detail (interview JSON shape, scan invocation, writer spawn payload, handoff
+template) lives here so the SKILL stays under the 100-line cap.
+
+The companion file `./start-interview.md` (Phase 27 ship) holds the 5-question copy,
+defaults, and validation rules. This file documents what `/gdd:start` does WITH the answers.
+
+## Step 0 — Dismiss-only shortcut
+
+If invoked with `--dismiss-nudge`:
+
+1. `touch ~/.claude/gdd-nudge-dismissed` (Windows: equivalent). Ignore errors silently.
+2. Print exactly: `Nudge dismissed. Delete ~/.claude/gdd-nudge-dismissed to re-enable.`
+3. Exit with `## START COMPLETE` marker.
+
+Do not proceed to any other step.
+
+## Step 1 — Detect UI root
+
+Run the detector:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/detect-ui-root.cjs" "$(pwd)"
+```
+
+Capture the JSON output. Branches:
+
+- `kind: "backend-only"` → print the frontend-only diagnostic below, write nothing, exit with `## START COMPLETE`. The diagnostic copy is:
+  > `/gdd:start` is for frontend codebases. This repo looks backend-only (detected `<framework>`). The plugin can still help with design references and component libraries imported by your clients — but there is no UI surface here to scan. Exiting without creating `.design/`.
+- `kind: null` (no package.json, no UI dir) → print a short "Nothing recognizable here — point me at a frontend repo and try again." and exit.
+- Any other `kind` → proceed with `detected.path` as the scan root.
+
+## Step 2 — Run the 5-question interview
+
+Read `./start-interview.md` for the exact question copy, defaults, and validation rules.
+
+If `--skip-interview`, skip this step and use the defaults documented in that file.
+
+Otherwise, ask the five questions in order using `AskUserQuestion`:
+
+1. Pain point (text, required, single-line cap 120 chars)
+2. Target area confirmation (detected path)
+3. Budget / latency preference (enum: fast / balanced / thorough)
+4. Framework + design-system confirmation (from detection)
+5. Figma / canvas workflow (enum: figma / canvas / neither / skip)
+
+Any early exit at Q1 → abort with a one-line pointer to `/gdd:scan`.
+
+Store the answers + detection result in `.design/.start-context.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "detected": { "kind": "...", "path": "...", "framework": "...", "design_system": "...", "confidence": 0.85 },
+  "interview": { "pain": "...", "target_area": "...", "budget": "balanced", "framework_confirmed": true, "design_system_confirmed": true, "figma_workflow": "skip" },
+  "generated_at": "<ISO-8601>"
+}
+```
+
+`.design/` is created here for the first time. `.design/STATE.md` is NOT written.
+
+## Step 3 — Scan findings
+
+Run the findings engine:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/start-findings-engine.cjs" \
+  --root "<detected.path>" \
+  --budget "<budget>" \
+  --pain "<pain_point>"
+```
+
+Capture the JSON. The output carries at most three findings, each with stable IDs `F1`..`F3`, plus `bestFirstProofId` (may be null).
+
+Append the engine output to `.design/.start-context.json` under a `scan` key.
+
+## Step 4 — Spawn the writer
+
+Dispatch `Task` with:
+
+- `subagent_type: design-start-writer`
+- `description: "Write .design/START-REPORT.md"`
+- `prompt:` a short instruction pointing the agent at `.design/.start-context.json` and asking it to emit the report per its Output contract. Include a reminder that it must produce exactly 7 H2 sections plus the JSON block, and must not write `STATE.md`.
+
+Wait for the agent to complete. The agent writes `.design/START-REPORT.md`.
+
+## Step 5 — Print the handoff
+
+Read the final line of `.design/START-REPORT.md` to capture the suggested command.
+
+Print exactly (one line, no emoji):
+
+```
+Report written to .design/START-REPORT.md. Next: run <suggested_command> to see the first proof.
+```
+
+If `bestFirstProofId` was null, the suggested command is `/gdd:brief` (the default fallback).
+
+Emit `## START COMPLETE` and exit.
+
+## Failure handling
+
+Every error path exits with `## START COMPLETE` and a one-line pointer. Do not half-write files: if the writer agent fails, keep `.design/.start-context.json` and tell the user they can rerun. Do not delete `.design/` unless it was empty before the run.

package/reference/style-doc-procedure.md

@@ -0,0 +1,150 @@
+---
+name: style-doc-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [style, handoff, component-spec, doc-writer, procedure, extracted]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/style/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing routing + mode-detection stays in `../skills/style/SKILL.md`; this file
+holds the agent-spawn payload, source-resolution paths, and the per-section spec the
+`design-doc-writer` agent produces. See `./shared-preamble.md#output-contract-reminders` for
+the cross-skill output discipline.
+
+# Style Doc Procedure
+
+Detailed procedure for the `get-design-done:style` standalone command — companion to
+`../skills/style/SKILL.md`. Read this file when executing the agent-spawn step (Step 4 in the
+skill) or when wiring the source-resolution fallback chain. The SKILL.md keeps the load-bearing
+mode detection + decision tree; this file holds the deep methodology.
+
+---
+
+## Mode Detection
+
+```
+If .design/DESIGN-SUMMARY.md exists:
+  mode = post-pipeline   (STYL-03)
+  pipeline_complete = true
+
+Elif .design/DESIGN.md exists:
+  mode = pre-pipeline    (STYL-04)
+  pipeline_complete = false
+
+Else:
+  Abort: "No .design/ artifacts found. Run /get-design-done scan first to initialize."
+```
+
+The mode controls which files are supplied to the agent in `<required_reading>`.
+
+---
+
+## Component Source Resolution
+
+Search for a source file matching the provided ComponentName (case-insensitive):
+
+1. `src/components/[ComponentName].tsx`
+2. `src/components/[ComponentName].jsx`
+3. `src/components/[ComponentName].vue`
+4. `src/components/[ComponentName].svelte`
+5. `src/**/[ComponentName]/index.tsx`
+6. `src/**/[ComponentName]/index.jsx`
+7. `components/[ComponentName].tsx`
+8. `components/[ComponentName].jsx`
+9. `components/[ComponentName].vue`
+10. `components/[ComponentName].svelte`
+
+**If multiple matches found:** Present the list to the user and prompt them to specify the exact path. Do not proceed until a single file is selected.
+
+**If zero matches found:** Abort with: "Component [ComponentName] not found in expected paths. Verify the name matches a file in src/components/ or components/."
+
+When `$ARGUMENTS` is empty, the skill enters **list mode** — glob the same source roots, also list task names from `.design/tasks/*.md` (if directory exists), display the list, and prompt the user to specify a ComponentName. Exit without generating any file.
+
+---
+
+## Agent Spawn Payload
+
+Once mode and source path are resolved, spawn the `design-doc-writer` agent:
+
+```
+Task("design-doc-writer", """
+<required_reading>
+[If pipeline_complete=true:]
+@.design/STATE.md
+@.design/DESIGN-SUMMARY.md
+@.design/DESIGN-CONTEXT.md
+@<component_source_path>
+[Else (pipeline_complete=false):]
+@.design/DESIGN.md
+@<component_source_path>
+@reference/anti-patterns.md
+@reference/audit-scoring.md
+</required_reading>
+
+Generate a handoff spec for component <ComponentName>.
+
+Context:
+  component_name: <ComponentName>
+  component_source_path: <resolved absolute path>
+  pipeline_complete: <true|false>
+  output_path: .design/DESIGN-STYLE-<ComponentName>.md
+
+Produce the doc per STYL-05 sections:
+  - Spacing Tokens (used by component)
+  - Color Tokens (used by component)
+  - Typography Scale (used by component)
+  - Component States (default, hover, focus, active, disabled, etc.)
+  - Token Semantic Health Score (raw-hex-ratio formula — see ./shared-preamble.md#token-first-reasoning)
+  - AI-Slop Detection (using ./anti-patterns.md BAN/SLOP patterns)
+  [If pipeline_complete=true:]
+  - Decisions Applied (D-XX from DESIGN-SUMMARY.md that mention this component)
+
+Emit ## DOC COMPLETE when the output file is written.
+""")
+```
+
+After the agent emits `## DOC COMPLETE`, confirm the file exists at `output_path` and report success to the user.
+
+---
+
+## STYL-05 Section Spec
+
+Each generated `.design/DESIGN-STYLE-[ComponentName].md` SHOULD contain (in this order):
+
+1. **Spacing Tokens** — every spacing token the component uses (paddings, gaps, margins). Cross-reference `./composition.md` for the 4 px / 8 px modular scale discipline.
+2. **Color Tokens** — every color token the component uses (background, foreground, border, focus ring, state-overlays). Cross-reference `./palette-catalog.md` for naming convention and `./shared-preamble.md#token-first-reasoning` for the raw-hex audit threshold.
+3. **Typography Scale** — type ramps the component reaches into (label, body, code, etc.) with size + line-height + weight. Cross-reference `./typography.md`.
+4. **Component States** — default, hover, focus, active, disabled, loading, error. Each row: token diff vs default.
+5. **Token Semantic Health Score** — raw-hex ratio = `raw_hex_count / total_color_uses`. Healthy < 5 %.
+6. **AI-Slop Detection** — apply `./anti-patterns.md` `BAN-*` and `SLOP-*` patterns to the component source. List violations.
+7. **Decisions Applied** (post-pipeline only) — D-XX entries from `DESIGN-SUMMARY.md` that name or describe this component.
+
+---
+
+## Examples
+
+**Example 1: Named component**
+
+```
+/get-design-done style Button
+```
+
+- Resolves component: `src/components/Button.tsx`
+- Detects mode: DESIGN-SUMMARY.md exists → post-pipeline
+- Spawns `design-doc-writer` with `pipeline_complete: true`
+- Output: `.design/DESIGN-STYLE-Button.md`
+
+**Example 2: No argument (list mode)**
+
+```
+/get-design-done style
+```
+
+- Globs component files from `src/components/`
+- Displays available components and exits without generating any file.
+
+---
+
+*Imported by: `../skills/style/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework).*

package/reference/style-vocabulary.md

@@ -16,6 +16,8 @@ This catalog gives two categories of agent a shared, unambiguous vocabulary for
 
 Style names in this file are preserved verbatim from the UUPM source to maintain ecosystem legibility. Do not rename or abbreviate styles when writing context files or audit reports.
 
+**See:** [`./proportion-systems.md`](./proportion-systems.md) for the whole-UI proportion system (4pt / 8pt / √2 baseline grids, modular relationships across type / spacing / sizing / radius) that the rows below reference when they call out "8pt spacing grid", "12-column grid", "section-level spacing (120–200px vertical rhythm)", and similar grid-anchored signatures.
+
 ---
 
 ## Style Table

package/reference/threat-modeling.md

@@ -0,0 +1,101 @@
+---
+name: threat-modeling
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [threat-modeling, stride, audit, security, trust-boundary, disposition]
+last_updated: 2026-05-18
+---
+
+# Threat Modeling
+
+Audit-side STRIDE / threat-modeling reference. Centralizes the categories, trust-boundary
+identification heuristics, and disposition framework (mitigate / accept / transfer) so
+consumer skills can cross-link rather than inline. Extracted as part of Phase 28.5 from
+inline content in `skills/quality-gate/SKILL.md` (the four-tier classification) and the
+shared verifier / audit family. See `./audit-scoring.md` for the design-side scoring
+framework, which uses STRIDE as one of its lenses.
+
+## When to use
+
+Apply STRIDE during:
+
+- **Verify entry** (Stage 5) when the changeset touches a trust boundary (auth, ingress,
+  deserialization, subprocess spawn).
+- **Audit pillar runs** when a heuristic flags potential security surface.
+- **Plan-phase risk-register population** when the plan touches user input, network
+  endpoints, file IO from user paths, or persisted state.
+- **Threat register on plans that ship new endpoints** — assign one of {mitigate, accept,
+  transfer} to every identified threat before the plan ships.
+
+## STRIDE categories
+
+| Letter | Threat                  | Audit lens                                         |
+|--------|-------------------------|----------------------------------------------------|
+| S      | Spoofing                | Auth surfaces — login, session, token issuance     |
+| T      | Tampering               | Data integrity — write paths, persisted state      |
+| R      | Repudiation             | Audit trails / logging — proof of action           |
+| I      | Information Disclosure  | PII / secret leakage — logs, errors, side channels |
+| D      | Denial of Service       | Resource exhaustion — unbounded loops, large reads |
+| E      | Elevation of Privilege  | AuthZ bypass — role checks, capability tokens      |
+
+## Trust boundaries
+
+A trust boundary is a point where untrusted input crosses into trusted code. Identify
+trust boundaries before applying STRIDE — each boundary is one analysis sweep.
+
+Identification heuristics:
+
+- **Network ingress** — HTTP, gRPC, WebSocket, MCP transport, any TCP/UDP listen socket.
+- **File reads from user-writable paths** — uploads, `$HOME` configs, user-supplied paths
+  from CLI args, drag-drop.
+- **Subprocess spawns with user-supplied args** — `exec`/`spawn` where any argv element
+  is reachable from user input (URL params, env vars, config keys).
+- **Deserialization of persisted format** — JSON, YAML, MsgPack, Protobuf, custom
+  formats. The deserializer is the boundary, regardless of where the bytes came from.
+- **Third-party SDK callouts** — when gdd hands data to a peer-CLI, the data leaves the
+  trust boundary; treat the return path as untrusted on re-entry.
+
+## Disposition framework
+
+Every identified threat MUST carry a disposition before the plan ships. Three values:
+
+| Disposition | When to use                                                                  |
+|-------------|------------------------------------------------------------------------------|
+| Mitigate    | Threat has both impact and likelihood; ASVS L1 requires the control. Build  |
+|             | the control as part of the plan; cite the test that proves it.               |
+| Accept      | Low impact AND low likelihood. Documented rationale in the threat register;  |
+|             | no code change required. Re-visit if the threat-surface scope grows.         |
+| Transfer    | Third-party owns the control surface (e.g., the OS, the runtime, a peer's   |
+|             | sandbox). Document the boundary; do not re-implement the control.            |
+
+Mitigations on Plan tasks are correctness requirements — the executor applies Rule 2
+(missing critical functionality) if a mitigation disposition is present but the
+implementation lacks the control.
+
+## Threat register schema
+
+When a plan carries a `<threat_model>` block in its frontmatter, each entry follows:
+
+```yaml
+- id: T-01
+  category: spoofing       # S, T, R, I, D, or E
+  surface: auth/login      # path or component the threat hits
+  description: "<one-line description>"
+  disposition: mitigate    # mitigate, accept, or transfer
+  control: "rate-limit + ASVS V2.2.1 password policy"   # required when mitigate
+  rationale: "<why accept/transfer>"                    # required when accept/transfer
+```
+
+Multiple threats per plan are normal. The disposition column is the load-bearing field —
+the executor scans it; the verifier scans it.
+
+## Cross-references
+
+- `./audit-scoring.md` — design-side audit-scoring rubric; STRIDE is one of its lenses.
+- `./anti-patterns.md` — concrete anti-patterns mapped to STRIDE categories where
+  applicable (e.g., `eval`-on-user-input → Tampering + EoP).
+- `./accessibility.md` — accessibility is the orthogonal lens; threat-modeling does not
+  cover it.
+- ASVS (OWASP Application Security Verification Standard) — external authority for the
+  control catalog. Cited in plan threat-registers as `ASVS V<chapter>.<section>`.

package/reference/typography.md

@@ -35,6 +35,8 @@ Choose a ratio and base size. Common ratios:
 
 Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values in the scale.
 
+**See:** [`./proportion-systems.md`](./proportion-systems.md) §Modular Relationships for how the type scale ties to spacing / sizing / radius scales — when one ratio drives all four scales the whole UI gains a single rhythm rather than four independently-tuned progressions.
+
 ---
 
 ## Line Height
@@ -228,6 +230,8 @@ Always include a non-variable fallback of the same family in the font stack:
 font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
 ```
 
+**See:** [`./i18n.md`](./i18n.md) §Multi-Script Font Stacks for when a multi-script project should ship weighted-static fonts rather than a single variable font (some scripts ship as static-only families; mixing scripts in a single variable file is rarely viable).
+
 ---
 
 ## Micro-Typography