viepilot 2.15.0 → 2.23.0

package/skills/vp-crystallize/SKILL.md

@@ -4,6 +4,18 @@ description: "Convert brainstorm sessions into executable artifacts"
 version: 0.8.0
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-CRYSTALLIZE  v0.8.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-crystallize`, `/vp-crystallize`, hoặc "crystallize", "setup project"
@@ -271,14 +283,18 @@ This skill uses adapter-aware interactive prompts. Behavior depends on your adap
 
 | Adapter | Interactive Prompts | Notes |
 |---------|---------------------|-------|
-| Claude Code (terminal) | ✅ `AskUserQuestion` tool | Click-to-select UI, multi-select, preview panels |
+| Claude Code (terminal) | ✅ `AskUserQuestion` tool — **REQUIRED** | Must call AUQ; plain-text only if tool errors or is unavailable |
 | Claude Code (VS Code ext) | ⚠️ Partial | Terminal yes; VS Code UI pending [anthropics/claude-code#12609](https://github.com/anthropics/claude-code/issues/12609) |
 | Cursor (Plan Mode) | ⚠️ Partial | `AskQuestion` in Plan Mode only — not in Agent/Skills Mode |
 | Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
 | Codex CLI | ❌ Text fallback | Native tool N/A; community MCP available |
 | Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
+| GitHub Copilot | ✅ `/skill-name` in Chat | Via `.agent.md` custom agent; AUQ not available — text fallback |
+
+**Claude Code (terminal) — AUQ preload required (ENH-059):**
+Before the first interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred tool schema. Only after `ToolSearch` succeeds can `AskUserQuestion` be invoked. If `ToolSearch` returns an error, fall back to plain-text numbered list for that session.
 
-When `AskUserQuestion` is not available, the skill automatically falls back to
+When `AskUserQuestion` is not available on other adapters, the skill automatically falls back to
 plain-text numbered list prompts — no configuration required.
 
 **Prompts using AskUserQuestion in this skill:**

package/skills/vp-debug/SKILL.md

@@ -4,6 +4,18 @@ description: "Systematic debugging with persistent state tracking across session
 version: 0.2.0
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-DEBUG  v0.2.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-debug`, `/vp-debug`, "debug", "gỡ lỗi"

package/skills/vp-docs/SKILL.md

@@ -4,6 +4,18 @@ description: "Generate comprehensive documentation for the project"
 version: 0.2.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-DOCS  v0.2.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-docs`, `/vp-docs`, "docs", "documentation", "tài liệu"

package/skills/vp-evolve/SKILL.md

@@ -4,6 +4,18 @@ description: "Upgrade, add features, or start a new milestone"
 version: 0.3.0
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-EVOLVE  v0.3.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-evolve`, `/vp-evolve`, "evolve", "thêm feature", "milestone mới", "upgrade"
@@ -180,6 +192,27 @@ Next action: /vp-auto --from {new_phase}
 ```
 </process>
 
+## Adapter Compatibility
+
+### AskUserQuestion Tool (ENH-048 + ENH-055)
+
+| Adapter | Interactive Prompts | Notes |
+|---------|---------------------|-------|
+| Claude Code (terminal) | ✅ `AskUserQuestion` tool — **REQUIRED** | Must call AUQ; plain-text only if tool errors or is unavailable |
+| Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
+| Codex CLI | ❌ Text fallback | Native tool N/A |
+| Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
+| GitHub Copilot | ✅ `/skill-name` in Chat | Via `.agent.md` custom agent; AUQ not available — text fallback |
+
+**Claude Code (terminal) — AUQ preload required (ENH-059):**
+Before the first interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred tool schema. Only after `ToolSearch` succeeds can `AskUserQuestion` be invoked. If `ToolSearch` returns an error, fall back to plain-text numbered list for that session.
+
+**Prompts using AskUserQuestion in this skill:**
+- Evolve mode selection (Step 2 — Add Feature / New Milestone / Refactor)
+- Complexity selection (Step 3A — S/M/L/XL)
+- Brainstorm routing decision (Step 3A — Yes / No)
+- Workflow continuation (Step 5 — Execute /vp-auto / Create request / Done)
+
 <success_criteria>
 - [ ] User intent correctly identified
 - [ ] Architecture compatibility checked

package/skills/vp-info/SKILL.md

@@ -4,6 +4,18 @@ description: "Display ViePilot version, npm latest, skills/workflows list via vp
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-INFO  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-info`, `/vp-info`, "viepilot version", "phiên bản viepilot", "skills list bundle"

package/skills/vp-pause/SKILL.md

@@ -4,6 +4,18 @@ description: "Pause work with context preservation to resume later"
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-PAUSE  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-pause`, `/vp-pause`, "pause", "dừng", "tạm nghỉ"

package/skills/vp-proposal/SKILL.md

@@ -4,6 +4,18 @@ description: "Generate professional proposal packages (.pptx + .docx + .md) from
 version: 0.1.0
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-PROPOSAL  v0.1.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-proposal`, `/vp-proposal`, "proposal", "pitch deck", "presentation", "tài liệu đề xuất"

package/skills/vp-request/SKILL.md

@@ -4,6 +4,18 @@ description: "Create new request: feature, bug fix, enhancement, or brainstorm c
 version: 0.2.0
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-REQUEST  v0.2.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-request`, `/vp-request`, "request", "yêu cầu", "bug", "lỗi", "feature mới", "nâng cấp"
@@ -273,17 +285,22 @@ This skill uses adapter-aware interactive prompts. Behavior depends on your adap
 
 | Adapter | Interactive Prompts | Notes |
 |---------|---------------------|-------|
-| Claude Code (terminal) | ✅ `AskUserQuestion` tool | Click-to-select UI, multi-select, preview panels |
+| Claude Code (terminal) | ✅ `AskUserQuestion` tool — **REQUIRED** | Must call AUQ; plain-text only if tool errors or is unavailable |
 | Claude Code (VS Code ext) | ⚠️ Partial | Terminal yes; VS Code UI pending [anthropics/claude-code#12609](https://github.com/anthropics/claude-code/issues/12609) |
 | Cursor (Plan Mode) | ⚠️ Partial | `AskQuestion` in Plan Mode only — not in Agent/Skills Mode |
 | Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
 | Codex CLI | ❌ Text fallback | Native tool N/A; community MCP available |
 | Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
+| GitHub Copilot | ✅ `/skill-name` in Chat | Via `.agent.md` custom agent; AUQ not available — text fallback |
+
+**Claude Code (terminal) — AUQ preload required (ENH-059):**
+Before the first interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred tool schema. Only after `ToolSearch` succeeds can `AskUserQuestion` be invoked. If `ToolSearch` returns an error, fall back to plain-text numbered list for that session.
 
-When `AskUserQuestion` is not available, the skill automatically falls back to
+When `AskUserQuestion` is not available on other adapters, the skill automatically falls back to
 plain-text numbered list prompts — no configuration required.
 
 **Prompts using AskUserQuestion in this skill:**
 - Request type detection (Bug / Feature / Enhancement / Tech Debt — Step 2)
 - Bug severity selection (Critical / High / Medium / Low — Step 4A)
 - Feature priority selection (Must-have / Should-have / Nice-to-have — Step 4B)
+- Workflow continuation (Step 6 — Plan /vp-evolve / Create another / Done)

package/skills/vp-resume/SKILL.md

@@ -4,6 +4,18 @@ description: "Resume work from previous session with full context restoration"
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-RESUME  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-resume`, `/vp-resume`, "resume", "tiếp tục", "where was i"

package/skills/vp-rollback/SKILL.md

@@ -4,6 +4,18 @@ description: "Rollback to any checkpoint safely with state preservation"
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-ROLLBACK  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-rollback`, `/vp-rollback`, "rollback", "quay lại"

package/skills/vp-status/SKILL.md

@@ -4,6 +4,18 @@ description: "Display progress dashboard and actionable insights"
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-STATUS  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-status`, `/vp-status`, "status", "tiến độ", "đang ở đâu"

package/skills/vp-task/SKILL.md

@@ -4,6 +4,18 @@ description: "Manual control over individual tasks"
 version: 0.2.0
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-TASK  v0.2.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-task`, `/vp-task`

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

@@ -4,6 +4,18 @@ description: "Manage workflow for collecting and reusing UI components"
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-UI-COMPONENTS  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-ui-components`, `/vp-ui-components`, "ui components", "component library", "21st.dev component"

package/skills/vp-update/SKILL.md

@@ -4,6 +4,18 @@ description: "Upgrade viepilot package via npm (dry-run, --yes, --global) via vp
 version: 0.1.1
 ---
 
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-UPDATE  v0.1.1 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
 <cursor_skill_adapter>
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-update`, `/vp-update`, "upgrade viepilot", "cập nhật viepilot npm"

package/workflows/audit.md

@@ -100,7 +100,10 @@ fi
 ```bash
 # List completed phases (PHASE-STATE.md with status: complete)
 # 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)
+COMPLETE_TAGS=$(git tag 2>/dev/null | grep -E \
+  '(^vp-p[0-9]+-complete$)|(^[a-z0-9-]+-vp-p[0-9]+-complete$)|(^[a-z0-9._-]+-[a-z0-9._-]+-[0-9]+\.[0-9]+\.[0-9]+-vp-p[0-9]+-complete$)' \
+  | sort)
+# Third alternative matches enriched format: prefix-branch-version-vp-pN-complete (ENH-050)
 # Report any phase marked complete in PHASE-STATE.md without a git tag
 ```
 
@@ -215,7 +218,8 @@ for phase_state in $RECENT_PHASES; do
     PHASE_NUM=$(basename "$PHASE_DIR" | grep -o '^[0-9]*' | sed 's/^0*//')
     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)
+    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)
+    # [a-z0-9._-]+ covers both legacy (viepilot-vp-p60) and enriched (viepilot-main-2.17.0-vp-p80) formats
     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
@@ -338,8 +342,7 @@ Include source links and last-updated timestamp.
 
 ```bash
 if [ "$IS_VIEPILOT_FRAMEWORK" != "true" ]; then
-  echo "→ Tier 4 skipped (not a viepilot framework repo)"
-  # Jump to step 5 (report)
+  # Tier 4 skipped silently — not a viepilot framework repo
 fi
 ```
 
@@ -389,14 +392,22 @@ MISSING_IN_SKILLSREF=$(comm -23 <(echo "$ACTUAL_SKILLS_LIST") <(echo "$DOCUMENTE
 ```
 
 ### 4f. Report Tier 4 results
-```
- TIER 4: Framework Integrity
- ─────────────────────────────────────────────────
- Skills count (ARCHITECTURE.md)  {✅ N in sync | ⚠️ N actual vs M documented}
- Workflows count                  {✅ N in sync | ⚠️ N actual vs M documented}
- CLI commands count               {✅ N in sync | ⚠️ N actual vs M documented}
- README.md badges                 {✅ In sync | ⚠️ version/skills/workflows drift}
- docs/skills-reference.md         {✅ Complete | ⚠️ N skills missing}
+
+> **Silent by default (ENH-049):** Only output Tier 4 results when `TIER4_ISSUES > 0`.
+> If all checks pass or Tier 4 was skipped, produce no output — the user does not
+> need to see "✅ In sync" or "ℹ️ Skipped" every run.
+
+```bash
+if [ "$TIER4_ISSUES" -gt 0 ]; then
+  echo " TIER 4: Framework Integrity"
+  echo " ─────────────────────────────────────────────────"
+  # Print each failing check:
+  # Skills count (ARCHITECTURE.md)  ⚠️ N actual vs M documented
+  # Workflows count                  ⚠️ N actual vs M documented
+  # CLI commands count               ⚠️ N actual vs M documented
+  # README.md badges                 ⚠️ version/skills/workflows drift
+  # docs/skills-reference.md         ⚠️ N skills missing
+fi
 ```
 </step>
 
@@ -412,7 +423,6 @@ MISSING_IN_SKILLSREF=$(comm -23 <(echo "$ACTUAL_SKILLS_LIST") <(echo "$DOCUMENTE
  Tier 1: ViePilot State     ✅ All consistent
  Tier 2: Project Docs       ✅ No drift detected
  Tier 3: Stack Practices    {✅ In sync | ⚠️ N issues}
- Tier 4: Framework          {✅ In sync | ℹ️ Skipped}
 
  Everything looks good!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -427,7 +437,9 @@ MISSING_IN_SKILLSREF=$(comm -23 <(echo "$ACTUAL_SKILLS_LIST") <(echo "$DOCUMENTE
  Tier 1: ViePilot State     {✅ | ⚠️ N issues}
  Tier 2: Project Docs       {✅ | ⚠️ N issues}
  Tier 3: Stack Practices    {✅ | ⚠️ N issues}
- Tier 4: Framework          {✅ | ⚠️ N issues | ℹ️ Skipped}
+{if TIER4_ISSUES > 0}
+ Tier 4: Framework          ⚠️ {TIER4_ISSUES} issues
+{/if}
 
  ISSUES DETAIL:
  {list each issue with context}
@@ -512,32 +524,55 @@ Create `.viepilot/audit-report.md`:
 <integration>
 ## Auto-Hook Integration
 
-Add to `workflows/autonomous.md` after phase complete:
+The following `&lt;step name="post_phase_audit"&gt;` block is inserted into `workflows/autonomous.md`
+immediately after the `&lt;step name="phase_complete"&gt;` block (after git tag + push, before
+starting the next phase).
 
 ```xml
-<step name="post_phase_audit">
-## Post-Phase Documentation Audit
-
-After marking phase complete:
-
-1. Run silent audit (Tier 1 + Tier 2 only)
-   ```bash
-   # Conceptually:
-   /vp-audit --silent
-   ```
-
-2. If issues found:
-   ```
-   ⚠️ Documentation may be out of sync.
-   
-   Run /vp-audit to check and fix.
-   
-   Continue anyway? (y/n)
-   ```
-
-3. Recommend running before version bump
-</step>
+&lt;step name="post_phase_audit"&gt;
+## Post-Phase Documentation Audit (Tier 1 + 2 only)
+
+After the phase-complete git tag is created, run a fast silent audit:
+
+```bash
+AUDIT_ISSUES=0
+
+# Tier 1: ROADMAP.md phase marked ✅?
+PHASE_IN_ROADMAP=$(grep -c "Phase ${PHASE_NUM}.*✅" .viepilot/ROADMAP.md 2>/dev/null || echo "0")
+[ "$PHASE_IN_ROADMAP" -eq 0 ] && AUDIT_ISSUES=$((AUDIT_ISSUES+1)) && \
+  echo "⚠️  Tier 1: Phase ${PHASE_NUM} not marked ✅ in ROADMAP.md"
+
+# Tier 1: HANDOFF.json current phase matches?
+HANDOFF_PHASE=$(node -e "try{const h=require('./.viepilot/HANDOFF.json');console.log(h.phase||'')}catch(e){}" 2>/dev/null)
+[ "$HANDOFF_PHASE" != "$PHASE_NUM" ] && AUDIT_ISSUES=$((AUDIT_ISSUES+1)) && \
+  echo "⚠️  Tier 1: HANDOFF.json phase=$HANDOFF_PHASE, expected $PHASE_NUM"
+
+# Tier 2: README.md version badge matches package.json?
+PKG_VERSION=$(node -p "require('./package.json').version" 2>/dev/null)
+README_VERSION=$(grep -o 'version-[0-9]*\.[0-9]*\.[0-9]*' README.md 2>/dev/null | head -1 | sed 's/version-//')
+[ "$PKG_VERSION" != "$README_VERSION" ] && AUDIT_ISSUES=$((AUDIT_ISSUES+1)) && \
+  echo "⚠️  Tier 2: README.md badge=$README_VERSION, package.json=$PKG_VERSION"
+```
+
+If `AUDIT_ISSUES > 0`:
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ POST-PHASE AUDIT: {AUDIT_ISSUES} issue(s) found
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{list issues above}
+
+Fix now before starting next phase? (y/n)
+→ y: run /vp-audit --fix  then continue
+→ n: continue (issues noted, non-blocking)
+```
+
+If `AUDIT_ISSUES == 0`: silent — no output.
+&lt;/step&gt;
+```
+
+> **Note:** This hook runs Tier 1 + Tier 2 checks only (3 fast assertions). It does NOT
+> invoke `/vp-audit` in full — Tier 3 (stack) and Tier 4 (framework) are too slow for
+> a post-phase gate. For a full audit, run `/vp-audit` manually.
 </integration>
 
 <success_criteria>