pan-wizard 3.32.0 → 3.34.0

package/pan-wizard-core/templates/uat.md

@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-uat.md` — persistent UAT se
 
 ```markdown
 ---
-status: testing | complete | diagnosed
+status: testing | complete | diagnosed | resolved
 phase: XX-name
 source: [list of summary.md files tested]
 started: [ISO timestamp]
@@ -74,7 +74,7 @@ skipped: [N]
 <section_rules>
 
 **Frontmatter:**
-- `status`: OVERWRITE - "testing" or "complete"
+- `status`: OVERWRITE - "testing", "complete", "diagnosed" (after diagnosis) or "resolved" (exec-phase closes the gaps)
 - `phase`: IMMUTABLE - set on creation
 - `source`: IMMUTABLE - SUMMARY files being tested
 - `started`: IMMUTABLE - set on creation
@@ -106,7 +106,7 @@ skipped: [N]
 
 **After testing complete (status: complete), if gaps exist:**
 
-1. User runs diagnosis (from verify-phase offer or manually)
+1. User runs diagnosis (on Claude Code, the native `/pan-diagnose-issues <phase>`; no `/pan:` command or verify-phase step runs it)
 2. diagnose-issues workflow spawns parallel debug agents
 3. Each agent investigates one gap, returns root cause
 4. uat.md Gaps section updated with diagnosis:

package/pan-wizard-core/templates/user-setup.md

@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required c
 
 ## File Template
 
-```markdown
+~~~markdown
 # Phase {X}: User Setup Required
 
 **Generated:** [YYYY-MM-DD]
@@ -55,7 +55,7 @@ Expected results:
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 
 ---
 
@@ -117,7 +117,7 @@ user_setup:
 ## Service-Specific Examples
 
 <stripe_example>
-```markdown
+~~~markdown
 # Phase 10: User Setup Required
 
 **Generated:** 2025-01-14
@@ -188,11 +188,11 @@ Expected: Build passes, webhook returns 400 (signature validation working).
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 </stripe_example>
 
 <supabase_example>
-```markdown
+~~~markdown
 # Phase 2: User Setup Required
 
 **Generated:** 2025-01-14
@@ -242,11 +242,11 @@ npx supabase status
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 </supabase_example>
 
 <sendgrid_example>
-```markdown
+~~~markdown
 # Phase 5: User Setup Required
 
 **Generated:** 2025-01-14
@@ -297,7 +297,7 @@ curl -X POST http://localhost:3000/api/test-email \
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 </sendgrid_example>
 
 ---

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

@@ -10,11 +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: 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
-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"
+test_gate: passed | failed | skipped
+# 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
@@ -207,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
@@ -256,7 +222,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a PAN or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (summary.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
 
-   For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
+   For real failures: report which plan failed → ask "Continue?" or "Stop?". If stop, partial completion report. If continue, never run a plan that depends on a failed one; ask the engine which plans are blocked:
+   ```bash
+   BLOCKED=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase-plan-index "${PHASE_NUMBER}" --failed "${FAILED_PLAN_IDS}")
+   ```
+   `${FAILED_PLAN_IDS}` is the comma-separated ids of every plan that failed so far. `blocked` lists each unfinished plan whose `depends_on` reaches a failed plan, directly or through another blocked plan, with the failed plans behind it. Do not spawn those plans in this or any later wave. Name them in the wave report and the final summary ("Skipped 03-03 and 03-04: they depend on 03-01, which failed"), and run every other plan as planned. The same applies after "Continue with remaining waves?" in step 4.
 
 6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
@@ -275,7 +245,7 @@ AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.
 
 When executor returns a checkpoint AND `AUTO_CFG` is `"true"`:
 - **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
-- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
+- **decision** → The executor already took the plan's `auto_select` option when the task had one, so a decision that comes back has none: present it to the user (standard flow below). If a returned decision's task does carry `auto_select` in the plan file, auto-spawn the continuation agent with `{user_response}` = that option id and log `⚡ Auto-selected: [option] (auto_select)`. Never answer with an option because it is listed first.
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
 
 **Standard flow (not auto-mode, or human-action type):**
@@ -521,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).
@@ -552,21 +522,25 @@ 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",
   model="{verifier_model}"
@@ -585,7 +559,7 @@ VERIF_STATUS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record
 
 | Status | Action |
 |--------|--------|
-| `passed` | → update_roadmap |
+| `passed` | → update_roadmap. If the verification frontmatter has `test_gate: skipped` or a `not_checked` list, say so when you report the phase: "passed — not checked: tests (no test script)". A pass never hides what it did not check |
 | `human_needed` | Present items for human testing, get approval or feedback |
 | `gaps_found` | Present gap summary, offer `/pan:plan-phase {phase} --gaps` |
 
@@ -660,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">
@@ -685,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,7 +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 |
-| 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 |
 
@@ -175,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 |
@@ -196,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