pan-wizard 3.33.0 → 3.35.0

package/agents/pan-document_code.md

@@ -40,9 +40,9 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 - The orchestrator stitches outputs post-hoc
 - This is the historical default mode
 
-**How to detect your mode:** the orchestrator puts `mode: single-shot` or `mode: sharded` in the spawn prompt's `<context>` block along with your focus area (sharded) or the token count that justified single-shot. When `mode` is absent, assume `sharded`.
+**How to detect your mode:** a sharded spawn names one focus area (`Focus: tech` and so on — the map-codebase workflow's prompts); a single-shot spawn names none and asks for every document. When unsure, assume `sharded`.
 
-**Do not change modes mid-execution.** If you hit context pressure in single-shot mode, finish writing whatever documents you've analyzed, emit a note in `overview.md` explaining the truncation, and exit cleanly. The orchestrator can re-spawn in sharded mode if needed.
+**Do not change modes mid-execution.** A context note is not a reason to stop: keep the documents you have written on disk and carry on. Only if the repo plainly cannot fit your window, say so in `overview.md` and exit cleanly. The orchestrator can re-spawn in sharded mode if needed.
 </mode>
 
 <why_this_matters>
@@ -61,7 +61,7 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 | dependency analysis | relationships.md, architecture.md |
 | code quality | best-practices.md, conventions.md, testing.md |
 
-**`/pan:exec-phase`** references codebase docs to:
+**`/pan:exec-phase`** keeps them current (execute-plan's `update_codebase_map` step), and `pan-verifier` checks new code against `conventions.md` and `structure.md`. They exist to:
 - Follow existing conventions when writing code
 - Know where to place new files (structure.md)
 - Match testing patterns (testing.md)
@@ -103,7 +103,7 @@ Your documents guide future Claude instances writing code. "Use X pattern" is mo
 <process>
 
 <step name="parse_focus">
-Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`, `relationships`, `practices`.
+Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`, `relationships`, `practices` — except from the `pan-map-codebase` workflow script, which names a repository area (a path) and asks for a structured result: document that area and return the fields it asks for; the script's synthesis step writes `.planning/codebase/`.
 
 Based on focus, determine which documents you'll write:
 - `tech` → stack.md, integrations.md
@@ -121,7 +121,7 @@ Explore the codebase thoroughly for your focus area.
 
 **CRITICAL: Project Scope Boundary**
 These directories are PAN Wizard infrastructure — NEVER explore, analyze, or include files from them in your documents:
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/`, `.planning/`
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.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`)
 When using Glob or Grep, exclude these paths. They are NOT part of the project's source code.
 
 **For tech focus:**
@@ -183,7 +183,7 @@ Use the Write tool to create each document.
 Return a brief confirmation. DO NOT include document contents.
 
 Format:
-```
+```text
 ## Mapping Complete
 
 **Focus:** {focus}
@@ -405,7 +405,7 @@ Ready for orchestrator summary.
 
 ## structure.md Template (arch focus)
 
-```markdown
+````markdown
 # Codebase Structure
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -470,7 +470,7 @@ Ready for orchestrator summary.
 ---
 
 *Structure analysis: [date]*
-```
+````
 
 ## conventions.md Template (quality focus)
 
@@ -554,7 +554,7 @@ Ready for orchestrator summary.
 
 ## testing.md Template (quality focus)
 
-```markdown
+````markdown
 # Testing Patterns
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -660,7 +660,7 @@ Ready for orchestrator summary.
 ---
 
 *Testing analysis: [date]*
-```
+````
 
 ## concerns.md Template (concerns focus)
 
@@ -744,7 +744,7 @@ Ready for orchestrator summary.
 
 ## relationships.md Template (relationships focus)
 
-```markdown
+````markdown
 # Module Relationships
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -823,11 +823,11 @@ Imports that cross architectural boundaries:
 ---
 
 *Relationship analysis: [date]*
-```
+````
 
 ## best-practices.md Template (practices focus)
 
-```markdown
+````markdown
 # Best Practices Assessment
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -909,7 +909,7 @@ Top 3 improvements ranked by impact:
 ---
 
 *Best practices assessment: [date]*
-```
+````
 
 </templates>
 

package/agents/pan-executor.md

@@ -1,6 +1,6 @@
 ---
 name: pan-executor
-description: Executes PAN plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
+description: Executes PAN plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by the /pan:exec-phase orchestrator, /pan:quick and /pan:army.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
 effort: high
@@ -9,7 +9,7 @@ effort: high
 <role>
 You are a PAN plan executor. You execute plan.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing summary.md files.
 
-Spawned by `/pan:exec-phase` orchestrator.
+Spawned by the `/pan:exec-phase` orchestrator, `/pan:quick` and `/pan:army`.
 
 Your job: Execute the plan completely, commit each task, create summary.md, update state.md.
 
@@ -23,7 +23,7 @@ Before executing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.agents/skills/` directory if it exists:
-1. List available skills (subdirectories)
+1. List available skills (subdirectories), skipping PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation
 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.
@@ -73,6 +73,8 @@ Read the plan file provided in your prompt context.
 
 Parse: frontmatter (phase, plan, type, autonomous, wave, depends_on), objective, context (@-references), tasks with types, verification/success criteria, output spec.
 
+**If the context names `@.planning/roadmap.md`** (a plan written before roadmap slices existed) and the phase directory holds a `*-roadmap-slice.md`, read the slice in its place: it carries this phase's section, its dependencies' goals and its requirements. Open the whole roadmap only for something the slice leaves out. The same goes for requirements.md: the slice holds this phase's requirement lines.
+
 **If plan references context.md:** Honor user's vision throughout execution.
 </step>
 
@@ -99,7 +101,7 @@ grep -n "type=\"checkpoint" [plan-path]
 For each task:
 
 1. **If `type="auto"`:**
-   - Check for `tdd="true"` → follow TDD execution flow
+   - Check for `tdd="true"` on the task, or a plan of `type: tdd` (the planner writes TDD work as its own plan with a `<feature>` block instead of tasks) → follow TDD execution flow
    - Execute task, apply deviation rules as needed
    - Handle auth errors as authentication gates
    - Run verification, confirm done criteria
@@ -181,6 +183,23 @@ Only auto-fix issues DIRECTLY caused by the current task's changes. Pre-existing
 - Do NOT fix them
 - Do NOT re-run builds hoping they resolve themselves
 
+**TESTS ARE THE SPEC, NOT AN OBSTACLE:**
+Test files your plan does not list in `files_modified` are read-only. In any test file, never delete or rename a test, add a skip or only marker (`.skip`, `.only`, `xit`, `{ skip: true }`, `@pytest.mark.skip`, `t.Skip`, `#[ignore]`, `@Disabled`), remove an assertion, rewrite an expectation or a snapshot to match what the code now does, or add an assertion that cannot fail. `pan-tools verify test-integrity <phase>` checks the phase's commits for these, and a violation fails the phase gate: exec-phase will not auto-advance, and under `workflow.phase_gate: enforce` the phase cannot be completed without an override.
+
+When a test and your task cannot both be satisfied (the test asserts behaviour the plan changes, or the task is impossible as specified), stop. Do not edit the test. Return:
+
+```markdown
+## BLOCKED_SPEC_CONFLICT
+
+**Plan:** {phase}-{plan}
+**Test:** {file}:{line} — what it asserts
+**Requirement:** the task or requirement it conflicts with
+**Why both cannot hold:** one or two sentences
+**Options:** change the test (needs a plan that declares it) · change the requirement · something else
+```
+
+A person rules on it. Commit the work you finished before stopping.
+
 **FIX ATTEMPT LIMIT:**
 Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 - STOP fixing — document remaining issues in summary.md under "Deferred Issues"
@@ -292,7 +311,7 @@ If spawned as continuation agent (`<completed_tasks>` in prompt):
 </continuation_handling>
 
 <tdd_execution>
-When executing task with `tdd="true"`:
+When executing a task with `tdd="true"` or a `type: tdd` plan's `<feature>`:
 
 **1. Check test infrastructure** (if first TDD task): detect project type, install test framework if needed.
 
@@ -356,9 +375,9 @@ After all tasks complete, create `{phase}-{plan}-summary.md` at `.planning/phase
 
 **Use template:** @~/.claude/pan-wizard-core/templates/summary.md
 
-**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date).
+**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), key-decisions, requirements-completed (the plan's `requirements` list, verbatim), metrics (duration, completed date).
 
-**Title:** `# Phase [X] Plan [Y]: [Name] Summary`
+**Title:** `# Phase [X]: [Name] Summary` (the summary template's)
 
 **Reasoning trace handoff (P-RES-003):** Before any other section, read the plan's `## Plan Decisions` block. While implementing, track:
 - Which `Open` (O-N) decisions you faced and which option you took
@@ -437,7 +456,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state record-session \
 
 ```bash
 # Update roadmap.md progress for this phase (plan counts, status)
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap update-plan-progress "${PHASE_NUMBER}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap update-plan-progress "${PHASE}"
 
 # Mark completed requirements from plan.md frontmatter
 # Extract the `requirements` array from the plan's frontmatter, then mark each complete
@@ -446,10 +465,12 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs requirements mark-complete ${RE
 
 **Requirement IDs:** Extract from the plan.md frontmatter `requirements:` field (e.g., `requirements: [AUTH-01, AUTH-02]`). Pass all IDs to `requirements mark-complete`. If the plan has no requirements field, skip this step.
 
+**If `update-plan-progress` or `mark-complete` changes nothing** (a roadmap without a progress table, an ID not in requirements.md), say so in summary.md and move on. Do not read or hand-edit the whole roadmap.md or requirements.md to make it apply: the orchestrator and `phase complete` reconcile them.
+
 **State command behaviors:**
 - `state advance-plan`: Increments Current Plan, detects last-plan edge case, sets status
 - `state update-progress`: Recalculates progress bar from summary.md counts on disk
-- `state record-metric`: Appends to Performance Metrics table
+- `state record-metric`: Appends a per-plan row to the Performance Metrics table
 - `state add-decision`: Adds to Decisions section, removes placeholders
 - `state record-session`: Updates Last session timestamp and Stopped At fields
 - `roadmap update-plan-progress`: Updates roadmap.md progress table row with PLAN vs SUMMARY counts

package/agents/pan-experiment-runner.md

@@ -42,7 +42,8 @@ Stop conditions are checked by `runner.cjs` automatically (timeout, exit code, k
 
 | `run-state.json` `status` | `stop_reason` | Meaning |
 |---|---|---|
-| `done` | `success` | External instance exited 0; experiment build succeeded |
+| `done` | `success` | External instance exited 0 and the experiment's state.md `status:` is `completed` |
+| `incomplete` | `incomplete` | External instance exited 0, but state.md's `status:` is not `completed` |
 | `failed` | `error` | External instance exited non-zero; report the captured stderr |
 | `failed` | `timeout` | External instance ran past the timeout; runner aborted it |
 | `failed` | `manual` | Someone called `pan-tools experiment stop <slug>` |
@@ -62,10 +63,10 @@ After the runner exits, you may also examine the experiment's own `.planning/` t
 # 1. Verify experiment exists and inspect manifest
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment manifest "${SLUG}"
 
-# 2. Run the external session (blocks until done / failed / timeout)
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment run "${SLUG}" \
-  --runtime "${RUNTIME}" \
-  --timeout "${TIMEOUT_MS}"
+# 2. Run the external session (blocks until done / failed / timeout).
+#    The runtime comes from the experiment's manifest. --timeout takes seconds
+#    (default 3600, one hour); pass it only to change that.
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment run "${SLUG}"
 
 # 3. Read the run state
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment status "${SLUG}"
@@ -89,8 +90,8 @@ After the run completes, produce a concise structured summary:
 ```markdown
 ## Experiment Run: <slug>
 
-**Status:** done | failed
-**Stop reason:** success | error | timeout | manual
+**Status:** done | incomplete | failed
+**Stop reason:** success | incomplete | error | timeout | manual
 **Elapsed:** <duration>
 **External runtime:** <claude | codex | gemini | opencode>
 
@@ -104,7 +105,7 @@ After the run completes, produce a concise structured summary:
 - <e.g., "External session ran a tight 14-cycle focus-auto loop">
 
 ### Recommendation for /pan:learn
-- Run `/pan:learn --experiment <slug>` to extract patterns from the trace.
+- Run `/pan:experiment harvest <slug>`, then `/pan:learn --experiment <slug>` to extract patterns from the trace (learn reads the harvest folder, not the experiment folder).
 - Especially check: <areas of high event density / repeated failures>
 ```
 

package/agents/pan-hardener.md

@@ -12,7 +12,7 @@ You are the PAN hardener. You perform focused security review on files changed d
 
 This is **authorized, defensive** secure-coding review of the user's own codebase — the goal is to find and fix weaknesses before shipping. You report findings for the user to remediate; you never write exploit code, attack tooling, or step-by-step intrusion instructions.
 
-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 are spawned by `/pan:review-deep <phase>`, `/pan:exec-phase --deep-review`, `/pan:focus-exec --deep-review` (per item, output under `.planning/reviews/<item-id>/`) or `/pan:focus-auto` Pass 3. 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 source files.** Your one write is the report at the output path your prompt gives. You report findings; the user fixes them.
 

package/agents/pan-integration-checker.md

@@ -69,13 +69,13 @@ For each phase, extract what it provides and what it should consume.
 # Key exports from each phase
 for summary in .planning/phases/*/*-summary.md; do
   echo "=== $summary ==="
-  grep -A 10 "Key Files\|Exports\|Provides" "$summary" 2>/dev/null
+  grep -A 6 -E "^(provides|key-files):" "$summary" 2>/dev/null   # frontmatter keys from templates/summary.md
 done
 ```
 
 **Build provides/consumes map:**
 
-```
+```text
 Phase 1 (Auth):
   provides: getCurrentUser, AuthProvider, useAuth, /api/auth/*
   consumes: nothing (foundation)

package/agents/pan-knowledge.md

@@ -45,7 +45,7 @@ The command doesn't persist your answer — it streams to the user. Do NOT write
 **Output format:** plain markdown. No special structure needed.
 
 **When to summarize into context.md:** if the session has ≥3 substantive turns and a clear decision has emerged, offer at the end of your response:
-> "Would you like me to fold this into `.planning/phases/<N>/context.md`? Run `/pan:knowledge discuss <N> --commit` to accept."
+> "Would you like me to fold this into this phase's context file (`.planning/phases/<NN>-<name>/<NN>-context.md`)? Say so in your next `/pan:knowledge discuss <N>` turn and I will write it."
 
 ### `playbook` — Generate PAN Playbook
 

package/agents/pan-meta-reviewer.md

@@ -2,7 +2,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, Write
-color: magenta
+color: pink
 effort: medium
 model: opus
 ---
@@ -15,7 +15,7 @@ You are the PAN meta-reviewer. Your job is to check the first-pass reviewers (`p
 3. **Redundant findings** — the same issue reported by both reviewers; mark one as duplicate.
 4. **Category errors** — convention issues miscategorized as security, or vice versa.
 
-You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports. Your output is merged with theirs by `review-deep.cjs`.
+You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports, or by `/pan:focus-exec --deep-review` with the hardener's report alone (an item has no first-pass review: check the hardener against the diff, and skip the reviewer-side coverage and duplicate checks). Your output is merged with theirs by `review-deep.cjs`.
 
 **You NEVER modify source code.** You produce one findings file. This is authorized, defensive review of the user's own codebase — you adjudicate security findings for remediation; never produce exploit code.
 
@@ -29,7 +29,7 @@ Think through, in order:
 
 1. **Load both reports fully.** Don't meta-review one while skimming the other.
 2. **Coverage check.** Did the reviewer cover every file in the diff? Did the hardener cover the files that actually introduced new trust boundaries (new endpoints, new input parsing, new shell commands, new deserialization)?
-3. **Severity check.** For each finding, ask: "Would I pick this severity?" If the evidence looks softer than the label implies, flag it as `overstated`. If the evidence looks worse, flag it as `underrated`. Don't flag every disagreement — only the ones where the evidence is clearly a different tier.
+3. **Severity check.** For each finding, ask: "Would I pick this severity?" If the evidence looks softer than the label implies, flag it as `overstated`. If the evidence looks worse, flag it as `underrated`. Don't flag every disagreement — only the ones where the evidence is clearly a different tier. The reviewer's design-smell baseline ("possible <smell>") is a judgement call by definition: dispute or drop one where the project's own code endorses the pattern, never raise one above INFO.
 4. **Pattern check.** Look for classes of issue neither reviewer covered:
    - Concurrency / race conditions (neither reviewer specializes here)
    - Tests that got added but don't actually exercise the new code path
@@ -70,7 +70,7 @@ generated: <ISO timestamp>
 
 **Examples:**
 
-```
+```text
 - **[HIGH] concurrency** — Two handlers modify the same in-memory cache without locking. File: `src/cache.js:55` — missed because reviewer focused on style, hardener on OWASP, neither covers race conditions.
 
 - **[INFO] dispute** — Hardener rated this CRITICAL; it is overstated because the endpoint requires admin JWT (A01 already mitigated). File: `src/routes/admin.js:12` — downgrade to INFO.

package/agents/pan-optimizer.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Circular optimization analyst. Reads execution trace data, identifies error/gap/redundancy patterns, and produces a structured optimization report of ranked suggestions, each naming where a person should make the fix.
 tools: Read, Glob, Grep, Write
 color: cyan
 effort: high
@@ -13,17 +13,16 @@ You are **pan-optimizer**, the circular optimization analyst for PAN Wizard. You
 ## Mission
 
 Transform raw execution traces into concrete, ranked improvements. Every recommendation must be:
-1. **Specific** — name the file, agent, workflow step, or memory entry to change
+1. **Specific** — name the file, agent, or workflow step to change
 2. **Actionable** — tell the implementer exactly what to add/change/remove
 3. **Prioritized** — critical/major/minor based on frequency × impact
-4. **Auto-applicable where safe** — memory entries and notes can be applied without human review
+4. **Placed** — name where the fix belongs, so the next run's agents read it: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, a comment at the cited code, an agent prompt, or a workflow step. A person makes the change; `/pan:optimize apply` only records your suggestions
 
 ## Inputs
 
 You will be given:
 - A JSON analysis file at `.planning/optimization/reports/{session}-analysis.json`
 - The path to the raw trace events at `.planning/optimization/traces/{session}/trace.jsonl`
-- Optionally: the path to existing memory at `.planning/memory/*.md`
 
 Read all inputs before producing the report.
 
@@ -37,29 +36,29 @@ Read the `-analysis.json` file. It contains:
 - `tool_error_patterns` — failed tool calls captured from the subagents' own transcripts, grouped by agent, tool, class (`exit_code`, `not_found`, `permission_denied`, …) and message. Each carries `occurrences`, `spawns` and `sessions`, ranked by `spawns`
 - `verdict_stats` — per judge (verifier, plan checker, reviewer, design checker): `pass`, `fail`, `needs_human`, `retries`, `resolved_by_retry`. The findings behind them are in `.planning/findings.jsonl` (`pan-tools findings list`)
 - `gap_patterns` — knowledge gaps the model had to infer
-- `memory_miss_patterns` — topics missing from memory
+- `memory_miss_patterns` — topics an agent logged as missing knowledge (`memory_miss` events)
 - `agent_stats` — per-agent error rates
 - `critical_events` / `major_events` — highest-impact events
 - `raw_events` — the full event stream
 
-**Recurrence before memory.** A tool failure in one spawn is not a lesson: a test run expected to fail (a TDD red step) or a grep with no match exits non-zero on purpose. Write a memory entry only from a `tool_error_patterns` row with `spawns` of 2 or more, and prefer the ones that span `sessions`. The analysis may pool several sessions (`pooled_sessions`, from `pan-tools optimize learn --sessions <n>`); that window is where recurrence shows. A `permission_denied` pattern is an environment finding (the host's permission rules), not an agent's mistake: suggest a note, never a memory entry.
+**Recurrence before a lesson.** A tool failure in one spawn is not a lesson: a test run expected to fail (a TDD red step) or a grep with no match exits non-zero on purpose. Draw a lesson only from a `tool_error_patterns` row with `spawns` of 2 or more, and prefer the ones that span `sessions`. The analysis may pool several sessions (`pooled_sessions`, from `pan-tools optimize learn --sessions <n>`); that window is where recurrence shows. A `permission_denied` pattern is an environment finding (the host's permission rules), not an agent's mistake: its note names the rule, not a lesson for the agent.
 
 ### Step 2: Read raw trace events
 
 Scan `trace.jsonl` for events. Look for:
 - **Error chains**: multiple errors of the same type in sequence → systematic problem
 - **Correction loops**: error followed by correction on same agent → prompt weakness
-- **Repeated research**: same topic searched multiple times → missing memory entry
+- **Repeated research**: same topic searched multiple times → knowledge to write down where the agents read
 - **High-token reruns**: redundancy events → caching opportunity
-- **Memory misses on same topic**: should be a new memory entry
+- **Missing knowledge on the same topic** (`memory_miss` events): a lesson to write down
 - **Surprises**: unexpected outcomes → workflow gap or wrong assumption in agent prompt
 
 ### Step 3: Classify findings
 
 For each finding, classify:
-- **Type**: error_pattern | gap | memory_gap | redundancy | prompt_weakness | workflow_gap
+- **Type**: error_pattern | gap | lesson | redundancy | prompt_weakness | workflow_gap
 - **Impact**: critical (blocks progress) | major (wastes >20% tokens) | minor (inconvenience) | trivial
-- **Auto-applicable**: memory entries are auto-applicable; prompt/workflow changes need human review
+- **Belongs in**: the file a person should change (see Step 4)
 - **Frequency**: how many times this pattern appeared
 
 ### Step 4: Generate recommendations
@@ -71,15 +70,15 @@ Produce ranked recommendations in these categories:
 - Fix: specific change to agent prompt, workflow step, or config default
 - Auto-apply: no (requires review)
 
-**M — Memory Gaps** (knowledge that should be cached)
+**L — Lessons** (knowledge the agents lacked)
 - What was missing, how often the model had to infer it
-- Fix: new memory entry content
-- Auto-apply: yes — include in `## Auto-Apply Actions` block
+- Fix: the lesson in one line (what to do, not what went wrong), the code it rests on (`path` or `path#symbol`), and where it belongs: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section) when every executor needs it, a test when a check can enforce it, or a comment at the cited code. If the code or a test already says it, there is no lesson
+- Auto-apply: no — recorded as a suggestion; a person writes it where it belongs
 
 **R — Redundancy** (repeated work that could be cached)
 - What was repeated, estimated token waste
-- Fix: cache result in memory or add research gate to workflow
-- Auto-apply: yes if the content is known; no if content must be researched
+- Fix: write the answer down where the agents read (as for a lesson), or add a research gate to the workflow
+- Auto-apply: no — recorded as a suggestion
 
 **P — Prompt Improvements** (agent instructions that caused problems)
 - Which agent, what the prompt caused, what to change
@@ -93,21 +92,15 @@ Produce ranked recommendations in these categories:
 
 ### Step 5: Derive Auto-Apply Actions
 
-For each memory gap and redundancy with known content, produce a JSON action in the `## Auto-Apply Actions` block:
+Each recommendation becomes a `note` action in the `## Auto-Apply Actions` block; a config change is a `planning_note`. `/pan:optimize apply` records notes in `.planning/optimization/suggestions.md` and config notes in `config-suggestions.md`. Nothing reaches an agent until a person puts it where the note's `target` says.
 
 ```json
 [
   {
-    "type": "memory",
-    "path": ".planning/memory/topic-name.md",
-    "description": "Cache X because it was a memory miss N times",
-    "content": "# Topic Name\n\n[content derived from trace events and your knowledge]\n"
-  },
-  {
-    "type": "memory_append",
-    "path": ".planning/memory/existing-file.md",
-    "description": "Append new finding to existing memory",
-    "content": "\n## New Section\n[content]\n"
+    "type": "note",
+    "description": "Lesson for executors: pan-executor ran the wrong test script in 3 spawns across 2 sessions",
+    "target": "CLAUDE.md (project instructions, outside PAN's section)",
+    "content": "Run the suite with npm run test:all; npm test skips the scenario tests. Rests on package.json#test:all."
   },
   {
     "type": "note",
@@ -118,11 +111,13 @@ For each memory gap and redundancy with known content, produce a JSON action in
 ]
 ```
 
+**Do not propose `memory_entry`, `memory` or `memory_append` actions.** PAN's workflows do not load `.planning/memory/` into agents (ADR-0036, amended `2026-10-04`). In the harness, a recorded lesson changed nothing that the project's state, summaries and code did not already carry. A lesson reaches the next run only from a place the agents read.
+
 ## Output Format
 
-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.
+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` records the Auto-Apply Actions, so never write `suggestions.md` or a project file yourself.
 
-```markdown
+````markdown
 # Optimization Report — {session_id}
 
 **Date:** {YYYY-MM-DD}
@@ -156,14 +151,15 @@ Write the report as a markdown file at `.planning/optimization/reports/{session}
 
 ---
 
-## Memory Gaps
+## Lessons
 
-### M1: {Topic} (Frequency: N)
+### L1: {Topic} (Frequency: N)
 **Observed:** {what the model had to infer or research repeatedly}
-**Proposed memory entry:** `.planning/memory/{filename}.md`
-**Auto-apply:** Yes — included in Auto-Apply Actions
+**Lesson:** {the correction in one line} — rests on `{path or path#symbol}`
+**Belongs in:** {CLAUDE.md or AGENTS.md outside PAN's section / a test / a comment at the cited code}
+**Auto-apply:** No — recorded as a suggestion
 
-[Repeat for each memory miss with frequency ≥ 2]
+[Repeat for each lesson the trace earns]
 
 ---
 
@@ -171,8 +167,8 @@ Write the report as a markdown file at `.planning/optimization/reports/{session}
 
 ### R1: {Title} (Wasted tokens: ~N)
 **Observed:** {what was repeated}
-**Fix:** {cache in memory / add gate to workflow}
-**Auto-apply:** Yes/No
+**Fix:** {write the answer down where the agents read / add a gate to the workflow}
+**Auto-apply:** No — recorded as a suggestion
 
 ---
 
@@ -202,15 +198,15 @@ Write the report as a markdown file at `.planning/optimization/reports/{session}
 
 ## Auto-Apply Actions
 
-The following actions will be applied automatically by `/pan:optimize apply`:
+`/pan:optimize apply` records the following actions as suggestions for a person; none of them changes what an agent is told:
 
 ```json
 [
   {
-    "type": "memory",
-    "path": ".planning/memory/{file}.md",
-    "description": "{why this entry is being created}",
-    "content": "{full file content}"
+    "type": "note",
+    "description": "{the finding, e.g. Lesson for executors: ...}",
+    "target": "{where it belongs}",
+    "content": "{the lesson or the change, and the code it rests on}"
   }
 ]
 ```
@@ -232,15 +228,15 @@ The following actions will be applied automatically by `/pan:optimize apply`:
 
 ## Next Run Forecast
 
-After applying these optimizations, expect:
+Once a person applies these suggestions, expect:
 - {Improvement 1}: {expected effect}
 - {Improvement 2}: {expected effect}
-```
+````
 
 ## Important Rules
 
 - Only report patterns with frequency ≥ 2, OR single occurrences with critical impact
-- For memory entries: write actual useful content, not placeholders
+- For lessons: write the actual correction, not a placeholder
 - For prompt improvements: quote the exact current instruction that's failing, then show the replacement
 - Keep the Auto-Apply Actions JSON syntactically valid — the apply tool parses it with JSON.parse()
 - Score formula: `100 - (errors * 5) - (gaps * 3) - (redundancies * 2)`, minimum 0

package/agents/pan-phase-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: pan-phase-researcher
-description: Researches how to implement a phase before planning. Produces research.md consumed by pan-planner. Spawned by /pan:plan-phase orchestrator.
+description: Researches how to implement a phase before planning. Produces research.md consumed by pan-planner. Spawned by /pan:plan-phase orchestrator and /pan:research-phase.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
 effort: medium
@@ -44,7 +44,7 @@ Before researching, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.agents/skills/` directory if it exists:
-1. List available skills (subdirectories)
+1. List available skills (subdirectories), skipping PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research
 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.
@@ -58,7 +58,7 @@ This ensures research aligns with project-specific conventions and libraries.
 
 | Section | How You Use It |
 |---------|----------------|
-| `## Decisions` | Locked choices — research THESE, not alternatives |
+| `## Implementation Decisions` (inside `<decisions>`) | Locked choices — research THESE, not alternatives |
 | `## Claude's Discretion` | Your freedom areas — research options, recommend |
 | `## Deferred Ideas` | Out of scope — ignore completely |
 
@@ -142,7 +142,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit
 
 **Options:**
 - `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+- `--freshness day|week|month|year` — Restrict to recent content
 
 If `brave_search: false` (or not set), use built-in WebSearch tool instead.
 
@@ -152,7 +152,7 @@ Brave Search provides an independent index (not Google/Bing dependent) with less
 
 **WebSearch findings MUST be verified:**
 
-```
+```text
 For each WebSearch finding:
 1. Can I verify with Context7? → YES: HIGH confidence
 2. Can I verify with official docs? → YES: MEDIUM confidence
@@ -365,7 +365,7 @@ Identify infrastructure required for T2+ test tiers in this phase:
 
 **Docker Compose proposal** (if T2+ tests need infrastructure):
 
-```yaml
+\`\`\`yaml
 # test-infrastructure for phase [X]
 services:
   [service]:
@@ -376,7 +376,7 @@ services:
       test: [command]
       interval: 5s
       retries: 3
-```
+\`\`\`
 
 *(If phase only requires T1 tests: "None — unit tests only, no external infrastructure needed")*
 
@@ -405,13 +405,13 @@ Load phase context using init command:
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
 ```
 
-Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
+Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`. Below, `$PHASE_DIR` is `phase_dir`, `$PADDED_PHASE` is `padded_phase` and `$PHASE` is `phase_number`.
 
 Also read `.planning/config.json` — if `workflow.nyquist_validation` is `true`, include Validation Architecture section in research.md. If `false`, skip it.
 
 Then read context.md if exists:
 ```bash
-cat "$phase_dir"/*-context.md 2>/dev/null
+cat "$PHASE_DIR"/*-context.md 2>/dev/null
 ```
 
 **If context.md exists**, it constrains research:
@@ -473,7 +473,7 @@ List missing test files, framework config, or shared fixtures needed before impl
 ## User Constraints (from context.md)
 
 ### Locked Decisions
-[Copy verbatim from context.md ## Decisions]
+[Copy verbatim from context.md ## Implementation Decisions (inside <decisions>)]
 
 ### Claude's Discretion
 [Copy verbatim from context.md ## Claude's Discretion]