viepilot 1.9.11 → 2.1.0

package/workflows/crystallize.md

@@ -1,5 +1,5 @@
 <purpose>
-Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.
+Convert brainstorm sessions into structured artifacts for autonomous AI execution.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)
@@ -11,6 +11,19 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 
 <process>
 
+<step name="load_language_config">
+## Step 0-A: Load Language Configuration (ENH-032)
+
+Read `~/.viepilot/config.json` → set session variables:
+- `DOCUMENT_LANG` — language for generated project files (default: `en`)
+- `COMMUNICATION_LANG` — language for AI↔user messages (default: `en`)
+
+Use `DOCUMENT_LANG` for all file content written in Steps 1–9.
+Use `COMMUNICATION_LANG` for all prompts and confirmation messages in this session.
+
+If `~/.viepilot/config.json` is absent, use defaults (en/en) — do not fail.
+</step>
+
 <step name="collect_metadata">
 ## Step 0: Collect Project Metadata
 
@@ -18,34 +31,34 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 
 Normative: **`docs/dev/global-profiles.md`**. Binding: **`.viepilot/META.md`** (`viepilot_profile_id`, optional `viepilot_profile_path`).
 
-**Trước** block câu hỏi Basic Info:
+**Before** the Basic Info question block:
 
-1. Nếu có `.viepilot/META.md`, parse YAML frontmatter lấy `viepilot_profile_id` và tùy chọn `viepilot_profile_path`.
-2. **Resolve** file profile markdown:
-   - Nếu `viepilot_profile_path` có và file tồn tại (expand `~` / `$HOME`) → dùng path đó.
-   - Else nếu có `viepilot_profile_id` hợp lệ → `$HOME/.viepilot/profiles/<viepilot_profile_id>.md`.
-3. **Khi đọc được file profile:**
-   - Đọc frontmatter (`display_name`, `org_tag`, `website`, `tags`, …) và body (`## Organization`, `## Branding & voice`, `## Audience`, `## Legal & attribution`, `## Contact (public)`).
-   - **Pre-fill** các câu hỏi Step 0 (org, website, mô tả ngắn nếu khớp) dưới dạng **proposal**; user **confirm** hoặc **sửa**.
-   - Ghi working note **`profile_resolved`**: `{ profile_id, absolute_path }` cho các bước sau.
-4. **Khi không có META, thiếu id, hoặc file không tồn tại:**
-   - Ghi **`profile_resolved: none`** và tiếp tục Step 0 như cũ — **không** fail crystallize.
+1. If `.viepilot/META.md` exists, parse YAML frontmatter to extract `viepilot_profile_id` and optionally `viepilot_profile_path`.
+2. **Resolve** the profile markdown file:
+   - If `viepilot_profile_path` is set and the file exists (expand `~` / `$HOME`) → use that path.
+   - Else if a valid `viepilot_profile_id` is present → `$HOME/.viepilot/profiles/<viepilot_profile_id>.md`.
+3. **When the profile file is readable:**
+   - Read frontmatter (`display_name`, `org_tag`, `website`, `tags`, …) and body (`## Organization`, `## Branding & voice`, `## Audience`, `## Legal & attribution`, `## Contact (public)`).
+   - **Pre-fill** Step 0 questions (org, website, short description if matched) as a **proposal**; user must **confirm** or **edit**.
+   - Record working note **`profile_resolved`**: `{ profile_id, absolute_path }` for use in later steps.
+4. **When META is absent, id is missing, or file does not exist:**
+   - Record **`profile_resolved: none`** and continue Step 0 as normal — do **not** fail crystallize.
 
-Hỏi user các thông tin dự án:
+Ask the user for project information:
 
 ### Basic Info
 ```
-1. Tên dự án?
+1. Project name?
    Default: (extract from brainstorm)
    
-2. Mô tả ngắn gọn (1-2 câu)?
+2. Short description (1-2 sentences)?
 ```
 
 ### Organization Info
 ```
-3. Tên công ty/tổ chức phát triển?
+3. Company/organization name?
 
-4. Website công ty? (optional)
+4. Company website? (optional)
 ```
 
 ### Package Info
@@ -63,9 +76,9 @@ Hỏi user các thông tin dự án:
 
 ### Developer Info
 ```
-8. Tên người phát triển chính?
+8. Lead developer name?
 
-9. Email người phát triển chính?
+9. Lead developer email?
 
 10. GitHub username? (optional)
 ```
@@ -84,7 +97,7 @@ Hỏi user các thông tin dự án:
     Options: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, Proprietary
     Default: MIT
     
-14. Năm bắt đầu dự án?
+14. Project start year?
     Default: {current_year}
 ```
 
@@ -104,25 +117,22 @@ 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).
+6. **Phase assignment** — parse `## Phases` from brainstorm session(s):
+   - Collect features/capabilities listed under each `### Phase N` heading.
+   - If a feature has no phase assigned → ask user which phase before continuing.
+   - Record `phases_inventory: { phase_1: [...], phase_2: [...], ... }` in working notes.
 
-**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.
+**Phase assignment gate (before leaving Step 1):**
+- [ ] Every brainstorm session checked for `## Phases` section OR features explicitly assigned during conversation.
+- [ ] All features have a phase number assigned — no unassigned features.
+- [ ] `phases_inventory` recorded in working notes with at least Phase 1 non-empty.
 
 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)
+- [ ] Phase assignment gate satisfied (phases_inventory recorded)
 
 If gaps found → ask user to clarify or return to brainstorm.
 </step>
@@ -130,7 +140,43 @@ If gaps found → ask user to clarify or return to brainstorm.
 <step name="consume_ui_direction">
 ## Step 1A: Consume UI Direction Artifacts (for UI/UX projects)
 
-If brainstorm indicates frontend/UI scope, check for direction artifacts:
+### UI Scope Detection (ENH-026 hard gate)
+
+Before checking for artifacts, scan brainstorm session files (`docs/brainstorm/session-*.md`) for UI signal keywords:
+
+> `màu`, `màu sắc`, `color`, `layout`, `màn hình`, `screen`, `page`, `trang`, `button`, `nút`, `form`, `biểu mẫu`, `mobile`, `responsive`, `giao diện`, `UI`, `UX`, `design`, `dashboard`, `sidebar`, `header`, `footer`, `modal`, `popup`, `icon`, `theme`, `typography`, `font`, `spacing`, `grid`, `card`, `component`, `hero`, `banner`
+
+If **≥3 unique signal occurrences** found → set `ui_scope_detected = true`.
+
+**Hard gate** (only when `ui_scope_detected = true`):
+
+Check if `.viepilot/ui-direction/` exists and contains any session artifacts.
+
+If `ui_scope_detected = true` **AND** artifacts are missing → **STOP** and present:
+
+```
+⚠️ UI Direction artifacts missing
+
+The brainstorm session indicates this project has UI scope but `.viepilot/ui-direction/` has no artifacts yet.
+
+1. Return to /vp-brainstorm --ui to create direction first (recommended)
+2. Continue with assumptions — record in ARCHITECTURE.md and proceed
+```
+
+**Option 2 path**: append to `.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
+```
+
+If `ui_scope_detected = false` → skip gate; proceed normally.
+
+### Consume artifacts (when available)
+
+Check for direction artifacts:
 
 ```bash
 ls -la .viepilot/ui-direction/ 2>/dev/null
@@ -149,10 +195,7 @@ When available, for the selected/latest session:
 - 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:
-  1. generate UI direction via `/vp-brainstorm --ui`, or
-  2. explicitly continue with assumptions.
+If `notes.md` exists but has no `## Pages inventory` section and brainstorm shows multi-page scope → warn user and request fix or assumptions before proceeding.
 </step>
 
 <step name="research_stack_official">
@@ -211,6 +254,79 @@ Also create project-local index for traceability:
 - `.viepilot/STACKS.md` listing stacks used and cache paths.
 </step>
 
+<step name="consume_architect_artifacts">
+## Step 1D: Consume Architect Artifacts (FEAT-011)
+
+If `.viepilot/architect/` exists with at least one session directory:
+
+1. **Select most recent session** (by directory mtime or newest session-id).
+2. **Read `notes.md`** → parse YAML frontmatter sections:
+   - **`decisions[]`** → append to `.viepilot/ARCHITECTURE.md` under:
+     ```markdown
+     ## Architecture Decisions (from Architect Mode)
+     | ID | Topic | Chosen | Rationale | Status |
+     ```
+   - **`tech_stack{}`** → use as **authoritative tech stack** (overrides brainstorm text if conflict; when conflict detected: surface to user with both values and ask which to use before proceeding).
+   - **`open_questions[]`** with `status: open` → surface as list:
+     ```
+     ⚠️ These questions were open at end of Architect Design Mode — please resolve before proceeding:
+     - Q001: {question}
+     - Q002: {question}
+     ```
+3. **`erd.html` / `notes.md ## erd`** (if exists — ENH-027) → append to `.viepilot/ARCHITECTURE.md`:
+   ```markdown
+   ## Database Schema (from Architect ERD)
+   | Entity | Attributes | PK | FK | Notes |
+   ...
+   ### Relationships
+   | Entity A | Type | Entity B | Label |
+   ```
+4. **`user-use-cases.html` / `notes.md ## use_cases`** (if exists — ENH-028) → append to `.viepilot/PROJECT-CONTEXT.md`:
+   ```markdown
+   ## User Stories & Use Cases (from Architect Mode)
+   ### Actors
+   | Actor | Role | Goals |
+   ### User Stories
+   | ID | As a... | I want to... | So that... | Priority |
+   ```
+5. **`deployment.html` / `notes.md ## deployment`** (if exists — ENH-029) → append to `.viepilot/ARCHITECTURE.md`:
+   ```markdown
+   ## Deployment & Infrastructure (from Architect Mode)
+   | Env | URL | Purpose | Services | Config notes |
+   ...
+   ### Infrastructure Components
+   | Component | Type | Provider | Sizing | Notes |
+   ```
+6. **`apis.html` / `notes.md ## apis`** (if exists — ENH-029) → append to `.viepilot/ARCHITECTURE.md`:
+   ```markdown
+   ## API Design (from Architect Mode)
+   ### API Style: {REST / GraphQL / gRPC / WebSocket}
+   | Service | Method | Path | Auth? | Notes |
+   ...
+   ### API Design Decisions
+   | Decision | Choice | Rationale |
+   ```
+   Note: `sequence-diagram.html` is intentionally excluded from crystallize extraction — per-scenario diagrams are not architecture artifacts (they live in Architect Mode workspace only).
+7. **`feature-map.html`** → cross-reference Phase badges with `phases_inventory`; if discrepancies found (feature in HTML not in inventory, or vice versa) → list them for user to confirm.
+8. **Record in working notes**:
+   - `architect_session_id`: {id}
+   - `decisions_imported`: {count}
+   - `open_questions_count`: {count of open questions}
+   - `erd_entities_count`: {count if erd present, else "n/a"}
+   - `use_cases_count`: {count if use_cases present, else "n/a"}
+   - `deployment_imported`: {true/false}
+   - `apis_imported`: {true/false}
+
+If `.viepilot/architect/` does **not** exist but brainstorm shows complex architecture (≥5 services/components detected):
+- Suggest (soft prompt — not a hard block):
+  ```
+  💡 Would you like to return to /vp-brainstorm --architect to create visualizations first?
+  1. Yes — return to architect mode
+  2. No — continue crystallize with text-only brainstorm
+  ```
+- User confirmation required before proceeding.
+</step>
+
 <step name="generate_ai_guide">
 ## Step 2: Generate AI-GUIDE.md
 
@@ -219,8 +335,8 @@ Create `.viepilot/AI-GUIDE.md` using template:
 
 Customize with:
 - Project-specific file references
-- **ViePilot profile (FEAT-009):** Nếu Step 0 đặt `profile_resolved` thành đường dẫn hợp lệ, thêm mục **Quick context** ghi `profile_id`, đường dẫn file profile, và nhắc đọc file đó cho **tone/branding** khi viết user-facing text. Nếu `profile_resolved: none`, ghi một dòng: chưa bind profile global.
-- 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
+- **ViePilot profile (FEAT-009):** If Step 0 set `profile_resolved` to a valid path, add a **Quick context** entry recording `profile_id`, the profile file path, and a reminder to read that file for **tone/branding** when writing user-facing text. If `profile_resolved: none`, write a single line: no global profile bound.
+- Context loading strategy based on project size — **preserve template ordering** where `PROJECT-CONTEXT.md` **`<product_vision>`** and **`ROADMAP.md` phases** 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`
@@ -240,7 +356,7 @@ Fill with collected metadata:
 - Package structure (generate from base ID)
 - Developer info
 - File headers (generate from metadata)
-- **FEAT-009:** Nếu profile đã resolve ở Step 0 và user đã confirm pre-fill, **ưu tiên** khớp bảng Organization / attribution trong template với nội dung profile (chỉ dữ liệu công khai; không secrets).
+- **FEAT-009:** If the profile was resolved in Step 0 and the user confirmed the pre-fill, **prioritize** aligning the Organization / attribution table in the template with the profile content (public data only; no secrets).
 </step>
 
 <step name="generate_architecture">
@@ -258,7 +374,7 @@ Extract from brainstorm:
 
 ### ViePilot organization context (FEAT-009)
 
-- Nếu Step 0 ghi **`profile_resolved`** với đường dẫn hợp lệ: ngay sau phần **overview** đầu tiên của `.viepilot/ARCHITECTURE.md`, thêm section:
+- If Step 0 recorded **`profile_resolved`** with a valid path: immediately after the first **overview** section of `.viepilot/ARCHITECTURE.md`, add the following section:
 
 ```markdown
 ## ViePilot organization context
@@ -267,9 +383,9 @@ Extract from brainstorm:
 
 ```
 
-Sau đó **2–8 bullet** tóm tắt (không secrets) từ **Organization**, **Branding & voice**, **Audience** trong file profile.
+Then add **2–8 bullets** summarizing (no secrets) from the **Organization**, **Branding & voice**, and **Audience** sections of the profile file.
 
-- Nếu **`profile_resolved: none`**: một dòng dưới overview: *No ViePilot global profile bound — organization context comes from Step 0 only.*
+- If **`profile_resolved: none`**: add one line below the overview: *No ViePilot global profile bound — organization context comes from Step 0 only.*
 
 Before writing diagrams, create a **diagram applicability matrix** from brainstorm signals (complexity, service boundaries, event usage, deployment shape, user-flow complexity, integration surface):
 
@@ -323,7 +439,7 @@ Extract:
 - Naming conventions
 - Constraints
 
-**FEAT-009 — ViePilot active profile block:** Nếu profile đã resolve ở Step 0, chèn **trước** `<domain_knowledge>` (hoặc ngay sau title file) section:
+**FEAT-009 — ViePilot active profile block:** If the profile was resolved in Step 0, insert **before** `<domain_knowledge>` (or immediately after the file title) the following section:
 
 ```markdown
 ## ViePilot active profile (FEAT-009)
@@ -338,7 +454,7 @@ Extract:
 
 ```
 
-Nếu không có profile: một dòng *Profile binding not configured (`META.md` or global profile file missing).*
+If no profile: a single line *Profile binding not configured (`META.md` or global profile file missing).*
 </step>
 
 <step name="generate_rules">
@@ -368,23 +484,17 @@ Include:
 Create `.viepilot/ROADMAP.md` using template:
 `@$HOME/.cursor/viepilot/templates/project/ROADMAP.md`
 
-From brainstorm features/MVP breakdown:
-1. Create **executable MVP phases** (what `/vp-auto` can run next; near-term delivery only).
+From brainstorm `phases_inventory`:
+1. Generate phases in order: Phase 1, Phase 2, Phase 3... from `phases_inventory`.
 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 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.
+3. Define dependencies between phases.
+4. Each phase: tasks, acceptance criteria, verification commands.
+5. No Post-MVP / horizon block needed — all work is already in phases.
 </step>
 
 <step name="generate_schemas">
@@ -531,11 +641,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
+- [ ] Step 1: phase assignment gate satisfied (phases_inventory recorded, all features assigned)
 - [ ] All artifacts created in .viepilot/
 - [ ] PROJECT-META.md complete
 - [ ] SYSTEM-RULES.md has all standards
-- [ ] 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
 - [ ] Phase directories created
 - [ ] Project files created
 - [ ] Git committed

package/workflows/debug.md

@@ -1,6 +1,6 @@
 <purpose>
-Systematic debugging workflow với persistent state tracking.
-Giúp organize debugging process và track progress qua nhiều sessions.
+Systematic debugging workflow with persistent state tracking.
+Helps organize the debugging process and track progress across multiple sessions.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)
@@ -11,8 +11,8 @@ Giúp organize debugging process và track progress qua nhiều sessions.
 
 ## Implementation routing guard (debug)
 
-- **`debug.md`**: ưu tiên **điều tra**, log session, chạy test — **không** sửa mã shipping mặc định cho đến khi (a) user **explicit** *sửa luôn* / *hotfix*, hoặc (b) đã route **`/vp-request`** + **`/vp-evolve`** + **`/vp-auto`** cho fix có cấu trúc.
-- Reproduce/minimal patch **chỉ để xác minh giả thuyết** được phép nếu nhỏ và user đồng ý ngầm trong phiên debug; merge fix thật vẫn nên qua **`/vp-auto`** khi có task plan.
+- **`debug.md`**: prioritizes **investigation**, session logging, running tests — does **not** modify shipping code by default until (a) user **explicitly** says *fix now* / *hotfix*, or (b) already routed through **`/vp-request`** + **`/vp-evolve`** + **`/vp-auto`** for a structured fix.
+- Reproduce/minimal patch **only to verify hypotheses** is allowed if small and the user implicitly agrees during the debug session; merging the real fix should still go through **`/vp-auto`** when a task plan exists.
 
 
 <process>
@@ -61,11 +61,11 @@ Go to step 3 (New Session).
 
 Ask user:
 ```
-Mô tả vấn đề bạn đang gặp:
-1. Vấn đề là gì?
-2. Triệu chứng? (error messages, behavior)
-3. Khi nào xảy ra? (điều kiện)
-4. Files liên quan?
+Describe the problem you are facing:
+1. What is the problem?
+2. Symptoms? (error messages, behavior)
+3. When does it occur? (conditions)
+4. Related files?
 ```
 
 Create session:

package/workflows/documentation.md

@@ -1,5 +1,5 @@
 <purpose>
-Generate comprehensive documentation từ code và artifacts.
+Generate comprehensive documentation from code and artifacts.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)
@@ -60,11 +60,11 @@ For viepilot framework repos, also use `$ACTUAL_SKILLS`, `$ACTUAL_WORKFLOWS`.
 
 ### 0A. ViePilot active profile (FEAT-009)
 
-Normative: **`docs/dev/global-profiles.md`**. Cùng **resolution** như `workflows/crystallize.md` Step 0 (đọc `.viepilot/META.md` → `viepilot_profile_path` hoặc `$HOME/.viepilot/profiles/<viepilot_profile_id>.md`).
+Normative: **`docs/dev/global-profiles.md`**. Same **resolution** as `workflows/crystallize.md` Step 0 (read `.viepilot/META.md` → `viepilot_profile_path` or `$HOME/.viepilot/profiles/<viepilot_profile_id>.md`).
 
-1. Nếu đọc được file profile, giữ **working notes** (display_name, org_tag, website, audience, branding) để dùng khi sinh README / contributing / bất kỳ prose **attribution** — chỉ nội dung **công khai**, không secrets.
-2. Nếu không có binding hoặc file thiếu → tiếp tục; **không** fail `/vp-docs`.
-3. Khi có profile, nhắc trong output (vd. footer README hoặc `docs/dev/architecture.md`) một dòng trích **profile_id** nếu phù hợp policy dự án.
+1. If the profile file is readable, keep **working notes** (display_name, org_tag, website, audience, branding) for use when generating README / contributing / any prose **attribution** — public content only, no secrets.
+2. If no binding exists or file is missing → continue; do **not** fail `/vp-docs`.
+3. When a profile is present, mention in output (e.g., README footer or `docs/dev/architecture.md`) one line referencing **profile_id** if appropriate for the project policy.
 
 Post-generation validation (run after all files generated):
 ```bash

package/workflows/evolve.md

@@ -1,5 +1,5 @@
 <purpose>
-Nâng cấp hoặc mở rộng dự án: thêm features, bắt đầu milestone mới, hoặc refactor.
+Upgrade or expand the project: add features, start a new milestone, or refactor.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)
@@ -10,9 +10,9 @@ Nâng cấp hoặc mở rộng dự án: thêm features, bắt đầu milestone
 
 ## Implementation routing guard (planning vs execution)
 
-- **`evolve.md`** chỉ **lập kế hoạch**: ROADMAP, phase dir, SPEC/tasks, TRACKER, ghi chú CHANGELOG `[Unreleased]` khi workflow yêu cầu — **không** implement mã shipping mặc định (`lib/`, `tests/`, `bin/`, `workflows/` ngoài plan, v.v.).
-- **Bước tiếp:** **`/vp-auto`** sau khi task/phase có plan (doc-first **BUG-001**).
-- **Ngoại lệ:** User **explicit** bypass — phải nêu rõ trong chat.
+- **`evolve.md`** only **plans**: ROADMAP, phase dir, SPEC/tasks, TRACKER, CHANGELOG `[Unreleased]` notes when the workflow requires — does **not** implement shipping code by default (`lib/`, `tests/`, `bin/`, `workflows/` outside plan, etc.).
+- **Next step:** **`/vp-auto`** after task/phase has a plan (doc-first **BUG-001**).
+- **Exception:** User **explicit** bypass — must be stated clearly in chat.
 
 
 <process>
@@ -63,7 +63,7 @@ Describe the new feature:
 3. Which services/modules affected?
 4. Dependencies on existing code?
 5. Estimated complexity? (S/M/L/XL)
-6. Có cần brainstorm chuyên sâu không? (landing page / UX / growth ideas / research-heavy)
+6. Need deep brainstorm? (landing page / UX / growth ideas / research-heavy)
 ```
 
 ### Check Architecture Compatibility
@@ -79,12 +79,12 @@ Questions:
 
 If incompatible → suggest refactor first or discuss alternative.
 
-### Smart Route to Brainstorm (khi phù hợp)
-Nếu feature có nội dung thiên về product discovery, UX, hoặc landing page:
-- Route qua brainstorm nâng cao thay vì chốt phase ngay:
-  - `/vp-brainstorm --new --landing --research` (nếu có landing page)
-  - `/vp-brainstorm --new --research` (nếu cần research decision)
-- Sau khi brainstorm xong, quay lại `/vp-evolve` để crystallize phase/tasks.
+### Smart Route to Brainstorm (when applicable)
+If the feature leans toward product discovery, UX, or landing page:
+- Route through advanced brainstorm instead of locking the phase immediately:
+  - `/vp-brainstorm --new --landing --research` (if there is a landing page)
+  - `/vp-brainstorm --new --research` (if a research decision is needed)
+- After brainstorm is complete, return to `/vp-evolve` to crystallize phase/tasks.
 
 ### Generate Phase
 Create new phase in ROADMAP.md:
@@ -103,6 +103,38 @@ Create new phase in ROADMAP.md:
 - [ ] {criteria}
 ```
 
+### ⚠️ TASK PATH RULE (BUG-009)
+
+When writing the `## Paths` block in **any task `.md` file**, ALWAYS use paths
+**relative to the repository root** (where `package.json` / `Makefile` lives).
+
+```
+CORRECT (repo-relative):
+  workflows/crystallize.md
+  skills/vp-audit/SKILL.md
+  templates/project/AI-GUIDE.md
+  lib/viepilot-config.cjs
+  bin/vp-tools.cjs
+  tests/unit/my-test.test.js
+
+INCORRECT (never use in ## Paths):
+  ~/.claude/viepilot/workflows/crystallize.md
+  ~/.claude/skills/vp-audit/SKILL.md
+  /Users/someone/.claude/...
+  /absolute/path/to/anything
+```
+
+**Exception:** paths *inside* code block content (bash examples, runtime descriptions)
+may reference absolute paths (e.g., `~/.claude/viepilot/config.json` inside a bash
+snippet). Only the `## Paths` header block must be repo-relative.
+
+If unsure of the repo-relative path, inspect:
+- `ls workflows/`   → workflow files
+- `ls skills/`      → skill files
+- `ls lib/`         → library files
+- `ls bin/`         → CLI files
+- `ls templates/`   → template files
+
 ### Create Phase Directory
 ```bash
 mkdir -p .viepilot/phases/{NN}-{feature-slug}/tasks/
@@ -168,7 +200,7 @@ New milestone details:
 
 Options:
 - Route to `/vp-brainstorm --new` for full brainstorm
-- Nếu milestone có landing page focus: `/vp-brainstorm --new --landing --research`
+- If milestone has landing page focus: `/vp-brainstorm --new --landing --research`
 - Quick setup with minimal questions
 
 ### Generate New ROADMAP.md

package/workflows/pause-work.md

@@ -1,6 +1,6 @@
 <purpose>
-Save complete work state để có thể resume từ bất kỳ context nào.
-Creates HANDOFF.json và .continue-here.md cho recovery.
+Save complete work state so it can be resumed from any context.
+Creates HANDOFF.json and .continue-here.md for recovery.
 </purpose>
 
 <process>

package/workflows/request.md

@@ -1,5 +1,5 @@
 <purpose>
-Tạo và quản lý requests cho dự án: bugs, features, enhancements, tech debt, và brainstorm continuation.
+Create and manage project requests: bugs, features, enhancements, tech debt, and brainstorm continuation.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)
@@ -10,9 +10,9 @@ Tạo và quản lý requests cho dự án: bugs, features, enhancements, tech d
 
 ## Implementation routing guard (planning vs execution)
 
-- Workflow **`request.md`** chỉ **ghi nhận, backlog, triage** — **không** là lane mặc định để **implement** mã shipping (`lib/`, `tests/`, `bin/`, `src/` app, `workflows/`, `skills/` trong repo framework, v.v.).
-- **Chuỗi khuyến nghị sau khi có request:** `/vp-evolve` (ROADMAP, phase, SPEC/tasks, task plan; doc-first **BUG-001** khi áp dụng) → **`/vp-auto`** (thực thi + verify + git persistence **BUG-003**).
-- **Ngoại lệ:** User **explicit** (vd. *hotfix ngay*, *sửa file X trong chat này*, *bypass planning*) → được implement trực tiếp; assistant **phải nêu rõ** đang bypass guard.
+- Workflow **`request.md`** only **records, backlogs, and triages** — it is **not** the default lane to **implement** shipping code (`lib/`, `tests/`, `bin/`, `src/` app, `workflows/`, `skills/` in the framework repo, etc.).
+- **Recommended chain after a request:** `/vp-evolve` (ROADMAP, phase, SPEC/tasks, task plan; doc-first **BUG-001** when applicable) → **`/vp-auto`** (execute + verify + git persistence **BUG-003**).
+- **Exception:** User **explicitly** states (e.g., *hotfix now*, *fix file X in this chat*, *bypass planning*) → direct implementation is allowed; the assistant **must state clearly** it is bypassing the guard.
 
 
 <process>
@@ -455,8 +455,8 @@ Current task: {task}
 
 If option 1:
 - Save current state (like /vp-pause)
-- Create emergency fix phase (minimal SPEC/tasks) **hoặc** user explicit hotfix
-- Route to **`/vp-auto`** — vẫn qua task plan ngắn khi có thể; **không** implement lặng trong thread `/vp-request` trừ user explicit bypass
+- Create emergency fix phase (minimal SPEC/tasks) **or** user explicit hotfix
+- Route to **`/vp-auto`** — still go through a short task plan when possible; do **not** implement silently inside the `/vp-request` thread unless the user explicitly bypasses
 
 ### High Priority Feature
 ```
@@ -466,7 +466,7 @@ Options:
 1. Add to current milestone
 2. Brainstorm more first
 3. Schedule for next milestone
-4. **Plan then execute:** `/vp-evolve` → `/vp-auto` (không implement trực tiếp trong thread `/vp-request` trừ user explicit override)
+4. **Plan then execute:** `/vp-evolve` → `/vp-auto` (do not implement directly inside the `/vp-request` thread unless user explicitly overrides)
 ```
 
 ### Regular Request
@@ -527,7 +527,7 @@ git push
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
  /vp-request --list    View all requests
- /vp-evolve            ROADMAP + phase/tasks (trước code)
+ /vp-evolve            ROADMAP + phase/tasks (before code)
  /vp-auto              Implement theo task plan (sau evolve)
  /vp-request           Create another request
  /vp-status            See overall progress

package/workflows/resume-work.md

@@ -1,5 +1,5 @@
 <purpose>
-Restore complete project context và resume work seamlessly từ previous session.
+Restore complete project context and resume work seamlessly from a previous session.
 </purpose>
 
 <process>

package/workflows/rollback.md

@@ -1,5 +1,5 @@
 <purpose>
-Safe rollback to any ViePilot checkpoint với backup và state preservation.
+Safe rollback to any ViePilot checkpoint with backup and state preservation.
 </purpose>
 
 <process>