docs(01-04): finalize summary — DSGN-02 approved, plan complete (3/3)

- status banner: tasks 3/3; DSGN-02 APPROVED (verbatim 'approved', no fix list)
- requirements-completed: [DSGN-02] (REQUIREMENTS.md/STATE.md/ROADMAP.md marking
  deferred to the orchestrator per wave-parallel convention, matching 01-01/02/03)
- task 3 commits: f51e714 (approval record) + 7d6845a (gallery script wiring)
- deviation #4 documented: [Rule 1] broken root gallery delegate repaired
- duration 22min total; self-check PASSED (5 files, 7 commits, no deletions)

.planning/phases/01-design-tokens-rams-foundation/01-04-SUMMARY.md

@@ -18,6 +18,8 @@ provides:
   - "Playwright capture toolchain (D-14): theme/scripts/screenshot.mjs — real-browser captures of the sheet (390 fullPage), the 4 mockups via file:// (CDN network renders, committed screen.png fallback — mockups never edited, D-06), the basemap (READY-signal-gated); ≥10KB blank gate; wired as `npm run capture`"
   - "DSGN-02 approval gallery (D-12): theme/gallery.html — the mechanism template every later UI phase extends (4 mockup-vs-sheet comparison rows + basemap direction row + token ledger of 13 typography specimens + 6 hero color swatches, names only per D-07 + approval scope strip); CDN-free, tokens-only"
   - "6 regenerated captures under theme/screenshots/ (gitignored by policy): sheet-full.png, mockup-<screen>.png ×4, basemap-kl.png — all network renders, zero fallbacks needed"
+  - "DSGN-02 approval record: .planning/phases/01-design-tokens-rams-foundation/01-04-DSGN-02-APPROVAL.md — verbatim \"approved\" (2026-10-22T00:51:39Z), full provenance (reviewed URLs, approved artifact commits waves 1-3 + 01-04, capture manifest), evidence re-verified at record time; gate consequence: DSGN-02 PASSED for Phase 1"
+  - "One-command DSGN-02 review loop: `npm run gallery` (root delegate → theme) = build → capture → serve theme/ on :8123 — repairs the root delegate that had pointed at a missing theme script since wave 1 (01-01 contract: plan 04 wires the gallery slot)"
 affects: [every later UI phase (DSGN-02 gallery extension + `npm run audit`/`npm run capture` standing gates), 02-telegram-bot-worker (fidelity bar applies to bot-adjacent UI), 03-mini-app-shell, 05-guidance]
 
 # Tech tracking
@@ -36,8 +38,9 @@ key-files:
     - theme/scripts/audit.test.mjs
     - theme/scripts/screenshot.mjs
     - theme/gallery.html
+    - .planning/phases/01-design-tokens-rams-foundation/01-04-DSGN-02-APPROVAL.md (task 3 — DSGN-02 approval record)
   modified:
-    - theme/package.json (audit + capture + test scripts)
+    - theme/package.json (audit + capture + test + gallery scripts)
 
 key-decisions:
   - "Rendered-CSS audit scope (D-13's own words: 'scans rendered CSS/classes'): dist compiles the mockup vocabulary 1:1 per wave-1's @source requirement — including utilities the design doc REJECTS (shadow-*, blur, backdrop-blur, bg-[#…]). Auditing raw dist would flag reference vocabulary no implementation page wears; the audit therefore filters @layer utilities to classes harvested from implementation pages (registry: IMPLEMENTATION_PAGES in audit.mjs — later phases append) and audits everything else implementation-owned fully. A used off-token utility (T7) or shadow utility still flags — proven by tests"
@@ -52,24 +55,24 @@ patterns-established:
   - "Evidence gates as npm scripts: `npm run audit` (exit-code truth) + `npm run capture` (≥10KB blank gate) — CI-able in Phase 2's deploy pipeline (D-17)"
   - "Implementation pages registry (audit.mjs IMPLEMENTATION_PAGES) is the rendered-surface contract — every page that renders Rams components must be registered there"
 
-requirements-completed: [] # DSGN-02 pending — awaiting the blocking user-approval checkpoint (task 3); continuation records it on approval
+requirements-completed: [DSGN-02] # approved 2026-10-22 (task 3 checkpoint passed — record committed); REQUIREMENTS.md/STATE.md/ROADMAP.md marking deferred to the orchestrator (wave-parallel execution; DSGN-01 equally still unmarked on disk)
 
 # Metrics
-duration: 12min (pre-checkpoint; started 2026-10-22T00:20:01Z, artifacts done 00:32:00Z)
+duration: 22min total (12min pre-checkpoint 2026-10-22T00:20:01Z→00:32:00Z + ~10min continuation 00:45Z→00:56Z: approval record, gallery wiring, verification, summary)
 completed: 2026-10-22
 ---
 
 # Phase 01 Plan 04: Audit + Gallery + DSGN-02 Checkpoint Summary
 
-**Automated off-token audit as a rendered-CSS scanner with drift guards and evasion-proof checks (16/16 TDD green, real build `AUDIT CLEAN — 354 declarations, 0 off-token values`), a committed Playwright capture toolchain producing 6/6 non-blank real-browser captures, and the DSGN-02 side-by-side approval gallery (mockup-vs-sheet rows + basemap direction + names-only token ledger) — the fidelity gate now awaiting the user's approval verdict**
+**Automated off-token audit as a rendered-CSS scanner with drift guards and evasion-proof checks (16/16 TDD green, real build `AUDIT CLEAN — 354 declarations, 0 off-token values`), a committed Playwright capture toolchain producing 6/6 non-blank real-browser captures, the DSGN-02 side-by-side approval gallery (mockup-vs-sheet rows + basemap direction + names-only token ledger) — and the user's APPROVED verdict on both, recorded with full provenance as the Phase-1 fidelity gate**
 
-> **STATUS: tasks 1–2 complete and committed; task 3 (DSGN-02 approval checkpoint, blocking) PENDING the user's verdict — resume signal: "approved" or a fix list. No later-phase work may rely on DSGN-02 until then.**
+> **STATUS: COMPLETE — tasks 3/3. DSGN-02 APPROVED by the user on 2026-10-22 (verbatim "approved"; no fix list), recorded in `01-04-DSGN-02-APPROVAL.md` (commit `f51e714`). Evidence re-verified post-approval: AUDIT CLEAN, CAPTURE OK 6/6 — the approved capture set reproduced with sheet-full.png and basemap-kl.png byte-identical. Later UI phases may build on the approved fidelity bar; `npm run gallery` (wired this plan, `7d6845a`) is their review mechanism.**
 
 ## Performance
 
-- **Duration:** ~12 min pre-checkpoint (2026-10-22T00:20:01Z → 00:32:00Z)
+- **Duration:** ~22 min total (00:20:01Z → 00:32:00Z pre-checkpoint tasks 1–2; ~00:45Z → 00:56Z continuation: prior-work verification, approval record, gallery wiring, evidence re-runs, summary)
-- **Tasks:** 2/3 complete (task 3 = blocking checkpoint, pending user)
+- **Tasks:** 3/3 complete (task 3 checkpoint passed — user approved)
-- **Files:** 4 created, 1 modified (+ this SUMMARY)
+- **Files:** 5 created, 1 modified (+ this SUMMARY)
 
 ## Accomplishments
 
@@ -84,7 +87,7 @@ Each task was committed atomically (TDD tasks have RED/GREEN pairs):
 
 1. **task 1: Off-token audit script (D-13)** — `6a7c256` (test: RED, 13 failing checks) → `b39317d` (feat: GREEN, 13/13)
 2. **task 2: Playwright capture script + gallery page (D-14, D-12)** — `9ba73f2` (test: RED for the style-attr evasion hole found while building the gallery) → `0b3eebf` (feat: GREEN, audit surface extension) → `b462936` (feat: capture toolchain + gallery + audit registry)
-3. **task 3: DSGN-02 approval checkpoint** — blocking, PENDING user verdict (this report is the checkpoint delivery)
+3. **task 3: DSGN-02 approval checkpoint** — **PASSED**: user approved (verbatim "approved"; no fix list). `f51e714` (docs: DSGN-02 approval record — date, verbatim response, reviewed URLs, approved artifact commits, re-verified evidence, gate consequence) → `7d6845a` (fix: theme `gallery` script — post-approval wiring repairing the broken root delegate, the 01-01 contract's "plan 04 (gallery)" slot)
 
 **Plan metadata:** (see final commit below — docs: SUMMARY)
 
@@ -94,7 +97,8 @@ Each task was committed atomically (TDD tasks have RED/GREEN pairs):
 - `theme/scripts/audit.test.mjs` (233 lines) — TDD harness: 16 checks / 8 groups (clean/dirty/drift-colors/drift-radius/real-build/components-layer/used-utilities/style-attributes), fixtures under /tmp/opencode
 - `theme/scripts/screenshot.mjs` (191 lines) — D-14 capture tool: loopback static server (theme/ docroot, traversal-guarded), sheet/mockup/basemap captures, blank gate, screen.png fallback, per-capture log
 - `theme/gallery.html` (290 lines) — the DSGN-02 mechanism page (see Accomplishments)
-- `theme/package.json` — `"audit": "node ./scripts/audit.mjs ./dist/rams.css"`, `"capture": "node ./scripts/screenshot.mjs"`, `"test": "node ./scripts/audit.test.mjs"` (root delegates `audit`/`capture` verified resolving)
+- `theme/package.json` — `"audit": "node ./scripts/audit.mjs ./dist/rams.css"`, `"capture": "node ./scripts/screenshot.mjs"`, `"test": "node ./scripts/audit.test.mjs"`, and (continuation, task 3) `"gallery": "npm run build && npm run capture && echo 'DSGN-02 gallery serving: http://localhost:8123/gallery.html + /basemap/' && npm run basemap:preview"` (root delegates `audit`/`capture`/`gallery` verified resolving)
+- `.planning/phases/01-design-tokens-rams-foundation/01-04-DSGN-02-APPROVAL.md` (56 lines) — the DSGN-02 approval record: verbatim response, provenance, re-verified evidence, gate consequence
 - `theme/screenshots/*` — 6 regenerated captures, gitignored by policy (re-run `npm run capture` after fresh checkout)
 
 ## Decisions Made
@@ -104,6 +108,7 @@ Each task was committed atomically (TDD tasks have RED/GREEN pairs):
 - **Rendered-vs-vocabulary scope** — the plan's required behavior ("audit of theme/dist/rams.css (real build) → exit 0") collides with wave-1's own requirement that dist compile the mockup utility vocabulary 1:1 — which includes shadow/blur/glass/`bg-[#222222]` utilities the design doc rejects and the implementation never wears. D-13's own wording ("scans rendered CSS/classes") resolves it: the audit's unit of truth is what implementation pages render. Utilities-layer rules are audited exactly for harvested used classes; framework layers and `@property --tw-*` plumbing are skipped; everything implementation-owned is fully audited. Tests T5/T6/T7 lock all three behaviors.
 - **Circle primitive adjudication** (wave-1's deferred call) — `rounded-full` sanctioned only as the full-circle primitive for signets; the audit quotes the design doc's Shapes enumeration (rect families at absolute zero) in its header; 50%/9999px/any other non-zero radius stays a violation.
 - **Gallery serving** — the checkpoint how-to uses the workspace's existing preview server rather than `npx http-server` (equivalent docroot, one less ad-hoc package, D-17).
+- **Gallery script as the full review loop (continuation, task 3 wiring)** — `npm run gallery` chains build → capture → serve rather than serve-only: fresh-checkout-safe (dist/ + captures are regenerated artifacts — an unstyled-sheet capture would otherwise pass the ≥10KB blank gate silently), encodes the documented user-setup flow as one command, and matches 01-01's own anticipation ("run `npx playwright install` before capture/gallery"). Each link individually verified; the serve link is `basemap:preview` — proven live by the checkpoint server itself.
 
 ## Deviations from Plan
 
@@ -132,10 +137,18 @@ Each task was committed atomically (TDD tasks have RED/GREEN pairs):
 - **Files modified:** none
 - **Committed in:** n/a (checkpoint instructions)
 
+**4. [Rule 1 - Bug] Root `npm run gallery` delegate was broken — theme-side script never wired**
+- **Found during:** task 3 (post-approval wiring check, continuation session)
+- **Issue:** root `gallery` → `npm run gallery --workspace theme` failed with "Missing script: gallery" — 01-01 created the root delegate and explicitly assigned plan 04 the theme-side slot ("plan 04 (gallery/audit)"), but 01-04's tasks 1–2 wired only `audit`/`capture`/`test`
+- **Fix:** added theme `"gallery": "npm run build && npm run capture && echo '…' && npm run basemap:preview"` — the one-command DSGN-02 review loop; root delegate untouched (already correct)
+- **Files modified:** theme/package.json
+- **Verification:** JSON valid in both manifests; resolution listed from root + theme; build 114ms; CAPTURE OK 6/6 (approved capture set reproduced — sheet + basemap byte-identical, mockups ≤107B variance, zero fallbacks); AUDIT CLEAN; serve link live-proven (`:8123` serving gallery.html 200)
+- **Committed in:** `7d6845a`
+
 ---
 
-**Total deviations:** 3 auto-fixed (1 bug, 1 missing critical, 1 tooling)
+**Total deviations:** 4 auto-fixed (2 bugs, 1 missing critical, 1 tooling)
-**Impact on plan:** All fix-level; no scope changes. The style-attribute extension made the D-13 evidence strictly stronger than the plan's letter.
+**Impact on plan:** All fix-level; no scope changes. The style-attribute extension made the D-13 evidence strictly stronger than the plan's letter; the gallery-script repair closed the 01-01 contract's last open slot.
 
 ## Issues Encountered
 
@@ -153,19 +166,19 @@ None — no new trust surface beyond the plan's register: audit.mjs reads local
 
 ## User Setup Required
 
-None — no external service configuration. For the checkpoint the user only serves the workspace and opens two URLs (see checkpoint instructions): `npm run capture` (only needed after a fresh checkout — captures are gitignored regenerated artifacts) then `npm run basemap:preview --workspace theme` → http://localhost:8123/gallery.html and /basemap/.
+None — no external service configuration. Re-reviewing the gallery (any later phase) is now one command: `npm run gallery` (root) = build → capture → serve, then open http://localhost:8123/gallery.html and /basemap/. Captures regenerate automatically (fresh-checkout safe). The checkpoint itself required no user setup beyond the two URLs.
 
 ## Next Phase Readiness
 
-- **Task 3 (this plan):** the continuation agent records the user's DSGN-02 verdict (resume signal "approved" or fix list) in this SUMMARY + REQUIREMENTS; on fix-list, iterate sheet/gallery/basemap per the listed aspects and re-present
+- **Task 3: CLOSED — DSGN-02 APPROVED** (record: `01-04-DSGN-02-APPROVAL.md`, commit `f51e714`). No fix list; no aspects flagged for iteration. Product screens (Phase 2+) may build against the approved fidelity bar
-- **Every later UI phase:** extend theme/gallery.html (one comparison row per new product screen), append pages to audit.mjs IMPLEMENTATION_PAGES, run `npm run capture` + `npm run audit` as the standing DSGN-02/DSGN-01 gates; CI wiring lands with Phase 2's deploy pipeline (D-17)
+- **Every later UI phase:** extend theme/gallery.html (one comparison row per new product screen), append pages to audit.mjs IMPLEMENTATION_PAGES, then `npm run gallery` regenerates evidence and serves the review; `npm run audit` + `npm run capture` remain the standing DSGN-01/DSGN-02 gates; CI wiring lands with Phase 2's deploy pipeline (D-17)
-- **Fresh checkouts:** `npm run capture` regenerates theme/screenshots/ (gitignored); `npm run build --workspace theme` before audit
+- **Fresh checkouts:** `npm run gallery` does it all (build → capture → serve); `npm run build --workspace theme` before standalone `npm run audit`
-- STATE.md/ROADMAP.md updates deferred to the orchestrator (wave-parallel execution)
+- STATE.md/ROADMAP.md/REQUIREMENTS.md updates deferred to the orchestrator (wave-parallel execution — DSGN-01 remains "Pending" on disk for the same reason; this frontmatter's `requirements-completed` list is the durable record, matching plans 01-01/02/03's convention)
 
 ## Self-Check: PASSED
 
-All 4 created + 1 modified files exist; all 5 task commit hashes verified in git log (6a7c256, b39317d, 9ba73f2, 0b3eebf, b462936); must-have markers verified (gallery.html 290 lines ≥ 80 + `screenshots/` ×10; package.json `audit` wired; audit.mjs → `tokens.css` ×5 + `rams.css` ×3; screenshot.mjs → `screenshots` ×4); no stub markers in the new artifacts.
+All 5 created files exist (audit.mjs 583 · audit.test.mjs 233 · screenshot.mjs 191 · gallery.html 290 ≥ 80 · 01-04-DSGN-02-APPROVAL.md 56 lines); all 7 plan commit hashes verified in git log (6a7c256, b39317d, 9ba73f2, 0b3eebf, b462936, f51e714, 7d6845a); must-have markers verified (gallery.html `screenshots/` ×10; package.json `audit` + `gallery` wired; audit.mjs → `tokens.css`/`rams.css`; screenshot.mjs → `screenshots`); no deletions in any commit; working tree shows only this SUMMARY modified — STATE.md/ROADMAP.md/REQUIREMENTS.md untouched; no stub markers in the new artifacts.
 
 ---
 *Phase: 01-design-tokens-rams-foundation*
-*Completed: 2026-10-22 (tasks 1–2; DSGN-02 checkpoint pending)*
+*Completed: 2026-10-22 (3/3 tasks; DSGN-02 approved and recorded — 01-04-DSGN-02-APPROVAL.md, commit f51e714)*