viepilot 1.3.1 → 1.8.0

package/lib/viepilot-update.cjs

@@ -0,0 +1,156 @@
+/**
+ * Plan and run `npm` upgrade for the viepilot package (FEAT-008 / vp-tools update).
+ */
+
+const path = require('path');
+const { spawnSync, execFileSync } = require('child_process');
+const viepilotInfo = require('./viepilot-info.cjs');
+
+/**
+ * @returns {string|null} absolute path to global .../node_modules/viepilot
+ */
+function tryGetNpmGlobalViepilotPath() {
+  try {
+    const root = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: 10000,
+      windowsHide: true,
+    }).trim();
+    if (!root) return null;
+    return path.resolve(root, 'viepilot');
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * @param {string} viepilotPackageRoot
+ * @param {boolean} forceGlobal
+ * @param {string|null} globalViepilotPath
+ */
+function classifyInstall(viepilotPackageRoot, forceGlobal, globalViepilotPath) {
+  if (forceGlobal) {
+    return {
+      mode: 'global',
+      cwd: undefined,
+      npmArgs: ['install', '-g', 'viepilot@latest'],
+      ambiguous: false,
+    };
+  }
+  const r = path.resolve(viepilotPackageRoot);
+  if (globalViepilotPath) {
+    const g = path.resolve(globalViepilotPath);
+    if (r === g) {
+      return {
+        mode: 'global',
+        cwd: undefined,
+        npmArgs: ['install', '-g', 'viepilot@latest'],
+        ambiguous: false,
+      };
+    }
+  }
+  const localSuffix = path.join('node_modules', 'viepilot');
+  if (r.endsWith(localSuffix)) {
+    const projectRoot = path.resolve(viepilotPackageRoot, '..', '..');
+    return {
+      mode: 'local',
+      cwd: projectRoot,
+      npmArgs: ['install', 'viepilot@latest'],
+      ambiguous: false,
+    };
+  }
+  return {
+    mode: 'global',
+    cwd: undefined,
+    npmArgs: ['install', '-g', 'viepilot@latest'],
+    ambiguous: true,
+  };
+}
+
+/**
+ * Rough semver compare for x.y.z (numeric segments only).
+ * @returns {-1|0|1|null} null if either side empty
+ */
+function compareSemver(a, b) {
+  if (a == null || b == null || a === '' || b === '') return null;
+  const pa = String(a).split(/[.+]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split(/[.+]/).map((x) => parseInt(x, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da < db) return -1;
+    if (da > db) return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {{ startDir: string, forceGlobal?: boolean }} opts
+ */
+function buildUpdatePlan(opts) {
+  const startDir = opts.startDir;
+  const forceGlobal = Boolean(opts.forceGlobal);
+  const root = viepilotInfo.resolveViepilotPackageRoot(startDir);
+  if (!root) {
+    return { ok: false, error: 'Could not locate viepilot package root' };
+  }
+
+  const installed = viepilotInfo.readInstalledVersion(root);
+  const latestResult = viepilotInfo.fetchLatestNpmVersion();
+
+  if (latestResult.ok && installed && compareSemver(installed, latestResult.version) >= 0) {
+    return {
+      ok: true,
+      alreadyLatest: true,
+      installedVersion: installed,
+      latestVersion: latestResult.version,
+      viepilotRoot: root,
+    };
+  }
+
+  const globalViepilotPath = tryGetNpmGlobalViepilotPath();
+  const layout = classifyInstall(root, forceGlobal, globalViepilotPath);
+  const displayCommand = layout.cwd
+    ? `(cwd ${layout.cwd}) npm ${layout.npmArgs.join(' ')}`
+    : `npm ${layout.npmArgs.join(' ')}`;
+
+  return {
+    ok: true,
+    alreadyLatest: false,
+    installedVersion: installed,
+    latestVersion: latestResult.ok ? latestResult.version : null,
+    latestNpmError: latestResult.ok ? null : latestResult.error,
+    viepilotRoot: root,
+    mode: layout.mode,
+    cwd: layout.cwd,
+    npmArgs: layout.npmArgs,
+    ambiguous: layout.ambiguous,
+    displayCommand,
+  };
+}
+
+/**
+ * @param {object} plan - from buildUpdatePlan (not alreadyLatest)
+ * @returns {{ ok: boolean, code?: number }}
+ */
+function runNpmUpdate(plan) {
+  const r = spawnSync('npm', plan.npmArgs, {
+    cwd: plan.cwd,
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: true,
+  });
+  if (r.status === 0) {
+    return { ok: true };
+  }
+  return { ok: false, code: r.status == null ? 1 : r.status };
+}
+
+module.exports = {
+  tryGetNpmGlobalViepilotPath,
+  classifyInstall,
+  compareSemver,
+  buildUpdatePlan,
+  runNpmUpdate,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.3.1",
+  "version": "1.8.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {
@@ -16,6 +16,7 @@
     "test:watch": "jest --watch",
     "readme:sync": "node scripts/sync-readme-metrics.cjs",
     "lint:cli": "node --check bin/vp-tools.cjs && node --check bin/viepilot.cjs",
+    "verify:ui-direction": "node scripts/verify-ui-direction-pages.cjs",
     "verify:release": "npm run lint:cli && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run verify:release",
     "smoke:published": "node scripts/smoke-published.cjs",

package/skills/vp-audit/SKILL.md

@@ -32,6 +32,10 @@ Auto-detect nếu đang chạy trong viepilot framework repo để thêm framewo
 - `CHANGELOG.md` vs recent git commits
 - Placeholder URLs trong `docs/` (`your-org`, `YOUR_USERNAME`, v.v.)
 - Features mới (từ phases gần đây) chưa có documentation
+- `ARCHITECTURE.md` diagram applicability matrix consistency:
+  - `required` diagrams must have Mermaid content
+  - `optional` diagrams may be omitted/merged with explicit note
+  - `N/A` diagrams must have rationale line
 
 **Tier 3 — Stack Best Practices + Code Quality (mọi project, theo stack detect được):**
 - Detect stacks liên quan từ context/project manifests
@@ -66,7 +70,8 @@ Optional flags:
 - `--silent`    : Only output if issues found
 - `--tier1`     : Run Tier 1 (state consistency) only
 - `--tier2`     : Run Tier 2 (docs drift) only
-- `--tier3`     : Run Tier 3 (framework integrity) only
+- `--tier3`     : Run Tier 3 (stack best-practice) only
+- `--tier4`     : Run Tier 4 (framework integrity) only
 </context>
 
 <process>
@@ -90,6 +95,7 @@ Execute workflow from `@$HOME/.cursor/viepilot/workflows/audit.md`
 # README.md version mention
 # CHANGELOG.md vs recent commits
 # Placeholder URLs in docs/
+# ARCHITECTURE.md diagram matrix consistency (required|optional|N/A)
 ```
 
 **Step 3 — Tier 3**: Stack Best Practices + Code Quality

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
@@ -113,12 +116,20 @@ Ask user for:
 - Services definitions
 - Data flow
 - Technology decisions
+- Build **diagram applicability matrix** for:
+  - `system-overview`, `data-flow`, `event-flows`, `module-dependencies`, `deployment`, `user-use-case`
+- For each type assign status: `required` | `optional` | `N/A`
+- Apply generation policy:
+  - `required` => include concrete Mermaid block
+  - `optional` => allow lightweight/merged representation
+  - `N/A` => keep section heading + one-line rationale
 
 ### Step 5: Generate PROJECT-CONTEXT.md
 - Domain knowledge
 - 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 +142,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,8 +178,11 @@ 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
+- [ ] ARCHITECTURE diagram matrix is present and consistent (`required|optional|N/A`)
 </success_criteria>

package/skills/vp-debug/SKILL.md

@@ -28,6 +28,12 @@ Systematic debugging với persistent state tracking. Giúp track vấn đề qu
 - `continue` - Continue current session
 - `list` - List all sessions
 - `close` - Close current session with resolution
+
+**Architecture diagram intake (ENH-018):**
+- If `.viepilot/ARCHITECTURE.md` has diagram applicability matrix, consume it before deep debugging.
+- Prioritize investigation context from diagrams marked `required`.
+- For `optional` diagrams: use when available; do not block debug flow if missing.
+- For `N/A` diagrams: respect rationale and avoid forcing diagram creation during debug.
 </objective>
 
 <execution_context>
@@ -79,11 +85,12 @@ Execute workflow from `@$HOME/.cursor/viepilot/workflows/debug.md`
 
 ### Key Steps
 1. **Start Session**: Gather problem description
-2. **Hypothesize**: Generate possible causes
-3. **Test**: Run tests to confirm/reject hypotheses
-4. **Track**: Log all findings
-5. **Resolve**: Document fix and root cause
-6. **Close**: Mark session complete
+2. **Load Architecture Context**: Read `.viepilot/ARCHITECTURE.md` matrix status (`required|optional|N/A`) and relevant Mermaid diagrams if present
+3. **Hypothesize**: Generate possible causes
+4. **Test**: Run tests to confirm/reject hypotheses
+5. **Track**: Log all findings
+6. **Resolve**: Document fix and root cause
+7. **Close**: Mark session complete
 </process>
 
 <success_criteria>

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/ARCHITECTURE.md

@@ -8,6 +8,26 @@
 {{SYSTEM_DIAGRAM}}
 ```
 
+## Architecture Diagram Applicability
+
+> Decide diagram depth from brainstorm complexity signals. Do not force all six as detailed by default.
+
+- **Complexity**: {{ARCH_COMPLEXITY_LEVEL}}  <!-- simple | moderate | complex -->
+- **Services/Modules signal**: {{ARCH_SIGNAL_SERVICES}}
+- **Event-driven signal**: {{ARCH_SIGNAL_EVENTS}}
+- **Deployment signal**: {{ARCH_SIGNAL_DEPLOYMENT}}
+- **User-flow signal**: {{ARCH_SIGNAL_USER_FLOWS}}
+- **Integration signal**: {{ARCH_SIGNAL_INTEGRATIONS}}
+
+| Diagram type | Status (`required|optional|N/A`) | Reason |
+|--------------|----------------------------------|--------|
+| system-overview | {{DIAGRAM_STATUS_SYSTEM_OVERVIEW}} | {{DIAGRAM_REASON_SYSTEM_OVERVIEW}} |
+| data-flow | {{DIAGRAM_STATUS_DATA_FLOW}} | {{DIAGRAM_REASON_DATA_FLOW}} |
+| event-flows | {{DIAGRAM_STATUS_EVENT_FLOWS}} | {{DIAGRAM_REASON_EVENT_FLOWS}} |
+| module-dependencies | {{DIAGRAM_STATUS_MODULE_DEPENDENCIES}} | {{DIAGRAM_REASON_MODULE_DEPENDENCIES}} |
+| deployment | {{DIAGRAM_STATUS_DEPLOYMENT}} | {{DIAGRAM_REASON_DEPLOYMENT}} |
+| user-use-case | {{DIAGRAM_STATUS_USER_USE_CASE}} | {{DIAGRAM_REASON_USER_USE_CASE}} |
+
 ## Services
 
 {{#SERVICES}}
@@ -26,6 +46,36 @@
 {{DATA_FLOW_DIAGRAM}}
 ```
 
+### Event Flows
+
+- **Status**: {{DIAGRAM_STATUS_EVENT_FLOWS}}
+- **Not applicable rationale**: {{DIAGRAM_NA_EVENT_FLOWS}}
+
+```mermaid
+flowchart LR
+  EventSource --> EventBus --> Consumer
+```
+
+### Module Dependencies
+
+- **Status**: {{DIAGRAM_STATUS_MODULE_DEPENDENCIES}}
+- **Not applicable rationale**: {{DIAGRAM_NA_MODULE_DEPENDENCIES}}
+
+```mermaid
+flowchart LR
+  UI --> Service --> Repository
+```
+
+### User Use-Case Flows
+
+- **Status**: {{DIAGRAM_STATUS_USER_USE_CASE}}
+- **Not applicable rationale**: {{DIAGRAM_NA_USER_USE_CASE}}
+
+```mermaid
+flowchart TD
+  User --> Action --> Outcome
+```
+
 ## Integration Points
 
 | Service A | Service B | Protocol | Endpoint/Topic |
@@ -62,6 +112,9 @@
 {{DEPLOYMENT_DIAGRAM}}
 ```
 
+- **Status**: {{DIAGRAM_STATUS_DEPLOYMENT}}
+- **Not applicable rationale**: {{DIAGRAM_NA_DEPLOYMENT}}
+
 ## Monitoring & Observability
 
 - **Logging**: {{LOGGING_SOLUTION}}

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