maxsimcli 4.12.0 → 4.13.0

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [4.12.0](https://github.com/maystudios/maxsimcli/compare/v4.11.0...v4.12.0) (2026-03-11)
+
+
+### Features
+
+* **workflows:** rewrite plan workflows for GitHub-first artifact storage and stage detection ([289fc7e](https://github.com/maystudios/maxsimcli/commit/289fc7e4fbc583e2b182d4a73ebdfc0d85123d2b))
+
 # [4.11.0](https://github.com/maystudios/maxsimcli/compare/v4.10.0...v4.11.0) (2026-03-11)
 
 

package/dist/assets/templates/workflows/go.md

@@ -1,5 +1,5 @@
 <purpose>
-Auto-detect project state through deep context gathering, surface problems proactively, and dispatch to the appropriate MAXSIM command. Uses the Show + Act pattern: display detection reasoning first, then act immediately.
+Auto-detect project state through live GitHub queries, surface problems proactively, and dispatch to the appropriate MAXSIM command. Uses the Show + Act pattern: display detection reasoning first, then act immediately.
 </purpose>
 
 <required_reading>
@@ -30,19 +30,24 @@ PLANNING_EXISTS=$(test -d .planning && echo "true" || echo "false")
 
 If `.planning/` does not exist, skip all other checks and go directly to the decision tree (Rule 1: No project found).
 
-**2. Load project state (if .planning/ exists):**
+**2. Load local project context (always from local files per WIRE-02):**
 ```bash
-# State snapshot
+# State snapshot (local)
 STATE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state-snapshot 2>/dev/null || echo "{}")
-
-# Roadmap analysis
-ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze 2>/dev/null || echo "{}")
 ```
 
-**3. Read key files (if they exist):**
-- `.planning/PROJECT.md` -- project name and vision
-- `.planning/STATE.md` -- blockers, decisions, session continuity
-- `.planning/ROADMAP.md` -- phase structure and progress
+Read local files for project context:
+- `.planning/STATE.md` — blockers, decisions, session continuity
+- `.planning/ROADMAP.md` — phase structure and phase ordering
+
+**3. Live GitHub state (primary source — always-live, no cached state):**
+
+Call `mcp_get_all_progress` to get current state of all phases from GitHub. Returns:
+- `phase_number`, `title`, `issue_number`
+- `total_tasks`, `completed_tasks`, `remaining_tasks`
+- `status` (GitHub board column: To Do / In Progress / In Review / Done)
+
+Call `mcp_detect_interrupted` to check for any phases that were interrupted mid-execution (e.g., agent was stopped while a task was marked in-flight).
 
 **4. Git context:**
 ```bash
@@ -52,20 +57,12 @@ GIT_STATUS=$(git status --porcelain 2>/dev/null | head -20)
 # Recent commits
 RECENT_COMMITS=$(git log --oneline -5 2>/dev/null)
 ```
-
-**5. Phase directory scan:**
-```bash
-# List phase directories and their contents
-ls -1 .planning/phases/ 2>/dev/null
-```
-
-For each phase directory, check for PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md files to determine phase state.
 </step>
 
 <step name="problem_detection">
 **Phase 2: Problem Detection**
 
-Check for problems BEFORE suggesting any action. All problems are blocking -- no severity tiers.
+Check for problems BEFORE suggesting any action. All problems are blocking — no severity tiers.
 
 **Check each of these in order:**
 
@@ -78,7 +75,7 @@ If uncommitted changes exist in `.planning/`:
 ## Problem Detected
 
 **Issue:** Uncommitted changes in .planning/ directory
-**Impact:** State drift -- local planning files may diverge from team or lose work
+**Impact:** State drift — local planning files may diverge from team or lose work
 **Resolution:** Commit planning changes to preserve state
 
 **Files with changes:**
@@ -110,22 +107,18 @@ Resolve this before continuing. Options:
 
 Block until user responds.
 
-**3. Failed verification**
-Check for VERIFICATION.md in the current/latest phase with FAIL status:
-```bash
-grep -l "FAIL\|status: failed" .planning/phases/*/VERIFICATION.md 2>/dev/null | tail -1
-```
-If found:
+**3. Failed verification on GitHub**
+Check if any phase issue has a verification comment with FAIL status (from live GitHub data via `mcp_get_all_progress` — look for phases stuck in "In Review" with a known failure, or check recent comments via `mcp_get_issue_detail` for the current phase issue):
 ```
 ## Problem Detected
 
 **Issue:** Phase verification failed
-**Phase:** {phase number and name}
-**Impact:** Phase is not verified as complete -- may have gaps
+**Phase:** {phase number and name} (GitHub Issue #{issue_number})
+**Impact:** Phase is not verified as complete — may have gaps
 **Resolution:** Re-run verification or fix identified issues
 
 Resolve this before continuing. Options:
-1. View verification results
+1. View verification results (check GitHub issue comments)
 2. Re-execute to fix issues
 3. Skip and continue anyway
 ```
@@ -142,6 +135,8 @@ Block until user responds.
 
 Apply rules in strict precedence order. The FIRST matching rule determines the action.
 
+Use live GitHub data from `mcp_get_all_progress` and `mcp_detect_interrupted` (gathered in Phase 1) as the primary source of truth for phase state. Use local ROADMAP.md for phase ordering only.
+
 ```
 Rule 1: No .planning/ directory?
   -> Action: /maxsim:init
@@ -151,31 +146,35 @@ Rule 2: Has blockers in STATE.md? (not cleared in problem detection)
   -> Action: Surface blocker, suggest resolution
   -> Reasoning: "BLOCKED: {blocker text}"
 
-Rule 3: Active phase has plans but not all executed?
-  -> Check: summaries < plans in current phase directory
+Rule 3: Interrupted phase detected (from mcp_detect_interrupted)?
+  -> Action: /maxsim:execute {N}
+  -> Reasoning: "Phase {N} ({name}) was interrupted. Resuming execution."
+
+Rule 4: Phase "In Progress" on GitHub board with incomplete tasks?
+  -> Check: mcp_get_all_progress returns a phase with status="In Progress" and remaining_tasks > 0
   -> Action: /maxsim:execute {N}
-  -> Reasoning: "Phase {N} ({name}) has {X} plans, {Y} executed. Ready to continue."
+  -> Reasoning: "Phase {N} ({name}) has {remaining} tasks remaining. Ready to continue."
 
-Rule 4: Active phase needs planning? (no PLAN.md files)
-  -> Check: no PLAN.md files in current phase directory
+Rule 5: Phase "To Do" on GitHub board (not yet started)?
+  -> Check: mcp_get_all_progress returns the next unstarted phase (status="To Do")
   -> Action: /maxsim:plan {N}
   -> Reasoning: "Phase {N} ({name}) needs planning."
 
-  Sub-check: Does CONTEXT.md exist?
+  Sub-check: Does local CONTEXT.md exist?
   -> If yes: "Discussion complete, ready for research + planning."
   -> If no: "Starting from discussion stage."
 
-Rule 5: Current phase complete, next phase exists?
-  -> Check: all plans have summaries AND next phase exists in roadmap
-  -> Action: /maxsim:plan {N+1}
-  -> Reasoning: "Phase {N} complete. Next: Phase {N+1} ({name})."
+Rule 6: Current phase "In Review" on GitHub board?
+  -> Check: mcp_get_all_progress returns a phase with status="In Review"
+  -> Action: /maxsim:verify {N}
+  -> Reasoning: "Phase {N} ({name}) is awaiting verification."
 
-Rule 6: All phases complete?
-  -> Check: all phases in roadmap have all plans executed
+Rule 7: All phases "Done" on GitHub board?
+  -> Check: mcp_get_all_progress — all phases have status="Done"
   -> Action: /maxsim:progress
   -> Reasoning: "All phases complete. Milestone ready for review."
 
-Rule 7: None of the above?
+Rule 8: None of the above?
   -> Action: Show interactive menu
   -> Reasoning: "Project state is ambiguous. Here are your options."
 ```
@@ -186,53 +185,55 @@ Rule 7: None of the above?
 
 Once a rule matches, display detection reasoning FIRST, then act immediately.
 
-**Format for auto-dispatch (Rules 1-6):**
+**Format for auto-dispatch (Rules 1-7):**
 
 ```
 ## Detected: {summary of what was found}
 
 **Project:** {project name from PROJECT.md, or "New project"}
 **Milestone:** {milestone from ROADMAP.md, or "Not started"}
-**Current phase:** {phase N - name, or "None"}
-**Status:** {description of current state}
+**Current phase:** {phase N - name, or "None"} (GitHub Issue #{issue_number})
+**GitHub Status:** {board column from live mcp_get_all_progress data}
+**Tasks:** {completed}/{total} complete
 
 **Action:** Running /maxsim:{command} {args}...
 ```
 
 Then immediately dispatch the command using the SlashCommand tool. The user can Ctrl+C if the detection is wrong.
 
-**Important:** Show the detection block, then dispatch. Do not ask for confirmation -- this is Show + Act, not Show + Ask.
+**Important:** Show the detection block, then dispatch. Do not ask for confirmation — this is Show + Act, not Show + Ask.
 </step>
 
 <step name="interactive_menu">
-**Phase 5: Interactive Menu (Rule 7 -- no obvious action)**
+**Phase 5: Interactive Menu (Rule 8 — no obvious action)**
 
-When no clear action is detected, show a contextual menu. The menu items are NOT static -- filter based on what makes sense for the current project state.
+When no clear action is detected, show a contextual menu. The menu items are NOT static — filter based on what makes sense for the current project state (use live GitHub data from mcp_get_all_progress).
 
 ```
 ## Project Status
 
 **Project:** {project name}
 **Milestone:** {milestone}
-**Progress:** {X}/{Y} phases complete
+**GitHub Progress:** {X}/{Y} phases Done on board
 
 What would you like to do?
 
-1. /maxsim:plan {next_phase} -- Plan next phase
-2. /maxsim:quick -- Quick ad-hoc task
-3. /maxsim:progress -- View detailed progress
-4. /maxsim:debug -- Debug an issue
+1. /maxsim:plan {next_phase} — Plan next phase
+2. /maxsim:quick — Quick ad-hoc task
+3. /maxsim:progress — View detailed progress
+4. /maxsim:debug — Debug an issue
 
 Or describe what you'd like to do:
 ```
 
 **Contextual filtering rules:**
-- If phases are planned but not executed: show execute options prominently
-- If all phases are done: show `/maxsim:progress` (offers milestone completion)
+- If phases are "In Progress" on GitHub: show execute options prominently
+- If all phases are "Done" on GitHub: show `/maxsim:progress` (offers milestone completion)
 - If recent git activity suggests debugging: show `/maxsim:debug` prominently
-- If no phases exist: show `/maxsim:plan` prominently
+- If no phases exist on board: show `/maxsim:plan` prominently
 - Always include `/maxsim:quick` as it is always relevant
 - Always include an open-ended fallback ("Or describe what you'd like to do")
+- If GitHub not available (mcp calls fail): fall back to local ROADMAP analysis and note degraded mode
 
 Wait for user selection, then dispatch the chosen command.
 </step>
@@ -242,9 +243,12 @@ Wait for user selection, then dispatch the chosen command.
 <constraints>
 - Never ask for confirmation before dispatching (Show + Act, not Show + Ask)
 - Always surface problems BEFORE suggesting actions
-- All problems block -- no severity tiers, no "warnings"
-- No arguments accepted -- this is pure auto-detection
+- All problems block — no severity tiers, no "warnings"
+- No arguments accepted — this is pure auto-detection
 - No mention of old commands (plan-phase, execute-phase, etc.)
-- Keep initial feedback fast -- show "Analyzing..." before heavy operations
+- Keep initial feedback fast — show "Analyzing..." before heavy operations
+- Primary source for phase state: live GitHub (mcp_get_all_progress, mcp_detect_interrupted)
+- Local reads: STATE.md for blockers/decisions, ROADMAP.md for phase ordering only
 - If context gathering fails (tools not available, etc.), fall back to the interactive menu
 </constraints>
+</output>

package/dist/assets/templates/workflows/progress.md

@@ -1,5 +1,5 @@
 <purpose>
-Check project progress, milestone status, and offer milestone completion when all phases are done. Shows GitHub Issues-based progress alongside local ROADMAP.md progress for cross-validation. Detects phase gaps and intelligently routes to the next action.
+Check project progress, milestone status, and offer milestone completion when all phases are done. Reads status from live GitHub queries (always-live, no cached state). Detects phase gaps and intelligently routes to the next action.
 </purpose>
 
 <required_reading>
@@ -37,64 +37,91 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/maxsim:init`.
 </step>
 
 <step name="load">
-**Use structured extraction from maxsim-tools:**
+**Load local project context (always from local files per WIRE-02):**
 
-Instead of reading full files, use targeted tools to get only the data needed for the report:
-- `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)`
+Use targeted tools to get data needed for the report:
 - `STATE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state-snapshot)`
 
+Read local files for project context:
+- `.planning/config.json` — model profile, workflow flags
+- `.planning/PROJECT.md` — project name and vision
+- `.planning/REQUIREMENTS.md` — requirements context
+- `.planning/STATE.md` — decisions, blockers, metrics
+
 This minimizes orchestrator context usage.
 </step>
 
-<step name="analyze_roadmap">
-**Get comprehensive roadmap analysis (replaces manual parsing):**
+<step name="live_github_phase_overview">
+**Get live phase status from GitHub (primary source — always-live, no cached state):**
+
+Call `mcp_get_all_progress` to get progress for all phases. This returns live data from GitHub Issues:
+- `phase_number`, `title`, `issue_number`
+- `total_tasks`, `completed_tasks`, `remaining_tasks`
+- `status` (the GitHub board column: To Do / In Progress / In Review / Done)
+
+Display as formatted table:
 
-```bash
-ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)
 ```
+## GitHub Issues Progress (Live)
+
+| Phase | Title | Issue | Completed | Total | Remaining | Status |
+|-------|-------|-------|-----------|-------|-----------|--------|
+| 01    | ...   | #12   | 3         | 5     | 2         | In Progress |
+| 02    | ...   | #13   | 0         | 4     | 4         | To Do |
+```
+
+**Also get board column view:**
 
-This returns structured JSON with:
-- All phases with disk status (complete/partial/planned/empty/no_directory)
-- Goal and dependencies per phase
-- Plan and summary counts per phase
-- Aggregated stats: total plans, summaries, progress percent
-- Current and next phase identification
+Call `mcp_query_board` with the project number (from init context / config). Group items by status column (To Do, In Progress, In Review, Done). Display column counts and issue details:
 
-Use this instead of manually reading/parsing ROADMAP.md.
+```
+## Board Status (Live)
+
+| Column      | Count | Issues |
+|-------------|-------|--------|
+| To Do       | 2     | #13, #14 |
+| In Progress | 1     | #12 |
+| In Review   | 0     | — |
+| Done        | 3     | #9, #10, #11 |
+```
+
+**Cross-validate with local ROADMAP.md:**
+- Run `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)` to get local phase data
+- Compare local completion status against GitHub board status
+- Highlight any discrepancies between local and GitHub state in the Issues Detected section
 </step>
 
-<step name="recent">
-**Gather recent work context:**
+<step name="live_github_detail">
+**Per-phase detail (when user requests or for current phase):**
 
-- Find the 2-3 most recent SUMMARY.md files
-- Use `summary-extract` for efficient parsing:
-  ```bash
-  node ~/.claude/maxsim/bin/maxsim-tools.cjs summary-extract <path> --fields one_liner
-  ```
-- This shows "what we've been working on"
-  </step>
+For the current active phase (or any phase requested by user):
+- Call `mcp_get_phase_progress` with the phase issue number to get task-level progress
+- Call `mcp_list_sub_issues` to get individual task status with sub-issue details
+- Display task breakdown with status indicators (✓ done / ⏳ in progress / ○ to do)
+
+**Detect external edits:**
+
+After reading phase data from GitHub, call `mcp_detect_external_edits` for each phase with the stored `body_hash`. Warn in the Issues Detected section if modifications were detected outside the normal workflow.
+</step>
 
 <step name="position">
-**Parse current position from init context and roadmap analysis:**
+**Parse current position from init context and live GitHub data:**
 
-- Use `current_phase` and `next_phase` from `$ROADMAP`
+- Use `current_phase` and `next_phase` from `$ROADMAP` (local) cross-referenced with GitHub board status
 - Note `paused_at` if work was paused (from `$STATE`)
-- Count pending todos: use `init todos` or `list-todos`
-- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
-  </step>
+- Count pending todos: use `mcp_list_todos` for live todo count
+- Check for interrupted phases via `mcp_detect_interrupted`
+</step>
 
 <step name="report">
 **Generate progress bar from maxsim-tools, then present rich status report:**
 
 ```bash
-# Get formatted progress bar
+# Get formatted progress bar (local computation)
 PROGRESS_BAR=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs progress phase-bars --raw)
-
-# Get GitHub Issues-based progress (best-effort, may fail if gh not authenticated)
-GH_PROGRESS=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs mcp_get_all_progress 2>/dev/null || echo '{"error": "GitHub not available"}')
 ```
 
-Present (include GitHub Issues progress if available for cross-validation):
+Present (GitHub Issues is the primary progress source; local ROADMAP is cross-validation):
 
 ```
 # [Project Name]
@@ -102,13 +129,15 @@ Present (include GitHub Issues progress if available for cross-validation):
 **Progress:** {PROGRESS_BAR}
 **Profile:** [quality/balanced/budget]
 
-## Recent Work
-- [Phase X, Plan Y]: [what was accomplished - 1 line from summary-extract]
-- [Phase X, Plan Z]: [what was accomplished - 1 line from summary-extract]
+## GitHub Issues Progress (Live)
+[formatted table from mcp_get_all_progress — see live_github_phase_overview step]
+
+## Board Status (Live)
+[column view from mcp_query_board — see live_github_phase_overview step]
 
 ## Current Position
 Phase [N] of [total]: [phase-name]
-Plan [M] of [phase-total]: [status]
+GitHub Status: [board column from live data]
 CONTEXT: [✓ if has_context | - if not]
 
 ## Key Decisions Made
@@ -119,26 +148,16 @@ CONTEXT: [✓ if has_context | - if not]
 - [extract from $STATE.blockers[]]
 - [e.g. jq -r '.blockers[].text' from state-snapshot]
 
-## GitHub Issues Progress
-(If GH_PROGRESS available and not error)
-- Phase completion status from GitHub Issues
-- Cross-validate with local ROADMAP.md progress
-- Highlight any discrepancies between local and GitHub state
-
 ## Issues Detected
 (Only show if gaps found during analysis)
-- Phase [N]: [issue description, e.g., "Verification failed (2 truths unmet)"]
-- Phase [M]: [issue description, e.g., "Plan exists but not executed"]
+- Phase [N]: [issue description, e.g., "External edit detected — body_hash mismatch"]
+- Phase [M]: [issue description, e.g., "Local: complete, GitHub: In Progress — discrepancy"]
 
 ## Pending Todos
 - [count] pending — /maxsim:quick --todo to review
 
-## Active Debug Sessions
-- [count] active — /maxsim:debug to continue
-(Only show this section if count > 0)
-
 ## What's Next
-[Next phase/plan objective from roadmap analyze]
+[Next phase/plan objective from live GitHub data and local roadmap]
 ```
 
 **Performance metrics table truncation:**
@@ -152,54 +171,40 @@ When displaying the performance metrics table from STATE.md (the `## Performance
 </step>
 
 <step name="route">
-**Determine next action based on verified counts.**
-
-**Step 1: Count plans, summaries, and issues in current phase**
+**Determine next action based on live GitHub data.**
 
-List files in the current phase directory:
+**Step 1: Get live phase state from GitHub**
 
-```bash
-ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
-ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
-ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l
-```
-
-State: "This phase has {X} plans, {Y} summaries."
-
-**Step 1.5: Check for unaddressed UAT gaps**
+Call `mcp_get_all_progress` (already fetched above). Identify:
+- Phases with status "In Progress" that have remaining tasks
+- Phases with status "To Do" (not yet started)
+- Phases with status "Done"
 
-Check for UAT.md files with status "diagnosed" (has gaps needing fixes).
-
-```bash
-# Check for diagnosed UAT with gaps
-grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null
-```
+**Step 1.5: Check for interrupted or external edit issues**
 
-Track:
-- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)
+Call `mcp_detect_interrupted` to check for any phases that were interrupted mid-execution. If any are found, note them — they take priority over new work.
 
-**Step 2: Route based on counts**
+**Step 2: Route based on live GitHub status**
 
 | Condition | Meaning | Action |
 |-----------|---------|--------|
-| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** |
-| summaries < plans | Unexecuted plans exist | Go to **Route A** |
-| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
-| plans = 0 | Phase not yet planned | Go to **Route B** |
+| Interrupted phase detected | Work was cut off | Go to **Route A** (resume) |
+| Phase "In Progress" with remaining tasks | Unfinished execution | Go to **Route A** (continue) |
+| Phase "To Do" | Phase not yet started | Go to **Route B** |
+| All phases "Done" | Milestone complete | Go to **Route D** |
 
 ---
 
-**Route A: Unexecuted plan exists**
+**Route A: Phase in progress or interrupted — continue execution**
 
-Find the first PLAN.md without matching SUMMARY.md.
-Read its `<objective>` section.
+Identify the in-progress or interrupted phase (from `mcp_get_all_progress` or `mcp_detect_interrupted`).
 
 ```
 ---
 
 ## ▶ Next Up
 
-**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
+**Phase {N}: [Phase Name]** — resuming execution
 
 `/maxsim:execute {phase}`
 
@@ -250,50 +255,6 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 
 ---
 
-**Route E: UAT gaps need fix plans**
-
-UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
-
-```
----
-
-## ⚠ UAT Gaps Found
-
-**{phase_num}-UAT.md** has {N} gaps requiring fixes.
-
-`/maxsim:plan {phase} --gaps`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/maxsim:execute {phase}` — execute phase plans (includes verification)
-
----
-```
-
----
-
-**Step 3: Check milestone status (only when phase complete)**
-
-Read ROADMAP.md and identify:
-1. Current phase number
-2. All phase numbers in the current milestone section
-
-Count total phases and identify the highest phase number.
-
-State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
-
-**Route based on milestone status:**
-
-| Condition | Meaning | Action |
-|-----------|---------|--------|
-| current phase < highest phase | More phases remain | Go to **Route C** |
-| current phase = highest phase | Milestone complete | Go to **Route D** |
-
----
-
 **Route C: Phase complete, more phases remain**
 
 Read ROADMAP.md to get the next phase's name and goal.
@@ -318,14 +279,14 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 **Route D: Milestone complete**
 
-All phases are done. Offer milestone completion interactively:
+All phases are "Done" on the GitHub board. Offer milestone completion interactively:
 
 ```
 ---
 
 ## Milestone Complete!
 
-All {N} phases are complete. Ready to wrap up?
+All {N} phases are complete (all "Done" on GitHub board). Ready to wrap up?
 
 1. Complete milestone (archive, create release notes) → `/maxsim:init` (detects milestone completion)
 2. Start new milestone → `/maxsim:init` (starts new milestone flow)
@@ -373,21 +334,27 @@ Ready to plan the next milestone.
 - Phase complete but next phase not planned → offer `/maxsim:plan [next]`
 - All work complete → offer milestone completion via `/maxsim:init`
 - Blockers present → highlight before offering to continue
-- Phase gaps detected → surface in Issues Detected section
-- Handoff file exists → mention it, offer `/maxsim:go`
+- External edits detected → surface in Issues Detected section before routing
+- Discrepancy between local ROADMAP and GitHub board → surface in Issues Detected, ask user to reconcile
+- GitHub not available (mcp calls fail) → fall back to local ROADMAP analysis and note degraded mode
   </step>
 
 </process>
 
 <success_criteria>
 
-- [ ] Rich context provided (recent work, decisions, issues)
-- [ ] GitHub Issues progress shown (cross-validated with local ROADMAP)
-- [ ] Phase gaps detected and surfaced in Issues Detected section
+- [ ] Rich context provided (decisions, blockers, issues)
+- [ ] GitHub Issues progress shown as primary source (always-live reads via mcp_get_all_progress)
+- [ ] Board column view shown via mcp_query_board
+- [ ] Per-phase task detail available via mcp_get_phase_progress and mcp_list_sub_issues
+- [ ] External edit detection via mcp_detect_external_edits
+- [ ] Cross-validation between local ROADMAP.md and GitHub board status
+- [ ] Phase gaps and discrepancies detected and surfaced in Issues Detected section
 - [ ] Current position clear with visual progress
 - [ ] What's next clearly explained
-- [ ] Smart routing: /maxsim:execute if plans exist, /maxsim:plan if not
+- [ ] Smart routing: /maxsim:execute if in progress, /maxsim:plan if not started
 - [ ] Milestone completion offered when all phases done
 - [ ] User confirms before any action
 - [ ] Seamless handoff to appropriate maxsim command
       </success_criteria>
+</output>

package/dist/assets/templates/workflows/verify-phase.md

@@ -5,7 +5,7 @@ Before executing any step in this workflow, verify:
 </sanity_check>
 
 <purpose>
-Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, not just that tasks completed.
+Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, not just that tasks completed. Posts verification results as GitHub comments on the phase issue (no local VERIFICATION.md or UAT.md files are written).
 
 Executed by a verification subagent spawned from execute-phase.md.
 </purpose>
@@ -39,13 +39,16 @@ INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init phase-op "${PHASE_ARG}")
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
 
-Then load phase details and list plans/summaries:
+Then load phase details:
 ```bash
 node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "${phase_number}"
 grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null
-ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null
 ```
 
+**Get the phase issue number from GitHub (live):**
+
+Call `mcp_get_all_progress` and find the entry where `phase_number` matches. Extract `issue_number` — this is used for posting all verification results as GitHub comments.
+
 Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks) and **requirements** from REQUIREMENTS.md if it exists.
 </step>
 
@@ -172,7 +175,7 @@ For each requirement: parse description → identify supporting truths/artifacts
 </step>
 
 <step name="scan_antipatterns">
-Extract files modified in this phase from SUMMARY.md, scan each:
+Extract files modified in this phase from local plan files, scan each:
 
 | Pattern | Search | Severity |
 |---------|--------|----------|
@@ -212,21 +215,105 @@ If gaps_found:
 3. **Order by dependency:** Fix missing → fix stubs → fix wiring → verify.
 </step>
 
-<step name="create_report">
-```bash
-REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
+<step name="post_verification_to_github">
+**Post verification results as a GitHub comment (primary output — no local file written).**
+
+Build the verification content in memory using the same structured format as the verification report template. Then call `mcp_post_comment` with `type: 'verification'` on the phase issue:
+
 ```
+mcp_post_comment({
+  issue_number: {PHASE_ISSUE_NUMBER},
+  type: 'verification',
+  body: {
+    status: 'passed' | 'gaps_found' | 'human_needed',
+    score: '{verified}/{total}',
+    phase: '{phase_number} — {phase_name}',
+    timestamp: '{ISO timestamp}',
+    truths_checked: [
+      { truth: '...', status: 'VERIFIED | FAILED | UNCERTAIN', evidence: '...' }
+    ],
+    artifacts_verified: [
+      { path: '...', exists: true/false, substantive: true/false, wired: true/false, status: 'VERIFIED | STUB | MISSING | ORPHANED' }
+    ],
+    key_links_validated: [
+      { from: '...', to: '...', via: '...', status: 'WIRED | PARTIAL | NOT_WIRED' }
+    ],
+    antipatterns: [
+      { file: '...', line: N, pattern: '...', severity: 'Blocker | Warning | Info' }
+    ],
+    human_verification_items: [
+      { name: '...', steps: '...', expected: '...', reason: '...' }
+    ],
+    gaps: [
+      { description: '...', fix_plan: '...' }
+    ],
+    fix_plans: [
+      { name: '...', objective: '...', tasks: ['...'] }
+    ]
+  }
+})
+```
+
+The comment is the canonical record of this verification run.
+</step>
+
+<step name="run_uat">
+**User Acceptance Testing (UAT):**
+
+Present the human verification items to the user and walk through each one. After the user completes UAT:
+
+Build the UAT results in memory, then post as a GitHub comment by calling `mcp_post_comment` with `type: 'uat'` on the phase issue:
+
+```
+mcp_post_comment({
+  issue_number: {PHASE_ISSUE_NUMBER},
+  type: 'uat',
+  body: {
+    status: 'passed' | 'gaps_found',
+    phase: '{phase_number} — {phase_name}',
+    timestamp: '{ISO timestamp}',
+    items: [
+      { name: '...', result: 'pass | fail', notes: '...' }
+    ],
+    gaps: [
+      { description: '...', severity: 'Blocker | Warning' }
+    ]
+  }
+})
+```
+
+Do NOT write a UAT.md file to `.planning/phases/`.
+</step>
+
+<step name="board_transition">
+**Update GitHub board based on verification outcome.**
+
+**If verification passes AND PR is merged:**
+1. Call `mcp_move_issue` to move the phase issue to the "Done" column on the board
+2. Call `mcp_close_issue` to close the phase issue
+3. Report to orchestrator: phase complete, issue closed
+
+**If verification passes but PR not yet merged:**
+1. Keep the phase issue in "In Review" on the board
+2. Note: board will be updated when PR merges
 
-Fill template sections: frontmatter (phase/timestamp/status/score), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
+**If verification fails (gaps_found):**
+1. Check current board column for the phase issue
+2. If in "In Review": call `mcp_move_issue` to move back to "In Progress"
+3. Post failure details as a verification comment (already done in post_verification_to_github step)
+4. Note which gaps need fixing before re-verification
 
-See ~/.claude/maxsim/templates/verification-report.md for complete template.
+**If human_needed:**
+1. Keep the phase issue in its current column (do not move)
+2. The UAT comment posted above documents what needs human testing
 </step>
 
 <step name="return_to_orchestrator">
-Return status (`passed` | `gaps_found` | `human_needed`), score (N/M must-haves), report path.
+Return status (`passed` | `gaps_found` | `human_needed`), score (N/M must-haves), GitHub issue number and comment URL.
 
-If gaps_found: list gaps + recommended fix plan names.
-If human_needed: list items requiring human testing.
+If gaps_found: list gaps + recommended fix plan names. Phase issue has been moved back to "In Progress" on the board.
+If human_needed: list items requiring human testing. UAT comment posted to GitHub issue.
+If passed: phase issue moved to "Done" and closed on GitHub.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
 </step>
@@ -234,6 +321,7 @@ Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execu
 </process>
 
 <success_criteria>
+- [ ] Phase issue number retrieved from live GitHub via mcp_get_all_progress
 - [ ] Must-haves established (from frontmatter or derived)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels
@@ -243,6 +331,9 @@ Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execu
 - [ ] Human verification items identified
 - [ ] Overall status determined
 - [ ] Fix plans generated (if gaps_found)
-- [ ] VERIFICATION.md created with complete report
+- [ ] Verification results posted as GitHub comment via mcp_post_comment (type: 'verification') — NO local VERIFICATION.md written
+- [ ] UAT results posted as GitHub comment via mcp_post_comment (type: 'uat') — NO local UAT.md written
+- [ ] Board transition executed: mcp_move_issue + mcp_close_issue on pass; mcp_move_issue back to In Progress on fail
 - [ ] Results returned to orchestrator
 </success_criteria>
+</output>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxsimcli",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "private": false,
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by MayStudios.",
   "bin": {