viepilot 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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

package/README.md

@@ -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) |
 
 ---
 

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/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/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/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.2.0",
   "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

@@ -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)
@@ -132,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
@@ -177,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)
@@ -392,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.