viepilot 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -9,10 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Planned
 
-- **M1.25 / Phase 29 (ENH-018)** — **Crystallize + ARCHITECTURE**: Mermaid diagrams **complexity-gated** from brainstorm; six diagram kinds with required/optional/N/A; vp-audit / vp-auto / vp-debug alignment; target **1.8.0** on complete.
+ - None.
 
 ### Added
 
+ - None yet.
+
+## [1.8.1] - 2026-04-01
+
+### Fixed
+
+- **M1.26 / Phase 30 (BUG-004) completed** — enforced vp-only namespace behavior across the framework: all `vp-*` skills include scope guard rules, core workflows default to `vp-*` routing only, and external skills are allowed only via explicit user opt-in.
+
+### Added
+
+- `tests/unit/vp-scope-policy-contracts.test.js` — regression tests to ensure all bundled skills/workflows retain the BUG-004 scope policy contract.
+
+### Documentation
+
+- `docs/skills-reference.md`, `docs/user/features/autonomous-mode.md`, `docs/user/features/debug-mode.md`, `docs/user/quick-start.md` — clarified default `vp-*` scope and added explicit opt-in examples for external skills.
+
 ## [1.8.0] - 2026-04-01
 
 ### Added
@@ -274,7 +290,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.8.0...HEAD
+[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.8.1...HEAD
+[1.8.1]: https://github.com/0-CODE/viepilot/compare/v1.8.0...v1.8.1
 [1.8.0]: https://github.com/0-CODE/viepilot/compare/v1.7.0...v1.8.0
 [0.10.0]: https://github.com/0-CODE/viepilot/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/0-CODE/viepilot/compare/v0.8.2...v0.9.0

package/docs/skills-reference.md

@@ -2,6 +2,14 @@
 
 Complete reference for all ViePilot skills.
 
+## ViePilot Scope Policy
+
+- **Default behavior**: ViePilot workflows and responses only use skills under `vp-*`.
+- **Out-of-scope by default**: skills outside the ViePilot namespace are ignored, even if present in the runtime environment.
+- **Explicit opt-in**: external skills are considered only when the user explicitly asks to expand beyond ViePilot scope.
+- **Routing fallback**: if an external skill is mentioned accidentally, prefer the closest built-in `vp-*` command instead.
+- **Opt-in example**: "Trong bước này, cho phép dùng thêm external skills ngoài ViePilot để tham khảo."
+
 ---
 
 ## /vp-brainstorm

package/docs/user/features/autonomous-mode.md

@@ -30,6 +30,12 @@ Mỗi task:
 /vp-auto --dry-run        # Preview, không execute
 ```
 
+## ViePilot Scope Policy (BUG-004)
+
+- Mặc định, `/vp-auto` chỉ route/gợi ý các skill thuộc namespace `vp-*`.
+- Nếu môi trường runtime có skills ngoài framework, workflow sẽ bỏ qua và ưu tiên skill ViePilot tương đương.
+- Chỉ khi bạn ghi rõ yêu cầu mở rộng (explicit opt-in), agent mới được phép dùng external skills.
+
 ### Doc-first gate (v0.8.2 / BUG-001)
 
 Workflow `autonomous.md` yêu cầu **ghi nhận kế hoạch trong file task** và **`PHASE-STATE` → `in_progress`** trước khi chỉnh sửa deliverable. Xem `workflows/autonomous.md` — *Pre-execution documentation gate*.

package/docs/user/features/debug-mode.md

@@ -75,3 +75,4 @@ Active debug sessions:
 - Mô tả problem cụ thể: "X happens when Y" thay vì "something is broken"
 - Một session per issue — không mix nhiều bugs
 - Dùng `/vp-debug continue` sau context reset để không mất progress
+- Theo policy BUG-004, `/vp-debug` mặc định chỉ dùng hệ skill `vp-*`; external skills chỉ dùng khi bạn explicit opt-in.

package/docs/user/quick-start.md

@@ -182,6 +182,14 @@ Hiển thị:
 
 ---
 
+## Skill Scope (BUG-004)
+
+- Theo mặc định, ViePilot chỉ dùng hệ lệnh/skill `vp-*` trong toàn bộ workflow.
+- Nếu bạn thấy đề cập skill ngoài framework, hãy coi đó là out-of-scope trừ khi bạn đã explicit opt-in.
+- Ví dụ opt-in hợp lệ: "Cho phép dùng thêm external skills ngoài ViePilot trong bước research này."
+
+---
+
 ## Next Steps
 
 - [Skills Reference](../skills-reference.md) — Chi tiết tất cả commands

package/package.json

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

package/skills/vp-audit/SKILL.md

@@ -15,6 +15,13 @@ Display audit results clearly with actionable suggestions grouped by tier.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Audit ViePilot project state và documentation để phát hiện drift.

package/skills/vp-auto/SKILL.md

@@ -18,6 +18,13 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 ## D. Subagent Spawning
 Use `Task(subagent_type="generalPurpose", ...)` for parallel execution.
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Autonomous execution của project phases. Cho mỗi phase: analyze → plan → execute → verify → iterate.

package/skills/vp-brainstorm/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với numbered list options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Thu thập ý tưởng, requirements, quyết định kiến trúc cho dự án thông qua interactive Q&A.

package/skills/vp-crystallize/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với numbered list options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.

package/skills/vp-debug/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally. Guide through systematic debugging steps.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Systematic debugging với persistent state tracking. Giúp track vấn đề qua nhiều sessions.

package/skills/vp-docs/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Generate comprehensive documentation từ code và artifacts.

package/skills/vp-evolve/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Nâng cấp hoặc mở rộng dự án sau khi hoàn thành milestone hoặc cần thêm features.

package/skills/vp-info/SKILL.md

@@ -12,6 +12,13 @@ version: 0.1.0
 ## B. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Chạy **`vp-tools info`** để lấy metadata bundle ViePilot (không cần `.viepilot/` trong project đích).

package/skills/vp-pause/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally để gather state info.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Save complete work state để có thể resume từ bất kỳ context nào.

package/skills/vp-request/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với numbered list options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Tạo và quản lý requests cho dự án đang phát triển:

package/skills/vp-resume/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Restore complete project context và resume work seamlessly.

package/skills/vp-rollback/SKILL.md

@@ -15,6 +15,13 @@ Show available checkpoints and confirm before rollback.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Rollback đến bất kỳ checkpoint nào một cách an toàn, với backup và state preservation.

package/skills/vp-status/SKILL.md

@@ -12,6 +12,13 @@ version: 0.1.0
 ## B. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Hiển thị visual progress dashboard với actionable insights.

package/skills/vp-task/SKILL.md

@@ -12,6 +12,13 @@ version: 0.1.0
 ## B. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Manual control over tasks khi cần fine-grained management.

package/skills/vp-ui-components/SKILL.md

@@ -15,6 +15,13 @@ Prompt user conversationally với numbered list options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Thu thập, phân loại, và lưu trữ UI components để tái sử dụng:

package/skills/vp-update/SKILL.md

@@ -12,6 +12,13 @@ version: 0.1.0
 ## B. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <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`.

package/workflows/audit.md

@@ -4,6 +4,13 @@ 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.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="detect_project_type">

package/workflows/autonomous.md

@@ -3,6 +3,13 @@ Autonomous execution của project phases. Cho mỗi phase: analyze → execute
 Pauses at control points cho user decisions.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="initialize">
@@ -90,6 +97,12 @@ read:
   - context_required files from task file
 ```
 
+### 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.
+- **Opt-in rule**: external skills are allowed only when user explicitly requests expansion outside ViePilot scope.
+- **Fallback behavior**: if an external skill appears in environment context, ignore it and continue with nearest `vp-*` equivalent.
+
 Architecture context rule (ENH-018):
 - If `.viepilot/ARCHITECTURE.md` includes a diagram applicability matrix, load only diagrams relevant to current task:
   - `required`: must be consulted before implementation/debug decisions.

package/workflows/brainstorm.md

@@ -3,6 +3,13 @@ Interactive brainstorm session để thu thập ý tưởng, requirements, và q
 Cho phép research ngay trong cùng phiên brainstorm khi cần.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="detect_sessions">

package/workflows/crystallize.md

@@ -2,6 +2,13 @@
 Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="collect_metadata">

package/workflows/debug.md

@@ -3,6 +3,13 @@ Systematic debugging workflow với persistent state tracking.
 Giúp organize debugging process và track progress qua nhiều sessions.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="initialize">

package/workflows/documentation.md

@@ -2,6 +2,13 @@
 Generate comprehensive documentation từ code và artifacts.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="resolve_context">

package/workflows/evolve.md

@@ -2,6 +2,13 @@
 Nâng cấp hoặc mở rộng dự án: thêm features, bắt đầu milestone mới, hoặc refactor.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="detect_state">

package/workflows/request.md

@@ -2,6 +2,13 @@
 Tạo và quản lý requests cho dự án: bugs, features, enhancements, tech debt, và brainstorm continuation.
 </purpose>
 
+## ViePilot Skill Scope Policy (BUG-004)
+
+- Default behavior: only use and suggest skills under `vp-*`.
+- External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
+- If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
+
+
 <process>
 
 <step name="init">