viepilot 1.14.0 → 2.4.0

package/templates/project/AI-GUIDE.md

@@ -1,70 +1,70 @@
 # {{PROJECT_NAME}} - AI Navigation Guide
 
-> **Đọc file này TRƯỚC KHI làm bất kỳ task nào**
-> File này giúp bạn tìm đúng context mà không cần load tất cả
+> **Read this file BEFORE starting any task**
+> This file helps you find the right context without loading everything
 
 ## Quick Lookup
 
-| 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 | `PROJECT-CONTEXT.md` | `<product_vision>` |
-| Roadmap phases (không chỉ task hiện tại) | `ROADMAP.md` | Phases sau phase hiện tại |
-| 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` |
-| Xem task tiếp theo | `ROADMAP.md` | Tìm phase đang `In Progress` |
+| I need to... | Read file | Section |
+|--------------|-----------|---------|
+| Understand what the project does | `PROJECT-CONTEXT.md` | `<domain_knowledge>` |
+| Vision & phased scope | `PROJECT-CONTEXT.md` | `<product_vision>` |
+| Roadmap phases (beyond current task) | `ROADMAP.md` | Phases after current phase |
+| Know the tech stack | `ARCHITECTURE.md` | `## Technology Decisions` |
+| See what each service does | `ARCHITECTURE.md` | `## Services` |
+| Know current phase | `TRACKER.md` | `## Current State` |
+| See next task | `ROADMAP.md` | Find phase marked `In Progress` |
 | Coding conventions | `SYSTEM-RULES.md` | `<coding_rules>` |
-| Những gì KHÔNG được làm | `SYSTEM-RULES.md` | `<do_not>` |
+| What NOT to do | `SYSTEM-RULES.md` | `<do_not>` |
 | Database schema | `schemas/database-schema.sql` | - |
 | API contracts | `schemas/api-contracts.yaml` | - |
-| Decisions đã quyết định | `TRACKER.md` | `## Decision Log` |
-| Resume công việc dở | `HANDOFF.json` | - |
+| Past decisions | `TRACKER.md` | `## Decision Log` |
+| Resume in-progress work | `HANDOFF.json` | - |
 | Package structure | `PROJECT-META.md` | `## Package Structure` |
 | File headers | `PROJECT-META.md` | `## File Headers` |
 
 ## Context Loading Strategy
 
-### Minimal Context (cho quick tasks)
+### Minimal Context (for quick tasks)
 ```
-Chỉ đọc:
-1. AI-GUIDE.md (file này)
+Read only:
+1. AI-GUIDE.md (this file)
 2. TRACKER.md → Current State
-3. File cụ thể liên quan đến task
+3. The specific file related to the task
 ```
 
-### Standard Context (cho coding tasks)
+### Standard Context (for coding tasks)
 ```
-Đọc theo thứ tự:
-1. AI-GUIDE.md (file này)
-2. TRACKER.md → biết đang ở đâu
-3. PROJECT-CONTEXT.md → <product_vision> + phased scope (đọc TRƯỚC khi khóa thiết kế chi tiết)
-4. ROADMAP.md → skim phases sau phase hiện tại, rồi task hiện tại
+Read in order:
+1. AI-GUIDE.md (this file)
+2. TRACKER.md → know where you are
+3. PROJECT-CONTEXT.md → <product_vision> + phased scope (read BEFORE locking detailed design)
+4. ROADMAP.md → skim phases after current phase, then current task
 5. SYSTEM-RULES.md → coding rules
-6. Schema file nếu cần
+6. Schema file if needed
 ```
 
-### Full Context (cho architecture decisions)
+### Full Context (for architecture decisions)
 ```
-Đọc theo thứ tự:
+Read in order:
 1. AI-GUIDE.md + TRACKER.md
-2. PROJECT-CONTEXT.md → domain + <product_vision> (đầy đủ)
+2. PROJECT-CONTEXT.md → domain + <product_vision> (complete)
 3. ROADMAP.md → phases + tasks
 4. ARCHITECTURE.md
 5. SYSTEM-RULES.md
-6. Brainstorm session gốc (nếu cần rationale chi tiết)
+6. Original brainstorm session (if detailed rationale needed)
 ```
 
-### Product vision & phase planning (trước khi “lock” architecture)
+### Product vision & phase planning (before "locking" architecture)
 
-- Trước task implementation sâu hoặc quyết định kiến trúc lớn: đọc phần `<product_vision>` và phase goals trong `ROADMAP.md` **cùng lúc** với task hiện tại.
+- Before deep implementation tasks or major architecture decisions: read `<product_vision>` and phase goals in `ROADMAP.md` **together** with the current task.
 
 ## File Relationships
 
 ```
-AI-GUIDE.md (đọc đầu tiên)
+AI-GUIDE.md (read first)
      │
-     ├── TRACKER.md (state hiện tại)
+     ├── TRACKER.md (current state)
      │      └── points to → current phase in ROADMAP.md
      │
      ├── PROJECT-CONTEXT.md (domain + <product_vision> / phased scope)
@@ -102,24 +102,24 @@ AI-GUIDE.md (đọc đầu tiên)
 
 Full guidelines: `SYSTEM-RULES.md#comment_standards`
 
-## Khi Nào Cần Đọc Lại
+## When to Re-read
 
-| Trigger | Cần refresh |
-|---------|-------------|
-| Bắt đầu session mới | `TRACKER.md`, `HANDOFF.json` |
-| Chuyển phase | `ROADMAP.md` section của phase mới |
-| Gặp lỗi architecture | `ARCHITECTURE.md`, `SYSTEM-RULES.md` |
-| Không rõ business rule | `PROJECT-CONTEXT.md` |
-| Cần quyết định mới | `TRACKER.md` → Decision Log |
+| Trigger | Refresh |
+|---------|---------|
+| Starting a new session | `TRACKER.md`, `HANDOFF.json` |
+| Switching phases | `ROADMAP.md` section for the new phase |
+| Encountering architecture issues | `ARCHITECTURE.md`, `SYSTEM-RULES.md` |
+| Unclear business rule | `PROJECT-CONTEXT.md` |
+| Need to make a new decision | `TRACKER.md` → Decision Log |
 
 ## Commands Reference
 
-| Command | Dùng khi |
-|---------|----------|
-| `/vp-status` | Xem progress nhanh |
-| `/vp-auto` | Chạy autonomous |
-| `/vp-pause` | Dừng, lưu state |
-| `/vp-resume` | Tiếp tục từ pause |
-| `/vp-evolve` | Thêm features/milestone mới |
+| Command | When to use |
+|---------|-------------|
+| `/vp-status` | Quick progress view |
+| `/vp-auto` | Run autonomous execution |
+| `/vp-pause` | Stop and save state |
+| `/vp-resume` | Continue from pause |
+| `/vp-evolve` | Add features / start new milestone |
 | `/vp-docs` | Generate documentation |
-| `/vp-task` | Quản lý task thủ công |
+| `/vp-task` | Manage tasks manually |

package/workflows/audit.md

@@ -1,7 +1,7 @@
 <purpose>
-Audit ViePilot project state và documentation để phát hiện drift.
-Hoạt động trên bất kỳ project nào đang dùng ViePilot.
-Auto-detect nếu đang chạy trong viepilot framework repo để thêm framework-specific checks.
+Audit ViePilot project state and documentation to detect drift.
+Works on any project using ViePilot.
+Auto-detects if running inside the viepilot framework repo to enable framework-specific checks.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)

package/workflows/autonomous.md

@@ -1,6 +1,6 @@
 <purpose>
-Autonomous execution của project phases. Cho mỗi phase: analyze → execute tasks → verify → iterate.
-Pauses at control points cho user decisions.
+Autonomous execution of project phases. For each phase: analyze → execute tasks → verify → iterate.
+Pauses at control points for user decisions.
 </purpose>
 
 ## ViePilot Skill Scope Policy (BUG-004)
@@ -11,7 +11,7 @@ Pauses at control points cho user decisions.
 
 ## Implementation entry (cross-skill)
 
-- **`/vp-auto`** + workflow này là **lane mặc định** để **implement** work đã có **phase/task plan** (và doc-first **BUG-001**). **`/vp-request`** và **`/vp-evolve`** **không** thay thế bước này trừ user explicit override — xem **Implementation routing guard** trong `workflows/request.md` và `workflows/evolve.md`.
+- **`/vp-auto`** + this workflow is the **default lane** for **implementing** work that already has a **phase/task plan** (and doc-first **BUG-001**). **`/vp-request`** and **`/vp-evolve`** do **not** replace this step unless the user explicitly overrides — see **Implementation routing guard** in `workflows/request.md` and `workflows/evolve.md`.
 
 
 <process>
@@ -20,8 +20,8 @@ Pauses at control points cho user decisions.
 ## 1. Initialize
 
 Parse `{{VP_ARGS}}` for flags:
-- `--from N` : Start từ phase N
-- `--phase N` : Chỉ chạy phase N
+- `--from N` : Start from phase N
+- `--phase N` : Run only phase N
 - `--fast` : Skip optional verifications
 - `--dry-run` : Plan only
 
@@ -32,6 +32,10 @@ cat .viepilot/TRACKER.md
 cat .viepilot/ROADMAP.md
 ```
 
+### load_language_config
+Read `~/.viepilot/config.json` → `COMMUNICATION_LANG` (default: `en`).
+Use `COMMUNICATION_LANG` for all banners, control-point messages, and user-facing output in this session.
+
 Display startup banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -101,6 +105,54 @@ read:
   - context_required files from task file
 ```
 
+#### ⛔ Preflight: Task Paths Validation (BUG-009)
+
+**Before any implementation**, read the `## Paths` block of the task file and validate each listed path:
+
+```
+FOR EACH path in ## Paths:
+  IF path starts with "~/" OR starts with "/" (absolute):
+    → STOP. Do NOT execute this task.
+    → Output:
+
+    ⛔ TASK PATH ERROR (BUG-009)
+    Task {phase}.{task} contains an absolute or external path:
+      "{offending_path}"
+
+    Expected: a repo-relative path (e.g., workflows/foo.md, skills/vp-bar/SKILL.md)
+
+    Fix the task file before continuing:
+      .viepilot/phases/{phase-dir}/tasks/{phase}.{task}.md
+
+    Replace:   {offending_path}
+    With the repo-relative equivalent (e.g., without ~/.claude/viepilot/ prefix).
+
+  ELSE:
+    → Pass. Continue with task execution.
+```
+
+This check fires on `~/`, `~\`, and any path starting with `/`.
+It does NOT fire on paths inside code block content within the task (only the `## Paths` header block is validated).
+
+#### ⛔ PATH RESOLUTION RULE (BUG-012)
+
+**All file reads and edits during task execution MUST be resolved from `{cwd}`** — the repository root where `package.json` lives (e.g. `/Users/.../my-project/`).
+
+```
+WHEN executing a task with:
+  ## Paths
+  workflows/brainstorm.md
+
+→ Read and edit: {cwd}/workflows/brainstorm.md
+→ NEVER:         ~/.claude/viepilot/workflows/brainstorm.md
+→ NEVER:         ~/.cursor/viepilot/workflows/brainstorm.md
+→ NEVER:         any path outside {cwd}
+```
+
+**Rule**: If a file exists at both `{cwd}/workflows/foo.md` (codebase) and `~/.claude/viepilot/workflows/foo.md` (production install), **ALWAYS use the `{cwd}` copy**.
+
+The install directory (`~/.claude/`, `~/.cursor/`) is a **deployment artifact** — it is populated by `dev-install.sh`. Editing it directly bypasses version control and will be silently overwritten on the next install.
+
 ### ViePilot Skill Scope Policy (BUG-004 baseline)
 - **Default mode**: only reference/route skills in the ViePilot namespace (`vp-*`).
 - **External skills** (`non vp-*`) are out of scope by default and must not be suggested implicitly.
@@ -181,6 +233,16 @@ Ensure `PHASE-STATE.md` already shows current task `in_progress` (set during the
    git commit -m "{type}({scope}): {description}"
    git push
    ```
+
+   ⛔ **GITIGNORE-AWARE STAGING RULE (BUG-013)**: Before staging any file, verify it is
+   not gitignored. NEVER stage or commit gitignored files — they are internal state, not
+   shipping artifacts.
+   ```bash
+   # Check before staging:
+   git check-ignore -q {file} && echo "IGNORED — skip" || git add {file}
+   ```
+   `.viepilot/` is ALWAYS gitignored in ViePilot repos. **Never run `git add .viepilot/`.**
+
 8. Log notes in task file after each sub-task
 
 #### Verify Task
@@ -205,6 +267,9 @@ Before marking a task PASS, require durable git persistence:
 ```bash
 # Must have no unstaged/staged residue for this task
 git status --porcelain
+# NOTE (BUG-013): lines starting with "??" are UNTRACKED files — NOT a dirty state.
+# Porcelain is CLEAN when output is empty OR contains only "??" lines.
+# Gitignored files (e.g. .viepilot/) must never be staged, so they appear as ?? here.
 
 # Must track an upstream branch
 git rev-parse --abbrev-ref --symbolic-full-name @{u}