pan-wizard 3.35.0 → 3.37.0

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

@@ -7,8 +7,8 @@ Analyze the most recent trace session and generate a circular optimization repor
 - A trace session must exist in `.planning/optimization/traces/`
 - If no session exists, instruct the user to start one first:
   ```
-  /pan:optimize trace init --description "what you're building"
-  [run your build: /pan:exec-phase N or /pan:focus-exec]
+  /pan:learn --optimize trace init --description "what you're building"
+  [run your build: /pan:exec-phase N or /pan:focus-auto --step exec]
   /pan:learn
   ```
 
@@ -65,7 +65,7 @@ Present to the user:
 2. **Top 3 findings** — the most impactful recommendations
 3. **Lessons** — how many, and where each belongs: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
 4. **Prompt and workflow changes** — how many, for human review
-5. **Next step** — `/pan:optimize apply` records the suggestions in `.planning/optimization/suggestions.md`; a person makes the changes, because nothing in the report reaches an agent until it is written where the agents read
+5. **Next step** — `/pan:learn --optimize apply` records the suggestions in `.planning/optimization/suggestions.md`; a person makes the changes, because nothing in the report reaches an agent until it is written where the agents read
 
 ## Step 5 — Auto-apply (if --apply flag)
 

package/pan-wizard-core/workflows/milestone-audit.md

@@ -274,7 +274,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 **Plan gap closure** — create phases to complete milestone
 
-/pan:milestone-gaps
+/pan:milestone-audit --gaps
 
 <sub>/clear first → fresh context window</sub>
 
@@ -316,7 +316,7 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 
 **B. Plan cleanup phase** — address debt before completing
 
-/pan:milestone-gaps
+/pan:milestone-audit --gaps
 
 <sub>/clear first → fresh context window</sub>
 

package/pan-wizard-core/workflows/milestone-new.md

@@ -55,17 +55,13 @@ Update Active requirements section and "Last updated" footer.
 
 ## 5. Update state.md
 
-```markdown
-## Current Position
+Reset the position for the new milestone through the engine, keeping the Accumulated Context of the last one:
 
-**Current Phase:** Not started (defining requirements)
-**Current Plan:** —
-**Status:** Defining requirements
-**Last Activity:** [today]
-**Last Activity Description:** Milestone v[X.Y] started
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state init --core-value "<core value from project.md>" --focus "Milestone v[X.Y] [Name]" --phase "Not started" --phase-name "Defining requirements" --status "Defining requirements" --activity "Milestone v[X.Y] started" --force --keep-context
 ```
 
-Keep Accumulated Context section from previous milestone.
+The old state.md is backed up first. The engine writes every section of the template and keeps the frontmatter in sync; never write state.md with the Write or Edit tool (under `hooks.guard: enforce` the guard denies it).
 
 ## 6. Cleanup and Commit
 
@@ -81,108 +77,63 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start milestone v
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init new-milestone)
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
+Extract from init JSON: `researcher_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
 
 ## 8. Research Decision
 
-AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
-- "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
-- "Skip research" — Go straight to requirements
+Research is **off by default** and answers questions; it never surveys a domain or adds scope (the same contract as `/pan:new-project` step 6).
 
-**Persist choice to config** (so future `/pan:plan-phase` honors it):
+AskUserQuestion: "Research open questions for the new features before defining requirements?"
+- "Skip research (Recommended)" — Go straight to requirements
+- "Research open questions" — Answer up to 5 questions that block building the new features, each with a source
 
-```bash
-# If "Research first": persist true
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research true
+`/pan:plan-phase` keeps its own setting (`workflow.research`, off by default; `/pan:settings` changes it).
+
+**If "Research open questions":**
 
-# If "Skip research": persist false
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research false
+List at most **5** open questions the milestone's goals leave unanswered and that block building the NEW features (a technology choice, an external API's behaviour, a data format, a limit or rule; never what already exists). Write them as a numbered list to `.planning/research/questions.md` (`mkdir -p .planning/research` first):
+
+```markdown
+# Research questions — milestone v[X.Y]
+
+1. [question] — blocks: [the decision it settles]
 ```
 
-**If "Research first":**
+**No questions → no research.** If nothing blocks building, write no file, say so, and continue to Step 9.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PAN ► RESEARCHING
+ PAN ► RESEARCHING {N} QUESTIONS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning 4 researchers in parallel...
-  → Stack, Features, Architecture, Pitfalls
 ```
 
-```bash
-mkdir -p .planning/research
-```
-
-Spawn 4 parallel pan-project-researcher agents. Each uses this template with dimension-specific fields:
-
-**Common structure for all 4 researchers:**
 ```
 Task(prompt="
-<research_type>Project Research — {DIMENSION} for [new features].</research_type>
-
-<milestone_context>
-SUBSEQUENT MILESTONE — Adding [target features] to existing app.
-{EXISTING_CONTEXT}
-Focus ONLY on what's needed for the NEW features.
-</milestone_context>
-
-<question>{QUESTION}</question>
-
 <files_to_read>
-- .planning/project.md (Project context)
+- .planning/research/questions.md (The questions: answer these and nothing else)
+- .planning/project.md (Project context; what exists is not a question)
 </files_to_read>
 
-<downstream_consumer>{CONSUMER}</downstream_consumer>
-
-<quality_gate>{GATES}</quality_gate>
-
 <output>
-Write to: .planning/research/{FILE}
-Use template: ~/.claude/pan-wizard-core/templates/research-project/{FILE}
+Write to: .planning/research/research-summary.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). Do not commit.
 </output>
-", subagent_type="pan-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Answer research questions")
 ```
 
-**Dimension-specific fields:**
-
-| Field | Stack | Features | Architecture | Pitfalls |
-|-------|-------|----------|-------------|----------|
-| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from project.md] | Existing features (already built): [from project.md] | Existing architecture: [from project.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
-| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
-| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
-| GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
-| FILE | stack.md | features.md | architecture.md | pitfalls.md |
-
-After all 4 complete, spawn synthesizer:
+Check the answers:
 
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research check .planning/research/questions.md .planning/research/research-summary.md
 ```
-Task(prompt="
-Synthesize research outputs into summary.md.
-
-<files_to_read>
-- .planning/research/stack.md
-- .planning/research/features.md
-- .planning/research/architecture.md
-- .planning/research/pitfalls.md
-</files_to_read>
 
-Write to: .planning/research/summary.md
-Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
-Commit after writing.
-", subagent_type="pan-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
-```
+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 research-summary.md with the assumption you will use. Commit:
 
-Display key findings from summary.md:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: answer milestone research questions" --files .planning/research/questions.md .planning/research/research-summary.md
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PAN ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Stack additions:** [from summary.md]
-**Feature table stakes:** [from summary.md]
-**Watch Out For:** [from summary.md]
-```
+Display the decisions settled, the unknowns with their assumptions, and the number of ideas (offered in Step 9 as future candidates, never added to this milestone by themselves).
 
 **If "Skip research":** Continue to Step 9.
 
@@ -196,27 +147,19 @@ Display key findings from summary.md:
 
 Read project.md: core value, current milestone goals, validated requirements (what exists).
 
-**If research exists:** Read features.md, extract feature categories.
-
-Present features by category:
-```
-## [Category 1]
-**Table stakes:** Feature A, Feature B
-**Differentiators:** Feature C, Feature D
-**Research notes:** [any relevant notes]
-```
+**If research exists:** Read `.planning/research/research-summary.md`. Its answers settle decisions the requirements use; its `## Ideas (v2 candidates)` are offered as future candidates the user may promote, never added to this milestone by themselves.
 
-**If no research:** Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
+Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
 
 **Scope each category** via AskUserQuestion (multiSelect: true, header max 12 chars):
 - "[Feature 1]" — [brief description]
 - "[Feature 2]" — [brief description]
 - "None for this milestone" — Defer entire category
 
-Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
+Track: Selected → this milestone. Unselected → future or out of scope (ask which when unclear).
 
 **Identify gaps** via AskUserQuestion:
-- "No, research covered it" — Proceed
+- "No, that covers it" — Proceed
 - "Yes, let me add some" — Capture additions
 
 **Generate requirements.md:**
@@ -275,7 +218,7 @@ Task(prompt="
 <files_to_read>
 - .planning/project.md
 - .planning/requirements.md
-- .planning/research/summary.md (if exists)
+- .planning/research/research-summary.md (if exists; older projects: .planning/research/summary.md)
 - .planning/config.json
 - .planning/milestones.md
 </files_to_read>
@@ -288,7 +231,7 @@ Create roadmap for milestone v[X.Y]:
 3. Map every requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
 5. Validate 100% coverage
-6. Write files immediately (roadmap.md, state.md, update requirements.md traceability)
+6. Write roadmap.md immediately; initialise state.md with `pan-tools state init ... --force --keep-context` (it exists from step 5), never the Write tool; update requirements.md traceability
 7. Return ROADMAP CREATED with summary
 
 Write files first, then return.