viepilot 2.12.0 → 2.22.0

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>

package/workflows/autonomous.md

@@ -13,6 +13,29 @@ Pauses at control points for user decisions.
 
 - **`/vp-auto`** + this workflow is the **default lane** for **implementing** work that already has a **phase/task plan** (and doc-first **BUG-001**). **`/vp-request`** and **`/vp-evolve`** do **not** replace this step unless the user explicitly overrides — see **Implementation routing guard** in `workflows/request.md` and `workflows/evolve.md`.
 
+## Agent Delegation (ENH-057)
+
+This workflow delegates heavy/repetitive operations to sub-agents defined in `agents/`.
+Each agent is invoked via the pattern below rather than implemented inline.
+
+| Agent | When invoked | Operation |
+|-------|-------------|-----------|
+| tracker-agent | Task start, task complete, phase complete | TRACKER.md status updates |
+| changelog-agent | Post-phase last task (version bump) | CHANGELOG + package.json bump |
+| test-generator-agent | Last task of each phase (contract tests) | Test file generation + run |
+| doc-sync-agent | Bulk edits: ≥5 identical file types in Paths block | Multi-file .md updates |
+
+**Invoke-agent pattern** (Claude Code adapter):
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "{agent-name}: {operation}",
+  prompt: "Load agents/{agent-name}.md for full spec. Execute: {operation} with inputs: {inputs}"
+})
+```
+**Non-Claude Code adapters**: execute the equivalent operation inline in the same session.
+
+See `agents/` directory for full agent specifications.
 
 <process>
 
@@ -36,6 +59,26 @@ cat .viepilot/ROADMAP.md
 Read `~/.viepilot/config.json` → `COMMUNICATION_LANG` (default: `en`).
 Use `COMMUNICATION_LANG` for all banners, control-point messages, and user-facing output in this session.
 
+### Tag Prefix Resolution (ENH-050)
+Resolve the enriched git tag prefix once at session start. All task/phase tags use `${TAG_PREFIX}`.
+
+```bash
+PROJECT_PREFIX=$(node bin/vp-tools.cjs info --prefix 2>/dev/null \
+  || grep -i "^prefix:" .viepilot/PROJECT-META.md 2>/dev/null | awk '{print $2}' \
+  || basename "$(pwd)")
+BRANCH_SAFE=$(git rev-parse --abbrev-ref HEAD 2>/dev/null \
+  | sed 's/[^a-zA-Z0-9._-]/-/g' || echo "main")
+VERSION=$(node -e "try{console.log(require('./package.json').version)}catch(e){console.log('0.0.0')}" 2>/dev/null \
+  || grep '"version"' package.json 2>/dev/null | head -1 | sed 's/.*"\([0-9.]*\)".*/\1/' || echo "0.0.0")
+TAG_PREFIX="${PROJECT_PREFIX}-${BRANCH_SAFE}-${VERSION}"
+# Example: viepilot-main-2.17.0
+# Tags: ${TAG_PREFIX}-vp-p{phase}-t{task}
+#        ${TAG_PREFIX}-vp-p{phase}-t{task}-done
+#        ${TAG_PREFIX}-vp-p{phase}-complete
+```
+
+> Note: dots in version are valid in git tag names. Branch `/` → `-` via sed.
+
 Display startup banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -195,7 +238,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 `{projectPrefix}-vp-p{phase}-t{task}`
+- **Do not** create `{TAG_PREFIX}-vp-p{phase}-t{task}` (where `TAG_PREFIX=${PROJECT_PREFIX}-${BRANCH_SAFE}-${VERSION}`)
 - **Do not** proceed to **Execute Task**
 
 #### Stack Preflight (token-efficient lookup)
@@ -213,9 +256,34 @@ 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: `{projectPrefix}-vp-p{phase}-t{task}`  
+Create git tag: `{TAG_PREFIX}-vp-p{phase}-t{task}` (enriched format: `${PROJECT_PREFIX}-${BRANCH_SAFE}-${VERSION}-vp-p{phase}-t{task}`)
+```bash
+git tag "${TAG_PREFIX}-vp-p${PHASE}-t${TASK}"
+```
 Ensure `PHASE-STATE.md` already shows current task `in_progress` (set during the gate if not already).
 
+#### Bulk-Edit Task Detection — doc-sync-agent (ENH-057)
+
+**Before executing**, scan the `## Paths` block of the task:
+
+```
+IF (Paths block contains ≥5 files of the same type, e.g., skills/*/SKILL.md)
+  OR (task description matches: "update all N files", "add row to all skills", "sync across N files")
+→ Invoke doc-sync-agent instead of N sequential edits:
+
+   Agent({ subagent_type: "general-purpose",
+     description: "doc-sync-agent: {change_mode} across {file_pattern}",
+     prompt: "Load agents/doc-sync-agent.md. Pattern: {glob}. Mode: {change_mode}. Anchor: {anchor}. Content: {content}."
+   })
+   Non-Claude Code: apply changes sequentially inline.
+
+   Example: Task 84.3 "Update all 17 SKILL.md — add Copilot adapter row"
+   → Pattern: skills/*/SKILL.md | Mode: insert-row | Anchor: "| Codex CLI |" | Content: "| GitHub Copilot | ✅ ..."
+   → 1 agent call replaces 17 sequential Edit calls.
+```
+
+If Paths block has < 5 files: proceed with sequential edits as normal.
+
 #### Execute Task
 1. Read task objective and acceptance criteria
 2. Read SYSTEM-RULES.md for coding standards
@@ -289,7 +357,7 @@ If any check fails:
 #### Handle Result
 
 **PASS:**
-- Create git tag: `{projectPrefix}-vp-p{phase}-t{task}-done`
+- Create git tag: `{TAG_PREFIX}-vp-p{phase}-t{task}-done` (e.g. `git tag "${TAG_PREFIX}-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
@@ -312,11 +380,20 @@ After each PASS task and PASS sub-task (state-first, then continue):
 ```yaml
 update:
   - PHASE-STATE.md: task status, timestamp
-  - TRACKER.md: current state, progress
+  - TRACKER.md: current state, progress   ← via tracker-agent (ENH-057)
   - HANDOFF.json: latest position
   - ROADMAP.md: sync when phase status/progress changed
-  - CHANGELOG.md: if feature/fix completed
+  - CHANGELOG.md: if feature/fix completed  ← via changelog-agent at end of phase (ENH-057)
+```
+
+**Tracker updates — invoke tracker-agent:**
+```
+Agent({ subagent_type: "general-purpose",
+  description: "tracker-agent: update task {phase}.{task} → {status}",
+  prompt: "Load agents/tracker-agent.md. Operation: update-task-status. Phase: {phase}. Task: {task}. Status: {status}."
+})
 ```
+Non-Claude Code: update TRACKER.md inline as before.
 
 Rule:
 - Never defer state updates to end-of-phase only.
@@ -355,10 +432,22 @@ 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: `{projectPrefix}-vp-p{phase}-complete`
-5. Check version bump needed:
-   - Features added → MINOR
-   - Fixes only → PATCH
+4. Create git tag: `{TAG_PREFIX}-vp-p{phase}-complete` (e.g. `git tag "${TAG_PREFIX}-vp-p${PHASE}-complete"`)
+5. Check version bump needed — apply `.viepilot/SYSTEM-RULES.md → Version Bump Rules`:
+   - Features added → MINOR; Fixes only → PATCH; Mixed → MINOR; Breaking → MAJOR
+
+   **Version bump — invoke changelog-agent (ENH-057, ENH-053 fix):**
+   ```
+   Agent({ subagent_type: "general-purpose",
+     description: "changelog-agent: bump to {version} + CHANGELOG [{version}]",
+     prompt: "Load agents/changelog-agent.md. Version: {version}. Date: {today}. Entries: {phase_summary_bullets}. Files: package.json + CHANGELOG.md."
+   })
+   ```
+   Non-Claude Code: update CHANGELOG.md + package.json inline as before.
+
+   > changelog-agent is the **single authority** for version bumps. Both autonomous.md and
+   > evolve.md invoke it — never do inline version bumps (resolves ENH-053).
+
 6. Update TRACKER.md
 7. Push all changes:
    ```bash
@@ -406,6 +495,46 @@ fi
 ```
 </step>
 
+<step name="post_phase_audit">
+## 5c. 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}
+
+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.
+</step>
+
 <step name="iterate">
 ## 6. Iterate
 

package/workflows/brainstorm.md

@@ -3,6 +3,15 @@ Interactive brainstorm session to gather ideas, requirements, and decisions for
 Allows research inline within the same brainstorm session when needed.
 </purpose>
 
+## Adapter Compatibility
+
+| Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
+|---------|----------------------|-----------------------|-----------|----------------------|
+| Interactive prompts | ✅ `AskUserQuestion` tool — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
+
 ## ViePilot Skill Scope Policy (BUG-004)
 
 - Default behavior: only use and suggest skills under `vp-*`.
@@ -37,6 +46,15 @@ Parse results to get list of existing sessions.
 ## 2. Ask User Intent
 
 **If previous sessions exist:**
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
+>   - question: "Previous brainstorm sessions found. What would you like to do?"
+>   - header: "Session"
+>   - options: [{ label: "Continue recent session", description: "Resume the most recent session from where it stopped" }, { label: "Review specific session", description: "Choose a particular session to review or continue" }, { label: "New brainstorm session", description: "Start fresh — previous sessions are preserved" }]
+>   - multiSelect: false
+> **Cursor / Codex / Antigravity / other:** use text menu below
+
 ```
 I found previous brainstorm sessions:
 {list sessions with dates}
@@ -118,6 +136,15 @@ If the user is brainstorming a landing page / homepage / marketing page:
    - Visual tone? (minimal, modern, bold, enterprise, playful)
    - Primary CTA and secondary CTA?
 2. Present a layout menu for the user to choose from:
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
+>   - question: "Which landing page layout fits your goals and audience?"
+>   - header: "Layout"
+>   - options: [{ label: "Layout A — Hero centric", description: "Hero + trust logos + features + CTA — best for brand awareness and conversions" }, { label: "Layout B — Problem/Solution", description: "Problem/Solution + social proof + pricing + FAQ — best for SaaS sign-ups" }, { label: "Layout C — Product storytelling", description: "Screenshots + testimonials + final CTA — best for product demos" }, { label: "Layout D — SaaS conversion", description: "Integrations + comparison + onboarding steps — best for tool adoption" }]
+>   - multiSelect: false
+> **Cursor / Codex / Antigravity / other:** use list below
+
    - Layout A: Hero centric + trust logos + features + CTA
    - Layout B: Problem/Solution + social proof + pricing + FAQ
    - Layout C: Product storytelling + screenshots + testimonials + final CTA
@@ -567,6 +594,40 @@ After intake is **completed** or a **valid skip** (META already has profile) →
 <step name="save_session">
 ## 6. Save Session
 
+### Pre-Save Phase Assignment Validation (ENH-052)
+
+Before writing the session file, validate phase assignment completeness:
+
+**Scope-locked session** — `## Phases` section exists with real content OR user confirmed scope finalized (ref: Step 5.1 condition 1):
+
+```
+CHECK 1: Does session draft contain a non-empty ## Phases section?
+CHECK 2: Does Phase 1 have at least one feature/capability assigned?
+CHECK 3: Are there any features listed outside a phase (unassigned)?
+```
+
+**Gate condition:**
+- If scope is locked AND (CHECK 1 fails OR CHECK 2 fails):
+  → **Block save.** Show:
+  ```
+  ⚠️  Phase assignment incomplete — cannot save as Completed.
+
+  Features were discussed but no phase assignments exist.
+  Before saving:
+    1. Assign all features to phases (## Phases section)
+    2. Ensure Phase 1 has at least one feature
+
+  Return to the conversation to assign phases, then /save again.
+  ```
+- If scope is **not** locked (exploratory session — no feature assignments):
+  → **Allow save** with `Status: In Progress` and add advisory note to session file:
+  ```markdown
+  > ⚠️ Exploratory session — no phase assignments yet.
+  > Run /vp-brainstorm to continue and assign features to phases before /vp-crystallize.
+  ```
+- If brownfield stub session (`IS_BROWNFIELD=true`): **skip this gate** — brownfield stubs intentionally have no phases.
+- If all checks pass → proceed to file write below.
+
 Create/update file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
 ```markdown