viepilot 1.9.10 → 1.14.0

package/CHANGELOG.md

@@ -7,9 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Planned
+## [1.14.0] - 2026-04-06
 
-- None.
+### Changed (ENH-030 — Phase 46)
+
+- **Remove MVP/Post-MVP/Future concept** — all projects now use phase-based planning only:
+  - `workflows/brainstorm.md`: replaced `## Product horizon` section + ENH-014 rule with Phase assignment rule (ENH-030) and `## Phases` session template
+  - `workflows/crystallize.md`: replaced Horizon validation gate with Phase assignment gate; Step 7 ROADMAP generation now uses `phases_inventory` (no Post-MVP block)
+  - `templates/architect/feature-map.html`: mindmap nodes + badge classes updated — MVP/Post-MVP/Future → Phase 1/Phase 2/Phase 3
+  - `templates/architect/style.css`: `.badge-mvp/.badge-post-mvp/.badge-future` → `.badge-phase-1/.badge-phase-2/.badge-phase-3`
+  - `templates/architect/user-use-cases.html`: Priority column → Phase; badge-mvp/post-mvp/future → badge-phase-1/2/3
+  - `templates/architect/index.html`: feature map subtitle updated (no MVP/Post-MVP text)
+  - `templates/project/PROJECT-CONTEXT.md`: MVP boundary + Post-MVP themes sections replaced with Project scope + Phase overview table
+  - `templates/project/ROADMAP.md`: Post-MVP / Product horizon block removed; maintenance note updated
+  - `templates/project/AI-GUIDE.md`: all MVP/horizon reading instructions replaced with phase-centric equivalents
+  - `skills/vp-brainstorm/SKILL.md` v1.1.0: phase assignment rule replaces product horizon rule
+  - `skills/vp-crystallize/SKILL.md` v0.8.0: phase assignment gate replaces horizon gate
+  - `skills/vp-task/SKILL.md`: example updated (no MVP reference)
+
+### Tests
+- Added `tests/unit/vp-enh030-no-mvp-contracts.test.js` (10 tests) — all pass (372 total)
+
+## [1.13.0] - 2026-04-04
+
+### Added
+
+- **ENH-029 — Architect Design Mode: C4/Sequence/Deployment/APIs pages (12-page workspace)**:
+  - `templates/architect/architecture.html`: C4 Context diagram section (Mermaid `C4Context`) + External Systems table (6 columns: System/Type/Description/Integration method/Owned by/Notes).
+  - `templates/architect/sequence-diagram.html` (new): per-scenario sequences — Scenario Index table, 2 placeholder `sequenceDiagram` blocks, differentiation note linking to data-flow.html.
+  - `templates/architect/deployment.html` (new): infra `graph TD` with dev/staging/prod, Environments table, Infrastructure Components table, CI/CD `flowchart LR`.
+  - `templates/architect/apis.html` (new): per-service endpoint tables (Method/Path/Auth?/Request Body/Response/Status codes/Notes), HTTP method badges, API Design Decisions table with style badges.
+  - `templates/architect/style.css`: 5 HTTP method badge classes (`.method-get/post/put/delete/patch`).
+  - All 12 architect pages updated with full 12-item sidebar nav (Sequence + Deployment + APIs items added to all existing pages).
+  - `templates/architect/index.html`: 3 new hub cards (Sequence Diagram, Deployment, APIs); Architecture card subtitle updated.
+  - `workflows/brainstorm.md`: Page Boundary Rules table; Sequence/Deployment/APIs trigger keyword sections; C4Context added to diagram types; `## apis` YAML schema section; 3 new pages in workspace layout.
+  - `workflows/crystallize.md` Step 1D: steps 5–6 extract `deployment.html`/`notes.md ## deployment` → `## Deployment & Infrastructure` and `apis.html`/`notes.md ## apis` → `## API Design` in ARCHITECTURE.md; sequence-diagram.html explicitly excluded with rationale.
+  - `skills/vp-brainstorm/SKILL.md`: ENH-029 capability note added.
+  - `tests/unit/vp-enh029-architect-pages-contracts.test.js` (new): 11 contract tests — all pass (362 total).
+
+## [1.12.0] - 2026-04-04
+
+### Added
+
+- **ENH-027 — Architect Design Mode: ERD page**:
+  - `templates/architect/erd.html` (new): Mermaid `erDiagram` with sample entities (User/Order/OrderItem/Product), Entity List table (Entity/Attributes/PK/FK/Notes), Relationship Summary table.
+  - `workflows/brainstorm.md`: ERD trigger keywords (entity, table, relationship, foreign key, schema, DB, database); `## erd` section in notes.md YAML schema; `erDiagram` added to supported Mermaid types.
+  - `workflows/crystallize.md` Step 1D: step 3 — extracts `## erd` → `## Database Schema (from Architect ERD)` in ARCHITECTURE.md.
+  - All 7 existing architect templates updated with `🗄️ ERD` sidebar nav link.
+- **ENH-028 — Architect Design Mode: User Use Cases page**:
+  - `templates/architect/user-use-cases.html` (new): Mermaid `flowchart LR` with Actors/Use Cases subgraphs, Use Case List table (ID/Actor/Priority), Actor Summary table.
+  - `workflows/brainstorm.md`: Use Case trigger keywords (user story, actor, role, use case, scenario); `## use_cases` section in notes.md YAML schema.
+  - `workflows/crystallize.md` Step 1D: step 4 — extracts `## use_cases` → `## User Stories & Use Cases (from Architect Mode)` in PROJECT-CONTEXT.md.
+  - All architect templates updated with `👤 Use Cases` sidebar nav link; `index.html` adds 2 hub cards.
+- **vp-brainstorm v1.0.0**: bumped from 0.9.0 with ENH-027 + ENH-028 capability notes.
+
+## [1.11.0] - 2026-04-04
+
+### Added
+
+- **FEAT-011 — Architect Design Mode**:
+  - `workflows/brainstorm.md`: new `### Architect Design Mode` section — activate via `--architect` flag or auto-heuristic (≥3 components OR ≥1 stack mention); generates HTML workspace with 7 sections (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map, hub) + `notes.md` YAML schema; incremental updates per decision with `.updated` CSS highlight; `/review-arch` command for summary + open_questions review.
+  - `templates/architect/`: 7 HTML templates + `style.css` — dark/light toggle, Mermaid.js diagrams, `.updated` diff indicator, responsive sidebar nav. Self-contained, open in browser.
+  - `workflows/crystallize.md`: new Step 1D `consume_architect_artifacts` — reads `notes.md` YAML; imports `decisions[]` → ARCHITECTURE.md, uses `tech_stack{}` as authoritative, surfaces `open_questions[]` status=open; cross-references `feature-map.html` with Product Horizon; soft suggestion (not hard block) when architect dir missing.
+  - `skills/vp-brainstorm/SKILL.md`: bumped to `0.9.0`, FEAT-011 listed in capabilities.
+  - `skills/vp-crystallize/SKILL.md`: bumped to `0.7.0`, FEAT-011 listed in capabilities.
+  - `docs/user/features/architect-design-mode.md`: new — 8 sections covering overview, activation, HTML artifacts, dialogue cadence, `/review-arch`, crystallize integration, notes.md schema, tips.
+  - `tests/unit/vp-feat011-architect-design-mode-contracts.test.js`: 8 contract tests (333 total, all pass).
+
+## [1.10.0] - 2026-04-04
+
+### Added
+
+- **ENH-026 — Background UI Extraction + Crystallize Hard Gate**:
+  - `workflows/brainstorm.md`: new `### Background UI Extraction (silent mode)` section — auto-detects 35 UI signal keywords in any brainstorm session; silent `ui_idea_buffer[]` accumulation; surfaces 3-option confirmation dialogue (save to notes, activate UI Direction Mode, or keep buffer) at topic end / `/save` / ≥5 signals. Non-blocking.
+  - `workflows/crystallize.md`: Step 1A upgraded to **hard gate** — scans brainstorm sessions for ≥3 UI signals; if `ui_scope_detected = true` and artifacts missing → STOP with 2-option dialogue; Option 2 bypass writes `## UI Direction Assumptions` to `.viepilot/ARCHITECTURE.md`.
+  - `skills/vp-brainstorm/SKILL.md`: bumped to `0.8.0`, ENH-026 background extraction listed in capabilities.
+  - `skills/vp-crystallize/SKILL.md`: bumped to `0.6.0`, ENH-026 hard gate listed in capabilities.
+  - `docs/user/features/ui-direction.md`: new `## Background Extraction` and updated `## Crystallize Integration` sections with hard gate docs, dialogue examples, and diff table vs `--ui` mode.
+  - `tests/unit/vp-enh026-ui-extraction-contracts.test.js`: 6 contract tests (325 total, all pass).
+
+## [1.9.11] - 2026-04-02
+
+### Fixed
+
+- **BUG-007**: `vp-tools info` crash "Could not locate viepilot package root" khi CWD không phải viepilot source repo. Fix: `buildInstallPlan()` claude-code block nay copy `package.json` → `~/.claude/viepilot/package.json`, cho phép `resolveViepilotPackageRoot()` tìm thấy root ngay cả khi install từ `~/.claude/viepilot/`. (+2 tests, 319 total pass)
 
 ## [1.9.10] - 2026-04-02
 

package/docs/brainstorm/session-2026-04-02.md

@@ -0,0 +1,145 @@
+# Brainstorm Session: Multi-Agent Support Expansion
+
+**Date:** 2026-04-02  
+**Status:** In Progress  
+**Topic:** Mở rộng hỗ trợ các coding agent ngoài Codex
+
+---
+
+## Objective
+
+Nghiên cứu và lên kế hoạch để ViePilot hỗ trợ thêm các coding agent phổ biến ngoài OpenAI Codex hiện tại.
+
+---
+
+## Research: Coding Agents Landscape 2025-2026
+
+### Tier 1 — CLI-native / Có thể tích hợp trực tiếp
+
+| Agent | Maker | CLI | API/SDK | ACP | MCP | Notes |
+|-------|-------|-----|---------|-----|-----|-------|
+| **Codex CLI** | OpenAI | ✓ | ✓ | ✓ | ✓ | Đang hỗ trợ |
+| **Claude Code** | Anthropic | ✓ | ✓ | ✓ | ✓ | CLI `claude`, SDK @anthropic-ai/claude-agent-sdk |
+| **Aider** | OSS | ✓ | ✓ | ✗ | ✓ | CLI `aider`, Python-based, Git-native |
+| **Goose** | Block/LF | ✓ | ✓ | ✓ | ✓ | CLI + desktop, 25+ LLM providers |
+| **OpenCode** | OSS | ✓ | ✓ | ✓ | ✓ | 75+ models, terminal-native |
+| **Kimi Code** | Moonshot AI | ✓ | ✓ | ✓ | ✓ | 1T param MoE, 256K context |
+| **GitHub Copilot CLI** | GitHub/MS | ✓ | ✓ | Planned | ✓ | `gh copilot` command |
+
+### Tier 2 — IDE-primary (CLI hạn chế)
+
+| Agent | Maker | CLI | Notes |
+|-------|-------|-----|-------|
+| **Cursor** | Cursor | ✗ | IDE-only, không có CLI programmatic |
+| **Windsurf** | Cognition | ✗ | IDE-only |
+| **Continue.dev** | OSS | ✗ | VS Code / JetBrains extension |
+| **Cline** | OSS | ✗ | VS Code extension, MCP support |
+| **Gemini Code Assist** | Google | Limited | IDE plugin chính |
+| **Amazon Q Dev** | AWS | Limited | IDE plugin, `q` CLI |
+| **Devin** | Cognition | Limited | Web app + API |
+
+### Tier 3 — Web-only / Specialized
+
+- **v0 by Vercel** — full-stack web generation
+- **Bolt.new** — in-browser WebContainers
+- **Tabnine** — IDE plugin + Jira integration
+- **Cody (Sourcegraph)** — multi-repo search agent
+
+---
+
+## Integration Protocols
+
+### Model Context Protocol (MCP)
+- Chuẩn hóa cách agent truy cập tools bên ngoài
+- Adopted by: OpenAI, Google, Microsoft, Anthropic
+- Rủi ro security: prompt injection (April 2025 report)
+
+### Agent Client Protocol (ACP)
+- JSON RPC over stdio — standardized editor ↔ agent communication
+- Created by: JetBrains & Zed (Aug 2025)
+- Supported agents: Claude Code, Codex CLI, Gemini, Goose
+- Supported editors: Zed, Neovim, Marimo
+
+---
+
+## Open Questions
+
+1. ViePilot hiện tại hỗ trợ Codex theo cơ chế nào? (CLI wrapper, API, hay file convention?)
+2. Agent nào nên ưu tiên hỗ trợ trước? (Claude Code, Aider, hay GitHub Copilot?)
+3. Mô hình integration: ViePilot gọi agent như thế nào — cùng CLI pattern hay adapter layer?
+4. Có cần abstraction layer (agent-agnostic interface) không?
+5. Phạm vi support: code generation only, hay cả agentic execution (file edit, terminal)?
+
+---
+
+## Product Horizon
+
+### MVP
+- Hỗ trợ **Claude Code** (Anthropic CLI) — CLI pattern tương tự Codex (MVP)
+- Hỗ trợ **Aider** — CLI-native, OSS, Git-native (MVP)
+- Abstraction: config-based agent selection (MVP)
+
+### Post-MVP
+- Hỗ trợ **GitHub Copilot CLI** — `gh copilot` (Post-MVP)
+- Hỗ trợ **Goose** (Block) — MCP-compatible (Post-MVP)
+- Hỗ trợ **OpenCode** (Post-MVP)
+
+### Future
+- ACP-based integration cho IDE agents (Future)
+- MCP server để expose ViePilot tools sang các agent (Future)
+- Agent routing: tự động chọn agent phù hợp theo task type (Future)
+
+### Non-goals (MVP)
+- Không hỗ trợ IDE-only agents (Cursor, Windsurf) ở MVP
+- Không hỗ trợ web-only agents (v0, Bolt.new)
+- Không build MCP server ở MVP
+
+---
+
+## Research Notes
+
+### Candidates Được Đề Xuất Theo Priority
+
+**Priority 1: Claude Code**
+- `claude` CLI — tương tự pattern của `codex`
+- SDK: `@anthropic-ai/claude-agent-sdk`
+- Supports: file editing, terminal, MCP, remote sessions
+- Pricing: subscription (user đã có nếu dùng Claude Code)
+
+**Priority 2: Aider**
+- `aider` CLI — Python, OSS, Apache 2.0
+- Git-native: tự commit sau mỗi change
+- Multi-LLM: Claude, OpenAI, local models
+- Strong community: 100K+ GitHub stars
+
+**Priority 3: GitHub Copilot CLI**
+- `gh copilot` — requires GitHub Copilot subscription
+- GA: Feb 2026
+- Custom agents support
+- MCP integration
+
+**Key Insight:** Tất cả Tier 1 agents đều có CLI interface và hỗ trợ MCP — ViePilot có thể build một adapter layer chung dựa trên:
+1. CLI command pattern
+2. Config file location
+3. Prompt/task passing convention
+
+---
+
+## Action Items
+
+- [ ] Xem lại cơ chế hiện tại ViePilot gọi Codex (source code)
+- [ ] Quyết định: adapter pattern hay agent-specific skills
+- [ ] Prototype integration với Claude Code trước (priority 1)
+- [ ] Tạo `docs/dev/agents.md` — agent support matrix
+
+---
+
+## Session Notes
+
+Research conducted 2026-04-02. Landscape nhanh thay đổi — re-verify agent CLI APIs trước khi implement.
+
+---
+
+## Project meta intake (FEAT-009)
+
+_Chưa hoàn tất — cần binding profile trước khi close session._

package/docs/user/features/architect-design-mode.md

@@ -0,0 +1,170 @@
+# Architect Design Mode (FEAT-011)
+
+`/vp-brainstorm --architect` bật chế độ brainstorm kiến trúc với live HTML generation — workspace trực quan để review, chỉnh sửa, và trình bày trước khi chạy `/vp-crystallize`.
+
+## Overview
+
+Architect Design Mode giải quyết gap: brainstorm architecture thông thường chỉ là text/markdown. Không có visualization trực quan → khó detect lỗi sớm, khó align với stakeholders.
+
+**Architect Mode tạo ra:**
+- HTML workspace với 7 sections (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map)
+- Machine-readable `notes.md` với YAML schema (decisions, open_questions, tech_stack)
+- Mermaid.js diagrams tự động render trong browser
+- Incremental updates khi decisions thay đổi — không tái tạo toàn bộ workspace
+
+## Activation
+
+### Explicit flag
+```
+/vp-brainstorm --architect
+```
+Kích hoạt ngay khi bắt đầu phiên. ViePilot sẽ tạo workspace và bắt đầu generate HTML sau mỗi major decision.
+
+### Auto-activate heuristic
+Khi đang brainstorm thông thường, ViePilot theo dõi:
+- **Component/service mentions**: tên theo pattern `{capitalized} Service|API|Module|Layer|Server|Database`
+- **Stack mentions**: bất kỳ technology keyword nào (React, Node.js, PostgreSQL, Kafka, AWS, Docker, v.v.)
+
+Khi **≥3 components** hoặc **≥1 stack suggestion** → prompt:
+```
+🏗️ Tôi nhận thấy bạn đang thiết kế kiến trúc với nhiều components.
+Kích hoạt Architect Design Mode để tôi tạo HTML visualization không?
+1. Có — tạo workspace và generate initial HTML
+2. Không — tiếp tục text-only
+```
+
+## HTML Artifacts
+
+### Workspace layout
+
+```
+.viepilot/architect/{session-id}/
+  index.html         # Hub: sidebar nav → tất cả sections
+  architecture.html  # System diagram (Mermaid) + component table
+  data-flow.html     # Sequence/flow diagrams
+  decisions.html     # ADR log: Date | Decision | Options | Chosen | Rationale | Status
+  tech-stack.html    # Layer-by-layer: frontend, backend, infra, data, DevOps
+  tech-notes.html    # 3 columns: Assumptions | Risks | Open Questions
+  feature-map.html   # Features: layer, phase, MVP/Post-MVP/Future tags
+  style.css          # Shared: dark/light mode, .updated highlight, Mermaid container
+  notes.md           # Machine-readable YAML (xem Schema bên dưới)
+```
+
+### File descriptions
+
+| File | Nội dung | Diagram type |
+|------|----------|-------------|
+| `index.html` | Hub: card links tới 6 sections | — |
+| `architecture.html` | System components, service boundaries | `graph TD` hoặc `C4Context` |
+| `data-flow.html` | Request/event flows | `sequenceDiagram` hoặc `flowchart LR` |
+| `decisions.html` | ADR log với status badges | — |
+| `tech-stack.html` | Layer table + alternatives | — |
+| `tech-notes.html` | 3 cột: Assumptions, Risks, Open Questions | — |
+| `feature-map.html` | Feature list + mindmap | `mindmap` hoặc `quadrantChart` |
+
+### Opening the workspace
+Mở `index.html` trong browser để xem toàn bộ workspace. Các trang tự liên kết nhau qua sidebar nav.
+
+### Dark/light mode
+Mỗi trang có nút toggle dark/light. Mermaid diagrams tự điều chỉnh theme.
+
+## Dialogue Cadence
+
+Sau **mỗi major decision** trong Architect Mode:
+1. ViePilot cập nhật HTML section liên quan (chỉ section đó — không tái tạo toàn bộ)
+2. Thêm `class="updated"` + `data-updated="true"` → CSS highlight (yellow left border + "updated" badge)
+3. Update `notes.md` YAML (`updated` date + entry tương ứng)
+
+**Ví dụ luồng:**
+```
+User: "Chọn PostgreSQL cho database vì cần ACID compliance"
+→ AI update decisions.html (thêm row D001)
+→ AI update tech-stack.html (Database layer)
+→ AI update notes.md (decisions[] + tech_stack.database)
+→ Highlight các section đã thay đổi với .updated class
+```
+
+## `/review-arch` command
+
+Gõ `/review-arch` trong phiên Architect Mode để xem tóm tắt:
+
+```
+📊 Architecture Review
+
+Decisions so far:
+| ID   | Topic           | Chosen      | Status   |
+|------|-----------------|-------------|----------|
+| D001 | Database        | PostgreSQL  | decided  |
+| D002 | Caching layer   | Redis       | decided  |
+| D003 | Queue system    | —           | open     |
+
+Open Questions:
+- Q001: Caching layer Redis hay Memcached? (due: before crystallize)
+- Q002: Deploy ECS hay Kubernetes? (due: open)
+
+Tiếp tục brainstorm không?
+```
+
+## Crystallize Integration
+
+### Step 1D — Consume Architect Artifacts
+
+Khi chạy `/vp-crystallize`, Step 1D tự động đọc `.viepilot/architect/`:
+
+1. **decisions[]** → import vào `.viepilot/ARCHITECTURE.md` section `## Architecture Decisions (from Architect Mode)`
+2. **tech_stack{}** → dùng làm authoritative stack (override brainstorm text nếu conflict; khi có conflict → hỏi user)
+3. **open_questions[] status=open** → surface trước khi tiếp tục
+4. **feature-map.html** → cross-check với `## Product Horizon` trong brainstorm session
+
+**Soft suggestion** (không block) khi architect dir chưa có nhưng brainstorm có ≥5 services:
+```
+💡 Bạn muốn quay lại /vp-brainstorm --architect để tạo visualization trước không?
+1. Có — quay lại architect mode
+2. Không — tiếp tục crystallize với text-only brainstorm
+```
+
+## notes.md Schema
+
+File `notes.md` trong architect workspace là machine-readable YAML + Markdown:
+
+```yaml
+---
+session_id: {id}
+project: {name}
+created: {date}
+updated: {date}
+---
+## decisions
+- id: D001
+  topic: Database choice
+  options: [PostgreSQL, MongoDB, DynamoDB]
+  chosen: PostgreSQL
+  rationale: ACID compliance needed for financial data
+  status: decided  # decided | open | deferred
+
+## open_questions
+- id: Q001
+  question: Caching layer Redis hay Memcached?
+  context: High read traffic expected
+  due: before crystallize
+
+## tech_stack
+  frontend: React + TypeScript
+  backend: Node.js + Express
+  database: PostgreSQL
+  infra: AWS ECS + RDS
+  devops: GitHub Actions + Terraform
+```
+
+`crystallize` đọc file này trực tiếp — giữ schema nhất quán để import hoạt động đúng.
+
+## Tips & Best Practices
+
+1. **Bắt đầu với Architecture** — chốt component boundaries trước khi đi vào data-flow và decisions
+2. **Dùng `/review-arch` thường xuyên** — đặc biệt khi có nhiều open_questions; resolve trước khi crystallize
+3. **Decisions.html là lịch sử** — không xóa rows cũ; chỉ update `status` khi quyết định thay đổi
+4. **tech_stack{} là authoritative** — crystallize sẽ dùng đây làm stack chính; đảm bảo đúng trước khi `/vp-crystallize`
+5. **Mở index.html trong browser** — workspace được thiết kế để share với stakeholders trực tiếp từ file
+
+---
+_Cập nhật: 1.11.0 (FEAT-011 — Architect Design Mode)_

package/docs/user/features/ui-direction.md

@@ -84,12 +84,85 @@ Gợi ý: kèm tên sản phẩm hoặc ngữ cảnh trong cùng tin nhắn (vd.
 
 **Khác `/research {chủ đề}`**: lệnh tự do chỉ cần research ngắn và quay lại topic; **`/research-ui`** bắt buộc 3 phase + log + chỉnh prototype khi phù hợp.
 
+## Background Extraction (ENH-026)
+
+Kể từ **1.10.0**, bạn **không cần** gọi `--ui` để thu thập ý tưởng UI — `/vp-brainstorm` tự động nhận diện tín hiệu UI trong mọi phiên.
+
+### Cách hoạt động
+
+| Bước | Mô tả |
+|------|-------|
+| **1. Silent detection** | AI theo dõi các keyword UI (`màu`, `layout`, `page`, `button`, `giao diện`, v.v.) trong suốt hội thoại — không interrupt |
+| **2. Accumulation** | Khi ≥3 keyword xuất hiện, ý tưởng UI được ghi vào buffer ngầm (`ui_idea_buffer`) |
+| **3. Surface** | Khi topic kết thúc, bạn gõ `/save`/`/review`, hoặc ≥5 signals tích luỹ → AI đề xuất lưu |
+
+### Ví dụ thực tế
+
+Bạn đang brainstorm về tính năng đặt vé và nhắc đến:
+
+> "tôi muốn **nút** màu **xanh**, **màn hình** danh sách vé cần rõ ràng, và **form** thanh toán đơn giản"
+
+→ 3 keywords (`nút`, `màn hình`, `form`) → threshold đạt → buffer bắt đầu tích luỹ im lặng.
+
+Khi topic kết thúc, AI hỏi:
+
+```
+💡 Tôi phát hiện một số ý tưởng UI trong phiên này:
+- Nút màu xanh (CTA)
+- Màn hình danh sách vé — yêu cầu layout rõ ràng
+- Form thanh toán — thiết kế đơn giản
+
+Bạn muốn:
+1. Lưu vào ui-direction/notes.md (background extraction)
+2. Lưu + kích hoạt UI Direction Mode để generate HTML direction
+3. Bỏ qua, tiếp tục brainstorm
+```
+
+### Khác biệt với `--ui` mode
+
+| | Background Extraction | UI Direction Mode (`--ui`) |
+|---|---|---|
+| **Kích hoạt** | Tự động (silent) | Chủ động (`--ui` hoặc chọn Option 2) |
+| **Artifact tạo ra** | `notes.md` (`## Background extracted ideas`) | `index.html`, `style.css`, `notes.md` |
+| **Gián đoạn brainstorm?** | Không (non-blocking) | Có thể (chuyển sang UI mode) |
+| **Dùng khi** | UI là phụ, main focus là domain/arch | UI là trọng tâm phiên |
+
+## Crystallize Integration
+
+`/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+
+### Hard gate (ENH-026)
+
+Kể từ **1.10.0**, Step 1A áp dụng **hard gate** khi phát hiện UI scope trong brainstorm nhưng thiếu artifacts:
+
+```
+⚠️ UI Direction artifacts missing
+
+Phiên brainstorm cho thấy dự án có UI scope nhưng `.viepilot/ui-direction/` chưa có artifacts.
+
+1. Quay lại /vp-brainstorm --ui để tạo direction trước (khuyến nghị)
+2. Tiếp tục với assumptions — ghi vào ARCHITECTURE.md và proceed
+```
+
+**Option 1** (khuyến nghị): quay lại brainstorm và tạo direction trước — đảm bảo UI vision được capture đầy đủ.
+
+**Option 2** (bypass): crystallize tiếp tục nhưng ghi block `## UI Direction Assumptions` vào `.viepilot/ARCHITECTURE.md`:
+
+```markdown
+## UI Direction Assumptions
+> Auto-generated by crystallize (ENH-026 gate bypassed by user)
+- UI scope detected in brainstorm but no ui-direction artifacts present
+- Proceeding without visual direction; architecture decisions may need UI review later
+```
+
+Gate **chỉ kích hoạt** khi `ui_scope_detected = true` (≥3 UI signals trong brainstorm sessions). Dự án không có UI scope đi qua bình thường.
+
 ## Flow khuyến nghị
-1. `/vp-brainstorm --ui`
-2. Chọn legacy hoặc multi-page theo số màn hình.
+1. `/vp-brainstorm` (mọi phiên — background extraction hoạt động im lặng)
+2. Hoặc `/vp-brainstorm --ui` nếu UI là trọng tâm.
 3. (Optional) `/research-ui` để chạy walkthrough và nâng cấp prototype + `notes.md`.
 4. Mỗi thay đổi page → cập nhật HTML + **hub + `## Pages inventory`** trong cùng một lượt.
-5. `/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+5. `/vp-crystallize` — Step 1A hard gate kiểm tra artifacts trước khi tiến hành.
 
 ## Kiểm tra nhanh (optional)
 
@@ -98,3 +171,6 @@ node scripts/verify-ui-direction-pages.cjs
 ```
 
 Script báo lỗi nếu có session có `pages/*.html` nhưng thiếu `## Pages inventory` hoặc thiếu tên file page trong `notes.md`.
+
+---
+_Cập nhật: 1.10.0 (ENH-026 — background extraction + crystallize hard gate)_

package/lib/viepilot-install.cjs

@@ -190,6 +190,9 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
       for (const f of ['cli-shared.cjs', 'viepilot-info.cjs', 'viepilot-update.cjs', 'viepilot-install.cjs']) {
         steps.push({ kind: 'copy_file', from: path.join(root, 'lib', f), to: path.join(claudeViepilotDir, 'lib', f) });
       }
+      // BUG-007: copy package.json so resolveViepilotPackageRoot() finds the root
+      // when vp-tools runs from ~/.claude/viepilot/ (CWD ≠ viepilot source repo)
+      steps.push({ kind: 'copy_file', from: path.join(root, 'package.json'), to: path.join(claudeViepilotDir, 'package.json') });
 
       // Rewrite execution_context paths in mirrored skill files
       steps.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.9.10",
+  "version": "1.14.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-brainstorm/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-brainstorm
 description: "Brainstorm session để thu thập ý tưởng, quyết định cho dự án"
-version: 0.6.3
+version: 1.1.0
 ---
 
 <cursor_skill_adapter>
@@ -39,9 +39,14 @@ Hỗ trợ:
 - Landing page layout discovery (hỏi thêm để chốt bố cục)
 - In-session research (research ngay trong phiên brainstorm theo yêu cầu)
 - UI Direction mode: tạo/cập nhật HTML prototype + notes trong `.viepilot/ui-direction/{session-id}/` — hỗ trợ **multi-page** (`pages/{slug}.html` + hub `index.html`) và hook **`## Pages inventory`** trong `notes.md` khi có `pages/` (FEAT-007)
-- **Product horizon (ENH-014):** mọi session phải duy trì **`## Product horizon`** khi thảo luận capability/milestone — tier tags `(MVP)` / `(Post-MVP)` / `(Future)`, non-goals, deferred capabilities; hoặc ghi rõ **single-release / no deferred epics** (contract: `workflows/brainstorm.md`)
+- **Phase assignment (ENH-030):** trong mọi session, features/capabilities được gán trực tiếp vào Phase 1, Phase 2, Phase 3... — không dùng MVP/Post-MVP/Future tiers. Session file lưu trong `## Phases` section.
 - **Project meta intake (FEAT-009):** sau khi **scope locked**, **trước** `Completed` / `/end`, nếu thiếu `.viepilot/META.md` (`viepilot_profile_id`) — chạy Q&A **tuần tự** có proposal; đọc/ghi `~/.viepilot/profile-map.md`; tạo `~/.viepilot/profiles/<slug>.md` + binding theo **`docs/dev/global-profiles.md`**. Nếu đã có profile bound — skip intake mặc định (hỏi đổi nếu cần).
 - **UX walkthrough (FEAT-010 + ENH-019 + ENH-020):** trong **`--ui`**, lệnh **`/research-ui`** hoặc **`/research ui`** chạy 3 phase — mô phỏng **end-user** (kèm **content stress pass** + **stress recipes theo archetype** → **Stress findings**) → **UX designer + web research** → chỉnh `index.html` / `pages/*.html` / `style.css` và ghi **`## UX walkthrough log`** trong `notes.md` (đồng bộ hub + **Pages inventory** khi multi-page).
+- **Background UI extraction (ENH-026):** tự động nhận diện UI signal keywords trong mọi phiên brainstorm (không cần `--ui` flag); silent accumulation buffer; surface để xác nhận khi topic kết thúc, `/save`, hoặc ≥5 signals — không interrupt hội thoại chính.
+- **Architect Design Mode (FEAT-011):** `/vp-brainstorm --architect` hoặc auto-activate khi ≥3 components/services; generate HTML workspace (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map) với 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).
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -75,9 +80,9 @@ Key steps:
 6. Nếu topic cần UI/UX: tạo/cập nhật UI Direction artifacts trong `.viepilot/ui-direction/{session-id}/` — legacy: `index.html` + `style.css` + `notes.md`; multi-page: thêm `pages/*.html`, `index.html` làm hub, và sau mỗi thay đổi page cập nhật **`## Pages inventory`** trong `notes.md` (xem `docs/user/features/ui-direction.md`)
 6b. Khi user gõ **`/research-ui`** hoặc **`/research ui`** trong phiên UI: làm đúng **`workflows/brainstorm.md`** (FEAT-010) — không gộp vào bước research ngắn thường lệ
 7. Nếu user yêu cầu research hoặc cần làm rõ quyết định: research ngay trong session và quay lại topic
-8. Khi topic thêm/sửa capability hoặc release scope: cập nhật **`## Product horizon`** trong session (merge, không xóa tier tags im lặng) theo `workflows/brainstorm.md`
+8. Khi topic thêm/sửa capability: cập nhật **`## Phases`** trong session theo `workflows/brainstorm.md`
 9. Trước khi hoàn tất phiên: **bước 5 — Project meta intake (FEAT-009)** trong `workflows/brainstorm.md` khi binding thiếu; sequential Q&A + profile-map disambiguation + ghi global profile + `.viepilot/META.md`
-10. Save session with structured format (bao gồm **`## Project meta intake (FEAT-009)`**, research notes + UI direction references + **Product horizon** khi có)
+10. Save session with structured format (bao gồm **`## Project meta intake (FEAT-009)`**, research notes + UI direction references + **`## Phases`**)
 11. Suggest next action: `/vp-crystallize`
 </process>
 
@@ -92,7 +97,7 @@ Key steps:
 - [ ] UI Direction artifacts created/updated when UI mode is active
 - [ ] Multi-page sessions: hub links + `## Pages inventory` stay in sync with `pages/*.html`
 - [ ] **FEAT-010 + ENH-019 + ENH-020**: `/research-ui` (khi `--ui`) chạy đủ 3 phase, gồm **content stress pass** + **archetype recipes** + **`## UX walkthrough log`** (có **Stress findings**) khi có chỉnh prototype
-- [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement) khi scope được thảo luận
+- [ ] `## Phases` present với Phase 1 có nội dung thật khi scope được thảo luận
 - [ ] **FEAT-009**: intake hoàn tất hoặc binding đã có **hoặc** waiver có lý do trước Completed; session ghi **`## Project meta intake (FEAT-009)`**
 - [ ] Next steps suggested
 </success_criteria>

package/skills/vp-crystallize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-crystallize
 description: "Chuyển đổi brainstorm thành executable artifacts"
-version: 0.5.2
+version: 0.8.0
 ---
 
 <cursor_skill_adapter>
@@ -41,7 +41,7 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 ├── architecture/        # ENH-022: *.mermaid sidecars (mirror fenced diagrams)
 ├── PROJECT-CONTEXT.md   # Domain knowledge + `<product_vision>` (phased scope)
 ├── SYSTEM-RULES.md      # Coding rules & standards
-├── ROADMAP.md           # MVP phases & tasks + **Post-MVP / Product horizon** block (mandatory)
+├── ROADMAP.md           # Phases & tasks in order from phases_inventory
 ├── TRACKER.md           # Progress tracking
 ├── HANDOFF.json         # Machine-readable state
 └── schemas/             # Database, API, Kafka schemas
@@ -65,6 +65,12 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 - `.viepilot/STACKS.md` (project-local index to global cache)
 
 **After:** Ready for `/vp-auto`
+
+**UI direction hard gate (ENH-026):**
+- Step 1A scans brainstorm for UI signal keywords; if ≥3 signals detected + no artifacts → **STOP** with 2-option dialogue (go back to brainstorm --ui OR proceed with assumptions written to ARCHITECTURE.md). Enforces direction-first workflow before crystallize proceeds.
+
+**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.
 </objective>
 
 <execution_context>
@@ -93,8 +99,8 @@ Ask user for (confirm proposals từ profile nếu có):
 - Load all brainstorm sessions
 - Extract: decisions, architecture, schemas, features
 - Extract selected tech stacks
-- **Product horizon (ENH-014):** parse each session **`## Product horizon`**; build consolidated **horizon inventory**; record **single-release** mode when stated; run **validation gate** (missing section vs multi-release discussion → stop and ask; tier conflicts → stop) — full contract: `workflows/crystallize.md` Step 1
-- Validate completeness (tech stack, features, schema/API clarity, **horizon gate**)
+- **Phase assignment (ENH-030):** parse `## Phases` từ brainstorm sessions; build `phases_inventory`; run phase assignment gate (mọi feature phải có phase — full contract: `workflows/crystallize.md` Step 1)
+- Validate completeness (tech stack, features, schema/API clarity, **phase assignment gate**)
 
 ### Step 1A: Consume UI direction (if present)
 - Read `.viepilot/ui-direction/{session-id}/notes.md` first, then `style.css`, then HTML:
@@ -152,7 +158,7 @@ Ask user for (confirm proposals từ profile nếu có):
 - Business rules
 - Conventions
 - Constraints
-- Fill **`<product_vision>`** from template (`templates/project/PROJECT-CONTEXT.md`): MVP boundary, Post-MVP / Future themes, anti-goals — aligned with brainstorm horizon + Step 1 inventory
+- Fill **`<product_vision>`** from template (`templates/project/PROJECT-CONTEXT.md`): Project scope, Phase overview, anti-goals — aligned with brainstorm `## Phases` + Step 1 phases_inventory
 
 ### Step 6: Generate SYSTEM-RULES.md
 - Architecture rules
@@ -165,9 +171,9 @@ Ask user for (confirm proposals từ profile nếu có):
 - Stack-specific rules from cache
 
 ### Step 7: Generate ROADMAP.md
-- Use `templates/project/ROADMAP.md` — **executable MVP phases** first (tasks, criteria, verification)
-- **Mandatory `## Post-MVP / Product horizon`:** epic-level deferred work from horizon inventory **or** explicit single-release statement (no silent omission)
-- **Self-check before finalize:** non-empty horizon inventory must appear in ROADMAP; if mismatch → stop and ask user — see `workflows/crystallize.md` Step 7
+- Use `templates/project/ROADMAP.md` — phases in order (Phase 1, Phase 2...) from `phases_inventory`; no Post-MVP block
+- Each phase: tasks, acceptance criteria, verification commands
+- **Self-check before finalize:** all phases from phases_inventory appear in ROADMAP; if mismatch → stop and ask user — see `workflows/crystallize.md` Step 7
 
 ### Step 8: Generate schemas/
 - database-schema.sql
@@ -201,9 +207,9 @@ Ask user for (confirm proposals từ profile nếu có):
 - [ ] All artifacts created in .viepilot/
 - [ ] PROJECT-META.md has complete metadata
 - [ ] SYSTEM-RULES.md has all standards
-- [ ] Step 1 horizon extracted or explicit single-release recorded; validation gate satisfied
+- [ ] Step 1 phase assignment gate satisfied (phases_inventory recorded, all features assigned)
 - [ ] PROJECT-CONTEXT.md includes populated **`<product_vision>`** (template placeholders filled from brainstorm)
-- [ ] ROADMAP.md has MVP phases with tasks **and** mandatory Post-MVP / horizon block (or explicit single-release statement)
+- [ ] ROADMAP.md has phases with tasks in order from phases_inventory
 - [ ] TRACKER.md initialized
 - [ ] Project files created
 - [ ] Git committed