pan-wizard 3.36.0 → 3.37.0

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

@@ -1,77 +1,155 @@
-<purpose>
-Research how to implement a phase. Spawns pan-phase-researcher with phase context.
+<objective>
+Answer the open questions that block planning a phase (at most 5). Spawns one pan-phase-researcher agent with the questions and the phase context.
 
-Standalone research command. For most workflows, use `/pan:plan-phase` which integrates research automatically.
-</purpose>
+**Note:** This is the standalone research mode. `/pan:plan-phase` researches only with `--research` or `workflow.research: true`.
 
-<process>
+**Use this command when:**
+- You want to research without planning yet
+- You want to re-research after planning is complete
+- You need to investigate before deciding if a phase is feasible
+
+**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
 
-## Step 0: Resolve Model Profile
+**Why subagent:** Searching burns context. A fresh context window answers the questions, at most 4 searches or fetches each; the main context stays lean for user interaction.
+</objective>
 
-@~/.claude/pan-wizard-core/references/model-profile-resolution.md
+<context>
+Phase number: $ARGUMENTS (required)
 
-Resolve model for:
-- `pan-phase-researcher`
+Normalize phase input in step 1 before any directory lookups.
+</context>
 
-## Step 1: Normalize and Validate Phase
+<process>
 
-@~/.claude/pan-wizard-core/references/phase-argument-parsing.md
+## 0. Initialize Context
 
 ```bash
-PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}")
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "$ARGUMENTS")
 ```
 
-If `found` is false: Error and exit.
+Extract from init JSON: `phase_dir`, `padded_phase`, `phase_slug`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`. `phase_dir` is null when the phase is in the roadmap but has no directory yet: create it (`mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"`) and use that path as `phase_dir`, as discuss-phase does.
 
-## Step 2: Check Existing Research
+Resolve researcher model:
+```bash
+RESEARCHER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-phase-researcher --raw)
+```
+
+## 1. Validate Phase
 
 ```bash
-ls .planning/phases/*/*-research.md 2>/dev/null | grep -E "/0*${PHASE}-[^/]*/"
+PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}")
 ```
 
-If exists: Offer update/view/skip options.
+**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
-## Step 3: Gather Phase Context
+## 2. Check Existing Research
 
-```bash
-INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
-# Extract: phase_dir, padded_phase, phase_slug, phase_number, state_path, requirements_path, context_path
-# phase_dir is null when the phase has no directory yet: create it (scaffold pads the number and honours the planning root) and use the printed path as 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 `has_research` and `research_path` from INIT.
+
+**If exists:** Offer: 1) Update research, 2) View existing (`research_path`), 3) Skip. Wait for response.
+
+**If doesn't exist:** Continue.
+
+## 3. Gather Phase Context
 
-# This phase's roadmap and requirements, written into the phase directory
-SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${PHASE}" --write --raw)
+Write this phase's roadmap slice (its section, its dependencies' goals and its requirement lines), then use paths from INIT (do not inline file contents in orchestrator context):
+```bash
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${phase_number}" --write --raw)
 ```
+- `slice_path` (from the command above; `requirements_path` if it is empty)
+- `context_path`
+- `state_path`
+
+Present summary with phase description and what files the researcher will load.
+
+## 4. Write the Questions and Spawn pan-phase-researcher
 
-## Step 4: Spawn Researcher
+Research answers questions; it does not survey the phase's domain. List at most **5** open questions the phase's requirements leave unanswered and that block building (a technology choice, an external API's behaviour, a data format, a limit or rule), as a numbered list in `{phase_dir}/{padded_phase}-research-questions.md`:
 
+```markdown
+# Phase {phase_number} research questions
+
+1. [question] — blocks: [the task or decision it settles]
 ```
-Task(
-  prompt="<objective>
-Research implementation approach for Phase {phase}: {name}
+
+**No questions → no research.** If nothing blocks building, write no file, say `No open questions block Phase {phase_number} — research skipped`, and stop.
+
+```markdown
+<objective>
+Answer the research questions for Phase {phase_number}: {phase_name}, and nothing else.
 </objective>
 
 <files_to_read>
-- {context_path} (USER DECISIONS from /pan:discuss-phase)
-- {slice_path} (This phase's roadmap and requirements; if SLICE_PATH is empty, {requirements_path} instead)
-- {state_path} (Project decisions and history)
+- {phase_dir}/{padded_phase}-research-questions.md (The questions)
+- {slice_path} (This phase's roadmap and requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
 </files_to_read>
 
-<additional_context>
-Phase description: {description}
-</additional_context>
-
 <output>
 Write to: {phase_dir}/{padded_phase}-research.md
-</output>",
+One row per question: | # | Question | Answer | Source | Confidence | Decision it settles |, or `unknown — assume: …`. At most 4 searches or fetches per question. Anything that suggests new scope goes under ## Ideas (v2 candidates).
+</output>
+```
+
+```
+Task(
+  prompt=filled_prompt,
   subagent_type="pan-phase-researcher",
-  model="{researcher_model}"
+  model="{researcher_model}",
+  description="Research Phase {phase}"
 )
 ```
 
-## Step 5: Handle Return
+Then check the answers:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research check "{phase_dir}/{padded_phase}-research-questions.md" "{phase_dir}/{padded_phase}-research.md"
+```
+
+Exit 1: send its `errors` to the researcher once as a revision. One revision at most; then proceed, with each question still unsourced recorded under `## Unknowns` in the research file with the assumption the plan uses.
+
+## 5. Handle Agent Return
+
+**`## RESEARCH COMPLETE`:** Display the decisions it settled and any unknowns, offer: Plan phase, Review full, Done.
+
+**`## RESEARCH BLOCKED`:** Show the blocker and what was attempted, offer: Provide context (then spawn a continuation, step 6), Skip research, Abort.
+
+## 6. Spawn Continuation Agent
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+<files_to_read>
+- {phase_dir}/{padded_phase}-research.md (Existing research)
+</files_to_read>
+</prior_state>
 
-- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
-- `## RESEARCH BLOCKED` — Display the blocker, offer: Provide context / Skip research / Abort
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="pan-phase-researcher",
+  model="{researcher_model}",
+  description="Continue research Phase {phase}"
+)
+```
 
 </process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing research checked
+- [ ] At most 5 questions written (none: no research)
+- [ ] One pan-phase-researcher spawned with the questions
+- [ ] `research check` run, one revision at most
+- [ ] Checkpoints handled correctly
+- [ ] User knows next steps
+</success_criteria>

package/pan-wizard-core/workflows/resume-project.md

@@ -138,6 +138,16 @@ Present complete project status to user:
 </step>
 
 <step name="determine_next_action">
+An interrupted agent or a `.continue-here` checkpoint comes first (below). Otherwise ask the router:
+
+```bash
+NEXT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs next-action)
+```
+
+It returns `{action, phase, reason, command}`, read from roadmap.md and the phase directories by the same state machine the MCP `pan_next_action` tool uses, so progress, resume and transition never disagree about what comes next. `action` is one of `plan`, `execute`, `verify`, `complete_phase`, `plan_gaps`, `audit_milestone`, `new_milestone`, `new_project` or `stop`, and `command` is the command that carries it out.
+
+Offer its `command` as the primary option.
+
 Based on project state, determine the most logical next action:
 
 **If interrupted agent exists:**
@@ -237,7 +247,7 @@ Based on user selection, route to appropriate workflow:
 
   **Also available:**
   - `/pan:discuss-phase [N]` — gather context first
-  - `/pan:research-phase [N]` — investigate unknowns
+  - `/pan:plan-phase --research-only [N]` — investigate unknowns
 
   ---
   ```
@@ -274,7 +284,13 @@ If state.md is missing but other artifacts exist:
 4. Count pending todos in .planning/todos/pending/
 5. Check for .continue-here files → Session continuity
 
-Reconstruct and write state.md, then proceed normally.
+Reconstruct state.md through the engine, never with the Write tool:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state init --core-value "<from project.md>" --focus "<current phase name>" --phase <current phase> --phase-name "<its name>" --total-phases <N> --activity "Reconstructed from artifacts"
+```
+
+Then add what the summaries and todos hold, one section at a time: `state section "Decisions" --append "- [Phase X]: ..."`, `state section "Blockers/Concerns" --append "..."`, `state section "Pending Todos" --set "<N> pending"`. Proceed normally.
 
 This handles cases where:
 

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

@@ -24,13 +24,13 @@ Creates `.planning/config.json` with defaults if missing and loads current confi
 cat .planning/config.json
 ```
 
-Parse current values (when a key is absent, use PAN's default: `true` for research, plan_check and verifier; `false` for nyquist_validation):
-- `workflow.research` — spawn researcher during plan-phase
+Parse current values (when a key is absent, use PAN's default: `false` for research and nyquist_validation; `true` for plan_check and verifier):
+- `workflow.research` — spawn researcher during plan-phase (off by default: research is opt-in, and when on it answers at most 5 open questions per phase)
 - `workflow.plan_check` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
 - `workflow.nyquist_validation` — validation architecture research during plan-phase
-- `model_profile` — which model each agent uses (default: `balanced`)
-- `routing.strategy` — how model tiers are adjusted at runtime (default: `static`)
+- `model_profile` — how much ceremony and which model each agent uses (default: `balanced`; `quality` keeps the full ceremony everywhere)
+- `routing.strategy` — not asked here (default: `static`). The `complexity` strategy reaches no workflow, so offering it would be a choice that changes nothing; `config-set routing.strategy complexity` still sets it for `resolve-model --metadata` callers. A `quality` profile in an existing config keeps working: it is identical to `balanced`
 - `cost.phase_budget_usd` — spend per phase PAN warns about, in API-equivalent dollars (default: `20`; `0` = off). It never stops a run
 - `branching_strategy` — branching approach (default: `"none"`; a top-level key — a nested `git.branching_strategy` is ignored when the top-level key exists, as it does in every config `config-ensure-section` creates — write the top-level key)
 </step>
@@ -45,18 +45,18 @@ AskUserQuestion([
     header: "Model",
     multiSelect: false,
     options: [
-      { label: "Quality", description: "reasoning tier for every agent — identical to balanced, so switching between the two changes nothing" },
-      { label: "Balanced (Recommended)", description: "reasoning tier for every agent (quality and balanced are identical post-COST-RESET); use budget to step down" },
-      { label: "Budget", description: "mid tier for writing, fast tier for research/verification (lowest cost)" }
+      { label: "Balanced (Recommended)", description: "right-sized: a small, well-specified phase or quick task skips research and the planner/checker loop; plan-checker and researchers on the mid tier; one plan revision" },
+      { label: "Quality", description: "the full ceremony on every piece of work, every agent on the reasoning tier (the behaviour before right-sizing; costs several times more)" },
+      { label: "Budget", description: "right-sized like balanced, plus mid tier for writing and fast tier for research/verification (lowest cost)" }
     ]
   },
   {
-    question: "Spawn Plan Researcher? (researches domain before planning)",
+    question: "Spawn Plan Researcher? (off by default; answers up to 5 open questions before planning)",
     header: "Research",
     multiSelect: false,
     options: [
-      { label: "Yes", description: "Research phase goals before planning" },
-      { label: "No", description: "Skip research, plan directly" }
+      { label: "No (default)", description: "Plan directly from requirements; /pan:plan-phase N --research researches one phase" },
+      { label: "Yes", description: "Before each phase, answer up to 5 open questions that block building, each with a source" }
     ]
   },
   {
@@ -76,7 +76,14 @@ AskUserQuestion([
       { label: "Yes", description: "Verify must-haves after execution" },
       { label: "No", description: "Skip post-execution verification" }
     ]
-  },
+  }
+])
+```
+
+Then the next batch (the host takes at most four questions per call):
+
+```
+AskUserQuestion([
   {
     question: "Auto-advance pipeline? (discuss → plan → execute automatically)",
     header: "Auto",
@@ -105,15 +112,6 @@ AskUserQuestion([
       { label: "Per Milestone", description: "Create branch for entire milestone (pan/{version}-{name})" }
     ]
   },
-  {
-    question: "Model routing strategy?",
-    header: "Routing",
-    multiSelect: false,
-    options: [
-      { label: "Static (Recommended)", description: "Profile assigns fixed tiers to each agent. Predictable and simple." },
-      { label: "Complexity", description: "Adjust tiers by task complexity, only where a model is resolved with the task passed (resolve-model --metadata); the *_model values workflows pass are not, so it changes nothing there" }
-    ]
-  },
   {
     question: "Warn when a phase's spend passes how much? (API-equivalent dollars; warns only, never stops)",
     header: "Phase budget",
@@ -136,14 +134,13 @@ A dollar amount typed under Other is used as given.
 Write each answer with `config-set`, which keeps every other key in the `workflow` and `routing` objects:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set model_profile <quality|balanced|budget>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set model_profile <balanced|quality|budget>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research <true|false>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.plan_check <true|false>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.verifier <true|false>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance <true|false>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.nyquist_validation <true|false>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set branching_strategy <none|phase|milestone>
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set routing.strategy <static|complexity>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set cost.phase_budget_usd <20|50|10|0|amount>
 ```
 </step>
@@ -216,8 +213,8 @@ Display:
 These settings apply to future /pan:plan-phase and /pan:exec-phase runs.
 
 Quick commands:
-- /pan:profile <profile> — switch model profile
-- /pan:plan-phase --research — force research
+- /pan:settings --profile <profile> — switch model profile
+- /pan:plan-phase --research — research one phase (up to 5 open questions)
 - /pan:plan-phase --skip-research — skip research
 - /pan:plan-phase --skip-verify — skip plan check
 ```

package/pan-wizard-core/workflows/todo-check.md

@@ -129,7 +129,7 @@ Use AskUserQuestion:
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs todo complete "[filename]"
 ```
 This moves it out of `.planning/todos/pending/` (the directory `init todos` and `/pan:progress` count) into `.planning/todos/completed/` with a `completed:` date.
-Update state.md todo count. Present problem/solution context. Begin work or ask how to proceed.
+Update the todo count in state.md (the `update_state` step). Present problem/solution context. Begin work or ask how to proceed.
 
 **Add to phase plan:**
 Note todo reference in phase planning notes. Keep in pending. Return to list or exit.
@@ -148,7 +148,11 @@ Return to list_todos step.
 <step name="update_state">
 After any action that changes todo count:
 
-Re-run `init todos` to get updated count, then update state.md "### Pending Todos" section if exists.
+Re-run `init todos` to get the updated count, then set state.md's "### Pending Todos" section through the engine:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state section "Pending Todos" --set "{count} pending — /pan:todo-check to review"
+```
 </step>
 
 <step name="git_commit">

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

@@ -25,7 +25,7 @@ Mark current phase complete and advance to next. This is the natural point where
 **Required pattern from v3.7.5 onward:**
 
 1. Run the steps below to *plan* each state.md update, but **do not write or commit** between them. Hold the changes in memory.
-2. After `update_session_continuity_after_transition` (the last state.md-touching step before `offer_next_phase`), perform a **single Edit** that applies all four section updates (Project Reference, Accumulated Context, Session Continuity, plus the progress bar from `update_current_position_after_transition`).
+2. After `update_session_continuity_after_transition` (the last state.md-touching step before `offer_next_phase`), make a **single `pan-tools state apply` call** that applies all four section updates in one write (Project Reference, Accumulated Context, Session Continuity, plus the progress bar from `update_current_position_after_transition`).
 3. Then issue **one** commit:
    ```bash
    node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(transition): phase ${current_phase} → ${next_phase} (state, progress, context)"
@@ -34,6 +34,14 @@ Mark current phase complete and advance to next. This is the natural point where
 
 Net result per transition: 2 commits instead of 5. Reduces git noise and keeps `/pan:learn` overhead metrics (commits_per_minute) honest. Substantive content of each step below is unchanged — only the **timing of the write** changes.
 
+The batched call, with the values the steps below planned (fields are bold `**Name:**` lines; a section is appended to or replaced):
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state apply --json '{"fields": {"Progress": "<bar from progress bar --raw>", "Current focus": "<next phase name>", "Core value": "<current core value>", "Last session": "<YYYY-MM-DD HH:MM>", "Resume File": "None"}, "sections": {"Decisions": {"append": ["- [Phase X]: <decision>"]}, "Blockers/Concerns": {"set": "<the reviewed list>"}}}'
+```
+
+It reports any field it could not find in `failed`. Never edit state.md with the Edit tool: the engine keeps the frontmatter in sync, and under `hooks.guard: enforce` the guard denies a direct write.
+
 </state_write_policy>
 
 <process>
@@ -355,7 +363,7 @@ Update Session Continuity section in state.md to reflect transition completion.
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Stopped at" "Phase ${current_phase} complete, ready to plan Phase ${next_phase}"
 ```
 
-Then Edit state.md (still under the P-1604 batched-write policy — fold this Edit into the final batched Edit at the end of the workflow):
+Then fold the other two lines into the batched `state apply` call at the end of the workflow (P-1604):
 
 **Format:**
 
@@ -387,6 +395,16 @@ The `is_last_phase` field from the phase complete result tells you directly:
 
 The `next_phase` and `next_phase_name` fields give you the next phase details.
 
+To name the next command, ask the router after `phase complete`:
+
+```bash
+NEXT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs next-action)
+```
+
+It returns `{action, phase, reason, command}`, read from roadmap.md and the phase directories by the same state machine the MCP `pan_next_action` tool uses, so progress, resume and transition never disagree about what comes next. `action` is one of `plan`, `execute`, `verify`, `complete_phase`, `plan_gaps`, `audit_milestone`, `new_milestone`, `new_project` or `stop`, and `command` is the command that carries it out.
+
+For the next phase it returns `plan` (or `execute` when the phase is already planned); at the milestone boundary it returns `audit_milestone`.
+
 If you need additional context, use:
 ```bash
 ROADMAP=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap analyze)
@@ -530,7 +548,7 @@ Task(
 
 **Also available:**
 - `/pan:plan-phase [X+1]` — skip discussion, plan directly
-- `/pan:research-phase [X+1]` — investigate unknowns
+- `/pan:plan-phase --research-only [X+1]` — investigate unknowns
 
 ---
 ```
@@ -555,7 +573,7 @@ Task(
 
 **Also available:**
 - `/pan:discuss-phase [X+1]` — revisit context
-- `/pan:research-phase [X+1]` — investigate unknowns
+- `/pan:plan-phase --research-only [X+1]` — investigate unknowns
 
 ---
 ```

package/pan-wizard-core/workflows/uat-walkthrough.md

@@ -0,0 +1,90 @@
+<purpose>
+Walk the user through user acceptance testing for one phase, one test at a time, on any runtime. Record each answer through the engine, so every runtime leaves the same `{phase_num}-uat.md`. When the walkthrough finds issues, diagnose them, then hand the gaps to `/pan:plan-phase {phase_num} --gaps`.
+</purpose>
+
+<core_principle>
+The user is the oracle here. You present what they should be able to observe, they say whether they observed it, and the engine writes it down. Never mark a test passed on their behalf, and never rephrase their report: an issue is recorded in their words.
+</core_principle>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE_ARG}")
+```
+Take `phase_dir`, `phase_number` and `phase_name` from the JSON. Look for an existing session:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat status "${PHASE_NUMBER}"
+```
+
+- **A session exists with tests pending:** resume at the first pending test.
+- **A session exists and is complete:** show its summary. If it has gaps, go to `diagnose`; otherwise go to `done`.
+- **No session (`uat_not_found`):** go to `build_tests`.
+</step>
+
+<step name="build_tests">
+Create the file, then fill in its tests:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold uat --phase "${PHASE_NUMBER}"
+```
+
+Read the phase's summaries (`{phase_dir}/*-summary.md`) and its plans' `must_haves`. Write one test per user-observable truth into the file's `## Tests` section, each as:
+
+```markdown
+### N. <short name>
+expected: <what the user should be able to see or do, concretely: the command, the screen, the output>
+result: [pending]
+```
+
+Keep to what a person can observe without reading the code. Write the test list once, in full, then leave every result to the engine.
+</step>
+
+<step name="walk">
+For each pending test, in order:
+
+1. Show the test: its name and its `expected` behaviour, with the exact steps to observe it.
+2. Ask for the result:
+   ```
+   AskUserQuestion([
+     { question: "Test N: <name>. Did you observe the expected behaviour?", header: "UAT", multiSelect: false, options: [
+       { label: "Pass", description: "It behaves as expected" },
+       { label: "Issue", description: "Something differs; describe what you saw" },
+       { label: "Skip", description: "Cannot test this now" }
+     ] }
+   ])
+   ```
+   Runtimes without AskUserQuestion ask the same question in plain text and take the answer from the reply.
+3. Record it, in the user's own words for an issue:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat record "${PHASE_NUMBER}" --test N --result pass
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat record "${PHASE_NUMBER}" --test N --result issue --reported "<their words>" --severity major
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat record "${PHASE_NUMBER}" --test N --result skipped --reason "<why>"
+   ```
+   Severity: `blocker` (cannot use the feature), `major` (wrong behaviour), `minor` (works, but rough), `cosmetic`.
+
+When no test is pending, the engine marks the session `complete`.
+</step>
+
+<step name="diagnose">
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat status "${PHASE_NUMBER}"
+```
+
+If `gaps` is empty, go to `done`. Otherwise follow the diagnose-issues workflow (@~/.claude/pan-wizard-core/workflows/diagnose-issues.md). On Claude Code the native `/pan-diagnose-issues {phase_num}` script does the same in parallel. Diagnosis fills each gap's `root_cause`, `artifacts`, `missing` and `debug_session`, and the engine keeps those fields across any later re-record.
+</step>
+
+<step name="done">
+Report the summary (`passed`, `issues`, `skipped`). With gaps:
+
+```
+UAT found {issues} issue(s), diagnosed in {phase_num}-uat.md.
+
+Next: /pan:plan-phase {phase_num} --gaps
+```
+
+Without gaps: "UAT passed. Continue with `/pan:exec-phase {phase_num}` (transition) or the next phase."
+</step>
+
+</process>

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

@@ -197,7 +197,7 @@ Format completion message (changelog was already shown in confirmation step):
 
 ⚠️  Restart your AI coding tool to pick up the new commands.
 
-[View full changelog](https://github.com/oharms/PanWizard/blob/main/CHANGELOG.md)
+Full changelog: ~/.claude/pan-wizard-core/CHANGELOG.md
 ```
 </step>
 

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

@@ -119,7 +119,7 @@ from the exit code and the runner's output, and you copy it.
 </step>
 
 <step name="mutation_report">
-**Measure whether the tests pin the code the phase wrote** (a report, never a gate).
+**Measure whether the tests pin the code the phase wrote** (a report, unless the project chose gate mode).
 
 Only when the test gate passed: a mutant cannot be read against a suite that already fails.
 With `workflow.mutation_gate: off` the command runs nothing and says so.
@@ -134,7 +134,7 @@ commits changed, in a throwaway worktree at HEAD, and runs the suite against eac
 
 Write a **Test strength** section in verification.md: `killed/sampled`, and each survivor as
 `file:line — before → after`, framed as a test the phase could add. A survivor is a lead, not a
-gap: it never changes the status. `aborted: flaky` (the unmutated suite passed once and failed
+gap: in `report` mode it never changes the status. In `gate` mode (`workflow.mutation_gate: gate`) the result carries `gate`: when `gate.failed` is true (the score is below `workflow.mutation_floor`), set the status to `gaps_found` and list each survivor as a gap; `verify reconcile` refuses a passed verification over a failed gate. `aborted: flaky` (the unmutated suite passed once and failed
 once) is worth reporting as a finding of its own; `checked: false` with its `reason` goes in
 `not_checked` as `check: "mutation"`.
 </step>

package/scripts/build-agent-plugin.js

@@ -15,9 +15,17 @@
  *                                 canonical agent reference copies under agents/
  *
  *   hooks/pan-*.js                PAN's hook scripts (pure Node), shared by every vendor
- *   hooks/hooks.json              Codex: default plugin hooks location; matcher-group
+ *   hooks/hooks.json              Codex's default plugin hooks location; matcher-group
  *                                 shape with `${PLUGIN_ROOT}` paths and `async` observers
- *                                 (developers.openai.com/plugins/build/plugins, 2026-09-10)
+ *                                 (developers.openai.com/plugins/build/plugins, 2026-09-10).
+ *                                 NOT LOADED BY CODEX for this bundle: a root plugin.json
+ *                                 with the agent-plugins.org schema makes Codex treat the
+ *                                 plugin as an Agent Plugin, and its loader then skips
+ *                                 hooks entirely (codex-rs/core-plugins/src/loader.rs,
+ *                                 "Enforce Agent Plugin runtime boundaries" #37027,
+ *                                 2026-08-05; same at rust-v0.163.0; read 2026-10-19, R55).
+ *                                 Codex users get PAN's hooks from a `--codex` install
+ *                                 (.codex/hooks.json). Kept for the other consumers.
  *   com.github.copilot/           Copilot's reverse-domain namespace (ADR-0045 D5):
  *     agents/pan-*.agent.md         agents in Copilot's format
  *     hooks/hooks.json              flat PascalCase format, `${CLAUDE_PLUGIN_ROOT}` paths
@@ -90,25 +98,35 @@ function emitSkills(srcDir, skillsDir, prefix) {
       if (entry.isDirectory()) { recurse(srcPath, `${currentPrefix}-${entry.name}`); continue; }
       if (!entry.name.endsWith('.md')) continue;
       const skillName = `${currentPrefix}-${entry.name.replace(/\.md$/, '')}`;
-      const skillDir = path.join(skillsDir, skillName);
-      fs.mkdirSync(skillDir, { recursive: true });
-      let content = fs.readFileSync(srcPath, 'utf8');
-      content = lib.rewriteUnifiedSkillCommandContent(content, REWRITE);
-      content = lib.convertClaudeCommandToUnifiedSkill(content, skillName, { adapterNote: lib.agentPluginSkillAdapterNote() });
-      const { skill, reference } = lib.splitOversizedSkill(content, skillName);
-      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skill);
-      if (reference) {
-        const refPath = path.join(skillDir, ...lib.AGENT_PLUGIN_SKILL_REFERENCE.split('/'));
-        fs.mkdirSync(path.dirname(refPath), { recursive: true });
-        fs.writeFileSync(refPath, reference);
-        split++;
-      }
+      if (emitSkill(fs.readFileSync(srcPath, 'utf8'), skillsDir, skillName)) split++;
       count++;
     }
   })(srcDir, prefix);
+  // Renamed commands keep their old names as aliases, as the installer writes them (L7).
+  const { COMMAND_ALIASES } = require(path.join(ROOT, 'pan-wizard-core', 'bin', 'lib', 'constants.cjs'));
+  for (const [oldName, alias] of Object.entries(COMMAND_ALIASES)) {
+    const target = fs.readFileSync(path.join(srcDir, `${alias.to}.md`), 'utf8');
+    if (emitSkill(lib.renderCommandAlias(target, oldName, alias), skillsDir, `${prefix}-${oldName}`)) split++;
+    count++;
+  }
   return { count, split };
 }
 
+/** One command → skills/<name>/SKILL.md (plus a reference file when split). Returns true when split. */
+function emitSkill(content, skillsDir, skillName) {
+  const skillDir = path.join(skillsDir, skillName);
+  fs.mkdirSync(skillDir, { recursive: true });
+  content = lib.rewriteUnifiedSkillCommandContent(content, REWRITE);
+  content = lib.convertClaudeCommandToUnifiedSkill(content, skillName, { adapterNote: lib.agentPluginSkillAdapterNote() });
+  const { skill, reference } = lib.splitOversizedSkill(content, skillName);
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skill);
+  if (!reference) return false;
+  const refPath = path.join(skillDir, ...lib.AGENT_PLUGIN_SKILL_REFERENCE.split('/'));
+  fs.mkdirSync(path.dirname(refPath), { recursive: true });
+  fs.writeFileSync(refPath, reference);
+  return true;
+}
+
 /** pan-wizard-core → bundle, markdown rewritten, everything else verbatim. */
 function emitCore(srcDir, destDir) {
   (function recurse(currentSrc, currentDest) {
@@ -133,6 +151,8 @@ function emitCore(srcDir, destDir) {
     if (err.code !== 'ENOENT') throw err;
   }
   fs.writeFileSync(path.join(destDir, 'VERSION'), pkg.version);
+  // `/pan:update` points at the installed changelog, as a loose-file install carries it.
+  fs.copyFileSync(path.join(ROOT, 'CHANGELOG.md'), path.join(destDir, 'CHANGELOG.md'));
 }
 
 /** Canonical agent reference copies under <core>/agents/ (ADR-0028). */