pan-wizard 3.34.0 → 3.36.0

package/pan-wizard-core/templates/summary-complex.md

@@ -53,7 +53,7 @@ completed: YYYY-MM-DD
 - DT-1: Chose [option] for O-N. Reason: [rationale].
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable].
+- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable]. Cost if wrong: [low | medium | high] — [what breaks].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -64,6 +64,10 @@ completed: YYYY-MM-DD
 [Problems during planned work and resolutions — distinct from Deviations above:
  Issues = bugs/blockers fixed; Deviations = intentional departures from plan]
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [What's ready for next phase]
 [Blockers or concerns]

package/pan-wizard-core/templates/summary-minimal.md

@@ -44,5 +44,9 @@ completed: YYYY-MM-DD
 [One line each, or this single line if none:
  "No deviations or open questions — implementation followed plan exactly."]
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [Ready for next phase]

package/pan-wizard-core/templates/summary-standard.md

@@ -49,7 +49,7 @@ completed: YYYY-MM-DD
 - DT-1: Chose [option] for O-N. Reason: [rationale].
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable].
+- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable]. Cost if wrong: [low | medium | high] — [what breaks].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -57,5 +57,9 @@ completed: YYYY-MM-DD
 <!-- If none: replace ALL three buckets with:
      "No deviations or open questions — implementation followed plan exactly." -->
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [What's ready for next phase]

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

@@ -88,7 +88,7 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 - DT-1: Chose [option] for O-N. Reason: [rationale].
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable].
+- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable]. Cost if wrong: [low | medium | high] — [what breaks].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -112,6 +112,7 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 - **Fix:** [What was done]
 - **Files modified:** [file paths]
 - **Verification:** [How it was verified]
+- **Cost if wrong:** [low | medium | high] — [what breaks, and for whom, if this call was wrong]
 - **Committed in:** [hash] (part of task commit)
 
 [... repeat for each auto-fix ...]
@@ -124,6 +125,12 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 ## Issues Encountered
 [Problems and how they were resolved, or "None"]
 
+## Concerns
+
+[What was finished but is not certain, or "None". Any entry here means the executor returned DONE_WITH_CONCERNS.]
+
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 [Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
 
 ## User Setup Required

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:**
@@ -105,6 +117,14 @@ Report:
 | 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
 | 2 | 01-03 | ... |
 ```
+
+**Test baseline.** Before the first wave, record what the test suite does now, so the verifier can tell a failure this phase caused from one it inherited:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "${PHASE_NUMBER}" --baseline > /dev/null
+```
+
+A phase that already has a baseline keeps it (a resumed run or a `--gaps-only` round compares against the phase's start, not its half-built state); the command says `kept_existing: true` and runs nothing. A failing or empty baseline is not a reason to stop: it is what the phase starts from.
 </step>
 
 <step name="execute_waves">
@@ -190,6 +210,10 @@ 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 `## DONE_WITH_CONCERNS`** finished its plan: run the same spot-checks and treat it as complete. Keep its concerns (each with why and cost if wrong, also under `## Concerns` in its summary) for the wave report and the phase report. Do not stop the wave for them; a high-cost concern is something the review and the verifier should look at, and the phase report puts it in front of the user.
+
+   **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:
    ```
    ---
@@ -197,7 +221,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    **{Plan ID}: {Plan Name}**
    {What was built — from summary.md}
-   {Notable deviations, if any}
+   {Notable deviations, if any, with their cost if wrong}
+   {Concerns, if it returned DONE_WITH_CONCERNS}
 
    {If more waves: what this enables for next wave}
    ---
@@ -215,6 +240,12 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
      2>/dev/null || true
    ```
 
+   Check the phase's spend against its budget (`cost.phase_budget_usd`, default $20; it only warns):
+   ```bash
+   BUDGET=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs cost budget --phase "${PHASE_NUMBER}" 2>/dev/null)
+   ```
+   When its `status` is `near` or `over`, add one line to the wave report: "Spend: ${spent_usd} of the ${budget_usd} phase budget (${pct}%)", and for `over`, "over budget: the phase keeps running; change the budget with /pan:settings". Do not stop, pause or ask: the budget warns, it never blocks. `ok` and `off` add nothing.
+
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
@@ -309,7 +340,14 @@ After all waves:
 
 ### Issues Encountered
 [Aggregate from SUMMARYs, or "None"]
+
+### Concerns
+[Every concern from the plans that returned DONE_WITH_CONCERNS (and any `## Concerns` entry in a summary), high cost if wrong first:]
+- **03-02** C-1: [concern]. Why: [...]. Cost if wrong: high — [what breaks]
+[Or "None"]
 ```
+
+Concerns go into the review too: the code_review step passes them to the reviewer as `${EXECUTOR_CONCERNS}`, so a high-cost concern is checked rather than only reported.
 </step>
 
 <step name="generate_tests">
@@ -319,7 +357,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 +369,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 +381,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 +392,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>
 
@@ -361,15 +402,17 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
 
 **Skip if** `--skip-review` or `--fast` flag is present in $ARGUMENTS.
 
-1. Collect changed files from executor summaries:
+1. Collect the review scope: the files the phase's commits changed plus any uncommitted or untracked work, whether or not a summary lists them, and the intent to judge them against:
 ```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*- //'
-done | sort -u > /tmp/review-files.txt
+REVIEW_SCOPE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "${PHASE_NUMBER}")
+CHANGED_FILES_LIST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "${PHASE_NUMBER}" --raw)
 ```
+`REVIEW_SCOPE` is JSON. Its `unlisted` array holds the changed files no summary's key-files names. Review them like the others: an executor that changed a file without listing it is exactly what a review must not miss. Its `intent` holds each plan's objective, `must_haves` and Review Focus, and the text of the requirements the plans claim.
 
-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 +434,23 @@ Task(
     Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
     Phase directory: ${phase_dir}
     </context>
+
+    <intent>
+    The plans' objectives, must_haves and Review Focus, the requirements they claim,
+    and the changed files no summary listed (review scope JSON):
+    ${REVIEW_SCOPE}
+    </intent>
+
+    <executor_concerns>
+    What the executors finished but were not sure of, each with why and its cost if
+    wrong (from DONE_WITH_CONCERNS returns and the summaries' ## Concerns). Check the
+    high-cost ones first. Empty when there were none:
+    ${EXECUTOR_CONCERNS}
+    </executor_concerns>
+
+    <open_findings>
+    ${OPEN_REVIEW_FINDINGS}
+    </open_findings>
   "
 )
 ```
@@ -426,7 +486,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 +613,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 +659,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 (`workflow.phase_gate: warn`) | 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 +733,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 +749,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/execute-plan.md

@@ -218,10 +218,12 @@ Proceed with proposed change? (yes / different approach / defer)
 
 Summary MUST include deviations section. None? → `## Deviations from Plan\n\nNone - plan executed exactly as written.`
 
-Per deviation: **[Rule N - Category] Title** — Found during: Task X | Issue | Fix | Files modified | Verification | Commit hash
+Per deviation: **[Rule N - Category] Title** — Found during: Task X | Issue | Fix | Files modified | Verification | Cost if wrong (low, medium or high, and what breaks) | Commit hash
 
 End with: **Total deviations:** N auto-fixed (breakdown). **Impact:** assessment.
 
+Then `## Concerns`: what was finished but is not certain, each as `- C-1: <concern>. Why: <…>. Cost if wrong: <…>.`, or "None". A plan with concerns returns `## DONE_WITH_CONCERNS` (see the executor's completion format).
+
 </deviation_documentation>
 
 <tdd_plan_execution>

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

@@ -209,81 +209,140 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 ## All Commands
 
-> This table is a **curated subset** of the most-used commands, not an exhaustive list. For the full, always-current command set, browse the `commands/pan/*.md` files in your install (each `.md` is one `/pan:<name>` command).
+Every shipped command, by group. This list is generated from each command's own description, so it is complete.
 
+<!-- generated:command-index:start (scripts/build-help.cjs --write) -->
 ### Getting Started
 | Command | Description |
 |---------|-------------|
-| `/pan:new-project` | Initialize new project — research, requirements, roadmap |
-| `/pan:map-codebase` | Analyze existing codebase with parallel agents |
+| `/pan:map-codebase` | Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents |
+| `/pan:new-project` | Initialize a new project with deep context gathering and project.md |
 
 ### Phase Lifecycle
 | Command | Description |
 |---------|-------------|
-| `/pan:discuss-phase <N>` | Shape implementation through targeted questions |
-| `/pan:plan-phase <N>` | Research + plan a phase with verification |
-| `/pan:exec-phase <N>` | Execute plans with wave-based parallelization |
-| `/pan:research-phase <N>` | Deep ecosystem research for specialized domains |
-| `/pan:verify-phase <N>` | Re-run goal-backward verification with a test-suite gate |
+| `/pan:design-phase` | Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker |
+| `/pan:discuss-phase` | Gather phase context through adaptive questioning before planning |
+| `/pan:exec-phase` | Execute all plans in a phase with wave-based parallelization |
+| `/pan:plan-phase` | Create detailed phase plan (plan.md) with verification loop |
+| `/pan:research-phase` | Research how to implement a phase (standalone - usually use /pan:plan-phase instead) |
+| `/pan:verify-phase` | Re-run goal-backward verification of a phase with a test-suite gate and list its gaps |
 
 ### Phase Management
 | Command | Description |
 |---------|-------------|
-| `/pan:add-phase <desc>` | Append new phase to roadmap |
-| `/pan:insert-phase <N> <desc>` | Insert urgent work between phases |
-| `/pan:remove-phase <N>` | Remove phase and renumber |
-| `/pan:assumptions <N>` | Surface approach assumptions before planning |
-| `/pan:phase-tests <N>` | Generate tests for completed phase |
-| `/pan:phase-budget` | Estimate context utilization for current phase |
+| `/pan:add-phase` | Add phase to end of current milestone in roadmap |
+| `/pan:assumptions` | Surface Claude's assumptions about a phase approach before planning |
+| `/pan:insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases |
+| `/pan:phase-budget` | Estimate context utilization and quality for the current phase |
+| `/pan:phase-tests` | Generate tests for a completed phase from its summaries, context decisions, verification report and implementation |
+| `/pan:remove-phase` | Remove a future phase from roadmap and renumber subsequent phases |
 
 ### Session & Progress
 | Command | Description |
 |---------|-------------|
-| `/pan:progress` | Check status and route to next action |
-| `/pan:quick <desc>` | Fast-path execution (skip optional agents) |
-| `/pan:pause` | Save context for later resumption |
-| `/pan:resume` | Restore previous session context |
-| `/pan:profile <name>` | Switch model profile (quality/balanced/budget) |
+| `/pan:pause` | Create context handoff when pausing work mid-phase |
+| `/pan:profile` | Switch model profile for PAN agents (quality/balanced/budget) |
+| `/pan:progress` | Check project progress, show context, and route to next action (execute or plan) |
+| `/pan:quick` | Execute a quick task with PAN guarantees (atomic commits, state tracking) but skip optional agents |
+| `/pan:resume` | Resume work from previous session with full context restoration |
 
 ### Milestone
 | Command | Description |
 |---------|-------------|
-| `/pan:milestone-new` | Start a new milestone cycle |
-| `/pan:milestone-done <v>` | Archive completed milestone |
-| `/pan:milestone-audit` | Audit completion against intent |
-| `/pan:milestone-gaps` | Create phases to close audit gaps |
-| `/pan:milestone-cleanup` | Archive accumulated phase directories |
-| `/pan:retro` | Milestone retrospective — estimation & verification analysis |
-
-### Focus (Strategic Project Management)
+| `/pan:milestone-audit` | Audit milestone completion against original intent before archiving |
+| `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
+| `/pan:milestone-done` | Archive completed milestone and prepare for next version |
+| `/pan:milestone-gaps` | Create phases to close all gaps identified by milestone audit |
+| `/pan:milestone-new` | Start a new milestone cycle — update project.md and route to requirements |
+
+### Milestone Lifecycle
+| Command | Description |
+|---------|-------------|
+| `/pan:retro` | Milestone retrospective — analyze estimation accuracy, verification patterns, and common gaps |
+
+### Focus
+| Command | Description |
+|---------|-------------|
+| `/pan:focus-auto` | Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness |
+| `/pan:focus-design` | Strategic 10-phase feature investigation, design, and specification pipeline |
+| `/pan:focus-doc-audit` | Multi-dimensional document audit — accuracy, freshness, links, cross-consistency, and structural quality |
+| `/pan:focus-drift-walking` | Deep documentation-code drift detection, CLAUDE.md alignment, and auto-repair across all project directories |
+| `/pan:focus-exec` | Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers |
+| `/pan:focus-plan` | Create capacity-budgeted work batch with spec coverage verification and 4 execution modes |
+| `/pan:focus-scan` | Deep-dive strategic work scan with prioritized items and Reality Score filtering |
+| `/pan:focus-sync` | Synchronize documentation after changes — check staleness and update counts |
+
+### Foresight
+| Command | Description |
+|---------|-------------|
+| `/pan:preview` | Preview what will happen — phase blast radius, phase dependency graph, or milestone ETA |
+| `/pan:what-if` | Explore a phase's alternative approach in an isolated git worktree. Replays the scenario, compares to the original plan, writes a report. |
+
+### Review
+| Command | Description |
+|---------|-------------|
+| `/pan:review-deep` | Security audit + cross-reviewer check. OWASP/STRIDE pass by pan-hardener, then pan-meta-reviewer catches what the first pass missed. Writes consolidated deep-review.md. |
+
+### Validation
+| Command | Description |
+|---------|-------------|
+| `/pan:links` | Validate the doc-code link graph — inline wiki-style refs, source-comment anchors, and require-code-mention contracts (ADR-0027, v3.8.0+) |
+
+### Observability
+| Command | Description |
+|---------|-------------|
+| `/pan:cost` | Show token usage and estimated cost across PAN commands and agents |
+| `/pan:dashboard` | Alias for /pan:hud — generate the single-page HTML dashboard of the bot army and project |
+| `/pan:hud` | Generate a single-page, self-contained HTML dashboard of the bot army and the project's current state |
+| `/pan:report` | Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report |
+
+### Knowledge
+| Command | Description |
+|---------|-------------|
+| `/pan:knowledge` | Grounded Q&A, multi-turn design discussion, and playbook generation. Three modes in one command. |
+
+### Self-Improvement
+| Command | Description |
+|---------|-------------|
+| `/pan:experiment` | Manage external experiments — scaffold, run, harvest, promote findings back to PAN |
+| `/pan:learn` | Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports |
+| `/pan:optimize` | Manage the circular optimization loop — record a report's suggestions, undo them, view stats, list reports, manage trace sessions |
+
+### Git Workflow
+| Command | Description |
+|---------|-------------|
+| `/pan:git` | Safe, phase-aware git workflow commands — commit, branch, push, status, log, stash, diff, rollback, tag, sync |
+
+### Army
+| Command | Description |
+|---------|-------------|
+| `/pan:army` | Bot-army campaign — Mission Control (the reasoning-tier conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires. |
+
+### External tools
 | Command | Description |
 |---------|-------------|
-| `/pan:focus-scan` | Step 1: Find and prioritize all work items |
-| `/pan:focus-plan` | Step 2: Budget items into an execution batch |
-| `/pan:focus-exec` | Step 3: Implement, test, verify, commit |
-| `/pan:focus-sync` | Step 4: Synchronize documentation after changes |
-| `/pan:focus-auto` | Continuous scan→plan→exec loop with safety harness |
-| `/pan:focus-design <desc>` | Standalone: Deep feature investigation and spec |
-| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, auto-repair |
-| `/pan:focus-doc-audit` | Deep document audit with quality scoring |
+| `/pan:mcp-bridge` | Discover available MCP tools and recommend which ones apply to a phase. Discovery-only; auto-invocation deferred. |
 
 ### System
 | Command | Description |
 |---------|-------------|
-| `/pan:help` | Show this reference |
-| `/pan:health` | Diagnose planning directory integrity |
-| `/pan:settings` | Configure workflow toggles |
-| `/pan:update` | Update PAN to latest version |
-| `/pan:debug` | Systematic debugging with persistent state |
-| `/pan:todo-add` | Capture idea as todo |
-| `/pan:todo-check` | List and select pending todos |
-| `/pan:audit-deployment <dir>` | Audit a PAN installation for integrity and health |
+| `/pan:audit-deployment` | Audit a PAN Wizard deployment — verify installation integrity, project health, and draft enhancement specs |
+| `/pan:debug` | Systematic debugging with persistent state across context resets |
+| `/pan:health` | Diagnose planning directory health and optionally repair issues |
+| `/pan:help` | Show available PAN commands and usage guide |
+| `/pan:hygiene` | Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat and stale entries, poisoned ledgers, trace debris, oversized planning files) and apply safe cleanups |
+| `/pan:patches` | Reapply local modifications after a PAN update |
+| `/pan:settings` | Configure PAN workflow toggles and model profile |
+| `/pan:todo-add` | Capture idea or task as todo from current conversation context |
+| `/pan:todo-check` | List pending todos and select one to work on |
+| `/pan:update` | Update PAN to latest version with changelog display |
 
 ### Community
 | Command | Description |
 |---------|-------------|
 | `/pan:discord` | Join the PAN Discord community |
-| `/pan:patches` | Reapply local modifications after update |
+<!-- generated:command-index:end -->
 
 ---
 

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: