@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/verify/verify-procedure.md

@@ -0,0 +1,512 @@
+---
+name: verify-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [verify, procedure, extracted, pipeline-stage, gap-loop, must-have, quality-gate]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/verify/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/verify/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (state integration, quality-gate
+decision tree, agent spawn protocols, gap-response loop, must-have flipping).
+
+# Verify Procedure
+
+Detailed procedure for the get-design-done `verify` Stage 5 orchestrator. Companion to
+`../skills/verify/SKILL.md`. Read this file when executing a specific verify step; the
+SKILL.md keeps the load-bearing workflow + decision tree, this file holds the deep
+methodology, agent prompts, and gap-loop semantics.
+
+---
+
+## State Integration
+
+### Stage entry
+
+1. `mcp__gdd_state__transition_stage` with `to: "verify"`.
+2. `mcp__gdd_state__get` → snapshot `state`. Read `state.must_haves` — this is the verification checklist; each M-XX starts at `status: pending` and will be flipped to `pass` or `fail` as verification concludes.
+
+#### Step 2.5 — Quality-gate gate (D-08, D-09)
+
+Before resume detection, inspect `state.quality_gate` from the same snapshot. The Stage 4.5 quality-gate skill (see `skills/quality-gate/SKILL.md`) writes a single `<run/>` element capturing the most recent run; this step is the verify-side consumer of that result. Three branches, evaluated in order:
+
+- **`state.quality_gate?.run?.status === "fail"`** → Refuse to advance. The fix loop in `quality-gate/SKILL.md` Step 4 reached `max_iters` without converging, and the verify stage MUST NOT paper over it. Print a blocker reason that includes the iteration count and the `commands_run` field from the run, then call:
+
+  ```
+  mcp__gdd_state__add_blocker({
+    stage: "verify",
+    text: "quality-gate failed at iteration <N> (commands: <commands_run>) — re-run /gdd:quality-gate before /gdd:verify"
+  })
+  ```
+
+  Exit immediately with the failure surface visible to the user. Do NOT call `mcp__gdd_state__update_progress` to open the verify stage; the gate refused entry, so the stage was never opened.
+
+- **`state.quality_gate?.run?.status === "timeout"` OR `=== "skipped"`** → Print a one-line warning naming the status and the `commands_run` value, then continue normally. Per D-07 these are signals, not walls: a slow test suite must not hostage the pipeline, and a project with no detectable quality commands must not block verify entry. The warning surfaces the degraded state without halting.
+
+- **`state.quality_gate?.run?.status === "pass"` OR `state.quality_gate === null`** → Continue silently. `pass` is the happy path; `null` means the gate has never been run for this cycle (the user skipped Stage 4.5 entirely, which is permitted — verify only *checks* the gate result, never *runs* the gate itself, per the 25-07 out-of-scope clause).
+
+This step is a pure read against the snapshot already loaded in Step 2 — no extra MCP call is required.
+
+3. Resume detection (read `state.position.status` from the snapshot):
+   - If `status==in_progress` and `.design/DESIGN-VERIFICATION.md` exists: RESUME — skip re-spawning agents, go to Step 2 (gap-response loop).
+   - Otherwise: call `mcp__gdd_state__update_progress` with `task_progress: "0/3"`, `status: "in_progress"` to open the stage, then proceed to Step 1.
+4. If STATE.md is missing entirely (edge case — verify is never the entry point): block with "No STATE.md found — run /get-design-done:discover first." Do NOT attempt to create a skeleton from verify; upstream stages own bootstrap.
+
+---
+
+## Flipping a must-have status
+
+When verification concludes that M-XX is satisfied (or failed), record the result by issuing:
+
+`mcp__gdd_state__add_must_have` with the SAME `id` as the existing entry and the updated `status`:
+
+```json
+{ "id": "M-03", "text": "Dark mode toggle persists to localStorage", "status": "pass" }
+```
+
+The gdd-state mutator treats an `add_must_have` with an existing id as an **update-in-place**, not a duplicate append. The entry's position in the `<must_haves>` block is preserved. This is intentional design — verify doesn't need a dedicated `update_must_have_status` tool because `add_must_have` handles both cases correctly.
+
+Pass the original `text` verbatim when you're only flipping the status; supplying a changed `text` overwrites the prose in-place as well (useful when the M-XX description was imprecise and the verifier can restate it). Omit `text` by passing the value from the earlier `mcp__gdd_state__get` snapshot.
+
+---
+
+## Connection Probes
+
+### Probe Preview connection
+
+Run at stage entry, after reading STATE.md:
+
+```
+Step P1 — ToolSearch check:
+  ToolSearch({ query: "Claude_Preview", max_results: 5 })
+  -> Empty result      -> preview: not_loaded  (MCP not registered — skip all Preview steps in this stage)
+  -> Non-empty result  -> proceed to Step P2
+
+Step P2 — Live tool call:
+  call mcp__Claude_Preview__preview_list
+  -> Success                               -> preview: available
+  -> Error containing "permission"/blocked -> preview: permission_denied
+  -> Any other error                       -> preview: unreachable
+
+Record the preview probe result via `mcp__gdd_state__probe_connections` (batched with the storybook and chromatic probes below — one call per stage, see "Batched connections write" at the end of this section).
+```
+
+When `preview: available`, the design-verifier agent runs Phase 4B — Screenshot Evidence to resolve `? VISUAL` heuristic flags with real screenshot evidence. See `agents/design-verifier.md` Phase 4B for the screenshot evidence loop.
+
+### Probe Storybook connection
+
+Run at stage entry, after reading STATE.md:
+
+Step B1 — Project detection:
+  Bash: ls .storybook/ 2>/dev/null || grep -l '"storybook"' package.json 2>/dev/null
+  -> Found -> storybook_project: true -> proceed to Step B2
+  -> Not found -> storybook: not_configured (skip all Storybook steps)
+
+Step B2 — Dev server detection:
+  Bash: curl -sf http://localhost:6006/index.json 2>/dev/null | head -1
+  -> Returns JSON -> storybook: available
+  -> Fails -> Bash: curl -sf http://localhost:6006/stories.json 2>/dev/null | head -1
+      -> Returns JSON -> storybook: available (compat endpoint)
+      -> Fails -> storybook: unavailable
+
+Record the storybook probe result for the batched `mcp__gdd_state__probe_connections` call (see below).
+
+### Storybook A11y Loop (when storybook: available)
+
+If `state.connections.storybook === "available"` (from the earlier `mcp__gdd_state__get` snapshot):
+1. Run: Bash: npx storybook test --ci 2>&1 | tee .design/storybook-a11y-report.txt
+2. Read .design/storybook-a11y-report.txt — pass to design-verifier as additional a11y evidence
+3. design-verifier reads this file in its a11y gap analysis section and annotates DESIGN-VERIFICATION.md with per-story violations
+
+If storybook: unavailable — skip this section; run standard WCAG grep-based a11y checks only.
+If storybook: not_configured — skip; emit no note (opt-in feature).
+
+### 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).
+Record the chromatic probe result for the batched `mcp__gdd_state__probe_connections` call below.
+
+### Batched connections write
+
+After all three probes (preview, storybook, chromatic) have a verdict, call `mcp__gdd_state__probe_connections` ONCE with `probe_results` = an array of `{ name, status }` entries — one per probed connection. Example:
+
+```json
+[
+  { "name": "preview",   "status": "available" },
+  { "name": "storybook", "status": "unavailable" },
+  { "name": "chromatic", "status": "not_configured" }
+]
+```
+
+Unspecified connections keep their existing value. Do NOT issue multiple `probe_connections` calls — the tool is designed for a single batch write per stage.
+
+### Chromatic Visual Delta (when chromatic: available)
+
+After design executor has run (when verifying post-design):
+1. Run: Bash: npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN --output json 2>&1 | tee .design/chromatic-results.json
+2. Pass .design/chromatic-results.json to design-verifier for narration (see design-verifier.md Chromatic Delta Narration section)
+If chromatic: unavailable or not_configured: skip; note in DESIGN-VERIFICATION.md "visual regression check skipped".
+
+---
+
+## Prerequisite Checks
+
+**DESIGN-PLAN.md prerequisite check:**
+- **Normal mode:** Check that `.design/DESIGN-PLAN.md` exists. If missing, block with: "Verify requires DESIGN-PLAN.md. Run `/gdd:plan` first, or use `--post-handoff` if starting from a Claude Design handoff bundle."
+- **Post-handoff mode** (`post_handoff=true` OR STATE.md `status: handoff-sourced`): Skip the DESIGN-PLAN.md check entirely — handoff workflows have no DESIGN-PLAN.md.
+
+Abort only if no `.design/` directory exists (user has not run prior stages). Output: "No .design/ directory found. Run /get-design-done:discover first."
+
+## Post-Handoff Mode
+
+When `--post-handoff` flag is present OR STATE.md `<position>` contains `status: handoff-sourced`:
+
+1. **Skip DESIGN-PLAN.md prerequisite check** (no plan exists in handoff flows)
+2. **Pass `post_handoff: true` to design-verifier** spawn prompt (see Step 1b below)
+3. **Pass `handoff_path`** from STATE.md to design-verifier spawn prompt
+4. **DESIGN-VERIFICATION.md** will include a `## Handoff Faithfulness` section generated by design-verifier (see `agents/design-verifier.md` Handoff Faithfulness Phase)
+
+Also pass post-handoff context to design-auditor: auditor skips DESIGN-PLAN.md reads and focuses on implementation-vs-bundle gap analysis.
+
+## Flag Parsing
+
+- `--auto` -> `auto_mode=true` (no interactive prompts; skip visual UAT interactive steps; on gaps: save-and-exit rather than prompt for fix)
+- `--post-handoff` -> `post_handoff=true` (relax DESIGN-PLAN.md prerequisite; instruct verifier to add Handoff Faithfulness section; see ## Post-Handoff Mode below)
+
+## Parallelism Decision (before agent spawns)
+
+- Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+- Apply rules from `reference/parallelism-rules.md`.
+- `design-verifier` depends on `design-auditor` output (rule 1) -> serial between those two. `design-integration-checker` is independent of the auditor's *file* output but runs after verifier in the current sequence; if config opts in, `design-auditor` and `design-integration-checker` can parallelize (disjoint writes). Default: serial.
+- Record `<parallelism_decision>` via `mcp__gdd_state__set_status` (e.g., `status: "verify_parallelism_decided: <serial|parallel>"`) before spawning. Do not write STATE.md directly.
+
+---
+
+## Step 1 — Spawn Auditor + Verifier + Integration Checker
+
+Initialize iteration counter to 0 (used for fix loop limit in Step 3).
+
+Three agents run in sequence. Each waits for its completion marker before the next is spawned.
+
+**Note on lazy gates (Plan 10.1-04 / D-21):** Each full checker is preceded by a cheap Haiku gate that reads the diff and may return `{spawn: false}` to short-circuit. When gated out, `lazy_skipped: true` is appended to `.design/telemetry/costs.jsonl`. Gates: `design-verifier-gate` (before 1b), `design-integration-checker-gate` (before 1c). `design-context-checker-gate` is wired into `skills/discover/SKILL.md` Step 1.75.
+
+### 1a. Run design-auditor first (retrospective 6-pillar audit)
+
+```
+Task("design-auditor", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@.design/DESIGN-PLAN.md
+@.design/tasks/
+@reference/audit-scoring.md
+</required_reading>
+
+You are the design-auditor agent. Run the 6-pillar retrospective audit (copy, visual hierarchy,
+color, typography, layout/spacing, experience design) against the completed design work.
+
+Score each pillar 1-4. Write your findings to .design/DESIGN-AUDIT.md.
+
+This audit SUPPLEMENTS the 7-category 0-10 system in reference/audit-scoring.md — do not replace
+or contradict it. Your output will be read by design-verifier as additional context.
+
+Emit `## AUDIT COMPLETE` when done.
+""")
+```
+
+Wait for `## AUDIT COMPLETE` in the agent response. Once detected, call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary (e.g., `status: "audit_done"`).
+
+### 1b-gate. Lazy gate — should design-verifier run?
+
+Spawn the cheap Haiku gate before the expensive verifier:
+
+    Task("design-verifier-gate", """
+    <required_reading>
+    @.design/STATE.md
+    </required_reading>
+
+    You are the design-verifier-gate. Read the diff since the last verified commit
+    and decide whether design-verifier should spawn.
+
+    Context:
+      diff_files: <output of `git diff --name-only <baseline_sha>..HEAD`>
+      diff_body: <output of `git diff <baseline_sha>..HEAD` truncated to 4000 lines>
+      baseline_sha: <from .design/STATE.md last_verified_sha, or HEAD~1 if absent>
+
+    Apply the heuristic. Emit JSON + `## GATE COMPLETE`.
+    """)
+
+Wait for `## GATE COMPLETE`. Parse the JSON:
+
+- `spawn: false` -> append pending telemetry row `{ts, agent: "design-verifier", tier: "skipped", tokens_in: 0, tokens_out: 0, cache_hit: false, est_cost_usd: 0, lazy_skipped: true, gate_rationale: "<from gate>", cycle, phase}` (PreToolUse hook from 10.1-01 flushes on next tool use; orchestrator MAY stub-append directly to `.design/telemetry/costs.jsonl` until 10.1-05 lands). Skip 1b. Call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and `status: "verifier_gate_skipped"`. Emit `design-verifier skipped — gate rationale: <rationale>`.
+- `spawn: true` -> proceed to 1b as currently written.
+
+### 1b. Run design-verifier (reads auditor output as additional input)
+
+```
+Task("design-verifier", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-AUDIT.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+@.design/tasks/
+@reference/audit-scoring.md
+@reference/heuristics.md
+@reference/review-format.md
+@reference/accessibility.md
+</required_reading>
+
+You are the design-verifier agent. Run the 5-phase verification against completed design work.
+
+DESIGN-AUDIT.md (above) contains a retrospective 6-pillar qualitative audit from design-auditor.
+Read it as supplementary signal — incorporate the priority fix list into your Phase 5 gap analysis
+where relevant. The auditor's 1-4 scores complement your 0-10 category scores; they do not
+replace your Phase 1 category scoring.
+
+Context:
+  auto_mode: <true|false>
+  re_verify: false
+  post_handoff: <true|false — true when --post-handoff flag active or STATE.md status==handoff-sourced>
+  handoff_path: <value from STATE.md handoff_path, or empty string>
+
+Write .design/DESIGN-VERIFICATION.md. If post_handoff is true, include ## Handoff Faithfulness section
+(see agents/design-verifier.md Handoff Faithfulness Phase). If gaps found, emit `## GAPS FOUND` followed
+by structured gap list, then `## VERIFICATION COMPLETE`. If no gaps, just emit `## VERIFICATION COMPLETE`.
+""")
+```
+
+Wait for `## VERIFICATION COMPLETE` in the agent response. Once detected, call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and a short `status` summary (e.g., `status: "verifier_done"`).
+
+### 1c-gate. Lazy gate — should design-integration-checker run?
+
+Same pattern as 1b-gate:
+
+    Task("design-integration-checker-gate", """
+    <required_reading>
+    @.design/STATE.md
+    </required_reading>
+
+    You are the design-integration-checker-gate. Read the diff and decide whether
+    design-integration-checker should spawn.
+
+    Context:
+      diff_files: <git diff --name-only output>
+      diff_body: <git diff output, truncated>
+      baseline_sha: <from STATE.md or HEAD~1>
+
+    Apply the heuristic. Emit JSON + `## GATE COMPLETE`.
+    """)
+
+Wait for `## GATE COMPLETE`. Parse JSON:
+
+- `spawn: false` -> append `lazy_skipped: true` telemetry row (same shape), skip 1c, call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and `status: "integration_checker_gate_skipped"`, emit `design-integration-checker skipped — gate rationale: <rationale>`.
+- `spawn: true` -> proceed to 1c as currently written.
+
+### 1c. Run design-integration-checker (post-verification decision wiring check)
+
+```
+Task("design-integration-checker", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@.design/DESIGN-VERIFICATION.md
+</required_reading>
+
+You are the design-integration-checker agent. Verify that each D-XX design decision recorded
+in DESIGN-CONTEXT.md is actually reflected in the source code.
+
+Check each decision by type:
+- Typography decisions -> grep font-size/scale values against declared scale
+- Color decisions -> grep for removed colors (expect 0 hits) and added tokens (expect >=1 hit)
+- Layout/spacing decisions -> grep spacing values against declared grid
+- Component decisions -> grep for old patterns (expect 0) and new patterns (expect >=1)
+
+Return: Connected count, Orphaned count, Missing count with per-decision evidence.
+Emit `## INTEGRATION CHECK COMPLETE` when done.
+""")
+```
+
+Wait for `## INTEGRATION CHECK COMPLETE` in the agent response. Once detected, call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and a short `status` summary (e.g., `status: "integration_check_done"`).
+
+**Note:** Integration-checker findings (Orphaned and Missing decisions) are treated as additional gaps and fed into the gap-response loop in Step 2 alongside verifier gaps.
+
+---
+
+## Step 2 — Interpret Result
+
+Check agent responses for gaps. Gaps come from two sources:
+- design-verifier: `## GAPS FOUND` marker in the verifier response (G-NN entries)
+- design-integration-checker: Orphaned or Missing decisions in the integration checker response (any decision with status Orphaned or Missing is a gap)
+
+### Consolidate gaps:
+
+Merge verifier gaps (G-NN entries) and integration-checker gaps (Orphaned/Missing D-XX decisions) into a single gap list. Integration-checker Orphaned decisions become MAJOR gaps; Missing decisions become BLOCKER gaps (a decision that was never applied).
+
+### If NO gaps from either source (PASS):
+
+- For each M-XX from the earlier `mcp__gdd_state__get` snapshot (`state.must_haves`): call `mcp__gdd_state__add_must_have` with the same `id`, the same `text`, and `status: "pass"`. The mutator updates in-place (see "Flipping a must-have status" above).
+- Go to **Stage exit** with status=completed.
+
+### If GAPS FOUND (from either source):
+
+- Parse all gaps (verifier + integration-checker combined).
+- Count gaps by severity (BLOCKER, MAJOR, MINOR, COSMETIC).
+- If `auto_mode=true`: preserve DESIGN-VERIFICATION.md, call `mcp__gdd_state__set_status` with `status: "blocked"`, then call `mcp__gdd_state__add_blocker` with `stage: "verify"` and `text: "N blockers found — see .design/DESIGN-VERIFICATION.md and integration-checker output"` (the mutator stamps the ISO date automatically). Exit with message:
+  ```
+  Verification failed — N gaps found (X blockers, Y majors, Z minors, W cosmetics).
+  Report: .design/DESIGN-VERIFICATION.md
+  Fix gaps and re-run: /get-design-done:verify
+  ```
+- If `auto_mode=false`: present gap summary and menu (go to Step 3).
+
+---
+
+## Step 3 — Gap Response Loop
+
+Present to the user:
+
+```
+=== Verification found N gaps ===
+  BLOCKER: X
+  MAJOR:   Y
+  MINOR:   Z
+  COSMETIC:W
+
+Options:
+  [1] Fix now   — inline fix for addressable gaps, then re-verify
+  [2] Save and exit — work preserved; fix in a later session
+  [3] Accept as-is  — mark verify complete despite gaps (not recommended for blockers)
+
+Choose:
+=================================
+```
+
+### If user chose [2] Save and exit:
+
+- Preserve DESIGN-VERIFICATION.md.
+- Call `mcp__gdd_state__set_status` with `status: "blocked"`.
+- Call `mcp__gdd_state__add_blocker` with `stage: "verify"` and `text: "N gaps outstanding — see .design/DESIGN-VERIFICATION.md"` (ISO date stamped by the mutator).
+- Call `mcp__gdd_state__checkpoint` to record the save-and-exit checkpoint.
+- Exit:
+  ```
+  Gaps saved. Resume with: /get-design-done:verify
+  Report: .design/DESIGN-VERIFICATION.md
+  ```
+
+### If user chose [3] Accept as-is:
+
+- For each unmet must-have (from the earlier snapshot, comparing against verifier gaps): call `mcp__gdd_state__add_must_have` with the same `id`, the same `text`, and `status: "fail"` (update-in-place idiom). Then proceed to exit.
+- Call `mcp__gdd_state__add_blocker` with `stage: "verify"` and `text: "accepted with N unresolved gaps"`.
+- Go to **Stage exit** with status=completed.
+
+### If user chose [1] Fix now:
+
+Check fix iteration counter. If counter >= 3:
+```
+Maximum fix iterations (3) reached. Saving current state and exiting.
+Outstanding gaps remain — see .design/DESIGN-VERIFICATION.md.
+```
+Treat as Save and exit (option 2 above).
+
+Otherwise: increment iteration counter and spawn design-fixer:
+
+Task("design-fixer", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-VERIFICATION.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+Fix all BLOCKER and MAJOR gaps from ## Phase 5 — Gaps in DESIGN-VERIFICATION.md.
+For each gap: apply the targeted fix to the file/location in the gap's Location field.
+After each fix, make an atomic commit: fix(design-gap-GNN): [gap title].
+
+Context:
+  auto_mode: <true|false>
+
+Emit ## FIX COMPLETE when all in-scope gaps have been attempted (partial success is still ## FIX COMPLETE).
+Record any gap that could not be fixed via mcp__gdd_state__add_blocker with stage: "verify".
+""")
+
+Wait for `## FIX COMPLETE` in the agent response before continuing.
+
+After the design-fixer spawn returns `## FIX COMPLETE`, re-spawn design-verifier with `re_verify=true` and loop to Step 2:
+
+```
+Task("design-verifier", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-AUDIT.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+@.design/tasks/
+@reference/audit-scoring.md
+@reference/heuristics.md
+@reference/review-format.md
+@reference/accessibility.md
+</required_reading>
+
+You are the design-verifier agent. This is a re-verification run after inline fixes.
+
+DESIGN-AUDIT.md contains the retrospective 6-pillar audit from design-auditor (read as supplementary context).
+
+Context:
+  auto_mode: <true|false>
+  re_verify: true
+
+Focus verification on previously-failed must-haves first. Run full 5-phase pass.
+Write updated .design/DESIGN-VERIFICATION.md. Emit ## GAPS FOUND (if any), then ## VERIFICATION COMPLETE.
+""")
+```
+
+---
+
+## Stage exit
+
+1. Call `mcp__gdd_state__update_progress` with `task_progress: "<verified>/<total>"` (the total is `state.must_haves.length` from the entry snapshot; verified is the count set to `pass`) and `status: "verify_complete"`.
+2. Call `mcp__gdd_state__set_status` with one of:
+   - `status: "pipeline_complete"` — all must-haves passed and no outstanding gaps.
+   - `status: "verify_failed_requires_loop"` — gaps remain (save-and-exit, accept-as-is with fails, or auto-mode blocker).
+3. Call `mcp__gdd_state__checkpoint` — stamps `frontmatter.last_checkpoint` and appends a `verify_completed_at` timestamp entry. No direct STATE.md writes; the checkpoint tool owns the final persist.
+
+---
+
+## After Completion
+
+Print summary:
+
+```
+=== Verify complete ===
+Status: PASS | FAIL | ACCEPTED-WITH-GAPS
+Gaps:   X blockers, Y majors, Z minors, W cosmetics
+
+Agents run:
+  design-auditor              -> .design/DESIGN-AUDIT.md (6-pillar qualitative)
+  design-verifier-gate        -> JSON gate decision (may skip design-verifier)
+  design-verifier             -> .design/DESIGN-VERIFICATION.md (7-category + heuristics + UAT)
+  design-integration-checker-gate -> JSON gate decision (may skip design-integration-checker)
+  design-integration-checker  -> inline (D-XX decision wiring)
+
+Reports:
+  Qualitative audit: .design/DESIGN-AUDIT.md
+  Full verification: .design/DESIGN-VERIFICATION.md
+
+Next: [if pass] pipeline complete — run /get-design-done:discover for next session
+      [if fail] fix gaps and re-run /get-design-done:verify
+======================
+```

package/skills/warm-cache/SKILL.md

@@ -4,6 +4,7 @@ description: "Pre-warms Anthropic's 5-min prompt cache across all agents that im
 user-invocable: true
 argument-hint: "[--agents <comma-list>]"
 tools: Read, Bash, Grep
+disable-model-invocation: true
 ---
 
 # warm-cache
@@ -55,37 +56,7 @@ Print the markdown summary described in the Invocation Contract.
 
 ## Concrete Command Example
 
-```
-$ /gdd:warm-cache
-
-Warming Anthropic prompt cache for 14 agents (5 min TTL)...
-[1/14] design-verifier ... ok (0.3s)
-[2/14] design-planner ... ok (0.3s)
-[3/14] design-integration-checker ... ok (0.3s)
-...
-[14/14] design-reflector ... ok (0.3s)
-
-## Warm-cache complete
-- Agents warmed: 14
-- Skipped (no shared preamble import): 3  (agents/README.md not an agent; 2 agents not yet migrated to shared preamble)
-- Duration: 4.2s
-- Next 5 min: repeated spawns of these agents pay cached_input_per_1m rate
-```
-
-Filtered example:
-
-```
-$ /gdd:warm-cache --agents design-verifier,design-planner
-
-Warming Anthropic prompt cache for 2 agents (filtered from 14)...
-[1/2] design-verifier ... ok (0.3s)
-[2/2] design-planner ... ok (0.3s)
-
-## Warm-cache complete
-- Agents warmed: 2
-- Filtered out by --agents: 12
-- Duration: 0.7s
-```
+Full + filtered command-output examples live in `./../cache-manager/cache-policy.md#concrete-warm-cache-command-examples-layer-a` so this skill stays close to its step-by-step flow rather than its sample output.
 
 ## Integration Points
 
@@ -95,10 +66,7 @@ Warming Anthropic prompt cache for 2 agents (filtered from 14)...
 
 ## Cost Model
 
-- Each no-op Haiku ping: ~50 input tokens (shared preamble + "No-op warm: acknowledge..." system+user) + ~5 output tokens ("ok").
-- At Haiku rates (reference/model-prices.md): `(50 / 1e6) * 1.00 + (5 / 1e6) * 5.00 = $0.00005 + $0.000025 = $0.000075` per agent.
-- 14 agents × $0.000075 = **$0.00105** total for a full warm-cache invocation.
-- Payback: a single subsequent Opus spawn with 40k cached input tokens saves `(40000/1e6) * (15.00 - 1.50) = $0.54`. Warm-cache pays for itself ~500× over on the first repeated planner spawn.
+Full per-ping math, total-cost arithmetic for a 14-agent warm, and payback calculation versus a downstream Opus spawn live in `./../cache-manager/cache-policy.md#cost-model-layer-a`. Top-line: a full warm is ~$0.001 and pays back ~500× on the first repeated planner spawn.
 
 ## Failure Modes
 

package/skills/zoom-out/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: zoom-out
+description: "Asks the agent to go up a layer of abstraction and map the relevant modules and callers using the project's CONTEXT.md vocabulary. Use when the user is working in an unfamiliar area of code and needs orientation before deep work."
+disable-model-invocation: true
+argument-hint: "[scope]"
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Zoom Out
+
+**Role:** Give the user a map, not a fix.
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary (`CONTEXT.md`) vocabulary.
+
+When invoked, produce a one-screen map that names:
+
+1. **Modules in scope** — one-line description of each, using terms from `CONTEXT.md` (see `./../reference/context-md-format.md` for the schema). Do not invent terms.
+2. **Callers** — who calls these modules from elsewhere, with file paths.
+3. **Seams** — where data crosses module boundaries, named per `./../reference/architecture-vocabulary.md`.
+
+Do not propose fixes. Do not write code. The output is a map.
+
+If `CONTEXT.md` is absent, suggest `/gdd:discuss` to start one, but still produce the map using basenames and inferred terms.
+
+## ZOOM-OUT COMPLETE