viepilot 2.23.0 → 2.41.0

package/skills/vp-audit/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -103,15 +130,36 @@ When auditing a project bootstrapped via `vp-crystallize --brownfield`:
 
 <context>
 Optional flags:
-- `--framework` : Force Tier 3 framework checks (even if not auto-detected)
-- `--project`   : Force project-only mode — skip Tier 3 framework checks
-- `--fix`       : Auto-fix all detected issues
-- `--report`    : Generate report file at `.viepilot/audit-report.md`
-- `--silent`    : Only output if issues found
-- `--tier1`     : Run Tier 1 (state consistency) only
-- `--tier2`     : Run Tier 2 (docs drift) only
-- `--tier3`     : Run Tier 3 (stack best-practice) only
-- `--tier4`     : Run Tier 4 (framework integrity) only
+- `--framework`  : Force Tier 3 framework checks (even if not auto-detected)
+- `--project`    : Force project-only mode — skip Tier 3 framework checks
+- `--fix`        : Auto-fix all detected issues
+- `--report`     : Generate report file at `.viepilot/audit-report.md`
+- `--silent`     : Only output if issues found
+- `--tier1`      : Run Tier 1 (state consistency) only
+- `--tier2`      : Run Tier 2 (docs drift) only
+- `--tier3`      : Run Tier 3 (stack best-practice) only
+- `--tier4`      : Run Tier 4 (framework integrity) only
+- `--no-autolog` : Skip auto-logging of gaps to `.viepilot/requests/`; report-only mode
+
+### Auto-Log Behavior (ENH-070)
+
+By default, `vp-audit` automatically logs each detected gap as a request file after the audit report is shown — no manual `/vp-request` step needed:
+
+| Tier | Issue category | Request type | Priority |
+|------|----------------|-------------|----------|
+| 1 | State inconsistency / HANDOFF drift / git tag missing | BUG | medium |
+| 1 | Execute-first ordering risk | BUG | medium |
+| 2 | Doc drift (README/CHANGELOG version) | BUG | low |
+| 2 | Missing docs / placeholder URLs | ENH | low |
+| 3 | Stack violation / correctness anti-pattern | BUG | high |
+| 3 | Stack improvement / best-practice gap | ENH | medium |
+| 4 | Framework integrity gap | ENH | high |
+
+**Duplicate detection**: if a matching open request already exists (title ≥ 70% match or file overlap), the finding is appended to it as a "Re-detected" note rather than creating a duplicate file.
+
+**Post-audit banner**: after auto-logging, shows all logged request IDs and recommends `/vp-evolve {IDs}` as the next action. AUQ prompt on Claude Code terminal.
+
+**Disable**: use `vp-audit --no-autolog` for report-only mode (no `.viepilot/requests/` files created).
 </context>
 
 <process>

package/skills/vp-auto/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -267,3 +294,20 @@ Before the first interactive prompt, call `ToolSearch` with `query: "select:AskU
 - [ ] CHANGELOG updated for features/fixes
 - [ ] Clean stop with summary on pause/error
 </success_criteria>
+
+### Skill Context Execution (FEAT-020)
+
+At session start, vp-auto reads `PROJECT-CONTEXT.md ## Skills` (locked by `/vp-crystallize`
+Step 1E) and builds a `SKILL_CONTEXT_MAP`.
+
+During each task:
+- Required skills whose phases match the current task's phase are **silently** injected into the execution context
+- Best practices from matched skills appear as a silent checklist before implementation
+- Task output records `skills_applied: [id@version, ...]`
+
+**No prompts are shown** — all skill decisions are locked at crystallize time.
+`/vp-auto` is execution-only for skills.
+
+Install skills: `vp-tools install-skill <source>`
+Lock decisions: `/vp-crystallize` Step 1E
+Docs: `docs/user/features/skill-registry.md`

package/skills/vp-brainstorm/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -54,11 +81,18 @@ Supports:
 - **Phase assignment (ENH-030):** in every session, features/capabilities are assigned directly to Phase 1, Phase 2, Phase 3... — no MVP/Post-MVP/Future tiers. Session file stores assignments in the `## Phases` section.
 - **Project meta intake (FEAT-009):** after **scope locked**, **before** `Completed` / `/end`, if `.viepilot/META.md` (`viepilot_profile_id`) is missing — run **sequential** Q&A with proposals; read/write `~/.viepilot/profile-map.md`; create `~/.viepilot/profiles/<slug>.md` + binding per **`docs/dev/global-profiles.md`**. If a profile is already bound — skip intake by default (ask if change needed).
 - **UX walkthrough (FEAT-010 + ENH-019 + ENH-020):** in **`--ui`** mode, command **`/research-ui`** or **`/research ui`** runs 3 phases — simulates **end-user** (with **content stress pass** + **stress recipes by archetype** → **Stress findings**) → **UX designer + web research** → update `index.html` / `pages/*.html` / `style.css` and write **`## UX walkthrough log`** in `notes.md` (sync hub + **Pages inventory** for multi-page).
-- **Background UI extraction (ENH-026):** automatically detects UI signal keywords in every brainstorm session (no `--ui` flag required); silent accumulation buffer; surfaces for confirmation when topic ends, `/save`, or ≥5 signals — does not interrupt the main conversation.
+- **Background UI extraction (ENH-026 + ENH-060):** automatically detects UI signal keywords in every brainstorm session (no `--ui` flag required). **Auto-suggests itself (ENH-060):** if the initial message contains ≥1 UI keyword, shows a proactive 🎨 banner immediately — mirrors Architect Design Mode's 🏗️ proactive activation. Accumulation starts at ≥1 signal (was ≥3); surfaces for confirmation when topic ends, `/save`, or **≥2 unique signals** accumulated (was ≥5) — does not interrupt the main conversation.
+- **Idea → Architecture breakdown loop (ENH-061):** structured 8-step flow from free idea collection → scope lock → **Feature → Coverage mapping** (maps each Phase 1 feature to an architect page + UI screen, outputs `## Coverage` matrix in `notes.md`) → Architect Design → **`arch_to_ui_sync`** reverse sync (surfaces UI implications of architectural decisions; `/sync-ui` command) → UI Direction → **completeness gate** (CHECK 4: warns if any Phase 1 feature has no coverage in either mode, non-blocking). See `Recommended Breakdown Ordering` section in `workflows/brainstorm.md`.
+- **Unified workspace mode selection (BUG-018):** after scope lock, before any design workspace is created, an AUQ prompt offers: Both / Architect only / UI Direction only / Neither. Architect auto-activate heuristic is deferred until after this selection; suppressed if user selects "Neither" or "UI Direction only".
+- **Admin & Governance coverage (ENH-063):** Topic 6 in brainstorm template; proactive 🔐 heuristic fires on admin/governance keywords; admin coverage gate before /save for multi-user/SaaS/compliance projects; `admin.html` added to Architect workspace when applicable; `notes.md ## admin` YAML exported via crystallize.
+- **Content Management coverage (ENH-065):** Topic 7 in brainstorm template; proactive 🗂️ heuristic fires on content-type/media/SEO keywords; content coverage gate before /save for projects with content layer; `content.html` added to Architect workspace; `notes.md ## content` YAML exported via crystallize.
+- **Admin Entity Management coverage (ENH-068):** Topic 7 in brainstorm template; proactive 🗄️ heuristic fires on CRUD/entity/admin panel keywords; entity management coverage gate before /save for projects with DB entities (cross-references ERD); `entity-mgmt.html` added to Architect workspace; `notes.md ## entity_mgmt` YAML exported via crystallize.
+- **User Data Management coverage (ENH-066):** Topic 9 in brainstorm template; proactive 👤 heuristic fires on user-account/privacy/auth keywords; user data coverage gate before /save for B2C/SaaS/GDPR projects; `user-data.html` added to Architect workspace; `notes.md ## user_data` YAML exported via crystallize.
 - **Architect Design Mode (FEAT-011):** `/vp-brainstorm --architect` or auto-activate when ≥3 components/services detected; generate HTML workspace (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map) with Mermaid diagrams; incremental update per decision; `/review-arch` command; machine-readable `notes.md` YAML schema.
 - **ERD page (ENH-027):** Architect workspace includes `erd.html` — Mermaid `erDiagram`, entity list table, relationship summary; triggered by DB/entity/table/relationship keywords; notes.md `## erd` YAML section exported to ARCHITECTURE.md `## Database Schema` via crystallize Step 1D.
 - **User Use Cases page (ENH-028):** Architect workspace includes `user-use-cases.html` — actor/use-case diagram (Mermaid flowchart), use case table; triggered by user/role/actor/story keywords; notes.md `## use_cases` YAML section exported to PROJECT-CONTEXT.md `## User Stories & Use Cases` via crystallize Step 1D.
 - **C4Context/Sequence/Deployment/APIs pages (ENH-029, 12-page workspace):** Architect workspace expanded to 12 pages — `sequence-diagram.html` (per-scenario sequenceDiagram), `deployment.html` (infra graph + environments + CI/CD pipeline), `apis.html` (endpoint tables with HTTP method badges); page boundary rules table; trigger keywords for sequence/deploy/API; notes.md `## apis` YAML section; deployment+APIs exported to ARCHITECTURE.md via crystallize Step 1D (sequence excluded — scenario docs are not architecture artifacts).
+- **Embedded Domain Mode (ENH-071):** Activated when ≥2 embedded trigger keywords detected (MCU families: STM32/ESP32/nRF52/AVR/RISC-V/RP2040; concepts: firmware/bare-metal/GPIO/interrupt/HAL/bootloader/RTOS) OR `--domain embedded` flag. Adds 6 Architect workspace pages for embedded hardware artifacts, injects domain-specific topic probes, suppresses web-UI false-positives for hardware display keywords, and offers a firmware phase ordering template. crystallize exports 8 YAML sections to ARCHITECTURE.md hardware sections.
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -70,6 +104,16 @@ Supports:
 - `BRAINSTORM_LANG` is used for brainstorm file storage and generated content.
 - User session language takes precedence over config if different.
 - Configure via: `vp-tools config set language.document vi`
+
+**Workflow version stamps (ENH-067):**
+- Session files record `workflow_version` (current ViePilot semver) at create/save time.
+- `upgrade_supplement_version` stamped after gap-detection supplement completes (idempotency guard).
+
+**Upgrade gap detection (ENH-067):**
+- On `--continue`, compares session `workflow_version` vs. current Topics Template to detect missing topics.
+- Proactive 🔄 upgrade banner (AUQ) lists missing topics; user can discuss inline, defer to /save, or skip.
+- Inline supplement appended as `## Upgrade supplement (vX → vY)` section; `upgrade_supplement_version` stamped for idempotency.
+- After supplement: suggests `/vp-crystallize --upgrade` to patch project artifacts.
 </objective>
 
 <execution_context>
@@ -84,8 +128,52 @@ Optional flags:
 - `--landing` : Prioritize the Landing Page layout discovery flow
 - `--research` : Enable proactive research suggestions during the session
 - `--ui` : Enable UI Direction mode (live HTML/CSS direction artifacts)
+- `--domain embedded` : Force-activate Embedded Domain Mode (hardware topology, RTOS, pin map, memory layout, protocol matrix, power budget pages + topic probes)
 </context>
 
+### Embedded Domain Mode (ENH-071)
+
+**Activation**: Automatically when ≥2 embedded keywords detected, or via `--domain embedded` flag. One-time `🔌 Embedded Domain Mode activated` banner shown.
+
+**Topic probes injected when `embedded_domain: true`:**
+- **MCU/Toolchain** (Gap 2): MCU family, toolchain (GCC-ARM/Keil/IAR), build system (CMake/PlatformIO/West), debug interface (SWD/JTAG), flasher, SDK/HAL
+- **RTOS/Scheduling** (Gap 3): bare-metal vs RTOS choice, task list, ISR table, resource protection strategy
+- **Power Budget** (Gap 7): supply type, sleep modes, current targets, battery life (triggered by battery/power/sleep keywords)
+- **Safety/Compliance** (Gap 10): IEC 61508/ISO 26262/DO-178C, watchdog, fault handlers (triggered by safety/SIL/ASIL keywords)
+- **Firmware Phase Template** (Gap 9): Board Bring-Up → Drivers → RTOS → Middleware → Application → Integration Test → OTA
+
+**6 new Architect workspace pages** (in `.viepilot/architect/{session-id}/`):
+
+| Page | Trigger | Content |
+|------|---------|---------|
+| `hw-topology.html` | Always in embedded domain | MCU block diagram (Mermaid graph TD) + component/bus/power-rail tables |
+| `pin-map.html` | GPIO/pin/pinout keywords | Pin assignment table (Pin# / GPIO / Function / Peripheral / Direction / Pull / Voltage) |
+| `memory-layout.html` | Flash/RAM/linker/bootloader/OTA keywords | Flash + RAM regions tables + linker constraint notes |
+| `protocol-matrix.html` | CAN/I2C/SPI/BLE/LoRa/MQTT/Modbus keywords | Bus protocol + wireless connectivity tables (distinct from `apis.html` HTTP REST) |
+| `rtos-scheduler.html` | RTOS/FreeRTOS/task/ISR/scheduler keywords | Task priority table + ISR table + state diagram (≤5 tasks) |
+| `power-budget.html` | Battery/sleep/power/µA/mAh keywords | Power modes table + battery life estimate |
+
+Pages linked in `index.html` under an **Embedded** nav section.
+
+**UI Direction false-positive suppression** (Gap 6):
+- `LCD` / `OLED` / `TFT` / `display` / `screen` in hardware context → routed to `hw-topology` peripherals, NOT UI Direction buffer
+- Hardware context confirmed by: GPIO / SPI / I2C / driver / framebuffer / ILI9341 / SSD1306 / LVGL / u8g2 keywords
+- `🎨 UI Direction Mode?` banner suppressed when all display signals have hardware context
+
+**notes.md YAML sections written:** `## hw_topology`, `## pin_map`, `## memory_layout`, `## protocols`, `## rtos_config`, `## embedded_toolchain`, `## power_budget`, `## safety_config`
+
+**crystallize Step 1D item 13 exports:**
+- `## Hardware Architecture` (from `hw_topology`)
+- `## Hardware Interface` (from `pin_map`)
+- `## Memory Map` (from `memory_layout`)
+- `## Communication Protocols` (from `protocols`) — distinct from `## APIs`
+- `## RTOS & Task Model` (from `rtos_config`)
+- `## Toolchain & Build System` (from `embedded_toolchain`)
+- `## Power Budget` (from `power_budget`)
+- `## Safety & Reliability` (from `safety_config`)
+- `## Embedded Domain: true` + MCU family written to `PROJECT-CONTEXT.md`
+- UI Coverage Gate skipped; Hardware Coverage Check (driver-task completeness, non-blocking) applied instead
+
 <process>
 Execute workflow from `@$HOME/{envToolDir}/workflows/brainstorm.md`
 
@@ -144,3 +232,22 @@ plain-text numbered list prompts — no configuration required.
 **Prompts using AskUserQuestion in this skill:**
 - Session intent (continue / review / new — Step 2)
 - Landing page layout selection (Step 4 — Layout A/B/C/D)
+
+
+### Skill Registry Integration (FEAT-020)
+
+When UI Direction Mode is active, vp-brainstorm automatically:
+1. Loads `~/.viepilot/skill-registry.json` (written by `vp-tools scan-skills`)
+2. Matches installed skills by `capabilities` to current UI signals
+3. **Silently** applies matched skill `best_practices` to HTML generation
+4. Records matched skills in `notes.md ## skills_used`
+
+**No prompt is shown** — integration is transparent. Skills with relevant
+capabilities (e.g., `ui-generation`, `component-design`, `responsive-layout`)
+are detected automatically.
+
+Skill decisions are **locked at crystallize time** (see `/vp-crystallize`).
+`/vp-auto` executes with those locked decisions — no re-asking.
+
+Install skills via `vp-tools install-skill <source>`.
+See: `docs/user/features/skill-registry.md`

package/skills/vp-crystallize/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -84,6 +111,35 @@ Convert brainstorm sessions into structured artifacts for autonomous AI executio
 **Architect artifacts consumption (FEAT-011):**
 - Step 1D reads `.viepilot/architect/{session}/notes.md` YAML — imports `decisions[]` → ARCHITECTURE.md, uses `tech_stack{}` as authoritative stack (conflict → ask user), surfaces `open_questions[]` with `status: open`. Soft suggestion (not hard block) when architect dir missing but ≥5 services detected.
 
+**Admin & Governance Export (ENH-063):**
+- Step 1D item 7: if `admin.html` or `notes.md ## admin` exists in architect workspace → append `## Admin & Governance` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Capability | Required | Phase | Notes) + Admin Personas table. Records `admin_imported` and `admin_capabilities_count` in working notes.
+
+**Content Management Export (ENH-065):**
+- Step 1D item 8: if `content.html` or `notes.md ## content` exists in architect workspace → append `## Content Management` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Content Type | Created By | Lifecycle | Key Fields | Phase) + Media/Storage and Localization sub-tables. Records `content_imported` and `content_types_count` in working notes.
+
+**Admin Entity Management Export (ENH-068):**
+- Step 1D item 10: if `entity-mgmt.html` or `notes.md ## entity_mgmt` exists in architect workspace → append `## Admin Entity Management` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Entity | CRUD Ops | Soft Delete | Bulk Actions | Audit Trail | Scope) + Import/Export sub-table. Records `entity_mgmt_imported` and `entity_mgmt_entity_count` in working notes.
+
+**User Data Management Export (ENH-066):**
+- Step 1D item 9: if `user-data.html` or `notes.md ## user_data` exists in architect workspace → append `## User Data Management` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Capability | Supported | Notes) with 8 capability rows (profile editing, notification prefs, privacy settings, data export, right to erasure, connected accounts, session management, 2FA). Records `user_data_imported` and `user_data_capabilities_count` in working notes.
+
+**Crystallize version stamps (ENH-067):**
+- Generated `PROJECT-CONTEXT.md` includes `<!-- crystallize_version: {semver} -->` as its first line.
+- `HANDOFF.json` records `crystallize_version` and `crystallized_at` fields.
+- Used by `--upgrade` re-scan mode to compute delta on future runs.
+
+**Upgrade re-scan mode (`--upgrade`) (ENH-067):**
+- Detects `crystallize_version` delta; lists missing PROJECT-CONTEXT.md sections.
+- **Patch mode:** appends only missing sections non-destructively; re-stamps `crystallize_version`.
+- **Full re-generate:** backs up `.viepilot/` → regenerates all artifacts using existing sessions.
+- Integrates brainstorm `## Upgrade supplement` sections when present.
+
+**Mandatory Workspace Read Gates (ENH-064):**
+- **Architect workspace (Step 1D):** if `.viepilot/architect/` exists → reads ALL 12 pages front-to-back before any extraction. `architect_read_complete: true` required. Missing `notes.md` → STOP.
+- **UI Direction workspace (Step 1A strengthened):** if `.viepilot/ui-direction/` exists → reads ALL pages/*.html + ALL notes.md sections. `ui_direction_read_complete: true` required. Pages inventory mismatch → STOP.
+- **Cross-reference gate (Step 1F):** when both workspaces present → validates coverage matrix; warns on Phase 1 features with no architect OR UI coverage.
+- **No silent skip**: any workspace that exists MUST be fully read. Partial reads are not allowed.
+
 **Language configuration (ENH-032):**
 - Step 0-A reads `~/.viepilot/config.json` → `DOCUMENT_LANG` (default: `en`) and `COMMUNICATION_LANG` (default: `en`).
 - `DOCUMENT_LANG` controls content language for all generated files (ROADMAP, TRACKER, ARCHITECTURE, etc.).
@@ -303,3 +359,19 @@ plain-text numbered list prompts — no configuration required.
 - Polyrepo related-repos prompt (Step 0-B)
 - UI direction gate choice (Step 1A)
 - Architect mode suggestion (Step 1D)
+
+### Step 1E — Skill Decision Gate (FEAT-020)
+
+After scope lock, before SPEC generation, crystallize checks for `## skills_used`
+in the brainstorm session's notes.md:
+
+- **No skills_used found** → step silently skipped
+- **Skills found** → AUQ presents each skill (required / optional / exclude)
+- **Decision written** to `PROJECT-CONTEXT.md ## Skills`
+
+The `## Skills` decision is **final** — `/vp-auto` reads it at execution time
+and injects skill best practices per task without re-prompting.
+
+Install skills: `vp-tools install-skill <source>`
+Registry: `vp-tools scan-skills`
+Docs: `docs/user/features/skill-registry.md`

package/skills/vp-debug/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation

package/skills/vp-docs/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation

package/skills/vp-evolve/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -179,16 +206,42 @@ Update in:
 - CHANGELOG.md [Unreleased] section
 
 ### Step 5: Confirm & Suggest Next
+
+Display summary banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► EVOLVE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Mode: {mode}
+ Changes: {list}
+ Version: {old} → {new}
+ New Phases: Phase {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
-✓ Evolution complete
 
-Mode: {mode}
-Changes:
-- {list changes}
+**Claude Code (terminal) — REQUIRED:** After banner, call `AskUserQuestion`:
+```
+question: "Phase {N} planned. What would you like to do next?"
+options:
+  - label: "Execute now → /vp-auto"
+    description: "Start implementing Phase {N} immediately (Recommended)"
+  - label: "Create another request → /vp-request"
+    description: "Log more requests before implementing"
+  - label: "Done for now"
+    description: "Exit — run /vp-auto later"
+```
 
-Version: {old} → {new}
+**On selection:**
+- "Execute now → /vp-auto": invoke `/vp-auto --from {new_phase}` skill
+- "Create another request → /vp-request": invoke `/vp-request` skill
+- "Done for now": print "Phase {N} ready. Run /vp-auto when ready." and exit
 
-Next action: /vp-auto --from {new_phase}
+**Text fallback (Cursor/Codex/Copilot/Antigravity):**
+```
+Next actions:
+  /vp-auto --from {N}    Execute Phase {N}
+  /vp-request            Create another request
 ```
 </process>
 

package/skills/vp-info/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation

package/skills/vp-pause/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation

package/skills/vp-proposal/SKILL.md

@@ -15,6 +15,33 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation