diff --git a/.planning/phases/01-design-tokens-rams-foundation/01-04-SUMMARY.md b/.planning/phases/01-design-tokens-rams-foundation/01-04-SUMMARY.md index a43ef43..05a5642 100644 --- a/.planning/phases/01-design-tokens-rams-foundation/01-04-SUMMARY.md +++ b/.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-.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) -- **Tasks:** 2/3 complete (task 3 = blocking checkpoint, pending user) -- **Files:** 4 created, 1 modified (+ this SUMMARY) +- **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:** 3/3 complete (task 3 checkpoint passed — user approved) +- **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) -**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. +**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; 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 -- **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) -- **Fresh checkouts:** `npm run capture` regenerates theme/screenshots/ (gitignored); `npm run build --workspace theme` before audit -- STATE.md/ROADMAP.md updates deferred to the orchestrator (wave-parallel execution) +- **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, 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 gallery` does it all (build → capture → serve); `npm run build --workspace theme` before standalone `npm run audit` +- 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)*