viepilot 1.2.0 → 1.6.1

package/skills/vp-auto/SKILL.md

@@ -35,6 +35,15 @@ Pauses at control points:
 - `CHANGELOG.md` (if feature/fix)
 - `.viepilot/ROADMAP.md` when task completion changes phase progress/status
 
+**Git persistence gate before PASS (BUG-003):**
+- Task/phase cannot be marked PASS if git is not durably persisted.
+- Required checks:
+  - `git status --porcelain` must be empty
+  - upstream branch must exist (`git rev-parse ... @{u}`)
+  - no unpushed commits (`git rev-list --count @{u}..HEAD` equals `0`)
+- Recommended single check: `node bin/vp-tools.cjs git-persistence --strict`
+- On failure: route to control point (retry commit/push, rollback, or stop).
+
 **Mandatory task decomposition before implementation:**
 - Objective with concrete expected outcome
 - Exact file paths to create/modify

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.3.0
+version: 0.4.0
 ---
 
 <cursor_skill_adapter>
@@ -25,7 +25,8 @@ Hỗ trợ:
 - Xem lại session trước đó
 - 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}/`
+- 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`)
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -56,10 +57,11 @@ Key steps:
 3. Load context if continuing
 4. Run interactive Q&A với topic-based structure
 5. Nếu topic là landing page: hỏi thêm bố cục + tham khảo `21st.dev` để đề xuất section/components
-6. Nếu topic cần UI/UX: tạo/cập nhật UI Direction artifacts (`index.html`, `style.css`, `notes.md`) trong `.viepilot/ui-direction/{session-id}/`
+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`)
 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. Save session with structured format (bao gồm research notes + UI direction references khi có)
-9. Suggest next action: `/vp-crystallize`
+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`
+9. Save session with structured format (bao gồm research notes + UI direction references + **Product horizon** khi có)
+10. Suggest next action: `/vp-crystallize`
 </process>
 
 <success_criteria>
@@ -71,5 +73,7 @@ Key steps:
 - [ ] 21st.dev references included when relevant
 - [ ] Research can be executed inside the same brainstorm session
 - [ ] UI Direction artifacts created/updated when UI mode is active
+- [ ] Multi-page sessions: hub links + `## Pages inventory` stay in sync with `pages/*.html`
+- [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement) khi scope được thảo luận
 - [ ] 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.3.0
+version: 0.4.0
 ---
 
 <cursor_skill_adapter>
@@ -25,9 +25,9 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 ├── AI-GUIDE.md          # Navigation cho AI
 ├── PROJECT-META.md      # Metadata dự án
 ├── ARCHITECTURE.md      # System design
-├── PROJECT-CONTEXT.md   # Domain knowledge
+├── PROJECT-CONTEXT.md   # Domain knowledge + `<product_vision>` (phased scope)
 ├── SYSTEM-RULES.md      # Coding rules & standards
-├── ROADMAP.md           # Phases & tasks
+├── ROADMAP.md           # MVP phases & tasks + **Post-MVP / Product horizon** block (mandatory)
 ├── TRACKER.md           # Progress tracking
 ├── HANDOFF.json         # Machine-readable state
 └── schemas/             # Database, API, Kafka schemas
@@ -75,12 +75,15 @@ Ask user for:
 - Load all brainstorm sessions
 - Extract: decisions, architecture, schemas, features
 - Extract selected tech stacks
-- Validate completeness
+- **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**)
 
 ### Step 1A: Consume UI direction (if present)
-- Read `.viepilot/ui-direction/{session-id}/notes.md`, `index.html`, `style.css`
-- Carry approved layout/component decisions into architecture + roadmap artifacts
-- Mark assumptions explicitly if direction artifacts are missing
+- Read `.viepilot/ui-direction/{session-id}/notes.md` first, then `style.css`, then HTML:
+  - **Multi-page:** if `pages/*.html` exists → require `## Pages inventory` in `notes.md`, validate it lists every page file, read each `pages/*.html` plus hub `index.html` for navigation.
+  - **Legacy:** no `pages/` → read `index.html` + `style.css` as before.
+- Carry approved layout/component decisions into architecture + roadmap artifacts; **architecture must reference all pages** from inventory when multi-page.
+- Mark assumptions explicitly if direction artifacts are missing or inventory/files mismatch.
 
 ### Step 1B: Official stack research (mandatory)
 - For every selected stack, research official docs and authoritative sources
@@ -119,6 +122,7 @@ Ask user for:
 - 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
 
 ### Step 6: Generate SYSTEM-RULES.md
 - Architecture rules
@@ -131,10 +135,9 @@ Ask user for:
 - Stack-specific rules from cache
 
 ### Step 7: Generate ROADMAP.md
-- Break into phases
-- Define tasks per phase
-- Set acceptance criteria
-- Add verification checkpoints
+- 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
 
 ### Step 8: Generate schemas/
 - database-schema.sql
@@ -168,7 +171,9 @@ Ask user for:
 - [ ] All artifacts created in .viepilot/
 - [ ] PROJECT-META.md has complete metadata
 - [ ] SYSTEM-RULES.md has all standards
-- [ ] ROADMAP.md has phases with tasks
+- [ ] Step 1 horizon extracted or explicit single-release recorded; validation gate satisfied
+- [ ] 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)
 - [ ] TRACKER.md initialized
 - [ ] Project files created
 - [ ] Git committed

package/skills/vp-info/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: vp-info
+description: "Hiển thị phiên bản ViePilot, npm latest, danh sách skills/workflows qua vp-tools"
+version: 0.1.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-info`, `/vp-info`, "viepilot version", "phiên bản viepilot", "skills list bundle"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Chạy **`vp-tools info`** để lấy metadata bundle ViePilot (không cần `.viepilot/` trong project đích).
+
+**Output hữu ích cho agent:**
+- `installedVersion`, `packageName`, `packageRoot`
+- `latestNpm` (ok + version hoặc lỗi mạng/registry)
+- `gitHead` (nếu clone có git)
+- `skills[]`: `id`, `version`, `relativePath`
+- `workflows[]`: `id`, `relativePath`, `note`
+
+Dùng **`vp-tools info --json`** khi cần parse hoặc so sánh phiên bản trong script.
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/bin/vp-tools.cjs
+</execution_context>
+
+<process>
+
+### Step 1: Resolve CLI
+Ưu tiên theo thứ tự:
+1. `vp-tools info` — khi ViePilot đã có trên `PATH` (npm global hoặc shim).
+2. `node <viepilot-package>/bin/vp-tools.cjs info` — từ repo clone hoặc `node_modules/viepilot`.
+
+### Step 2: Chạy lệnh
+```bash
+vp-tools info
+# hoặc
+vp-tools info --json
+```
+
+### Step 3: Diễn giải JSON (khi dùng `--json`)
+- **`packageRoot`**: gốc package `viepilot` CLI đang resolve được.
+- **`installedVersion`**: semver trong `package.json` của bundle đó.
+- **`latestNpm`**: `{ ok, version }` hoặc `{ ok: false, error }`.
+- **`skills`**: inventory skill trong `skills/*/SKILL.md` (version từ frontmatter).
+- **`workflows`**: file `workflows/*.md`.
+
+### Step 4: Lỗi thường gặp
+Nếu báo không tìm thấy package root: cài global (`npm i -g viepilot`), hoặc chạy từ project có dependency `viepilot`, hoặc trỏ thẳng tới `bin/vp-tools.cjs` trong clone.
+</process>
+
+<success_criteria>
+- [ ] Đã gọi đúng subcommand `info` (hoặc `--json` khi cần parse)
+- [ ] Nêu rõ `installedVersion` và (nếu có) `latestNpm.version`
+- [ ] Khi user hỏi “có những skill nào trong bundle”, tóm tắt từ `skills[]` hoặc output bảng CLI
+</success_criteria>

package/skills/vp-update/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: vp-update
+description: "Nâng cấp package viepilot qua npm (dry-run, --yes, --global) qua vp-tools"
+version: 0.1.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-update`, `/vp-update`, "upgrade viepilot", "cập nhật viepilot npm"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Chạy **`vp-tools update`** để lên kế hoạch và (khi được xác nhận) thực thi `npm` nâng cấp `viepilot`.
+
+**Ràng buộc an toàn:**
+- **Non-interactive** (CI, agent không TTY): bắt buộc **`--dry-run`** hoặc **`--yes`**; nếu không sẽ exit lỗi.
+- Luôn ưu tiên **`--dry-run`** trước khi apply, trừ khi user đã yêu cầu rõ apply.
+
+**Phân biệt target:** trong repo **không phải** ViePilot nhưng có `node_modules/viepilot`, lệnh có thể cập nhật **local dependency**. Muốn chỉ nâng **global**, thêm **`--global`**.
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/bin/vp-tools.cjs
+</execution_context>
+
+<process>
+
+### Step 1: Dry run (mặc định khi tự động)
+```bash
+vp-tools update --dry-run
+```
+Đọc output: planned npm command, phiên bản hiện tại vs latest, cảnh báo ambiguous/global.
+
+### Step 2: Apply (sau khi user đồng ý hoặc đã yêu cầu rõ)
+```bash
+vp-tools update --yes
+```
+Hoặc ép global:
+```bash
+vp-tools update --global --dry-run
+vp-tools update --global --yes
+```
+
+### Step 3: Interactive
+Nếu terminal tương tác và **không** có `--yes`, CLI có thể hỏi xác nhận trước khi chạy npm.
+
+### Step 4: Rollback gợi ý
+Output dry-run/update thường gợi ý `npm install -g viepilot@<previous>` — giữ phiên bản cũ từ `vp-tools info` nếu cần hoàn tác.
+</process>
+
+<success_criteria>
+- [ ] Không chạy apply trong non-interactive mà thiếu `--yes`
+- [ ] Nêu rõ target (local vs global) khi user đang ở project lạ
+- [ ] Ghi nhận khi đã `already up to date` (no-op thành công)
+</success_criteria>

package/templates/project/AI-GUIDE.md

@@ -8,6 +8,8 @@
 | Tôi cần... | Đọc file | Section |
 |------------|----------|---------|
 | Hiểu project làm gì | `PROJECT-CONTEXT.md` | `<domain_knowledge>` |
+| Tầm nhìn & scope theo pha (MVP / Post-MVP / Future) | `PROJECT-CONTEXT.md` | `<product_vision>` |
+| Roadmap sau MVP & horizon (không chỉ task hiện tại) | `ROADMAP.md` | Sections Post-MVP / Future / product horizon |
 | Biết tech stack | `ARCHITECTURE.md` | `## Technology Decisions` |
 | Xem service nào làm gì | `ARCHITECTURE.md` | `## Services` |
 | Biết đang ở phase nào | `TRACKER.md` | `## Current State` |
@@ -36,20 +38,28 @@ Chỉ đọc:
 Đọc theo thứ tự:
 1. AI-GUIDE.md (file này)
 2. TRACKER.md → biết đang ở đâu
-3. ROADMAP.md → task hiện tại
-4. SYSTEM-RULES.md → coding rules
-5. Schema file nếu cần
+3. PROJECT-CONTEXT.md → <product_vision> + phased scope (đọc TRƯỚC khi khóa thiết kế chi tiết)
+4. ROADMAP.md → skim Post-MVP / Future / horizon, rồi task hiện tại
+5. SYSTEM-RULES.md → coding rules
+6. Schema file nếu cần
 ```
 
 ### Full Context (cho architecture decisions)
 ```
-Đọc thêm:
-1. Standard Context +
-2. ARCHITECTURE.md
-3. PROJECT-CONTEXT.md
-4. Brainstorm session gốc (nếu cần rationale)
+Đọc theo thứ tự:
+1. AI-GUIDE.md + TRACKER.md
+2. PROJECT-CONTEXT.md → domain + <product_vision> (đầy đủ)
+3. ROADMAP.md → MVP phases + Post-MVP / horizon blocks
+4. ARCHITECTURE.md
+5. SYSTEM-RULES.md
+6. Brainstorm session gốc (nếu cần rationale chi tiết, đặc biệt cho deferred capabilities)
 ```
 
+### Product vision & roadmap horizon (trước khi “lock” architecture)
+
+- **Không** để post-MVP chỉ tồn tại trong file brainstorm: sau `/vp-crystallize`, horizon phải nằm trong `ROADMAP.md` và vision theo pha trong `PROJECT-CONTEXT.md`.
+- Trước task implementation sâu hoặc quyết định kiến trúc lớn: đọc `<product_vision>` và các section horizon trong `ROADMAP.md` **cùng lúc** với task hiện tại — tránh code MVP làm bế tắc bản sau hoặc bỏ sót ràng buộc đã thống nhất.
+
 ## File Relationships
 
 ```
@@ -58,7 +68,10 @@ AI-GUIDE.md (đọc đầu tiên)
      ├── TRACKER.md (state hiện tại)
      │      └── points to → current phase in ROADMAP.md
      │
-     ├── ROADMAP.md (what to do)
+     ├── PROJECT-CONTEXT.md (domain + <product_vision> / phased scope)
+     │      └── read early with → ROADMAP.md horizon blocks
+     │
+     ├── ROADMAP.md (what to do + Post-MVP / Future)
      │      └── tasks reference → schemas/
      │
      ├── SYSTEM-RULES.md (how to code)
@@ -67,8 +80,7 @@ AI-GUIDE.md (đọc đầu tiên)
      ├── ARCHITECTURE.md (system design)
      │      └── decisions from → PROJECT-CONTEXT.md
      │
-     └── PROJECT-CONTEXT.md (domain knowledge)
-            └── extracted from → docs/brainstorm/
+     └── docs/brainstorm/ (session rationale; horizon đã mirror vào ROADMAP + PROJECT-CONTEXT)
 ```
 
 ## When Creating New Files

package/templates/project/PROJECT-CONTEXT.md

@@ -20,6 +20,28 @@
 {{DATA_RELATIONSHIPS}}
 </domain_knowledge>
 
+<product_vision>
+## Product vision & phased scope
+
+> Aligns with **`ROADMAP.md` → Post-MVP / Product horizon** and brainstorm tier tags `(MVP)` / `(Post-MVP)` / `(Future)`.
+
+### MVP boundary (ship first)
+
+{{MVP_BOUNDARY}}
+
+### Post-MVP themes
+
+{{POST_MVP_VISION}}
+
+### Future / exploratory north star
+
+{{FUTURE_VISION}}
+
+### Anti-goals & explicit non-scope
+
+{{VISION_NON_GOALS}}
+</product_vision>
+
 <conventions>
 ## Naming Conventions
 

package/templates/project/ROADMAP.md

@@ -51,6 +51,33 @@
 
 ---
 
+## Post-MVP / Product horizon
+
+> **Mandatory block (crystallize):** Populate from brainstorm **`## Product horizon`**, or state **single-release** explicitly. Tier tags: `(MVP)` ship first; `(Post-MVP)` after first release; `(Future)` exploratory.
+
+### Horizon mode
+
+{{HORIZON_MODE_LINE}}
+
+### Post-MVP themes (epic-level)
+
+{{POST_MVP_EPICS}}
+
+### Future / exploratory
+
+{{FUTURE_EPICS}}
+
+### Deferred capabilities (from MVP)
+
+{{DEFERRED_CAPABILITIES}}
+
+### Non-goals for MVP (reference)
+
+{{MVP_NON_GOALS_ROADMAP}}
+
+---
+
 ## Notes
 - Created: {{DATE}}
 - Last Updated: {{DATE}}
+- **Horizon:** Keep Post-MVP / Future content in sync with `PROJECT-CONTEXT.md` *Product vision & phased scope* after crystallize.

package/workflows/autonomous.md

@@ -175,6 +175,28 @@ quality_gate:
   - no_lint_errors: true
 ```
 
+#### Git Persistence Gate (BUG-003)
+Before marking a task PASS, require durable git persistence:
+
+```bash
+# Must have no unstaged/staged residue for this task
+git status --porcelain
+
+# Must track an upstream branch
+git rev-parse --abbrev-ref --symbolic-full-name @{u}
+
+# Must have no unpushed commits
+git rev-list --count @{u}..HEAD
+
+# Consolidated check helper (recommended)
+node bin/vp-tools.cjs git-persistence --strict
+```
+
+If any check fails:
+- **Do not** mark task `done`
+- **Do not** advance phase progress/state files as PASS
+- Route to control point (retry commit/push, rollback, or stop)
+
 #### Handle Result
 
 **PASS:**
@@ -253,6 +275,7 @@ When all tasks in phase are done/skipped:
    ```bash
    git push
    git push --tags
+   node bin/vp-tools.cjs git-persistence --strict
    ```
 
 ### 5a. Sync ROADMAP.md (after every phase complete)

package/workflows/brainstorm.md

@@ -41,6 +41,7 @@ Nếu user chọn tiếp tục:
 2. Tóm tắt nội dung đã thảo luận
 3. Xác định các open questions / action items còn lại
 4. Tiếp tục từ điểm dừng
+5. Nếu session đã có section **`## Product horizon`**: tóm tắt nhanh MVP / Post-MVP / Future hiện có; mọi cập nhật sau đó phải **merge** vào section đó (không xóa im lặng, không làm mất tier tags) trừ khi user chủ động yêu cầu thu hẹp/mở rộng scope.
 </step>
 
 <step name="brainstorm_mode">
@@ -74,6 +75,13 @@ Gợi ý các topics để brainstorm:
    - Monitoring
    - Scaling
 
+6. **Product horizon (MVP vs Post-MVP vs Future)** — **bắt buộc duy trì trong session file** khi user thảo luận bất kỳ tính năng / milestone nào:
+   - **Mục tiêu**: tách rõ phạm vi ship đầu tiên với tầm nhìn sau MVP để `/vp-crystallize` không “mất” ý tưởng dài hạn.
+   - **Quy ước tag** (đặt ở cuối dòng bullet): `(MVP)` | `(Post-MVP)` | `(Future)`.
+   - **Non-goals for MVP**: những gì cố tình *không* làm ở bản đầu (tránh hiểu nhầm là quên).
+   - **Deferred capabilities**: tính năng đã thống nhất nhưng **lùi sau MVP** — ghi rõ để crystallize map vào roadmap horizon.
+   - Nếu sản phẩm **single-release** (không có post-MVP): ghi một dòng explicit trong session, ví dụ: `**Scope**: single-release only — no deferred epics.`
+
 ### Interactive Q&A
 Cho mỗi topic:
 1. Đặt câu hỏi cụ thể
@@ -113,26 +121,42 @@ User có thể yêu cầu research ngay trong brainstorm (không cần đổi sk
 Nếu assistant nhận thấy topic có độ mơ hồ cao hoặc rủi ro quyết định sai, assistant nên chủ động đề xuất:
 `Mục này nên research nhanh trước khi chốt, bạn muốn mình research luôn trong phiên này không?`
 
-### UI Direction Mode (design-in-the-loop; FEAT-002)
+### UI Direction Mode (design-in-the-loop; FEAT-002 + FEAT-007)
 Nếu user đang brainstorm cho dự án có UI/UX hoặc yêu cầu thiết kế trực quan:
 
-1. Tạo workspace direction cho phiên hiện tại:
-   - `.viepilot/ui-direction/{session-id}/index.html`
-   - `.viepilot/ui-direction/{session-id}/style.css`
-   - `.viepilot/ui-direction/{session-id}/notes.md`
+**Layout — chọn một:**
+
+- **Legacy (một màn):** `.viepilot/ui-direction/{session-id}/index.html` + `style.css` + `notes.md`.
+- **Multi-page (nhiều màn):** cùng thư mục session, thêm `pages/{slug}.html` cho từng page; `index.html` là **hub** (liên kết tới mọi page). `style.css` shared.
+
+**Quy tắc chung**
+
+1. Tạo workspace direction cho phiên hiện tại (tối thiểu `style.css` + `notes.md`; HTML theo layout đã chọn).
 2. Mỗi lần user đổi requirement/layout/component:
    - Cập nhật trực tiếp HTML/CSS direction
-   - Ghi decision + rationale vào `notes.md` (single source of truth)
+   - Ghi decision + rationale vào `notes.md` (single source of truth cho design intent)
+
+**Hook bắt buộc (multi-page only)**
+
+Khi thư mục `pages/` tồn tại hoặc bất kỳ `pages/*.html` nào được thêm / đổi tên / xóa:
+
+- Cập nhật **hub** `index.html` (nav / danh sách link tới mọi page còn lại).
+- Cập nhật ngay section **`## Pages inventory`** trong `notes.md` (bảng: Slug | File | Title | Purpose | Key sections | Nav to) — phải khớp 100% tập file `pages/*.html` hiện có.
+- Không kết thúc topic / không coi session UI đã “sync” nếu inventory lệch với file trên disk.
+
 3. Nếu user gửi references/components (bao gồm 21st.dev prompt/link), ghi rõ:
    - nguồn tham chiếu
-   - phần UI áp dụng
+   - phần UI áp dụng (page slug nếu multi-page)
    - điều chỉnh theo mục tiêu sản phẩm
 4. Giữ prototype ở mức mô tả định hướng (directional), không ép build production-ready code ở bước brainstorm.
 
+Tham chiếu user: `docs/user/features/ui-direction.md`.
+
 ### Kết thúc mỗi topic
 - Tóm tắt decisions
 - List action items
 - Note open questions
+- Nếu topic thêm/sửa capability: cập nhật **`## Product horizon`** trong bản nháp session (hoặc nhắc user lưu `/save`) với tag tier phù hợp
 </step>
 
 <step name="save_session">
@@ -148,6 +172,30 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 - **Participants**: User, Claude
 - **Status**: In Progress | Completed
 
+## Product horizon
+
+> Single source for **MVP / Post-MVP / Future** scope. Bắt buộc giữ section này khi tiếp tục session; crystallize đọc để không bỏ sót post-MVP.
+
+### MVP (ship first)
+- Capability / theme — `(MVP)`
+- ...
+
+### Post-MVP (after first release)
+- Capability / theme — `(Post-MVP)`
+- ...
+
+### Future / exploratory
+- Idea — `(Future)`
+- ...
+
+### Non-goals for MVP
+- ...
+
+### Deferred capabilities (from MVP)
+- ...
+
+**Scope note (optional):** Nếu không có post-MVP: `Single-release product — no separate horizon epics.`
+
 ## Topics Discussed
 
 ### Topic 1: {Name}
@@ -179,12 +227,14 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
 **UI Direction Artifacts** (if applicable):
 - Session id: {session-id}
+- Layout: legacy (single `index.html`) | multi-page (`pages/*.html` + hub `index.html`)
 - Files:
-  - `.viepilot/ui-direction/{session-id}/index.html`
+  - `.viepilot/ui-direction/{session-id}/index.html` (hub hoặc single-screen)
   - `.viepilot/ui-direction/{session-id}/style.css`
-  - `.viepilot/ui-direction/{session-id}/notes.md`
+  - `.viepilot/ui-direction/{session-id}/notes.md` (must include `## Pages inventory` when `pages/` exists)
+  - `.viepilot/ui-direction/{session-id}/pages/*.html` (when multi-page)
 - Preview focus:
-  - {layout/flow summary}
+  - {layout/flow summary; list each page slug if multi-page}
 
 ---
 
@@ -228,7 +278,7 @@ Next step: /vp-crystallize
 This will transform your brainstorm into:
 - Project structure
 - Architecture documents
-- Development roadmap
+- Development roadmap (MVP phases + **Post-MVP / horizon** when documented above)
 ```
 </step>
 
@@ -247,6 +297,7 @@ User có thể dùng các lệnh trong phiên brainstorm:
 
 <success_criteria>
 - [ ] Session file created với đầy đủ sections
+- [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement)
 - [ ] Decisions có rationale
 - [ ] Open questions tracked
 - [ ] Action items captured

package/workflows/crystallize.md

@@ -80,12 +80,25 @@ For each session file:
 3. Extract database schemas
 4. Extract features/requirements
 5. Extract tech stack choices
+6. **Product horizon (mandatory)** — parse `## Product horizon` when present (contract: `workflows/brainstorm.md`):
+   - Classify bullets under **MVP (ship first)**, **Post-MVP (after first release)**, and **Future / exploratory** using trailing tags `(MVP)` / `(Post-MVP)` / `(Future)` when present.
+   - Capture **Non-goals for MVP** and **Deferred capabilities (from MVP)** as first-class lists (these feed roadmap horizon and architecture constraints).
+   - Record **extensibility / platform notes** that imply deferred work (e.g., plugin model later, multi-tenant after MVP) if written in horizon or architecture sections.
+   - If the session states **single-release only** / **no deferred epics** (see brainstorm scope note), record `horizon_mode: single_release` in working notes for Step 7.
+
+**Consolidate across sessions** into a single **horizon inventory** (dedupe by capability name; if the same capability appears under conflicting tiers → stop and ask the user which tier wins).
+
+**Horizon validation gate (before leaving Step 1):**
+- [ ] Every brainstorm file was checked for `## Product horizon` **or** an explicit in-session single-release / no-deferred statement.
+- [ ] If `## Product horizon` is missing and the session still discusses releases beyond MVP without a single-release statement → stop and ask the user to update the session (e.g. `/vp-brainstorm` save) or confirm **single-release only** for the whole project.
+- [ ] Either **horizon inventory is non-empty** (Post-MVP/Future/deferred items captured) **or** **single-release** is explicitly recorded — no silent default.
 
 Validate completeness:
 - [ ] Tech stack defined
 - [ ] Core features identified
 - [ ] Database schema exists
 - [ ] API requirements clear
+- [ ] Product horizon processed per gate above (inventory or explicit single-release)
 
 If gaps found → ask user to clarify or return to brainstorm.
 </step>
@@ -101,11 +114,16 @@ ls -la .viepilot/ui-direction/ 2>/dev/null
 
 When available, for the selected/latest session:
 - Read `.viepilot/ui-direction/{session-id}/notes.md` first (source of design decisions)
-- Read `index.html` + `style.css` to extract:
-  - layout hierarchy
-  - component candidates
-  - interaction expectations
-- Record how each UI direction item maps into target tech stack implementation plan.
+- If `pages/` exists and contains `*.html`:
+  - Require section **`## Pages inventory`** in `notes.md`; treat it as the **site map** (page count, purpose, navigation).
+  - List all `pages/*.html` and confirm each file is represented in the inventory table (if mismatch → stop and ask user to fix brainstorm artifacts or document assumptions).
+  - Read **each** `pages/{slug}.html` for section structure, components, and interaction hints.
+  - Read hub `index.html` for cross-page navigation intent.
+- Else (legacy single-file layout):
+  - Read `index.html` + `style.css` only (no `pages/`).
+- Always read `style.css` for shared styling constraints.
+- Extract from HTML: layout hierarchy, component candidates, interaction expectations.
+- In architecture / UI plan output, **enumerate every page** from inventory (or state explicitly single-page legacy).
 
 If UI scope is present but artifacts are missing:
 - Warn user and request either:
@@ -177,7 +195,7 @@ Create `.viepilot/AI-GUIDE.md` using template:
 
 Customize with:
 - Project-specific file references
-- Context loading strategy based on project size
+- Context loading strategy based on project size — **preserve template ordering** where `PROJECT-CONTEXT.md` **`<product_vision>`** and **`ROADMAP.md` horizon** (Post-MVP / Future) are read **before** deep implementation / architecture lock; state this explicitly in the generated `AI-GUIDE.md` if you trim sections
 - Quick lookup for project-specific terms
 - Fast stack lookup section:
   - Read `.viepilot/STACKS.md`
@@ -255,14 +273,22 @@ Create `.viepilot/ROADMAP.md` using template:
 `@$HOME/.cursor/viepilot/templates/project/ROADMAP.md`
 
 From brainstorm features/MVP breakdown:
-1. Create phases
+1. Create **executable MVP phases** (what `/vp-auto` can run next; near-term delivery only).
 2. For each phase:
    - Define goal
    - Break into tasks
    - Set acceptance criteria
    - Add verification checkpoints
    - Estimate complexity (S/M/L/XL)
-3. Define dependencies between phases
+3. Define dependencies between MVP phases.
+4. **Post-MVP / product horizon (mandatory section in `.viepilot/ROADMAP.md`):**
+   - After MVP phases, always add a dedicated block (heading e.g. `## Post-MVP / Product horizon` or match the project template’s equivalent) that is **never omitted**:
+     - If Step 1 recorded **single-release** / no deferred epics: state explicitly *e.g.* **Single-release scope — no separate post-MVP epics** and that deferred capabilities are none by confirmation (do not invent future work).
+     - Otherwise: summarize **horizon inventory** items as **epic-level** entries (dependencies, rough sequencing OK; full task breakdown optional).
+   - Where a future epic depends on MVP deliverables, note **dependency links** back to the MVP phase(s) that unlock it.
+5. **ROADMAP self-check before finalize:**
+   - If Step 1 **horizon inventory** is non-empty but the draft ROADMAP **drops** those items or lacks the horizon block → **stop** and ask the user to reconcile (do not ship a roadmap that silently omits post-MVP content from brainstorm).
+   - If brainstorm contained Post-MVP ideas only in free text without `## Product horizon` → you should already have stopped in Step 1; do not proceed to commit ROADMAP.
 </step>
 
 <step name="generate_schemas">
@@ -408,10 +434,11 @@ Note: global stack cache at `~/.viepilot/stacks/` is machine-level knowledge and
 - [ ] All metadata collected
 - [ ] Official research completed for each selected stack
 - [ ] Global stack cache written under ~/.viepilot/stacks/{stack}/
+- [ ] Step 1: product horizon extracted **or** explicit single-release recorded; validation gate satisfied
 - [ ] All artifacts created in .viepilot/
 - [ ] PROJECT-META.md complete
 - [ ] SYSTEM-RULES.md has all standards
-- [ ] ROADMAP.md has phases with tasks
+- [ ] ROADMAP.md has MVP phases with tasks **and** mandatory Post-MVP / horizon block (or explicit single-release statement)
 - [ ] Phase directories created
 - [ ] Project files created
 - [ ] Git committed