viepilot 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -9,16 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Enhanced
 
-- **M1.15 / Phase 18 (FEAT-004) in progress** — npm publish distribution scaffold: package publish metadata, release scripts, secure GitHub Actions `release-npm` workflow, and maintainer publish/rollback guide. Final registry smoke verify is blocked pending npm publish auth.
+- **M1.17 / Phase 21 (ENH-013) completed** — realigned README metrics (`npm run readme:sync` with `cloc`) and moved `.viepilot` to local-only (`.gitignore` + untracked index).
+- **M1.15 / Phase 18 (FEAT-004) completed** — npm distribution flow is now fully closed: publish pipeline passes and package released to npm as `viepilot@1.0.1`.
 - **M1.15 / Phase 19 (FEAT-005) completed** — installer now supports keyboard selector UX (arrow/space/enter), added `viepilot uninstall` command (`--target`, `--yes`, `--dry-run`), and switched dev installer to copy-first flow to avoid symlink-based skill discovery failures.
+- **M1.16 / Phase 20 (FEAT-006) completed** — added README LOC auto-sync command (`npm run readme:sync`) driven by `cloc` with non-blocking fallback, installer `cloc` dependency checks/guidance, and a donate section in README with PayPal/MOMO links.
 
 ### Fixed
 
+- **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/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.
 - `README.md` — Project Scale LOC + M1.11 completion banner; Documentation row includes `api/`
 - `.viepilot/audit-report.md` — PASS after README metric sync (`/vp-audit`)

package/README.md

@@ -16,13 +16,19 @@ ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) ph
 
 ViePilot is a skill framework that enables AI assistants to develop projects **autonomously**, with **control points**, and **recovery capability**. Built with professional standards: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
+### Support ViePilot
+
+Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
+- PayPal: [https://paypal.me/SATCODING](https://paypal.me/SATCODING)
+- MOMO: [https://me.momo.vn/aMINujUPTbIRtbTli6Fd](https://me.momo.vn/aMINujUPTbIRtbTli6Fd)
+
 ---
 
 ## Quy mô dự án / Project Scale
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~24,000+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~22,384+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **14** |
 | Workflows | **12** |
 | Templates | **16** (Project: 11, Phase: 5) |
@@ -31,6 +37,8 @@ ViePilot is a skill framework that enables AI assistants to develop projects **a
 | ViePilot phases (repo) | **15** hoàn thành (xem `.viepilot/TRACKER.md`) |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
+> Metric `Total LOC` có thể được refresh tự động bằng `npm run readme:sync` (dùng `cloc`; nếu thiếu `cloc` script sẽ fallback an toàn).
+
 ### Phân bổ / Breakdown
 
 | Thành phần / Component | Số lượng / Count | Mô tả / Description |
@@ -176,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) |
 
 ---
 

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,22 @@ 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 }));
+  },
+
   /**
    * Check for potential conflicts
    */
@@ -803,6 +821,14 @@ 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',
+        ],
+      },
     };
 
     if (command && commandHelp[command]) {
@@ -839,6 +865,7 @@ ${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}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/dev-install.sh

@@ -31,6 +31,20 @@ echo "  Target: $CURSOR_SKILLS_DIR, $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
 echo ""
 
+check_cloc_dependency() {
+    if command -v cloc >/dev/null 2>&1; then
+        echo -e "  ${GREEN}✓${NC} cloc detected"
+        return 0
+    fi
+
+    echo -e "${YELLOW}  cloc not found.${NC}"
+    echo "  README LOC auto-sync will fallback safely, but metrics won't refresh automatically."
+    echo "  Install suggestion:"
+    echo "    - macOS: brew install cloc"
+    echo "    - Ubuntu/Debian: sudo apt-get install -y cloc"
+    echo "    - Windows: choco install cloc"
+}
+
 # Confirm
 if [ "$AUTO_YES" != "1" ]; then
     read -p "This will replace existing installation with dev files. Continue? (y/n) " -n 1 -r
@@ -95,6 +109,7 @@ echo -e "  ${GREEN}✓${NC} templates"
 echo -e "  ${GREEN}✓${NC} bin"
 echo -e "  ${GREEN}✓${NC} lib"
 echo -e "  ${GREEN}✓${NC} ui-components"
+check_cloc_dependency
 
 # Count installed
 SKILL_COUNT=$(ls -d "$CURSOR_SKILLS_DIR"/vp-*/ 2>/dev/null | wc -l | tr -d ' ')

package/docs/skills-reference.md

@@ -109,9 +109,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 +338,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/troubleshooting.md

@@ -41,6 +41,22 @@ npx viepilot install --target cursor-agent --yes
 
 ---
 
+### README LOC metric is not updating
+
+**Cause**: `cloc` is not installed, so `readme:sync` skips update by design.
+
+```bash
+# Install cloc (macOS)
+brew install cloc
+
+# Then rerun metric sync
+npm run readme:sync
+```
+
+On Linux/Windows, use your package manager (`apt`, `dnf`, `choco`) to install `cloc`.
+
+---
+
 ### `./install.sh: Permission denied`
 
 **Cause**: Script not executable.

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

@@ -13,11 +13,11 @@ 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`)
 
 ## Flags
 
@@ -87,15 +87,17 @@ Nếu bất kỳ gate nào fail → control point.
 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/docs/user/quick-start.md

@@ -48,6 +48,12 @@ vp-tools help
 # Hiển thị targets + ViePilot CLI Tools
 ```
 
+Optional (maintainers):
+```bash
+npm run readme:sync
+# refresh README Total LOC metrics via cloc
+```
+
 ---
 
 ## Step 2: Create a New Project

package/install.sh

@@ -40,6 +40,50 @@ echo "  ViePilot: $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
 echo ""
 
+install_cloc_best_effort() {
+    if command -v cloc >/dev/null 2>&1; then
+        echo "  ✓ cloc detected"
+        return 0
+    fi
+
+    echo -e "${YELLOW}  cloc not found.${NC}"
+    echo "  README metric auto-sync can still run with fallback, but LOC refresh will be skipped."
+    echo "  Suggested install:"
+    echo "    - macOS: brew install cloc"
+    echo "    - Ubuntu/Debian: sudo apt-get install -y cloc"
+    echo "    - Windows: choco install cloc"
+
+    if [ "$AUTO_YES" = "1" ]; then
+        return 0
+    fi
+
+    read -p "  Attempt automatic cloc install now (best effort)? (y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        return 0
+    fi
+
+    if command -v brew >/dev/null 2>&1; then
+        brew install cloc || true
+    elif command -v apt-get >/dev/null 2>&1; then
+        sudo apt-get update && sudo apt-get install -y cloc || true
+    elif command -v dnf >/dev/null 2>&1; then
+        sudo dnf install -y cloc || true
+    elif command -v yum >/dev/null 2>&1; then
+        sudo yum install -y cloc || true
+    elif command -v pacman >/dev/null 2>&1; then
+        sudo pacman -Sy --noconfirm cloc || true
+    else
+        echo -e "${YELLOW}  Could not detect supported package manager. Install cloc manually.${NC}"
+    fi
+
+    if command -v cloc >/dev/null 2>&1; then
+        echo "  ✓ cloc installed"
+    else
+        echo -e "${YELLOW}  cloc is still unavailable; continuing without blocking installation.${NC}"
+    fi
+}
+
 # Confirm installation
 if [ "$AUTO_YES" != "1" ]; then
     read -p "Continue with installation? (y/n) " -n 1 -r
@@ -102,6 +146,9 @@ chmod +x "$VIEPILOT_DIR/bin/vp-tools.cjs"
 chmod +x "$VIEPILOT_DIR/bin/viepilot.cjs"
 echo "    ✓ vp-tools.cjs + viepilot.cjs + lib/cli-shared.cjs"
 
+echo "  Checking optional dependency for README metric sync..."
+install_cloc_best_effort
+
 # Create symlink in PATH (optional)
 echo ""
 if [ "$AUTO_YES" != "1" ]; then

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.0.1",
+  "version": "1.2.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {
@@ -14,6 +14,7 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "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:release": "npm run lint:cli && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run verify:release",

package/skills/vp-auto/SKILL.md

@@ -47,7 +47,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)
@@ -63,6 +63,7 @@ If required task details are missing, do not implement until task contract is re
 
 **Updates on milestone complete:**
 - `README.md` — version badge, skills/workflows counts, Skills Reference table, Workflows table, Project Structure, Completion Status
+- `README.md` metrics — run `npm run readme:sync` when script exists; if `cloc` missing, continue with logged guidance (non-blocking)
 
 **After:** Project built, or paused for user intervention.
 </objective>
@@ -131,7 +132,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
@@ -176,7 +177,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
@@ -178,7 +178,7 @@ quality_gate:
 #### 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 +224,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 +244,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
@@ -280,7 +281,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)
@@ -323,6 +325,11 @@ fi
 Update README.md — **generic updates (all projects)**:
 1. Any version number mentions: update to `$ACTUAL_VERSION`
 2. Any "last updated" or "as of" date references
+3. If project contains `README` metrics table and `scripts/sync-readme-metrics.cjs`, run:
+   ```bash
+   npm run readme:sync || true
+   ```
+   - If `cloc` is unavailable, script must log guidance and continue (non-blocking).
 
 **viepilot framework only** (skip if `skills/` directory does not exist):
 ```bash
@@ -387,7 +394,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.