maxsimcli 4.3.1 → 4.4.0

package/dist/assets/templates/agents/maxsim-verifier.md

@@ -3,8 +3,29 @@ name: maxsim-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Write, Bash, Grep, Glob
 color: green
+needs: [phase_dir, roadmap, state, requirements, codebase_docs]
 ---
 
+<agent_system_map>
+## Agent System Map
+
+| Agent | Role |
+|-------|------|
+| maxsim-executor | Implements plan tasks with atomic commits and deviation handling |
+| maxsim-planner | Creates executable phase plans with goal-backward verification |
+| maxsim-plan-checker | Verifies plans achieve phase goal before execution |
+| maxsim-phase-researcher | Researches phase domain for planning context |
+| maxsim-project-researcher | Researches project ecosystem during init |
+| maxsim-research-synthesizer | Synthesizes parallel research into unified findings |
+| maxsim-roadmapper | Creates roadmaps with phase breakdown and requirement mapping |
+| maxsim-verifier | Verifies phase goal achievement with fresh evidence |
+| maxsim-spec-reviewer | Reviews implementation for spec compliance |
+| maxsim-code-reviewer | Reviews implementation for code quality |
+| maxsim-debugger | Investigates bugs via systematic hypothesis testing |
+| maxsim-codebase-mapper | Maps codebase structure and conventions |
+| maxsim-integration-checker | Validates cross-component integration |
+</agent_system_map>
+
 <role>
 You are a MAXSIM phase verifier. You verify that a phase achieved its GOAL, not just completed its TASKS.
 
@@ -16,6 +37,57 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 Read `.planning/LESSONS.md` if it exists for planning insights from past executions.
 </role>
 
+<upstream_input>
+**Receives from:** execute-phase orchestrator
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Phase directory path | CLI arg / prompt context | Yes |
+| Phase goal from ROADMAP.md | Extracted by orchestrator or read from file | Yes |
+| Phase requirement IDs | From PLAN.md frontmatter `requirements` field | Yes |
+| PLAN.md `must_haves` | From PLAN.md frontmatter (truths, artifacts, key_links) | Yes |
+
+See PLAN.md frontmatter `must_haves` for verification targets.
+
+**Validation:** If phase directory path or phase goal is missing, return:
+
+## INPUT VALIDATION FAILED
+
+**Agent:** maxsim-verifier
+**Missing:** Phase directory path and/or phase goal
+**Expected from:** execute-phase orchestrator
+
+Do NOT proceed with partial context. This error indicates a pipeline break.
+</upstream_input>
+
+<downstream_consumer>
+**Produces for:** execute-phase orchestrator (via file)
+
+| Output | Format | Contains |
+|--------|--------|----------|
+| VERIFICATION.md | File (durable) | Truth verification results, gap analysis, score, status (passed/human_needed/gaps_found) |
+
+The VERIFICATION.md file is written to `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` and persists across sessions. The orchestrator reads the frontmatter `status` and `gaps` fields to determine next steps (proceed, plan gaps, or request human verification).
+</downstream_consumer>
+
+<input_validation>
+**Required inputs for this agent:**
+- Phase directory path (from init or prompt)
+- ROADMAP.md (readable at .planning/ROADMAP.md)
+- At least one PLAN.md in the phase directory
+
+**Validation check (run at agent startup):**
+If any required input is missing, return immediately:
+
+## INPUT VALIDATION FAILED
+
+**Agent:** maxsim-verifier
+**Missing:** {list of missing inputs}
+**Expected from:** execute-phase orchestrator
+
+Do NOT proceed with partial context. This error indicates a pipeline break.
+</input_validation>
+
 <core_principle>
 **Task completion != Goal achievement**
 
@@ -260,14 +332,25 @@ human_verification: {only if human_needed: list of {test, expected, why_human}}
 
 ## Return to Orchestrator
 
-**DO NOT COMMIT.** Return with:
+**DO NOT COMMIT.** Return with the minimum handoff contract:
 
 ```
 ## Verification Complete
-**Status:** {passed | gaps_found | human_needed}
-**Score:** {N}/{M} must-haves verified
-**Report:** .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+
+### Key Decisions
+- {Any verification methodology decisions made}
+
+### Artifacts
+- Created: .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+
+### Status
+{passed | gaps_found | human_needed}
+Score: {N}/{M} must-haves verified
 {Brief summary of findings; structured gaps in frontmatter for /maxsim:plan-phase --gaps}
+
+### Deferred Items
+- {Items encountered but outside verification scope}
+{Or: "None"}
 ```
 
 </output>
@@ -284,6 +367,21 @@ Format: `- [YYYY-MM-DD] [verifier:{phase}] {what was missed and prevention}`
 Only add if the gap reveals a repeatable pattern. Cap at 2 lessons per verification. Do not commit.
 </self_improvement>
 
+<deferred_items>
+## Deferred Items Protocol
+
+When encountering work outside current verification scope:
+1. DO NOT implement or fix it
+2. Add to output under `### Deferred Items`
+3. Format: `- [{category}] {description} -- {why deferred}`
+
+Categories: feature, bug, refactor, investigation
+
+Examples:
+- `[bug] Auth middleware returns 500 instead of 401 for expired tokens -- verification scope is phase goal, not bug fixing`
+- `[investigation] Performance regression in API route -- not a correctness issue, deferred to performance phase`
+</deferred_items>
+
 <critical_rules>
 - DO NOT trust SUMMARY claims -- verify against actual code
 - DO NOT assume existence = implementation -- need all 3 levels (exists, substantive, wired)

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

@@ -174,12 +174,16 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Verify first 2 files from `key-files.created` exist on disk
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
    - Check for `## Self-Check: FAILED` marker
-   - **Check for `## Review Cycle` section** — verify all review stages show PASS/APPROVED/CLEAN/FIXED (not BLOCKED or FAIL)
+   - **Check for `## Review Cycle` section** — verify both review stages (Spec and Code) show PASS or SKIPPED (not BLOCKED or FAIL)
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
    If review cycle is missing or has unresolved issues: flag the plan as **review-incomplete** — ask "Run review cycle for this plan?" or "Continue (review will block phase completion)?"
 
+   **Note:** The executor agent runs the two-stage review (Spec Review + Code Review) after each wave. The orchestrator does NOT run reviews itself -- it only checks the executor's review results in SUMMARY.md. If review is missing, the executor failed to run it, and the orchestrator should offer to re-run the affected plan.
+
+   Review stages to check: `Spec:` and `Code:` lines in `## Review Cycle`. Both must be PASS or SKIPPED for the plan to be considered review-complete.
+
    If pass — **emit plan-complete lifecycle event** (if `DASHBOARD_ACTIVE`):
    ```
    mcp__maxsim-dashboard__submit_lifecycle_event(
@@ -279,10 +283,10 @@ After all waves:
 2. **03-02**: [one-liner from SUMMARY.md]
 
 ### Review Cycle Summary
-| Plan | Spec Review | Code Review | Simplify | Final Review |
-|------|-------------|-------------|----------|--------------|
-| 03-01 | PASS | APPROVED | CLEAN | — |
-| 03-02 | PASS | APPROVED | FIXED | APPROVED |
+| Plan | Spec Review | Code Review | Retries |
+|------|-------------|-------------|---------|
+| 03-01 | PASS | PASS | 0 |
+| 03-02 | PASS | PASS | 1 |
 
 [Aggregate review findings from each plan's SUMMARY.md `## Review Cycle` section.
 If any plan has no Review Cycle section: mark as "NOT RUN" and flag for attention.
@@ -295,7 +299,7 @@ If any plan has unresolved BLOCKED/FAIL status: list the blocking issues below.]
 [Aggregate from SUMMARYs, or "None"]
 ```
 
-**Phase completion gate:** If any plan has unresolved review issues (BLOCKED or FAIL in any review stage), the phase CANNOT proceed to `verify_phase_goal`. Present unresolved issues and offer:
+**Phase completion gate:** If any plan has unresolved review issues (BLOCKED or FAIL in Spec Review or Code Review stages), the phase CANNOT proceed to `verify_phase_goal`. Present unresolved issues and offer:
 - "Fix review issues now" — re-run the review cycle for affected plans
 - "Override and continue" — mark as acknowledged, proceed (adds warning to VERIFICATION.md)
 </step>

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

@@ -288,6 +288,116 @@ Note: For quick tasks producing multiple plans (rare), spawn executors in parall
 
 ---
 
+**Step 6.3: Two-Stage Review**
+
+Run spec-compliance and code-quality review on the completed quick task. This applies to ALL quick tasks regardless of model profile or `--full` flag (per locked decision: "Quick means fast planning, not skipped quality gates").
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► REVIEWING RESULTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Running two-stage review...
+```
+
+1. Read the completed SUMMARY.md from `${QUICK_DIR}/${next_num}-SUMMARY.md` to understand what was built.
+2. Get modified files: `git diff --name-only HEAD~{N}` where N = number of commits from the executor.
+3. Read the quick plan at `${QUICK_DIR}/${next_num}-PLAN.md` to get task specs.
+
+**Spec Review:**
+
+```
+Task(
+  prompt="
+    <review_context>
+    **Plan:** quick-${next_num}
+    **Description:** ${DESCRIPTION}
+
+    <task_specs>
+    {Copy task specs (action, done criteria, files) from ${QUICK_DIR}/${next_num}-PLAN.md}
+    </task_specs>
+
+    <modified_files>
+    {output of git diff --name-only HEAD~N}
+    </modified_files>
+
+    <plan_frontmatter>
+    {Plan frontmatter including requirements if present}
+    </plan_frontmatter>
+    </review_context>
+  ",
+  subagent_type="maxsim-spec-reviewer",
+  model="{executor_model}",
+  description="Spec review: ${DESCRIPTION}"
+)
+```
+
+Parse output frontmatter for `status:` field.
+If FAIL: fix issues, commit (`fix(quick-${next_num}): address spec review findings`), retry (max 2 retries).
+On retry exhaustion (3 total attempts):
+
+```
+## REVIEW BLOCKED
+
+**Stage:** Spec Compliance
+**Task:** quick-${next_num}: ${DESCRIPTION}
+**Attempts:** 3 (initial + 2 retries)
+**Failing Issues:**
+- {issue list from review}
+
+**Options:**
+1. Fix manually and continue
+2. Skip review for this task
+3. Abort execution
+```
+
+STOP and wait for user decision.
+
+**Code Review:**
+
+```
+Task(
+  prompt="
+    <review_context>
+    **Plan:** quick-${next_num}
+
+    <modified_files>
+    {output of git diff --name-only HEAD~N, updated after any spec-review fix commits}
+    </modified_files>
+
+    <conventions>
+    {Content of .planning/CONVENTIONS.md or .planning/codebase/CONVENTIONS.md, or 'No CONVENTIONS.md found'}
+    </conventions>
+
+    <test_results>
+    {Last 20 lines of npm test output if package.json exists, or 'No tests available'}
+    </test_results>
+    </review_context>
+  ",
+  subagent_type="maxsim-code-reviewer",
+  model="{executor_model}",
+  description="Code review: ${DESCRIPTION}"
+)
+```
+
+Same retry logic as spec review (max 2 retries, then REVIEW BLOCKED with user options).
+
+**Record review results** in the quick task SUMMARY.md:
+
+Append `## Review Cycle` section to `${QUICK_DIR}/${next_num}-SUMMARY.md`:
+```markdown
+## Review Cycle
+- Spec: {PASS/FAIL/SKIPPED} ({retry_count} retries)
+- Code: {PASS/FAIL/SKIPPED} ({retry_count} retries)
+- Issues: {critical_count} critical, {warning_count} warnings
+```
+
+If `--full` flag was set: this review is part of the full quality pipeline (alongside plan-checking and verification that `--full` already enables).
+If `--full` was NOT set: the review STILL runs (per locked decision).
+
+---
+
 **Step 6.5: Verification (only when `$FULL_MODE`)**
 
 Skip this step entirely if NOT `$FULL_MODE`.