pan-wizard 3.33.0 → 3.34.0

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
@@ -292,7 +294,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 +358,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 +439,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,6 +448,8 @@ 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

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>
 

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
 ---
@@ -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 |
 
@@ -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,7 +405,7 @@ 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.
 
@@ -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]