viepilot 1.1.0 → 1.3.1

package/CHANGELOG.md

@@ -16,10 +16,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **M1.19 / Phase 23 (BUG-003) completed** — enforced deterministic git persistence gates for `/vp-auto`: PASS transitions now require clean worktree, configured upstream, and zero unpushed commits (via `vp-tools git-persistence --strict` in workflow).
+- **M1.18 / Phase 22 (BUG-002) completed** — introduced project-scoped checkpoint tags (`{project}-vp-p...`) and kept backward compatibility with legacy `vp-p...` tags for list/rollback flows.
 - **CI coverage** — Jest chỉ instrument process hiện tại; test CLI qua `spawnSync` khiến `bin/vp-tools.cjs` báo **0%**. Đã tách `lib/cli-shared.cjs` (validators, `findProjectRoot`, Levenshtein) và đặt `collectCoverageFrom` trên file đó; bổ sung test in-process + `require.main === module` gate cho CLI; `install.sh` / `dev-install.sh` cài kèm `lib/`.
 
 ### Documentation
 
+- `README.md`, `docs/README.md` — refreshed framework version, skills/commands/test counts, and index notes after M1.18 checkpoint-tag rollout.
+- `workflows/autonomous.md`, `skills/vp-auto/SKILL.md`, `docs/user/features/autonomous-mode.md`, `docs/skills-reference.md` — documented and standardized git persistence gate behavior for `/vp-auto`.
 - `README.md`, `docs/user/quick-start.md` — updated install wizard controls and uninstall command examples.
 - `README.md`, `docs/troubleshooting.md`, `docs/user/quick-start.md` — documented README metric sync flow, `cloc` fallback/install guidance, and maintainer usage.
 - `docs/troubleshooting.md` — added selector TTY fallback guidance and uninstall/reinstall recovery flow for legacy symlink installs.

package/README.md

@@ -2,7 +2,7 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-0.10.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-14-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
@@ -10,7 +10,7 @@
 [![Tests](https://img.shields.io/badge/tests-202%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Versioning:** Shield **0.10.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.0.0**) is the Node package identifier for this repo and may differ; use the framework version for milestone releases and docs.
+**Versioning:** Shield **1.2.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.2.0**) is the Node package identifier for this repo and may differ; use the framework version for milestone releases and docs.
 
 ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) phát triển dự án một cách **tự động**, **có kiểm soát**, và **có thể khôi phục**. Thiết kế theo các tiêu chuẩn chuyên nghiệp: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
@@ -48,14 +48,14 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Project Templates | 11 | AI-GUIDE, ARCHITECTURE, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
 | CLI Tools | 2 | vp-tools.cjs (**13** commands) + viepilot.cjs (guided installer) |
-| Test Files | 3 | Jest unit, integration, AI compatibility (202 tests) |
+| Test Files | 4 | Jest unit + integration + AI compatibility + README metrics tests (231 tests) |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  100% 🎉 M1.14 roadmap phases ✅ (v0.10.0)
+Tổng thể / Overall:  ████████████████████  100% 🎉 M1.18 roadmap phases ✅ (v1.2.0)
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
@@ -184,7 +184,7 @@ Tổng thể / Overall:  ██████████████████
 | **Workflows** | Step-by-step XML-like process definitions |
 | **CLI** | Node.js (vp-tools.cjs, viepilot.cjs) |
 | **State** | JSON (HANDOFF.json) + Markdown (TRACKER.md) |
-| **Version Control** | Git tags for checkpoints (vp-p{N}-t{M}) |
+| **Version Control** | Git tags for checkpoints (`{project}-vp-p{N}-t{M}`, legacy `vp-p{N}-t{M}` supported) |
 
 ---
 
@@ -386,9 +386,9 @@ viepilot/
 │   └── cli-shared.cjs             # Validators, project root, Levenshtein helpers
 │
 ├── bin/                           # CLI tools
-│   └── vp-tools.cjs               # 13 commands (requires ../lib/cli-shared.cjs)
+│   └── vp-tools.cjs               # 14 commands (requires ../lib/cli-shared.cjs)
 │
-├── tests/                         # Test suite (202 tests)
+├── tests/                         # Test suite (231 tests)
 │   ├── unit/                      # Unit tests
 │   │   ├── validators.test.js     # CLI subprocess + in-process coverage tests
 │   │   └── ai-provider-compat.test.js  # 142 AI compat tests
@@ -488,7 +488,7 @@ your-project/
 | [Getting Started](docs/getting-started.md) | Hướng dẫn bắt đầu / Quick start guide |
 | [Quick Start (User)](docs/user/quick-start.md) | 5-minute guide |
 | [Skills Reference](docs/skills-reference.md) | Chi tiết từng skill / Detailed skill docs |
-| [CLI Reference](docs/dev/cli-reference.md) | vp-tools 13 commands |
+| [CLI Reference](docs/dev/cli-reference.md) | vp-tools 14 commands |
 | [Advanced Usage](docs/advanced-usage.md) | Power user features |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues & fixes |
 | [Architecture](docs/dev/architecture.md) | System design |

package/bin/vp-tools.cjs

@@ -19,6 +19,8 @@ const {
   levenshteinDistance,
   findProjectRoot,
   VIEPILOT_DIR,
+  getCheckpointTagPrefix,
+  isCheckpointTag,
 } = require(path.join(__dirname, '../lib/cli-shared.cjs'));
 
 // ============================================================================
@@ -570,10 +572,10 @@ const commands = {
     const { execSync } = require('child_process');
     
     try {
-      const tags = execSync('git tag -l "vp-*" --sort=-creatordate', { 
+      const tags = execSync('git tag --sort=-creatordate', {
         cwd: projectRoot, 
         encoding: 'utf8' 
-      }).trim().split('\n').filter(t => t);
+      }).trim().split('\n').filter(t => t).filter(isCheckpointTag);
 
       if (tags.length === 0) {
         console.log(formatWarning('No checkpoints found'));
@@ -616,6 +618,82 @@ const commands = {
     }
   },
 
+  /**
+   * Output deterministic project-scoped checkpoint tag prefix
+   */
+  'tag-prefix': (args) => {
+    const projectCheck = validators.requireProjectRoot();
+    validateArgs([projectCheck]);
+    const raw = args.includes('--raw');
+    const prefix = getCheckpointTagPrefix(projectCheck.value);
+    if (raw) {
+      console.log(prefix);
+      return;
+    }
+    console.log(formatInfo(`Checkpoint tag prefix: ${colors.bold}${prefix}${colors.reset}`));
+    console.log(JSON.stringify({ prefix }));
+  },
+
+  /**
+   * Validate git persistence readiness for PASS transitions
+   */
+  'git-persistence': (args) => {
+    const projectCheck = validators.requireProjectRoot();
+    validateArgs([projectCheck]);
+    const projectRoot = projectCheck.value;
+    const strict = args.includes('--strict');
+    const { execSync } = require('child_process');
+
+    let cleanWorktree = false;
+    let upstreamConfigured = false;
+    let aheadCount = null;
+    let branch = '';
+
+    try {
+      branch = execSync('git branch --show-current', { cwd: projectRoot, encoding: 'utf8' }).trim();
+    } catch (_e) {
+      branch = '';
+    }
+
+    try {
+      const status = execSync('git status --porcelain', { cwd: projectRoot, encoding: 'utf8' }).trim();
+      cleanWorktree = status.length === 0;
+    } catch (_e) {
+      cleanWorktree = false;
+    }
+
+    try {
+      execSync('git rev-parse --abbrev-ref --symbolic-full-name @{u}', { cwd: projectRoot, encoding: 'utf8' });
+      upstreamConfigured = true;
+    } catch (_e) {
+      upstreamConfigured = false;
+    }
+
+    if (upstreamConfigured) {
+      try {
+        const output = execSync('git rev-list --count @{u}..HEAD', { cwd: projectRoot, encoding: 'utf8' }).trim();
+        aheadCount = parseInt(output, 10);
+      } catch (_e) {
+        aheadCount = null;
+      }
+    }
+
+    const readyForPersistedPass = cleanWorktree && upstreamConfigured && aheadCount === 0;
+    const result = {
+      branch,
+      clean_worktree: cleanWorktree,
+      upstream_configured: upstreamConfigured,
+      ahead_count: aheadCount,
+      ready_for_persisted_pass: readyForPersistedPass,
+    };
+
+    console.log(JSON.stringify(result, null, 2));
+
+    if (strict && !readyForPersistedPass) {
+      process.exit(1);
+    }
+  },
+
   /**
    * Check for potential conflicts
    */
@@ -803,6 +881,22 @@ const commands = {
           'vp-tools version bump minor',
         ],
       },
+      'tag-prefix': {
+        usage: 'vp-tools tag-prefix [--raw]',
+        description: 'Return deterministic project-scoped checkpoint tag prefix',
+        examples: [
+          'vp-tools tag-prefix',
+          'vp-tools tag-prefix --raw',
+        ],
+      },
+      'git-persistence': {
+        usage: 'vp-tools git-persistence [--strict]',
+        description: 'Check if commit/push persistence gate is satisfied',
+        examples: [
+          'vp-tools git-persistence',
+          'vp-tools git-persistence --strict',
+        ],
+      },
     };
 
     if (command && commandHelp[command]) {
@@ -839,6 +933,8 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bold}reset${colors.reset} <target> [-f]      Reset task/phase/all state (interactive)
   ${colors.bold}clean${colors.reset} [-f] [--dry-run]   Clean generated files (interactive)
   ${colors.bold}checkpoints${colors.reset}              List all ViePilot checkpoints (git tags)
+  ${colors.bold}tag-prefix${colors.reset} [--raw]       Show project-scoped checkpoint prefix
+  ${colors.bold}git-persistence${colors.reset} [--strict] Check commit/push persistence readiness
   ${colors.bold}conflicts${colors.reset}                Check for potential conflicts
   ${colors.bold}save-state${colors.reset}               Save current state for precise resume
   ${colors.bold}help${colors.reset} [command]           Show help (optionally for specific command)

package/docs/README.md

@@ -53,7 +53,7 @@
 |----------|-------------|
 | [Getting Started](getting-started.md) | Installation and first steps |
 | [Getting Started (dev entry)](dev/getting-started.md) | Short link into dev guide |
-| [CLI Reference](dev/cli-reference.md) | All 13 `vp-tools` commands with examples |
+| [CLI Reference](dev/cli-reference.md) | All 14 `vp-tools` commands with examples |
 | [Architecture](dev/architecture.md) | System layers, data flow, design decisions |
 | [UI Components Library](dev/ui-components-library.md) | Curation taxonomy, storage contract, reuse flow |
 | [Contributing](dev/contributing.md) | How to add skills, workflows, CLI commands |
@@ -66,7 +66,7 @@
 
 | Document | Description |
 |----------|-------------|
-| [Skills Reference](skills-reference.md) | All 13 skills with flags and examples |
+| [Skills Reference](skills-reference.md) | All 14 skills with flags and examples |
 | [Advanced Usage](advanced-usage.md) | Power user features and patterns |
 
 ---
@@ -122,4 +122,4 @@
 
 ---
 
-*Last updated: 2026-03-31 — ViePilot framework v0.10.0 (see `.viepilot/TRACKER.md`); guided NPX installer flow added.*
+*Last updated: 2026-03-31 — ViePilot framework v1.2.0 (see `.viepilot/TRACKER.md`); project-scoped checkpoint tags delivered.*

package/docs/skills-reference.md

@@ -96,8 +96,9 @@ For each phase:
     2. Create git tag
     3. Execute implementation
     4. Verify results
-    5. Handle outcome (pass/fail)
-    6. Update state
+    5. Enforce git persistence gate (`vp-tools git-persistence --strict`)
+    6. Handle outcome (pass/fail)
+    7. Update state
   Mark phase complete
 ```
 
@@ -109,9 +110,10 @@ AI pauses for user input when:
 - Blocker encountered
 
 ### Git Tags
-- `vp-p{phase}-t{task}` - Task started
-- `vp-p{phase}-t{task}-done` - Task completed
-- `vp-p{phase}-complete` - Phase completed
+- `{project}-vp-p{phase}-t{task}` - Task started
+- `{project}-vp-p{phase}-t{task}-done` - Task completed
+- `{project}-vp-p{phase}-complete` - Phase completed
+- Legacy `vp-p...` tags are still accepted for compatibility
 
 ---
 
@@ -337,9 +339,9 @@ CHANGELOG.md (updated)
 ### Checkpoint Types
 | Tag Pattern | Created By | Meaning |
 |-------------|------------|---------|
-| `vp-p{N}-t{M}` | vp-auto | Task started |
-| `vp-p{N}-t{M}-done` | vp-auto | Task completed |
-| `vp-p{N}-complete` | vp-auto | Phase completed |
+| `{project}-vp-p{N}-t{M}` | vp-auto | Task started |
+| `{project}-vp-p{N}-t{M}-done` | vp-auto | Task completed |
+| `{project}-vp-p{N}-complete` | vp-auto | Phase completed |
 | `v{semver}` | vp-auto | Version release |
 
 ### Safety Guarantees

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

@@ -13,11 +13,12 @@ Autonomous mode điều phối **toàn bộ** phase và task theo `workflows/aut
 ```
 
 Mỗi task:
-1. Tạo git checkpoint tag (`vp-p{N}-t{T}`)
+1. Tạo git checkpoint tag (`{project}-vp-p{N}-t{T}`)
 2. Implement theo acceptance criteria
 3. Verify (automated + manual nếu cần)
 4. Commit với conventional commit message
-5. Tạo done tag (`vp-p{N}-t{T}-done`)
+5. Tạo done tag (`{project}-vp-p{N}-t{T}-done`)
+6. Pass Git persistence gate (clean + pushed) trước khi mark done
 
 ## Flags
 
@@ -82,20 +83,37 @@ Trước khi mark task done, ViePilot kiểm tra:
 
 Nếu bất kỳ gate nào fail → control point.
 
+## Git Persistence Gate (BUG-003)
+
+Trước khi `/vp-auto` được phép mark task/phase là PASS:
+
+```bash
+node bin/vp-tools.cjs git-persistence --strict
+```
+
+Gate chỉ PASS khi:
+- Working tree sạch (không còn thay đổi chưa commit)
+- Nhánh hiện tại có upstream
+- Không còn commit local chưa push (`ahead_count = 0`)
+
+Nếu fail, workflow phải vào control point và **không được** cập nhật state sang `done/complete`.
+
 ## Checkpoints
 
 Mỗi task tạo 2 git tags:
 
 ```bash
-vp-p2-t3        # Bắt đầu task 3 của phase 2
-vp-p2-t3-done   # Hoàn thành task 3 của phase 2
+viepilot-vp-p2-t3        # Bắt đầu task 3 của phase 2
+viepilot-vp-p2-t3-done   # Hoàn thành task 3 của phase 2
 ```
 
 Khi phase complete:
 ```bash
-vp-p2-complete  # Phase 2 hoàn thành
+viepilot-vp-p2-complete  # Phase 2 hoàn thành
 ```
 
+Legacy tags `vp-p...` vẫn được hỗ trợ khi list/rollback để tương thích dự án cũ.
+
 Xem tất cả checkpoints:
 ```bash
 vp-tools checkpoints

package/lib/cli-shared.cjs

@@ -5,6 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execSync } = require('child_process');
 
 const VIEPILOT_DIR = '.viepilot';
 
@@ -19,6 +20,39 @@ function findProjectRoot() {
   return null;
 }
 
+function normalizeTagPart(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+}
+
+function getProjectSlug(root = findProjectRoot()) {
+  if (!root) return 'project';
+  try {
+    const gitTop = execSync('git rev-parse --show-toplevel', { cwd: root, encoding: 'utf8' }).trim();
+    const repoName = path.basename(gitTop);
+    const normalizedRepo = normalizeTagPart(repoName);
+    if (normalizedRepo) return normalizedRepo;
+  } catch (_e) {
+    // fallback to directory name below
+  }
+  return normalizeTagPart(path.basename(root)) || 'project';
+}
+
+function getCheckpointTagPrefix(root = findProjectRoot()) {
+  return `${getProjectSlug(root)}-vp`;
+}
+
+function isCheckpointTag(tag) {
+  const value = String(tag || '');
+  return /^vp-p\d+-(?:t\d+(?:-done)?|complete)$/.test(value)
+    || /^[a-z0-9][a-z0-9-]*-vp-p\d+-(?:t\d+(?:-done)?|complete)$/.test(value)
+    || /^vp-backup-\d{8}-\d{6}$/.test(value)
+    || /^[a-z0-9][a-z0-9-]*-vp-backup-\d{8}-\d{6}$/.test(value);
+}
+
 const validators = {
   isPositiveInteger(value, name = 'value') {
     const num = parseInt(value, 10);
@@ -103,6 +137,10 @@ function levenshteinDistance(a, b) {
 module.exports = {
   VIEPILOT_DIR,
   findProjectRoot,
+  normalizeTagPart,
+  getProjectSlug,
+  getCheckpointTagPrefix,
+  isCheckpointTag,
   validators,
   levenshteinDistance,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.1.0",
+  "version": "1.3.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-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
@@ -47,7 +56,7 @@ If required task details are missing, do not implement until task contract is re
 **Doc-first gate before implementation (BUG-001):**
 - After contract validation and **before** any deliverable code/doc edits: the task `.md` MUST hold a real written plan (`Paths` + `File-Level Plan` or bullet **Implementation Notes**—no bare `{{PLACEHOLDER}}` rows).
 - `PHASE-STATE.md` MUST show the task `in_progress` **before** the first implementation commit for that task.
-- **Do not** create `vp-p{phase}-t{task}` or edit shipping files until both are satisfied (read-only exploration and editing the task file to record the plan are allowed).
+- **Do not** create `{projectPrefix}-vp-p{phase}-t{task}` or edit shipping files until both are satisfied (read-only exploration and editing the task file to record the plan are allowed).
 
 **Preflight before each task implementation:**
 - Read `.viepilot/STACKS.md` (if exists)
@@ -132,7 +141,7 @@ Stack preflight:
 1. Validate task contract (`workflows/autonomous.md`).
 2. Record plan in task file; set task `in_progress` in `PHASE-STATE.md`.
 3. Stack preflight.
-4. Create git tag `vp-p{phase}-t{task}` **only after** steps 1–3 pass.
+4. Create git tag `{projectPrefix}-vp-p{phase}-t{task}` **only after** steps 1–3 pass.
 
 #### 3b. Execute Task
 - Implement according to objective
@@ -177,7 +186,7 @@ When all tasks done:
 - Run phase verification
 - Check phase quality gate
 - Write SUMMARY.md
-- Create git tag: `vp-p{phase}-complete`
+- Create git tag: `{projectPrefix}-vp-p{phase}-complete`
 - Increment version if needed
 
 ### 6. Iterate

package/templates/phase/SUMMARY.md

@@ -26,7 +26,7 @@
 
 ## Files Changed
 
-> Populate by running: `git diff vp-p{{PHASE_NUMBER}}-t1..HEAD --name-status | sort`
+> Populate by running: `TAG_PREFIX=$(vp-tools tag-prefix --raw) && git diff "${TAG_PREFIX}-p{{PHASE_NUMBER}}-t1"..HEAD --name-status | sort`
 > List every file individually. Do NOT use glob patterns or summarize groups.
 
 ### Created
@@ -64,4 +64,4 @@
 {{NOTES}}
 
 ---
-Git Tag: `vp-p{{PHASE_NUMBER}}-complete`
+Git Tag: `{projectPrefix}-vp-p{{PHASE_NUMBER}}-complete`

package/templates/phase/TASK.md

@@ -5,7 +5,7 @@
 - **Status**: not_started | in_progress | blocked | done | skipped
 - **Complexity**: {{COMPLEXITY}}
 - **Dependencies**: {{DEPENDENCIES}}
-- **Git Tag**: vp-p{{PHASE_NUMBER}}-t{{TASK_NUMBER}}
+- **Git Tag**: {projectPrefix}-vp-p{{PHASE_NUMBER}}-t{{TASK_NUMBER}}
 
 ## Objective
 
@@ -97,5 +97,6 @@ manual:
 ## Rollback
 ```bash
 # If need to undo this task:
-git revert --no-commit $(git rev-list vp-p{{PHASE_NUMBER}}-t{{TASK_NUMBER}}..vp-p{{PHASE_NUMBER}}-t{{TASK_NUMBER}}-done)
+TAG_PREFIX=$(vp-tools tag-prefix --raw)
+git revert --no-commit $(git rev-list "${TAG_PREFIX}-p{{PHASE_NUMBER}}-t{{TASK_NUMBER}}".."${TAG_PREFIX}-p{{PHASE_NUMBER}}-t{{TASK_NUMBER}}-done")
 ```

package/workflows/audit.md

@@ -92,8 +92,8 @@ fi
 ### 1d. Git tags vs completed phases
 ```bash
 # List completed phases (PHASE-STATE.md with status: complete)
-# List git tags matching vp-p{N}-complete
-COMPLETE_TAGS=$(git tag 2>/dev/null | grep -E '^vp-p[0-9]+-complete$' | sort)
+# List git tags matching legacy + project-scoped complete format
+COMPLETE_TAGS=$(git tag 2>/dev/null | grep -E '(^vp-p[0-9]+-complete$)|(^[a-z0-9-]+-vp-p[0-9]+-complete$)' | sort)
 # Report any phase marked complete in PHASE-STATE.md without a git tag
 ```
 
@@ -206,8 +206,9 @@ for phase_state in $RECENT_PHASES; do
     PHASE_DIR=$(dirname "$phase_state")
     # Check if docs/ was updated in commits for this phase
     PHASE_NUM=$(basename "$PHASE_DIR" | grep -o '^[0-9]*' | sed 's/^0*//')
-    PHASE_TAG="vp-p${PHASE_NUM}-complete"
-    PREV_TAG=$(git tag --sort=-version:refname 2>/dev/null | grep "vp-p.*-complete" | grep -A1 "^$PHASE_TAG$" | tail -1)
+    TAG_PREFIX=$(vp-tools tag-prefix --raw 2>/dev/null || echo "vp")
+    PHASE_TAG="${TAG_PREFIX}-p${PHASE_NUM}-complete"
+    PREV_TAG=$(git tag --sort=-version:refname 2>/dev/null | grep -E "(vp-p.*-complete|[a-z0-9-]+-vp-p.*-complete)" | grep -A1 "^$PHASE_TAG$" | tail -1)
     if [ -n "$PREV_TAG" ]; then
       DOCS_CHANGED=$(git diff "$PREV_TAG"..HEAD --name-only 2>/dev/null | grep "^docs/" | wc -l | tr -d ' ')
       if [ "$DOCS_CHANGED" -eq 0 ]; then

package/workflows/autonomous.md

@@ -119,7 +119,7 @@ Canonical order for every task: **Validate contract → Doc-first gate → Stack
 
 If any check fails:
 - Mark task `blocked` in `PHASE-STATE.md` and list what is missing under **Notes**
-- **Do not** create `vp-p{phase}-t{task}`
+- **Do not** create `{projectPrefix}-vp-p{phase}-t{task}`
 - **Do not** proceed to **Execute Task**
 
 #### Stack Preflight (token-efficient lookup)
@@ -137,7 +137,7 @@ If stack cache is missing:
 
 Only after **Validate Task Contract**, **Pre-execution documentation gate**, and **Stack Preflight** (or explicit waiver logged in the task file with reason):
 
-Create git tag: `vp-p{phase}-t{task}`  
+Create git tag: `{projectPrefix}-vp-p{phase}-t{task}`  
 Ensure `PHASE-STATE.md` already shows current task `in_progress` (set during the gate if not already).
 
 #### Execute Task
@@ -175,10 +175,32 @@ 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:**
-- Create git tag: `vp-p{phase}-t{task}-done`
+- Create git tag: `{projectPrefix}-vp-p{phase}-t{task}-done`
 - Update PHASE-STATE.md immediately: task → done, append files changed by this task to Files Changed table (individual files, no glob patterns)
 - Update TRACKER.md immediately
 - Update HANDOFF.json immediately
@@ -224,7 +246,8 @@ When all tasks in phase are done/skipped:
    Populate `{{CREATED_FILES}}`, `{{MODIFIED_FILES}}`, `{{DELETED_FILES}}` from git:
    ```bash
    # Get ALL individual files changed since phase start tag
-   git diff vp-p{phase}-t1..HEAD --name-status | sort
+   TAG_PREFIX=$(node bin/vp-tools.cjs tag-prefix --raw)
+   git diff "${TAG_PREFIX}-p{phase}-t1"..HEAD --name-status | sort
    ```
    List **every file individually** — do NOT use glob patterns or summarize.
    Correct example:
@@ -243,7 +266,7 @@ When all tasks in phase are done/skipped:
    | smarttrack-*/pom.xml (8 files) | 1.1 |   ← WRONG: glob pattern
    | smarttrack-*/src/** (7 files)  | 1.1 |   ← WRONG: summarized
    ```
-4. Create git tag: `vp-p{phase}-complete`
+4. Create git tag: `{projectPrefix}-vp-p{phase}-complete`
 5. Check version bump needed:
    - Features added → MINOR
    - Fixes only → PATCH
@@ -252,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)
@@ -280,7 +304,8 @@ Commit: `chore: update ROADMAP.md — phase {N} complete`
 if [ ! -d "skills" ]; then
   echo "→ Skipping skills-reference update (not a viepilot framework repo)"
 else
-  NEW_SKILLS=$(git diff vp-p{phase}-t1..HEAD --name-only | grep 'skills/.*/SKILL\.md' | sed 's|skills/||; s|/SKILL\.md||')
+  TAG_PREFIX=$(node bin/vp-tools.cjs tag-prefix --raw)
+  NEW_SKILLS=$(git diff "${TAG_PREFIX}-p{phase}-t1"..HEAD --name-only | grep 'skills/.*/SKILL\.md' | sed 's|skills/||; s|/SKILL\.md||')
   if [ -n "$NEW_SKILLS" ]; then
     # Append new sections to docs/skills-reference.md
     # (same incremental logic as workflows/documentation.md step 3B)
@@ -392,7 +417,8 @@ Options:
 
 **Rollback:**
 ```bash
-git revert --no-commit $(git rev-list vp-p{phase}-t{task}..HEAD)
+TAG_PREFIX=$(node bin/vp-tools.cjs tag-prefix --raw)
+git revert --no-commit $(git rev-list "${TAG_PREFIX}-p{phase}-t{task}"..HEAD)
 ```
 - Reset task → not_started
 - Continue or stop

package/workflows/rollback.md

@@ -8,7 +8,7 @@ Safe rollback to any ViePilot checkpoint với backup và state preservation.
 ## 1. List Available Checkpoints
 
 ```bash
-git tag -l "vp-*" --sort=-creatordate | head -20
+git tag --sort=-creatordate | rg "(^vp-p|^-*vp-backup|^[a-z0-9-]+-vp-p|^[a-z0-9-]+-vp-backup)" | head -20
 ```
 
 For each tag, get info:
@@ -41,7 +41,7 @@ If `--list` flag, stop here.
 Validate tag exists.
 
 **If --latest:**
-Select most recent vp-* tag.
+Select most recent checkpoint tag (project-scoped or legacy).
 
 **Otherwise:**
 Ask user to select from list or enter tag name.
@@ -98,7 +98,8 @@ Wait for confirmation.
 
 ```bash
 # Create backup tag
-BACKUP_TAG="vp-backup-$(date +%Y%m%d-%H%M%S)"
+TAG_PREFIX="$(vp-tools tag-prefix --raw)"
+BACKUP_TAG="${TAG_PREFIX}-backup-$(date +%Y%m%d-%H%M%S)"
 git tag $BACKUP_TAG
 
 # Backup state files
@@ -126,10 +127,10 @@ git log -1 --oneline
 <step name="update_state">
 ## 7. Update State Files
 
-Parse tag to determine phase/task:
-- `vp-p{N}-t{M}` → Phase N, Task M, status: in_progress
-- `vp-p{N}-t{M}-done` → Phase N, Task M+1, status: not_started
-- `vp-p{N}-complete` → Phase N+1, Task 1, status: not_started
+Parse tag to determine phase/task (support both legacy and project-scoped):
+- `vp-p{N}-t{M}` or `{project}-vp-p{N}-t{M}` → Phase N, Task M, status: in_progress
+- `vp-p{N}-t{M}-done` or `{project}-vp-p{N}-t{M}-done` → Phase N, Task M+1, status: not_started
+- `vp-p{N}-complete` or `{project}-vp-p{N}-complete` → Phase N+1, Task 1, status: not_started
 
 Update HANDOFF.json accordingly.
 Update TRACKER.md progress.