maxsimcli 4.12.0 → 4.14.0

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.14.0",
   "private": false,
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by MayStudios.",
   "bin": {