pan-wizard 3.33.0 → 3.35.0

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

@@ -1,5 +1,5 @@
 <purpose>
-Create executable phase prompts (plan.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates pan-phase-researcher, pan-planner, and pan-plan-checker agents with a revision loop (max 3 iterations).
+Create executable phase prompts (plan.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates pan-phase-researcher, pan-planner, and pan-plan-checker agents with a revision loop (at most 2 revisions, up to 3 checks).
 </purpose>
 
 <required_reading>
@@ -8,7 +8,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 @~/.claude/pan-wizard-core/references/ui-brand.md
 @~/.claude/pan-wizard-core/references/guardrails.md
 
-> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent planner --token-budget 5000 --raw` to load only the topics tagged relevant for planning at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent planner --cue "<phase goal; the files it touches>" --token-budget 5000 --raw` to load the topics that match this task, within the budget; if none matches, it falls back to the topics tagged relevant for planning. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
 </required_reading>
 
 ## Phase 0 — Clarify Phase Scope (recommended)
@@ -19,7 +19,7 @@ Before drafting the phase plan, confirm:
 2. **What's deliberately out of scope?**
 3. **Any constraints or dependencies on other phases?**
 
-If the answers aren't already in `.planning/requirements.md` or the phase context file, ask the user. A 2-minute clarification prevents 30-minute rework downstream.
+If the answers aren't already in the phase's roadmap section and requirement lines (`pan-tools roadmap slice <phase> --raw` prints them) or the phase context file, ask the user — except with `--auto` or `workflow.auto_advance: true`, where you proceed with what the files hold (as step 4 does). A 2-minute clarification prevents 30-minute rework downstream.
 
 ## Re-Read Checkpoints
 
@@ -44,7 +44,7 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init plan-phase "$PHASE"
 
 Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
 
-**File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist.
+**File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. The first three are always set, even when the file is missing; the other four are absent (treat as null) when their file does not exist.
 
 **If `planning_exists` is false:** Error — run `/pan:new-project` first.
 
@@ -63,9 +63,9 @@ Extract `--prd <filepath>` from $ARGUMENTS. If present, set PRD_FILE to the file
 
 **If no phase number:** Detect next unplanned phase from roadmap.
 
-**If `phase_found` is false:** Validate phase exists in roadmap.md. If valid, create the directory using `phase_slug` and `padded_phase` from init:
+**If `phase_found` is false:** Validate phase exists in roadmap.md. If valid, create the directory (scaffold pads the number and honours the planning root) and use the path it prints as `phase_dir`:
 ```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw
 ```
 
 **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
@@ -78,6 +78,14 @@ PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase
 
 **If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
+## 3.1. Write the Phase's Roadmap Slice
+
+```bash
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${PHASE}" --write --raw)
+```
+
+`SLICE_PATH` (`{slice_path}` below) is what this phase needs from roadmap.md and requirements.md: a line for every phase, this phase's section, the goals of the phases it depends on, and its requirement lines. The researcher, planner and checker read it instead of the whole files, which a long project re-read on every turn of every spawn. Plans name it in their `<context>` too, so executors read it rather than the whole roadmap. **If `SLICE_PATH` is empty** (no roadmap section, or no phase directory yet), list `{roadmap_path}` and `{requirements_path}` wherever `{slice_path}` appears below.
+
 ## 3.5. Handle PRD Express Path
 
 **Skip if:** No `--prd` flag in arguments.
@@ -214,15 +222,15 @@ If "Run discuss-phase first": Display `/pan:discuss-phase {X}` and exit workflow
 
 **P-1401 lightweight-phase bypass (v3.7.3+):** Also skip per-phase research when ALL three are true:
 
-1. The phase has only **1 plan** (read `plan_count` from init JSON)
-2. The plan's `change_class` is in `[chore, docs, feat-trivial]` (i.e., scaffolding, config, single-file feat with ≤3 tasks)
+1. The phase's roadmap section expects no more than one plan (`**Plans:** 1 plan`, or the `TBD` / `0 plans` the roadmapper and `phase add`/`insert` write before any planning); init's `plan_count` counts plans already written, which is 0 before the first planning run
+2. The phase is scaffolding, config, docs or a single-file feature with ≤3 tasks (judge from its goal; no plan field records this)
 3. Project-level `research/architecture.md`, `features.md`, `stack.md` already exist (so the planner has broad context to draw from)
 
 In that case, log a `decision` trace event (`type: "decision", category: "skip-research-trivial"`) and proceed directly to step 6 (planning). Saves ~3 commits and ~5 minutes per trivial phase. Surfaced by panloop run: Phase 1 (project setup, scaffolding only) over-ceremonialized.
 
 This is a workflow-level optimization — the planner still produces a plan, just without per-phase research.md. Phase 2+ phases with substantive build work still go through full research.
 
-**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${PHASE_NUM}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces the planning output (context, research, plan) to a record and a plan for trivial phases; execution still writes the plan's summary. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (>1 plan or non-trivial change_class) still produce full per-phase artifacts regardless of this flag.
+**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${padded_phase}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces the planning output (context, research, plan) to a record and a plan for trivial phases; execution still writes the plan's summary. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (more than one plan, or more than scaffolding, config, docs or a single-file feature) still produce full per-phase artifacts regardless of this flag.
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
@@ -240,7 +248,7 @@ Display banner:
 ### Spawn pan-phase-researcher
 
 ```bash
-PHASE_DESC=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" | jq -r '.section')
+PHASE_DESC=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw)   # --raw prints the phase's section
 ```
 
 Research prompt:
@@ -253,7 +261,7 @@ Answer: "What do I need to know to PLAN this phase well?"
 
 <files_to_read>
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
-- {requirements_path} (Project requirements)
+- {slice_path} (This phase's roadmap and requirements)
 - {state_path} (Project decisions and history)
 </files_to_read>
 
@@ -266,14 +274,14 @@ Answer: "What do I need to know to PLAN this phase well?"
 </additional_context>
 
 <output>
-Write to: {phase_dir}/{phase_num}-research.md
+Write to: {phase_dir}/{padded_phase}-research.md
 </output>
 ```
 
 ```
 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}"
 )
@@ -306,7 +314,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-${PHASE}): a
 **If not found (and nyquist enabled):** Display warning:
 ```
 ⚠ Nyquist validation enabled but researcher did not produce a Validation Architecture section.
-  Continuing without validation strategy. Plans may fail Dimension 8 check.
+  Continuing without validation strategy. The plan checker skips Nyquist Compliance (Dimension 9).
 ```
 
 ## 6. Check Existing Plans
@@ -319,17 +327,7 @@ ls "${PHASE_DIR}"/*-plan.md 2>/dev/null
 
 ## 7. Use Context Paths from INIT
 
-Extract from INIT JSON:
-
-```bash
-STATE_PATH=$(echo "$INIT" | jq -r '.state_path // empty')
-ROADMAP_PATH=$(echo "$INIT" | jq -r '.roadmap_path // empty')
-REQUIREMENTS_PATH=$(echo "$INIT" | jq -r '.requirements_path // empty')
-RESEARCH_PATH=$(echo "$INIT" | jq -r '.research_path // empty')
-VERIFICATION_PATH=$(echo "$INIT" | jq -r '.verification_path // empty')
-UAT_PATH=$(echo "$INIT" | jq -r '.uat_path // empty')
-CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty')
-```
+`state_path`, `roadmap_path`, `requirements_path`, `research_path`, `verification_path`, `uat_path` and `context_path` come straight from the INIT JSON; fill the `{…_path}` placeholders below with them. `state_path`, `roadmap_path` and `requirements_path` are always set, even when the file is missing; the other four are absent from the JSON when their file does not exist.
 
 ## 8. Spawn pan-planner Agent
 
@@ -351,8 +349,7 @@ Planner prompt:
 
 <files_to_read>
 - {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
+- {slice_path} (This phase's roadmap and requirements — read the whole roadmap.md or requirements.md only for something it leaves out)
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
 - {research_path} (Technical Research)
 - {verification_path} (Verification Gaps - if --gaps)
@@ -386,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}"
 )
@@ -395,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.
-- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
-- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
+- **`## 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:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -419,8 +425,7 @@ Checker prompt:
 
 <files_to_read>
 - {PHASE_DIR}/*-plan.md (Plans to verify)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
+- {slice_path} (This phase's roadmap and requirements — read the whole roadmap.md or requirements.md only for something it leaves out)
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
 - {research_path} (Technical Research — includes Validation Architecture)
 </files_to_read>
@@ -431,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
@@ -461,9 +470,9 @@ 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 (Max 3 Iterations)
+## 12. Revision Loop (At Most 2 Revisions, 3 Checks)
 
 Track `iteration_count` (starts at 1 after initial plan + check).
 
@@ -495,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"
 )
@@ -512,7 +521,7 @@ Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
 **On "Force proceed":** record that planning continues past the remaining issues. Execution and the milestone audit will see them as deferred, with this reason:
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-plan-checker --open --as deferred --reason "force proceed after 3 plan revision iterations"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-plan-checker --open --as deferred --reason "force proceed after 3 plan checks"
 ```
 
 ## 13. Present Final Status
@@ -585,7 +594,7 @@ Task(
 
     <instructions>
     1. Read exec-phase.md from execution_context for your complete workflow
-    2. Follow ALL steps: initialize, handle_branching, validate_phase, discover_and_group_plans, execute_waves, aggregate_results, close_parent_artifacts, verify_phase_goal, update_roadmap
+    2. Follow ALL steps: initialize, handle_branching, validate_phase, discover_and_group_plans, execute_waves, checkpoint_handling, aggregate_results, generate_tests, code_review, close_parent_artifacts, verify_phase_goal, update_roadmap, offer_next
     3. The --no-transition flag means: after verification + roadmap update, STOP and return status. Do NOT run transition.md.
     4. When spawning executor agents, use subagent_type='pan-executor' with the existing @file pattern from the workflow
     5. When spawning verifier agents, use subagent_type='pan-verifier'
@@ -594,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}"
 )
 ```
@@ -614,7 +624,8 @@ Task(
   Auto-advance stopped: Execution needs review.
 
   Review the output above and continue manually:
-  /pan:exec-phase ${PHASE}
+  /pan:plan-phase ${PHASE} --gaps   (verification found gaps)
+  /pan:exec-phase ${PHASE}          (execution did not finish)
   ```
 
 **If neither `--auto` nor config enabled:**

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

@@ -34,7 +34,7 @@ This creates `.planning/config.json` with defaults if missing and loads current
 Detect if this is a downgrade and confirm with user:
 
 ```
-TIER_MAP = { "quality": 3, "balanced": 2, "budget": 1 }
+TIER_MAP = { "quality": 2, "balanced": 2, "budget": 1 }   # quality and balanced resolve every agent to the same tier and effort
 current_profile = config.model_profile OR "balanced"
 new_profile = $ARGUMENTS.profile
 
@@ -86,7 +86,7 @@ Display confirmation with model table and cost estimate for selected profile:
 
 Agents will now use:
 
-[Show table from MODEL_PROFILES in pan-tools.cjs for selected profile]
+[Show table from MODEL_PROFILES in ~/.claude/pan-wizard-core/bin/lib/core.cjs for selected profile]
 
 Example (`budget` — the only profile that steps agents below the reasoning
 tier; `quality` and `balanced` put every agent on `reasoning`):

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

@@ -29,9 +29,9 @@ Exit.
 
 If missing state.md: suggest `/pan:new-project`.
 
-**If roadmap.md missing but project.md exists:**
+**If `.planning/requirements.md` is missing but roadmap.md and project.md exist:**
 
-This means a milestone was completed and archived. Go to **Route F** (between milestones).
+This means a milestone was completed and archived (`/pan:milestone-done` deletes requirements.md and keeps roadmap.md with the milestone collapsed). Go to **Route F** (between milestones).
 
 If missing both roadmap.md and project.md: suggest `/pan:new-project`.
 </step>
@@ -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
@@ -109,12 +109,10 @@ Plan [M] of [phase-total]: [status]
 CONTEXT: [✓ if has_context | - if not]
 
 ## Key Decisions Made
-- [extract from $STATE.decisions[]]
-- [e.g. jq -r '.decisions[].decision' from state-snapshot]
+- [extract from $STATE.decisions[]: each entry's summary]
 
 ## Blockers/Concerns
 - [extract from $STATE.blockers[]]
-- [e.g. jq -r '.blockers[].text' from state-snapshot]
 
 ## Pending Todos
 - [count] pending — /pan:todo-check to review
@@ -280,7 +278,7 @@ State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
 
 **Route C: Phase complete, more phases remain**
 
-Read roadmap.md to get the next phase's name and goal.
+Take the next phase's name and goal from `$ROADMAP` (`roadmap analyze` lists every phase's `name` and `goal`).
 
 ```
 ---
@@ -333,7 +331,7 @@ All {N} phases finished!
 
 ---
 
-**Route F: Between milestones (roadmap.md missing, project.md exists)**
+**Route F: Between milestones (requirements.md missing, roadmap.md and project.md exist)**
 
 A milestone was completed and archived. Ready to start the next milestone cycle.
 

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}"
 )
@@ -267,6 +267,7 @@ Execute quick task ${next_num}.
 - Commit each task atomically
 - Create summary at: ${QUICK_DIR}/${next_num}-summary.md
 - Do NOT update roadmap.md (quick tasks are separate from planned phases)
+- This is not a phase: skip `init execute-phase` and the state updates (advance-plan, update-progress, record-metric, record-session, roadmap update-plan-progress, requirements mark-complete); Step 7 of this workflow records the task in state.md
 </constraints>
 ",
   subagent_type="pan-executor",
@@ -381,7 +382,8 @@ Use `date` and `description_cell` from init. Write `description_cell` exactly as
 
 Use `date` and `description_cell` from init (one line, whatever the description held):
 ```
-Last activity: ${date} - Completed quick task ${next_num}: ${description_cell}
+**Last Activity:** ${date}
+**Last Activity Description:** Completed quick task ${next_num}: ${description_cell}
 ```
 
 Use Edit tool to make these changes atomically
@@ -449,8 +451,8 @@ Ready for next task: /pan:quick
 - [ ] User provides task description
 - [ ] `--full` flag parsed from arguments when present
 - [ ] Slug generated (lowercase, hyphens, max 40 chars)
-- [ ] Next number calculated (001, 002, 003...)
-- [ ] Directory created at `.planning/quick/NNN-slug/`
+- [ ] Next number taken from init (`next_num`: 1, 2, 3...)
+- [ ] Directory created at init's `task_dir` (`.planning/quick/{next_num}-{slug}/`)
 - [ ] `${next_num}-plan.md` created by planner
 - [ ] (--full) Plan checker validates plan, revision loop capped at 2
 - [ ] `${next_num}-summary.md` created by executor

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

@@ -102,7 +102,7 @@ Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `ren
 Stage and commit the removal:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: remove phase {target} ({original-phase-name})" --files .planning/ --force
 ```
 
 The commit message preserves the historical record of what was removed.

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

@@ -35,7 +35,12 @@ If exists: Offer update/view/skip options.
 
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
-# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path
+# Extract: phase_dir, padded_phase, phase_slug, phase_number, state_path, requirements_path, context_path
+# phase_dir is null when the phase has no directory yet: create it (scaffold pads the number and honours the planning root) and use the printed path as phase_dir
+case "{phase_dir}" in ""|null) node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw ;; esac
+
+# This phase's roadmap and requirements, written into the phase directory
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${PHASE}" --write --raw)
 ```
 
 ## Step 4: Spawn Researcher
@@ -48,7 +53,7 @@ Research implementation approach for Phase {phase}: {name}
 
 <files_to_read>
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
-- {requirements_path} (Project requirements)
+- {slice_path} (This phase's roadmap and requirements; if SLICE_PATH is empty, {requirements_path} instead)
 - {state_path} (Project decisions and history)
 </files_to_read>
 
@@ -57,7 +62,7 @@ Phase description: {description}
 </additional_context>
 
 <output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-research.md
+Write to: {phase_dir}/{padded_phase}-research.md
 </output>",
   subagent_type="pan-phase-researcher",
   model="{researcher_model}"
@@ -67,7 +72,6 @@ Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-research.md
 ## Step 5: Handle Return
 
 - `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
-- `## CHECKPOINT REACHED` — Present to user, spawn continuation
-- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
+- `## RESEARCH BLOCKED` — Display the blocker, offer: Provide context / Skip research / Abort
 
 </process>

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

@@ -252,12 +252,10 @@ Before proceeding to routed workflow, update session continuity:
 
 Update state.md:
 
-```markdown
-## Session Continuity
-
-Last session: [now]
-Stopped at: Session resumed, proceeding to [action]
-Resume file: [updated if applicable]
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state record-session \
+  --stopped-at "Session resumed, proceeding to [action]" \
+  --resume-file "[updated if applicable, else None]"
 ```
 
 This ensures if session ends unexpectedly, next resume knows the state.

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

@@ -22,6 +22,8 @@ Call pan-tools retro to gather all metrics:
 RETRO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs retro)
 ```
 
+If the user passed `--write-memory` (and `--max N`), pass them on: `pan-tools retro --write-memory [--max N]`. It is the one flag that writes, appending recurring-pattern entries to the agent logs in `.planning/memory/`, and the JSON then carries `memory.wrote`. Never add it on your own.
+
 Parse JSON for: `phases_planned`, `phases_completed`, `phases_decimal`, `estimation_accuracy_pct`, `verifications_total`, `verifications_passed_first_try`, `verifications_gaps_found`, `verifications_human_needed`, `first_try_rate_pct`, `common_gap_patterns`.
 
 **If error:** Report "No roadmap found — run /pan:new-project first."
@@ -114,7 +116,7 @@ For each top pattern, suggest a preventive action:
 </process>
 
 <constraints>
-- Read-only: this workflow does not modify any files
+- Read-only: this workflow does not modify any files, unless the user passed `--write-memory` (then `pan-tools retro` appends to the agent logs in `.planning/memory/` and nothing else changes)
 - Data-driven: all assessments backed by quantitative metrics
 - Actionable: every finding includes a concrete recommendation
 - Non-judgmental: focus on systemic patterns, not individual decisions

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

@@ -24,7 +24,7 @@ Creates `.planning/config.json` with defaults if missing and loads current confi
 cat .planning/config.json
 ```
 
-Parse current values (default to `true` if not present):
+Parse current values (when a key is absent, use PAN's default: `true` for research, plan_check and verifier; `false` for nyquist_validation):
 - `workflow.research` — spawn researcher during plan-phase
 - `workflow.plan_check` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
@@ -110,7 +110,7 @@ AskUserQuestion([
     multiSelect: false,
     options: [
       { label: "Static (Recommended)", description: "Profile assigns fixed tiers to each agent. Predictable and simple." },
-      { label: "Complexity", description: "Adjust tiers up/down based on task complexity (file count, requirements, architecture). Saves tokens on simple phases." }
+      { label: "Complexity", description: "Adjust tiers by task complexity, only where a model is resolved with the task passed (resolve-model --metadata); the *_model values workflows pass are not, so it changes nothing there" }
     ]
   }
 ])
@@ -118,27 +118,18 @@ AskUserQuestion([
 </step>
 
 <step name="update_config">
-Merge new settings into existing config.json:
+Write each answer with `config-set`, which keeps every other key in the `workflow` and `routing` objects:
 
-```json
-{
-  ...existing_config,
-  "model_profile": "quality" | "balanced" | "budget",
-  "workflow": {
-    "research": true/false,
-    "plan_check": true/false,
-    "verifier": true/false,
-    "auto_advance": true/false,
-    "nyquist_validation": true/false
-  },
-  "branching_strategy": "none" | "phase" | "milestone",
-  "routing": {
-    "strategy": "static" | "complexity"
-  }
-}
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set model_profile <quality|balanced|budget>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.plan_check <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.verifier <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.nyquist_validation <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set branching_strategy <none|phase|milestone>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set routing.strategy <static|complexity>
 ```
-
-Write updated config to `.planning/config.json`.
 </step>
 
 <step name="save_as_defaults">
@@ -179,7 +170,8 @@ Write `~/.pan-wizard/defaults.json` with:
     "verifier": <current>,
     "auto_advance": <current>,
     "nyquist_validation": <current>
-  }
+  },
+  "routing": { "strategy": <current> }
 }
 ```
 </step>
@@ -218,8 +210,8 @@ Quick commands:
 
 <success_criteria>
 - [ ] Current config read
-- [ ] User presented with 7 settings (profile + 5 workflow toggles + git branching)
-- [ ] Config updated with model_profile, workflow, and git sections
+- [ ] User presented with the settings above (model profile, workflow toggles, git branching, routing strategy)
+- [ ] Config updated with model_profile, workflow, branching_strategy and routing
 - [ ] User offered to save as global defaults (~/.pan-wizard/defaults.json)
 - [ ] Changes confirmed to user
 </success_criteria>

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>
@@ -127,7 +128,7 @@ Use AskUserQuestion:
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs todo complete "[filename]"
 ```
-This moves it to `.planning/todos/completed/` with a `completed:` date — the directory `init todos` and `/pan:progress` count.
+This moves it out of `.planning/todos/pending/` (the directory `init todos` and `/pan:progress` count) into `.planning/todos/completed/` with a `completed:` date.
 Update state.md todo count. Present problem/solution context. Begin work or ask how to proceed.
 
 **Add to phase plan:**