pan-wizard 3.35.0 → 3.37.0

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

@@ -2,6 +2,8 @@
 Execute small, ad-hoc tasks with PAN guarantees (atomic commits, state.md tracking). Quick mode spawns pan-planner (quick mode) + pan-executor(s), tracks tasks in `.planning/quick/`, and updates state.md's "Quick Tasks Completed" table.
 
 With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony.
+
+Without `--full`, a task whose description already says precisely what to build takes the lean path: the engine writes its one-task plan (`pan-tools size quick-plan`) and no planner runs. `--quality`, the `quality` profile or `workflow.ceremony: full` keep the planner.
 </purpose>
 
 <required_reading>
@@ -13,6 +15,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 Parse `$ARGUMENTS` for:
 - `--full` flag → store as `$FULL_MODE` (true/false)
+- `--quality` flag → store as `$QUALITY` (true/false): the full ceremony for this run
 - Remaining text → use as `$DESCRIPTION` if non-empty
 
 If `$DESCRIPTION` is empty after parsing, prompt user interactively:
@@ -50,6 +53,14 @@ Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_mo
 
 **If `roadmap_exists` is false:** Error — Quick mode requires an active project with roadmap.md. Run `/pan:new-project` first.
 
+**Size the ceremony** (pass `--full` and `--quality` through when set):
+
+```bash
+SIZING=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size task "$DESCRIPTION" [--full] [--quality])
+```
+
+`SIZING.path` is `lean` (the description names what to build and how to check it) or `full`; `SIZING.mode` is `auto` or `full`. Show it in one line: `Ceremony: {path} ({reasons joined by "; "})`.
+
 Quick tasks can run mid-phase - validation only checks roadmap.md exists, not phase status.
 
 **Circular optimization — ensure trace session active:**
@@ -90,6 +101,16 @@ Store `$QUICK_DIR` for use in orchestration.
 
 **Step 5: Spawn planner (quick mode)**
 
+**If `SIZING.path` is `lean`:** the engine writes the plan and no planner runs:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size quick-plan --out "${QUICK_DIR}/${next_num}-plan.md" --num "${next_num}" "$DESCRIPTION"
+```
+
+Report `Plan written by the engine (lean path): ${QUICK_DIR}/${next_num}-plan.md` and go to Step 6.
+
+**Otherwise**, spawn the planner:
+
 **If `$FULL_MODE`:** Use `quick-full` mode with stricter constraints.
 
 **If NOT `$FULL_MODE`:** Use standard `quick` mode.
@@ -168,6 +189,11 @@ Checker prompt:
 **Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal.
 </verification_context>
 
+<output_budget>
+{Only when SIZING.mode is auto, include:}
+Report the verdict and the blocking issues only: one line per issue (task, what is wrong, the fix), at most 200 words before the pan-verdict block. No summary of what passed.
+</output_budget>
+
 <check_dimensions>
 - Requirement coverage: Does the plan address the task description?
 - Task completeness: Do tasks have files, action, verify, done fields?
@@ -336,57 +362,22 @@ Store as `$VERIFICATION_STATUS`.
 
 **Step 7: Update state.md**
 
-Update state.md with quick task completion record.
-
-**7a. Check if "Quick Tasks Completed" section exists:**
-
-Read state.md and check for `### Quick Tasks Completed` section.
-
-**7b. If section doesn't exist, create it:**
-
-Insert after `### Blockers/Concerns` section:
+Record the task through the engine. It creates the "### Quick Tasks Completed" table after "### Blockers/Concerns" when it is missing, numbers the row, and keeps an existing table's columns. Pass `description_cell` exactly as init returned it, never `$DESCRIPTION`: init escapes `|` and folds line breaks, and a raw `|` would split the row.
 
 **If `$FULL_MODE`:**
-```markdown
-### Quick Tasks Completed
-
-| # | Description | Date | Commit | Status | Directory |
-|---|-------------|------|--------|--------|-----------|
-```
-
-**If NOT `$FULL_MODE`:**
-```markdown
-### Quick Tasks Completed
-
-| # | Description | Date | Commit | Directory |
-|---|-------------|------|--------|-----------|
-```
-
-**Note:** If the table already exists, match its existing column format. If adding `--full` to a project that already has quick tasks without a Status column, add the Status column to the header and separator rows, and leave Status empty for the new row's predecessors.
-
-**7c. Append new row to table:**
-
-Use `date` and `description_cell` from init. Write `description_cell` exactly as init returned it, never `$DESCRIPTION`: init escapes `|` and folds line breaks, and a raw `|` in a description would split the row into an extra column and break the table for every later read.
-
-**If `$FULL_MODE` (or table has Status column):**
-```markdown
-| ${next_num} | ${description_cell} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state quick-task --description "${description_cell}" --date "${date}" --commit "${commit_hash}" --status "${VERIFICATION_STATUS}" --directory "[${next_num}-${slug}](./quick/${next_num}-${slug}/)"
 ```
 
-**If NOT `$FULL_MODE` (and table has no Status column):**
-```markdown
-| ${next_num} | ${description_cell} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
-```
+**If NOT `$FULL_MODE`:** the same without `--status`.
 
-**7d. Update "Last activity" line:**
+Then the activity line:
 
-Use `date` and `description_cell` from init (one line, whatever the description held):
-```
-**Last Activity:** ${date}
-**Last Activity Description:** Completed quick task ${next_num}: ${description_cell}
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state patch --"Last Activity" "${date}" --"Last Activity Description" "Completed quick task ${next_num}: ${description_cell}"
 ```
 
-Use Edit tool to make these changes atomically
+Never edit state.md with the Edit tool (under `hooks.guard: enforce` the guard denies it).
 
 ---
 

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

@@ -72,6 +72,8 @@ This will:
 Proceed? (y/n)
 ```
 
+If an integer target has decimal phases inserted after it (`### Phase {target}.1:` and so on in roadmap.md, or `{target}.N-*` directories), name them in the summary and ask whether to remove them too. pan-tools refuses to remove the integer phase while they exist, because they would be left behind under a different phase's number.
+
 Wait for confirmation.
 </step>
 
@@ -88,6 +90,14 @@ If the phase has executed plans (summary.md files), pan-tools will error. Use `-
 RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase remove "${target}" --force)
 ```
 
+If the phase has decimal phases, pan-tools errors and names them. Add `--with-decimals` only if the user confirmed removing them as well (each is checked for executed plans the same way, so `--force` still applies to them):
+
+```bash
+RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase remove "${target}" --with-decimals)
+```
+
+Otherwise stop and report the decimals; the user can remove them one by one first.
+
 The CLI handles:
 - Deleting the phase directory
 - Renumbering all subsequent directories (in reverse order to avoid conflicts)
@@ -95,7 +105,7 @@ The CLI handles:
 - Updating roadmap.md (removing section, renumbering all phase references, updating dependencies)
 - Updating state.md (decrementing phase count)
 
-Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
+Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`, and `removed_decimals` when `--with-decimals` removed any.
 </step>
 
 <step name="commit">

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

@@ -1,77 +1,155 @@
-<purpose>
-Research how to implement a phase. Spawns pan-phase-researcher with phase context.
+<objective>
+Answer the open questions that block planning a phase (at most 5). Spawns one pan-phase-researcher agent with the questions and the phase context.
 
-Standalone research command. For most workflows, use `/pan:plan-phase` which integrates research automatically.
-</purpose>
+**Note:** This is the standalone research mode. `/pan:plan-phase` researches only with `--research` or `workflow.research: true`.
 
-<process>
+**Use this command when:**
+- You want to research without planning yet
+- You want to re-research after planning is complete
+- You need to investigate before deciding if a phase is feasible
+
+**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
 
-## Step 0: Resolve Model Profile
+**Why subagent:** Searching burns context. A fresh context window answers the questions, at most 4 searches or fetches each; the main context stays lean for user interaction.
+</objective>
 
-@~/.claude/pan-wizard-core/references/model-profile-resolution.md
+<context>
+Phase number: $ARGUMENTS (required)
 
-Resolve model for:
-- `pan-phase-researcher`
+Normalize phase input in step 1 before any directory lookups.
+</context>
 
-## Step 1: Normalize and Validate Phase
+<process>
 
-@~/.claude/pan-wizard-core/references/phase-argument-parsing.md
+## 0. Initialize Context
 
 ```bash
-PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}")
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "$ARGUMENTS")
 ```
 
-If `found` is false: Error and exit.
+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.
 
-## Step 2: Check Existing Research
+Resolve researcher model:
+```bash
+RESEARCHER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-phase-researcher --raw)
+```
+
+## 1. Validate Phase
 
 ```bash
-ls .planning/phases/*/*-research.md 2>/dev/null | grep -E "/0*${PHASE}-[^/]*/"
+PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}")
 ```
 
-If exists: Offer update/view/skip options.
+**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
-## Step 3: Gather Phase Context
+## 2. Check Existing Research
 
-```bash
-INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
-# 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
+Use `has_research` and `research_path` from INIT.
+
+**If exists:** Offer: 1) Update research, 2) View existing (`research_path`), 3) Skip. Wait for response.
+
+**If doesn't exist:** Continue.
+
+## 3. Gather Phase Context
 
-# 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)
+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`
+
+Present summary with phase description and what files the researcher will load.
+
+## 4. Write the Questions and Spawn pan-phase-researcher
 
-## Step 4: Spawn Researcher
+Research answers questions; it does not survey the phase's domain. List at most **5** open questions the phase's requirements leave unanswered and that block building (a technology choice, an external API's behaviour, a data format, a limit or rule), as a numbered list in `{phase_dir}/{padded_phase}-research-questions.md`:
 
+```markdown
+# Phase {phase_number} research questions
+
+1. [question] — blocks: [the task or decision it settles]
 ```
-Task(
-  prompt="<objective>
-Research implementation approach for Phase {phase}: {name}
+
+**No questions → no research.** If nothing blocks building, write no file, say `No open questions block Phase {phase_number} — research skipped`, and stop.
+
+```markdown
+<objective>
+Answer the research questions for Phase {phase_number}: {phase_name}, and nothing else.
 </objective>
 
 <files_to_read>
-- {context_path} (USER DECISIONS from /pan:discuss-phase)
-- {slice_path} (This phase's roadmap and requirements; if SLICE_PATH is empty, {requirements_path} instead)
-- {state_path} (Project decisions and history)
+- {phase_dir}/{padded_phase}-research-questions.md (The questions)
+- {slice_path} (This phase's roadmap and requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
 </files_to_read>
 
-<additional_context>
-Phase description: {description}
-</additional_context>
-
 <output>
 Write to: {phase_dir}/{padded_phase}-research.md
-</output>",
+One row per question: | # | Question | Answer | Source | Confidence | Decision it settles |, or `unknown — assume: …`. At most 4 searches or fetches per question. Anything that suggests new scope goes under ## Ideas (v2 candidates).
+</output>
+```
+
+```
+Task(
+  prompt=filled_prompt,
   subagent_type="pan-phase-researcher",
-  model="{researcher_model}"
+  model="{researcher_model}",
+  description="Research Phase {phase}"
 )
 ```
 
-## Step 5: Handle Return
+Then check the answers:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research check "{phase_dir}/{padded_phase}-research-questions.md" "{phase_dir}/{padded_phase}-research.md"
+```
+
+Exit 1: send its `errors` to the researcher once as a revision. One revision at most; then proceed, with each question still unsourced recorded under `## Unknowns` in the research file with the assumption the plan uses.
+
+## 5. Handle Agent Return
+
+**`## RESEARCH COMPLETE`:** Display the decisions it settled and any unknowns, offer: Plan phase, Review full, Done.
+
+**`## 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
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+<files_to_read>
+- {phase_dir}/{padded_phase}-research.md (Existing research)
+</files_to_read>
+</prior_state>
 
-- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
-- `## RESEARCH BLOCKED` — Display the blocker, offer: Provide context / Skip research / Abort
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="pan-phase-researcher",
+  model="{researcher_model}",
+  description="Continue research Phase {phase}"
+)
+```
 
 </process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing research checked
+- [ ] At most 5 questions written (none: no research)
+- [ ] One pan-phase-researcher spawned with the questions
+- [ ] `research check` run, one revision at most
+- [ ] Checkpoints handled correctly
+- [ ] User knows next steps
+</success_criteria>

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

@@ -138,6 +138,16 @@ Present complete project status to user:
 </step>
 
 <step name="determine_next_action">
+An interrupted agent or a `.continue-here` checkpoint comes first (below). Otherwise ask the router:
+
+```bash
+NEXT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs next-action)
+```
+
+It returns `{action, phase, reason, command}`, read from roadmap.md and the phase directories by the same state machine the MCP `pan_next_action` tool uses, so progress, resume and transition never disagree about what comes next. `action` is one of `plan`, `execute`, `verify`, `complete_phase`, `plan_gaps`, `audit_milestone`, `new_milestone`, `new_project` or `stop`, and `command` is the command that carries it out.
+
+Offer its `command` as the primary option.
+
 Based on project state, determine the most logical next action:
 
 **If interrupted agent exists:**
@@ -237,7 +247,7 @@ Based on user selection, route to appropriate workflow:
 
   **Also available:**
   - `/pan:discuss-phase [N]` — gather context first
-  - `/pan:research-phase [N]` — investigate unknowns
+  - `/pan:plan-phase --research-only [N]` — investigate unknowns
 
   ---
   ```
@@ -274,7 +284,13 @@ If state.md is missing but other artifacts exist:
 4. Count pending todos in .planning/todos/pending/
 5. Check for .continue-here files → Session continuity
 
-Reconstruct and write state.md, then proceed normally.
+Reconstruct state.md through the engine, never with the Write tool:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state init --core-value "<from project.md>" --focus "<current phase name>" --phase <current phase> --phase-name "<its name>" --total-phases <N> --activity "Reconstructed from artifacts"
+```
+
+Then add what the summaries and todos hold, one section at a time: `state section "Decisions" --append "- [Phase X]: ..."`, `state section "Blockers/Concerns" --append "..."`, `state section "Pending Todos" --set "<N> pending"`. Proceed normally.
 
 This handles cases where:
 

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

@@ -24,13 +24,14 @@ Creates `.planning/config.json` with defaults if missing and loads current confi
 cat .planning/config.json
 ```
 
-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
+Parse current values (when a key is absent, use PAN's default: `false` for research and nyquist_validation; `true` for plan_check and verifier):
+- `workflow.research` — spawn researcher during plan-phase (off by default: research is opt-in, and when on it answers at most 5 open questions per phase)
 - `workflow.plan_check` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
 - `workflow.nyquist_validation` — validation architecture research during plan-phase
-- `model_profile` — which model each agent uses (default: `balanced`)
-- `routing.strategy` — how model tiers are adjusted at runtime (default: `static`)
+- `model_profile` — how much ceremony and which model each agent uses (default: `balanced`; `quality` keeps the full ceremony everywhere)
+- `routing.strategy` — not asked here (default: `static`). The `complexity` strategy reaches no workflow, so offering it would be a choice that changes nothing; `config-set routing.strategy complexity` still sets it for `resolve-model --metadata` callers. A `quality` profile in an existing config keeps working: it is identical to `balanced`
+- `cost.phase_budget_usd` — spend per phase PAN warns about, in API-equivalent dollars (default: `20`; `0` = off). It never stops a run
 - `branching_strategy` — branching approach (default: `"none"`; a top-level key — a nested `git.branching_strategy` is ignored when the top-level key exists, as it does in every config `config-ensure-section` creates — write the top-level key)
 </step>
 
@@ -44,18 +45,18 @@ AskUserQuestion([
     header: "Model",
     multiSelect: false,
     options: [
-      { label: "Quality", description: "reasoning tier for every agent — identical to balanced, so switching between the two changes nothing" },
-      { label: "Balanced (Recommended)", description: "reasoning tier for every agent (quality and balanced are identical post-COST-RESET); use budget to step down" },
-      { label: "Budget", description: "mid tier for writing, fast tier for research/verification (lowest cost)" }
+      { label: "Balanced (Recommended)", description: "right-sized: a small, well-specified phase or quick task skips research and the planner/checker loop; plan-checker and researchers on the mid tier; one plan revision" },
+      { label: "Quality", description: "the full ceremony on every piece of work, every agent on the reasoning tier (the behaviour before right-sizing; costs several times more)" },
+      { label: "Budget", description: "right-sized like balanced, plus mid tier for writing and fast tier for research/verification (lowest cost)" }
     ]
   },
   {
-    question: "Spawn Plan Researcher? (researches domain before planning)",
+    question: "Spawn Plan Researcher? (off by default; answers up to 5 open questions before planning)",
     header: "Research",
     multiSelect: false,
     options: [
-      { label: "Yes", description: "Research phase goals before planning" },
-      { label: "No", description: "Skip research, plan directly" }
+      { label: "No (default)", description: "Plan directly from requirements; /pan:plan-phase N --research researches one phase" },
+      { label: "Yes", description: "Before each phase, answer up to 5 open questions that block building, each with a source" }
     ]
   },
   {
@@ -75,7 +76,14 @@ AskUserQuestion([
       { label: "Yes", description: "Verify must-haves after execution" },
       { label: "No", description: "Skip post-execution verification" }
     ]
-  },
+  }
+])
+```
+
+Then the next batch (the host takes at most four questions per call):
+
+```
+AskUserQuestion([
   {
     question: "Auto-advance pipeline? (discuss → plan → execute automatically)",
     header: "Auto",
@@ -105,30 +113,35 @@ AskUserQuestion([
     ]
   },
   {
-    question: "Model routing strategy?",
-    header: "Routing",
+    question: "Warn when a phase's spend passes how much? (API-equivalent dollars; warns only, never stops)",
+    header: "Phase budget",
     multiSelect: false,
     options: [
-      { label: "Static (Recommended)", description: "Profile assigns fixed tiers to each agent. Predictable and simple." },
-      { 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" }
+      { label: "$20 per phase (Recommended)", description: "Warn at $16 (80%) and again once a phase passes $20" },
+      { label: "$50 per phase", description: "For larger phases or the quality profile" },
+      { label: "$10 per phase", description: "For small phases or the budget profile" },
+      { label: "Off", description: "No spend warnings; /pan:cost still reports spend" }
     ]
   }
 ])
 ```
+
+A dollar amount typed under Other is used as given.
+```
 </step>
 
 <step name="update_config">
 Write each answer with `config-set`, which keeps every other key in the `workflow` and `routing` objects:
 
 ```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 model_profile <balanced|quality|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>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set cost.phase_budget_usd <20|50|10|0|amount>
 ```
 </step>
 
@@ -194,13 +207,14 @@ Display:
 | Nyquist Validation   | {On/Off} |
 | Git Branching        | {None/Per Phase/Per Milestone} |
 | Routing Strategy     | {Static/Complexity} |
+| Phase Budget         | {$N per phase (warn only)/Off} |
 | Saved as Defaults    | {Yes/No} |
 
 These settings apply to future /pan:plan-phase and /pan:exec-phase runs.
 
 Quick commands:
-- /pan:profile <profile> — switch model profile
-- /pan:plan-phase --research — force research
+- /pan:settings --profile <profile> — switch model profile
+- /pan:plan-phase --research — research one phase (up to 5 open questions)
 - /pan:plan-phase --skip-research — skip research
 - /pan:plan-phase --skip-verify — skip plan check
 ```

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

@@ -129,7 +129,7 @@ Use AskUserQuestion:
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs todo complete "[filename]"
 ```
 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.
+Update the todo count in state.md (the `update_state` step). Present problem/solution context. Begin work or ask how to proceed.
 
 **Add to phase plan:**
 Note todo reference in phase planning notes. Keep in pending. Return to list or exit.
@@ -148,7 +148,11 @@ Return to list_todos step.
 <step name="update_state">
 After any action that changes todo count:
 
-Re-run `init todos` to get updated count, then update state.md "### Pending Todos" section if exists.
+Re-run `init todos` to get the updated count, then set state.md's "### Pending Todos" section through the engine:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state section "Pending Todos" --set "{count} pending — /pan:todo-check to review"
+```
 </step>
 
 <step name="git_commit">

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

@@ -25,7 +25,7 @@ Mark current phase complete and advance to next. This is the natural point where
 **Required pattern from v3.7.5 onward:**
 
 1. Run the steps below to *plan* each state.md update, but **do not write or commit** between them. Hold the changes in memory.
-2. After `update_session_continuity_after_transition` (the last state.md-touching step before `offer_next_phase`), perform a **single Edit** that applies all four section updates (Project Reference, Accumulated Context, Session Continuity, plus the progress bar from `update_current_position_after_transition`).
+2. After `update_session_continuity_after_transition` (the last state.md-touching step before `offer_next_phase`), make a **single `pan-tools state apply` call** that applies all four section updates in one write (Project Reference, Accumulated Context, Session Continuity, plus the progress bar from `update_current_position_after_transition`).
 3. Then issue **one** commit:
    ```bash
    node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(transition): phase ${current_phase} → ${next_phase} (state, progress, context)"
@@ -34,6 +34,14 @@ Mark current phase complete and advance to next. This is the natural point where
 
 Net result per transition: 2 commits instead of 5. Reduces git noise and keeps `/pan:learn` overhead metrics (commits_per_minute) honest. Substantive content of each step below is unchanged — only the **timing of the write** changes.
 
+The batched call, with the values the steps below planned (fields are bold `**Name:**` lines; a section is appended to or replaced):
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state apply --json '{"fields": {"Progress": "<bar from progress bar --raw>", "Current focus": "<next phase name>", "Core value": "<current core value>", "Last session": "<YYYY-MM-DD HH:MM>", "Resume File": "None"}, "sections": {"Decisions": {"append": ["- [Phase X]: <decision>"]}, "Blockers/Concerns": {"set": "<the reviewed list>"}}}'
+```
+
+It reports any field it could not find in `failed`. Never edit state.md with the Edit tool: the engine keeps the frontmatter in sync, and under `hooks.guard: enforce` the guard denies a direct write.
+
 </state_write_policy>
 
 <process>
@@ -355,7 +363,7 @@ Update Session Continuity section in state.md to reflect transition completion.
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Stopped at" "Phase ${current_phase} complete, ready to plan Phase ${next_phase}"
 ```
 
-Then Edit state.md (still under the P-1604 batched-write policy — fold this Edit into the final batched Edit at the end of the workflow):
+Then fold the other two lines into the batched `state apply` call at the end of the workflow (P-1604):
 
 **Format:**
 
@@ -387,6 +395,16 @@ The `is_last_phase` field from the phase complete result tells you directly:
 
 The `next_phase` and `next_phase_name` fields give you the next phase details.
 
+To name the next command, ask the router after `phase complete`:
+
+```bash
+NEXT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs next-action)
+```
+
+It returns `{action, phase, reason, command}`, read from roadmap.md and the phase directories by the same state machine the MCP `pan_next_action` tool uses, so progress, resume and transition never disagree about what comes next. `action` is one of `plan`, `execute`, `verify`, `complete_phase`, `plan_gaps`, `audit_milestone`, `new_milestone`, `new_project` or `stop`, and `command` is the command that carries it out.
+
+For the next phase it returns `plan` (or `execute` when the phase is already planned); at the milestone boundary it returns `audit_milestone`.
+
 If you need additional context, use:
 ```bash
 ROADMAP=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap analyze)
@@ -530,7 +548,7 @@ Task(
 
 **Also available:**
 - `/pan:plan-phase [X+1]` — skip discussion, plan directly
-- `/pan:research-phase [X+1]` — investigate unknowns
+- `/pan:plan-phase --research-only [X+1]` — investigate unknowns
 
 ---
 ```
@@ -555,7 +573,7 @@ Task(
 
 **Also available:**
 - `/pan:discuss-phase [X+1]` — revisit context
-- `/pan:research-phase [X+1]` — investigate unknowns
+- `/pan:plan-phase --research-only [X+1]` — investigate unknowns
 
 ---
 ```