pan-wizard 3.34.0 → 3.35.0

package/pan-wizard-core/templates/preview-report.md

@@ -59,7 +59,7 @@ source: pan-previewer
 ## Hidden coupling
 
 <!-- phases mode only; may be "none found" -->
-- Phase {{from}} → Phase {{to}} — inferred from prose mention; consider promoting to `depends_on:` frontmatter.
+- Phase {{from}} → Phase {{to}} — inferred from prose mention; consider adding it to Phase {{to}}'s `**Depends on:**` line in the roadmap.
 
 ## Current state
 

package/pan-wizard-core/templates/state.md

@@ -35,10 +35,10 @@ See: .planning/project.md (updated [date])
 - Average duration: [X] min
 - Total execution time: [X.X] hours
 
-**By Phase:**
+**By Plan:** (one row per plan, written by `state record-metric`)
 
-| Phase | Plans | Total | Avg/Plan |
-|-------|-------|-------|----------|
+| Plan | Duration | Tasks | Files |
+|------|----------|-------|-------|
 | - | - | - | - |
 
 **Recent Trend:**
@@ -139,7 +139,7 @@ Progress calculation: (completed plans) / (total plans across all phases) × 100
 Track velocity to understand execution patterns:
 - Total plans completed
 - Average duration per plan
-- Per-phase breakdown
+- Per-plan rows (phase, plan, duration, tasks, files)
 - Recent trend (improving/stable/degrading)
 
 Updated after each plan completion.

package/pan-wizard-core/workflows/diagnose-issues.md

@@ -81,6 +81,7 @@ For each gap, fill the debug-subagent-prompt template and spawn:
 Task(
   prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-uat.md\n- .planning/state.md\n</files_to_read>",
   subagent_type="pan-debugger",
+  model="{debugger_model}",   # node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-debugger --raw
   description="Debug: {issue_summary_short}"
 )
 ```
@@ -181,11 +182,10 @@ Display:
 
 Debug sessions: ${DEBUG_DIR}/
 
-Proceeding to plan fixes...
+Next: /pan:plan-phase {phase_num} --gaps
 ```
 
-Return to verify-phase orchestrator for automatic planning.
-Do NOT offer manual next steps - verify-phase handles the rest.
+No command runs this workflow as a sub-step, so end by giving the user the next step: `/pan:plan-phase {phase_num} --gaps` (it reads the diagnosed uat.md).
 </step>
 
 </process>
@@ -217,5 +217,5 @@ Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
 - [ ] Root causes collected from all agents
 - [ ] uat.md gaps updated with artifacts and missing
 - [ ] Debug sessions saved to ${DEBUG_DIR}/
-- [ ] Hand off to verify-phase for automatic planning
+- [ ] Next step shown: /pan:plan-phase {phase_num} --gaps
 </success_criteria>

package/pan-wizard-core/workflows/discuss-phase.md

@@ -130,7 +130,7 @@ Exit workflow.
 </step>
 
 <step name="auto_mode_bypass">
-**P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The unguarded `AskUserQuestion` calls in `check_existing`, `present_gray_areas` and `discuss_areas` all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with $0.42 cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly.
+**P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The unguarded `AskUserQuestion` calls in `check_existing`, `present_gray_areas` and `discuss_areas` all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with 42 cents of cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly.
 
 Detect auto mode:
 
@@ -599,6 +599,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Plan Phase ${PHASE}"
 )
 ```

package/pan-wizard-core/workflows/exec-phase.md

@@ -34,12 +34,24 @@ Load all context in one call:
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "${PHASE_ARG}")
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `verifier_enabled`.
+Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `verifier_enabled`, `plan_check`, `plan_drift`. In the shell steps below, `$PHASE_DIR` (and `$phase_dir`) is `phase_dir` and `$PHASE_NUMBER` is `phase_number`.
 
 **If `phase_found` is false:** Error — phase directory not found.
 **If `plan_count` is 0:** Error — no plans found in phase.
 **If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
 
+**The plans must be the plans that passed the plan check** (`plan_check.status`):
+
+| Status | Action |
+|---|---|
+| `ok`, `disabled` | Continue |
+| `legacy` | Continue, and say: "the plan check predates plan hashing, so it cannot show these plans are unchanged" |
+| `stale` | Stop: "The plans changed after they passed the plan check. Re-plan with `/pan:plan-phase {N} --skip-research`, which checks the new plans." Continue only if the user gives a reason, and record it: `pan-tools optimize trace log --type decision --category plan_check_overridden --description "<reason>"` |
+| `failed` | Stop: "The last plan check found issues." Same override |
+| `missing` | Stop: "No plan check is recorded for this phase." This includes plans made with `/pan:plan-phase --skip-verify` or with `workflow.plan_check` off after the fact. Same override |
+
+**Drift.** For each `plan_drift` entry, tell the executor of that plan, in its prompt, which of its `files_modified` changed since it was planned (`files`), so it re-reads them before editing. An entry with `error` means its `planned_commit` is unknown: say so and continue.
+
 When `parallelization` is false, plans within a wave execute sequentially.
 
 **Circular optimization — start trace session for this exec:**
@@ -190,6 +202,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
+   **An executor that returned `## BLOCKED_SPEC_CONFLICT`** found a test it cannot satisfy without weakening it. It is not a failure to retry: show the user its Test, Requirement and Options and ask for a ruling. "Change the test" means a revised plan that declares the test file in `files_modified` (`/pan:plan-phase {N} --gaps` or an edit to the plan), then re-run that plan; "change the requirement" means updating the requirement and the plan. Never re-run the same plan unchanged: it would meet the same test. Declaring the file permits rewriting its expectations; deleting the test, skipping it or dropping assertions still fails `verify test-integrity`, so a ruling to do that also needs `phase complete --force --reason`.
+
    If pass:
    ```
    ---
@@ -319,7 +333,7 @@ After all waves:
 
 1. Record baseline test count:
 ```bash
-TEST_BASELINE=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
+TEST_BASELINE=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 ```
 
 2. Invoke phase-tests workflow for the completed phase:
@@ -331,7 +345,8 @@ Read each summary.md to understand what was built.
 Generate unit and integration tests for the new code.
 Discover the project's existing test patterns, directories, frameworks, and helpers before writing tests.
 Follow whatever conventions the project already uses.",
-  subagent_type="general-purpose"
+  subagent_type="general-purpose",
+  model="{executor_model}",
 )
 ```
 
@@ -342,7 +357,7 @@ Alternatively, if the user's AI tool supports it, invoke the command directly:
 
 3. Record new test count:
 ```bash
-TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
+TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 ```
 
 4. Report:
@@ -353,6 +368,8 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
 - New tests: +$((TEST_AFTER - TEST_BASELINE))
 ```
 
+`ℹ tests N` (spec reporter) and `# tests N` (TAP, Node's default for piped output before Node 23) are the summary lines of Node's built-in test runner, and both greps above match either. With any other runner both counts come back empty, so report the runner's own summary line instead of `+0`.
+
 **If tests fail after generation:** Report failures but continue to next step. Test issues are caught by the verify-phase test gate.
 </step>
 
@@ -365,11 +382,14 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
 ```bash
 # Read each summary.md and extract key-files.created + key-files.modified
 for summary in "$PHASE_DIR"/*-summary.md; do
-  grep -A 50 "key-files" "$summary" | grep -E "^\s*-" | sed 's/^\s*- //'
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields key_files | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const k=JSON.parse(s).key_files||{};for(const f of [...(k.created||[]),...(k.modified||[])])console.log(f)})"
 done | sort -u > /tmp/review-files.txt
 ```
 
-2. Spawn pan-reviewer:
+2. Collect the reviewer's earlier open findings on this phase (empty on a first review), then spawn pan-reviewer:
+```bash
+OPEN_REVIEW_FINDINGS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings list --phase "${PHASE_NUMBER}" --agent pan-reviewer --status open 2>/dev/null)
+```
 ```
 Task(
   subagent_type="pan-reviewer",
@@ -391,6 +411,10 @@ Task(
     Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
     Phase directory: ${phase_dir}
     </context>
+
+    <open_findings>
+    ${OPEN_REVIEW_FINDINGS}
+    </open_findings>
   "
 )
 ```
@@ -426,7 +450,7 @@ The fallback reads the word under `### Verdict` when the report carries no valid
   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-reviewer --open --as deferred --reason "accepted at review: PASS_WITH_WARNINGS"
   ```
 - **The user chooses "Continue anyway"** at `NEEDS_FIXES`: the same command with `--reason "continued past NEEDS_FIXES at the user's choice"`, then proceed to verification.
-- **The user chooses "Fix before verification"**: apply the fixes, then run the review once more (steps 2–4). The new record closes the findings it no longer reports.
+- **The user chooses "Fix before verification"**: apply the fixes, then run the review once more (steps 2–4). The re-review answers each earlier finding in its `resolutions`; the record closes the ones it answers `resolved` with evidence, and one it neither reports nor answers stays open.
 
 5. **No separate trace logging.** The record logs `verdict_passed` or `verdict_failed` for the reviewer on every runtime. The `reviewer_correction` and `reviewer_warnings` trace calls that used to sit here read the error count from a shell variable nothing ever set.
 
@@ -553,7 +577,7 @@ VERIF_FILE=$(ls "$PHASE_DIR"/*-verification.md 2>/dev/null | head -1)
 VERIF_STATUS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --file "$VERIF_FILE" --raw 2>/dev/null) \
   || VERIF_STATUS=$(grep "^status:" "$VERIF_FILE" | cut -d: -f2 | tr -d ' ')
 ```
-`findings record` reads the verdict from the verification frontmatter (`status`, `gaps`, `human_verification`, `unrequested`) and adds its findings to the ledger. A re-verification after a fix round is the next attempt: the gaps it no longer reports are closed, and the retry is logged. Recording the same file twice is a no-op, so verify-phase recording it too is safe. The grep fallback keeps the old reading when the record cannot parse the file.
+`findings record` reads the verdict from the verification frontmatter (`status`, `gaps`, `human_verification`, `unrequested`) and adds its findings to the ledger. A re-verification after a fix round is the next attempt: the gaps it lists under `re_verification.gaps_closed` are closed, a gap it neither reports nor answers stays open (listed in `unaddressed`), and the retry is logged. Recording the same file twice is a no-op, so verify-phase recording it too is safe. The grep fallback keeps the old reading when the record cannot parse the file.
 
 **Trace logging happens in the record.** The record above logs the verification outcome (`verdict_passed`, `verdict_failed` or `verdict_needs_human`) here, after the verifier returns. That covers inline verification too, which is the reason P-1806 moved the trace call here (v3.7.8). No separate `optimize trace log` call is needed.
 
@@ -599,12 +623,26 @@ Gap closure cycle: `/pan:plan-phase {X} --gaps` reads verification.md → create
 </step>
 
 <step name="update_roadmap">
-**Mark phase complete and update all tracking files:**
+**Mark phase complete and update all tracking files.** `phase complete` runs the phase gate first, on every path (this step runs before `offer_next`, with or without `--no-transition`). The gate checks in code what this workflow used to ask for in prose: every plan has a summary, the verification passes (a failed test gate lowers it to gaps), human items have a recorded approval, the verification is fresh, reconcile finds no contradiction, no critical or high finding is left open, no stub was committed, and no test was weakened.
 
 ```bash
 COMPLETION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${PHASE_NUMBER}")
+COMPLETION_EXIT=$?
+```
+
+| Result | Action |
+|---|---|
+| exit 1, `error: phase_gate_refused` (`workflow.phase_gate: enforce`) | The phase was NOT marked complete. Show each `gate.reasons` entry (`code`: `detail`) with its fix, and stop: no commit, no auto-advance. The user may complete anyway with a reason (below) |
+| exit 0, `gate.ok` false (`warn`, the default) | The phase was marked complete. Show the reasons as warnings, run the rest of this step, and do NOT auto-advance (`offer_next` reads `GATE_OK`) |
+| exit 0, `gate.ok` true | Continue |
+
+**Completing past a refusal** is the user's decision, never yours, and needs their reason. It records a `decision` for every open finding the gate counted:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${PHASE_NUMBER}" --force --reason "<the user's reason>"
 ```
 
+Set `GATE_OK` to `gate.ok` from `COMPLETION` (`false` when the gate refused).
+
 The CLI handles:
 - Marking phase checkbox `[x]` with completion date
 - Updating Progress table (Status → Complete, date)
@@ -659,7 +697,7 @@ Parse `--no-transition` flag from $ARGUMENTS.
 **If `--no-transition` flag present:**
 
 Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
-If verification found gaps, return `## GAPS FOUND` with the phase, score and gap summaries (plan-phase and discuss-phase stop the chain on it). After verification passes and roadmap is updated, return completion status to parent:
+If verification found gaps, or `GATE_OK` is false, return `## GAPS FOUND` with the phase, score and the gap summaries or the gate's reasons (plan-phase and discuss-phase stop the chain on it). After the gate passes, return completion status to parent:
 
 ```
 ## PHASE COMPLETE
@@ -675,37 +713,10 @@ STOP. Do not proceed to auto-advance or transition.
 
 **If `--no-transition` flag is NOT present:**
 
-**Verification gate check (before auto-advance):**
-
-If `workflow.verifier` is true in config, confirm the current phase has a passing verification:
-
-```bash
-VERIF=$(ls "$phase_dir"/*-verification.md 2>/dev/null | head -1)
-VERIF_STATUS=""
-if [ -n "$VERIF" ]; then
-  VERIF_STATUS=$(grep "^status:" "$VERIF" | awk '{print $2}')
-fi
-```
-
-**Cross-check the written verdict against the mechanical signals (anti-rubber-stamp, ADR-0036).** The `status:` string above is authored by the verifier agent; `reconcile` re-derives the artifact/key-link checks from disk and exits non-zero when a claimed pass contradicts them:
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify reconcile "${PHASE_NUMBER}" --raw
-RECONCILE_EXIT=$?
-```
-If `RECONCILE_EXIT` is non-zero:
-```
-⚠ Reconcile gate: Phase ${PHASE_NUMBER} verification says "passed" but the mechanical
-  checks disagree — artifacts fail substance checks or key-links are unwired.
-  This is a rubber-stamped verification. Do NOT auto-advance.
-  Re-run /pan:verify-phase and fix the failing artifacts/key-links.
-```
-STOP — do not auto-advance. Return to user.
-
-If `VERIF_STATUS` is not `passed`:
+**Gate check (before auto-advance).** The phase gate already ran inside `phase complete` (`update_roadmap`), and it covers the verification status, reconcile (anti-rubber-stamp, ADR-0036), freshness, open findings, stubs and test integrity. If `GATE_OK` is false:
 ```
-⚠ Verification gate: Phase ${PHASE_NUMBER} verification status is "${VERIF_STATUS:-missing}"
-  Cannot auto-advance without passing verification.
-  Run /pan:verify-phase to verify this phase first.
+⚠ Phase gate: Phase ${PHASE_NUMBER} may not advance — {each gate reason: code and detail}.
+  Fix the reasons (or close the gaps with /pan:plan-phase ${PHASE_NUMBER} --gaps), then re-run.
 ```
 STOP — do not auto-advance. Return to user.
 

package/pan-wizard-core/workflows/milestone-gaps.md

@@ -64,8 +64,8 @@ Gap: Flow "View dashboard" broken at data fetch
 
 Find highest existing phase:
 ```bash
-# Get sorted phase list, extract last one
-HIGHEST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list --raw | tail -1)
+# Highest phase number in roadmap.md — the same source `phase add` numbers from
+HIGHEST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap analyze | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const n=JSON.parse(s).phases.map(p=>parseInt(p.number,10)).filter(Number.isFinite);console.log(n.length?Math.max(...n):0)})")
 ```
 
 New phases continue from there:

package/pan-wizard-core/workflows/new-project.md

@@ -525,9 +525,7 @@ Display spawning indicator:
 Spawn 4 parallel pan-project-researcher agents with path references:
 
 ```
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
-
-<research_type>
+Task(prompt="<research_type>
 Project Research — Stack dimension for [domain].
 </research_type>
 
@@ -563,11 +561,9 @@ Your stack.md feeds into roadmap creation. Be prescriptive:
 Write to: .planning/research/stack.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/stack.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
-
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Stack research")
 
-<research_type>
+Task(prompt="<research_type>
 Project Research — Features dimension for [domain].
 </research_type>
 
@@ -603,11 +599,9 @@ Your features.md feeds into requirements definition. Categorize clearly:
 Write to: .planning/research/features.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/features.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Features research")
 
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
-
-<research_type>
+Task(prompt="<research_type>
 Project Research — Architecture dimension for [domain].
 </research_type>
 
@@ -643,11 +637,9 @@ Your architecture.md informs phase structure in roadmap. Include:
 Write to: .planning/research/architecture.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/architecture.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
-
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Architecture research")
 
-<research_type>
+Task(prompt="<research_type>
 Project Research — Pitfalls dimension for [domain].
 </research_type>
 
@@ -683,7 +675,7 @@ Your pitfalls.md prevents mistakes in roadmap/planning. For each pitfall:
 Write to: .planning/research/pitfalls.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/pitfalls.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Pitfalls research")
 ```
 
 After all 4 agents complete, spawn synthesizer to create summary.md:

package/pan-wizard-core/workflows/plan-phase.md

@@ -280,8 +280,8 @@ Write to: {phase_dir}/{padded_phase}-research.md
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-phase-researcher.md for your role and instructions.\n\n" + research_prompt,
-  subagent_type="general-purpose",
+  prompt=research_prompt,
+  subagent_type="pan-phase-researcher",
   model="{researcher_model}",
   description="Research Phase {phase}"
 )
@@ -383,8 +383,8 @@ Output consumed by /pan:exec-phase. Plans need:
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-planner.md for your role and instructions.\n\n" + filled_prompt,
-  subagent_type="general-purpose",
+  prompt=filled_prompt,
+  subagent_type="pan-planner",
   model="{planner_model}",
   description="Plan Phase {phase}"
 )
@@ -392,12 +392,21 @@ Task(
 
 ## 9. Handle Planner Return
 
-- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
+- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): still run the code checks at the start of step 10 (`verify plan-set`; they cost no model call), send any errors back to the planner (step 12), then skip to step 13. Otherwise: step 10.
 - **`## GAP CLOSURE PLANS CREATED`:** (`--gaps` mode) Handle as `## PLANNING COMPLETE`.
 - **`## CHECKPOINT REACHED`:** Present to user, get response, spawn a fresh planner (step 8's Task) with the response added to its prompt
 
 ## 10. Spawn pan-plan-checker Agent
 
+**First, the checks code can make.** Run them before spending a checker:
+
+```bash
+PLAN_SET=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-set "${PHASE_NUMBER}")
+PLAN_SET_EXIT=$?
+```
+
+Exit 1 means the plan set is broken in a way no review can wave through: a roadmap requirement no plan lists, two plans in one wave modifying the same file, a `depends_on` that names no plan or a plan in the same or a later wave, or a cycle. Send `PLAN_SET`'s `errors` to the planner as the revision context (step 12; it counts as an iteration) and do not spawn the checker for this set. Exit 0: continue, and pass any `warnings` to the checker.
+
 Display banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -427,6 +436,10 @@ Checker prompt:
 **Project skills:** Check .agents/skills/ directory (if exists) — verify plans account for project skill rules
 </verification_context>
 
+<open_findings>
+{output of `pan-tools findings list --phase {phase_number} --agent pan-plan-checker --status open`: empty on the first check; on a re-check, answer each in `resolutions`}
+</open_findings>
+
 <expected_output>
 - ## VERIFICATION PASSED — all checks pass
 - ## ISSUES FOUND — structured issue list
@@ -457,7 +470,7 @@ The fallback reads the heading when the report carries no valid `pan-verdict` bl
 - **`passed`:** Display confirmation, proceed to step 13.
 - **`issues_found`:** Display issues, check iteration count, proceed to step 12.
 
-Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The issues a revision resolved are closed by that record.
+Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The checker answers each earlier issue in `resolutions`; the record closes the ones it answers `resolved` with evidence, and one it neither reports nor answers stays open.
 
 ## 12. Revision Loop (At Most 2 Revisions, 3 Checks)
 
@@ -491,8 +504,8 @@ Return what changed.
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-planner.md for your role and instructions.\n\n" + revision_prompt,
-  subagent_type="general-purpose",
+  prompt=revision_prompt,
+  subagent_type="pan-planner",
   model="{planner_model}",
   description="Revise Phase {phase} plans"
 )
@@ -590,6 +603,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Execute Phase ${PHASE}"
 )
 ```

package/pan-wizard-core/workflows/progress.md

@@ -54,7 +54,7 @@ ROADMAP=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap analyze)
 ```
 
 This returns structured JSON with:
-- All phases with disk status (complete/partial/planned/empty/no_directory)
+- All phases with disk status (complete/partial/planned/researched/discussed/empty/no_directory)
 - Goal and dependencies per phase
 - Plan and summary counts per phase
 - Aggregated stats: total plans, summaries, progress percent

package/pan-wizard-core/workflows/quick.md

@@ -229,8 +229,8 @@ Return what changed.
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-planner.md for your role and instructions.\n\n" + revision_prompt,
-  subagent_type="general-purpose",
+  prompt=revision_prompt,
+  subagent_type="pan-planner",
   model="{planner_model}",
   description="Revise quick plan: ${DESCRIPTION}"
 )

package/pan-wizard-core/workflows/todo-check.md

@@ -12,7 +12,8 @@ Read all files referenced by the invoking prompt's execution_context before star
 Load todo context:
 
 ```bash
-INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init todos)
+AREA=""   # the area argument when one was given: /pan:todo-check api → AREA="api"; empty lists every todo
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init todos "$AREA")
 ```
 
 Extract from init JSON: `todo_count`, `todos`, `pending_dir`.
@@ -35,7 +36,7 @@ Exit.
 </step>
 
 <step name="parse_filter">
-Check for area filter in arguments:
+The area filter was applied in init_context (AREA):
 - `/pan:todo-check` → show all
 - `/pan:todo-check api` → filter to area:api only
 </step>

package/pan-wizard-core/workflows/transition.md

@@ -155,6 +155,8 @@ If found, delete them — phase is complete, handoffs are stale.
 TRANSITION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${current_phase}")   # skip when exec-phase invoked this workflow: its `phase complete` already ran — reuse that result
 ```
 
+`phase complete` runs the phase gate first. Exit 1 with `error: phase_gate_refused` (`workflow.phase_gate: enforce`) means the phase was not marked complete: show `gate.reasons` and stop the transition. With `gate.ok` false under `warn`, the phase was marked complete: show the reasons as warnings before continuing.
+
 The CLI handles:
 - Marking the phase checkbox as `[x]` complete with today's date
 - Updating plan count to final (e.g., "3/3 plans complete")
@@ -453,6 +455,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Plan Phase ${NEXT_PHASE}"
 )
 ```
@@ -495,6 +498,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Discuss Phase ${NEXT_PHASE}"
 )
 ```

package/pan-wizard-core/workflows/verify-phase.md

@@ -105,15 +105,15 @@ HAS_TEST=$(node -e "try{const p=require('./package.json');process.stdout.write(p
 ```bash
 TEST_OUTPUT=$(npm test 2>&1)
 TEST_EXIT=$?
-TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -E "^ℹ tests" | awk '{print $NF}')
-TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^ℹ pass" | awk '{print $NF}')
-TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^ℹ fail" | awk '{print $NF}')
+TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
+TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) pass" | awk '{print $NF}')
+TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) fail" | awk '{print $NF}')
 ```
 
 3. Evaluate results.
 
 **Check `TEST_EXIT` FIRST, before any count.** A suite that did not run emits no
-`ℹ fail` line at all, so `TEST_FAIL` comes back EMPTY — not `0`. Reading an empty
+`ℹ fail` / `# fail` line at all, so `TEST_FAIL` comes back EMPTY — not `0`. Reading an empty
 value as "no failures" scores a crashed suite as a pass, which is the worst
 direction this gate can fail in: a phase ships green on a project whose tests never
 executed. Empty is not zero. Judge the exit code, then the counts.
@@ -121,7 +121,7 @@ executed. Empty is not zero. Judge the exit code, then the counts.
 | Condition | Action |
 |-----------|--------|
 | `TEST_EXIT` = 0 **and** `TEST_FAIL` = 0 (a real number) | Record counts, continue to must-haves |
-| `TEST_EXIT` = 0 **and** no `ℹ` count lines (a runner other than Node's built-in one) | Set `test_gate_status: passed`; record the runner's own summary line as the counts |
+| `TEST_EXIT` = 0 **and** no `ℹ`/`#` count lines (a runner other than Node's built-in one) | Set `test_gate_status: passed`; record the runner's own summary line as the counts |
 | `TEST_EXIT` ≠ 0 **and** failures were reported | Set `test_gate_status: failed`, include failure details |
 | `TEST_EXIT` ≠ 0 **and** `TEST_FAIL` is empty/absent — the suite CRASHED or could not run (syntax error, missing module, bad import, no runner) | Set `test_gate_status: failed`, and record the reason as `suite did not run`. **Never `skipped`, never `passed`.** A suite that cannot execute is stronger evidence of a broken phase than one that runs and fails |
 | `HAS_TEST` = `no` (handled in step 1) | Record as `test_gate_status: skipped`, continue. This is the ONLY legitimate route to `skipped` |
@@ -328,7 +328,7 @@ If human_needed: list items requiring human testing.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
 
-**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt, and it closes the gaps it no longer reports:
+**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt. It closes the gaps it lists under `re_verification.gaps_closed`; a gap it neither reports nor answers stays open:
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${phase_number}" --file "$REPORT_PATH" 2>/dev/null || true
 ```

package/scripts/build-hooks.js

@@ -18,6 +18,7 @@ const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [
   'pan-check-update.js',
+  'pan-guard.js',
   'pan-context-monitor.js',
   'pan-statusline.js',
   'pan-cost-logger.js',

package/scripts/generate-skills-docs.py

@@ -391,11 +391,11 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
                 w(s.description)
                 w("")
             if s.argument_hint:
-                w(f"```")
+                w("```text")
                 w(f"{s.command} {s.argument_hint}")
                 w(f"```")
             else:
-                w(f"```")
+                w("```text")
                 w(f"{s.command}")
                 w(f"```")
             w("")