pan-wizard 3.36.0 → 3.37.0

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

@@ -1,4 +1,106 @@
-# Workflow: /pan:optimize
+<usage>
+# /pan:learn --optimize
+
+Manage the circular optimization loop: record a report's suggestions, view stats, list reports.
+
+**Usage:**
+```
+/pan:learn --optimize apply
+/pan:learn --optimize apply --report <filename>
+/pan:learn --optimize revert <apply_id>
+/pan:learn --optimize revert --last
+/pan:learn --optimize list
+/pan:learn --optimize stats
+/pan:learn --optimize trace init [--description "what you're building"]
+/pan:learn --optimize trace end
+/pan:learn --optimize trace current
+/pan:learn --optimize trace list
+```
+
+**Subcommands:**
+
+### apply
+Record the suggestions from the most recent (or specified) optimization report.
+
+Recorded automatically:
+- Suggestions appended to `.planning/optimization/suggestions.md`: lessons, prompt changes and workflow changes, each naming where it belongs
+- Config notes appended to `.planning/optimization/config-suggestions.md`
+- An older report's memory actions (`memory_entry`, `memory`, `memory_append`) still write to `.planning/memory/`, a `memory_entry` only if it passes the checks of the `memory record` command. The result warns that PAN's workflows do not load that folder into agents
+
+A person makes every change the suggestions describe (never auto-applied):
+- Lessons, written into the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
+- Agent prompt changes
+- Workflow step additions
+- Structural changes to commands
+
+After applying, the report lists what was applied and what still needs review, plus the `apply_id` that undoes it. Every apply is recorded action by action in `.planning/optimization/applied.jsonl`: the path, whether the file was created or appended to, the exact text, and a hash of the file after the write. Applying the same report a second time writes nothing: each action names the apply that already wrote it.
+
+### revert
+Undo one apply exactly: delete the files it created and cut the text it appended (`revert --last` for the newest).
+
+Revert never destroys work someone did since:
+- It refuses a file whose content changed after the apply. The comparison ignores line endings, so a CRLF checkout still matches.
+- It refuses a file that a later apply also wrote. Revert that later apply first.
+- It says which files it refused, and why.
+
+A CRLF file comes back CRLF. Applies logged before apply records existed cannot be reverted. After a revert, the same report can be applied again.
+
+### list
+List all optimization reports in `.planning/optimization/reports/`, most recent first.
+
+### stats
+Show cumulative optimization statistics:
+- Total trace sessions run
+- Total events traced
+- Total errors seen (`total_errors_traced`; gaps and redundancies are not totalled)
+- Total optimizations applied across all runs, the apply runs, the reverted runs, and the last `apply_id`
+- Current active trace session (if any)
+
+### trace init
+Start a trace session before running a build — or join the active one: `trace init` reuses an unended session started within the last hour (`reused: true`, keeping that session's description) instead of opening a new one. The hook fires automatically on SubagentStop, but calling `trace init` first lets you attach a description to a new session.
+
+```
+/pan:learn --optimize trace init --description "building express web server"
+/pan:exec-phase 1
+/pan:learn
+```
+
+### trace end
+Finalize the current trace session (writes summary stats to session.json).
+
+### trace current
+Show the active trace session ID (`optimize trace current` returns only `session_id` and `active`; `trace list` carries each session's event count).
+
+### trace list
+List all trace sessions, most recent first.
+
+---
+
+**The circular loop:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│                                                     │
+│  /pan:learn --optimize trace init                           │
+│         ↓                                          │
+│  /pan:exec-phase N    ← agents run, hook traces    │
+│         ↓                                          │
+│  /pan:learn           ← analyze + report           │
+│         ↓                                          │
+│  /pan:learn --optimize apply  ← record suggestions         │
+│         ↓                                          │
+│  You make the changes ← instructions, tests, code  │
+│         ↑                                          │
+│         └──────────────────────────────────────────┘
+└─────────────────────────────────────────────────────┘
+```
+
+Each iteration puts what the last run lacked where the next run's agents read it: fewer repeated errors and gaps.
+
+**See also:** `/pan:learn`, `/pan:exec-phase`
+</usage>
+
+# Workflow: /pan:learn --optimize
 
 Manage the circular optimization loop — apply reports, check stats, control trace sessions.
 
@@ -43,7 +145,7 @@ Show the user:
 - **Applied** — each item that was recorded (suggestions, config notes)
 - **Skipped** — items that already exist, that an earlier apply already wrote, or that had unknown types
 - **Still needs a person** — every suggestion in `suggestions.md`
-- **The `apply_id`**, and how to undo the apply: `/pan:optimize revert <apply_id>`
+- **The `apply_id`**, and how to undo the apply: `/pan:learn --optimize revert <apply_id>`
 
 If an applied item carries a `warning`, pass it on. An older report's memory actions write to `.planning/memory/`, which PAN's workflows do not load into agents.
 
@@ -82,7 +184,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init [--descript
 Show the user the session ID and confirm that:
 - The hook will automatically log agent completions to this session
 - To log a specific decision/error manually: `pan-tools optimize trace log --type <type> --description "..."` 
-- To end the session explicitly: `/pan:optimize trace end`
+- To end the session explicitly: `/pan:learn --optimize trace end`
 
 ---
 
@@ -103,7 +205,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
 ```
 
 If active: show session ID and instruct how to view events.
-If none: tell user to run `/pan:optimize trace init` before their next build.
+If none: tell user to run `/pan:learn --optimize trace init` before their next build.
 
 ---
 
@@ -142,7 +244,7 @@ Every agent spawn → hook logs completion event
                           ↓
               .planning/optimization/reports/{session}-opt-report.md
                           ↓
-             /pan:optimize apply → records suggestions
+             /pan:learn --optimize apply → records suggestions
                           ↓
      A person writes each one where the agents read it
                           ↓

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

@@ -370,6 +370,16 @@ Present next steps:
 ```
 </step>
 
+<step name="prove_red">
+Prove the tests you wrote test what the phase built. Each changed test file runs on its own at the phase's base, where it must fail, and at HEAD, where it must pass:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify red "${PHASE_ARG}"
+```
+
+A `not_red` test passes without the phase's code: rewrite it to assert the new behaviour, or drop it. Report the result with the test plan.
+</step>
+
 </process>
 
 <success_criteria>

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 (at most 2 revisions, up to 3 checks).
+Create executable phase prompts (plan.md files) for a roadmap phase with verification, and research only when asked for. Default flow: Plan -> Verify -> Done; research (opt-in: `--research` or `workflow.research: true`) answers at most five blocking questions first. 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>
@@ -48,6 +48,18 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 **If `planning_exists` is false:** Error — run `/pan:new-project` first.
 
+**Size the ceremony** (the engine decides; pass `--quality` or `--full` through when `$ARGUMENTS` has them):
+
+```bash
+SIZING=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size phase "$PHASE" [--quality] [--full])
+```
+
+`SIZING.path` is `lean` or `full`, and `SIZING.mode` is `auto` or `full`. Show it in one line: `Ceremony: {path} ({reasons joined by "; "})`.
+
+- **`lean`** (a small phase whose requirements say precisely what to build): no research (step 5), and the engine plans the phase (step 8: one task per requirement, checked and recorded in code). A planner and the plan-checker run only if the engine declines.
+- **`full`**: the whole path below.
+- **`mode` `auto`** (any profile but `quality`, and `workflow.ceremony` not `full`): the plan-checker gets an output budget (step 10) and the revision loop stops after one revision (step 12). **`mode` `full`** keeps the unbudgeted checker and two revisions.
+
 **Circular optimization — ensure trace session active:**
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
@@ -57,7 +69,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`, `--quality`, `--full`). `--quality` and `--full` force the full ceremony for this run (`size phase` above).
 
 Extract `--prd <filepath>` from $ARGUMENTS. If present, set PRD_FILE to the filepath.
 
@@ -202,7 +214,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
 
 2. Display: `Auto-mode: no Phase ${PHASE} context.md — planning from project-level research + requirements + idea.md`
 
-3. Proceed to step 5 (Handle Research). The `pan-planner` agent reads project-level `.planning/research/architecture.md`, `features.md`, `stack.md` and the original `.planning/idea.md` to derive phase-scoped decisions itself.
+3. Proceed to step 5 (Handle Research). The `pan-planner` agent reads the project-level answers (`.planning/research/research-summary.md`, when research ran) and the original `.planning/idea.md` to derive phase-scoped decisions itself.
 
 **Interactive-mode decision tree (the original behavior; runs when neither `--auto` nor `workflow.auto_advance` is set):**
 
@@ -218,63 +230,55 @@ If "Run discuss-phase first": Display `/pan:discuss-phase {X}` and exit workflow
 
 ## 5. Handle Research
 
-**Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override.
+Research is **opt-in**: it runs only with `--research`, or when `research_enabled` (from init: `workflow.research`, false by default) is true. When it runs it answers at most five questions with one researcher and settles decisions; it never adds scope to the phase.
 
-**P-1401 lightweight-phase bypass (v3.7.3+):** Also skip per-phase research when ALL three are true:
+**Skip if:** `--gaps` flag, `--skip-research` flag, `research_enabled` is false without `--research`, or `SIZING.path` is `lean` (the requirements already say what to build) without `--research`.
 
-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)
+**P-1401 lightweight-phase bypass (v3.7.3+):** With `research_enabled` true but no `--research`, also skip when 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) and it is scaffolding, config, docs or a single-file feature with ≤3 tasks (judge from its goal). Log a `decision` trace event (`type: "decision", category: "skip-research-trivial"`) and proceed to step 6.
 
-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.
+**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. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`.
 
-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.
+**If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
-**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.
+**Otherwise:**
 
-**If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
+**5a. Write the questions.** Read `{slice_path}` (and `{context_path}` when it exists) and 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. A question qualifies only if a task cannot be written without its answer; a decision context.md already locks is not open. If `.planning/research/research-summary.md` already answers one, it is not open either.
 
-**If research.md missing OR `--research` flag:**
+Write `{phase_dir}/{padded_phase}-research-questions.md` as a numbered list:
 
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PAN ► RESEARCHING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```markdown
+# Phase {X} research questions
 
-◆ Spawning researcher...
+1. [question] — blocks: [the task or decision it settles]
 ```
 
-### Spawn pan-phase-researcher
+**No questions → no research.** If nothing blocks building, write no file, display `No open questions block Phase {X} — research skipped`, and continue to step 6.
+
+**5b. Spawn one researcher.**
 
-```bash
-PHASE_DESC=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw)   # --raw prints the phase's section
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PAN ► RESEARCHING PHASE {X} ({N} QUESTIONS)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Research prompt:
 
 ```markdown
 <objective>
-Research how to implement Phase {phase_number}: {phase_name}
-Answer: "What do I need to know to PLAN this phase well?"
+Answer the research questions for Phase {phase_number}: {phase_name}, and nothing else.
 </objective>
 
 <files_to_read>
+- {phase_dir}/{padded_phase}-research-questions.md (The questions)
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
+- {assumptions_path} (the user's corrections to /pan:assumptions, when the file exists: `init` reports `assumptions_path`; each correction binds the plan like a decision)
 - {slice_path} (This phase's roadmap and requirements)
-- {state_path} (Project decisions and history)
 </files_to_read>
 
-<additional_context>
-**Phase description:** {phase_description}
-**Phase requirement IDs (MUST address):** {phase_req_ids}
-
-**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
-**Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, research should account for project skill patterns
-</additional_context>
-
 <output>
 Write to: {phase_dir}/{padded_phase}-research.md
+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>
 ```
 
@@ -287,9 +291,19 @@ Task(
 )
 ```
 
+**5c. 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 (the same `subagent_type` and model, with the errors and the file to fix). One revision at most: if the check still fails, proceed, and add a `## Unknowns` list to the research file naming each question still without a sourced answer and the assumption the plan uses. Research never blocks planning.
+
+The planner uses the answers to settle decisions. It never plans an item from `## Ideas (v2 candidates)`: those are for the user, through `/pan:todo-add` or a later phase.
+
 ### Handle Researcher Return
 
-- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
+- **`## RESEARCH COMPLETE`:** Display the decisions it settled, run 5c, continue to step 6
 - **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
 
 ## 5.5. Create Validation Strategy (if Nyquist enabled)
@@ -331,6 +345,14 @@ ls "${PHASE_DIR}"/*-plan.md 2>/dev/null
 
 ## 8. Spawn pan-planner Agent
 
+**Lean path (`SIZING.path` is `lean`, not `--gaps`): the engine plans the phase.**
+
+```bash
+LEAN_PLAN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size phase-plan "${PHASE_NUMBER}")
+```
+
+Exit 0: the plans are written (one task per requirement, each task's action the requirement's own text, at most `workflow.lean_max_requirements` tasks a plan), checked, recorded as the phase's plan check and committed. Show its `paths` and go to step 13. Exit 1 (`has_plans`, `not_lean`, or a check that failed): continue below with the planner.
+
 Display banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -351,6 +373,7 @@ Planner prompt:
 - {state_path} (Project State)
 - {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)
+- {assumptions_path} (the user's corrections to /pan:assumptions, when the file exists: `init` reports `assumptions_path`; each correction binds the plan like a decision)
 - {research_path} (Technical Research)
 - {verification_path} (Verification Gaps - if --gaps)
 - {uat_path} (UAT Gaps - if --gaps)
@@ -362,6 +385,11 @@ Planner prompt:
 **Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules
 </planning_context>
 
+<ceremony>
+{Only when SIZING.path is lean, include:}
+Lean path: this phase's requirements already name what to build. Write ONE plan, as short as the requirements allow: no research section, no restating of the requirements, decisions only (signatures, values, assertions, the verify command). The engine checks the plan in code instead of a plan-checker.
+</ceremony>
+
 <downstream_consumer>
 Output consumed by /pan:exec-phase. Plans need:
 - Frontmatter (wave, depends_on, files_modified, autonomous)
@@ -398,7 +426,15 @@ Task(
 
 ## 10. Spawn pan-plan-checker Agent
 
-**First, the checks code can make.** Run them before spending a checker:
+**Lean path (`SIZING.path` is `lean`): the engine checks the plans.**
+
+```bash
+ENGINE_CHECK=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size plan-check "${PHASE_NUMBER}")
+```
+
+Exit 0 (`ok`, `recorded`): the plan set, every plan's structure and the plans' grep gates pass, and the engine has recorded the phase's plan check. Skip the checker and go to step 13. Exit 1: send its `errors` to the planner as the revision context (step 12; it counts as an iteration) and run `size plan-check` again; when it still fails, continue below with the plan-checker agent.
+
+**Full path. 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}")
@@ -432,6 +468,7 @@ Checker prompt:
 - {PHASE_DIR}/*-plan.md (Plans to verify)
 - {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)
+- {assumptions_path} (the user's corrections to /pan:assumptions, when the file exists: `init` reports `assumptions_path`; each correction binds the plan like a decision)
 - {research_path} (Technical Research — includes Validation Architecture)
 </files_to_read>
 
@@ -453,6 +490,11 @@ Checker prompt:
 - ## VERIFICATION PASSED — all checks pass
 - ## ISSUES FOUND — structured issue list
 </expected_output>
+
+<output_budget>
+{Only when SIZING.mode is auto, include:}
+Report the verdict and the blocking issues only: one line per issue (plan, task, what is wrong, the fix), at most 300 words before the pan-verdict block. No summary of what passed.
+</output_budget>
 ```
 
 ```
@@ -483,11 +525,11 @@ Each re-check in the revision loop overwrites the same file and is recorded agai
 
 ## 12. Revision Loop (At Most 2 Revisions, 3 Checks)
 
-Track `iteration_count` (starts at 1 after initial plan + check).
+Track `iteration_count` (starts at 1 after initial plan + check). `MAX_CHECKS` is 2 when `SIZING.mode` is `auto` (one revision: a second failure goes to the user, not another paid round) and 3 when it is `full`.
 
-**If iteration_count < 3:**
+**If iteration_count < MAX_CHECKS:**
 
-Display: `Sending back to planner for revision... (iteration {N}/3)`
+Display: `Sending back to planner for revision... (iteration {N}/{MAX_CHECKS})`
 
 Revision prompt:
 
@@ -499,6 +541,7 @@ Revision prompt:
 <files_to_read>
 - {PHASE_DIR}/*-plan.md (Existing plans)
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
+- {assumptions_path} (the user's corrections to /pan:assumptions, when the file exists: `init` reports `assumptions_path`; each correction binds the plan like a decision)
 </files_to_read>
 
 **Checker issues:** {structured_issues_from_checker}
@@ -522,7 +565,7 @@ Task(
 
 After planner returns -> spawn checker again (step 10), increment iteration_count.
 
-**If iteration_count >= 3:**
+**If iteration_count >= MAX_CHECKS:**
 
 Display: `Max iterations reached. {N} issues remain:` + issue list
 
@@ -530,7 +573,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 checks"
+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 ${MAX_CHECKS} plan checks"
 ```
 
 ## 13. Present Final Status
@@ -682,7 +725,7 @@ Verification: {Passed | Passed with override | Skipped}
 
 **Also available:**
 - cat .planning/phases/{phase-dir}/*-plan.md — review plans
-- /pan:plan-phase {X} --research — re-research first
+- /pan:plan-phase {X} --research — answer open questions first, then replan
 
 ───────────────────────────────────────────────────────────────
 </offer_next>
@@ -692,8 +735,8 @@ Verification: {Passed | Passed with override | Skipped}
 - [ ] Phase validated against roadmap
 - [ ] Phase directory created if needed
 - [ ] context.md loaded early (step 4) and passed to ALL agents
-- [ ] Research completed (unless --skip-research or --gaps or exists)
-- [ ] pan-phase-researcher spawned with context.md
+- [ ] Research only when asked for (`--research` or `workflow.research: true`): at most 5 questions, one pan-phase-researcher, `research check` run
+- [ ] No idea from research planned into the phase
 - [ ] Existing plans checked
 - [ ] pan-planner spawned with context.md + research.md
 - [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)

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

@@ -1,3 +1,53 @@
+<objective>
+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)
+- Downgrade confirmation (quality → balanced → budget requires 'yes')
+- Config file creation if missing
+- Profile update in config.json
+- Confirmation with model table display
+</objective>
+
+<tier_decision_tree>
+**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:
+
+```
+Baseline tier (from MODEL_PROFILES[agent][profile])
+        │
+        ▼
+┌─────────────────────────────────────────────┐
+│ context_estimate > 700K tokens?             │── yes ──▶ force reasoning (widest ctx tier)
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+┌─────────────────────────────────────────────┐
+│ needs_thinking AND tier == fast?            │── yes ──▶ upgrade fast → mid
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+┌─────────────────────────────────────────────┐
+│ cache_warm AND !needs_thinking              │── yes ──▶ downgrade mid → fast
+│ AND context_estimate < 50K AND tier == mid  │
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+Final tier → provider-native model name
+```
+
+**Quick guide:**
+- Heavy verification (plan-checker, verifier, integration-checker, reviewer, debugger): `needs_thinking: true` — baseline upgrades fast→mid.
+- Whole-repo context estimates above the large-context threshold (`context_estimate > 700K` tokens — `LARGE_CONTEXT_TOKEN_THRESHOLD`): forced to reasoning, which inherits the model you launched with. Note the direction: `/pan:map-codebase` picks `single-shot` **at or below** 700K and `sharded` above it, so the repos that trip this rule are the ones the mapper is already sharding.
+- Routine exec tasks with project.md cached: `cache_warm + small ctx` — mid gets downgraded to fast for a cost win.
+- All rules are additive to the `quality` / `balanced` / `budget` profile you pick here — profile sets the floor, capability hints adjust upward or downward within that floor's band.
+
+**Inspecting routing:** use `pan-tools resolve-model <agent> --metadata '{"context_estimate":900000,"needs_thinking":true}'` to see what tier a given hint set resolves to.
+
+**Effort dimension (2026-06):** `resolve-model` also returns an `effort` level (`low`/`medium`/`high`/`xhigh`) per agent — the within-model reasoning-depth dial on current models. Profiles modulate it: `budget` steps each agent's base effort down one level (floor `low`); `quality`/`balanced` keep the base. Per-agent override: `.planning/config.json` → `"effort_overrides": { "pan-verifier": "xhigh" }`.
+</tier_decision_tree>
+
 <purpose>
 Switch the model profile used by PAN agents. Controls which model tier each agent uses, balancing quality vs token spend.
 </purpose>

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

@@ -128,6 +128,16 @@ CONTEXT: [✓ if has_context | - if not]
 </step>
 
 <step name="route">
+**Ask the router first.** One verb decides the next step:
+
+```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.
+
+Its `action` picks the route below: `execute` → **Route A**, `plan` → **Route B**, `plan_gaps` → **Route E**, `verify` → offer `/pan:verify-phase {phase}`, `complete_phase` → run `command`, then **Route C**, `audit_milestone` → **Route D** (audit before `/pan:milestone-done`), `new_milestone` → **Route F**. The counts below are what the router read; use them to explain the route, not to pick a different one.
+
 **Determine next action based on verified counts.**
 
 **Step 1: Count plans, summaries, and issues in current phase**

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).
 
 ---