Phase 2.5 — Redesign

Goal: better-looking, coherent UI with evidence, not vibes. Deterministic scripts do the checking; a design engine does the taste; a vision pass looks at the result. Everything is bounded so it cannot turn into an open-ended polish loop.

Read PIPELINE_STATUS.md §1-3 first (idea, stack, what was scaffolded). Read shared/references/note-style.md — every artifact this phase writes is note-form.

Step 0 — Preflight (three checks, in order)

node shared/scripts/setup_harness.cjs --check          # vision + screenshot plumbing
node 02b-redesign/scripts/design_context.cjs --root .  # routes, tokens, components map

3. Vision tier (details: references/vision-and-shots.md). In order of preference: A workflow vision child — agent(prompt, { provider: 'deepseek-official', model: 'deepseek-flash' }) — works with zero configuration; B the user switches with /model to DeepSeek-V4.1-Flash (the same model at the same price); C subagent-model-selection in settings.yaml + a new session; D blind mode — gates only, and say so plainly. Record the tier in vision_route.

Marker on (Tier-1 scope guard): create <project>/.dsh/state/redesign.active. Remove it in Step 6, always — a stale marker blocks legitimate Phase 2/4 work and install_scope_hook.cjs --check reports it after 24 h.

Step 1 — Pick the engine (never invent a design process)

Open impeccable's new-work.md (51 KB) or critique.md (42 KB) only when the user's request names a full redesign — the words "redesign"/"overhaul", or a named new visual world. Say what it costs before loading either. Tier 3 never freehands a substitute design process.

Installing impeccable into a project: it carries a 16.8 MB engine binary — make sure .dsh/ is git-ignored first, or install it at the user root. Refresh with npx impeccable update; record version + source in design_engine_version / design_engine_source.

Removed from this pipeline: ConardLi/garden-skills web-design-engineer — 35 KB always-loaded and three blocking "🛑 actually wait" checkpoints that stall an unattended run.

Step 2 — Run the engine, then the gate

Give the engine the real codebase and docs/design/DESIGN-NOTES.md, not a description. Free-only still applies (Google Fonts / Fontsource / system stacks satisfy any paid-font intent).

node 02b-redesign/scripts/design_gate.cjs --root .      # must be clean before any eye looks

The gate is exit-coded and finds the failures agent redesigns actually have: INLINE_COLOR (a raw hex outside the token block), UNDEFINED_TOKEN (var(--x) never defined), CONTRAST (a -foreground/background pair below 3:1, or below AA 4.5:1 for body text). Known-legitimate contexts (email HTML, OG images, next/font, Radix runtime variables) are ignored by default; extend with docs/design/gate-ignore.json, or --strict to see everything. A finding a script could catch belongs in this script — add it there and it is caught for free next time.

Also: bash 02b-redesign/scripts/check_redesign_scope.sh <branch> before any commit, and the Tier-1 hook (references/enforcement.md) if it is installed.

Step 3 — Look at it (bounded: 2 rounds maximum)

Screenshots at 1440x900 and 390x844, saved under docs/design/shots/ (git-ignored). Then one vision pass writes docs/design/REVIEW.md using the template in references/vision-and-shots.md: one finding per line, always file:line, always a concrete change. Fix everything in one batch, take one confirmation round, stop.

Cost discipline: 1024 tokens per image, always a cache miss ($0.00015) because a re-render is new bytes. Re-shoot only changed routes; never keep a growing gallery in context.

Step 4 — Accessibility and structure (free, deterministic)

lighthouse_audit (browser MCP) or the project's own a11y tooling, compared against the number recorded at the start of this phase — a redesign that lowers accessibility fails, whatever it looks like. The engine's own audit verb covers the same ground when impeccable is present.

Step 5 — Commit and record

• Work on a branch (redesign/<short>) whenever current_phase: live. Pre-launch, direct commits are fine, same as Phase 2.
• Separate commits for: structural/token changes, component restyling, content polish.
• PIPELINE_STATUS.md §3b: redesign_ran, direction, mode, engine + version + source, design_notes_path, review_path, shots_dir, vision_route, last_redesign_commit.
• Commit DESIGN-NOTES.md and REVIEW.md; never commit docs/design/shots/.
• Live app: push, CI green, user looks at the preview, then merge (Coolify deploys main).
• Pre-deploy: hand off to 03-deploy-vps/SKILL.md when the user is happy.

Step 6 — Cleanup, always

Delete the redesign marker. Run node shared/scripts/note_lint.cjs on the artifacts you wrote, then move to Phase 3 (or Phase 4's Steps 5-6 for a live app).

What this phase does NOT do

Doesn't touch backend logic, auth, the database, dependencies or CI — the scope guard and the hook enforce that, they do not merely advise it. Doesn't re-scope features Phase 2 disabled (re-enabling one is a Phase 2/4 decision with the user). Doesn't polish past round 2. Doesn't maintain its own copy of design recipes — that is the engine's job, and a local copy would drift.

Files in this phase

• references/vision-and-shots.md — vision tiers, screenshot policy, the bounded loop, REVIEW template
• references/enforcement.md — Tier-1 hook + Tier-2 script, and why prose isn't enough
• references/design-rules.md — the deterministic MUST/SHOULD/NEVER checklist (tier-3 fallback)
• scripts/design_context.cjs — routes/tokens/components → DESIGN-NOTES.md
• scripts/design_gate.cjs — inline colour / undefined token / contrast gate
• scripts/check_redesign_scope.sh — Tier-2 git-diff scope gate (reads scope-policy.json)
• scripts/scope-policy.json — the shared denylist both tiers read
• scripts/redesign_scope_hook.cjs + shared/scripts/install_scope_hook.cjs — Tier-1 hook and its installer