maxsimcli 4.8.0 → 4.9.0

package/dist/assets/templates/workflows/execute-plan.md

@@ -77,7 +77,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → spawn Task(subagent_type="maxsim-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.
+**Pattern A:** init_agent_tracking → spawn Task(subagent_type="executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
@@ -110,7 +110,7 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
 
 1. Parse segment map: checkpoint locations and types
 2. Per segment:
-   - Subagent route: spawn maxsim-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
+   - Subagent route: spawn executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
    - Main route: execute tasks using standard flow (step name="execute")
 3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
    - Verify key-files.created exist on disk with `[ -f ]`
@@ -131,6 +131,42 @@ cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 This IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout.
 </step>
 
+<step name="pre_execution_gates">
+Validate requirements before execution. These gates ensure spec-driven development.
+
+**Gate G1: Requirement Existence** — All requirement IDs from the plan's frontmatter must exist in REQUIREMENTS.md.
+
+```bash
+# Extract requirement IDs from plan frontmatter
+REQ_IDS=$(grep "^requirements:" "$PLAN_PATH" | sed 's/requirements:\s*\[//;s/\]//;s/,/ /g;s/"//g;s/'\''//g' | tr -s ' ')
+if [ -n "$REQ_IDS" ]; then
+  G1_RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs verify requirement-existence $REQ_IDS)
+  G1_VALID=$(echo "$G1_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).valid))")
+  if [ "$G1_VALID" != "true" ]; then
+    G1_MISSING=$(echo "$G1_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).missing.join(', ')))")
+    echo "GATE G1 FAILED: Requirements not found in REQUIREMENTS.md: $G1_MISSING"
+    echo "Fix: Add missing requirements to REQUIREMENTS.md or update plan frontmatter."
+    # STOP execution — this is a hard gate
+  fi
+fi
+```
+
+**Gate G2: Requirement Status** — Requirement IDs must not already be marked Complete.
+
+```bash
+if [ -n "$REQ_IDS" ]; then
+  G2_RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs verify requirement-status $REQ_IDS)
+  G2_VALID=$(echo "$G2_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).valid))")
+  if [ "$G2_VALID" != "true" ]; then
+    G2_COMPLETE=$(echo "$G2_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).already_complete.join(', ')))")
+    echo "GATE G2 WARNING: Requirements already marked complete: $G2_COMPLETE"
+    echo "This plan may be re-implementing completed work. Proceeding with warning."
+    # WARNING only — log but continue (re-execution scenarios are valid)
+  fi
+fi
+```
+</step>
+
 <step name="previous_phase_check">
 ```bash
 node ~/.claude/maxsim/bin/maxsim-tools.cjs phases list --type summaries --raw
@@ -348,12 +384,41 @@ Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready f
 
 After implementation is complete and SUMMARY.md is created, run the full review cycle before proceeding. All four stages must pass before the plan is considered done.
 
-**Stage 1: Spec Review** — Verify implementation matches plan spec.
+### Retry Counter Initialization
+
+```
+SPEC_ATTEMPTS=0
+CODE_ATTEMPTS=0
+SIMPLIFY_ATTEMPTS=0
+FINAL_ATTEMPTS=0
+MAX_REVIEW_ATTEMPTS=3
+REVIEW_ESCALATIONS=0
+REVIEW_ESCALATION_DETAILS=""
+REVIEW_CYCLE_START=$(date +%s)
+```
+
+---
+
+### Stage 1: Spec Review — Verify implementation matches plan spec.
+
+```
+SPEC_STAGE_START=$(date +%s)
+SPEC_RESULT="PENDING"
+```
+
+**Retry loop (max MAX_REVIEW_ATTEMPTS):**
+
+1. Increment `SPEC_ATTEMPTS`
+2. Spawn verifier:
 
 ```
 Task(
-  subagent_type="maxsim-spec-reviewer",
+  subagent_type="verifier",
   prompt="
+    ## Task: Review for spec compliance
+
+    ## Suggested Skills: verification-gates, evidence-collection
+
     <objective>
     Review plan {phase}-{plan} for spec compliance.
     </objective>
@@ -381,14 +446,54 @@ Task(
 )
 ```
 
-**If spec review FAILS:** Fix unmet requirements, re-run verification, update SUMMARY.md, then re-run spec review. Do not proceed until PASS.
+3. **If PASS:** Set `SPEC_RESULT="PASS"`, record `SPEC_STAGE_END=$(date +%s)`, proceed to Stage 2.
+
+4. **If FAIL and SPEC_ATTEMPTS < MAX_REVIEW_ATTEMPTS:** Fix the unmet requirements identified by the verifier, re-stage and commit fixes (`fix({phase}-{plan}): address spec review findings`), update SUMMARY.md, then loop back to step 1.
+
+5. **If FAIL and SPEC_ATTEMPTS >= MAX_REVIEW_ATTEMPTS:** Escalate to user:
+
+```markdown
+## Review Escalation: Spec Review Failed After 3 Attempts
+
+**Stage:** Spec Review
+**Attempts:** 3/3
+**Last failure reason:** {failure details from verifier}
+
+The spec review has failed 3 times. This may indicate a fundamental mismatch between the plan spec and the implementation.
+
+**Options:**
+1. Fix manually and type "retry" to re-run spec review (resets attempt counter)
+2. Type "override" to skip spec review (will be flagged in SUMMARY.md)
+3. Type "abort" to stop execution
+```
+
+Wait for user response:
+- **"retry":** Reset `SPEC_ATTEMPTS=0`, loop back to step 1.
+- **"override":** Set `SPEC_RESULT="OVERRIDDEN"`, increment `REVIEW_ESCALATIONS`, record `SPEC_STAGE_END=$(date +%s)`, proceed to Stage 2.
+- **"abort":** Stop execution, create partial SUMMARY.md with review status.
+
+---
+
+### Stage 2: Code Review — Check code quality, security, error handling.
+
+```
+CODE_STAGE_START=$(date +%s)
+CODE_RESULT="PENDING"
+```
+
+**Retry loop (max MAX_REVIEW_ATTEMPTS):**
 
-**Stage 2: Code Review** — Check code quality, security, error handling.
+1. Increment `CODE_ATTEMPTS`
+2. Spawn verifier:
 
 ```
 Task(
-  subagent_type="maxsim-code-reviewer",
+  subagent_type="verifier",
   prompt="
+    ## Task: Review code quality
+
+    ## Suggested Skills: code-review
+
     <objective>
     Review plan {phase}-{plan} code quality. Spec compliance already verified.
     </objective>
@@ -407,16 +512,61 @@ Task(
 )
 ```
 
-**If code review is BLOCKED:** Fix all blocker and high-severity issues. Re-run code review. Do not proceed until APPROVED.
+3. **If APPROVED:** Set `CODE_RESULT="APPROVED"`, record `CODE_STAGE_END=$(date +%s)`, proceed to Stage 3.
 
-**Stage 3: Simplify** — Spawn 3 parallel reviewers to catch reuse opportunities, quality issues, and inefficiencies.
+4. **If BLOCKED and CODE_ATTEMPTS < MAX_REVIEW_ATTEMPTS:** Fix all blocker and high-severity issues, re-stage and commit fixes (`fix({phase}-{plan}): address code review findings`), then loop back to step 1.
 
-**Reviewer 1 — Code Reuse:**
+5. **If BLOCKED and CODE_ATTEMPTS >= MAX_REVIEW_ATTEMPTS:** Escalate to user:
+
+```markdown
+## Review Escalation: Code Review Failed After 3 Attempts
+
+**Stage:** Code Review
+**Attempts:** 3/3
+**Last failure reason:** {blocking issues from verifier}
+
+The code review has been blocked 3 times. Remaining issues may require architectural changes or user guidance.
+
+**Options:**
+1. Fix manually and type "retry" to re-run code review (resets attempt counter)
+2. Type "override" to skip code review (will be flagged in SUMMARY.md)
+3. Type "abort" to stop execution
+```
+
+Wait for user response:
+- **"retry":** Reset `CODE_ATTEMPTS=0`, loop back to step 1.
+- **"override":** Set `CODE_RESULT="OVERRIDDEN"`, increment `REVIEW_ESCALATIONS`, record `CODE_STAGE_END=$(date +%s)`, proceed to Stage 3.
+- **"abort":** Stop execution, create partial SUMMARY.md with review status.
+
+---
+
+### Stage 3: Simplify — Config-gated, spawn 3 parallel reviewers.
+
+**Config gate check:**
+```bash
+SIMPLIFY_ENABLED=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs config-get review.simplify_review 2>/dev/null || echo "true")
+```
+
+**If `SIMPLIFY_ENABLED` is "false":** Skip Stage 3 and Stage 4 entirely. Log: "Simplify stage skipped (disabled in config)". Set `SIMPLIFY_RESULT="SKIPPED"`, `FINAL_RESULT="N/A"`. Proceed to review cycle tracking.
+
+**If `SIMPLIFY_ENABLED` is "true" (default):**
+
+```
+SIMPLIFY_STAGE_START=$(date +%s)
+SIMPLIFY_RESULT="PENDING"
+SIMPLIFY_ATTEMPTS=0
+```
+
+**Reviewer 1 -- Code Reuse:**
 
 ```
 Task(
-  subagent_type="maxsim-code-reviewer",
+  subagent_type="verifier",
   prompt="
+    ## Task: Review for code reuse opportunities
+
+    ## Suggested Skills: code-review
+
     <objective>
     Review plan {phase}-{plan} for code reuse opportunities.
     </objective>
@@ -437,12 +587,16 @@ Task(
 )
 ```
 
-**Reviewer 2 — Code Quality:**
+**Reviewer 2 -- Code Quality:**
 
 ```
 Task(
-  subagent_type="maxsim-code-reviewer",
+  subagent_type="verifier",
   prompt="
+    ## Task: Review for code quality issues
+
+    ## Suggested Skills: code-review
+
     <objective>
     Review plan {phase}-{plan} for code quality issues.
     </objective>
@@ -463,12 +617,16 @@ Task(
 )
 ```
 
-**Reviewer 3 — Efficiency:**
+**Reviewer 3 -- Efficiency:**
 
 ```
 Task(
-  subagent_type="maxsim-code-reviewer",
+  subagent_type="verifier",
   prompt="
+    ## Task: Review for efficiency issues
+
+    ## Suggested Skills: code-review
+
     <objective>
     Review plan {phase}-{plan} for efficiency issues.
     </objective>
@@ -492,14 +650,15 @@ Task(
 **Consolidation (after all 3 reviewers complete):**
 
 After all three reviewers report:
-- If ALL returned CLEAN: report CLEAN immediately, skip to next stage
+- If ALL returned CLEAN: Set `SIMPLIFY_RESULT="CLEAN"`, record `SIMPLIFY_STAGE_END=$(date +%s)`, skip Stage 4. Set `FINAL_RESULT="N/A"`.
 - If ANY returned ISSUES_FOUND:
-  1. Merge findings into deduplicated list
-  2. Spawn single executor to apply fixes:
+  1. Increment `SIMPLIFY_ATTEMPTS`
+  2. Merge findings into deduplicated list
+  3. Spawn single executor to apply fixes:
 
 ```
 Task(
-  subagent_type="maxsim-executor",
+  subagent_type="executor",
   prompt="
     <objective>
     Apply simplification fixes for plan {phase}-{plan} based on reviewer findings.
@@ -523,16 +682,56 @@ Task(
 )
 ```
 
-**If simplify is BLOCKED:** Present architectural issues to user via checkpoint protocol. Do not proceed until resolved.
+4. **If FIXED:** Set `SIMPLIFY_RESULT="FIXED"`, record `SIMPLIFY_STAGE_END=$(date +%s)`, proceed to Stage 4.
 
-**Stage 4: Final Review** — If simplify made changes, one more code review pass.
+5. **If BLOCKED and SIMPLIFY_ATTEMPTS < MAX_REVIEW_ATTEMPTS:** Re-run the 3 reviewers to find alternative fixes, then loop.
+
+6. **If BLOCKED and SIMPLIFY_ATTEMPTS >= MAX_REVIEW_ATTEMPTS:** Escalate to user:
+
+```markdown
+## Review Escalation: Simplify Stage Blocked After 3 Attempts
 
-Run this stage ONLY if Stage 3 reported FIXED (i.e., simplify found and applied fixes).
+**Stage:** Simplify
+**Attempts:** 3/3
+**Last failure reason:** {architectural issues from executor}
+
+The simplify stage has been blocked 3 times. Remaining issues require architectural changes.
+
+**Options:**
+1. Fix manually and type "retry" to re-run simplify (resets attempt counter)
+2. Type "override" to skip simplify (will be flagged in SUMMARY.md)
+3. Type "abort" to stop execution
+```
+
+Wait for user response:
+- **"retry":** Reset `SIMPLIFY_ATTEMPTS=0`, re-run 3 reviewers.
+- **"override":** Set `SIMPLIFY_RESULT="OVERRIDDEN"`, increment `REVIEW_ESCALATIONS`, record `SIMPLIFY_STAGE_END=$(date +%s)`, skip Stage 4. Set `FINAL_RESULT="N/A"`.
+- **"abort":** Stop execution, create partial SUMMARY.md with review status.
+
+---
+
+### Stage 4: Final Review — If simplify made changes, one more code review pass.
+
+Run this stage ONLY if Stage 3 reported FIXED (i.e., simplify found and applied fixes). If Stage 3 was CLEAN, SKIPPED, or OVERRIDDEN: set `FINAL_RESULT="N/A"`, skip to review cycle tracking.
+
+```
+FINAL_STAGE_START=$(date +%s)
+FINAL_RESULT="PENDING"
+```
+
+**Retry loop (max MAX_REVIEW_ATTEMPTS):**
+
+1. Increment `FINAL_ATTEMPTS`
+2. Spawn verifier:
 
 ```
 Task(
-  subagent_type="maxsim-code-reviewer",
+  subagent_type="verifier",
   prompt="
+    ## Task: Final review after simplification
+
+    ## Suggested Skills: code-review
+
     <objective>
     Final review pass after simplification changes on plan {phase}-{plan}.
     Verify simplification fixes did not introduce regressions.
@@ -558,18 +757,64 @@ Task(
 )
 ```
 
-**If final review is BLOCKED:** Fix issues, re-run final review. Do not proceed until APPROVED.
+3. **If APPROVED:** Set `FINAL_RESULT="APPROVED"`, record `FINAL_STAGE_END=$(date +%s)`, proceed to review cycle tracking.
+
+4. **If BLOCKED and FINAL_ATTEMPTS < MAX_REVIEW_ATTEMPTS:** Fix issues, re-stage and commit fixes (`fix({phase}-{plan}): address final review findings`), then loop back to step 1.
+
+5. **If BLOCKED and FINAL_ATTEMPTS >= MAX_REVIEW_ATTEMPTS:** Escalate to user:
+
+```markdown
+## Review Escalation: Final Review Blocked After 3 Attempts
+
+**Stage:** Final Review
+**Attempts:** 3/3
+**Last failure reason:** {blocking issues from verifier}
+
+The final review has been blocked 3 times after simplification changes.
+
+**Options:**
+1. Fix manually and type "retry" to re-run final review (resets attempt counter)
+2. Type "override" to skip final review (will be flagged in SUMMARY.md)
+3. Type "abort" to stop execution
+```
+
+Wait for user response:
+- **"retry":** Reset `FINAL_ATTEMPTS=0`, loop back to step 1.
+- **"override":** Set `FINAL_RESULT="OVERRIDDEN"`, increment `REVIEW_ESCALATIONS`, record `FINAL_STAGE_END=$(date +%s)`, proceed to review cycle tracking.
+- **"abort":** Stop execution, create partial SUMMARY.md with review status.
+
+---
+
+### Review Cycle Tracking
+
+```
+REVIEW_CYCLE_END=$(date +%s)
+REVIEW_CYCLE_TOTAL=$(( REVIEW_CYCLE_END - REVIEW_CYCLE_START ))
+```
+
+Calculate per-stage durations:
+```
+SPEC_DURATION=$(( SPEC_STAGE_END - SPEC_STAGE_START ))
+CODE_DURATION=$(( CODE_STAGE_END - CODE_STAGE_START ))
+# Only if simplify ran:
+SIMPLIFY_DURATION=$(( SIMPLIFY_STAGE_END - SIMPLIFY_STAGE_START ))  # or "N/A" if skipped
+# Only if final review ran:
+FINAL_DURATION=$(( FINAL_STAGE_END - FINAL_STAGE_START ))  # or "N/A" if skipped
+```
 
-**Review cycle tracking:** Record review results in SUMMARY.md under a `## Review Cycle` section:
+Record review results in SUMMARY.md under a `## Review Cycle` section:
 ```markdown
 ## Review Cycle
 
-| Stage | Result | Findings |
-|-------|--------|----------|
-| Spec Review | PASS | All requirements met |
-| Code Review | APPROVED | No blocking issues |
-| Simplify | FIXED | Extracted shared helper for X, removed unused import Y |
-| Final Review | APPROVED | Simplification changes verified |
+| Stage | Result | Attempts | Duration | Findings |
+|-------|--------|----------|----------|----------|
+| Spec Review | {PASS|FAIL|OVERRIDDEN} | {SPEC_ATTEMPTS}/3 | {SPEC_DURATION}s | {summary or "All requirements met"} |
+| Code Review | {APPROVED|BLOCKED|OVERRIDDEN} | {CODE_ATTEMPTS}/3 | {CODE_DURATION}s | {summary or "No blocking issues"} |
+| Simplify | {CLEAN|FIXED|BLOCKED|SKIPPED|OVERRIDDEN} | {SIMPLIFY_ATTEMPTS}/3 | {SIMPLIFY_DURATION}s | {summary or "N/A"} |
+| Final Review | {APPROVED|BLOCKED|SKIPPED|N/A|OVERRIDDEN} | {FINAL_ATTEMPTS}/3 | {FINAL_DURATION}s | {summary or "N/A"} |
+
+**Total review time:** {REVIEW_CYCLE_TOTAL}s
+**Escalations:** {REVIEW_ESCALATIONS} ({REVIEW_ESCALATION_DETAILS or "None"})
 ```
 
 Update the SUMMARY.md commit after the review cycle completes:
@@ -578,6 +823,26 @@ node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs({phase}-{plan}): add rev
 ```
 </step>
 
+<step name="evidence_gate">
+**Gate G6: Evidence Completeness** — SUMMARY.md must have evidence for each requirement.
+
+After the review cycle and before committing metadata, validate that the SUMMARY.md contains requirement evidence for all requirements in the plan's frontmatter.
+
+```bash
+if [ -n "$REQ_IDS" ]; then
+  SUMMARY_PATH=".planning/phases/XX-name/{phase}-{plan}-SUMMARY.md"
+  G6_RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs verify evidence-completeness "$SUMMARY_PATH" $REQ_IDS)
+  G6_VALID=$(echo "$G6_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).valid))")
+  if [ "$G6_VALID" != "true" ]; then
+    G6_MISSING=$(echo "$G6_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).missing_evidence.join(', ')))")
+    echo "GATE G6: Missing requirement evidence for: $G6_MISSING"
+    echo "Add Requirement Evidence rows to SUMMARY.md for these requirements before proceeding."
+    # Present as warning with instruction to fix — executor should add evidence
+  fi
+fi
+```
+</step>
+
 <step name="update_current_position">
 Update STATE.md using maxsim-tools:
 
@@ -675,9 +940,9 @@ ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
 
 | Condition | Route | Action |
 |-----------|-------|--------|
-| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/maxsim:execute-phase {phase}` + `/maxsim:verify-work`. STOP here. |
-| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/maxsim:plan-phase {Z+1}` + `/maxsim:verify-work {Z}` + `/maxsim:discuss-phase {Z+1}` |
-| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/maxsim:complete-milestone` + `/maxsim:verify-work` + `/maxsim:add-phase` |
+| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/maxsim:execute {phase}`. STOP here. |
+| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/maxsim:plan {Z+1}`. |
+| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/maxsim:progress`. |
 
 All routes: `/clear` first for fresh context.
 </step>