@hegemonart/get-design-done 1.59.3 → 1.59.5

package/scripts/skill-templates/plan/plan-procedure.md

@@ -0,0 +1,278 @@
+---
+name: plan-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [plan, procedure, extracted, pipeline-stage, research, planner, checker]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/plan/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/plan/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (agent spawn prompts, chromatic
+scoping, synthesizer wiring, research-synthesis persistence, exploration artifact globbing).
+
+# Plan Procedure
+
+Detailed procedure for the get-design-done `plan` Stage 3 orchestrator. Companion to
+`../skills/plan/SKILL.md`. Read this file when executing a specific plan step; the
+SKILL.md keeps the essential workflow + decision tree, this file holds the deep
+agent prompts and pre-plan research wiring.
+
+---
+
+## Stage entry
+
+1. `mcp__gdd_state__transition_stage` with `to: "plan"`.
+   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
+2. `mcp__gdd_state__get` -> snapshot `state`. Use this snapshot for `<position>`, `<connections>`, `<must_haves>`, `<blockers>`, `<decisions>` in the current stage; do not re-read STATE.md directly.
+
+Abort with a clear error only if the user is trying to plan without DESIGN-CONTEXT.md - that is the true prerequisite, not STATE.md.
+
+## Flag Parsing
+
+Parse $ARGUMENTS:
+- `--auto` -> auto_mode=true (skip approvals, skip optional research)
+- `--parallel` -> parallel_mode=true (planner fills Touches:/Parallel: fields)
+
+## Parallelism Decision (before any multi-agent spawn)
+
+- Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+- Apply rules from `reference/parallelism-rules.md`.
+- Plan's pipeline is inherently sequential (researcher -> pattern-mapper -> planner -> checker). Expected verdict: **serial** (rule 1).
+
+<!-- Parallelism decision is currently carried as the status string of an update_progress call. A dedicated tool may be added in a follow-on plan; until then, the status string is the canonical carrier. -->
+
+After the parallelism decision is made:
+- Call `mcp__gdd_state__update_progress` with `task_progress: "<current>/<total>"` and `status: "plan_parallelism_decided: batch_size=<N>, reason=<short-reason>"`.
+
+## Probe Chromatic connection
+
+Run at stage entry, after reading STATE.md:
+
+Step C1 - CLI presence:
+  Bash: command -v chromatic 2>/dev/null || npx chromatic `--version` 2>/dev/null
+  -> found -> proceed to Step C2
+  -> not found -> chromatic: not_configured (skip all Chromatic steps)
+
+Step C2 - Token check:
+  Bash: test -n "${CHROMATIC_PROJECT_TOKEN}"
+  -> true -> chromatic: available
+  -> false -> chromatic: unavailable
+
+Also check: if storybook: not_configured -> chromatic effectively unavailable (emit note, do not run).
+
+Write chromatic status to STATE.md `<connections>` via `mcp__gdd_state__probe_connections` - pass the single-entry probe result (`[{ name: "chromatic", status: "<verdict>" }]`). Do not edit `<connections>` directly.
+
+## Chromatic Change-Risk Scoping (when chromatic: available)
+
+Before writing DESIGN-PLAN.md, if chromatic: available:
+1. Identify token/component files to be changed (from DESIGN-CONTEXT.md scope)
+2. Run: Bash: npx chromatic `--project-token` $CHROMATIC_PROJECT_TOKEN `--trace-changed=expanded` `--dry-run` 2>&1
+3. Parse output - count story files that depend on changed source files
+4. Pass story count to design-planner.md (see design-planner.md Chromatic Change-Risk section)
+If unavailable: design-planner proceeds without story-count annotation.
+
+---
+
+## Step 1 - Optional Research (skip if auto_mode)
+
+Complexity heuristic: if DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn design-phase-researcher. Otherwise skip.
+
+If spawning:
+
+```
+Task("design-phase-researcher", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-phase-researcher agent. Identify the project type from DESIGN-CONTEXT.md
+and research relevant design patterns, pitfalls, and stack-specific conventions.
+
+Output file: .design/DESIGN-RESEARCH.md
+Target: ~100 lines, ~2 min budget.
+
+Emit `## RESEARCH COMPLETE` when done.
+""")
+```
+
+Wait for `## RESEARCH COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
+
+## Step 1.5 - Pattern Mapping (mandatory, brownfield protection)
+
+```
+Task("design-pattern-mapper", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@reference/audit-scoring.md
+</required_reading>
+
+You are design-pattern-mapper. Grep the codebase for existing design patterns
+(color tokens, spacing scale, typography conventions, component styling) and
+write .design/DESIGN-PATTERNS.md. Classify by design concern — NOT by code
+architecture (no controllers, services, middleware vocabulary).
+
+Output file: .design/DESIGN-PATTERNS.md
+Emit `## MAPPING COMPLETE` when done.
+""")
+```
+
+Wait for `## MAPPING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
+
+## Step 1.6 - Assumptions Analysis (optional, same flag as research)
+
+If assumptions analysis enabled (skip if auto_mode):
+
+```
+Task("design-assumptions-analyzer", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@.design/DESIGN-PATTERNS.md
+</required_reading>
+
+You are design-assumptions-analyzer. Surface hidden design assumptions with
+confidence levels and evidence citations.
+
+Emit `## ANALYSIS COMPLETE` when done.
+""")
+```
+
+Wait for `## ANALYSIS COMPLETE`.
+
+## Step 1.7 - Synthesize pre-plan research inputs (Plan 10.1-04, D-13/D-15)
+
+If 2+ of the pre-plan research agents ran (`design-phase-researcher` Step 1, `design-pattern-mapper` Step 1.5, `design-assumptions-analyzer` Step 1.6), invoke synthesize to merge their outputs into a single compact brief. If only one ran, skip this step.
+
+    Skill("synthesize", {
+      outputs: [
+        (if Step 1 ran)   "=== from design-phase-researcher ===\n" + <read .design/DESIGN-RESEARCH.md>,
+        (if Step 1.5 ran) "=== from design-pattern-mapper ===\n"   + <read .design/DESIGN-PATTERNS.md>,
+        (if Step 1.6 ran) "=== from design-assumptions-analyzer ===\n" + <read .design/DESIGN-ASSUMPTIONS.md>
+      ],
+      directive: "Merge into a single compact pre-plan brief. Preserve per-source section headers so the planner can trace provenance. Consolidate duplicate recommendations with source tags. Target ~150 lines.",
+      output_shape: "markdown"
+    })
+
+Wait for `## SYNTHESIS COMPLETE`. Write to `.design/DESIGN-PREPLAN-BRIEF.md` (overwrite if present). Add `@.design/DESIGN-PREPLAN-BRIEF.md` to the planner's `<required_reading>` in Step 2 - individual files remain on disk for drill-down.
+
+**Parallel synthesizer note (future):** if a future plan variant spawns N parallel phase-researchers (e.g., one per project-type family), wire synthesize the same way as `skills/map/` Step 3.5.
+
+## Research-synthesis persistence (decisions + must-haves)
+
+When the synthesizer (design-phase-researcher / design-pattern-mapper / design-assumptions-analyzer) produces D-XX decisions and M-XX must-haves, persist each one through MCP instead of editing STATE.md directly.
+
+For each D-XX decision the synthesizer produces:
+- Call `mcp__gdd_state__add_decision` with `{ id: "D-XX", text: "...", status: "locked"|"tentative" }`.
+
+For each M-XX must-have the synthesizer produces:
+- Call `mcp__gdd_state__add_must_have` with `{ id: "M-XX", text: "...", status: "pending" }`.
+
+Issue these sequentially. Each call is event-emitting and lockfile-safe. Parallel issuance would serialize on the STATE.md lockfile with no throughput gain.
+
+## Step 2 - Plan
+
+```
+Task("design-planner", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@reference/audit-scoring.md
+@.design/DESIGN-PATTERNS.md
+[@.design/DESIGN-RESEARCH.md — only include if research step ran]
+[@.design/DESIGN-ASSUMPTIONS.md — only include if assumptions analysis ran]
+[@.design/DESIGN-PREPLAN-BRIEF.md — include if Step 1.7 synthesize ran; planner prefers this compact brief over the individual files above]
+[@.design/sketches/*/WINNER.md — include all completed sketch winners if present]
+[@.design/spikes/*/FINDINGS.md — include all completed spike findings if present]
+[@./.claude/skills/design-*-conventions.md — include all project-local design conventions if present]
+[@~/.claude/gdd/global-skills/*.md — include all global skills if directory exists; global conventions inform but do not override project-local D-XX decisions]
+</required_reading>
+
+You are the design-planner agent. Read DESIGN-CONTEXT.md and produce .design/DESIGN-PLAN.md
+with wave-ordered tasks, acceptance criteria, and (if parallel mode) Touches:/Parallel: fields.
+
+Context:
+- Pipeline stage: plan
+- auto_mode: <true|false>
+- parallel_mode: <true|false>
+
+Output file: .design/DESIGN-PLAN.md
+Format: per agents/design-planner.md Output Format section.
+
+Emit `## PLANNING COMPLETE` when done.
+""")
+```
+
+Wait for `## PLANNING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and a short `status` summary.
+
+## Step 3 - Check
+
+```
+Task("design-plan-checker", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-plan-checker agent. Validate DESIGN-PLAN.md will achieve DESIGN-CONTEXT.md
+brief goals across 5 dimensions: requirement coverage, task completeness, wave ordering,
+must-have derivation, auto mode compliance.
+
+Context:
+- auto_mode: <true|false>
+
+Output: structured result as response text (no file). Start with `## PLAN CHECK RESULT: PASS`
+or `## PLAN CHECK RESULT: ISSUES FOUND`.
+
+Emit `## PLAN CHECK COMPLETE` when done.
+""")
+```
+
+Wait for `## PLAN CHECK COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and a short `status` summary.
+
+If `## PLAN CHECK RESULT: ISSUES FOUND` and any BLOCKER issues:
+- Present issues to user and offer: (a) revise plan now - re-spawn design-planner with issue list, (b) accept and proceed, (c) abort.
+- If auto_mode: auto-accept WARNING issues, abort on BLOCKER issues.
+
+## Stage exit
+
+1. Call `mcp__gdd_state__set_status` with `status: "plan_complete"`.
+2. Call `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` and finalize the plan stage.
+
+The next stage (design) calls `mcp__gdd_state__transition_stage` on entry - this skill does NOT issue the transition itself, preserving the stage-owned-transition discipline established by brief->explore and explore->plan.
+
+## After Completion
+
+Print user-facing summary:
+- Plan tasks: N waves, M total tasks
+- Files: .design/DESIGN-PLAN.md (and .design/DESIGN-RESEARCH.md if research ran)
+- Next: `/get-design-done:design` to execute the plan
+
+---
+
+## Exploration artifacts & project-local conventions
+
+When building the planner spawn prompt, also glob for:
+- `.design/sketches/*/WINNER.md` - winning sketch rationale (informs directional tasks)
+- `.design/spikes/*/FINDINGS.md` - spike verdicts (inform task feasibility)
+- `./.claude/skills/design-*-conventions.md` - project-local design conventions
+
+Include each matching file in `<files_to_read>` / `<required_reading>` so the planner sees them when creating tasks. Spike findings from `.design/spikes/` inform task feasibility; sketch winners inform directional choice; project-local conventions override defaults.
+
+## `--research` mode (removed)
+
+V2-04 deferred the `--research` flag. Rationale: complexity of an additional
+agent spawn + Context7 integration outweighs the benefit of discover-stage
+auto-detect for most projects. Use /discover's Auto Mode for research-assisted
+discovery instead.
+
+The optional research step that already exists (Step 1, triggered by complexity
+heuristic: 3+ domain scopes OR 6+ decisions) covers the core use case without
+a separate CLI flag.
+
+If `--research` is reintroduced in a future version, define its scope in
+ROADMAP.md V2+ and update this section.

package/scripts/skill-templates/plant-seed/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gdd-plant-seed
+description: "Forward-looking design idea with a trigger condition. Seeds surface automatically when trigger is met. Writes to .design/SEEDS.md."
+argument-hint: "[--trigger <condition>] [text]"
+tools: Read, Write, AskUserQuestion
+disable-model-invocation: true
+---
+
+# {{command_prefix}}plant-seed
+
+**Role:** Capture an idea that is too early to act on now but should surface when a future condition is met. Backing store: `.design/SEEDS.md`.
+
+## Step 1 - Gather inputs
+
+- `<text>`: free-text idea. If empty, ask the user: "What's the seed idea?"
+- `--trigger <condition>`: the surfacing condition. If missing, ask: "What trigger condition should surface this idea? (e.g., 'when we add dark mode', 'when the nav component is redesigned', 'at next cycle start')"
+
+## Step 2 - Append to .design/SEEDS.md
+
+Create the file with `# Design Seeds` header if missing. Append:
+
+```markdown
+## Seed: <first 60 chars of text>
+**Trigger**: <condition>
+**Planted**: YYYY-MM-DD
+**Status**: dormant
+
+<full text>
+
+---
+```
+
+## Step 3 - Surfacing contract
+
+Seeds are surfaced automatically by `{{command_prefix}}progress` and `{{command_prefix}}health`. Those commands do a keyword match of each seed's trigger text against current STATE.md + `.design/CYCLES.md` content and print any matches as `Seed ready to germinate: <text>`.
+
+This skill does NOT surface seeds itself - it only plants them.
+
+## Output
+
+```
+━━━ Seed planted ━━━
+Trigger: when we add dark mode
+Status: dormant
+━━━━━━━━━━━━━━━━━━━━
+```
+
+## PLANT-SEED COMPLETE

package/scripts/skill-templates/pr-branch/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: gdd-pr-branch
+description: "Create a clean PR branch by filtering out .design/ and .planning/ commits. Code-review-ready branch for the design implementation work."
+argument-hint: "[<base-branch>]"
+tools: Read, Write, Bash
+disable-model-invocation: true
+---
+
+# {{command_prefix}}pr-branch
+
+Produces a branch that contains only code changes (under `src/`) so reviewers are not forced to read through `.design/` planning churn.
+
+## Steps
+
+1. **Determine base**: Use the argument if provided; otherwise read the current branch's merge base with `main` via `git merge-base HEAD main`.
+2. **List commits**: `git log --oneline <base>..HEAD` via Bash.
+3. **Classify each commit**: For each SHA, run `git show --name-only <sha>` and inspect the changed paths:
+   - **code-only**: all paths under `src/` (or other code dirs, not `.design/` / `.planning/`) → include
+   - **design-only**: all paths under `.design/` or `.planning/` → skip
+   - **mixed**: both kinds → include and log a note
+4. **Get cycle name**: Read `.design/STATE.md` for the current `cycle:` ID (default `cycle-1`).
+5. **Create branch**: `git checkout -b pr/<cycle>-clean <base>`.
+6. **Cherry-pick**: For every included SHA (in original order), run `git cherry-pick <sha>`. On conflict, abort the whole operation with a clear message and reset to the pre-op branch.
+7. **Print summary**: "PR branch `pr/<cycle>-clean` created with <N> commits. `.design/` and `.planning/` commits excluded. Mixed commits flagged: <list>."
+
+## Do Not
+
+- Do not rewrite history on the original branch.
+- Do not include `.design/` or `.planning/` paths - if a mixed commit contains them, the cherry-pick carries them through, but reviewers are warned.
+- Do not push the branch automatically - let `{{command_prefix}}ship` or the user push.
+
+## PR-BRANCH COMPLETE

package/scripts/skill-templates/progress/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: gdd-progress
+description: "Shows current pipeline position and routes to next action. --forensic runs 6-check integrity audit. Activates for requests involving showing current project state, routing to the next action, or a status check."
+argument-hint: "[--forensic]"
+tools: Read, Bash, Grep, Glob, mcp__gdd_state__get, mcp__gdd_status, mcp__gdd_phase_current
+---
+
+@reference/retrieval-contract.md
+
+# {{command_prefix}}progress
+
+**Role:** Show current position in the pipeline and recommend the next action. With `--forensic`, run a 6-check integrity audit.
+
+## Step 1 - Read state
+
+Two paths - MCP preferred when available, file-read fallback otherwise.
+
+### MCP path (preferred)
+
+When the harness exposes `mcp__gdd_status` (Phase 27.7+, registered via `npx @hegemonart/get-design-done --register-mcp`):
+
+1. Call `mcp__gdd_status` (no args). Returns `{phase, branch, last_decisions, last_completed_plans, blocker_count}` in one call.
+2. If you need `stage` / `task_progress` for the output line, call `mcp__gdd_phase_current` (no args). Returns `{phase, stage, task_progress, status}`.
+3. Skip to Step 2.
+
+This path loads the full priming context in 1–2 MCP calls (~3s, ~32k tokens - Storybloq benchmark).
+
+### File-read path (fallback)
+
+When MCP tools are not available, fall back to the legacy flow:
+
+1. Call `mcp__gdd_state__get` if exposed (Phase 20 STATE.md mutator MCP) → parsed state object. Otherwise, `Read .design/STATE.md` and parse the frontmatter + `<position>`, `<decisions>`, `<plans>` sections.
+2. Extract: `stage`, `cycle`, `last_checkpoint`, `task_progress`, `status`, `decisions.length`, open todos from `.design/TODO.md` (count unchecked `- [ ]` - outside the MCP catalog, so `Read` is still used).
+3. If STATE.md is missing, print: "No pipeline state. Run `{{command_prefix}}brief` first." and stop.
+
+This path loads the same context in 5–10 file reads (~100s, ~46.5k tokens - file-reading baseline).
+
+## Step 2 - Default output
+
+```
+━━━ Pipeline state ━━━
+Stage: <stage>   Cycle: <cycle or "default">   Wave: <wave>
+Last checkpoint: <timestamp>
+Decisions: <N>   Open todos: <N>
+Next: {{command_prefix}}<next-stage>
+━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Recommend next stage via the same logic as `{{command_prefix}}next` (route by which artifacts exist).
+
+### First-run connection nudge
+
+After the pipeline state block, if every `<connections>` entry from the snapshot is `not_configured` AND `.design/config.json > connections_onboarding` is absent, append once per session (transient marker `.design/.connections-nudge-shown`): `Tip: run {{command_prefix}}connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).`
+
+## Step 3 - Forensic audit (only if `--forensic`)
+
+Run these six checks and print PASS/WARN/FAIL per check:
+
+1. **Stale artifacts** - compare mtime of `.design/DESIGN.md` against most recent file under `src/` via `ls -lt`. WARN if DESIGN.md is older by >7 days.
+2. **Missing transitions** - `stage` from the `mcp__gdd_state__get` snapshot vs artifacts present. e.g. stage=`plan` requires DESIGN-CONTEXT.md. FAIL if expected artifact missing.
+3. **Token drift** - `wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md`; tokens ≈ bytes/4. WARN if combined >50000 tokens.
+4. **Aged DESIGN-DEBT** - read `.design/DESIGN-DEBT.md`; any item whose line predates HEAD by >14 days (check `git blame` or file mtime fallback) → WARN.
+5. **Cycle alignment** - if `cycle` from the snapshot is set but `.design/CYCLES.md` has no matching heading → FAIL.
+6. **Connection status** - re-probe figma/refero via ToolSearch; compare to the `<connections>` field in the snapshot. WARN on mismatch.
+
+Also scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match the snapshot or CYCLES.md content; list them as "Seed ready to germinate: <text>".
+
+Print:
+```
+━━━ Forensic audit ━━━
+[PASS] Stale artifacts
+[WARN] Token drift — 53,400 tokens combined
+[PASS] Missing transitions
+[PASS] Aged DESIGN-DEBT
+[PASS] Cycle alignment
+[WARN] Connection status — figma now unavailable
+Seeds ready: 0
+━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 3.5 - Composition-graph readiness
+
+After the pipeline state (and forensic audit if run), surface a one-line composition-graph hint from `scripts/lib/manifest/skills.json`. Count skill records declaring `composes_with` or `next_skills`, then probe for structural problems (cycles in the directed graph, or edges pointing at a skill name that has no record). Print one line:
+
+- `Composition graph: <edges> edges, <skills-with-edges> skills wired | cycles: <n> | dangling: <n>`
+
+Run `scripts/validate-composition-graph.cjs` for the authoritative cycle and dangling-edge counts when that validator is present; until then report `0` and note the graph is not yet wired. This is a readiness hint, not a gate.
+
+## Step 3.6 - DesignContext graph coverage
+
+When `.design/context-graph.json` exists, surface one line for the typed DesignContext graph using the `coverage` helper in `scripts/lib/design-context-query.cjs` (`node scripts/lib/design-context-query.cjs coverage`), then point at the Atomic-Design map: `DesignContext graph: <pct>% node-type coverage | map: .design/INTEGRATION-MAP.md`. Skip this line entirely when the graph is absent (a pre-Phase-52 project); offer `{{command_prefix}}migrate-context` as the next step instead. Readiness hint, not a gate.
+
+## Step 4 - Update notice (safe-window surface)
+
+After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by `hooks/update-check.sh` subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+No-op when: no new release exists, state-machine guard is active (stage in plan|design|verify), or the latest tag has been dismissed via `{{command_prefix}}check-update --dismiss`.
+
+## Do Not
+
+- Do not mutate STATE.md - this skill is read-only. Only `mcp__gdd_state__get` is permitted.
+
+## PROGRESS COMPLETE

package/scripts/skill-templates/quality-gate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: quality-gate
+description: "Stage 4.5 of the pipeline. Detects, runs, and classifies project quality commands (lint / typecheck / test / visual-regression) between {{command_prefix}}design and {{command_prefix}}verify; writes the most recent run to STATE.md <quality_gate>. Non-blocking on timeout (warn + proceed); failures spawn design-fixer until the loop converges or max_iters is reached."
+tools: Read, Write, Edit, Bash, Grep, Glob, Task
+color: amber
+model: inherit
+default-tier: haiku
+size_budget: M
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 180
+reads-only: false
+writes:
+  - ".design/STATE.md"
+  - ".design/events.jsonl"
+---
+
+@reference/shared-preamble.md
+
+# quality-gate
+
+## Role
+
+You are the Stage 4.5 gate that runs between `{{command_prefix}}design` and `{{command_prefix}}verify`. You answer one question: *does this project's own quality tooling pass against the current working tree?* You are NOT a design checker, an a11y checker, or a verifier - you are a thin façade over the project's `lint` / `typecheck` / `test` / visual-regression scripts. Verify refuses entry when those scripts fail.
+
+You write exactly two artifacts: the `<quality_gate>` block in `.design/STATE.md`, and lifecycle events to `.design/events.jsonl`. You never block on timeout. You never block on a "skipped" result. You only mark `status="fail"` when the fix loop reaches `max_iters` - even then YOU exit successfully (verify is the consumer that refuses entry).
+
+## Configuration
+
+Read once at start from `.design/config.json` (all optional; defaults in parens):
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `quality_gate.commands` | `null` | Authoritative command list. When provided, skips auto-detection. |
+| `quality_gate.timeout_seconds` | `600` | Total wall-clock budget for Step 2. On timeout: warn + proceed (D-07). |
+| `quality_gate.max_iters` | `3` | Hard cap on Step 4 fix-loop iterations. |
+
+## Step 1 - Detection chain (D-06 3-tier fallback)
+
+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), 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
+
+Emit `quality_gate_started`. Spawn each command in a separate `Bash`; collect `{command, exit_code, stdout, stderr}`. Wall-clock budget is `timeout_seconds` (default 600). On timeout: emit `quality_gate_timeout`, mark `status="timeout"`, skip Steps 3–4, proceed to Step 5. Exit successfully - verify treats timeout as a warn.
+
+## 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, 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)
+
+If `iteration >= max_iters`: emit `quality_gate_fail`, mark `status="fail"`, Step 5, exit successfully. Verify-entry refuses on `fail`; YOU do not throw.
+
+Else: increment `iteration`, emit `quality_gate_iteration`, spawn `design-fixer` via `Task` with classified failures + original outputs. After fixer returns, restart from Step 2 (re-run all commands - fixes can introduce regressions).
+
+## Step 5 - STATE write
+
+Mutate `state.quality_gate.run` to `{started_at, completed_at, status, iteration, commands_run, extra_attrs:{}}`. Persist via `mcp__gdd_state__set_quality_gate` or `apply()` mutator from `sdk/state/mutator.ts` - identical on-disk shape.
+
+## Step 6 - Event emission (D-09)
+
+Use `appendEvent` from `sdk/event-stream/index.ts` - persist-first / broadcast-second; never throws on persist path. `ts` / `cycle` / `stage` are stamped by the writer. Six event types (one per lifecycle position):
+
+| Event | When | Payload |
+|-------|------|---------|
+| `quality_gate_started` | Step 2 entry, once | `commands`, `timeout_seconds`, `max_iters` |
+| `quality_gate_iteration` | Step 4 retry (iter ≥ 2) | `iteration` |
+| `quality_gate_pass` | Step 3 returned pass - terminal | `iteration`, `commands_run` |
+| `quality_gate_fail` | Step 4 hit `max_iters` - terminal | `iteration`, `classified_failures` |
+| `quality_gate_timeout` | Step 2 budget elapsed - terminal warn | `unfinished_commands` |
+| `quality_gate_skipped` | Step 1 tier 3 - terminal no-op | `reason` |
+
+`appendEvent` swallows persist failures - events are observability, not correctness. STATE.md (Step 5) is the durable record.
+
+## Output
+
+Emit one JSON object on stdout: `{status, iteration, commands_run, started_at, completed_at}`. Shell exit code `0` on every terminal status - `fail` included. Verify-entry is the sole consumer that acts on `fail`.
+
+## Constraints
+
+- Do not prune the command list across iterations - re-run everything in Step 2.
+- Do not spawn `quality-gate-runner` more than once per iteration.
+- Do not read/write any STATE block other than `<quality_gate>` (and `<position>.last_checkpoint`).
+- Do not invoke verify or design - Stage 4.5 sits strictly between.
+- Exit-code convention: `0` clean; non-zero classified as failure. Do not interpret stderr for pass/fail.
+
+For verify-side severity classification (when this gate's `status="fail"` reaches the verify entry gate), see `./threat-modeling.md` - STRIDE dispositions are the audit-side framework that informs whether a failed quality gate blocks ship.

package/scripts/skill-templates/quality-gate/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 essential 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>`.