pan-wizard 3.33.0 → 3.35.0

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,12 +34,24 @@ 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`, `plan_check`, `plan_drift`. In the shell steps below, `$PHASE_DIR` (and `$phase_dir`) is `phase_dir` and `$PHASE_NUMBER` is `phase_number`.
 
 **If `phase_found` is false:** Error — phase directory not found.
 **If `plan_count` is 0:** Error — no plans found in phase.
 **If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
 
+**The plans must be the plans that passed the plan check** (`plan_check.status`):
+
+| Status | Action |
+|---|---|
+| `ok`, `disabled` | Continue |
+| `legacy` | Continue, and say: "the plan check predates plan hashing, so it cannot show these plans are unchanged" |
+| `stale` | Stop: "The plans changed after they passed the plan check. Re-plan with `/pan:plan-phase {N} --skip-research`, which checks the new plans." Continue only if the user gives a reason, and record it: `pan-tools optimize trace log --type decision --category plan_check_overridden --description "<reason>"` |
+| `failed` | Stop: "The last plan check found issues." Same override |
+| `missing` | Stop: "No plan check is recorded for this phase." This includes plans made with `/pan:plan-phase --skip-verify` or with `workflow.plan_check` off after the fact. Same override |
+
+**Drift.** For each `plan_drift` entry, tell the executor of that plan, in its prompt, which of its `files_modified` changed since it was planned (`files`), so it re-reads them before editing. An entry with `error` means its `planned_commit` is unknown: say so and continue.
+
 When `parallelization` is false, plans within a wave execute sequentially.
 
 **Circular optimization — start trace session for this exec:**
@@ -49,6 +61,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 +87,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 +96,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 +178,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
@@ -224,6 +202,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
+   **An executor that returned `## BLOCKED_SPEC_CONFLICT`** found a test it cannot satisfy without weakening it. It is not a failure to retry: show the user its Test, Requirement and Options and ask for a ruling. "Change the test" means a revised plan that declares the test file in `files_modified` (`/pan:plan-phase {N} --gaps` or an edit to the plan), then re-run that plan; "change the requirement" means updating the requirement and the plan. Never re-run the same plan unchanged: it would meet the same test. Declaring the file permits rewriting its expectations; deleting the test, skipping it or dropping assertions still fails `verify test-integrity`, so a ruling to do that also needs `phase complete --force --reason`.
+
    If pass:
    ```
    ---
@@ -353,7 +333,7 @@ After all waves:
 
 1. Record baseline test count:
 ```bash
-TEST_BASELINE=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
+TEST_BASELINE=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 ```
 
 2. Invoke phase-tests workflow for the completed phase:
@@ -365,7 +345,8 @@ Read each summary.md to understand what was built.
 Generate unit and integration tests for the new code.
 Discover the project's existing test patterns, directories, frameworks, and helpers before writing tests.
 Follow whatever conventions the project already uses.",
-  subagent_type="general-purpose"
+  subagent_type="general-purpose",
+  model="{executor_model}",
 )
 ```
 
@@ -376,7 +357,7 @@ Alternatively, if the user's AI tool supports it, invoke the command directly:
 
 3. Record new test count:
 ```bash
-TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
+TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 ```
 
 4. Report:
@@ -387,6 +368,8 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
 - New tests: +$((TEST_AFTER - TEST_BASELINE))
 ```
 
+`ℹ tests N` (spec reporter) and `# tests N` (TAP, Node's default for piped output before Node 23) are the summary lines of Node's built-in test runner, and both greps above match either. With any other runner both counts come back empty, so report the runner's own summary line instead of `+0`.
+
 **If tests fail after generation:** Report failures but continue to next step. Test issues are caught by the verify-phase test gate.
 </step>
 
@@ -399,11 +382,14 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^ℹ tests" | awk '{print $NF}')
 ```bash
 # Read each summary.md and extract key-files.created + key-files.modified
 for summary in "$PHASE_DIR"/*-summary.md; do
-  grep -A 50 "key-files" "$summary" | grep -E "^\s*-" | sed 's/^\s*- //'
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields key_files | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const k=JSON.parse(s).key_files||{};for(const f of [...(k.created||[]),...(k.modified||[])])console.log(f)})"
 done | sort -u > /tmp/review-files.txt
 ```
 
-2. Spawn pan-reviewer:
+2. Collect the reviewer's earlier open findings on this phase (empty on a first review), then spawn pan-reviewer:
+```bash
+OPEN_REVIEW_FINDINGS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings list --phase "${PHASE_NUMBER}" --agent pan-reviewer --status open 2>/dev/null)
+```
 ```
 Task(
   subagent_type="pan-reviewer",
@@ -425,6 +411,10 @@ Task(
     Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
     Phase directory: ${phase_dir}
     </context>
+
+    <open_findings>
+    ${OPEN_REVIEW_FINDINGS}
+    </open_findings>
   "
 )
 ```
@@ -460,7 +450,7 @@ The fallback reads the word under `### Verdict` when the report carries no valid
   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-reviewer --open --as deferred --reason "accepted at review: PASS_WITH_WARNINGS"
   ```
 - **The user chooses "Continue anyway"** at `NEEDS_FIXES`: the same command with `--reason "continued past NEEDS_FIXES at the user's choice"`, then proceed to verification.
-- **The user chooses "Fix before verification"**: apply the fixes, then run the review once more (steps 2–4). The new record closes the findings it no longer reports.
+- **The user chooses "Fix before verification"**: apply the fixes, then run the review once more (steps 2–4). The re-review answers each earlier finding in its `resolutions`; the record closes the ones it answers `resolved` with evidence, and one it neither reports nor answers stays open.
 
 5. **No separate trace logging.** The record logs `verdict_passed` or `verdict_failed` for the reviewer on every runtime. The `reviewer_correction` and `reviewer_warnings` trace calls that used to sit here read the error count from a shell variable nothing ever set.
 
@@ -525,8 +515,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 +546,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",
@@ -584,7 +577,7 @@ VERIF_FILE=$(ls "$PHASE_DIR"/*-verification.md 2>/dev/null | head -1)
 VERIF_STATUS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --file "$VERIF_FILE" --raw 2>/dev/null) \
   || VERIF_STATUS=$(grep "^status:" "$VERIF_FILE" | cut -d: -f2 | tr -d ' ')
 ```
-`findings record` reads the verdict from the verification frontmatter (`status`, `gaps`, `human_verification`, `unrequested`) and adds its findings to the ledger. A re-verification after a fix round is the next attempt: the gaps it no longer reports are closed, and the retry is logged. Recording the same file twice is a no-op, so verify-phase recording it too is safe. The grep fallback keeps the old reading when the record cannot parse the file.
+`findings record` reads the verdict from the verification frontmatter (`status`, `gaps`, `human_verification`, `unrequested`) and adds its findings to the ledger. A re-verification after a fix round is the next attempt: the gaps it lists under `re_verification.gaps_closed` are closed, a gap it neither reports nor answers stays open (listed in `unaddressed`), and the retry is logged. Recording the same file twice is a no-op, so verify-phase recording it too is safe. The grep fallback keeps the old reading when the record cannot parse the file.
 
 **Trace logging happens in the record.** The record above logs the verification outcome (`verdict_passed`, `verdict_failed` or `verdict_needs_human`) here, after the verifier returns. That covers inline verification too, which is the reason P-1806 moved the trace call here (v3.7.8). No separate `optimize trace log` call is needed.
 
@@ -630,12 +623,26 @@ Gap closure cycle: `/pan:plan-phase {X} --gaps` reads verification.md → create
 </step>
 
 <step name="update_roadmap">
-**Mark phase complete and update all tracking files:**
+**Mark phase complete and update all tracking files.** `phase complete` runs the phase gate first, on every path (this step runs before `offer_next`, with or without `--no-transition`). The gate checks in code what this workflow used to ask for in prose: every plan has a summary, the verification passes (a failed test gate lowers it to gaps), human items have a recorded approval, the verification is fresh, reconcile finds no contradiction, no critical or high finding is left open, no stub was committed, and no test was weakened.
 
 ```bash
 COMPLETION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${PHASE_NUMBER}")
+COMPLETION_EXIT=$?
 ```
 
+| Result | Action |
+|---|---|
+| exit 1, `error: phase_gate_refused` (`workflow.phase_gate: enforce`) | The phase was NOT marked complete. Show each `gate.reasons` entry (`code`: `detail`) with its fix, and stop: no commit, no auto-advance. The user may complete anyway with a reason (below) |
+| exit 0, `gate.ok` false (`warn`, the default) | The phase was marked complete. Show the reasons as warnings, run the rest of this step, and do NOT auto-advance (`offer_next` reads `GATE_OK`) |
+| exit 0, `gate.ok` true | Continue |
+
+**Completing past a refusal** is the user's decision, never yours, and needs their reason. It records a `decision` for every open finding the gate counted:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${PHASE_NUMBER}" --force --reason "<the user's reason>"
+```
+
+Set `GATE_OK` to `gate.ok` from `COMPLETION` (`false` when the gate refused).
+
 The CLI handles:
 - Marking phase checkbox `[x]` with completion date
 - Updating Progress table (Status → Complete, date)
@@ -665,18 +672,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 +697,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, or `GATE_OK` is false, return `## GAPS FOUND` with the phase, score and the gap summaries or the gate's reasons (plan-phase and discuss-phase stop the chain on it). After the gate passes, 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]
 ```
@@ -706,37 +713,10 @@ STOP. Do not proceed to auto-advance or transition.
 
 **If `--no-transition` flag is NOT present:**
 
-**Verification gate check (before auto-advance):**
-
-If `workflow.verifier` is true in config, confirm the current phase has a passing verification:
-
-```bash
-VERIF=$(ls "$phase_dir"/*-verification.md 2>/dev/null | head -1)
-VERIF_STATUS=""
-if [ -n "$VERIF" ]; then
-  VERIF_STATUS=$(grep "^status:" "$VERIF" | awk '{print $2}')
-fi
-```
-
-**Cross-check the written verdict against the mechanical signals (anti-rubber-stamp, ADR-0036).** The `status:` string above is authored by the verifier agent; `reconcile` re-derives the artifact/key-link checks from disk and exits non-zero when a claimed pass contradicts them:
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify reconcile "${PHASE_NUMBER}" --raw
-RECONCILE_EXIT=$?
-```
-If `RECONCILE_EXIT` is non-zero:
-```
-⚠ Reconcile gate: Phase ${PHASE_NUMBER} verification says "passed" but the mechanical
-  checks disagree — artifacts fail substance checks or key-links are unwired.
-  This is a rubber-stamped verification. Do NOT auto-advance.
-  Re-run /pan:verify-phase and fix the failing artifacts/key-links.
-```
-STOP — do not auto-advance. Return to user.
-
-If `VERIF_STATUS` is not `passed`:
+**Gate check (before auto-advance).** The phase gate already ran inside `phase complete` (`update_roadmap`), and it covers the verification status, reconcile (anti-rubber-stamp, ADR-0036), freshness, open findings, stubs and test integrity. If `GATE_OK` is false:
 ```
-⚠ Verification gate: Phase ${PHASE_NUMBER} verification status is "${VERIF_STATUS:-missing}"
-  Cannot auto-advance without passing verification.
-  Run /pan:verify-phase to verify this phase first.
+⚠ Phase gate: Phase ${PHASE_NUMBER} may not advance — {each gate reason: code and detail}.
+  Fix the reasons (or close the gaps with /pan:plan-phase ${PHASE_NUMBER} --gaps), then re-run.
 ```
 STOP — do not auto-advance. Return to user.
 

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