@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/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 load-bearing 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 load-bearing 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/skills/plant-seed/SKILL.md

@@ -3,6 +3,7 @@ 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
 ---
 
 # /gdd:plant-seed

package/skills/pr-branch/SKILL.md

@@ -3,6 +3,7 @@ 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
 ---
 
 # /gdd:pr-branch

package/skills/progress/SKILL.md

@@ -50,13 +50,7 @@ Recommend next stage via the same logic as `/gdd:next` (route by which artifacts
 
 ### First-run connection nudge
 
-After the pipeline state block, check the `<connections>` field from the `mcp__gdd_state__get` snapshot. If every entry is `not_configured` AND `.design/config.json > connections_onboarding` is absent (user has never run the wizard), append once:
-
-```
-Tip: run /gdd:connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).
-```
-
-Suppress the nudge on subsequent invocations in the same session (track via a transient marker file `.design/.connections-nudge-shown` written at first emit, deleted on next session start by no mechanism — so effectively once per session).
+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 /gdd:connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).`
 
 ## Step 3 — Forensic audit (only if `--forensic`)
 

package/skills/quality-gate/SKILL.md

@@ -5,7 +5,6 @@ tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: amber
 model: inherit
 default-tier: haiku
-tier-rationale: "Orchestration of pre-detected commands and a downstream Haiku classifier. The skill itself does no synthesis — Bash runs do all the work, the classifier agent owns the routing decision."
 size_budget: M
 parallel-safe: conditional-on-touches
 typical-duration-seconds: 180
@@ -21,202 +20,71 @@ writes:
 
 ## Role
 
-You are the Stage 4.5 gate that runs between `/gdd:design` and `/gdd:verify`. You answer one question: *does this project's own quality tooling pass against the current working tree?*
+You are the Stage 4.5 gate that runs between `/gdd:design` and `/gdd: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 are NOT a design checker, an a11y checker, or a verifier. You are a thin façade over the project's existing `lint` / `typecheck` / `test` / visual-regression scripts. You exist so that the verify stage can refuse entry when those scripts fail (and so that the fix loop can be bounded and observable).
+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).
 
-You write exactly two artifacts:
-1. The `<quality_gate>` block in `.design/STATE.md` (one most-recent `<run/>` element).
-2. Lifecycle events in `.design/events.jsonl` (per Step 6 below).
+## Configuration
 
-You never block on timeout. You never block on a "skipped" detection result. You only mark `status="fail"` when the fix loop reaches `max_iters` without converging — and even then it is the verify stage's job to refuse entry; YOU exit successfully so the user sees the report regardless.
-
-## Configuration Surface
-
-Read once at start, from `.design/config.json` (all keys optional; defaults documented):
+Read once at start from `.design/config.json` (all optional; defaults in parens):
 
 | Key | Default | Purpose |
 |-----|---------|---------|
-| `quality_gate.commands` | `null` | Authoritative list of commands. When provided, skips auto-detection. Each entry is a string the shell can run (e.g. `"npm run lint"`). |
+| `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. |
 
-Missing config file is not an error — defaults apply.
-
-## Step 1 — Detection chain
-
-Per D-06, resolve the active command list with this 3-tier fallback. Stop at the first tier that produces ≥ 1 command:
-
-### Tier 1 — Authoritative config
-
-If `.design/config.json` carries `quality_gate.commands` and the array is non-empty, use it verbatim. Skip Tier 2 and Tier 3.
-
-### Tier 2 — Auto-detect from `package.json#scripts`
-
-If `package.json` exists at the project root, read its `scripts` object. Match script names against the following allowlist (case-sensitive, exact match unless noted):
-
-| Script name | Notes |
-|-------------|-------|
-| `lint` | Always include if present. |
-| `typecheck` | Always include if present. |
-| `tsc` | Include if `typecheck` is absent (substitute, not duplicate). |
-| `test` | Include if present. |
-| `chromatic` | Include if present (visual-regression). |
-| `test:visual` | Include if present (visual-regression). |
+## Step 1 — Detection chain (D-06 3-tier fallback)
 
-**Excluded by name** (intentionally — too slow for a Stage 4.5 gate):
-- `test:e2e`
-- `test:integration` (only if a separate `test` exists)
-- Any script whose name starts with `dev:`, `build:`, `start:`.
+Stop at the first tier that produces ≥ 1 command:
 
-For each matched script, the command to run is `npm run <script-name>` (use `pnpm run` or `yarn` only if the project's root carries a corresponding lockfile and the user's `.design/config.json` lists `quality_gate.package_manager`; otherwise default to `npm run` for portability).
-
-If `package.json` does not exist, or `scripts` is empty, or no allowlisted name matches, advance to Tier 3.
-
-### Tier 3 — Skip with notice
-
-Emit a `quality_gate_skipped` event with `reason: "no commands resolved"` (Step 6). Write a `<run/>` element with `status="skipped"`, `commands_run=""`, `iteration=0`, `started_at` and `completed_at` set to the same timestamp. Exit successfully with status `skipped`. The verify-entry gate (Plan 25-07 territory) does NOT block on `skipped`.
+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`. 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
 
-Open Step 2 by emitting `quality_gate_started` with the resolved command list (Step 6).
-
-For each command produced by Step 1, spawn a **separate** `Bash` invocation; collect `{command, exit_code, stdout, stderr}` for each. Run them concurrently — the gate's wall-clock budget is the slowest command, not their sum.
-
-The combined wall-clock budget is `quality_gate.timeout_seconds` (default 600). If the budget elapses before all commands complete:
-
-1. Emit `quality_gate_timeout` with the names of commands that did not finish.
-2. Mark `status="timeout"`, `commands_run=<comma-joined attempted names>`, and treat unfinished commands as having no failure to classify.
-3. Skip Step 3 / Step 4 (no fix loop on timeout — it would just compound the slowness).
-4. Proceed to Step 5 (STATE write) and Step 6 (final event).
-5. **Exit successfully.** Verify entry treats `timeout` as a warn, not a block.
-
-If all commands complete within budget, advance to Step 3.
+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 the `quality-gate-runner` agent via the `Task` tool. Pass an input payload of the shape:
-
-```json
-{
-  "outputs": [
-    {"command": "npm run lint", "exit_code": 0, "stderr": ""},
-    {"command": "npm run typecheck", "exit_code": 1, "stderr": "<verbatim stderr>"},
-    {"command": "npm run test", "exit_code": 0, "stderr": ""}
-  ]
-}
-```
-
-The agent emits a single JSON object on stdout (see `agents/quality-gate-runner.md`):
-
-```json
-{
-  "status": "pass" | "fail",
-  "classified_failures": {
-    "lint": ["…"],
-    "type": ["…"],
-    "test": ["…"],
-    "visual": ["…"]
-  }
-}
-```
-
-When `status === "pass"`, advance directly to Step 5 with `iteration` equal to the current loop counter (starts at `1` on the first pass).
-
-When `status === "fail"`, advance to Step 4.
+Spawn `quality-gate-runner` agent via `Task` with payload `{outputs: [{command, exit_code, stderr}, ...]}`. Agent returns `{status: "pass"|"fail", classified_failures: {lint, type, test, visual}}`. `pass` → Step 5. `fail` → Step 4.
 
 ## Step 4 — Fix loop (D-08)
 
-If `iteration >= quality_gate.max_iters` (default 3), the loop is exhausted:
-- Emit `quality_gate_fail` with the final classified failures.
-- Mark `status="fail"`, persist the final `iteration`, and proceed to Step 5.
-- **Exit successfully.** Verify entry refuses on `status="fail"`; YOU do not throw.
+If `iteration >= max_iters`: emit `quality_gate_fail`, mark `status="fail"`, Step 5, exit successfully. Verify-entry refuses on `fail`; YOU do not throw.
 
-Otherwise, increment `iteration` and emit `quality_gate_iteration` with the current value. Spawn the existing `design-fixer` agent (Phase 5) via `Task` with classified failures as context — pass the same shape produced by Step 3 plus the original `outputs[]` for verbatim error context. After the fixer returns, restart from Step 2 (re-run all commands; do not prune to "only the previously failing ones" — fixes can introduce regressions in formerly-clean commands).
-
-The loop terminates when either Step 3 returns `status="pass"` or `iteration` reaches `max_iters`.
+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
 
-Open `.design/STATE.md`. Mutate the parsed state's `quality_gate` field to:
-
-```ts
-{
-  run: {
-    started_at: <ISO 8601 — captured at Step 2 entry>,
-    completed_at: <ISO 8601 — now>,
-    status: <"pass" | "fail" | "timeout" | "skipped">,
-    iteration: <final loop counter>,
-    commands_run: <comma-joined names of commands that completed>,
-    extra_attrs: {},
-  },
-}
-```
-
-Persist via `mcp__gdd_state__set_quality_gate` (the underlying mutator wiring is named in this contract; the SDK MCP layer wraps every mutator method, so the surface inherits free from the parser/mutator extension landed in this plan). Until the MCP tool exists (Plan 25-07 surfaces it in the verify-stage integration), use the `apply()` mutator from `scripts/lib/gdd-state/mutator.ts` directly:
-
-```ts
-apply(raw, (state) => {
-  state.quality_gate = { run };
-  return state;
-});
-```
-
-Either path is acceptable. The on-disk shape is identical.
+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 `scripts/lib/gdd-state/mutator.ts` — identical on-disk shape.
 
 ## Step 6 — Event emission (D-09)
 
-Emit lifecycle events to `.design/events.jsonl` via the existing `appendEvent()` surface exported from `scripts/lib/event-stream/index.ts` — the same module Phase 22 telemetry, the budget-enforcer, the read-injection scanner, and the gdd-state MCP server already write through. Do not roll a bespoke writer; the singleton in `event-stream/index.ts` is persist-first / broadcast-second and never throws on the persist path, which is the contract this skill relies on.
-
-Import shape:
+Use `appendEvent` from `scripts/lib/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):
 
-```ts
-import { appendEvent } from '../../scripts/lib/event-stream/index.ts';
-```
+| 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` |
 
-Each emission is a single `appendEvent({...})` call with `type` set to one of the six names in the table below. Pass the event-specific payload fields verbatim — `appendEvent` stamps `_meta` (pid, host, source) and the JSONL writer captures the canonical `ts` from the writer surface. The `cycle` and `stage` fields are stamped by the same path used elsewhere in Phase 22+ (consumers match on `type`; treat `ts`, `cycle`, `stage` as injected, not caller-supplied).
+`appendEvent` swallows persist failures — events are observability, not correctness. STATE.md (Step 5) is the durable record.
 
-One event per JSONL line. Schema and lifecycle map:
+## Output
 
-| Event | When (lifecycle position) | Required fields |
-|-------|---------------------------|-----------------|
-| `quality_gate_started` | Step 2 entry — fired ONCE per skill invocation, immediately before any `Bash` spawn. Carries the resolved command list from Step 1 so downstream telemetry can correlate `started` → terminal event. | `commands` (string[]), `timeout_seconds` (number), `max_iters` (number) |
-| `quality_gate_iteration` | Step 4 entry — fired ONCE per retry, with `iteration` set to the new (post-increment) loop counter. The first run is implicit (covered by `started`); only retries `≥ 2` emit `iteration`. | `iteration` (int ≥ 2) |
-| `quality_gate_pass` | Step 3 returned `status: "pass"` — terminal happy path. Fires before Step 5 (STATE write) so a consumer tailing the stream sees the verdict before the on-disk run record. | `iteration` (final loop counter), `commands_run` (string[]) |
-| `quality_gate_fail` | Step 4 reached `max_iters` without convergence — terminal failure path. The verify-entry gate (Step 2.5 of `skills/verify/SKILL.md`) is the sole consumer that *acts* on this; this skill exits successfully regardless. | `iteration` (final loop counter, equal to `max_iters`), `classified_failures` (object — same shape as `quality-gate-runner` agent output) |
-| `quality_gate_timeout` | Step 2 wall-clock budget elapsed — terminal warn path (per D-07 verify treats this as a warning, not a block). Fires before Step 5 STATE write, same ordering as `pass`/`fail`. | `unfinished_commands` (string[]) |
-| `quality_gate_skipped` | Step 1 Tier 3 fired (no commands resolved) — terminal no-op path. Fires before the synthetic `<run/>` is written to STATE.md. | `reason` (string — e.g. `"no commands resolved"`) |
-
-All six events carry the standard `ts`, `cycle`, `stage` fields injected by `appendEvent` / the writer. Do not invent additional event names — the verify-entry gate, reflector, and Phase 22 telemetry consumers match on this exact list. Do not emit any of these names from any path other than the lifecycle positions above (e.g., do not emit `quality_gate_started` again on a Step 4 retry — that's what `quality_gate_iteration` is for).
-
-**Failure-mode contract:** `appendEvent()` swallows persist failures internally. If the writer cannot open `.design/events.jsonl`, the skill MUST still proceed — the event stream is observability, not correctness. The STATE.md write in Step 5 is the durable record consumers MUST rely on; events.jsonl is the supplementary timeline.
-
-## Output Contract
-
-Emit a single JSON object on stdout summarizing the run for the caller:
-
-```json
-{
-  "status": "pass",
-  "iteration": 1,
-  "commands_run": ["npm run lint", "npm run typecheck", "npm run test"],
-  "started_at": "2026-04-29T10:00:00Z",
-  "completed_at": "2026-04-29T10:01:42Z"
-}
-```
-
-Schema:
-- `status` — `pass | fail | timeout | skipped`.
-- `iteration` — final loop counter; `0` for `skipped`.
-- `commands_run` — array of command strings actually executed.
-- `started_at` / `completed_at` — ISO 8601, copied from the STATE write.
-
-The skill exits with shell exit code `0` on every terminal status — including `fail`. The verify-entry gate is the sole consumer of the `fail` status; this skill never throws to the orchestrator.
+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 — always re-run everything in Step 2.
-- **Do not** spawn `quality-gate-runner` more than once per loop iteration. Spawn `design-fixer` more than once if and only if the loop iterates.
-- **Do not** read or write any STATE block other than `<quality_gate>` and `<position>` (the latter only as required by the standard write contract; the gate is a checkpoint, not a stage transition, so `<position>` updates are limited to `last_checkpoint`).
-- **Do not** invoke verify or design — Stage 4.5 sits strictly between them.
-- Treat exit codes via the standard convention: `0` = clean; non-zero = failure to be classified. Do not interpret stderr content for the pass/fail decision — the agent does that classification, you do not.
+- 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.