viepilot 3.7.3 → 3.9.0

package/CHANGELOG.md

@@ -9,6 +9,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.9.0] - 2026-05-24
+
+### Changed
+- ENH-099: skills/vp-auto/SKILL.md — Claude Code adapter tool section expanded with 8 new
+  tools: Monitor, CronCreate/Delete/List, EnterWorktree/ExitWorktree, LSP, PushNotification,
+  EnterPlanMode/ExitPlanMode (sourced from official tools-reference, May 2026)
+- ENH-099: workflows/autonomous.md — TodoWrite deprecated references replaced with
+  TaskCreate/TaskList (disabled since Claude Code v2.1.142); Monitor quality-gate pattern
+  and PushNotification phase-complete notification added
+- ENH-099: docs/dev/agents.md — full 28-event hooks inventory table added; Agent Teams
+  experimental section (TeamCreate, TeamDelete, SendMessage) documented
+
+---
+
+## [3.8.0] - 2026-05-24
+
+### Added
+- ENH-098: vp-brainstorm Stakeholder Generation Gate — AI infers domain-appropriate stakeholders
+  at end of session, creates `.claude/agents/{project-slug}-{role}.md` agent files (haiku-4-5, Read-only)
+- ENH-098: vp-crystallize Step 1G Stakeholder Review Gate — parallel fan-out of all project
+  stakeholder agents, gap analysis synthesis (Gaps/Risks/Suggestions), enriches PROJECT-CONTEXT.md
+  before ROADMAP generation; skippable with `--no-stakeholders`
+- `templates/stakeholder-agent.md` — canonical template for generated stakeholder agent files
+
+---
+
 ## [3.7.3] - 2026-05-23
 
 ### Documentation

package/README.md

@@ -2,15 +2,15 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-3.7.3-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.8.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-21-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-14-orange.svg)](#workflows)
-[![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
+[![Templates](https://img.shields.io/badge/templates-18-cyan.svg)](#templates)
 [![Tests](https://img.shields.io/badge/tests-2210%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Version**: `3.7.3` — tracked in `package.json`, `CHANGELOG.md`, and `.viepilot/TRACKER.md`.
+**Version**: `3.8.0` — tracked in `package.json`, `CHANGELOG.md`, and `.viepilot/TRACKER.md`.
 
 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.
 
@@ -31,7 +31,7 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Total LOC | **~94,739+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **21** |
 | Workflows | **14** |
-| Templates | **17** (Project: 12, Phase: 5) |
+| Templates | **18** (Project: 13, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
 | Tests | **2210** (111 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009/010/011/012/013/015 + ENH-021~037 routing/language/architect/adapter + BUG-009~013 guards + viepilot-info/update/install/adapters) |
 | ViePilot phases (local `.viepilot`) | **142** phase cycles — **v3.7.x** ENH-095~097 orchestrator delegation; **v3.0.0** M3.0 Per-Adapter Intelligence; **v2.4.0** FEAT-015 Codex; **v2.0.0** FEAT-013 dynamic adapters; xem `CHANGELOG.md` |
@@ -167,6 +167,7 @@ Tổng thể / Overall:  ██████████████████
 | `CONTRIBUTING.md` | Contribution guidelines |
 | `CONTRIBUTORS.md` | Attribution list |
 | `README.md` | Professional README template |
+| `stakeholder-agent.md` | Agent template for stakeholder reviews (generated by vp-brainstorm Step S2) |
 
 ### Phase Templates (5)
 

package/docs/dev/agents.md

@@ -139,3 +139,85 @@ describes the exact steps — follow them as a scoped sub-prompt.
 - File: `agents/{name}-agent.md` (kebab-case, always ends in `-agent`)
 - Reference: `{name}-agent` (e.g., `tracker-agent`, not `tracker`)
 - Invocation: `Load agents/{name}-agent.md for full spec.`
+
+## Hook Events Reference (ENH-099)
+
+Complete list of 28 hook events supported in Claude Code (as of May 2026).
+Source: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)
+
+| Hook | Fires When | Blocking | Key ViePilot Use |
+|------|-----------|---------|-----------------|
+| `SessionStart` | Session begins/resumes | No | Inject context, set env, watch paths |
+| `SessionEnd` | Session terminates | No | Cleanup, logging |
+| `UserPromptSubmit` | User submits prompt | Yes | Block/augment prompts; set session title |
+| `UserPromptExpansion` | Slash command expands | Yes | Audit `/vp-*` invocations |
+| `PreToolUse` | Before any tool executes | Yes | Block destructive commands, log ops |
+| `PostToolUse` | After tool succeeds | No | Validate output, add context |
+| `PostToolUseFailure` | After tool fails | No | Log failures |
+| `PostToolBatch` | After parallel tools resolve | Yes | Validate parallel fan-out batch results |
+| `PermissionRequest` | Permission dialog appears | Yes | Auto-approve known safe patterns |
+| `PermissionDenied` | Tool call denied | No | Signal retry allowed |
+| `Stop` | Claude finishes responding | Yes | Continue autonomous loop without re-prompt |
+| `StopFailure` | Turn ends due to API error | No | Error logging |
+| `Notification` | Claude Code sends notification | No | Desktop notification / terminal bell |
+| `SubagentStart` | Subagent spawned | No | Log agent start, inject context |
+| `SubagentStop` | Subagent finishes | Yes | Block premature stop, collect output |
+| `TaskCreated` | TaskCreate tool used | Yes | Enforce naming conventions |
+| `TaskCompleted` | Task marked complete | Yes | Trigger quality gate automatically |
+| `TeammateIdle` | Agent team teammate idle | Yes | Keep agent alive / assign next task |
+| `CwdChanged` | Working directory changes | No | Reactive env setup (direnv) |
+| `FileChanged` | Watched file changes | No | React to test/code file saves |
+| `ConfigChange` | Config file changes | Yes | Block unexpected config changes |
+| `WorktreeCreate` | Worktree being created | Yes | Custom worktree setup |
+| `WorktreeRemove` | Worktree being removed | No | Cleanup |
+| `PreCompact` | Before context compaction | Yes | Block compaction during critical phase steps |
+| `PostCompact` | After compaction completes | No | Re-inject phase context |
+| `Setup` | `--init-only` / `-p --init` | No | One-time dependency installation |
+| `InstructionsLoaded` | CLAUDE.md / rules loaded | No | Audit logging |
+| `Elicitation` | MCP server requests user input | Yes | Auto-respond to MCP prompts |
+
+### Exit code behavior
+- **Exit 0**: success; JSON output processed
+- **Exit 2**: blocking error; stderr shown, event blocked
+- **Other non-zero**: non-blocking; first line of stderr shown
+
+### Most impactful hooks for ViePilot autonomous runs
+- `TaskCreated` + `TaskCompleted` → hook-driven quality gates (no manual trigger needed)
+- `PreCompact` + `PostCompact` → protect long phases from mid-run context loss
+- `SubagentStart` + `SubagentStop` → trace agent orchestration
+- `Stop` → enables fully autonomous `/vp-auto` without re-prompting
+- `PostToolBatch` → validate parallel fan-out results (ENH-096/097 pattern)
+
+## Agent Teams (Experimental)
+
+Agent Teams allow multiple Claude Code sessions to communicate via message passing.
+Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable.
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `TeamCreate` | Create a named team with multiple teammate sessions |
+| `TeamDelete` | Disband team and clean up all teammate processes |
+| `SendMessage` | Send a message to a teammate by name, or resume a stopped subagent |
+
+### Architecture
+
+```
+TeamCreate → defines lead + teammates
+TeamLead   → assigns tasks via SendMessage
+Teammates  → work independently, respond via SendMessage back to lead
+TeamDelete → cleanup after all work complete
+```
+
+### ViePilot roadmap
+
+Agent Teams represent a future upgrade path for the vp-auto orchestration model (ENH-096/097).
+Currently, vp-auto uses fire-and-forget `Agent` spawning (no back-and-forth). Agent Teams
+would enable:
+- Lead orchestrator assigns tasks AND receives status updates
+- Teammates can ask questions mid-task
+- Better handling of inter-task dependency resolution
+
+**Status**: experimental — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
+Not yet used in ViePilot workflows. Tracked via ENH-099.

package/package.json

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

@@ -67,6 +67,22 @@ Use Claude Code tools: `Bash` (shell), `Read` (file), `Edit` + `Write` (file wri
 `Agent` (spawn subagent — multi-level nesting supported)
 Interactive: `AskUserQuestion` (deferred — preload via ToolSearch before first call)
 
+**Additional tools (ENH-099):**
+- `Monitor` — run command in background, each output line fed back to Claude; use for
+  `npm test --watchAll=false`, dev server tail, CI polling mid-conversation
+- `CronCreate` / `CronDelete` / `CronList` — in-session scheduled prompts (survive
+  `--resume`); use for periodic quality checks during long autonomous phases
+- `EnterWorktree` / `ExitWorktree` — isolated git worktree per task; auto-cleanup on
+  exit if no changes; use for parallel task execution without branch conflicts
+  (not available to subagents)
+- `LSP` — code intelligence: type errors after each edit, jump to definition, find
+  references; requires code intelligence plugin; replaces post-edit `tsc --noEmit`
+- `PushNotification` — desktop + phone push on phase complete or control-point pause
+  (Anthropic infra only; not available on Bedrock/Vertex)
+- `EnterPlanMode` / `ExitPlanMode` — plan gate before implementation: EnterPlanMode
+  switches to read-only planning; ExitPlanMode presents plan for approval before any
+  file edits are made
+
 ## D. Subagent Spawning
 Use `Agent` tool for subagent dispatch. For parallel task execution: fan-out with multiple
 `Agent` calls per cluster (see ADAPTER_CONTEXT.orchestration — claude-code supports parallel: true).

package/skills/vp-brainstorm/SKILL.md

@@ -201,6 +201,7 @@ Optional flags:
 - `--research` : Enable proactive research suggestions during the session
 - `--ui` : Enable UI Direction mode (live HTML/CSS direction artifacts + auto-generates `design.md` when design keywords present — ENH-076)
 - `--domain embedded` : Force-activate Embedded Domain Mode (hardware topology, RTOS, pin map, memory layout, protocol matrix, power budget pages + topic probes)
+- `--no-stakeholders` : Skip stakeholder agent generation at session end
 
 ### Reference URL Input (ENH-092)
 
@@ -279,6 +280,11 @@ Key steps:
 9. Before completing the session: **step 5 — Project meta intake (FEAT-009)** in `workflows/brainstorm.md` when binding is missing; sequential Q&A + profile-map disambiguation + write global profile + `.viepilot/META.md`
 10. Save session with structured format (including **`## Project meta intake (FEAT-009)`**, research notes + UI direction references + **`## Phases`**)
 11. Suggest next action: `/vp-crystallize`
+
+**Stakeholder Generation (ENH-098):**
+At session end (scope locked), automatically infers project stakeholders from the domain and
+creates `.claude/agents/{project-slug}-{role}.md` agent files. These are consumed by
+`/vp-crystallize` Step 1G for parallel context review. Skip with `--no-stakeholders`.
 </process>
 
 <success_criteria>

package/skills/vp-crystallize/SKILL.md

@@ -58,6 +58,9 @@ Silent if command unavailable or errors.
 - Skill được gọi khi user mention `vp-crystallize`, `/vp-crystallize`, hoặc "crystallize", "setup project"
 - Treat all user text after the skill mention as `{{VP_ARGS}}`
 
+**Flags:**
+- `--no-stakeholders` : Skip the Step 1G Stakeholder Review Gate (ENH-098)
+
 ## B. User Prompting
 Prompt user conversationally with numbered list options.
 
@@ -434,3 +437,14 @@ and injects skill best practices per task without re-prompting.
 Install skills: `vp-tools install-skill <source>`
 Registry: `vp-tools scan-skills`
 Docs: `docs/user/features/skill-registry.md`
+
+### Step 1F — Cross-Reference Gate
+
+Validates coverage matrix when both Architect and UI Direction workspaces are present.
+Warns on Phase 1 features with no architect OR UI coverage (non-blocking).
+
+### Step 1G — Stakeholder Review Gate (ENH-098)
+
+After scope lock, spawns `.claude/agents/` stakeholder agents in parallel fan-out,
+collects gap analysis (Gaps/Risks/Suggestions), synthesizes feedback to enrich
+PROJECT-CONTEXT.md before ROADMAP generation. Can be skipped with `--no-stakeholders` flag.

package/templates/stakeholder-agent.md

@@ -0,0 +1,51 @@
+---
+name: {{project_slug}}-{{role_slug}}
+description: >
+  Stakeholder reviewer for {{PROJECT_NAME}}. Reviews the project context document
+  from the perspective of a {{ROLE_TITLE}}. Returns a structured gap analysis
+  (Gaps / Risks / Suggestions) to enrich PROJECT-CONTEXT.md.
+model: claude-haiku-4-5
+tools:
+  - Read
+---
+
+You are a **{{ROLE_TITLE}}** reviewing the initial project definition for **{{PROJECT_NAME}}**.
+
+## Your Perspective
+
+{{ROLE_DESCRIPTION}}
+
+## What You Care About
+
+{{ROLE_CONCERNS}}
+
+## Your Task
+
+Read the project context file at `.viepilot/PROJECT-CONTEXT.md`.
+
+Evaluate it from your professional perspective and return a structured review:
+
+### Gaps
+
+List definitions, sections, or decisions that are vague, missing, or contradictory
+from your point of view.
+
+*(Maximum 5 items. One sentence each.)*
+
+### Risks
+
+List concerns, assumptions, or red flags that could cause problems during execution
+or deployment.
+
+*(Maximum 5 items. One sentence each.)*
+
+### Suggestions
+
+List specific additions, clarifications, or reframings that would make the project
+context more complete and actionable from your perspective.
+
+*(Maximum 5 items. One sentence each.)*
+
+---
+
+> Return ONLY the structured review above. Do not summarize the project or ask questions.

package/workflows/autonomous.md

@@ -259,7 +259,7 @@ ELSE:
 
 **Agent Teams mode** (when `ADAPTER_CONTEXT.orchestration.teams == true` AND pending task count ≥ 8):
 - Set `TEAMS_MODE = true`
-- Activate shared TodoWrite task list for teammate coordination
+- Activate shared TaskCreate/TaskList task list for teammate coordination
 - Each Agent worker reads from the shared list rather than receiving an explicit task prompt
 
 #### 3b-orch: Orchestrator Fan-out (Claude Code only)
@@ -342,7 +342,7 @@ On `QUALITY_GATE: FAIL` or `PARTIAL` → route to control point (retry cluster /
 On `QUALITY_GATE: PASS` → update PHASE-STATE.md (all cluster tasks → done), update TRACKER.md, continue.
 
 **Teams mode** (when `TEAMS_MODE == true`):
-- Write all pending task IDs to shared `TodoWrite` list at phase start
+- Write all pending task IDs to shared task list via `TaskCreate` at phase start
 - Each `Agent(vp-task-executor)` reads next available task from shared list
 - Prevents duplicate execution when dispatching ≥ 8 tasks concurrently
 
@@ -689,6 +689,13 @@ quality_gate:
   - no_lint_errors: true
 ```
 
+**Monitor pattern (ENH-099) — long-running verifications:**
+For tests or builds that take minutes, use the `Monitor` tool instead of blocking `Bash`:
+```
+Monitor: tail -f test-output.log — react when output contains "FAIL" or "Tests: N failed"
+```
+This keeps the agentic loop active while the background process runs.
+
 #### Test Generation — test-generator-agent (ENH-057, BUG-028 fix)
 
 **Trigger**: current task is the last task in the phase AND task.md contains `## Acceptance Criteria`
@@ -845,6 +852,12 @@ Before phase-level verification, run a UI stub check:
 2. Check phase quality gate
 3. Write SUMMARY.md using `templates/phase/SUMMARY.md` as base.
 
+**PushNotification (ENH-099, optional):**
+After phase quality gate passes, send a desktop + phone alert:
+- Message: "Phase {N} — {name} complete ✅ ({tasks} tasks, {tests} tests)"
+- Requires Anthropic-hosted Claude Code (not available on Bedrock/Vertex).
+- Call: `PushNotification` tool with the summary message.
+
    Populate `{{CREATED_FILES}}`, `{{MODIFIED_FILES}}`, `{{DELETED_FILES}}` from git:
    ```bash
    # Get ALL individual files changed since phase start tag

package/workflows/brainstorm.md

@@ -2111,6 +2111,107 @@ git push
 ```
 </step>
 
+<step name="stakeholder_gate">
+## 6B. Stakeholder Generation Gate (ENH-098)
+
+Executed automatically after scope is locked and summary is written.
+Skipped if: `--no-stakeholders` flag present in session context, or `config.json → crystallize.stakeholders.enabled: false`.
+
+### Step S1: Infer Stakeholders
+
+From the brainstorm summary, extract:
+- `domain`: the product domain (web-saas, mobile, api, data, e-commerce, infra, other)
+- `product_type`: what kind of product (SaaS, marketplace, internal tool, SDK, mobile app, etc.)
+- `team_size`: from PROJECT-META or persona context (solo/small/medium/large)
+- `project_slug`: short kebab-case name derived from project title (e.g., "myapp", "invoice-app")
+
+Determine stakeholder count:
+- solo + simple domain: 3 stakeholders
+- medium complexity: 4–5 stakeholders
+- enterprise / regulated (fintech, health, legal): 6 stakeholders
+
+Generate stakeholder list based on domain. Examples:
+
+| Domain | Stakeholders |
+|--------|--------------|
+| **web-saas** | cto, product-manager, ux-lead, end-user, business-owner |
+| **mobile** | product-owner, mobile-developer, end-user, app-store-reviewer |
+| **api/platform** | platform-engineer, api-consumer, devops-lead, sre |
+| **e-commerce** | business-owner, customer, marketing-manager, logistics-manager |
+| **data/ml** | data-scientist, ml-engineer, business-analyst, end-user |
+| **other** | infer contextually from brainstorm content |
+
+### Step S2: Write Agent Files
+
+For each stakeholder, create a file at `.claude/agents/{project_slug}-{role_slug}.md` using the template from `templates/stakeholder-agent.md`.
+
+Template structure:
+```markdown
+---
+name: {project_slug}-{role_slug}
+description: Stakeholder reviewer for {PROJECT_NAME}. Reviews project context from the
+  perspective of a {ROLE_TITLE}. Returns gap analysis (Gaps/Risks/Suggestions).
+model: claude-haiku-4-5
+tools:
+  - Read
+---
+
+You are a {ROLE_TITLE} reviewing the project definition for **{PROJECT_NAME}**.
+
+## Your Perspective
+{2-3 sentence role description — who you are, what you own, what matters to you}
+
+## What You Care About
+{4-6 bullet points of specific concerns from this role's angle}
+
+## Your Task
+Read `.viepilot/PROJECT-CONTEXT.md`. Return a structured review with three sections:
+
+### Gaps
+(sections/definitions that are vague, missing, or contradictory from your perspective)
+
+### Risks
+(concerns or red flags that could cause execution problems)
+
+### Suggestions
+(specific additions or clarifications to strengthen the context)
+
+Keep each item to 1 sentence. Maximum 5 items per section.
+```
+
+Substitute variables:
+- `{{project_slug}}` → kebab-case project identifier
+- `{{role_slug}}` → kebab-case role identifier
+- `{{PROJECT_NAME}}` → Full project name
+- `{{ROLE_TITLE}}` → Human-readable role title
+- `{{ROLE_DESCRIPTION}}` → 2-3 sentence persona description
+- `{{ROLE_CONCERNS}}` → 4-6 bullet list of role-specific concerns
+
+Write each file using the Edit/Write tool. Path is relative to project root (where `.claude/` lives).
+
+> **Note**: `.claude/agents/` is the project-level agents directory for Claude Code.
+> For other adapters (Cursor, Codex): skip this step gracefully — agent files won't be created,
+> and the crystallize Step 1G will detect no agents and skip the review gate.
+
+### Step S3: Record in Summary
+
+Append a `## Stakeholders Generated` section to the brainstorm session summary output:
+
+```markdown
+## Stakeholders Generated
+
+The following stakeholder agents have been created in `.claude/agents/`:
+
+| File | Role | Perspective |
+|------|------|-------------|
+| `{project_slug}-cto.md` | CTO | Technical feasibility, stack, security |
+| `{project_slug}-product-manager.md` | Product Manager | Scope, user stories, priorities |
+| ... | ... | ... |
+
+These agents will be called in vp-crystallize Step 1G to review PROJECT-CONTEXT.md.
+```
+</step>
+
 <step name="arch_to_ui_sync">
 ## 6C. Architect → UI Direction Sync (ENH-061)
 

package/workflows/crystallize.md

@@ -2205,6 +2205,90 @@ Run when BOTH `architect_read_complete: true` AND `ui_direction_read_complete: t
 **Skip condition**: if only one workspace is present (not both) → silently skip Step 1F (single-workspace is valid).
 </step>
 
+<step name="stakeholder_review_gate">
+---
+
+## Step 1G: Stakeholder Review Gate (ENH-098)
+
+**Trigger**: Runs automatically after Step 1F, before Step 2.
+
+**Skip conditions**:
+- `--no-stakeholders` flag passed to `/vp-crystallize`
+- `config.json → crystallize.stakeholders.enabled: false`
+- No `.claude/agents/{project-slug}-*.md` files found (gate is silently skipped)
+- Non-Claude-Code adapter (Cursor, Codex, Copilot): skip gracefully
+
+### Step 1G.1 — Discover Stakeholder Agents
+
+```bash
+# Find project stakeholder agents
+ls .claude/agents/ | grep "^{project_slug}-"
+```
+
+If 0 files found: print notice "No stakeholder agents found — skipping Step 1G. Run `/vp-brainstorm` first to generate stakeholder agents, or use `--no-stakeholders` to suppress."
+Then continue to Step 2.
+
+If files found: proceed.
+
+### Step 1G.2 — Parallel Stakeholder Review
+
+Spawn all found stakeholder agents simultaneously (parallel fan-out):
+
+For each `.claude/agents/{project_slug}-{role_slug}.md`:
+```
+Agent({
+  subagent: "{project_slug}-{role_slug}",
+  prompt: "Read .viepilot/PROJECT-CONTEXT.md. Return your structured review (Gaps/Risks/Suggestions)."
+})
+```
+
+Collect all results. Each result is a structured document with three sections:
+- `### Gaps` — missing or vague definitions
+- `### Risks` — execution concerns from this role's perspective
+- `### Suggestions` — specific additions to strengthen the context
+
+### Step 1G.3 — Synthesis
+
+After all agents return:
+
+1. **Aggregate**: collect all Gaps, Risks, Suggestions across all stakeholders
+2. **Deduplicate**: merge identical or near-identical points
+3. **Rank**: sort by frequency (raised by ≥2 stakeholders = high priority) and severity
+4. **Conflict resolution**: if stakeholders disagree (e.g., CTO wants more tech detail, PM wants less), note both perspectives and use the more conservative approach
+5. **Filter**: discard suggestions that are already addressed in PROJECT-CONTEXT.md
+
+### Step 1G.4 — Enrich PROJECT-CONTEXT.md
+
+Apply the top-ranked suggestions to `.viepilot/PROJECT-CONTEXT.md`:
+
+- Add missing sections (e.g., `## Security Considerations`, `## Success Metrics`)
+- Expand vague definitions with the suggested specifics
+- Flag unresolved conflicts as `> ⚠️ Open question: {conflict}` inline
+- Do NOT remove or replace existing content — only add/clarify
+
+### Step 1G.5 — Stakeholder Review Summary Banner
+
+Display to user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ STAKEHOLDER REVIEW COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Stakeholders reviewed: {N}
+ Gaps found: {count} ({high-priority} high priority)
+ Risks flagged: {count}
+ Enrichments applied: {count} additions to PROJECT-CONTEXT.md
+ Open questions: {count} (flagged inline for your review)
+
+ Reviewers: {role_1}, {role_2}, ..., {role_N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then continue to Step 2 (ROADMAP generation).
+
+</step>
+
 <step name="generate_ai_guide">
 ## Step 2: Generate AI-GUIDE.md