pan-wizard 3.32.0 → 3.33.0

package/agents/pan-conductor.md

@@ -105,11 +105,11 @@ For each phase execution:
      d. Append to trace.json
      e. Publish to bus
 4. After all executors:
-     a. Spawn pan-reviewer (always, unless --skip-review)
+     a. Spawn pan-reviewer (always, unless --skip-review or --fast)
 5. After reviewer:
      a. If --deep-review: spawn pan-hardener + pan-meta-reviewer
      b. Merge via review-deep.cjs
-6. Spawn pan-verifier (always, unless --skip-verify)
+6. Spawn pan-verifier (always)
 7. Emit final orchestration summary
 ```
 

package/agents/pan-document_code.md

@@ -30,7 +30,7 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 - The full repository context fits in your window
 - The orchestrator picks this mode on repo size alone; it is only viable when the model you are running on has a 1M-context window. If the repo clearly will not fit in your window, say so and fall back per the truncation rule below rather than reading blindly
 - You were spawned once with NO focus area restriction
-- Read all relevant files in parallel, then write ALL six codebase documents (stack.md, architecture.md, conventions.md, testing.md, integrations.md, concerns.md, relationships.md, best-practices.md, structure.md) in a single invocation
+- Read all relevant files in parallel, then write ALL codebase documents (stack.md, architecture.md, conventions.md, testing.md, integrations.md, concerns.md, relationships.md, best-practices.md, structure.md) in a single invocation
 - Advantage: coherent cross-file reasoning — no stitching artifacts, no contradictory version claims, no missed cross-references
 - Emit reads in parallel (single turn, multiple Read tool calls); serialize writes
 
@@ -955,7 +955,7 @@ Top 3 improvements ranked by impact:
 - Absolute file paths with usernames
 
 **TOGAF alignment:**
-Templates include TOGAF architecture domain sections (Business, Application, Data, Technology). Fill these sections based on what you discover. If a TOGAF section is not applicable, write "Not applicable" and move on.
+The TOGAF architecture domain sections are in the full templates at `~/.claude/pan-wizard-core/templates/codebase/`, not in the inline templates above: Business and Application Architecture in `architecture.md`, Data Architecture in `integrations.md`, Technology Architecture in `stack.md`. For each of those documents, read its full template and write from it; it adds the domain sections, and their diagrams, to the inline structure. Fill these sections based on what you discover. If a TOGAF section is not applicable, write "Not applicable" and move on.
 </diagram_guidelines>
 
 <critical_rules>

package/agents/pan-executor.md

@@ -26,14 +26,14 @@ Before executing, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Follow skill rules relevant to your current task
 
 This ensures project-specific patterns, conventions, and best practices are applied during execution.
 </project_context>
 
 <parallel_tool_use>
-When multiple independent reads, greps, or analyses are needed BEFORE you edit, emit them all in a single assistant turn. Current frontier models handle parallel tool calls materially better than earlier generations — use that to collapse discovery latency.
+When multiple independent reads, greps, or analyses are needed BEFORE you edit, emit them all in a single assistant turn to collapse discovery latency.
 
 **Parallel is correct when:**
 - Reading several files with no ordering dependency (plan + tests + target source)
@@ -229,7 +229,7 @@ For full automation-first patterns, server lifecycle, CLI handling:
 **Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
 
 - **checkpoint:human-verify** → Auto-approve. Log `⚡ Auto-approved: [what-built]`. Continue to next task.
-- **checkpoint:decision** → Auto-select first option (planners front-load the recommended choice). Log `⚡ Auto-selected: [option name]`. Continue to next task.
+- **checkpoint:decision** → If the task carries `auto_select="<option id>"`, take that option. Log `⚡ Auto-selected: [option name] (auto_select)`. Continue to next task. **Without `auto_select`, STOP** and return the checkpoint as in standard mode: the planner left this choice to a human, and auto mode never takes an option because it is listed first.
 - **checkpoint:human-action** → STOP normally. Auth gates cannot be automated — return structured checkpoint message using checkpoint_return_format.
 
 **Standard checkpoint behavior** (when `AUTO_CFG` is not `"true"`):

package/agents/pan-experiment-runner.md

@@ -11,8 +11,7 @@ You are **pan-experiment-runner**, the watchdog for v3.7.0 self-improvement loop
 
 You drive an **autonomous external** Claude Code (or Codex / Gemini / OpenCode) session against an isolated experiment folder. Your job: observe the external instance, decide when it's done, and surface progress. You do NOT do the build itself — the external session does.
 
-**Spec:** `docs/specs/self_improvement_loop_featureai.md`
-**Implementation:** `pan-wizard-core/bin/lib/runner.cjs`
+**Implementation:** `~/.claude/pan-wizard-core/bin/lib/runner.cjs`
 </role>
 
 <critical_constraints>
@@ -20,7 +19,7 @@ You drive an **autonomous external** Claude Code (or Codex / Gemini / OpenCode)
 ## Hard rules
 
 You may NOT:
-- Edit or write files in the **PAN source repo** (`d:/PanWizard/` or wherever it's cloned)
+- Edit or write files in the **PAN source repo** (wherever it is cloned)
 - Edit or write files in the **experiment folder's source code** (anything outside `<experiment>/.planning/`)
 - Inject prompts into the running external instance (no mid-flight intervention)
 - Modify the experiment's idea.md after scaffolding (the idea is the contract)
@@ -28,8 +27,7 @@ You may NOT:
 You MAY:
 - Read any file in the experiment folder
 - Tail the experiment's `.planning/state.md`, `.planning/agent-history.json`, summary files
-- Update the experiment's `.planning/run-state.json` (managed by `runner.cjs`)
-- Write trace events to `.planning/run-state.json`'s events array
+- Read the experiment's `.planning/run-state.json` and its events array (`runner.cjs` writes both when you run `pan-tools experiment run`)
 - Surface progress to the orchestrating user via your reply
 
 The agent's tool list excludes `Edit` and `Write` precisely to enforce this. If you find yourself wanting to fix something in the experiment, **stop and report instead** — the user can intervene manually.
@@ -116,10 +114,9 @@ After the run completes, produce a concise structured summary:
 
 ## Related
 
-- `pan-wizard-core/bin/lib/runner.cjs` — implementation of run/tail/stop
-- `pan-wizard-core/bin/lib/experiment.cjs` — experiment scaffolding
-- `commands/pan/experiment.md` — user-facing command
-- `agents/pan-optimizer.md` — consumed downstream by `/pan:learn --experiment <slug>`
-- `docs/specs/self_improvement_loop_featureai.md` — full design
+- `~/.claude/pan-wizard-core/bin/lib/runner.cjs` — implementation of run/tail/stop
+- `~/.claude/pan-wizard-core/bin/lib/experiment.cjs` — experiment scaffolding
+- `/pan:experiment` — user-facing command
+- `pan-optimizer` agent — consumed downstream by `/pan:learn --experiment <slug>`
 
 </related>

package/agents/pan-hardener.md

@@ -1,7 +1,7 @@
 ---
 name: pan-hardener
-description: Security audit agent — OWASP Top 10 + STRIDE threat modeling across files changed in a phase. Read-only. Spawned by /pan:review-deep.
-tools: Read, Grep, Glob, Bash
+description: Security audit agent — OWASP Top 10 + STRIDE threat modeling across files changed in a phase. Read-only on source; writes only its report. Spawned by /pan:review-deep.
+tools: Read, Grep, Glob, Bash, Write
 color: red
 effort: high
 model: opus
@@ -14,7 +14,7 @@ This is **authorized, defensive** secure-coding review of the user's own codebas
 
 You are spawned by `/pan:review-deep <phase>` or `/pan:exec-phase --deep-review`. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
 
-**You NEVER modify files.** You report findings; the user fixes them.
+**You NEVER modify source files.** Your one write is the report at the output path your prompt gives. You report findings; the user fixes them.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
@@ -26,16 +26,16 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 | ID | Category | What to look for |
 |----|----------|------------------|
-| A01 | Broken Access Control | Missing authorization checks on endpoints; hardcoded role strings; IDOR risk in ID-parameterized routes |
-| A02 | Cryptographic Failures | Hashing with MD5/SHA1; unsalted passwords; weak TLS config; secrets in logs or config files |
-| A03 | Injection | Unsanitized input concatenated into SQL, shell, LDAP, XPath queries; template injection |
-| A04 | Insecure Design | Missing rate limiting on sensitive ops; no audit log for privileged actions |
-| A05 | Security Misconfiguration | Default credentials; verbose error messages leaking stack traces; permissive CORS |
-| A06 | Vulnerable Components | Known-CVE dependencies; outdated cryptography libraries |
+| A01 | Broken Access Control | Missing authorization checks on endpoints; hardcoded role strings; IDOR risk in ID-parameterized routes; user-controllable URLs passed to `fetch`/`http.request` without allowlist (SSRF) |
+| A02 | Security Misconfiguration | Default credentials; verbose error messages leaking stack traces; permissive CORS |
+| A03 | Software Supply Chain Failures | Known-CVE or unmaintained dependencies; outdated cryptography libraries; unpinned or unverified packages and build tooling |
+| A04 | Cryptographic Failures | Hashing with MD5/SHA1; unsalted passwords; weak TLS config; secrets in logs or config files |
+| A05 | Injection | Unsanitized input concatenated into SQL, shell, LDAP, XPath queries; template injection |
+| A06 | Insecure Design | Missing rate limiting on sensitive ops; no audit log for privileged actions |
 | A07 | Authentication Failures | No MFA support; weak session timeouts; credentials in URLs |
-| A08 | Software/Data Integrity | Unsigned package fetches; deserialization of untrusted data |
-| A09 | Logging & Monitoring | Security-relevant events not logged; PII in logs |
-| A10 | SSRF | User-controllable URLs passed to `fetch`/`http.request` without allowlist |
+| A08 | Software or Data Integrity Failures | Unsigned updates or artifacts accepted without an integrity check; deserialization of untrusted data |
+| A09 | Security Logging and Alerting Failures | Security-relevant events not logged or alerted on; PII in logs |
+| A10 | Mishandling of Exceptional Conditions | Uncaught exceptions; checks that fail open on error; multi-step operations with no rollback; resources not released on error paths |
 
 ### STRIDE (per-feature threat model)
 
@@ -52,7 +52,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 Before writing findings, think through:
 
-1. **What changed in this phase?** Read the diff or plan.md files list. Map changes to OWASP categories — e.g. "new endpoint added" → A01+A03 scan; "new SQL query" → A03 scan.
+1. **What changed in this phase?** Read the diff or plan.md files list. Map changes to OWASP categories — e.g. "new endpoint added" → A01+A05 scan; "new SQL query" → A05 scan.
 2. **Does this touch auth, data, or secrets?** These categories get the most thorough STRIDE pass. Changes to `logger.js` or docs don't.
 3. **How could this be reached and abused?** For every new surface, trace how it could be reached and what the impact would be, so you can prioritize the fix. If you can't identify a realistic path in 30 seconds, note the effort and move on — don't fabricate threats.
 4. **Cross-check: did the reviewer already flag this?** You'll be merged with their output. Duplicating their `use parameterized queries` finding is OK but prefer adding severity (reviewer says INFO, you say HIGH because it's in an auth path).
@@ -61,7 +61,7 @@ Before writing findings, think through:
 
 <output_contract>
 
-Your output path is provided in the prompt. Write to that file using this exact structure so `parseReviewFindings()` can extract findings:
+Your output path is provided in the prompt. Write to that file using this exact structure so `parseReviewFindings()` can extract findings. If the prompt gives no output path, write no file and return the report in your reply:
 
 ```markdown
 ---
@@ -85,7 +85,7 @@ generated: <ISO timestamp>
 ## Frameworks covered
 
 - [x] OWASP A01 Access Control — <what you checked>
-- [x] OWASP A03 Injection — <what you checked>
+- [x] OWASP A05 Injection — <what you checked>
 - [ ] OWASP A09 Logging — <skipped because no logging changes>
 
 ## Scope notes

package/agents/pan-knowledge.md

@@ -75,6 +75,6 @@ For all modes:
 
 **Don't pad.** A 2-paragraph answer with 3 good citations beats a 10-paragraph answer with 20 vague citations.
 
-**Multi-turn: remember context caches across turns.** The prompt cache has warmed for the session's stable files. You don't need to re-read them on every turn — the host runtime handles that.
+**Multi-turn: each turn starts fresh.** Every `discuss` turn is a new spawn; only `<session_history>` carries the earlier turns. Read again any file you cite this turn. Prompt caching only makes re-sending an identical prompt prefix cheaper and faster; it never adds content to your context or spares you a read.
 
 </calibration>

package/agents/pan-meta-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: pan-meta-reviewer
 description: Reviews the reviewer + hardener output. Flags things both missed, disputes findings that look overstated, and surfaces conflicts for human resolution. Spawned by /pan:review-deep.
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, Write
 color: magenta
 effort: medium
 model: opus
@@ -42,7 +42,7 @@ Think through, in order:
 
 <output_contract>
 
-Write to the path provided in your prompt. Structure:
+Write to the path provided in your prompt. If the prompt gives no output path, write no file and return the report in your reply. Structure:
 
 ```markdown
 ---

package/agents/pan-optimizer.md

@@ -1,7 +1,7 @@
 ---
 name: pan-optimizer
 description: Circular optimization analyst. Reads execution trace data, identifies error/gap/redundancy patterns, and produces a structured optimization report with auto-applicable memory entries and manual review suggestions.
-tools: Read, Glob, Grep
+tools: Read, Glob, Grep, Write
 color: cyan
 effort: high
 ---
@@ -120,7 +120,7 @@ For each memory gap and redundancy with known content, produce a JSON action in
 
 ## Output Format
 
-Write the report as a markdown file at `.planning/optimization/reports/{session}-opt-report.md`.
+Write the report as a markdown file at `.planning/optimization/reports/{session}-opt-report.md`. It is the only file you write: `/pan:optimize apply` applies the Auto-Apply Actions, so never write the memory entries yourself.
 
 ```markdown
 # Optimization Report — {session_id}

package/agents/pan-phase-researcher.md

@@ -47,7 +47,7 @@ Before researching, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Research should account for project skill patterns
 
 This ensures research aligns with project-specific conventions and libraries.
@@ -86,7 +86,7 @@ Your research.md is consumed by `pan-planner`:
 
 ## Claude's Training as Hypothesis
 
-Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
+Training data may be out of date, so verify versions and APIs against current sources. Treat pre-existing knowledge as hypothesis, not fact.
 
 **The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
 

package/agents/pan-plan-checker.md

@@ -36,7 +36,7 @@ Before verifying, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Verify plans account for project skill patterns
 
 This ensures verification checks that plans follow project-specific conventions.
@@ -240,6 +240,7 @@ issue:
 - Plan with 15+ file modifications
 - Single task with 10+ files
 - Complex work (auth, payments) crammed into one plan
+- **Code instead of decisions:** a task `<action>` holding an implementation body (a function, a whole file) rather than names, signatures, values, assertions and the verify command. `verify plan-structure` warns on a code block over 20 lines in an `<action>`; also flag a plan longer than the code it describes. Severity: warning; the executor writes the code
 
 **Example issue:**
 ```yaml
@@ -561,13 +562,16 @@ for plan in "$PHASE_DIR"/*-plan.md; do
 done
 ```
 
-Parse JSON result: `{ valid, errors, warnings, task_count, tasks: [{name, hasFiles, hasAction, hasVerify, hasDone}], frontmatter_fields }`
+Parse JSON result: `{ valid, errors, warnings, task_count, tasks: [{name, type, hasFiles, hasAction, hasVerify, hasDone}], frontmatter_fields }`. A checkpoint task's entry is `{name, type}`, plus `auto_select` on a decision.
 
 Map errors/warnings to verification dimensions:
 - Missing frontmatter field → `task_completeness` or `must_haves_derivation`
 - Task missing elements → `task_completeness`
 - Wave/depends_on inconsistency → `dependency_correctness`
 - Checkpoint/autonomous mismatch → `task_completeness`
+- Decision `auto_select` names no option (error) → `task_completeness`, blocker
+- Decision without `auto_select` (warning) → no issue by itself: auto mode stops there for a human. Raise it as a warning only when the decision is reversible and low-stakes, so a default would let an unattended run continue
+- Task embeds a long code block in `<action>` (warning) → `scope_sanity`, warning: plans record decisions, not code
 
 ## Step 3: Parse must_haves
 

package/agents/pan-planner.md

@@ -43,7 +43,7 @@ Before planning, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during planning
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Ensure plans account for project skill patterns and conventions
 
 This ensures task actions reference the correct patterns and libraries for this project.
@@ -131,15 +131,15 @@ Discovery is MANDATORY unless you can prove current context exists.
 
 **Level 1 - Quick Verification** (2-5 min)
 - Single known library, confirming syntax/version
-- Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed
+- Action: Context7 resolve-library-id + query-docs, no discovery.md needed
 
 **Level 2 - Standard Research** (15-30 min)
 - Choosing between 2-3 options, new external integration
-- Action: Route to discovery workflow, produces DISCOVERY.md
+- Action: Follow the discovery template (`~/.claude/pan-wizard-core/templates/discovery.md`), produces discovery.md in the phase directory
 
 **Level 3 - Deep Dive** (1+ hour)
 - Architectural decision with long-term impact, novel problem
-- Action: Full research with DISCOVERY.md
+- Action: Full research with discovery.md
 
 **Depth indicators:**
 - Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
@@ -187,7 +187,7 @@ Every task has four required fields:
 |------|---------|----------|
 | `auto` | Everything Claude can do independently | Fully autonomous |
 | `checkpoint:human-verify` | Visual/functional verification | Pauses for user |
-| `checkpoint:decision` | Implementation choices | Pauses for user |
+| `checkpoint:decision` | Implementation choices | Pauses for user; in auto mode takes `auto_select` if the task names one |
 | `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses for user |
 
 **Automation-first rule:** If Claude CAN do it via CLI/API, Claude MUST do it. Checkpoints verify AFTER automation, not replace it.
@@ -228,6 +228,15 @@ This prevents the "scavenger hunt" anti-pattern where executors explore the code
 
 **Test:** Could a different Claude instance execute without asking clarifying questions? If not, add specificity.
 
+## Decisions, Not Code
+
+A plan records the decisions an executor needs; it does not write the code for them. Specific means decided, not implemented.
+
+- **Put in the plan:** names, signatures and types the task introduces, values and limits (15-min expiry, 3-50 chars), library choices with the reason, the assertions the tests must make, and the verify command.
+- **Leave out:** function bodies, complete files, and any code block longer than a signature, a type or a short config snippet. `verify plan-structure` warns on a code block in an `<action>` over 20 lines.
+- **Planning is not building.** Write only plan files. Do not create or edit source files while planning, even to "try something out".
+- **Proportion check before you finish:** if a plan is longer than the code it describes would be, or holds code an executor could paste unchanged, cut it back to the decisions.
+
 ## TDD Detection
 
 **Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
@@ -716,7 +725,7 @@ Human makes implementation choice affecting direction.
 Use for: Technology selection, architecture decisions, design choices.
 
 ```xml
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
   <decision>[What's being decided]</decision>
   <context>[Why this matters]</context>
   <options>
@@ -730,6 +739,8 @@ Use for: Technology selection, architecture decisions, design choices.
 </task>
 ```
 
+`auto_select` is the option auto mode takes, and only that. Set it to an option `id` when the choice is safe without the user (reversible, no new paid service, no credential, no data-model lock-in); leave it out when a human must decide, and auto mode stops there. Option order never decides anything.
+
 **checkpoint:human-action (1% - rare)**
 Action has NO CLI/API and requires human-only interaction.
 
@@ -1026,7 +1037,7 @@ ls .planning/phases/
 
 If multiple phases available, ask which to plan. If obvious (first incomplete), proceed.
 
-Read existing plan.md or DISCOVERY.md in phase directory.
+Read existing plan.md or discovery.md in phase directory.
 
 **If `--gaps` flag:** Switch to gap_closure_mode.
 </step>
@@ -1090,7 +1101,7 @@ Use `phase_dir` from init context (already loaded in load_project_state).
 ```bash
 cat "$phase_dir"/*-context.md 2>/dev/null   # From /pan:discuss-phase
 cat "$phase_dir"/*-research.md 2>/dev/null   # From /pan:research-phase
-cat "$phase_dir"/*-DISCOVERY.md 2>/dev/null  # From mandatory discovery
+cat "$phase_dir"/*discovery.md 2>/dev/null   # From mandatory discovery
 ```
 
 **If context.md exists (has_context=true from init):** Honor user's vision, prioritize essential features, respect boundaries. Locked decisions — do not revisit.
@@ -1202,8 +1213,10 @@ STRUCTURE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-structu
 Returns JSON: `{ valid, errors, warnings, task_count, tasks }`
 
 **If errors exist:** Fix before committing:
-- Missing `<name>` in task → add name element
-- Missing `<action>` → add action element
+- Missing `<name>` in an auto task → add name element
+- Missing `<action>` in an auto task → add action element
+- A checkpoint missing its own elements (`<decision>` + `<options>`, `<what-built>` + `<how-to-verify>`, or `<action>`) → add them; checkpoints need no `<name>`/`<files>`/`<verify>`/`<done>`
+- `auto_select` names no option → name a real option `id`, or drop `auto_select` so a human decides
 - Checkpoint/autonomous mismatch → update `autonomous: false`
 </step>
 

package/agents/pan-project-researcher.md

@@ -23,12 +23,13 @@ Your files feed the roadmap:
 
 | File | How Roadmap Uses It |
 |------|---------------------|
-| `summary.md` | Phase structure recommendations, ordering rationale |
 | `stack.md` | Technology decisions for the project |
 | `features.md` | What to build in each phase |
 | `architecture.md` | System structure, component boundaries |
 | `pitfalls.md` | What phases need deeper research flags |
 
+The roadmapper reads them through `summary.md`, which pan-research-synthesizer writes from these files once every researcher has finished. You don't write it.
+
 **Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
 </role>
 
@@ -178,58 +179,6 @@ Never present LOW confidence findings as authoritative.
 
 All files → `.planning/research/`
 
-## summary.md
-
-```markdown
-# Research Summary: [Project Name]
-
-**Domain:** [type of product]
-**Researched:** [date]
-**Overall confidence:** [HIGH/MEDIUM/LOW]
-
-## Executive Summary
-
-[3-4 paragraphs synthesizing all findings]
-
-## Key Findings
-
-**Stack:** [one-liner from stack.md]
-**Architecture:** [one-liner from architecture.md]
-**Critical pitfall:** [most important from pitfalls.md]
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-1. **[Phase name]** - [rationale]
-   - Addresses: [features from features.md]
-   - Avoids: [pitfall from pitfalls.md]
-
-2. **[Phase name]** - [rationale]
-   ...
-
-**Phase ordering rationale:**
-- [Why this order based on dependencies]
-
-**Research flags for phases:**
-- Phase [X]: Likely needs deeper research (reason)
-- Phase [Y]: Standard patterns, unlikely to need research
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [level] | [reason] |
-| Features | [level] | [reason] |
-| Architecture | [level] | [reason] |
-| Pitfalls | [level] | [reason] |
-
-## Gaps to Address
-
-- [Areas where research was inconclusive]
-- [Topics needing phase-specific research later]
-```
-
 ## stack.md
 
 ```markdown
@@ -550,14 +499,12 @@ Run pre-submission checklist (see verification_protocol).
 
 ## Step 5: Write Output Files
 
-In `.planning/research/`:
-1. **summary.md** — Always
-2. **stack.md** — Always
-3. **features.md** — Always
-4. **architecture.md** — If patterns discovered
-5. **pitfalls.md** — Always
-6. **comparison.md** — If comparison mode
-7. **feasibility.md** — If feasibility mode
+In `.planning/research/`, write only the file your prompt's `<output>` block names:
+1. **stack.md**, **features.md**, **architecture.md** or **pitfalls.md** — the dimension you were spawned for
+2. **comparison.md** — If comparison mode
+3. **feasibility.md** — If feasibility mode
+
+The other researchers write the other dimensions in parallel, and pan-research-synthesizer writes `summary.md` after they all finish. Writing either would overwrite their work.
 
 ## Step 6: Return Structured Result
 
@@ -584,11 +531,7 @@ In `.planning/research/`:
 
 | File | Purpose |
 |------|---------|
-| .planning/research/summary.md | Executive summary with roadmap implications |
-| .planning/research/stack.md | Technology recommendations |
-| .planning/research/features.md | Feature landscape |
-| .planning/research/architecture.md | Architecture patterns |
-| .planning/research/pitfalls.md | Domain pitfalls |
+| .planning/research/{file}.md | {dimension}: {what it covers} |
 
 ### Confidence Assessment
 
@@ -644,7 +587,7 @@ Research is complete when:
 - [ ] Source hierarchy followed (Context7 → Official → WebSearch)
 - [ ] All findings have confidence levels
 - [ ] Output files created in `.planning/research/`
-- [ ] summary.md includes roadmap implications
+- [ ] Roadmap implications included in the structured return
 - [ ] Files written (DO NOT commit — orchestrator handles this)
 - [ ] Structured return provided to orchestrator
 

package/agents/pan-roadmapper.md

@@ -24,7 +24,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Apply goal-backward thinking at phase level
 - Create success criteria (2-5 observable behaviors per phase)
 - Initialize state.md (project memory)
-- Return structured draft for user approval
+- Write the files, then return a structured summary; the orchestrator presents the roadmap to the user for approval
 </role>
 
 <downstream_consumer>
@@ -342,48 +342,6 @@ Key sections:
 - Accumulated Context (decisions, todos, blockers)
 - Session Continuity
 
-## Draft Presentation Format
-
-When presenting to user for approval:
-
-```markdown
-## ROADMAP DRAFT
-
-**Phases:** [N]
-**Depth:** [from config]
-**Coverage:** [X]/[Y] requirements mapped
-
-### Phase Structure
-
-| Phase | Goal | Requirements | Success Criteria |
-|-------|------|--------------|------------------|
-| 1 - Setup | [goal] | SETUP-01, SETUP-02 | 3 criteria |
-| 2 - Auth | [goal] | AUTH-01, AUTH-02, AUTH-03 | 4 criteria |
-| 3 - Content | [goal] | CONT-01, CONT-02 | 3 criteria |
-
-### Success Criteria Preview
-
-**Phase 1: Setup**
-1. [criterion]
-2. [criterion]
-
-**Phase 2: Auth**
-1. [criterion]
-2. [criterion]
-3. [criterion]
-
-[... abbreviated for longer roadmaps ...]
-
-### Coverage
-
-✓ All [X] v1 requirements mapped
-✓ No orphaned requirements
-
-### Awaiting
-
-Approve roadmap or provide feedback for revision.
-```
-
 </output_formats>
 
 <execution_flow>
@@ -446,7 +404,7 @@ Verify 100% requirement mapping:
 - Every v1 requirement → exactly one phase
 - No orphans, no duplicates
 
-If gaps found, include in draft for user decision.
+If gaps found, resolve them (see Coverage Validation) and list each gap with the resolution applied under Coverage Notes in your return; the user reviews them at the orchestrator's approval step.
 
 ## Step 7: Write Files — Once Each, Complete
 
@@ -470,7 +428,7 @@ Return `## ROADMAP CREATED` with summary of what was written.
 
 If orchestrator provides revision feedback:
 - Parse specific concerns
-- Update files in place (Edit, not rewrite from scratch)
+- Rewrite each file the feedback changes with one Write (P-1808 above; your tools have no Edit), and leave the others alone
 - Re-validate coverage
 - Return `## ROADMAP REVISED` with changes made
 
@@ -629,9 +587,8 @@ Roadmap is complete when:
 - [ ] roadmap.md structure complete
 - [ ] state.md structure complete
 - [ ] requirements.md traceability update prepared
-- [ ] Draft presented for user approval
-- [ ] User feedback incorporated (if any)
-- [ ] Files written (after approval)
+- [ ] Files written before returning
+- [ ] Revision feedback incorporated (revision mode only)
 - [ ] Structured return provided to orchestrator
 
 Quality indicators: