@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/check-update/SKILL.md

@@ -7,91 +7,69 @@ tools: Read, Write, Bash, Task
 
 # /gdd:check-update
 
-**Role:** Manual entry point for the plugin-update checker. The SessionStart hook (`hooks/update-check.sh`) already runs on its own 24h cadence and writes `.design/update-cache.json` + `.design/update-available.md`. This command lets the user inspect / force / dismiss / enrich that state on demand.
+**Role:** Manual entry point for the plugin-update checker. The SessionStart hook (`hooks/update-check.sh`) already runs on its own 24h cadence and writes `.design/update-cache.json` + `.design/update-available.md`. This command lets the user inspect / force / dismiss / enrich that state on demand. See `./reference/heuristics.md` §"Version-cadence" for the off-cadence / preview-suffix handling background.
 
 ## Flags
 
 | Flag | Effect |
-|---|---|
-| *(none)* | Print cached state (latest_tag, delta, is_newer). If the cache is older than 24h, trigger `--refresh` implicitly. |
+|------|--------|
+| *(none)* | Print cached state. If cache is older than 24h, trigger `--refresh` implicitly. |
 | `--refresh` | Invoke `hooks/update-check.sh --refresh` — bypasses the 24h TTL and re-fetches immediately. |
 | `--dismiss` | Write `update_dismissed: "<latest_tag>"` to `.design/config.json` atomically and delete `.design/update-available.md`. Sticky until a newer release ships. |
 | `--prompt` | Spawn `design-update-checker` agent (Haiku) to produce a 3–5-line "what this release changes for you" summary. Does not alter the banner or cache. |
 
-Flags can be combined: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss` is the only flag that mutates `.design/config.json`.
+Flags combine: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss` is the only flag that mutates `.design/config.json`.
 
 ## Steps
 
-1. **Parse flags.** Detect `--refresh`, `--dismiss`, `--prompt` in `$ARGUMENTS`. Any unknown flag: print `Unknown flag: <flag>` and exit.
+1. **Parse flags.** Detect `--refresh`, `--dismiss`, `--prompt` in `$ARGUMENTS`. Unknown flag → `Unknown flag: <flag>` and exit.
+
+2. **`--refresh` path** (if set):
 
-2. **--refresh path** (if `--refresh` in flags):
-    Run the hot-path hook with the refresh flag:
     ```bash
     bash "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/hooks/update-check.sh" --refresh
     ```
-    This re-fetches `/releases/latest`, rewrites `.design/update-cache.json`, and re-renders `.design/update-available.md` subject to the same state/dismissal gates.
 
-3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If it does not exist:
-    - Print: `No cache. Network may be unreachable or the hook has not run yet. Try /gdd:check-update --refresh.`
-    - Exit.
+    This re-fetches `/releases/latest`, rewrites `.design/update-cache.json`, and re-renders `.design/update-available.md` subject to state/dismissal gates.
 
-<!-- markdownlint-disable MD025 -->
+3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If missing: print `No cache. Network may be unreachable or the hook has not run yet. Try /gdd:check-update --refresh.` and exit.
 
-4. **Dismiss path** (if `--dismiss` in flags):
-    Compute new config contents and write atomically. The python heredoc receives CONFIG_PATH and LATEST_TAG via the ENVIRONMENT (env-prefix form — `KEY=VALUE python3 <<PY`), NOT via trailing argv. Passing `python3 -c '...' KEY=VALUE` makes Python treat the assignments as `sys.argv`, which the old draft did incorrectly; env-prefix form is the portable fix.
+4. **`--dismiss` path** (if set): Compute new config contents and write atomically via the env-prefix Python heredoc pattern below. The pattern is load-bearing — passing variables as trailing `KEY=VALUE` argv treats them as `sys.argv`, not `os.environ`. Use env-prefix form only.
 
     ```bash
     CONFIG_PATH=".design/config.json"
     LATEST_TAG="$(grep -E '"latest_tag"' .design/update-cache.json | head -n1 | sed -E 's/.*"latest_tag"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
     [ -n "$LATEST_TAG" ] || { echo 'No latest_tag in cache — nothing to dismiss.'; exit 0; }
-
     mkdir -p .design
-
-    # Env-prefix form: CONFIG_PATH and LATEST_TAG are placed into the child process env,
-    # then python3 reads them via os.environ. Heredoc body is flat at column 0 (required —
-    # any leading indentation breaks Python parsing in a heredoc).
     CONFIG_PATH="$CONFIG_PATH" LATEST_TAG="$LATEST_TAG" python3 <<'PY'
-import json, os, sys, tempfile
-
-config_path = os.environ['CONFIG_PATH']
-latest_tag = os.environ['LATEST_TAG']
-
-# Load existing config if present; otherwise start fresh. Preserve every unknown key.
-try:
-    with open(config_path, 'r', encoding='utf-8') as f:
-        data = json.load(f)
-    if not isinstance(data, dict):
-        data = {}
-except (FileNotFoundError, json.JSONDecodeError):
-    data = {}
-
-# Set ONLY the dismissal key — every other pre-existing key is preserved verbatim.
-data['update_dismissed'] = latest_tag
-
-# Atomic write: write to tmp on the SAME filesystem, then os.replace() (POSIX rename(2)).
-target_dir = os.path.dirname(config_path) or '.'
-fd, tmp_path = tempfile.mkstemp(prefix='config.', suffix='.tmp', dir=target_dir)
-try:
-    with os.fdopen(fd, 'w', encoding='utf-8') as f:
-        json.dump(data, f, indent=2)
-        f.write('\n')
-    os.replace(tmp_path, config_path)  # atomic on same filesystem
-except Exception as exc:
+    import json, os, sys, tempfile
+    config_path = os.environ['CONFIG_PATH']
+    latest_tag = os.environ['LATEST_TAG']
     try:
-        os.unlink(tmp_path)
-    except OSError:
-        pass
-    sys.exit(1)
-PY
-
-    # Remove the rendered banner (user dismissed — stop showing it until a newer release ships).
+        with open(config_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        if not isinstance(data, dict): data = {}
+    except (FileNotFoundError, json.JSONDecodeError): data = {}
+    data['update_dismissed'] = latest_tag
+    target_dir = os.path.dirname(config_path) or '.'
+    fd, tmp_path = tempfile.mkstemp(prefix='config.', suffix='.tmp', dir=target_dir)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2); f.write('\n')
+        os.replace(tmp_path, config_path)
+    except Exception:
+        try: os.unlink(tmp_path)
+        except OSError: pass
+        sys.exit(1)
+    PY
     rm -f .design/update-available.md
     echo "Dismissed $LATEST_TAG. The nudge will return when a newer release ships."
     ```
 
-    D-14 atomic-write invariant: `os.replace()` (POSIX `rename(2)`) is atomic on the same filesystem — an interrupted write leaves the original config intact. The `json.load → set single key → json.dump` round-trip guarantees every unknown top-level key (e.g. `model_profile`, `parallelism`) is preserved verbatim.
+    D-14 atomic-write invariant: `os.replace()` (POSIX `rename(2)`) is atomic on the same filesystem. The `json.load → set single key → json.dump` round-trip preserves every unknown top-level key (e.g. `model_profile`, `parallelism`) verbatim.
+
+5. **Print default state** (always, unless exited early):
 
-5. **Print default state** (always, unless the skill exited early):
     ```
     ━━━ /gdd:check-update ━━━
     Current:   v<X.Y.Z>
@@ -101,35 +79,20 @@ PY
     Dismissed: <tag or "no">
     ━━━━━━━━━━━━━━━━━━━━━━━━━━
     ```
-    Parse these fields from `.design/update-cache.json` using `grep + sed` (no jq dependency). Read dismissal from `.design/config.json` via the same pattern as hooks/update-check.sh:
-    ```bash
-    [ -f .design/config.json ] && grep -E '"update_dismissed"' .design/config.json | sed -E 's/.*"update_dismissed"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/'
-    ```
-
-6. **--prompt path** (if `--prompt` in flags):
-    Spawn the `design-update-checker` agent via the Task tool. Pass as context:
-    - `current_tag` — from `.design/update-cache.json`
-    - `latest_tag` — from `.design/update-cache.json`
-    - `delta` — from `.design/update-cache.json`
-    - `release_body` — the `changelog_excerpt` from the cache (may be pre-truncated to 500 chars; that's fine — the agent knows)
 
-    Display the agent's inline response verbatim below the state banner. The agent ends with `## UPDATE-CHECKER COMPLETE` — the skill's own completion marker (below) is the final line.
+    Parse fields from `.design/update-cache.json` via `grep + sed` (no jq dep). Read dismissal from `.design/config.json` via the same pattern as `hooks/update-check.sh`.
 
-## Defaults
-
-- No flags → behave as: `--refresh (only if cache >24h old) → print state`. Silent no-op if cache is fresh and there is no newer version.
+6. **`--prompt` path** (if set): Spawn `design-update-checker` via Task tool with context `{current_tag, latest_tag, delta, release_body}`. Display response verbatim below the banner. Agent ends with `## UPDATE-CHECKER COMPLETE`.
 
 ## Do Not
 
-- Do not fetch from GitHub in this skill directly — always go through `hooks/update-check.sh --refresh` so the caching + state-guard + dismissal logic stays in one place.
-- Do not modify `.design/update-available.md` except to delete it on `--dismiss`. The hot-path hook is the only writer of that banner (D-06).
-- Do not rewrite `.design/config.json` wholesale — the atomic python rewrite preserves every unknown key (D-14).
-- Do not pass variables to the python heredoc via trailing `KEY=VALUE` argv — that assigns to `sys.argv`, not `os.environ`. Use env-prefix form only.
+- Do not fetch from GitHub directly — always go through `hooks/update-check.sh --refresh` so caching + state-guard + dismissal logic stays in one place.
+- Do not modify `.design/update-available.md` except to delete on `--dismiss`.
+- Do not rewrite `.design/config.json` wholesale — the atomic Python rewrite preserves every unknown key (D-14).
+- Do not pass variables to the Python heredoc via trailing `KEY=VALUE` argv — env-prefix form only.
 
 ## Completion marker
 
-Last line of output:
-
 ```
 ## CHECK-UPDATE COMPLETE
 ```

package/skills/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-design-done:compare
-description: "Compute delta between DESIGN.md baseline (from scan) and DESIGN-VERIFICATION.md result (from verify). Reports per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in DESIGN-PLAN.md). Writes .design/COMPARE-REPORT.md."
+description: "Compute the delta between the `DESIGN.md` baseline (from scan) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`."
 argument-hint: ""
 user-invocable: true
 ---
@@ -9,6 +9,8 @@ user-invocable: true
 
 Standalone delta command. Computes the difference between the scan baseline (`DESIGN.md`) and the verification result (`DESIGN-VERIFICATION.md`), and flags design drift for any regression not covered by an explicit task in `DESIGN-PLAN.md`. Writes one artifact: `.design/COMPARE-REPORT.md`.
 
+For the full step-by-step methodology (score parsing, set arithmetic for anti-patterns, drift-coverage map, screenshot-delta probe, and `COMPARE-REPORT.md` template), see `./compare-rubric.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list, connection-probe pattern), see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`. For the underlying 0–10 category-scoring rubric the delta is computed against, see `../../reference/audit-scoring.md`.
+
 ---
 
 ## Scope
@@ -19,7 +21,7 @@ This command is **standalone** — not a pipeline stage:
 - Does NOT require or implement a snapshot mechanism — multi-run history is deferred to V2-06.
 - Does NOT mutate any pipeline artifact (`DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `.design/STATE.md`).
 - Writes exactly ONE file: `.design/COMPARE-REPORT.md`.
-- Output artifact prefix is `COMPARE-REPORT` — distinct from the pipeline namespace (`DESIGN-*.md`). No naming conflict.
+- Output artifact prefix `COMPARE-REPORT` is distinct from the pipeline namespace (`DESIGN-*.md`). No naming conflict.
 
 ---
 
@@ -27,282 +29,43 @@ This command is **standalone** — not a pipeline stage:
 
 Required files — abort if either is missing:
 
-```
-.design/DESIGN.md              — baseline from scan
-.design/DESIGN-VERIFICATION.md — result from verify
-```
-
-**Abort conditions:**
-
-- If `.design/DESIGN.md` is missing:
-  > "No baseline found. Run /get-design-done scan first."
-
-- If `.design/DESIGN-VERIFICATION.md` is missing:
-  > "No verification result found. Run /get-design-done verify first to produce DESIGN-VERIFICATION.md."
-
-**Optional files** (graceful degradation if absent):
-
-- `.design/DESIGN-CONTEXT.md` — used for must-have delta (COMP-03). If missing, skip the Must-Have Status section and emit note: "Must-have delta skipped: DESIGN-CONTEXT.md not found."
-- `.design/DESIGN-PLAN.md` — used for drift detection (COMP-04). If missing, skip DRIFT flagging and emit note: "Drift detection skipped: no DESIGN-PLAN.md."
-
-Confirm `.design/` directory exists. If absent, create it: `mkdir -p .design/`
-
-### Probe Preview connection
-
-Run at stage entry, after pre-flight checks:
-
-```
-Step P1 — ToolSearch check:
-  ToolSearch({ query: "Claude_Preview", max_results: 5 })
-  → Empty result      → preview: not_configured  (skip Screenshot Delta section)
-  → Non-empty result  → proceed to Step P2
-
-Step P2 — Live tool call:
-  call mcp__Claude_Preview__preview_list
-  → Success           → preview: available
-  → Error             → preview: unavailable
-
-Write preview status to .design/STATE.md <connections>.
-```
-
----
-
-## Step 1: Parse Category Scores
-
-**Extract baseline scores from `.design/DESIGN.md`:**
-
-Locate the category score table. Expected format:
-
-```
-| Category | Score | Notes |
-|----------|-------|-------|
-| Accessibility | 6/10 | ... |
-```
-
-Parse each row: extract category name and numeric score (e.g., `6` from `6/10`).
-
-Store as `baseline_scores` map: `{ "Accessibility": 6, "Visual Hierarchy": 5, ... }`
-
-**Extract result scores from `.design/DESIGN-VERIFICATION.md`:**
-
-Locate the category score table in the Phase 1 output section. Same format as above.
-
-Store as `result_scores` map: `{ "Accessibility": 8, "Visual Hierarchy": 6, ... }`
-
-**Normalize category names:**
-- Strip leading/trailing whitespace
-- Apply title-case normalization (e.g., `anti-patterns` → `Anti-Patterns`)
-- Match categories case-insensitively between the two tables
-
-**Unmatched categories:**
-- If a category appears in `DESIGN.md` but not `DESIGN-VERIFICATION.md` → flag as `[UNMATCHED-BASELINE]` and exclude from score delta
-- If a category appears in `DESIGN-VERIFICATION.md` but not `DESIGN.md` → flag as `[UNMATCHED-RESULT]` and exclude from score delta
-- Report all unmatched categories in the Notes section of `COMPARE-REPORT.md`
-- Do NOT silently paper over category name mismatches
-
----
-
-## Step 2: Compute Score Delta (COMP-03)
-
-For each matched category:
-
-```
-delta = result_scores[category] - baseline_scores[category]
-```
-
-Classify each delta:
-- `improvement` — delta > 0
-- `no_change` — delta == 0
-- `regression` — delta < 0
-
-Record per category:
-- `category` — name
-- `baseline` — numeric score from DESIGN.md
-- `result` — numeric score from DESIGN-VERIFICATION.md
-- `delta` — signed integer
-- `classification` — improvement / no_change / regression
-
-Collect all regressed categories for drift detection in Step 5.
-
----
-
-## Step 3: Anti-Pattern Delta (COMP-03)
-
-**Enumerate anti-patterns in DESIGN.md (baseline):**
-
-Scan for entries identified by BAN-*, SLOP-*, or labeled as anti-patterns in DESIGN.md. Collect identifiers or descriptions as `baseline_anti_patterns` set.
-
-**Enumerate anti-patterns in DESIGN-VERIFICATION.md (result):**
-
-Same scan against DESIGN-VERIFICATION.md. Collect as `result_anti_patterns` set.
-
-**Compute delta:**
-
-```
-resolved  = baseline_anti_patterns - result_anti_patterns
-           (present in baseline, absent in result — fixed)
-
-new       = result_anti_patterns - baseline_anti_patterns
-           (absent in baseline, present in result — introduced)
+- `.design/DESIGN.md` missing → `"No baseline found. Run /get-design-done scan first."`
+- `.design/DESIGN-VERIFICATION.md` missing → `"No verification result found. Run /get-design-done verify first to produce DESIGN-VERIFICATION.md."`
 
-unchanged = intersection of both sets
-           (still present in both)
-```
-
-Report all three groups.
-
----
-
-## Step 4: Must-Have Pass/Fail Change (COMP-03)
-
-**Skip condition:** If `.design/DESIGN-CONTEXT.md` is absent → emit note and skip this section.
-
-**Extract must-haves:**
-- Read `.design/DESIGN-CONTEXT.md` `<must_haves>` section
-- Enumerate each declared must-have (ID + description)
-
-**Read pass/fail status from DESIGN-VERIFICATION.md:**
-- Locate the must-have status table in the verification output
-- For each must-have: record status as `pass`, `fail`, or `not-evaluated`
-
-**Report:**
-- Each must-have's current status (pass | fail | not-evaluated)
-- If DESIGN.md contained a must-have status section from a prior verify, compute change (pass→fail, fail→pass); otherwise report current status only
-
----
-
-## Step 5: Design Drift Detection (COMP-04)
-
-**Skip condition:** If `.design/DESIGN-PLAN.md` is absent → emit note: "Drift detection skipped: DESIGN-PLAN.md not found."
-
-**Coverage map:**
-
-Read `.design/DESIGN-PLAN.md` and extract the `Type:` field from each task entry. Build a coverage map of which design categories have at least one task of matching type:
-
-```
-Example: Type: accessibility → covers "Accessibility" category
-         Type: color         → covers "Color" category
-         Type: typography    → covers "Typography" category
-```
-
-Category-to-Type matching is case-insensitive and normalized (e.g., `visual-hierarchy` matches `Visual Hierarchy`).
-
-**Drift check:**
-
-For each category classified as `regression` in Step 2:
-
-```
-If category NOT in coverage_map:
-  → flag: DRIFT: [category] regressed from <baseline> to <result> without a design task of Type:<category>
-```
-
-If all regressed categories are covered by tasks → emit: "No drift detected. All regressed categories are covered by tasks in DESIGN-PLAN.md."
-
-If no regressions in Step 2 → emit: "No drift detected. No score regressions found."
+**Optional files (graceful degradation if absent):**
 
----
-
-## Step 5B: Screenshot Delta (when preview: available)
-
-Check `preview` status from STATE.md `<connections>` (written by the probe at stage entry).
-
-**If `preview: available`:**
+- `.design/DESIGN-CONTEXT.md` — used for must-have delta. If missing, skip the Must-Have Status section and emit note: `"Must-have delta skipped: DESIGN-CONTEXT.md not found."`
+- `.design/DESIGN-PLAN.md` — used for drift detection. If missing, skip DRIFT flagging and emit note: `"Drift detection skipped: no DESIGN-PLAN.md."`
 
-1. Call `preview_start` if no session is already running.
-2. For each route inferred from DESIGN-PLAN.md tasks or `src/app/` / `src/pages/` file structure:
-   a. `preview_navigate` to route URL (e.g., `http://localhost:3000/<route>`)
-   b. `preview_screenshot` → save to `.design/screenshots/before/<route>.png` (pre-design baseline — only if a prior run's screenshot exists at this path) and `.design/screenshots/after/<route>.png` (current render)
-   c. Record the reference path (NOT base64) for embedding in `## Screenshot Delta` section of COMPARE-REPORT.md
-3. Call `preview_stop` when all routes are captured.
+Confirm `.design/` directory exists. If absent: `mkdir -p .design/`.
 
-**If `preview: unavailable` or `preview: not_configured`:**
-
-Emit exactly: `Screenshot delta skipped — preview not configured.` in the `## Screenshot Delta` section of COMPARE-REPORT.md.
+Probe `preview` connection per `../../reference/shared-preamble.md#connection-handshake-summary` (ToolSearch → live call → STATE.md write). Result drives Step 5B (screenshot delta).
 
 ---
 
-## Step 6: Write COMPARE-REPORT.md (COMP-05)
-
-Output path: `.design/COMPARE-REPORT.md`
-
-This file MUST NOT be written to any of the pipeline-reserved paths (`DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`).
-
-**Report structure:**
-
-```markdown
-# Compare Report: Baseline vs Result
-
-**Generated:** <ISO 8601 date>
-**Baseline:** .design/DESIGN.md
-**Result:** .design/DESIGN-VERIFICATION.md
-
-## Score Delta by Category
-
-| Category | Baseline | Result | Delta | Status |
-|----------|----------|--------|-------|--------|
-| Accessibility | 6 | 8 | +2 | improvement |
-| Visual Hierarchy | 5 | 5 | 0 | no_change |
-| Anti-Patterns | 4 | 3 | -1 | regression |
-| ... | ... | ... | ... | ... |
-
-## Anti-Pattern Delta
+## Workflow
 
-**Resolved** (present in baseline, absent in result):
-- <anti-pattern id or description>
-
-**New** (absent in baseline, present in result):
-- <anti-pattern id or description>
-
-**Unchanged:**
-- <anti-pattern id or description>
-
-## Must-Have Status
-
-| Must-Have | Status |
-|-----------|--------|
-| <id / description> | pass |
-| <id / description> | fail |
-| <id / description> | not-evaluated |
-
-## Design Drift
-
-<One of the following:>
-- "No drift detected. No score regressions found."
-- "No drift detected. All regressed categories are covered by tasks in DESIGN-PLAN.md."
-- "DRIFT: [Category] regressed from <baseline> to <result> without a design task of Type:<category>"
-- "Drift detection skipped: DESIGN-PLAN.md not found."
-
-## Screenshot Delta
-
-<One of the following:>
-- Per-route screenshot pairs (when preview: available): reference paths to .design/screenshots/before/<route>.png and .design/screenshots/after/<route>.png
-- "Screenshot delta skipped — preview not configured."
-
-## Notes
-
-Scope: delta between two existing artifacts (.design/DESIGN.md → .design/DESIGN-VERIFICATION.md).
-No snapshot mechanism — multi-snapshot compare deferred to V2-06.
-This report does not modify DESIGN.md, DESIGN-VERIFICATION.md, or any other pipeline artifact.
-<List any UNMATCHED-BASELINE or UNMATCHED-RESULT categories here, if any.>
-<If must-have section was skipped: "Must-have delta skipped: DESIGN-CONTEXT.md not found.">
-<If drift detection was skipped: "Drift detection skipped: DESIGN-PLAN.md not found.">
-```
-
-If a section has no items (e.g., no anti-patterns in baseline), write "None."
+1. **Parse Category Scores** — extract baseline + result score tables, normalize names, flag unmatched. Detail: `./compare-rubric.md#step-1--parse-category-scores`.
+2. **Compute Score Delta** — `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `./compare-rubric.md#step-2--compute-score-delta-comp-03`.
+3. **Anti-Pattern Delta** — set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `./compare-rubric.md#step-3--anti-pattern-delta`.
+4. **Must-Have Pass/Fail Change** — read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `./compare-rubric.md#step-4--must-have-passfail-change`.
+5. **Design Drift Detection (COMP-04)** — build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `./compare-rubric.md#step-5--design-drift-detection-comp-04`.
+6. **Screenshot Delta (preview: available only)** — capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `./compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
+7. **Write `.design/COMPARE-REPORT.md`** — full template at `./compare-rubric.md#step-6--compare-reportmd-template`.
 
 ---
 
 ## Constraints
 
-This command MUST NOT:
+This command MUST NOT (per `../../reference/shared-preamble.md#output-contract-reminders`):
+
+- Write to `DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, or `.design/STATE.md`.
+- Require or implement a snapshot system (V2-06 deferred).
+- Reinterpret or silently normalize category names that do not match between files — report mismatches in the Notes section.
+- Invoke `design-auditor` or any other pipeline agent.
+- Produce more than one output file: `.design/COMPARE-REPORT.md`.
 
-- MUST NOT write to `DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, or `.design/STATE.md`
-- MUST NOT require or implement a snapshot system (V2-06 deferred)
-- MUST abort with a clear actionable error message if `DESIGN-VERIFICATION.md` is missing (Pitfall 3)
-- MUST abort with a clear actionable error message if `DESIGN.md` (baseline) is missing
-- MUST produce exactly one output file: `.design/COMPARE-REPORT.md`
-- MUST NOT reinterpret or silently normalize category names that do not match between files — report mismatches explicitly in the Notes section
-- MUST NOT invoke design-auditor or any other pipeline agent
+Must abort with a clear actionable error message if either input file (`DESIGN.md` baseline, `DESIGN-VERIFICATION.md` result) is missing.
 
 ---
 
@@ -314,9 +77,6 @@ After writing `.design/COMPARE-REPORT.md`, print a summary:
 Compare complete. Improvements: N. Regressions: M. Drift flags: K. See .design/COMPARE-REPORT.md.
 ```
 
-Where:
-- `N` = count of categories classified as `improvement`
-- `M` = count of categories classified as `regression`
-- `K` = count of DRIFT flags emitted (0 if drift detection was skipped or no regressions)
+Where `N` = improvement count, `M` = regression count, `K` = DRIFT-flag count (0 if drift detection was skipped or no regressions). Do not summarize individual issues — the file contains the full detail.
 
-Do not summarize individual issues in the completion message — the file contains the full detail.
+## COMPARE COMPLETE