pan-wizard 3.33.0 → 3.34.0

package/pan-wizard-core/templates/verification-report.md

@@ -10,16 +10,34 @@ Template for `.planning/phases/XX-name/{phase_num}-verification.md` — phase go
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
-verified_commit: <sha> # git rev-parse HEAD before writing this file; `pan-tools verify stale` compares against it
+# verified_commit: git rev-parse HEAD before writing this file; `pan-tools verify stale` compares against it
+verified_commit: <sha>
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
 test_gate: passed | failed | skipped
-not_checked: # Only for checks that could not run, with why — a skipped test gate is one
-  - check: "tests"
-    reason: "no test script in package.json"
-unrequested: # Only when the scope check (`pan-tools verify scope <phase>`) found work no plan asked for
-  - path: "src/admin/panel.tsx"
-    what: "An admin panel no plan or requirement asked for"
+# Only for checks that could not run, with why (a skipped test gate is one): write not_checked uncommented
+# not_checked:
+#   - check: "tests"
+#     reason: "no test script in package.json"
+# Only if status: gaps_found; read by `findings record` and /pan:plan-phase --gaps: write gaps uncommented
+# gaps:
+#   - truth: "Observable truth that failed"
+#     status: failed
+#     reason: "Why it failed"
+#     artifacts:
+#       - path: "src/path/to/file.tsx"
+#         issue: "What's wrong"
+#     missing:
+#       - "Specific thing to add/fix"
+# Only if status: human_needed: write human_verification uncommented
+# human_verification:
+#   - test: "What to do"
+#     expected: "What should happen"
+#     why_human: "Why it cannot be verified programmatically"
+# Only when the scope check (`pan-tools verify scope <phase>`) found work no plan asked for: write unrequested uncommented
+# unrequested:
+#   - path: "src/admin/panel.tsx"
+#     what: "An admin panel no plan or requirement asked for"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -212,8 +230,35 @@ Unrequested work is recorded, not blocking: the status does not change because o
 ---
 phase: 03-chat
 verified: 2025-01-15T14:30:00Z
+verified_commit: 4f2a9c1
 status: gaps_found
-score: 2/5 must-haves verified
+score: 1/5 must-haves verified
+test_gate: passed
+gaps:
+  - truth: "User can see existing messages"
+    status: failed
+    reason: "Chat.tsx renders a placeholder, not message data"
+    artifacts:
+      - path: "src/components/Chat.tsx"
+        issue: "Returns a placeholder div and fetches nothing"
+    missing:
+      - "Fetch from /api/chat and render the messages"
+  - truth: "User can send a message"
+    status: failed
+    reason: "The onSubmit handler only logs"
+    artifacts:
+      - path: "src/components/ChatInput.tsx"
+        issue: "onSubmit calls console.log, no fetch"
+    missing:
+      - "POST to /api/chat on submit"
+  - truth: "Sent message appears in list"
+    status: failed
+    reason: "No state update after send, and the API routes return hardcoded values"
+    artifacts:
+      - path: "src/app/api/chat/route.ts"
+        issue: "GET returns [], POST returns { ok: true }, no database call"
+    missing:
+      - "prisma.message.findMany and create in the route handlers, and a list refresh after send"
 ---
 
 # Phase 3: Chat Interface Verification Report

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

@@ -52,7 +52,7 @@ The CLI handles:
 - Calculating next phase number (max + 1)
 - Generating slug from description
 - Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
-- Inserting the phase entry into roadmap.md with Goal, Depends on, and Plans sections
+- Inserting the phase into roadmap.md: its checklist line, and a section with Goal, Requirements, Depends on and Plans lines
 
 Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
 </step>

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

@@ -24,7 +24,7 @@ Exit workflow.
 Validate phase exists in roadmap:
 
 ```bash
-cat .planning/roadmap.md | grep -i "Phase ${PHASE}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}"   # found, phase_name, goal, success_criteria, section
 ```
 
 **If phase not found:**

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

@@ -130,7 +130,7 @@ Exit workflow.
 </step>
 
 <step name="auto_mode_bypass">
-**P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The 6 unguarded `AskUserQuestion` calls in this workflow (lines ~140, 156, 208, 261, 264, 278) all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with $0.42 cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly.
+**P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The unguarded `AskUserQuestion` calls in `check_existing`, `present_gray_areas` and `discuss_areas` all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with $0.42 cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly.
 
 Detect auto mode:
 
@@ -152,7 +152,7 @@ Skip the interactive flow. Generate `context.md` from the roadmap goal + idea.md
 
 2. Read inputs:
 ```bash
-ROADMAP_GOAL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw | sed -n '/^Goal:/,/^$/p')
+PHASE_JSON=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}")   # JSON: goal, success_criteria, section
 IDEA_PATH=".planning/idea.md"
 PROJECT_PATH=".planning/project.md"
 REQ_PATH=".planning/requirements.md"
@@ -170,7 +170,7 @@ REQ_PATH=".planning/requirements.md"
 <domain>
 ## Phase Boundary
 
-[Goal extracted verbatim from roadmap.md]
+[The `goal` from PHASE_JSON, verbatim]
 
 </domain>
 
@@ -181,7 +181,7 @@ REQ_PATH=".planning/requirements.md"
 [For each item in idea.md "Constraints" / "Scope" / "Notes for the planner" sections that mentions Phase ${PHASE} or its domain keywords (e.g., "image pipeline" for Phase 3) — extract as a locked decision, prefixed with the domain name]
 
 ### From requirements.md
-[For each requirement marked Active that maps to Phase ${PHASE} via `requirements.md`'s phase column — list as a locked decision]
+[For each requirement the phase's slice lists under "Its requirements" (`pan-tools roadmap slice ${PHASE} --raw`) — list as a locked decision]
 
 ### Claude's Discretion
 - Implementation patterns within the constraints above (the planner decides specific libraries / file layouts / function shapes)
@@ -213,7 +213,8 @@ None — auto-mode synthesis honors the original idea.md scope.
 
 Write the file:
 ```bash
-mkdir -p "${phase_dir}"
+# phase_dir is null when the phase has no directory yet: create it (the printed path is phase_dir)
+case "{phase_dir}" in ""|null) node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw ;; esac
 # Use Write tool (NOT heredoc) to create ${phase_dir}/${PADDED_PHASE}-context.md
 ```
 
@@ -278,7 +279,7 @@ If "Cancel": Exit workflow.
 <step name="analyze_phase">
 Analyze the phase to identify gray areas worth discussing.
 
-**Read the phase description from roadmap.md and determine:**
+**Read the phase's section (`roadmap get-phase "${PHASE}"`: `goal`, `success_criteria`, `section`) and determine:**
 
 1. **Domain boundary** — What capability is this phase delivering? State it clearly.
 
@@ -416,9 +417,9 @@ Create context.md capturing decisions made.
 
 Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
 
-If `phase_dir` is null (phase exists in roadmap but no directory):
+If `phase_dir` is null (phase exists in roadmap but no directory), create it and use the printed path as `phase_dir`:
 ```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw
 ```
 
 **File location:** `${phase_dir}/${padded_phase}-context.md`

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

@@ -11,7 +11,7 @@ Read state.md before any operation to load project context.
 
 @~/.claude/pan-wizard-core/references/guardrails.md
 
-> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent executor --token-budget 5000 --raw` to load only the topics tagged relevant for execution at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts. Files appear here over time as `pan-tools learn promote` adds findings.
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent executor --cue "<phase goal; the files it touches>" --token-budget 5000 --raw` to load the topics that match this task, within the budget; if none matches, it falls back to the topics tagged relevant for execution. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts. Files appear here over time as `pan-tools learn promote` adds findings.
 </required_reading>
 
 ## Re-Read Checkpoints
@@ -20,7 +20,7 @@ Context compaction may have dropped earlier sections. Re-read the relevant secti
 
 | Before this step | Re-read | Why |
 |------------------|---------|-----|
-| Spawning a subagent | This workflow's `<step name="execute">` block | Wave/segment routing is easy to misremember after compaction |
+| Spawning a subagent | This workflow's `<step name="execute_waves">` block | Wave/segment routing is easy to misremember after compaction |
 | Writing code in a plan | `references/tdd.md` + plan file | Conventions and the plan's tasks drift across long sessions |
 | Committing | `references/guardrails.md` | Pre-commit shortcuts (silent model swaps, scope creep) are tempting under pressure |
 | Marking phase complete | `workflows/verify-phase.md` | Completion criteria are easy to misremember |
@@ -34,7 +34,7 @@ Load all context in one call:
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "${PHASE_ARG}")
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`.
+Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `verifier_enabled`.
 
 **If `phase_found` is false:** Error — phase directory not found.
 **If `plan_count` is 0:** Error — no plans found in phase.
@@ -49,6 +49,11 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
   --command "exec-phase" \
   --phase "${PHASE_ARG}" 2>/dev/null || true
 ```
+
+**The phase's roadmap slice** — what executing this phase needs from roadmap.md and requirements.md (a line per phase, this phase's section, its dependencies' goals, its requirement lines). Plans name it in their `<context>`; this writes it for plans made before it existed:
+```bash
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${phase_number}" --write --raw)
+```
 </step>
 
 <step name="handle_branching">
@@ -70,42 +75,6 @@ From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
 Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
 </step>
 
-<step name="load_phase_memory">
-**Load project memory before dispatching executors — prevents re-learning patterns already solved.**
-
-```bash
-ls .planning/memory/*.md 2>/dev/null
-```
-
-If `.planning/memory/` exists and contains `.md` files:
-1. **Check the memory-load budget first** (ADR-0036 — keeps per-agent injection bounded as logs grow):
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs memory budget --raw
-```
-2. **Load, size-gated — whole-file is the default:**
-   - If `status` is `ok`: **read every file whole** (Read tool) and condense each entry to its rule(s) — 1–3 lines per file. This preserves the "apply every rule" contract for normal-sized logs.
-   - If `status` is `warning` or `critical` (a log has grown large): load a **cue-scoped** slice per agent instead of the whole log, using the phase objective + the files this phase touches as the cue:
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs memory select <agent> --cue "<phase objective; changed files>" --raw
-```
-     Run once per agent that has a memory file. The returned `selected` entries are already recency-floored and token-budgeted (the newest lessons are always included). If `selected` is empty for an agent, **fall back to reading that file whole** — never silently drop an agent's memory.
-3. Store the condensed rules as a `MEMORY_RULES` block for injection into executor prompts in execute_waves.
-4. **Log memory priming to trace:**
-```bash
-MEMORY_COUNT=$(ls .planning/memory/*.md 2>/dev/null | wc -l | tr -d ' ')
-if [ "$MEMORY_COUNT" -gt "0" ]; then
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type decision --category memory_primed \
-    --description "Loaded ${MEMORY_COUNT} memory entries before Wave 1 dispatch" \
-    --agent orchestrator --impact minor \
-    --context "{\"memory_count\":${MEMORY_COUNT}}" \
-    2>/dev/null || true
-fi
-```
-
-If no memory files exist: skip (no trace event needed).
-</step>
-
 <step name="discover_and_group_plans">
 Load plan inventory with wave grouping in one call:
 
@@ -115,7 +84,7 @@ PLAN_INDEX=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase-plan-index "
 
 Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
 
-**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
+**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip plans whose frontmatter lacks `gap_closure: true` (`phase-plan-index` does not report it; `frontmatter get <plan> --field gap_closure` exits 1 when it is absent). If all filtered: "No matching incomplete plans" → exit.
 
 **If `--gaps-only`:** this run is the fix round after a verification found gaps — a second attempt at work that failed once. Resolve the executor for that attempt and use it in place of `executor_model` for every spawn in this run:
 
@@ -197,10 +166,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
        </files_to_read>
 
-       <project_memory>
-       {MEMORY_RULES — insert condensed content of all .planning/memory/*.md files read in load_phase_memory step. If no memory files exist, omit this block entirely.}
-       Apply every rule in this block without exception. These are lessons from previous phases that the reviewer has already verified.
-       </project_memory>
+       If the plan's `<context>` names `@.planning/roadmap.md`, read `{slice_path}` in its place: it carries this phase's section, its dependencies' goals and its requirements, and the whole roadmap is the largest file in `.planning/` on a long project. Open the whole file only for something the slice leaves out.
 
        <success_criteria>
        - [ ] All tasks executed
@@ -525,8 +491,8 @@ fi
 
 **2. Find parent UAT file:**
 ```bash
-PARENT_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "${PARENT_PHASE}" --raw)
-# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
+PARENT_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "${PARENT_PHASE}" --raw)
+# --raw prints the phase directory itself (empty when not found); find the UAT file in it
 ```
 
 **If no parent UAT found:** Skip this step (gap-closure may have been triggered by verification.md instead).
@@ -556,21 +522,24 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 
 **6. Commit updated artifacts:**
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-uat.md .planning/debug/resolved/*.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-uat.md .planning/debug/
 ```
 </step>
 
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
+**If `verifier_enabled` is false** (`workflow.verifier: false`, set by `/pan:settings` or at project setup): skip this step. Say "verification skipped (workflow.verifier is off)" when you report the phase, and go to update_roadmap. `/pan:verify-phase {X}` still verifies on demand.
+
 ```
 Task(
   prompt="Verify phase {phase_number} goal achievement.
 Phase directory: {phase_dir}
 Phase goal: {goal from roadmap.md}
 Phase requirement IDs: {phase_req_ids}
+Roadmap slice: {slice_path} — this phase's section, its dependencies' goals and its requirement lines. Read it instead of roadmap.md and requirements.md.
 Check must_haves against actual codebase.
-Cross-reference requirement IDs from PLAN frontmatter against requirements.md — every ID MUST be accounted for.
+Cross-reference requirement IDs from PLAN frontmatter against the slice's requirement lines — every ID MUST be accounted for.
 Run the project's test suite as the test gate (the run_test_suite step of @~/.claude/pan-wizard-core/workflows/verify-phase.md) and record test_gate in the frontmatter.
 Create verification.md.",
   subagent_type="pan-verifier",
@@ -665,18 +634,18 @@ The report files are appended to the completion commit's `--files` list (`$REPOR
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/roadmap.md .planning/state.md .planning/requirements.md {phase_dir}/*-verification.md $REPORT_FILES
 ```
 
-**Circular optimization — finalize trace session:**
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null || true
-```
-
-Log phase completion event:
+Log phase completion event (before the session ends: `trace end` clears the active-session pointer, and a `trace log` after it lands in a separate day-scoped `sess_auto_*` session):
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
   --type decision --category phase_complete \
-  --description "Phase ${PHASE_NUMBER} execution complete (${VERIFICATION_STATUS:-verified})" \
+  --description "Phase ${PHASE_NUMBER} execution complete (${VERIF_STATUS:-verified})" \
   --agent orchestrator --impact minor 2>/dev/null || true
 ```
+
+**Circular optimization — finalize trace session:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null || true
+```
 </step>
 
 <step name="offer_next">
@@ -690,14 +659,14 @@ Parse `--no-transition` flag from $ARGUMENTS.
 **If `--no-transition` flag present:**
 
 Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
-After verification passes and roadmap is updated, return completion status to parent:
+If verification found gaps, return `## GAPS FOUND` with the phase, score and gap summaries (plan-phase and discuss-phase stop the chain on it). After verification passes and roadmap is updated, return completion status to parent:
 
 ```
 ## PHASE COMPLETE
 
 Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
 Plans: ${completed_count}/${total_count}
-Verification: {Passed | Gaps Found}
+Verification: {Passed | Skipped (workflow.verifier is off)}
 
 [Include aggregate_results output]
 ```

package/pan-wizard-core/workflows/execute-plan.md

@@ -9,7 +9,7 @@ Read config.json for planning behavior settings.
 @~/.claude/pan-wizard-core/references/git-integration.md
 @~/.claude/pan-wizard-core/references/guardrails.md
 
-> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent executor --token-budget 5000 --raw` to load only the topics tagged relevant for execution at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent executor --cue "<plan objective; the files it modifies>" --token-budget 5000 --raw` to load the topics that match this task, within the budget; if none matches, it falls back to the topics tagged relevant for execution. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
 </required_reading>
 
 ## Re-Read Checkpoints
@@ -47,7 +47,8 @@ ls .planning/phases/XX-name/*-summary.md 2>/dev/null | sort
 Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`):
 
 ```bash
-PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
+PHASE=$(basename "$PLAN_PATH" | grep -oE '^[0-9]+(\.[0-9]+)?')
+PLAN=$(basename "$PLAN_PATH" | grep -oE '^[0-9]+(\.[0-9]+)?-[0-9]+' | cut -d- -f2)
 # config settings can be fetched via pan-tools config-get if needed
 ```
 
@@ -137,8 +138,8 @@ This IS the execution instructions. Follow exactly. If plan references context.m
 
 <step name="previous_phase_check">
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list --type summaries --raw
-# Extract the second-to-last summary from the JSON result
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list --type summaries
+# Extract the second-to-last summary from the JSON result's files[] (file names only, in phase order)
 ```
 If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness" blockers: AskUserQuestion(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous").
 </step>
@@ -277,7 +278,7 @@ TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
 <step name="checkpoint_protocol">
 On `type="checkpoint:*"`: automate everything possible first. Checkpoints are for verification/decisions only.
 
-Display: `CHECKPOINT: [Type]` box → Progress {X}/{Y} → Task name → type-specific content → `YOUR ACTION: [signal]`
+Display: `CHECKPOINT: [Type]` box → Progress {X}/{Y} → Task name → type-specific content → the action prompt line `→ [signal]`
 
 | Type | Content | Resume signal |
 |------|---------|---------------|
@@ -333,7 +334,7 @@ Create `{phase}-{plan}-summary.md` at `.planning/phases/XX-name/`. Use `~/.claud
 
 **Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (**MUST** copy `requirements` array from plan.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).
 
-Title: `# Phase [X] Plan [Y]: [Name] Summary`
+Title: `# Phase [X]: [Name] Summary` (the summary template's)
 
 One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
 
@@ -382,7 +383,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state record-session \
   --resume-file "None"
 ```
 
-Keep state.md under 150 lines.
+Keep state.md under 100 lines (the state template's size constraint).
 </step>
 
 <step name="issues_review_gate">

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

@@ -11,13 +11,13 @@ Read all files referenced by the invoking prompt's execution_context before star
 <step name="parse_args">
 **Parse arguments:**
 
-Check if `--repair` flag is present in the command arguments.
+Check which of `--repair`, `--standards`, `--full`, `--drift` and `--links` are present in the command arguments; `validate health` reads all five.
 
 ```
-REPAIR_FLAG=""
-if arguments contain "--repair"; then
-  REPAIR_FLAG="--repair"
-fi
+HEALTH_FLAGS=""
+for flag in --repair --standards --full --drift --links; do
+  if arguments contain "$flag"; then HEALTH_FLAGS="$HEALTH_FLAGS $flag"; fi
+done
 ```
 </step>
 
@@ -25,7 +25,7 @@ fi
 **Run health validation:**
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs validate health $REPAIR_FLAG
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs validate health $HEALTH_FLAGS
 ```
 
 Parse JSON output:
@@ -84,7 +84,7 @@ Errors: N | Warnings: N | Info: N
 ```
 ## Errors
 
-- [E001] config.json: JSON parse error at line 5
+- [E005] config.json: JSON parse error - <parser message>
   Fix: Run /pan:health --repair to reset to defaults
 
 - [E002] project.md not found
@@ -95,7 +95,7 @@ Errors: N | Warnings: N | Info: N
 ```
 ## Warnings
 
-- [W001] state.md references phase 5, but only phases 1-3 exist
+- [W002] state.md references phase 5, but only phases 01, 02, 03 exist
   Fix: Run /pan:health --repair to regenerate
 
 - [W005] Phase directory "1-setup" doesn't follow NN-name format
@@ -165,8 +165,8 @@ Report final status.
 | I003 | info | Focus-model or campaign tree — the phase-model checks do not apply | No |
 | I004 | info | planning-with-files shares the tree — PAN leaves its files alone | No |
 | I005 | info | The planning tree is gitignored while commit_docs is true — planning commits commit nothing | No |
-| I006 | info | config.json holds keys PAN does not read (usually a typo); the fix names the nearest known key | No |
-| STATE_REQ_DRIFT | warning | state.md complete but REQUIREMENTS.md has unchecked boxes | Yes |
+| I006 | info | config.json holds keys PAN's code does not read (usually a typo); the fix names the nearest known key. It also lists `gates` and `safety` from templates/config.json: the `custom`-mode conditions in transition.md and execute-plan.md read `gates`; nothing reads `safety` (transition.md asks before skipping plans in every mode) | No |
+| STATE_REQ_DRIFT | warning | state.md complete but requirements.md has unchecked boxes | Yes |
 | STATE_ROADMAP_DRIFT | warning | state.md complete but roadmap.md has unchecked plan boxes | Yes |
 | VERIFICATION_GATE_MISSING | warning | Phase has completed plans but no verification record | No |
 
@@ -176,7 +176,6 @@ Flag-gated codes:
 |------|----------|------|-------------|------------|
 | TESTS_FAIL | error | --full | Test run exited non-zero | No |
 | BUILD_FAIL | error | --full | Build exited non-zero | No |
-| MEM_BUDGET | warning / info | --full | Memory injection over budget | No |
 | DRIFT_HIGH | warning | --drift | Drift verdict is high | No |
 | DRIFT_MEDIUM | info | --drift | Drift verdict is medium | No |
 | LINKS_ERR | warning | --links | Link graph has errors | No |
@@ -197,7 +196,9 @@ or behind the current position warns.
 |--------|--------|------|
 | createConfig | Create config.json with defaults | None |
 | resetConfig | Delete + recreate config.json | Loses custom settings |
-| regenerateState | Create state.md from ROADMAP structure | Loses session history |
+| regenerateState | Back up state.md to `state.md.bak-<timestamp>`, then create state.md from ROADMAP structure | Session history only in the backup |
+| syncRequirements | Tick requirements.md boxes when state.md says every plan is done (STATE_REQ_DRIFT) | Edits requirements.md checkboxes |
+| syncRoadmap | Tick roadmap.md plan boxes when state.md says every plan is done (STATE_ROADMAP_DRIFT) | Edits roadmap.md checkboxes |
 
 **Not repairable (too risky):**
 - project.md, roadmap.md content

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

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

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

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