viepilot 2.23.0 → 2.45.2

package/workflows/crystallize.md

@@ -33,6 +33,100 @@ Use `COMMUNICATION_LANG` for all prompts and confirmation messages in this sessi
 If `~/.viepilot/config.json` is absent, use defaults (en/en) — do not fail.
 </step>
 
+<step name="upgrade_rescan">
+## Step 0-B: Upgrade Re-scan Mode (ENH-067)
+
+**Activated by:** `--upgrade` flag OR auto-detect (see below).
+
+### Auto-detect trigger
+
+1. Read `.viepilot/PROJECT-CONTEXT.md` first line → extract `<!-- crystallize_version: {semver} -->`.
+2. Fallback: read `.viepilot/HANDOFF.json` → `crystallize_version` field.
+3. If neither is present: treat as `crystallize_version = "0.0.0"` (legacy project, never stamped).
+4. Compare against current ViePilot version (`node bin/vp-tools.cjs info` → `version`).
+5. **If `crystallize_version` < current version AND gaps exist (see below): activate upgrade mode.**
+6. If `--upgrade` flag is explicitly passed: always activate, even if no gaps detected (allows forced re-scan).
+
+### Delta computation — version threshold table
+
+| Introduced in | Missing artifact section | Detection check |
+|--------------|--------------------------|-----------------|
+| v2.32.0 | `## Admin & Governance` in PROJECT-CONTEXT.md | section absent AND `admin_imported` not in HANDOFF.json |
+| v2.33.0 | `## Content Management` in PROJECT-CONTEXT.md | section absent AND `content_imported` not in HANDOFF.json |
+| v2.34.0 | `## User Data Management` in PROJECT-CONTEXT.md | section absent AND `user_data_imported` not in HANDOFF.json |
+
+Cross-check: confirm section is actually absent from current `PROJECT-CONTEXT.md` before listing
+as a gap — avoids false positives for projects that have the content already.
+
+### Upgrade menu
+
+**Claude Code (terminal) — REQUIRED:**
+```
+question: "🔄 Crystallize upgrade available (v{old} → v{new}).\nDetected gaps: {comma-separated list}.\nHow would you like to proceed?"
+header: "Upgrade"
+options:
+  - label: "Patch — append missing sections (Recommended)"
+    description: "Non-destructive: reads architect notes.md YAML → appends missing sections only; re-stamps crystallize_version"
+  - label: "Full re-generate"
+    description: "Backup .viepilot/ to .viepilot/backup-pre-regen-{timestamp}/ then regenerate all artifacts from scratch"
+  - label: "Skip"
+    description: "Proceed with current artifacts; skip upgrade for now"
+```
+
+**Text fallback (Cursor / Codex / other):**
+```
+🔄 Crystallize upgrade available (v{old} → v{new})
+Gaps: {list}
+
+1. Patch — append missing sections only (Recommended)
+2. Full re-generate (backup first)
+3. Skip
+```
+
+### Patch mode
+
+For each missing section, run only the corresponding Step 1D export item:
+- `## Admin & Governance` → Step 1D item 7 (ENH-063)
+- `## Content Management` → Step 1D item 8 (ENH-065)
+- `## User Data Management` → Step 1D item 9 (ENH-066)
+
+For each item:
+1. Check if architect `notes.md` has the corresponding YAML section (`## admin`, `## content`,
+   `## user_data`). If missing: soft warn —
+   > ⚠️ `notes.md ## {section}` not found — appending placeholder table instead.
+   Non-blocking: append the placeholder table from `templates/project/PROJECT-CONTEXT.md`.
+2. Check if latest brainstorm session has `## Upgrade supplement` with the relevant topic Q&A.
+   If yes: fold supplement content into the export (treat as first-class session data).
+3. Append section to `.viepilot/PROJECT-CONTEXT.md` (never overwrite existing content).
+4. After all missing sections appended: update `<!-- crystallize_version: {new} -->` comment.
+5. Update `crystallize_version` in `.viepilot/HANDOFF.json`.
+6. Commit: `chore: crystallize patch v{old} → v{new} (ENH-067)`
+
+**Brainstorm supplement check (for both Patch and Full re-generate):**
+Before extracting, check if the latest brainstorm session has pending `## Upgrade supplement`
+sections that haven't been incorporated yet. If brainstorm `upgrade_supplement_version < current`
+but supplement Q&A is present: include it automatically. If supplement Q&A is absent but gaps
+exist in brainstorm coverage: soft warn —
+> ⚠️ Brainstorm session missing Topic {N} coverage — run `/vp-brainstorm --continue` first
+> to fill gaps before crystallizing. Proceeding with placeholder tables.
+Non-blocking.
+
+### Full re-generate mode
+
+1. **Backup:** `cp -r .viepilot/ .viepilot/backup-pre-regen-{timestamp}/` — preserve existing artifacts
+2. **Pre-fill Step 0 metadata** from existing `.viepilot/PROJECT-META.md` (skip interactive Q&A for fields
+   that already have values — only ask about changed or missing fields)
+3. **Run full crystallize flow** from Step 0 onward using existing brainstorm session(s) + architect
+   artifacts as source
+4. Overwrite all `.viepilot/` artifacts (backup already taken in step 1)
+5. Commit: `chore: crystallize full re-generate v{old} → v{new} (ENH-067)`
+
+### Skip
+
+Proceed to Step 0 (Collect Project Metadata) as a normal crystallize run.
+`crystallize_version` is NOT updated until a successful patch or re-generate.
+</step>
+
 <step name="collect_metadata">
 ## Step 0: Collect Project Metadata
 
@@ -813,6 +907,20 @@ When `IS_BROWNFIELD=true`, the following table governs which steps execute:
 </step>
 
 <step name="analyze_brainstorm">
+## Step 0C: Persona output_style adaptation (ENH-073)
+
+Read active persona via:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona get
+```
+
+Apply `output_style` to document generation in Steps 1D and 1E:
+- `lean` → concise docs: summary sections, skip boilerplate headers, short descriptions
+- `balanced` → standard docs (default if persona unavailable)
+- `enterprise` → full docs: compliance sections, decision rationale appendix, detailed risk notes
+
+Silent if persona unavailable → use `balanced` default.
+
 ## Step 1: Analyze Brainstorm
 
 ```bash
@@ -895,6 +1003,27 @@ The brainstorm session indicates this project has UI scope but `.viepilot/ui-dir
 
 If `ui_scope_detected = false` → skip gate; proceed normally.
 
+**MANDATORY READ GATE (ENH-064) — if `.viepilot/ui-direction/` exists:**
+
+Read ALL artifacts completely (no partial reads):
+1. `notes.md` — ALL sections: ui_idea_buffer[], background extracted ideas, Pages inventory, arch_to_ui_sync[], skills_used[], coverage[], admin (if present)
+2. If `pages/` directory exists: read EVERY `pages/*.html` file — do NOT skip any page
+   For each page: extract layout intent, component list, interactions, designer annotations
+3. Read `index.html` (hub) — verify nav links match pages/ file set
+4. Verify `## Pages inventory` in notes.md matches actual `pages/*.html` set on disk
+   If mismatch detected → STOP:
+   ```
+   ⛔ UI Direction pages/ directory and notes.md Pages inventory are out of sync.
+   Files on disk: {list}
+   Inventory in notes.md: {list}
+   Please sync brainstorm artifacts before continuing.
+   1. Return to /vp-brainstorm --ui to update inventory
+   2. Continue with disk files as source of truth (override notes.md)
+   ```
+5. Record: `ui_direction_read_complete: true` in crystallize working notes
+
+Do NOT proceed to UI extraction until `ui_direction_read_complete: true`.
+
 ### Consume artifacts (when available)
 
 Check for direction artifacts:
@@ -917,6 +1046,69 @@ When available, for the selected/latest session:
 - In architecture / UI plan output, **enumerate every page** from inventory (or state explicitly single-page legacy).
 
 If `notes.md` exists but has no `## Pages inventory` section and brainstorm shows multi-page scope → warn user and request fix or assumptions before proceeding.
+
+---
+
+### Step 1A-i: Build UI Pages → Component Map (ENH-069 Gap 1)
+
+After all `pages/*.html` files are read, build a binding table in crystallize working notes:
+
+```markdown
+## UI Pages → Component Map
+| Prototype | Target component | Phase | Source | Status |
+|-----------|-----------------|-------|--------|--------|
+| pages/landing.html | resources/js/Pages/Home.vue | Phase 1 | page | pending |
+| pages/dashboard.html | resources/js/Pages/Dashboard.vue | Phase 2 | page | pending |
+```
+
+**Rules:**
+- One row per `pages/{slug}.html` found; derive target component from stack convention:
+  - Inertia/Vue → `resources/js/Pages/{PascalName}.vue`
+  - Next.js App Router → `app/{slug}/page.tsx`
+  - Generic SPA → `src/pages/{PascalName}.{ext}`
+- Phase = best estimate from `phases_inventory` topic match or page content
+- Source = `page` (from pages/*.html), `arch_to_ui_sync` (added in Step 1D), `ux_walkthrough` (added below)
+- Status = `pending` (updated to `assigned` in Step 7 after ROADMAP cross-check)
+
+This table is the **single source of truth** for UI→implementation tracing through Steps 1D, 1F, and Step 7.
+
+---
+
+### Step 1A-ii: Process `## UX walkthrough log` (ENH-069 Gap 9)
+
+After building the component map, scan `notes.md → ## UX walkthrough log` (written by `/research-ui`):
+
+- **P0 entries** (unusability, content loss, critical mis-clicks): add a UX-fix row to the component map:
+  ```
+  Source: ux_walkthrough
+  Status: ux-fix-required
+  Task hint: fix-ux-p0: {pain description} on {page}.html
+  ```
+  These become mandatory tasks in ROADMAP (Phase = same as the page's assigned phase).
+
+- **P1 entries** (significant friction, degraded experience): add to component map with `Status: ux-fix-p1`. Generate task hint; include in ROADMAP as same-phase tasks.
+
+- **P2 entries** (minor polish): surface as non-blocking warnings only; do NOT add to component map.
+
+- If `## UX walkthrough log` is absent or empty → no action.
+
+---
+
+### Step 1A-iii: `## Background extracted ideas` resolution gate (ENH-069 Gap 10)
+
+After UX walkthrough processing, scan `notes.md → ## Background extracted ideas` (written by ENH-026 background extraction when user selects "notes only" — no prototype generated):
+
+For each idea entry:
+1. Check if the idea maps to an existing row in the UI Pages → Component Map OR a feature in `phases_inventory`
+2. If NOT covered: add to a `## Unresolved Background Ideas` gate list
+
+**This gate BLOCKS Step 7 (ROADMAP generation) until every entry in `## Unresolved Background Ideas` is resolved with one of:**
+- **(a) Promote to UI Direction** — user creates/updates `pages/*.html`; add to component map
+- **(b) Add as task-TBD** — create implementation task with `design-TBD` note
+- **(c) Descope** — mark as out-of-scope with reason logged in working notes
+
+Record all resolutions in working notes before Step 7 runs.
+
 </step>
 
 <step name="research_stack_official">
@@ -980,6 +1172,44 @@ Also create project-local index for traceability:
 
 If `.viepilot/architect/` exists with at least one session directory:
 
+**MANDATORY READ GATE (ENH-064) — if `.viepilot/architect/` exists:**
+
+Before extracting any data, execute a full sequential read of ALL present files:
+
+```bash
+ls -la .viepilot/architect/{session-id}/
+```
+
+For each file present, READ COMPLETELY (no skimming):
+1. `notes.md` — ALL sections: decisions[], tech_stack{}, open_questions[], erd, use_cases, apis, deployment, feature_map, arch_to_ui_sync[], coverage[], admin (ENH-063), skills_used[]
+2. `architecture.html` — components, C4 intent, external integrations
+3. `data-flow.html` — service flows, async indicators, event queues
+4. `decisions.html` — all ADR entries (supplement notes.md decisions[])
+5. `tech-stack.html` — layer-by-layer stack (authoritative if conflicts with notes.md)
+6. `tech-notes.html` — assumptions, risks, open questions (supplement notes.md open_questions[])
+7. `feature-map.html` — features with phase/priority/status tags
+8. `erd.html` — entities, relationships (if present)
+9. `user-use-cases.html` — actors, use cases (if present)
+10. `deployment.html` — infra, environments (if present)
+11. `apis.html` — endpoints, service contracts (if present)
+12. `admin.html` — admin capabilities (if present — ENH-063)
+13. `content.html` — content types, lifecycle, media/SEO schema (if present — ENH-065)
+14. `user-data.html` — user-owned data controls (if present — ENH-066)
+15. `entity-mgmt.html` — admin entity CRUD matrix (if present — ENH-068)
+    *(Skip: `sequence-diagram.html` — intentionally excluded per existing rule)*
+
+**Failure rule**: if `notes.md` is missing or unreadable → STOP and surface:
+```
+⛔ Architect workspace found but notes.md is missing or unreadable.
+Path: .viepilot/architect/{session-id}/notes.md
+Please fix architect artifacts before running /vp-crystallize.
+1. Return to /vp-brainstorm --architect to regenerate notes.md
+2. Continue without architect data (not recommended)
+```
+
+**Completion record**: after all files read → set `architect_read_complete: true` in crystallize working notes.
+Do NOT proceed to data extraction until `architect_read_complete: true`.
+
 1. **Select most recent session** (by directory mtime or newest session-id).
 2. **Read `notes.md`** → parse YAML frontmatter sections:
    - **`decisions[]`** → append to `.viepilot/ARCHITECTURE.md` under:
@@ -1028,8 +1258,77 @@ If `.viepilot/architect/` exists with at least one session directory:
    | Decision | Choice | Rationale |
    ```
    Note: `sequence-diagram.html` is intentionally excluded from crystallize extraction — per-scenario diagrams are not architecture artifacts (they live in Architect Mode workspace only).
-7. **`feature-map.html`** → cross-reference Phase badges with `phases_inventory`; if discrepancies found (feature in HTML not in inventory, or vice versa) → list them for user to confirm.
-8. **Record in working notes**:
+7. **`admin.html` / `notes.md ## admin`** (if exists — ENH-063) → append to `.viepilot/PROJECT-CONTEXT.md`:
+   ```markdown
+   ## Admin & Governance (from Architect Mode)
+   | Capability | Required | Phase | Notes |
+   |-----------|----------|-------|-------|
+   | User management UI | yes | 2 | invite, deactivate, role assign |
+   | Audit log | yes | 3 | all write operations, 90-day retention |
+   | Monitoring dashboard | optional | 3 | error rate, latency, active users |
+   | Billing management | no | — | not in scope |
+
+   ### Admin Personas
+   | Persona | Key Capabilities |
+   |---------|-----------------|
+   | super_admin | user_management, billing, system_config, audit_log_view |
+   | org_admin | invite_users, role_assign, reporting |
+   ```
+8. **`content.html` / `notes.md ## content`** (if exists — ENH-065) → append to `.viepilot/PROJECT-CONTEXT.md`:
+   ```markdown
+   ## Content Management (from Architect Mode)
+   | Content Type | Created By | Lifecycle | Key Fields | Phase |
+   |-------------|-----------|-----------|-----------|-------|
+   | article | admin, author | draft → review → published → archived | title, body, slug, tags, seo_meta | 2 |
+   | product | admin | draft → published → discontinued | name, description, price, images, category | 1 |
+
+   ### Media & Storage
+   | Storage | CDN | Types | Max Size |
+   |---------|-----|-------|----------|
+   | S3 | CloudFront | image, pdf | 10 MB |
+
+   ### Localization
+   | Locales | Fallback |
+   |---------|---------|
+   | en | en |
+   ```
+9. **`user-data.html` / `notes.md ## user_data`** (if exists — ENH-066) → append to `.viepilot/PROJECT-CONTEXT.md`:
+   ```markdown
+   ## User Data Management (from Architect Mode)
+   | Capability | Supported | Notes |
+   |-----------|----------|-------|
+   | Profile edit (name/email/avatar) | yes | — |
+   | Notification preferences | yes | email, push, in_app |
+   | Data export (GDPR) | yes | CSV/JSON download |
+   | Account deletion (right-to-erasure) | yes | 730-day retention |
+   | Activity history | yes | login history, action log |
+   | Connected accounts (OAuth) | yes | Google, GitHub |
+   | Session/device management | yes | sign out all devices |
+   | Two-factor authentication | yes | TOTP + backup codes |
+   ```
+10. **`entity-mgmt.html` / `notes.md ## entity_mgmt`** (if exists — ENH-068) → append to `.viepilot/PROJECT-CONTEXT.md`:
+   ```markdown
+   ## Admin Entity Management (from Architect Mode)
+   | Entity | CRUD Ops | Soft Delete | Bulk Actions | Audit Trail | Scope |
+   |--------|----------|-------------|--------------|-------------|-------|
+   | — | — | — | — | — | — |
+
+   ### Import / Export
+   | Direction | Entities |
+   |-----------|----------|
+   | CSV Import | — |
+   | CSV Export | — |
+   ```
+11. **`feature-map.html`** — (ENH-069 Gap 7) cross-reference Phase badges with `phases_inventory`; if discrepancies found (feature in HTML not in inventory, or vice versa) → **BLOCKED: Step 7 cannot run until every discrepancy is explicitly resolved**:
+
+    For each discrepancy, record a resolution in `## Feature-Map Resolutions` working notes:
+    - **(a) add-to-inventory** — add feature to phases_inventory; will generate a ROADMAP task
+    - **(b) descoped** — mark feature as removed with reason
+    - **(c) design-only** — design artifact only; no implementation task required
+
+    No silent continuation. The `## Feature-Map Resolutions` table must be complete before Step 7 runs.
+
+12. **Record in working notes**:
    - `architect_session_id`: {id}
    - `decisions_imported`: {count}
    - `open_questions_count`: {count of open questions}
@@ -1037,6 +1336,214 @@ If `.viepilot/architect/` exists with at least one session directory:
    - `use_cases_count`: {count if use_cases present, else "n/a"}
    - `deployment_imported`: {true/false}
    - `apis_imported`: {true/false}
+   - `admin_imported`: {true/false}
+   - `admin_capabilities_count`: {count if admin present, else "n/a"}
+   - `content_imported`: {true/false}
+   - `content_types_count`: {count if content present, else "n/a"}
+   - `user_data_imported`: {true/false}
+   - `user_data_capabilities_count`: {count if user_data present, else "n/a"}
+   - `entity_mgmt_imported`: {true/false}
+   - `entity_mgmt_entity_count`: {count if entity_mgmt present, else "n/a"}
+   - `embedded_domain`: {true/false — from notes.md or PROJECT-CONTEXT.md}
+   - `embedded_hw_topology_imported`: {true/false}
+   - `embedded_peripheral_count`: {count if hw_topology present, else "n/a"}
+
+13. **Embedded Domain Export (ENH-071)**
+
+If notes.md contains any of: `## hw_topology`, `## pin_map`, `## memory_layout`, `## protocols`, `## rtos_config`, `## embedded_toolchain`, `## power_budget`, `## safety_config`:
+
+  a. Set `embedded_export: true` in working notes.
+
+  b. Export to `ARCHITECTURE.md` (append in order, skip sections whose YAML is empty/absent):
+
+  - **`## Hardware Architecture`** ← from `## hw_topology`
+    - MCU/SoC spec table: Family | Core | Flash (KB) | RAM (KB)
+    - Mermaid `graph TD` block diagram (MCU → external ICs via labeled bus arrows)
+    - External ICs + bus topology table: Part | Type | Interface | Bus Speed | Notes
+    - Power rails table: Rail | Source | Voltage | Max current (mA)
+
+  - **`## Hardware Interface`** ← from `## pin_map`
+    - Pin assignment table: Pin# | GPIO Name | Alt Function | Peripheral | Direction | Pull | Voltage | Notes
+    - Conflicts list (if any)
+
+  - **`## Memory Map`** ← from `## memory_layout`
+    - Flash regions table: Region | Start Address | Size (KB) | Usage | Notes
+    - RAM regions table: Region | Start Address | Size (KB) | Usage | Notes
+    - Linker constraints note
+
+  - **`## Communication Protocols`** ← from `## protocols`
+    - Bus protocol matrix table: Protocol | Role | Speed | Topology | Connected Devices | Notes
+    - Wireless/external connectivity table: Protocol | Role | Endpoint | Notes
+    - Note: "See `## APIs` for HTTP REST endpoints (if applicable)"
+
+  - **`## RTOS & Task Model`** ← from `## rtos_config`
+    - Execution model (bare-metal / RTOS name + version)
+    - Task table: Task Name | Priority | Period/Event | Stack KB | Notes
+    - ISR table: Interrupt | Handler | Priority | Shared Resources
+    - Shared resource protection strategy
+
+  - **`## Toolchain & Build System`** ← from `## embedded_toolchain`
+    - MCU family + toolchain + build system + debug interface (one-line summary)
+    - SDK/HAL choice + flasher/debugger tool
+
+  - **`## Power Budget`** ← from `## power_budget`
+    - Power supply summary
+    - Power modes table: Mode | MCU state | Active peripherals | Typical current | Wake-up sources
+    - Battery life estimate (if battery-powered)
+
+  - **`## Safety & Reliability`** ← from `## safety_config`
+    - Safety standard (if any)
+    - Watchdog configuration
+    - Fault handler strategy
+    - Safe state definition
+
+  c. Write to `.viepilot/PROJECT-CONTEXT.md`:
+  ```
+  ## Embedded Domain
+  embedded: true
+  target_mcu: {mcu.family from hw_topology, or "unknown"}
+  toolchain: {toolchain from embedded_toolchain, or "unknown"}
+  ```
+  This flag is read by `vp-auto` at runtime: scaffold-first gate selects the correct embedded toolchain stack instead of web framework scaffolding.
+
+  d. **Hardware sections are READ-ONLY for `vp-auto`** (same protection as ui-direction artifacts).
+     `vp-auto` MUST read hardware sections before implementing driver tasks — never overwrite them.
+
+---
+
+### Step 1D.14 — Design.MD Export (ENH-076)
+
+**Trigger (gate fires when ANY of):**
+- `design.md` exists in `.viepilot/ui-direction/{session-id}/`
+- `notes.md` contains `## design_tokens` section
+- Brainstorm session text contains ≥3 design keywords: `color` / `font` / `brand` / `spacing` / `typography` / `palette` / `theme` / `rounded` / `style`
+
+**Skip conditions (gate does NOT fire when ANY of):**
+- `notes.md` has `design_md_status: skipped` (idempotent — user already skipped this session)
+- `notes.md` has `design_md_status: exported` (already exported this session)
+- Session has no UI components and no design keywords
+
+**Gate — AUQ (mandatory-acknowledge — user must select one option):**
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "Design tokens found in this session. What would you like to do with design.md?"
+>   - header: "design.md"
+>   - options:
+>     - label: "Export to project root" (Recommended)
+>       description: "Copy design.md, update ARCHITECTURE.md + PROJECT-CONTEXT.md"
+>     - label: "Finalize & export"
+>       description: "Complete any missing tokens via Q&A, then export"
+>     - label: "Skip this time"
+>       description: "Note: vp-auto will not apply brand tokens to UI tasks"
+> **Cursor / Codex / Antigravity / Copilot:** present as plain numbered list.
+
+**Export pipeline (options 1 + 2):**
+
+1. **Source:** `.viepilot/ui-direction/{session-id}/design.md`
+2. **Destination:** `{project-root}/design.md`
+   - If `design.md` already exists at project root → AUQ (or plain numbered list on non-terminal):
+     Override with new tokens / Merge (new fills gaps, existing takes precedence) / Keep existing / View diff
+3. **Update `ARCHITECTURE.md`** — append `## Design System` section:
+   ```markdown
+   ## Design System
+
+   > Generated from Design.MD spec (v1)
+   > Source: `.viepilot/ui-direction/{session-id}/design.md`
+   > Last updated: {crystallize-date}
+
+   | Category | Token | Value |
+   |----------|-------|-------|
+   | Colors | primary | {hex} |
+   | Colors | surface | {hex} |
+   | Typography | fontFamily | {font} |
+   | Spacing | base | {n}px |
+
+   **Full spec:** See `design.md` at project root.
+   ```
+4. **Update `PROJECT-CONTEXT.md`** — add field:
+   ```
+   design_md: true
+   ```
+5. **Update `notes.md`** — set:
+   ```yaml
+   design_md_status: exported
+   design_md_exported_at: {timestamp}
+   ```
+
+**Skip pipeline (option 3):**
+- Write to `notes.md`:
+  ```yaml
+  design_md_status: skipped
+  design_md_skipped_at: {timestamp}
+  ```
+- Show warning: `⚠️  design.md skipped — vp-auto will not apply brand tokens to UI tasks`
+
+**Post-Export Handoff: vp-design --sync (ENH-077)**
+
+After **successful export** (export pipeline steps 1–5 complete), offer sync handoff:
+
+**Skip condition:** If no stylesheet target detected (no `tailwind.config.js`, no `.css`, no `.scss` files in project) → skip AUQ silently. Print:
+> `Note: no stylesheet target detected. Run /vp-design --sync after adding your stylesheets.`
+
+Otherwise:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "design.md exported to project root. Sync design tokens to your stylesheets now?"
+>   - header: "Sync tokens?"
+>   - options:
+>     - label: "Run /vp-design --sync now (Recommended)"
+>       description: "Auto-applies tokens to Tailwind / CSS vars / SCSS — stack auto-detected"
+>     - label: "Skip — run manually later"
+>       description: "Run /vp-design --sync yourself when ready"
+>
+> **Cursor / Codex / Antigravity / Copilot:** Text fallback:
+> ```
+> design.md exported. Next step:
+>   /vp-design --sync    Apply tokens to Tailwind / CSS / SCSS
+> ```
+
+**On selection:**
+- "Run /vp-design --sync now" → invoke `/vp-design --sync` skill
+- "Skip" → print: `Tip: run /vp-design --sync to apply design tokens to your stylesheets.`
+
+---
+
+### Step 1D-a: arch_to_ui_sync noted items → UI Pages → Component Map (ENH-069 Gap 5)
+
+After reading `notes.md → ## arch_to_ui_sync[]`, for each entry with `status: noted`:
+
+1. Check if the referenced `ui_implication` (screen/state/component) is already covered by a row in the `## UI Pages → Component Map` (built in Step 1A-i)
+2. If **NOT covered** → add a new row to the component map:
+   ```
+   | Prototype | Target component | Phase | Source | Status |
+   | [no page yet — arch_to_ui_sync] | {inferred component} | {inferred phase} | arch_to_ui_sync | pending |
+   ```
+3. If already covered (matching page exists in Step 1A map) → no action
+
+Note: entries with `status: addressed` are already reflected in pages/*.html — skip them.
+
+---
+
+### Step 1D-b: Design Staleness Check (ENH-069 Gap 8)
+
+After reading `decisions[]` (Step 1D item 2) and having pages/*.html content from Step 1A:
+
+For each decision in `decisions[]` that has a UI implication (check `arch_to_ui_sync[]` table for matching `decision_id`):
+1. Check the relevant `pages/{slug}.html` for visible representation of the decision (keyword search in HTML content)
+2. If **NOT represented**:
+   ```
+   ⚠️ Design Staleness Warning:
+   Decision '{title}' (ui_implication: {text}) is not reflected in {page}.html.
+   The prototype may have been created before this architectural decision was made.
+   
+   → Adding pre-implementation task to UI Pages → Component Map:
+     "update {page}.html to reflect {decision}"
+     Phase: same as page implementation phase
+     Source: design_staleness
+   ```
+3. This pre-implementation task must appear BEFORE the page's component implementation task in ROADMAP ordering
+
+
 
 If `.viepilot/architect/` does **not** exist but brainstorm shows complex architecture (≥5 services/components detected):
 - Suggest (soft prompt — not a hard block):
@@ -1057,6 +1564,77 @@ If `.viepilot/architect/` does **not** exist but brainstorm shows complex archit
 - User confirmation required before proceeding.
 </step>
 
+<step name="skill_decision_gate">
+## Step 1E — Skill Decision Gate (FEAT-020)
+
+**Trigger**: `## skills_used` section exists in the brainstorm session's `notes.md` (`.viepilot/ui-direction/{session-id}/notes.md` or `.viepilot/architect/{session-id}/notes.md`).
+
+**Skip condition**: If no `## skills_used` found anywhere → silently skip this step (no error, no prompt).
+
+**Step — Load skills_used:**
+Read `## skills_used` from the most recent session's `notes.md`. Extract each skill entry: `id`, `capabilities`, `best_practices_applied`.
+
+**Step — AUQ confirm (Claude Code adapter — REQUIRED):**
+
+> **Claude Code (terminal):** Call `AskUserQuestion` tool.
+> - question: "The following skills were used in this brainstorm. Mark each as required, optional, or exclude:"
+> - For each skill: show `id` + capabilities + `best_practices_applied[]`
+> - Options per skill: `required` | `optional` | `exclude`
+
+> **Text fallback (other adapters):** Present numbered list with required / optional / exclude options per skill.
+
+**Step — Write `## Skills` to `PROJECT-CONTEXT.md`:**
+
+Append to `.viepilot/PROJECT-CONTEXT.md`:
+
+```markdown
+## Skills
+
+| Skill | Source | Required | Phases | Rationale |
+|-------|--------|----------|--------|-----------|
+| frontend-design | npm:@vp-skills/frontend-design | required | 1, 2 | UI-Direction HTML generation — design token best practices |
+```
+
+- `required` — skill best_practices injected by vp-auto for matching phases — **no re-asking**
+- `optional` — skill context available but not auto-injected
+- `exclude` — entry omitted from PROJECT-CONTEXT.md
+
+**Lock semantics**: once written, `## Skills` is the authoritative skill decision for the project. `vp-auto` reads it and **never re-prompts**.
+</step>
+
+<step name="cross_reference_gate">
+## Step 1F: Cross-Reference Gate (ENH-064)
+
+Run when BOTH `architect_read_complete: true` AND `ui_direction_read_complete: true` are set in working notes:
+
+1. Read `## Coverage` from architect notes.md (or ui-direction notes.md if present).
+2. For each feature in coverage matrix:
+   - Confirm architect page was read (in `architect_read_complete` set)
+   - Confirm UI screen page was read (in `ui_direction_read_complete` set)
+3. Features with "none yet" in BOTH architect AND UI columns → apply **ENH-069 Gap 6** split:
+
+   **Case A — Feature IS in `phases_inventory`** (scoped for implementation):
+   ```
+   ⛔ Coverage gap BLOCKED: Feature "{name}" is scoped to Phase {N} but has no design coverage.
+   Step 7 (ROADMAP generation) is blocked until resolved. Choose one:
+     (a) Add to UI Direction now → /vp-brainstorm --ui (Recommended)
+     (b) Create implementation task with explicit 'design-TBD' note
+     (c) Remove from scope with reason logged in working notes
+   ```
+   → **Step 7 is BLOCKED** until this feature's gap is resolved and logged.
+
+   **Case B — Feature is NOT in `phases_inventory`** (out-of-scope):
+   ```
+   ⚠️ Coverage gap (out-of-scope): Feature "{name}" has no design coverage — not in phases_inventory.
+   Consider adding before proceeding — or dismiss to continue.
+   ```
+   → Non-blocking warning (unchanged behavior).
+
+4. Record: `cross_reference_complete: true`.
+
+**Skip condition**: if only one workspace is present (not both) → silently skip Step 1F (single-workspace is valid).
+</step>
+
 <step name="generate_ai_guide">
 ## Step 2: Generate AI-GUIDE.md
 
@@ -1162,6 +1740,13 @@ Create `.viepilot/architecture/` only when at least one `.mermaid` file will be
 Create `.viepilot/PROJECT-CONTEXT.md` using template:
 `@$HOME/.cursor/viepilot/templates/project/PROJECT-CONTEXT.md`
 
+**Version stamp (ENH-067):** Write the following as the **very first line** of the generated file (before the `#` title):
+```
+<!-- crystallize_version: {viepilot_semver} -->
+```
+where `{viepilot_semver}` is resolved from `node bin/vp-tools.cjs info` → `version` field.
+This stamp is used by `--upgrade` re-scan mode (Step 0-B) to detect delta on future crystallize runs.
+
 Extract:
 - Domain knowledge
 - Key concepts
@@ -1225,6 +1810,50 @@ From brainstorm `phases_inventory`:
 3. Define dependencies between phases.
 4. Each phase: tasks, acceptance criteria, verification commands.
 5. No Post-MVP / horizon block needed — all work is already in phases.
+
+---
+
+### Step 7 — UI Pages → Component Map Completeness Check (ENH-069 Gap 2)
+
+After generating all phase tasks from `phases_inventory`, run a mandatory UI coverage pass:
+
+For each row in the `## UI Pages → Component Map` (built in Step 1A-i and updated in Steps 1D-a, 1D-b):
+1. Check if a task exists in the generated ROADMAP that implements the `Target component`
+2. If **no task found**:
+   - Add a new task to the appropriate phase:
+     ```
+     Title: "Implement {target_component} from {prototype}"
+     UI Prototype Reference: {path/to/pages/{slug}.html}
+     Source: UI Pages → Component Map (auto-added by crystallize)
+     ```
+   - For `ux-fix-required` rows: add a separate task `fix-ux-p0: {pain description}` before the component task
+   - For `design_staleness` rows: add `update {page}.html to reflect {decision}` before the component task
+3. Update the row status in the component map: `pending` → `assigned (Phase N, Task N.X)`
+
+After the completeness check, **all rows must have `status != pending`**. If any rows remain `pending` after exhausting existing phases, create a new `Phase N+1: UI Implementation` and assign them there.
+
+Finally, write the finalized `## UI Pages → Component Map` to `.viepilot/PROJECT-CONTEXT.md` so `vp-auto` can read it at runtime.
+
+### Step 7 — Embedded Domain: Skip UI Coverage Gate + Apply Hardware Coverage Check (ENH-071)
+
+If `PROJECT-CONTEXT.md` contains `## Embedded Domain` with `embedded: true`:
+
+1. **Skip** the UI Pages → Component Map Completeness Check above (no web UI components expected).
+
+2. **Apply Hardware Coverage Check instead** (non-blocking warning):
+
+   For each peripheral in `hw_topology.peripherals[]` and `hw_topology.external_ics[]`:
+   - Check if a driver task exists in the generated ROADMAP (Phase 2: Driver Layer or equivalent)
+   - If **no driver task found** for peripheral `{name}`:
+     ```
+     ⚠️ Hardware Coverage: no driver task found for peripheral "{name}" ({interface})
+     Suggestion: Add "Implement {name} driver ({interface})" to Phase 2 (Driver Layer)
+     ```
+   - Warning is **non-blocking** — ROADMAP generation continues. User can dismiss or add the task.
+
+3. **Add Phase 1: Board Bring-Up task** if not already in ROADMAP and `embedded: true`:
+   - Automatically include "Board Bring-Up verification" as Phase 1 Task 1 (clock config, GPIO init, UART console confirm, LED blink)
+   - Only added if no equivalent task already exists.
 </step>
 
 <step name="generate_schemas">
@@ -1261,7 +1890,14 @@ Initialize:
 - Version info (0.1.0-alpha)
 - Next action
 
-Create empty `.viepilot/HANDOFF.json`
+Create `.viepilot/HANDOFF.json` with initial fields including:
+```json
+{
+  "crystallize_version": "{viepilot_semver}",
+  "crystallized_at": "{ISO-8601 timestamp}"
+}
+```
+`crystallize_version` mirrors the stamp written to `PROJECT-CONTEXT.md` (ENH-067). Used by `--upgrade` re-scan as a fallback when `PROJECT-CONTEXT.md` header comment is absent.
 </step>
 
 <step name="generate_phase_dirs">