pan-wizard 3.33.0 → 3.34.0

package/commands/pan/plan-phase.md

@@ -19,7 +19,7 @@ Create executable phase prompts (plan.md files) for a roadmap phase with integra
 
 **Default flow:** Research (if needed) → Plan → Verify → Done
 
-**Design input (ADR-0042):** if `{phase}-design.md` exists (from `/pan:design-phase`, verified by `pan-design-checker`), it is an authoritative upstream input — `pan-planner` implements its approved architecture/decisions and `pan-plan-checker` verifies conformance (Design Conformance dimension). It is optional: a phase without a design.md plans exactly as before.
+**Design input (ADR-0042):** if `{phase}-design.md` exists (from `/pan:design-phase`, verified by `pan-design-checker`), it is an authoritative upstream input — `pan-planner` implements its approved architecture/decisions and `pan-plan-checker` verifies conformance (Design Conformance dimension). It is optional: a phase without a design.md plans exactly as before. The plan-phase workflow does not list it in the planner's or checker's `<files_to_read>`, so they use it only when they find it in the phase directory themselves.
 
 **Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn pan-planner, verify with pan-plan-checker, iterate until pass or max iterations, present results.
 </objective>
@@ -38,6 +38,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--gaps` — Gap closure mode (reads verification.md, skips research)
 - `--skip-verify` — Skip verification loop
 - `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into context.md automatically. Skips discuss-phase entirely.
+- `--auto` — Autonomous mode: sets `workflow.auto_advance` and asks nothing (with no context.md it plans from the project-level research, requirements and idea.md); after planning it runs `/pan:exec-phase N --auto --no-transition` and, once the phase completes, prints `Next: /pan:discuss-phase <next phase> --auto` and stops.
 
 Normalize phase input in step 2 before any directory lookups.
 </context>
@@ -48,7 +49,7 @@ During the plan-checker verification iteration:
 2. For each identified gap: verify it is a genuine gap by re-reading the relevant requirement
 3. Do not blindly accept all critiques — some may be false positives from missing context
 4. Revise the plan to address genuine gaps only
-5. Maximum 2 revision iterations (plan → check → revise → check → final)
+5. At most 2 revisions: the workflow checks up to three times (plan → check → revise → check → revise → check); after the third check the user chooses force proceed, guidance or abandon
 This prevents over-revision while ensuring real gaps are closed.
 </reflexion_loop>
 
@@ -57,7 +58,7 @@ Planning is complete when ALL conditions are met:
 1. At least one plan.md file created in the phase directory
 2. Plan-checker passed (or max 2 revision iterations exhausted with final approval)
 3. Each plan contains: objective, task breakdown with estimates, dependency ordering, and key file links
-4. Research.md exists (unless --skip-research was used)
+4. Research.md exists, unless research was skipped (`--skip-research`, `--gaps`, `workflow.research: false`, or the single-plan lightweight-phase bypass)
 5. User presented with results and next-step options
 
 Planning FAILS if: phase not found in roadmap, or planner agent returns empty/malformed output after retries.
@@ -67,7 +68,7 @@ Planning FAILS if: phase not found in roadmap, or planner agent returns empty/ma
 Avoid these planning anti-patterns:
 ```
 BAD:  Plan has 25 tasks for a single phase → too granular, executor loses context
-GOOD: 5-8 tasks per plan, each with clear scope and testable outcome
+GOOD: 2-3 tasks per plan, each with clear scope and testable outcome (more work means more plans)
 
 BAD:  Task says "Implement the feature" with no file links or acceptance criteria
       → Executor guesses at scope, misses edge cases
@@ -92,7 +93,7 @@ IF --gaps flag is set:
 ELSE IF --prd <file> flag is set:
   → SKIP discuss-phase entirely
   → PARSE PRD file into context.md
-  → SKIP research (PRD provides requirements)
+  → RUN research as usual (step 3.5 writes context.md from the PRD, then continues to step 5)
   → PLAN from parsed requirements
   → VERIFY (unless --skip-verify)
 
@@ -120,23 +121,12 @@ IF --skip-verify:
 ELSE:
   → Spawn pan-plan-checker
   → IF checker PASSES: done
-  → IF checker finds gaps (iteration 1): revise plan, re-check
-  → IF checker finds gaps (iteration 2): final revision, present with caveats
-  → Max 2 revision iterations
+  → IF checker finds gaps (check 1 or 2): revise plan, re-check
+  → IF checker finds gaps (check 3): stop revising; the user chooses force proceed (open issues recorded as deferred), guidance and retry, or abandon
+  → Max 2 revisions, so at most 3 checks
 ```
 </routing_decision_tree>
 
-<cache_priming>
-**Before spawning research + planner agents, prime the prompt cache.** All sub-agents spawned within the next 5 minutes hit cached context instead of re-reading project.md / requirements.md / roadmap.md / state.md / standards.md.
-
-Run once per invocation:
-```
-pan-tools cache prime --summary
-```
-
-Returns `{blocks: [{path, bytes, cache}], total_bytes, sha}`. On a host runtime that supports prompt caching (Claude Code does), the host translates these block references into `cache_control: ephemeral`. Where prompt caching is unavailable this is a no-op — nothing breaks.
-</cache_priming>
-
 <process>
 Execute the plan-phase workflow from @~/.claude/pan-wizard-core/workflows/plan-phase.md end-to-end.
 Preserve all workflow gates (validation, research, planning, verification loop, routing).

package/commands/pan/preview.md

@@ -60,7 +60,7 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 ```
 
 **What it does:**
-1. `pan-tools preview milestone` returns `{phases_total, completed, remaining, avg_phase_duration_days, eta_date, confidence_pct, bottleneck, sample_size}`.
+1. `pan-tools preview milestone` returns `{current_milestone, phases_total, phases_completed, phases_remaining, avg_phase_duration_days, velocity_phases_per_week, eta_date, confidence_pct, bottleneck, sample_size}`.
 2. Spawn `pan-previewer` with `mode: milestone`.
 3. Agent writes `.planning/milestones/preview-<today>.md` with ETA + confidence + bottleneck + caveats + bottom line.
 

package/commands/pan/profile.md

@@ -10,7 +10,7 @@ allowed-tools:
 ---
 
 <objective>
-Switch the model profile used by PAN agents. Controls which Claude model each agent uses, balancing quality vs token spend.
+Switch the model profile used by PAN agents. Sets the model tier PAN's workflows pass when they spawn an agent (mapped to the detected provider's models), balancing quality vs token spend. `/pan:army` and `pan-conductor` spawn with no model, so the agents they run use their own `model:` pin, else the session model, under every profile.
 
 Routes to the profile workflow which handles:
 - Argument validation (quality/balanced/budget)
@@ -37,7 +37,7 @@ The workflow handles all logic including:
 </process>
 
 <tier_decision_tree>
-**Capability-aware routing** (shipped v2.10.0 — E-7). Even within a single profile, PAN picks a tier per-call based on three hints: context estimate, whether the task needs extended thinking, and whether prompt cache is warm.
+**Capability-aware routing** (shipped v2.10.0 — E-7). `resolveModel` can adjust the profile's tier per call from three hints — context estimate, whether the task needs extended thinking, and whether prompt cache is warm — but only when the caller passes them (`resolve-model <agent> --metadata '{…}'`). No shipped workflow, command or agent passes them, so the tree and the quick guide below describe what a caller's hints would do.
 
 The decision order `resolveModel` applies after the baseline profile pick:
 

package/commands/pan/quick.md

@@ -2,7 +2,7 @@
 name: pan:quick
 group: Session & Progress
 description: Execute a quick task with PAN guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full]"
+argument-hint: "[--full] [description]"
 allowed-tools:
   - Read
   - Write

package/commands/pan/remove-phase.md

@@ -28,5 +28,5 @@ Roadmap and state are resolved in-workflow via `init phase-op` and targeted read
 
 <process>
 Execute the remove-phase workflow from @~/.claude/pan-wizard-core/workflows/remove-phase.md end-to-end.
-Preserve all validation gates (future phase check, work check), renumbering logic, and commit.
+Preserve all validation gates (future phase check, work check), renumbering logic, and commit. The removal deletes tracked files, so commit with `--force` once the user has confirmed it: without it `pan-tools commit` refuses any pending deletion (`deleted_files_detected`).
 </process>

package/commands/pan/report.md

@@ -2,7 +2,7 @@
 name: pan:report
 group: Observability
 description: Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report
-argument-hint: "phase <N> | index [--bundle] | all [--out <file>] [--open] [--stdout]"
+argument-hint: "phase <N> [--out <file>] [--open] [--stdout] | index [--out <file>] [--open] [--stdout] [--bundle] | all [--open]"
 allowed-tools:
   - Read
   - Bash
@@ -48,7 +48,7 @@ pan-tools report all        [--open]
 {
   "action": "phase",
   "phase": "03",
-  "path": ".planning/phases/03-auth-sessions/03-report.html",
+  "path": "/abs/path/to/project/.planning/phases/03-auth-sessions/03-report.html",
   "bytes": 16183,
   "status": "complete",
   "written": true,

package/commands/pan/research-phase.md

@@ -2,7 +2,7 @@
 name: pan:research-phase
 group: Phase Lifecycle
 description: Research how to implement a phase (standalone - usually use /pan:plan-phase instead)
-argument-hint: "[phase]"
+argument-hint: "<phase>"
 allowed-tools:
   - Read
   - Bash
@@ -38,7 +38,7 @@ Normalize phase input in step 1 before any directory lookups.
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "$ARGUMENTS")
 ```
 
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
+Extract from init JSON: `phase_dir`, `padded_phase`, `phase_slug`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`. `phase_dir` is null when the phase is in the roadmap but has no directory yet: create it (`mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"`) and use that path as `phase_dir`, as discuss-phase does.
 
 Resolve researcher model:
 ```bash
@@ -63,8 +63,11 @@ Use `has_research` and `research_path` from INIT.
 
 ## 3. Gather Phase Context
 
-Use paths from INIT (do not inline file contents in orchestrator context):
-- `requirements_path`
+Write this phase's roadmap slice (its section, its dependencies' goals and its requirement lines), then use paths from INIT (do not inline file contents in orchestrator context):
+```bash
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${phase_number}" --write --raw)
+```
+- `slice_path` (from the command above; `requirements_path` if it is empty)
 - `context_path`
 - `state_path`
 
@@ -72,7 +75,7 @@ Present summary with phase description and what files the researcher will load.
 
 ## 4. Spawn pan-phase-researcher Agent
 
-Research modes: ecosystem (default), feasibility, implementation, comparison.
+Research mode: the prompt below names `ecosystem`; pan-phase-researcher defines no modes, so treat it as context, not a switch.
 
 ```markdown
 <research_type>
@@ -98,7 +101,7 @@ Mode: ecosystem
 </objective>
 
 <files_to_read>
-- {requirements_path} (Requirements)
+- {slice_path} (This phase's roadmap and requirements)
 - {context_path} (Phase context from discuss-phase, if exists)
 - {state_path} (Prior project decisions and blockers)
 </files_to_read>
@@ -128,7 +131,7 @@ Before declaring complete, verify:
 </quality_gate>
 
 <output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-research.md
+Write to: {phase_dir}/{padded_phase}-research.md
 </output>
 ```
 
@@ -145,9 +148,7 @@ Task(
 
 **`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
 
-**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
-
-**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+**`## RESEARCH BLOCKED`:** Show the blocker and what was attempted, offer: Provide context (then spawn a continuation, step 6), Skip research, Abort.
 
 ## 6. Spawn Continuation Agent
 
@@ -158,7 +159,7 @@ Continue research for Phase {phase_number}: {phase_name}
 
 <prior_state>
 <files_to_read>
-- .planning/phases/${PHASE}-{slug}/${PHASE}-research.md (Existing research)
+- {phase_dir}/{padded_phase}-research.md (Existing research)
 </files_to_read>
 </prior_state>
 

package/commands/pan/resume.md

@@ -62,22 +62,20 @@ ELSE IF .continue-here.md exists:
   → PRESENT: position, blockers, next action
   → ROUTE to the command that was paused (exec-phase, plan-phase, etc.)
 
-ELSE IF state.md exists AND has status "in_progress":
+ELSE IF state.md exists (its Status is free text — Ready to plan, Ready to execute, In progress, Phase complete, Milestone complete and the like; none says "blocked"):
+  → IF state.md's `### Blockers/Concerns` lists a blocker:
+    → PRESENT the blockers first
+    → OFFER: debug (/pan:debug) or unblock manually
   → FIND incomplete work: plans without summaries, phases mid-execution
   → IF incomplete phase found:
     → PRESENT phase status + what remains
     → OFFER: continue execution (/pan:exec-phase) or verify (/pan:verify-phase)
-  → IF no incomplete work but active milestone:
+  → ELSE IF roadmap phases remain incomplete (`roadmap analyze`):
     → PRESENT milestone progress
-    → OFFER: next unplanned phase (/pan:plan-phase) or audit (/pan:milestone-audit)
-
-ELSE IF state.md exists AND has status "blocked":
-  → PRESENT blockers from state.md
-  → OFFER: debug (/pan:debug) or unblock manually
-
-ELSE IF state.md exists AND has status "completed":
-  → "Current milestone is complete. Run /pan:milestone-done or /pan:milestone-new."
-  → STOP
+    → OFFER: next unplanned phase (/pan:discuss-phase, or /pan:plan-phase when it has a context.md) or audit (/pan:milestone-audit)
+  → ELSE (every roadmap phase complete):
+    → "Current milestone is complete. Run /pan:milestone-audit, then /pan:milestone-done, or /pan:milestone-new."
+    → STOP
 
 ELSE (state.md missing or unreadable):
   → ATTEMPT reconstruction from .planning/ artifacts

package/commands/pan/retro.md

@@ -2,7 +2,7 @@
 name: pan:retro
 group: Milestone Lifecycle
 description: Milestone retrospective — analyze estimation accuracy, verification patterns, and common gaps
-argument-hint: ""
+argument-hint: "[--write-memory] [--max N]"
 allowed-tools:
   - Read
   - Bash
@@ -14,7 +14,7 @@ Analyze completed milestone work to identify process improvement opportunities.
 
 Examines roadmap phases (planned vs completed, gap closures), verification results (pass rates, common gaps), and estimation accuracy. Output guides future planning improvements.
 
-This is a reflection command — **read-only by default**: with no flags it does not modify any files. Passing `--write-memory` (as `/pan:army` does) is the one exception — it appends recurring-pattern entries to agent memory so they persist into the next mission.
+This is a reflection command — **read-only by default**: with no flags it does not modify any files. Passing `--write-memory` is the one exception: it appends recurring-pattern entries to the agent logs in `.planning/memory/`, which `/pan:knowledge` reads. PAN's workflows do not load those logs into agents, so a pattern meant to change the next plan goes into that plan's brief or the project's instructions.
 </objective>
 
 <execution_context>
@@ -24,8 +24,10 @@ This is a reflection command — **read-only by default**: with no flags it does
 <context>
 No arguments required. Operates on the current `.planning/` directory.
 
+Flags: $ARGUMENTS
+
 **Flags:**
-- `--write-memory` — after analysis, append recurring-pattern entries to agent memory (used by `/pan:army`). Without this flag the command is strictly read-only.
+- `--write-memory` — after analysis, append recurring-pattern entries to the agent logs in `.planning/memory/` (stored for `/pan:knowledge`, not loaded into agents). `--max N` caps the planner lessons (default 3). Without `--write-memory` the command is strictly read-only.
 
 The retro command is typically run after `/pan:milestone-done` to reflect on the milestone before starting the next one.
 </context>

package/commands/pan/review-deep.md

@@ -54,7 +54,7 @@ Runs the normal exec → reviewer pipeline, then runs this command's process inl
 /pan:focus-exec --deep-review
 ```
 
-Per-item deep review during focus campaigns. Useful for high-stakes batches.
+Per-item deep review during focus campaigns: focus-exec runs the hardener and meta-reviewer on the item's changed files and merges them under the item's id (`review-deep merge <item-id>` with no `--reviewer-file`), since an item has no phase or first-pass review. Useful for high-stakes batches.
 
 </invocation_modes>
 
@@ -67,7 +67,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
    - Agent writes its findings to the output path, returns confirmation.
 
 3. **Spawn pan-meta-reviewer**:
-   - Prompt includes: `<files_to_read>` with both reviewer.md AND hardener.md (and representative diff snippets); `<output_path>` = `.planning/reviews/<N>/meta.md`.
+   - Prompt includes: `<files_to_read>` with both `{directory}/{phase_number}-review.md` AND `.planning/reviews/<N>/hardener.md` (and representative diff snippets); `<output_path>` = `.planning/reviews/<N>/meta.md`.
    - Agent reads both first-pass reports, identifies missed patterns, disputes overstated severities, writes to output path.
 
 4. **Merge** — call:
@@ -87,13 +87,13 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 
 | Verdict | Meaning | Action |
 |---------|---------|--------|
-| `ok` | No findings at any severity | Merge freely |
-| `ok_with_minor` | Only low/info findings | Merge with noted follow-ups |
+| `ok` | No findings, or info findings only | Merge freely |
+| `ok_with_minor` | Only low findings (info alone gives `ok`) | Merge with noted follow-ups |
 | `fix_before_merge` | Medium findings present | Fix or document before merge |
 | `review_required` | High findings present | Human sign-off required |
 | `block` | At least one critical | Do not merge |
 
-Verdict is driven by the highest-severity finding across all three sources. Meta-reviewer disputes can downgrade severity on specific findings but don't change the headline verdict — the merger trusts the consensus of the explicit severity labels.
+Verdict is driven by the highest-severity finding across all three sources. Meta-reviewer disputes are listed in the conflict table but change no severity, so they never lower the headline verdict; the meta-reviewer's own findings count toward it like the other two sources'.
 
 </verdict_semantics>
 
@@ -114,8 +114,8 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 | Claude Code | Full; reasoning depth from the agent's `effort:` frontmatter | Full | Full |
 | OpenCode | Prose "think step-by-step" preamble substitutes for thinking | Same | Full (runtime-agnostic CLI) |
 | Gemini | Same | Same | Full |
-| Codex | Same | Same | Full |
-| Copilot | Same | Same | Full |
+| Codex | Native — `effort:` becomes the agent TOML's `model_reasoning_effort` | Same | Full |
+| Copilot | Prose "think step-by-step" preamble, as on OpenCode | Same | Full |
 
 The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability.
 

package/commands/pan/settings.md

@@ -15,7 +15,7 @@ Interactive configuration of PAN workflow agents and model profile via multi-que
 Routes to the settings workflow which handles:
 - Config existence ensuring
 - Current settings reading and parsing
-- Interactive 5-question prompt (model, research, plan_check, verifier, branching)
+- Interactive multi-question prompt (model profile, research, plan_check, verifier, auto_advance, nyquist_validation, branching strategy, routing strategy)
 - Config merging and writing
 - Confirmation display with quick command references
 </objective>

package/commands/pan/verify-phase.md

@@ -74,17 +74,6 @@ After initial verification of each requirement:
 This prevents premature FAIL verdicts from incomplete investigation.
 </reflexion_loop>
 
-<cache_priming>
-**Before the verifier agent runs**, prime the prompt cache once. The verifier reads project.md / requirements.md / roadmap.md every run; caching avoids ~15-50K input tokens per invocation.
-
-Run once:
-```
-pan-tools cache prime --summary
-```
-
-See [plan-phase.md](plan-phase.md) or [exec-phase.md](exec-phase.md) for the full explanation. No-op on non-Claude runtimes.
-</cache_priming>
-
 <process>
 Execute the verify-phase workflow from @~/.claude/pan-wizard-core/workflows/verify-phase.md end-to-end.
 Preserve all workflow gates (the test-suite gate, the truth/artifact/wiring checks, status determination, the verification report).

package/commands/pan/what-if.md

@@ -56,7 +56,7 @@ If worktree creation fails (not a git repo, dirty tree blocking, etc.), abort wi
 
 ### Stage 2 — Spawn pan-counterfactual
 
-Spawn the agent with its working directory set to `worktree_path`. Prompt includes:
+Spawn the agent. A spawn cannot set its working directory — it starts in the main project — so the prompt's `<worktree_path>` is where it must work. Prompt includes:
 - `<files_to_read>` — the phase plan, any existing summary, the main project's `CLAUDE.md` so the agent understands conventions.
 - `<scenario>` — the user's scenario text verbatim.
 - `<worktree_path>` — so the agent knows the safe boundary.
@@ -69,7 +69,7 @@ The agent explores, then returns a JSON payload with `{summary, differences, rec
 Run (from main tree, NOT worktree):
 
 ```
-pan-tools whatif report <phase> "<scenario>" --comparison '<agent-json>'
+pan-tools whatif report <phase> "<scenario>" --comparison "$(cat <comparison-json-file>)"
 ```
 
 This writes `.planning/counterfactuals/<phase>-<slug>.md`. The file belongs to the main tree and survives worktree cleanup.