pan-wizard 3.33.0 → 3.35.0

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
 
@@ -64,9 +64,8 @@ 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 phase number in roadmap.md — the same source `phase add` numbers from
+HIGHEST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap analyze | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const n=JSON.parse(s).phases.map(p=>parseInt(p.number,10)).filter(Number.isFinite);console.log(n.length?Math.max(...n):0)})")
 ```
 
 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):
 
@@ -525,9 +525,7 @@ Display spawning indicator:
 Spawn 4 parallel pan-project-researcher agents with path references:
 
 ```
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
-
-<research_type>
+Task(prompt="<research_type>
 Project Research — Stack dimension for [domain].
 </research_type>
 
@@ -563,11 +561,9 @@ Your stack.md feeds into roadmap creation. Be prescriptive:
 Write to: .planning/research/stack.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/stack.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
-
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Stack research")
 
-<research_type>
+Task(prompt="<research_type>
 Project Research — Features dimension for [domain].
 </research_type>
 
@@ -603,11 +599,9 @@ Your features.md feeds into requirements definition. Categorize clearly:
 Write to: .planning/research/features.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/features.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Features research")
 
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
-
-<research_type>
+Task(prompt="<research_type>
 Project Research — Architecture dimension for [domain].
 </research_type>
 
@@ -643,11 +637,9 @@ Your architecture.md informs phase structure in roadmap. Include:
 Write to: .planning/research/architecture.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/architecture.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
-
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Architecture research")
 
-<research_type>
+Task(prompt="<research_type>
 Project Research — Pitfalls dimension for [domain].
 </research_type>
 
@@ -683,7 +675,7 @@ Your pitfalls.md prevents mistakes in roadmap/planning. For each pitfall:
 Write to: .planning/research/pitfalls.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/pitfalls.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Pitfalls research")
 ```
 
 After all 4 agents complete, spawn synthesizer to create summary.md:
@@ -1016,7 +1008,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 +1028,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 +1039,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 +1102,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