viepilot 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -16,11 +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 |
@@ -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

@@ -634,6 +634,66 @@ const commands = {
     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
    */
@@ -829,6 +889,14 @@ const commands = {
           '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]) {
@@ -866,6 +934,7 @@ ${colors.cyan}Commands:${colors.reset}
   ${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
 ```
 

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

@@ -18,6 +18,7 @@ Mỗi task:
 3. Verify (automated + manual nếu cần)
 4. Commit với conventional commit message
 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,6 +83,21 @@ 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.2.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

package/workflows/autonomous.md

@@ -175,6 +175,28 @@ 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:**
@@ -253,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)