pan-wizard 3.32.0 → 3.34.0

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

@@ -119,7 +119,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Reality Score:** Every P3-P6 item gets scored: `RS = (User Value + Time Criticality + Risk Reduction) / Job Size`. Items below RS 3.0 get deferred, below 1.5 get dropped.
 
-**Output:** `.planning/superplan_<date>.md` — the prioritized work list that `/pan:focus-plan` reads.
+**Output:** the prioritized work list, returned by `pan-tools focus scan` as JSON (`/pan:focus-plan` collects the items again itself).
 
 **Flags:**
 - `--quick` — skip strategic analysis and validation phases
@@ -136,10 +136,10 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 **Modes:**
 | Mode | Budget | Strategy |
 |------|--------|----------|
-| `bugfix` | 40 pts | P0→P1→smallest-first, no features |
+| `bugfix` | 40 pts | One pass over P0→P4 in priority order, smallest first within a priority (P5–P6 excluded; no item-type filter) |
 | `balanced` | 50 pts | 60% stability / 40% features (default) |
 | `features` | 50 pts | 80% features, P0 crashes still mandatory |
-| `full` | 60 pts | All priorities equally weighted |
+| `full` | 60 pts | One pass over every priority in priority order (P0 first, smallest first within a priority) |
 
 **Point system:** XS=1, S=2, M=4, L=10, XL=20 points.
 
@@ -183,8 +183,8 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Flags:**
 - `--readme` — check README only
-- `--commands` — verify command files match implementations
-- `--agents` — verify agent files
+- `--docs` — verify documentation matches implementations
+- `--arch` — verify architecture docs match actual structure
 - `--all` — full sync + auto-fix
 
 ### Standalone: `/pan:focus-design <description>`
@@ -336,7 +336,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:new-project`** — One command: deep questioning → optional domain research (4 parallel agents) → requirements → roadmap. Creates `.planning/` with project.md, roadmap.md, state.md, config.json, requirements.md.
 
-**`/pan:map-codebase`** — Analyze existing codebase before `/pan:new-project`. Creates `.planning/codebase/` with 7 documents (stack, architecture, structure, conventions, testing, integrations, concerns).
+**`/pan:map-codebase`** — Analyze existing codebase before `/pan:new-project`. Creates `.planning/codebase/` with its codebase documents (stack, architecture, structure, conventions, testing, integrations, concerns, relationships, best-practices).
 
 **`/pan:discuss-phase <N>`** — Capture your vision for a phase before planning. Creates context.md.
 
@@ -394,7 +394,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Planning config** (`.planning/config.json`):
 - `commit_docs: true` — commit planning artifacts to git (set `false` + add `.planning/` to `.gitignore` for private planning)
-- `search_gitignored: false` — add `--no-ignore` to ripgrep when `.planning/` is gitignored
+- `search_gitignored: false` — reserved: read by `loadConfig` and reported by `init map-codebase`, but no workflow or agent acts on it (to search a gitignored `.planning/`, add `--no-ignore` to `rg` yourself)
 
 ---
 
@@ -409,10 +409,9 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 ├── config.json           # Workflow & gate configuration
 ├── focus/                # Focus batch files
 │   └── batch-YYYY-MM-DD.json
-├── superplan_*.md        # Focus scan output
 ├── todos/
 │   ├── pending/          # Todos waiting
-│   └── done/             # Completed todos
+│   └── completed/        # Completed todos
 ├── debug/                # Active debug sessions
 │   └── resolved/         # Archived resolved issues
 ├── milestones/           # Archived milestones

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

@@ -27,11 +27,13 @@ Use the most recent session unless `--session <id>` was specified.
 
 If `--session <id>` was specified, use that session ID.
 
+If `--experiment <slug>` was specified, set `EXP` to the harvest folder (the `harvest_path` `/pan:experiment harvest <slug>` printed, `<source-repo>/experiments/<slug>/` by default), add `--cwd "$EXP"` to every `pan-tools` call in this workflow, and read and write every `.planning/optimization/` path below under `$EXP/`.
+
 ## Step 2 — Generate local analysis
 
 Run:
 ```
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id> | --sessions <n>]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id> | --sessions <n>]   # with no active session, pass --session <id> for the session Step 1 chose: a bare call errors "No trace session active"
 ```
 
 This produces `.planning/optimization/reports/{session}-analysis.json`. With `--sessions <n>` it pools the last n sessions into `pooled-<n>-{session}-analysis.json`: a recommendation should explain failures that recur across runs, not one run's accident.
@@ -39,18 +41,18 @@ This produces `.planning/optimization/reports/{session}-analysis.json`. With `--
 Read the output and note:
 - `summary.errors` — how many error events
 - `summary.gaps` — how many gap events
-- `summary.memory_misses` — how many memory miss events
+- `summary.memory_misses` — how many times an agent logged missing knowledge (`memory_miss` events)
 - `summary.wasted_tokens` — tokens wasted on redundancies
 - `top_error_patterns` — most frequent error categories
 - `top_tool_error_patterns` — failed tool calls captured from the subagents' own transcripts, ranked by how many spawns hit them
 - `verdict_stats` — each judge's pass/fail counts, retries, and the retries that resolved a failure
-- `top_memory_misses` — most frequent memory miss topics
+- `top_memory_misses` — the topics most often logged as missing
 
 ## Step 3 — Invoke pan-optimizer agent
 
 Spawn the `pan-optimizer` agent with this instruction:
 
-> Read the analysis at `.planning/optimization/reports/{session}-analysis.json` and the raw trace at `.planning/optimization/traces/{session}/trace.jsonl`. Also read any existing memory at `.planning/memory/*.md` to understand what's already known. Produce a full optimization report at `.planning/optimization/reports/{session}-opt-report.md` following the format in your agent definition.
+> Read the analysis at `{analysis_path}` (the path `optimize learn` printed: `{session}-analysis.json`, or `pooled-<n>-{session}-analysis.json` with `--sessions`) and the raw trace at `.planning/optimization/traces/{session}/trace.jsonl`. Produce a full optimization report at `.planning/optimization/reports/{session}-opt-report.md` following the format in your agent definition.
 
 Wait for the agent to complete. It will write the report to `.planning/optimization/reports/`.
 
@@ -61,9 +63,9 @@ Read `.planning/optimization/reports/{session}-opt-report.md`.
 Present to the user:
 1. **Score** — the circular optimization score (0–100)
 2. **Top 3 findings** — the most impactful recommendations
-3. **Auto-applicable count** — how many items `/pan:optimize apply` can handle automatically
-4. **Review required count** — how many prompt/workflow suggestions need human review
-5. **Next step** — suggest running `/pan:optimize apply` to apply safe optimizations
+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
 
 ## Step 5 — Auto-apply (if --apply flag)
 
@@ -72,14 +74,14 @@ If the `--apply` flag was passed, immediately run:
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize apply
 ```
 
-Show what was applied and what still needs review.
+Show what was recorded and where each suggestion belongs.
 
 ## Step 6 — Update the circular score baseline
 
 After applying, tell the user what to watch in the next run:
-- Which memory gaps were filled (will reduce `memory_miss` events)
-- Which error patterns were documented (will reduce repeat errors if agent reads memory)
-- Prompt/workflow changes to consider applying manually
+- Which lessons they wrote into the project's instructions, tests or code (the next trace should show fewer of those gaps and `memory_miss` events)
+- Which error patterns a prompt or workflow change addressed
+- Prompt/workflow changes still to consider
 
 ## Edge cases
 

package/pan-wizard-core/workflows/map-codebase.md

@@ -3,7 +3,7 @@ Orchestrate parallel codebase mapper agents to analyze codebase and produce stru
 
 Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
 
-Output: .planning/codebase/ folder with 9 structured documents about the codebase state.
+Output: .planning/codebase/ folder with structured documents about the codebase state.
 </purpose>
 
 <philosophy>
@@ -109,7 +109,7 @@ Use Task tool with `subagent_type="pan-document_code"`, `model="{mapper_model}"`
 **CRITICAL:** Use the dedicated `pan-document_code` agent, NOT `Explore`. The mapper agent writes documents directly.
 
 **CRITICAL: Project Scope Boundary — include this line in EVERY agent prompt:**
-> SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+> SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 **Agent 1: Tech Focus**
 
@@ -120,7 +120,7 @@ Task(
   run_in_background=true,
   description="Map codebase tech stack",
   prompt="Focus: tech
-SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 Analyze this codebase for technology stack and external integrations.
 
@@ -142,7 +142,7 @@ Task(
   run_in_background=true,
   description="Map codebase architecture",
   prompt="Focus: arch
-SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 Analyze this codebase architecture and directory structure.
 
@@ -164,7 +164,7 @@ Task(
   run_in_background=true,
   description="Map codebase conventions",
   prompt="Focus: quality
-SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 Analyze this codebase for coding conventions and testing patterns.
 
@@ -185,7 +185,7 @@ Task(
   run_in_background=true,
   description="Map codebase concerns",
   prompt="Focus: concerns
-SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 Analyze this codebase for technical debt, known issues, and areas of concern.
 
@@ -206,7 +206,7 @@ Task(
   run_in_background=true,
   description="Map module relationships",
   prompt="Focus: relationships
-SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 Analyze module dependencies using pre-computed import analysis.
 
@@ -230,7 +230,7 @@ Task(
   run_in_background=true,
   description="Map best practices",
   prompt="Focus: practices
-SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure paths: .claude/, .opencode/, .gemini/, .codex/, .agents/, .planning/, and the Copilot runtime paths PAN installs into under .github/ (agents/, skills/, hooks/, copilot/, pan-wizard-core/, pan-local-patches/, mcp.json, package.json, pan-file-manifest.json)
 
 Assess codebase best practices using pre-computed analysis.
 
@@ -284,7 +284,7 @@ wc -l .planning/codebase/*.md
 ```
 
 **Verification checklist:**
-- All 9 documents exist (lowercase filenames)
+- All codebase documents the mapper prompts list exist (lowercase filenames)
 - No empty documents (each should have >20 lines)
 
 If any documents missing or empty, note which agents may have failed.
@@ -395,7 +395,7 @@ End workflow.
 - Relationships agent receives pre-computed import/dependency data
 - Practices agent receives pre-computed language and best-practices data
 - Read agent output files to collect confirmations
-- All 9 codebase documents exist (lowercase filenames)
+- All codebase documents the mapper prompts list exist (lowercase filenames)
 - Clear completion summary with line counts
 - User offered clear next steps in PAN style
 </success_criteria>

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

@@ -14,7 +14,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init milestone-op)
 ```
 
-Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
+Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`. `{version}` below is the version without its leading `v` (the argument, else `milestone_version` with the `v` removed: `v1.0` → `1.0`), so `v{version}-milestone-audit.md` names the `v1.0-milestone-audit.md` that `/pan:milestone-done` looks for.
 
 **Also extract `planning_root` and `track`, and use `$PLANNING_ROOT` for every planning path in this workflow** — the project may hold several planning trees, and auditing the wrong one produces a confident, plausible, wrong report:
 
@@ -26,7 +26,7 @@ PLANNING_ROOT=$(printf '%s' "$INIT" | node -e "let s='';process.stdin.on('data',
 
 **Always state the resolved `planning_root` at the top of the audit report.** If `planning_root_exists` is `false`, STOP — that is a mistyped `--track`, not an empty milestone.
 
-To audit a specific tree, pass `--track <name>`. To see every tree's milestone state before choosing:
+To audit a specific tree, add `--track <name>` to every `pan-tools` call in this workflow (each call resolves its own planning root). To see every tree's milestone state before choosing:
 
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init milestone-op --all-tracks
@@ -38,12 +38,12 @@ That returns `{track_count, ambiguous_tracks, tracks[]}`, one entry per planning
 
 The init payload carries how the milestone was decided:
 
-- `milestone_basis` — `marked-current` (a `(current)` / 🚧 marker), `first-unshipped`, `last-shipped`, or `default`
+- `milestone_basis` — `marked-current` (a `(current)` / 🚧 marker), `first-unshipped`, `last-shipped`, `state` (state.md's `milestone:`), `no-milestone-heading`, or `default` (no roadmap.md)
 - `milestone_ambiguous` — **`true` means the roadmap marks more than one milestone current**
 
 **If `milestone_ambiguous` is `true`, STOP and report the planning-state error.** Do not audit. Two milestones marked current is a roadmap defect the owner must resolve; picking one silently is how an audit ends up describing a milestone that does not exist.
 
-If `milestone_basis` is `default`, there is no milestone heading in the roadmap at all — say so rather than auditing `v1.0 milestone`.
+If `milestone_basis` is `no-milestone-heading` (no milestone heading, none recorded in state.md) or `default` (no roadmap.md), say so rather than auditing `v1.0 milestone`; `state` means the version came from state.md's `milestone:`.
 
 Resolve integration checker model:
 ```bash
@@ -67,9 +67,9 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list
 For each phase directory, read the verification.md:
 
 ```bash
-# For each phase, use find-phase to resolve the directory (handles archived phases)
-PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase 01 --raw)
-# Extract directory from JSON, then read verification.md from that directory
+# For each phase, find-phase resolves its directory under phases/ (zero-padding handled; archived milestones are not searched)
+PHASE_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase 01 --raw)
+# --raw prints the directory itself (empty when not found); read verification.md from it
 # Repeat for each phase number from roadmap.md
 ```
 
@@ -87,7 +87,7 @@ If a phase is missing verification.md, flag it as "unverified phase" — this is
 What the judges found in this milestone, and what was decided about each finding, is on record. Read it rather than reconstructing it from prose:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings debt --milestone "{version}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings debt --milestone "{version}"   # with or without the leading v
 ```
 
 - **`deferred`** findings were continued past on purpose, and each carries the reason recorded at the time. They are the milestone's tech debt: put every one in `tech_debt`, with its id and reason.
@@ -115,7 +115,7 @@ MUST map each integration finding to affected requirement IDs where applicable.
 
 Verify cross-phase wiring and E2E user flows.",
   subagent_type="pan-integration-checker",
-  model="{integration_checker_model}"
+  model="{CHECKER_MODEL}"
 )
 ```
 
@@ -145,7 +145,7 @@ For each phase's verification.md, extract the expanded requirements table:
 For each phase's summary.md, extract `requirements-completed` from YAML frontmatter:
 ```bash
 for summary in "$PLANNING_ROOT"/phases/*-*/*-summary.md; do
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs frontmatter get "$summary" --field requirements-completed --raw
 done
 ```
 

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

@@ -27,15 +27,15 @@ No audit gaps found. Run `/pan:milestone-audit` first.
 
 ## 2. Prioritize Gaps
 
-Group gaps by priority from requirements.md:
+Group gaps by their audit status (requirements.md records no priority; each `gaps.requirements[]` entry carries `status`):
 
-| Priority | Action |
-|----------|--------|
-| `must` | Create phase, blocks milestone |
-| `should` | Create phase, recommended |
-| `nice` | Ask user: include or defer? |
+| Status | Action |
+|--------|--------|
+| `unsatisfied` | Create phase, blocks milestone |
+| `partial` | Create phase, recommended (the audit's FAIL gate forces `gaps_found` only for `unsatisfied` and `orphaned`) |
+| `orphaned` | Create phase, blocks milestone (the audit treats an orphaned requirement as unsatisfied) |
 
-For integration/flow gaps, infer priority from affected requirements.
+For integration/flow gaps, take the status of the requirements they affect.
 
 ## 3. Group Gaps into Phases
 
@@ -65,8 +65,7 @@ Gap: Flow "View dashboard" broken at data fetch
 Find highest existing phase:
 ```bash
 # Get sorted phase list, extract last one
-PHASES=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list)
-HIGHEST=$(echo "$PHASES" | jq -r '.directories[-1]')
+HIGHEST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list --raw | tail -1)
 ```
 
 New phases continue from there:
@@ -94,9 +93,9 @@ Closes:
 - Flow: {flow name}
 Tasks: {count}
 
-{If nice-to-have gaps exist:}
+{If partial gaps exist:}
 
-### Deferred (nice-to-have)
+### Recommended (partial — not one of the gaps that force the audit's `gaps_found`)
 
 These gaps are optional. Include them?
 - {gap description}
@@ -111,18 +110,14 @@ Wait for user confirmation.
 
 ## 6. Update roadmap.md
 
-Add new phases to current milestone:
+Add each new phase with the CLI, which writes its checklist line (what `phase complete` ticks), its `### Phase N:` section and its directory:
 
-```markdown
-### Phase {N}: {Name}
-**Goal:** {derived from gaps being closed}
-**Requirements:** {REQ-IDs being satisfied}
-**Gap Closure:** Closes gaps from audit
-
-### Phase {N+1}: {Name}
-...
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase add "{Name}"
 ```
 
+Then edit the new section: set **Goal:** to {derived from gaps being closed}, **Requirements:** to {REQ-IDs being satisfied}, and add `**Gap Closure:** Closes gaps from audit`.
+
 ## 7. Update requirements.md Traceability Table (REQUIRED)
 
 For each REQ-ID assigned to a gap closure phase:
@@ -140,9 +135,7 @@ grep -c "Pending" .planning/requirements.md
 
 ## 8. Create Phase Directories
 
-```bash
-mkdir -p ".planning/phases/{NN}-{name}"
-```
+`phase add` (step 6) already created each phase's directory.
 
 ## 9. Commit Roadmap and Requirements Update
 
@@ -261,7 +254,7 @@ becomes:
 
 <success_criteria>
 - [ ] milestone-audit.md loaded and gaps parsed
-- [ ] Gaps prioritized (must/should/nice)
+- [ ] Gaps grouped by audit status (unsatisfied and orphaned block the milestone, partial is recommended)
 - [ ] Gaps grouped into logical phases
 - [ ] User confirmed phase plan
 - [ ] roadmap.md updated with new phases

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

@@ -58,20 +58,21 @@ Update Active requirements section and "Last updated" footer.
 ```markdown
 ## Current Position
 
-Phase: Not started (defining requirements)
-Plan: —
-Status: Defining requirements
-Last activity: [today] — Milestone v[X.Y] started
+**Current Phase:** Not started (defining requirements)
+**Current Plan:** —
+**Status:** Defining requirements
+**Last Activity:** [today]
+**Last Activity Description:** Milestone v[X.Y] started
 ```
 
 Keep Accumulated Context section from previous milestone.
 
 ## 6. Cleanup and Commit
 
-Delete MILESTONE-context.md if exists (consumed).
+Delete MILESTONE-context.md if exists (consumed). If git tracks it, add its path to `--files` so the deletion is committed (`--force` confirms it; a tracked deletion blocks the commit otherwise):
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files .planning/project.md .planning/state.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files .planning/project.md .planning/state.md [path of the deleted MILESTONE-context.md, if git tracked it] --force
 ```
 
 ## 7. Load Context and Resolve Models

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

@@ -34,7 +34,7 @@ Before scaffolding or coding anything, confirm with the user:
 
 **Do NOT proceed** until the user has answered. Do not assume, research, or fill in blanks yourself. The user's intent drives everything — skipping this step leads to wasted scaffolding and mis-aligned implementation.
 
-Save answers to `.planning/requirements.md` (or update if exists). Confirm with the user before scaffolding.
+Ask these after Step 1's checks (Step 1 runs before any user interaction) and carry the answers into project.md (Step 4); requirements.md is written in Step 7 from its template. Confirm with the user before scaffolding.
 
 > **Auto mode exception:** If `--auto` is set with a provided idea document (see `<auto_mode>` below), the document IS the Phase 0 answer. Read it carefully and extract problem / success / scope / constraints from its contents.
 
@@ -46,7 +46,7 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **If auto mode:**
 - Skip brownfield mapping offer (assume greenfield)
 - Skip deep questioning (extract context from provided document)
-- Config: YOLO mode is implicit (skip that question), but ask depth/git/agents FIRST (Step 2a)
+- Config: YOLO mode is implicit; depth, git and agents take their defaults (or idea.md frontmatter overrides) silently in Step 2a — no questions
 - After config: run Steps 6-9 automatically with smart defaults:
   - Research: Always yes
   - Requirements: Include all table stakes + features from provided document
@@ -92,7 +92,7 @@ git init
 
 ## 2. Brownfield Offer
 
-**If auto mode:** Skip to Step 4 (assume greenfield, synthesize project.md from provided document).
+**If auto mode:** Skip to Step 2a (assume greenfield); Step 2a applies the config defaults and continues at Step 4, which synthesizes project.md from the provided document.
 
 **If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
 
@@ -985,7 +985,7 @@ Use AskUserQuestion:
   - .planning/roadmap.md (Current roadmap to revise)
   </files_to_read>
 
-  Update the roadmap based on feedback. Edit files in place.
+  Update the roadmap based on feedback: rewrite each changed file with one Write.
   Return ROADMAP REVISED with changes made.
   </revision>
   ", subagent_type="pan-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
@@ -1016,7 +1016,7 @@ Parse JSON for `project_types` and `recommendations` arrays.
 **If auto mode (P-1601 v3.7.5):** Auto-select ONLY `priority: "high"` recommendations. These are recommendations from explicitly-detected non-general project types (e.g., a recognized `web` or `ai` project). For `general` fallback projects with no explicit type signal, **skip auto-selection entirely** — leave `standards.md` absent rather than impose unrelated standards.
 
 ```bash
-HIGH_IDS=$(echo "$RECOMMEND" | jq -r '.recommendations[] | select(.priority=="high") | .id')
+HIGH_IDS=$(printf '%s' "$RECOMMEND" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log((JSON.parse(s).recommendations||[]).filter(r=>r.priority==='high').map(r=>r.id).join('\n')))")
 if [ -n "$HIGH_IDS" ]; then
   for id in $HIGH_IDS; do
     node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards select "$id"
@@ -1036,10 +1036,10 @@ Present recommendations:
 
 Based on your project type ([types]), these standards are recommended:
 
-| Standard | Category | Why |
+| Standard | Priority | Why |
 |----------|----------|-----|
-| [name] | [category] | [description] |
-| [name] | [category] | [description] |
+| [name] | [priority] | [reason] |
+| [name] | [priority] | [reason] |
 ```
 
 Use AskUserQuestion:
@@ -1047,7 +1047,7 @@ Use AskUserQuestion:
 - question: "Which standards would you like to apply? (advisory — guides agents, doesn't block)"
 - multiSelect: true
 - options: (from recommendations, max 4)
-  - "[standard name]" — [description]
+  - "[standard name]" — [reason]
 
 For each selected standard:
 ```bash
@@ -1110,7 +1110,7 @@ Present completion summary:
 ╚══════════════════════════════════════════╝
 ```
 
-Exit skill and invoke SlashCommand("/pan:discuss-phase 1 --auto")
+Spawn discuss-phase for Phase 1 as a Task subagent, exactly as transition.md Route A does for a phase with no context.md (discuss-phase.md as execution_context, `ARGUMENTS='1 --auto'`); do not call SlashCommand.
 
 **If interactive mode:**
 

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

@@ -6,8 +6,8 @@ Manage the circular optimization loop — apply reports, check stats, control tr
 
 | Subcommand | Action |
 |------------|--------|
-| `apply` | Apply safe recommendations from most recent report |
-| `apply --report <file>` | Apply from a specific report |
+| `apply` | Record the suggestions from the most recent report |
+| `apply --report <file>` | Record them from a specific report |
 | `revert <apply_id>` / `revert --last` | Undo one apply exactly |
 | `list` | List all reports |
 | `stats` | Show cumulative stats |
@@ -40,17 +40,17 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize apply [--report <path>
 ### Step 3 — Present results
 
 Show the user:
-- **Applied** — each item that was written (memory entries, notes)
+- **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 review** — prompt/workflow suggestions in `suggestions.md`
+- **Still needs a person** — every suggestion in `suggestions.md`
 - **The `apply_id`**, and how to undo the apply: `/pan:optimize revert <apply_id>`
 
-If memory entries were written, tell the user:
-> Memory entries have been added to `.planning/memory/`. They will be loaded on the next agent run, reducing future memory misses for these topics.
+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.
 
 ### Step 4 — Point to manual review items
 
 If `.planning/optimization/suggestions.md` exists, tell the user to review it for:
+- Lessons (apply by writing them into the project's CLAUDE.md or AGENTS.md outside PAN's section, a test, or a comment at the cited code)
 - Agent prompt improvements (apply by editing `agents/pan-*.md`)
 - Workflow step additions (apply by editing `pan-wizard-core/workflows/*.md`)
 
@@ -125,7 +125,7 @@ Active session:         sess_... (or none)
 ```
 
 If `total_optimizations_applied` > 0, note:
-> {N} optimizations have been applied across {apply_runs} apply runs. Each applied memory entry reduces future knowledge gaps.
+> {N} suggestions have been recorded across {apply_runs} apply runs. Each helps once a person has written it where the agents read.
 
 ---
 
@@ -142,11 +142,13 @@ Every agent spawn → hook logs completion event
                           ↓
               .planning/optimization/reports/{session}-opt-report.md
                           ↓
-             /pan:optimize apply → writes memory entries
+             /pan:optimize apply → records suggestions
+                          ↓
+     A person writes each one where the agents read it
                           ↓
          Next build has better context → fewer errors/gaps
                           ↓
                   (repeat, improving each time)
 ```
 
-The key insight: each apply run populates `.planning/memory/` with cached knowledge. Future agent runs load this memory and skip the research/inference that caused gaps. The error rate trends down. The optimization score trends up.
+The key insight: a lesson changes the next run only from a place the next run's agents read: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test that fails when it is broken, or the code itself. PAN's workflows do not load `.planning/memory/` into agents (ADR-0036, amended `2026-10-04`). In the harness, a lesson recorded there changed nothing that the project's state, summaries and code did not already carry. The report says where each suggestion belongs, and a person puts it there.

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

@@ -91,8 +91,13 @@ timestamp=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs current-timestamp f
 </step>
 
 <step name="commit">
+Record the stopping point in state.md too: the context monitor's note sends agents here to make state.md say where they are, and after a compaction PAN re-injects state.md's Stopped At and Resume File, not the handoff file.
+
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state record-session \
+  --stopped-at "Phase [XX] plan [P], task [X]/[Y] — next: [next_action]" \
+  --resume-file ".planning/phases/[XX-name]/.continue-here.md"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/state.md
 ```
 </step>
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Generate unit and E2E tests for a completed phase based on its summary.md, context.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+Generate unit and E2E tests for a completed phase based on its summary.md, context.md, and implementation. Classifies each changed file into TDD (unit), Integration, E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
 Users currently hand-craft `/pan:quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
 </purpose>
@@ -70,7 +70,7 @@ Extract the list of files modified by the phase from summary.md ("Files Changed"
 
 **CRITICAL: Project Scope Boundary**
 Skip any files inside PAN infrastructure directories — these are NOT project source code:
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/`, `.planning/`
+- `.claude/`, `.opencode/`, `.gemini/`, `.codex/`, `.agents/`, `.planning/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`)
 If all changed files are inside these directories, report "No project source files to test" and exit.
 
 For each file, classify into one of four categories:
@@ -334,7 +334,7 @@ Create a test coverage report and present to user:
 
 Record test generation in project state:
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state-snapshot
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Last Activity Description" "Phase ${phase_number} tests generated"
 ```
 
 If there are passing tests to commit:
@@ -374,7 +374,7 @@ Present next steps:
 
 <success_criteria>
 - [ ] Phase artifacts loaded (summary.md, context.md, optionally verification.md)
-- [ ] All changed files classified into TDD/E2E/Skip categories
+- [ ] All changed files classified into TDD/Integration/E2E/Skip categories
 - [ ] Classification presented to user and approved
 - [ ] Project test structure discovered (directories, conventions, runners)
 - [ ] Test plan presented to user and approved