pan-wizard 3.35.0 → 3.37.0

package/agents/pan-reviewer.md

@@ -12,8 +12,7 @@ You are a PAN code reviewer. You perform read-only code review on files changed
 
 Your job: Check convention compliance, security patterns, and code quality. You do NOT modify files — you report findings. This is authorized, defensive review of the user's own codebase — surface security-relevant findings for the user to remediate; never produce exploit code.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 
 **Read also:** `~/.claude/pan-wizard-core/references/guardrails.md` — anti-patterns and the Code Preservation Principle. Findings that violate Code Preservation (silent scope expansion, model swaps, refactor-while-here) should be flagged at high severity.
 
@@ -93,6 +92,10 @@ A fixed baseline that applies even when the project documents no standards (Fowl
 
 ## Scope (unrequested work)
 
+When the prompt carries an `<intent>` block (the `review scope` JSON), it is what you judge the change against: each plan's `objective`, `must_haves` and `review_focus` (the risk the planner asked a reviewer to check, so check it first and say what you found), and the text of the requirements the plans claim. Its `unlisted` array names changed files no summary's key-files lists: review them as closely as the rest, and say in the report that the summary did not list them.
+
+When the prompt carries an `<executor_concerns>` block, each entry is something an executor finished but was not sure of, with its cost if wrong. Check the high-cost ones against the code and report what you found: a concern that holds is a finding; one that does not, say so in a sentence.
+
 Compare what the changed code does with what the phase's plans asked for (their tasks and `must_haves`). Code that adds behaviour no plan task or requirement mentions is a finding: a feature nobody asked for, an unrelated refactor folded into the change, or an option no requirement needs. Use category `Unrequested` at WARNING, or at ERROR when it changes existing behaviour without a plan saying so. Its class in the `pan-verdict` block is `unrequested`. Supporting code the tasks need (tests, types, wiring) is not a finding.
 
 </review_checks>
@@ -128,7 +131,13 @@ Return a structured review report:
 {PASS | PASS_WITH_WARNINGS | NEEDS_FIXES}
 ```
 
-**Verdict rules:**
+**Lens.** When the prompt names a `<lens>` (`correctness`, `security` or `maintainability`), review only through it. Two other passes cover the other lenses, and a vote keeps the findings at least two passes report. So report what your lens finds, and do not stretch it to cover the others.
+
+**What you declined to judge.** If you set a behaviour aside (no way to run it, outside your lens, outside the diff), name it in the block's `declined` list as `{"behaviour": "...", "reason": "..."}`. Silence about a behaviour reads as a pass; a declined entry says it was not checked.
+
+**Pre-existing problems.** A problem in code this phase did not change, such as an untouched file or untouched lines of a changed file, was there before the phase. Report it, tagged pre-existing, but leave it out of the verdict: it is the project's debt, not this change's defect. `review scope` and `git diff` tell you what the phase changed.
+
+**Verdict rules** (pre-existing findings never count):
 - **PASS**: Zero errors, zero warnings
 - **PASS_WITH_WARNINGS**: Zero errors, warnings present
 - **NEEDS_FIXES**: Any errors present
@@ -138,7 +147,9 @@ Return a structured review report:
 - Add one finding per table row. ERROR → `high`, WARNING → `medium`, INFO → `info`.
 - Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, Unrequested → `unrequested`.
 - `where` is `file:line`.
+- A pre-existing finding carries `"pre_existing": true`. The recorder files it as deferred debt with the reason, so it never blocks the phase, and the milestone audit still lists it.
 - A clean review has `"findings": []`.
+- **Dismissed findings are filtered by the recorder, not by you.** When the project dismissed a finding with a reason, recording filters the same finding again for as long as its file is unchanged, and lets it back in once the file changes. Security and logic findings are never filtered. So report everything you find; do not leave out a finding because you think it was dismissed before. To see what is being filtered: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings suppressions --phase {phase_number} --agent pan-reviewer`.
 - **On a re-check you are given `<open_findings>`:** your earlier open findings on this phase, each with its `id`. Answer every one in a `resolutions` list in the block: `{"id":"f_…","status":"resolved","evidence":"what you checked and saw"}` when it is fixed, `still_present` when it is not, `cannot_tell` when you could not check it. A finding you leave out stays open: silence never closes a finding, and `resolved` without evidence closes nothing.
 
 The orchestrator records this block. It is how your findings reach the phase's findings ledger and `/pan:review-deep`.

package/agents/pan-roadmapper.md

@@ -16,8 +16,7 @@ You are spawned by:
 
 Your job: Transform requirements into a phase structure that delivers the project. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 
 **Core responsibilities:**
 - Derive phases from requirements (not impose arbitrary structure)
@@ -334,7 +333,7 @@ Reference full template: `~/.claude/pan-wizard-core/templates/roadmap.md`
 
 ## state.md Structure
 
-Use template from `~/.claude/pan-wizard-core/templates/state.md`.
+`pan-tools state init` writes it from the sections of `~/.claude/pan-wizard-core/templates/state.md`; you supply the values.
 
 Key sections:
 - Project Reference (core value, current focus)
@@ -352,7 +351,7 @@ Key sections:
 Orchestrator provides:
 - project.md content (core value, constraints)
 - requirements.md content (v1 requirements with REQ-IDs)
-- research/summary.md content (if exists - phase suggestions)
+- research/research-summary.md content (if exists - phase suggestions; older projects have research/summary.md instead)
 - config.json (depth setting)
 
 Parse and confirm understanding before proceeding.
@@ -376,7 +375,7 @@ Total v1: 11 requirements
 
 ## Step 3: Load Research Context (if exists)
 
-If research/summary.md provided:
+If research/research-summary.md (or an older project's research/summary.md) provided:
 - Extract suggested phase structure from "Implications for Roadmap"
 - Note research flags (which phases need deeper research)
 - Use as input, not mandate
@@ -415,7 +414,13 @@ If gaps found, resolve them (see Coverage Validation) and list each gap with the
 
 1. **Write roadmap.md** using output format
 
-2. **Write state.md** using output format
+2. **Initialise state.md through the engine**, not with Write:
+
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state init --core-value "<core value from project.md>" --focus "<first phase name>" --phase <first phase number> --phase-name "<first phase name>" --total-phases <N>
+   ```
+
+   When state.md already exists (a new milestone), add `--force --keep-context`: the old file is backed up and its Accumulated Context carried over. The engine writes every section of the template and keeps the frontmatter in sync; never write state.md with the Write or Edit tool (under `hooks.guard: enforce` the guard denies it).
 
 3. **Update requirements.md traceability section**
 
@@ -500,7 +505,7 @@ After incorporating user feedback and updating files:
 
 **Files updated:**
 - .planning/roadmap.md
-- .planning/state.md (if needed)
+- .planning/state.md (if needed, through `pan-tools state apply` or `state section`)
 - .planning/requirements.md (if traceability changed)
 
 ### Updated Summary

package/agents/pan-verifier.md

@@ -11,8 +11,7 @@ You are a PAN phase verifier. You verify that a phase achieved its GOAL, not jus
 
 Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 
 **Critical mindset:** Do NOT trust summary.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ.
 </role>
@@ -199,6 +198,12 @@ If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
 
 For each truth, determine if codebase enables it.
 
+**Requirements with EARS criteria are read against their tests.** Run the trace matrix for the phase's requirement ids:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify traceability <REQ-ID> <REQ-ID> …
+```
+`passed` means the mapped tests pass. `failing` is a gap. `not_checked` means no test is mapped to the requirement, so list it under `not_checked` and never as verified. `legacy` (no criteria) is judged as before.
+
 **Verification status:**
 
 - ✓ VERIFIED: All supporting artifacts pass all checks
@@ -486,9 +491,9 @@ Unrequested work never changes the status on its own; a phase can pass with it.
 
 ## Step 8b: Run the Test Gate
 
-Run the project's test suite exactly as the verify-phase protocol's `run_test_suite` step says (`~/.claude/pan-wizard-core/workflows/verify-phase.md`): detect a test script first, then run it and judge the exit code before any count. Record the result in the frontmatter as `test_gate: passed | failed | skipped`. `skipped` is only for a project with no test script; a suite that exists and did not run is `failed`.
+Run the test suite through the engine, as the verify-phase protocol's `run_test_suite` step says (`~/.claude/pan-wizard-core/workflows/verify-phase.md`): `pan-tools test run --phase <N>` detects the project's test command in any language, runs it, compares it with the phase's baseline and writes the record. Copy its `status` into the frontmatter as `test_gate: passed | failed | skipped`; do not run the suite yourself and do not re-judge the result. A failed record lowers a `passed` verification whatever you write, and reconcile refuses a `test_gate` that disagrees with it.
 
-A gate you could not run goes in `not_checked` with the reason, e.g. `- check: "tests"` / `reason: "no test script in package.json"`. If the orchestrator already ran the suite and gave you the result, record that result rather than running it again.
+A `skipped` record goes in `not_checked` with the record's reason, e.g. `- check: "tests"` / `reason: "no test command: …"`. If the orchestrator already ran `test run` for this phase and gave you the result, record that result rather than running it again.
 
 ## Step 9: Determine Overall Status
 

package/bin/install-lib.cjs

@@ -130,6 +130,25 @@ function extractFrontmatterAndBody(content) {
   };
 }
 
+/**
+ * Mark a Claude Code command or skill as user-invoked only (market-ideas M49): add
+ * `disable-model-invocation: true` to its frontmatter. Claude Code then keeps it out
+ * of the listing it sends the model on every turn, and it still runs as /pan:<name>.
+ * Seen to work on Claude Code 2.1.302 against the harness model double
+ * (skill-listing-claude, skill-listing-claude-commands; 2026-10-20). Claude only:
+ * no other runtime was seen to read the field (MI-022). Idempotent; content without
+ * frontmatter is returned unchanged.
+ * @param {string} content
+ * @returns {string}
+ */
+function withClaudeUserInvokedOnly(content) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!m || /^disable-model-invocation:/m.test(m[1])) return content;
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const end = m.index + m[0].length - 3; // the closing ---
+  return content.slice(0, end) + 'disable-model-invocation: true' + eol + content.slice(end);
+}
+
 /** Extract a field value from YAML frontmatter string */
 function extractFrontmatterField(frontmatter, fieldName) {
   const regex = new RegExp(`^${fieldName}:\\s*(.+)$`, 'm');
@@ -593,6 +612,39 @@ function rewriteAgentFileRefs(content, runtime, pathPrefix) {
   return content.replace(new RegExp(`(${prefix}agents/pan-[a-z0-9_-]+)\\.md\\b`, 'g'), (_, base) => base + ext);
 }
 
+/**
+ * Build the alias command for a renamed command (program L7, COMMAND_ALIASES).
+ * The alias is the target command itself under the old name: its frontmatter `name`
+ * becomes the old one, its description says what it was renamed to, and a line after
+ * the frontmatter presets the flags. Carrying the whole body, rather than a pointer to
+ * the target's installed path, is what makes it resolve on every runtime: each one
+ * installs commands at a different path and in a different shape. Pure.
+ * @param {string} targetContent - the target command's source (commands/pan/<to>.md)
+ * @param {string} oldName - the old command name, without prefix
+ * @param {{to: string, args: string}} alias
+ * @returns {string}
+ */
+function renderCommandAlias(targetContent, oldName, alias) {
+  const now = alias.args ? `/pan:${alias.to} ${alias.args}` : `/pan:${alias.to}`;
+  const m = targetContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!m) throw new Error(`renderCommandAlias: ${alias.to} has no frontmatter`);
+  const fm = m[1].split(/\r?\n/).map((line) => {
+    const name = line.match(/^name:\s*(pan:)?\S+/);
+    if (name) return `name: ${name[1] || ''}${oldName}`;
+    const desc = line.match(/^description:\s*(.*)$/);
+    if (desc) {
+      const raw = desc[1].trim();
+      const unq = raw.match(/^(["'])([\s\S]*)\1$/);
+      const text = (unq ? unq[2].replace(/\\"/g, '"') : raw).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+      return `description: "Renamed: now ${now}. ${text}"`;
+    }
+    return line;
+  });
+  const preset = alias.args ? `${alias.args} $ARGUMENTS` : '$ARGUMENTS';
+  const note = `> \`/pan:${oldName}\` is now \`${now}\`. Run the command below with the arguments \`${preset}\`.\n\n`;
+  return `---\n${fm.join('\n')}\n---\n${note}${targetContent.slice(m[0].length)}`;
+}
+
 function rewriteAgentReferenceCopy(content, corePrefix) {
   content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
   content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
@@ -708,7 +760,8 @@ function buildCopilotPluginHooksConfig(commands) {
   const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand } = commands || {};
   const hooks = {};
   if (updateCheckCommand) hooks.SessionStart = [{ type: 'command', command: updateCheckCommand }];
-  if (contextMonitorCommand) hooks.PostToolUse = [{ type: 'command', command: contextMonitorCommand }];
+  // No context monitor: it cannot measure on Copilot (HOOK_EVENT_MAP, M50).
+  if (contextMonitorCommand && HOOK_EVENT_MAP.copilot.postToolUse) hooks.PostToolUse = [{ type: 'command', command: contextMonitorCommand }];
   const subagentStop = [];
   if (costLoggerCommand) subagentStop.push({ type: 'command', command: costLoggerCommand });
   if (traceLoggerCommand) subagentStop.push({ type: 'command', command: traceLoggerCommand });
@@ -1171,7 +1224,7 @@ function buildCopilotHooksConfig(commands) {
     config.hooks.preToolUse = [{ type: 'command', command: guardCommand }];
   }
   const postToolUse = [];
-  if (contextMonitorCommand) postToolUse.push({ type: 'command', command: contextMonitorCommand });
+  if (contextMonitorCommand && HOOK_EVENT_MAP.copilot.postToolUse) postToolUse.push({ type: 'command', command: contextMonitorCommand });
   // State re-injection after a compaction (M33): preCompact leaves the marker, the
   // next postToolUse returns the block once (hooks/pan-state-reinject.js).
   if (stateReinjectInjectCommand) postToolUse.push({ type: 'command', command: stateReinjectInjectCommand });
@@ -1241,12 +1294,19 @@ function buildCopilotHooksConfig(commands) {
  * next tool result, the first point after it where both hosts take added context
  * (gemini-cli v0.61.0 docs/hooks/reference.md; Copilot hooks reference; read
  * 2026-10-03, and live on Copilot CLI 1.0.88 the same day).
+ *
+ * `postToolUse` is the context monitor's slot, and it is set only where the monitor
+ * can measure (market-ideas M50). Its numbers come from Claude Code's status-line
+ * bridge or a Claude-shaped transcript. Copilot sends camelCase `sessionId`, so the
+ * hook exited at its session_id check on every call. Codex has no bridge, and its
+ * transcripts are not Claude-shaped. Both events exist on those hosts, but PAN
+ * registers nothing there (reality check 2026-10-19).
  */
 const HOOK_EVENT_MAP = Object.freeze({
   claude: { surface: 'settings.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
   gemini: { surface: 'settings.json', sessionStart: 'SessionStart', preToolUse: 'BeforeTool', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null, compactMark: 'PreCompress', compactInject: 'AfterTool' },
-  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
-  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', preToolUse: 'preToolUse', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
+  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: null, subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', preToolUse: 'preToolUse', postToolUse: null, subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
   opencode: null,
 });
 
@@ -1543,7 +1603,7 @@ function mergeCodexHooksConfig(existing, commands) {
     ['SessionStart', updateCheckCommand, 'pan-check-update', true],
     // The guard decides whether a call may run, which an async handler cannot (A7).
     ['PreToolUse', guardCommand, 'pan-guard', false],
-    ['PostToolUse', contextMonitorCommand, 'pan-context-monitor', false],
+    ['PostToolUse', HOOK_EVENT_MAP.codex.postToolUse ? contextMonitorCommand : null, 'pan-context-monitor', false],
     ['SubagentStop', costLoggerCommand, 'pan-cost-logger', true],
     ['SubagentStop', traceLoggerCommand, 'pan-trace-logger', true],
     ['Stop', stopGuardCommand, 'pan-stop-guard', false],
@@ -1572,6 +1632,14 @@ function mergeCodexHooksConfig(existing, commands) {
     if (async) handler.async = true;
     config.hooks[event].push({ ...(matcher ? { matcher } : {}), hooks: [handler] });
   }
+  // An install from before M50 registered the context monitor here; it cannot measure
+  // on Codex, so an upgrade drops that handler (foreign hooks in the group stay).
+  if (!HOOK_EVENT_MAP.codex.postToolUse && Array.isArray(config.hooks.PostToolUse)) {
+    config.hooks.PostToolUse = config.hooks.PostToolUse
+      .map((group) => (Array.isArray(group.hooks) ? { ...group, hooks: group.hooks.filter((h) => !(h && h.command && h.command.includes('pan-context-monitor'))) } : group))
+      .filter((group) => !Array.isArray(group.hooks) || group.hooks.length > 0);
+    if (config.hooks.PostToolUse.length === 0) delete config.hooks.PostToolUse;
+  }
   return config;
 }
 
@@ -2338,6 +2406,7 @@ return { areas_mapped: maps.filter(Boolean).length, synthesis }
   phases: [
     { title: 'Index', detail: 'plan inventory with wave grouping, from the PAN engine' },
     { title: 'Execute', detail: 'one executor per plan; waves in order, plans within a wave in parallel' },
+    { title: 'Review', detail: 'pan-reviewer over the phase diff (review scope); the verdict recorded, and the phase budget read' },
     { title: 'Verify', detail: 'the phase verifier over the completed plans' },
     { title: 'Gate', detail: 'the PAN phase gate: stops when the phase may not be completed' },
   ],
@@ -2361,8 +2430,10 @@ const INDEX = {
     phase_name: { type: 'string' },
     phase_dir: { type: 'string' },
     parallelization: { type: 'boolean' },
+    worktree_isolation: { type: 'boolean' },
     verifier_enabled: { type: 'boolean' },
     has_checkpoints: { type: 'boolean' },
+    test_baseline: { type: 'string' },
     plans: {
       type: 'array',
       items: {
@@ -2371,6 +2442,7 @@ const INDEX = {
           id: { type: 'string' },
           file: { type: 'string' },
           wave: { type: 'integer' },
+          sub_wave: { type: 'integer' },
           autonomous: { type: 'boolean' },
           has_summary: { type: 'boolean' },
           objective: { type: 'string' },
@@ -2382,7 +2454,7 @@ const INDEX = {
   required: ['phase_found', 'has_checkpoints', 'plans'],
 }
 const index = await agent(
-  'Index phase ' + phaseArg + ' for execution using the ' + PAN_TOOLS + ' Run two verbs and merge their JSON: (1) init execute-phase ' + phaseArg + ' — take phase_found, phase_number, phase_name, phase_dir, parallelization, verifier_enabled; (2) phase-plan-index ' + phaseArg + ' — take has_checkpoints and plans[] (id, wave, autonomous, has_summary, objective; include each plan file path as file). Do not execute anything; return only the merged index.',
+  'Index phase ' + phaseArg + ' for execution using the ' + PAN_TOOLS + ' Run two verbs and merge their JSON: (1) init execute-phase ' + phaseArg + ' — take phase_found, phase_number, phase_name, phase_dir, parallelization, worktree_isolation, verifier_enabled; (2) phase-plan-index ' + phaseArg + ' — take has_checkpoints and plans[] (id, wave, sub_wave, autonomous, has_summary, objective; include each plan file path as file). Then, only if phase_found is true and has_checkpoints is false, (3) test run --phase ' + phaseArg + ' --baseline — it records what the test suite does before the first wave, so the verifier can tell a failure this phase caused from one it inherited; a phase that already has a baseline keeps it (kept_existing), and a failing or empty baseline is not an error. Put one line describing its result in test_baseline. Do not execute any plan; return only the merged index.',
   { label: 'index', phase: 'Index', schema: INDEX })
 if (!index || !index.phase_found) return { error: 'phase ' + phaseArg + ' not found' }
 if (index.has_checkpoints) {
@@ -2391,6 +2463,14 @@ if (index.has_checkpoints) {
 const pending = index.plans.filter(p => !p.has_summary)
 if (pending.length === 0) return { phase: phaseArg, done: true, message: 'every plan already has a summary — nothing to execute' }
 const waveNumbers = [...new Set(pending.map(p => p.wave))].sort((a, b) => a - b)
+// A3: plans of one wave that modify the same file are in different sub-waves, run in turn.
+const groups = []
+for (const w of waveNumbers) {
+  const inWave = pending.filter(p => p.wave === w)
+  for (const sw of [...new Set(inWave.map(p => p.sub_wave || 0))].sort((a, b) => a - b)) groups.push({ wave: w, sub: sw, plans: inWave.filter(p => (p.sub_wave || 0) === sw) })
+}
+// workflow.worktree_isolation: each executor works in its own git worktree.
+const iso = index.worktree_isolation === true ? { isolation: 'worktree' } : {}
 const parallelWithinWave = index.parallelization !== false
 log(pending.length + ' plans across ' + waveNumbers.length + ' wave(s)' + (parallelWithinWave ? '' : ', sequential within waves'))
 
@@ -2414,17 +2494,18 @@ const executorPrompt = (p) =>
   + 'Report plan_id, status (complete | failed | checkpoint), summary_path, the number of commits you made, and self_check (passed if your summary carries no "Self-Check: FAILED" marker).'
 const executed = []
 let halted = null
-for (const w of waveNumbers) {
-  const wavePlans = pending.filter(p => p.wave === w)
-  log('wave ' + w + ': ' + wavePlans.map(p => p.id).join(', '))
+for (const g of groups) {
+  const w = g.wave
+  const wavePlans = g.plans
+  log('wave ' + w + (g.sub ? '.' + g.sub : '') + ': ' + wavePlans.map(p => p.id).join(', '))
   let results
   if (parallelWithinWave) {
     results = await parallel(wavePlans.map(p => () =>
-      agent(executorPrompt(p), { agentType: 'pan-executor', label: 'exec:' + p.id, phase: 'Execute', schema: EXEC_RESULT })))
+      agent(executorPrompt(p), { agentType: 'pan-executor', label: 'exec:' + p.id, phase: 'Execute', schema: EXEC_RESULT, ...iso })))
   } else {
     results = []
     for (const p of wavePlans) {
-      results.push(await agent(executorPrompt(p), { agentType: 'pan-executor', label: 'exec:' + p.id, phase: 'Execute', schema: EXEC_RESULT }))
+      results.push(await agent(executorPrompt(p), { agentType: 'pan-executor', label: 'exec:' + p.id, phase: 'Execute', schema: EXEC_RESULT, ...iso }))
     }
   }
   const settled = results.filter(Boolean)
@@ -2441,9 +2522,44 @@ for (const w of waveNumbers) {
 if (halted) {
   return { phase: phaseArg, halted, executed, next: 'Inspect the failed plan(s), then re-run /pan-exec-waves ' + phaseArg + ' (completed plans are skipped) or fall back to /pan:exec-phase ' + phaseArg }
 }
+
+// Code review before verification, as in exec-phase.md (code_review). The reviewer is
+// read-only, so a second agent saves its report, records the verdict in the findings
+// ledger and reads the phase budget. A script cannot ask "fix before verification?",
+// so NEEDS_FIXES halts and hands the choice back. { skipReview: true } in args skips it,
+// like --skip-review.
+phase('Review')
+const skipReview = !!(args && typeof args === 'object' && args.skipReview === true)
+let review = null
+if (!skipReview) {
+  const REPORT = { type: 'object', properties: { report: { type: 'string' } }, required: ['report'] }
+  const reviewed = await agent(
+    'Review the code phase ' + phaseArg + ' changed, following your agent definition. Get the scope with the ' + PAN_TOOLS + ' Run review scope ' + phaseArg + ' (JSON: the changed files, the unlisted ones no summary names, and the intent to judge them against: objectives, must_haves, Review Focus) and findings list --phase ' + phaseArg + ' --agent pan-reviewer --status open (your earlier open findings; answer each in resolutions). Review every file in the scope, unlisted ones included. Return your full report, verbatim, closing pan-verdict block included, as report.',
+    { agentType: 'pan-reviewer', label: 'review', phase: 'Review', schema: REPORT })
+  const RECORD = {
+    type: 'object',
+    properties: {
+      verdict: { type: 'string', enum: ['PASS', 'PASS_WITH_WARNINGS', 'NEEDS_FIXES', 'unknown'] },
+      errors: { type: 'integer' },
+      warnings: { type: 'integer' },
+      review_path: { type: 'string' },
+      budget_status: { type: 'string' },
+      budget_line: { type: 'string' },
+    },
+    required: ['verdict'],
+  }
+  review = await agent(
+    'Record a PAN code review for phase ' + phaseArg + ' with the ' + PAN_TOOLS + ' (1) Write the report below, verbatim and in full, to ' + (index.phase_dir || '.planning/phases/<phase dir>') + '/' + (index.phase_number || phaseArg) + '-review.md. (2) Run findings record --phase ' + phaseArg + ' --agent pan-reviewer --file <that path> --raw and take the verdict it prints (if it fails, read the word under ### Verdict in the report). (3) If the verdict is PASS_WITH_WARNINGS, run findings dispose --phase ' + phaseArg + ' --agent pan-reviewer --open --as deferred --reason "accepted at review: PASS_WITH_WARNINGS". (4) Run cost budget --phase ' + phaseArg + ' and report its status as budget_status; when it is near or over, set budget_line to "Spend: <spent_usd> of the <budget_usd> phase budget (<pct>%)", adding "over budget: the phase keeps running" for over. The budget warns, it never blocks. Return verdict, error and warning counts, review_path, budget_status and budget_line. Do not change any code.\\n\\nREPORT:\\n' + ((reviewed && reviewed.report) || '(the reviewer returned no report)'),
+    { label: 'review-record', phase: 'Review', schema: RECORD })
+  if (review && review.budget_line) log(review.budget_line)
+  if (!review || !review.verdict || review.verdict === 'NEEDS_FIXES' || review.verdict === 'unknown') {
+    return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, review, halted: 'review', next: 'The review ' + (review ? 'found errors (' + review.verdict + ')' : 'returned no verdict') + '. Fix them and re-run /pan-exec-waves ' + phaseArg + ', or continue past them with /pan:exec-phase ' + phaseArg + ', which asks and records why. Do not mark the phase complete yet.' }
+  }
+}
+
 // workflow.verifier: false (/pan:settings) turns the phase verifier off, as in exec-phase.
 if (index.verifier_enabled === false) {
-  return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: null, next: 'Verification skipped: workflow.verifier is off. /pan:verify-phase ' + phaseArg + ' verifies on demand; then continue with /pan:exec-phase ' + phaseArg + ' (transition)' }
+  return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, review, verification: null, next: 'Verification skipped: workflow.verifier is off. /pan:verify-phase ' + phaseArg + ' verifies on demand; then continue with /pan:exec-phase ' + phaseArg + ' (transition)' }
 }
 
 phase('Verify')
@@ -2476,9 +2592,9 @@ const gate = await agent(
   { label: 'gate', phase: 'Gate', schema: GATE })
 const gateReasons = gate && Array.isArray(gate.reasons) ? gate.reasons : []
 if (!gate || gate.ok !== true) {
-  return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, gate, halted: 'phase_gate', next: 'The phase gate refused: ' + (gateReasons.map((r) => r.code).join(', ') || 'the gate step returned no verdict') + '. Fix each reason (or close the gaps with /pan:plan-phase ' + phaseArg + ' --gaps), then re-run /pan:exec-phase ' + phaseArg + '. Do not mark the phase complete until the gate passes.' }
+  return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, review, verification: verdict, gate, halted: 'phase_gate', next: 'The phase gate refused: ' + (gateReasons.map((r) => r.code).join(', ') || 'the gate step returned no verdict') + '. Fix each reason (or close the gaps with /pan:plan-phase ' + phaseArg + ' --gaps), then re-run /pan:exec-phase ' + phaseArg + '. Do not mark the phase complete until the gate passes.' }
 }
-return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, gate, next: 'The phase gate passes. Continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
+return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, review, verification: verdict, gate, next: 'The phase gate passes. Continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
 `;
 
   const diagnoseIssues = `export const meta = {
@@ -2589,6 +2705,7 @@ const {
   PAN_AGENTS_END,
   buildAgentsMdSection,
   upsertAgentsMdSection,
+  sectionState,
   removeAgentsMdSection,
   ensureClaudeMdImport,
   removeClaudeMdImport,
@@ -2597,6 +2714,8 @@ const {
 // ─── Exports ────────────────────────────────────────────────────────────────
 
 module.exports = {
+  withClaudeUserInvokedOnly,
+  renderCommandAlias,
   // Constants
   colorNameToHex,
   claudeToOpencodeTools,
@@ -2696,6 +2815,7 @@ module.exports = {
   // AGENTS.md universal rules layer (ADR-0028 Phase 3)
   buildAgentsMdSection,
   upsertAgentsMdSection,
+  sectionState,
   removeAgentsMdSection,
   ensureClaudeMdImport,
   removeClaudeMdImport,

package/bin/install.js

@@ -47,7 +47,7 @@ const pkg = require('../package.json');
 // that keep the advice actionable. Nothing in PAN gates on these values.
 const RECOMMENDED_MODELS = {
   flagship: 'claude-fable-5-1',
-  reasoningTier: 'claude-opus-5 / claude-opus-4-8',
+  reasoningTier: 'claude-opus-5-5',
 };
 
 // Source repo root — prevent installing PAN into its own source directory
@@ -673,7 +673,14 @@ function mirrorUnifiedSkillsForClaude(sharedSkillsDir, targetDir, prefix) {
     try {
       fs.mkdirSync(destDir, { recursive: true });
       for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-        if (entry.isFile()) fs.copyFileSync(path.join(srcDir, entry.name), path.join(destDir, entry.name));
+        if (!entry.isFile()) continue;
+        // SKILL.md gains disable-model-invocation for Claude Code (M49); the shared
+        // tree keeps the plain file, since no other runtime was seen to read the field.
+        if (entry.name === 'SKILL.md') {
+          fs.writeFileSync(path.join(destDir, entry.name), lib.withClaudeUserInvokedOnly(fs.readFileSync(path.join(srcDir, entry.name), 'utf8')));
+        } else {
+          fs.copyFileSync(path.join(srcDir, entry.name), path.join(destDir, entry.name));
+        }
       }
       copied++;
     } catch (err) { pushInstallWarning('claudeSkillMirror', `skills/${name}`, err); }
@@ -845,6 +852,33 @@ function copyCommandsAsCopilotSkills(srcDir, skillsDir, prefix, pathPrefix, runt
  * @param {string} pathPrefix - Path prefix for file references
  * @param {string} runtime - Target runtime ('claude', 'opencode', 'gemini', 'codex', 'copilot')
  */
+/**
+ * The command source every runtime installs from: commands/pan/ plus an alias command
+ * for each renamed command (COMMAND_ALIASES, program L7), so an old name keeps working
+ * on all five runtimes. The aliases are generated into a staging copy in the OS temp
+ * directory, removed when the installer exits; with no aliases it is commands/pan/.
+ */
+let stagedCommandSource = null;
+function stageCommandSource(src) {
+  const panSrc = path.join(src, 'commands', 'pan');
+  if (stagedCommandSource && stagedCommandSource.src === src) return stagedCommandSource.dir;
+  let aliases = {};
+  try { aliases = require(path.join(src, 'pan-wizard-core', 'bin', 'lib', 'constants.cjs')).COMMAND_ALIASES || {}; } catch {}
+  if (Object.keys(aliases).length === 0) return panSrc;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-commands-'));
+  for (const f of fs.readdirSync(panSrc)) {
+    if (f.endsWith('.md')) fs.copyFileSync(path.join(panSrc, f), path.join(dir, f));
+  }
+  for (const [oldName, alias] of Object.entries(aliases)) {
+    const target = path.join(panSrc, `${alias.to}.md`);
+    if (!fs.existsSync(target) || fs.existsSync(path.join(panSrc, `${oldName}.md`))) continue;
+    fs.writeFileSync(path.join(dir, `${oldName}.md`), lib.renderCommandAlias(fs.readFileSync(target, 'utf8'), oldName, alias));
+  }
+  stagedCommandSource = { src, dir };
+  process.on('exit', () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch {} });
+  return dir;
+}
+
 function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand = false) {
   const isOpencode = runtime === 'opencode';
   const isCodex = runtime === 'codex';
@@ -907,6 +941,9 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
           content = convertClaudeToCopilotMarkdown(content);
           fs.writeFileSync(destPath, content);
         } else {
+          // Claude Code: PAN's commands are user-invoked only (M49), so their
+          // descriptions stay out of the listing the model gets every turn.
+          if (runtime === 'claude' && isCommand) content = lib.withClaudeUserInvokedOnly(content);
           fs.writeFileSync(destPath, content);
         }
       } catch (err) {
@@ -2244,6 +2281,8 @@ function install(isGlobal, runtime = 'claude') {
       // With its newline, as the per-runtime core writes it: `/pan:update` cats the file
       // and prints the runtime flag next, which glued onto a bare version.
       try { fs.writeFileSync(path.join(sharedCoreDest, 'VERSION'), pkg.version + '\n'); } catch { /* non-fatal */ }
+      // `/pan:update` points at the changelog beside VERSION, so the shared core carries it too.
+      try { fs.copyFileSync(path.join(src, 'CHANGELOG.md'), path.join(sharedCoreDest, 'CHANGELOG.md')); } catch { /* non-fatal */ }
 
       // Canonical agent-definition reference copies (ADR-0028 agent-ref
       // canonicalization): shared content references these instead of the
@@ -2264,7 +2303,7 @@ function install(isGlobal, runtime = 'claude') {
       }
       console.log(`  ${green}✓${reset} Installed shared pan-wizard-core to ${isGlobal ? '~/.agents/' : '.agents/'}`);
 
-      const panSrc = path.join(src, 'commands', 'pan');
+      const panSrc = stageCommandSource(src);
       copyCommandsAsUnifiedSkills(panSrc, skillsDir, 'pan', pathPrefix, corePrefix, runtime);
       sweepProprietaryCommandSurfaces(targetDir, runtime);
 
@@ -2293,7 +2332,7 @@ function install(isGlobal, runtime = 'claude') {
       fs.mkdirSync(commandDir, { recursive: true });
 
       // Copy commands/pan/*.md as commands/pan-*.md (flatten structure)
-      const panSrc = path.join(src, 'commands', 'pan');
+      const panSrc = stageCommandSource(src);
       copyFlattenedCommands(panSrc, commandDir, 'pan', pathPrefix, runtime);
 
       // Upgrade path: remove PAN files left in the legacy singular command/
@@ -2317,7 +2356,7 @@ function install(isGlobal, runtime = 'claude') {
       // Codex reads skills from the shared .agents/skills tree (repo or user
       // scope) — $CODEX_HOME/skills is no longer a read location (2026-06).
       const skillsDir = getCodexSkillsRoot(isGlobal);
-      const panSrc = path.join(src, 'commands', 'pan');
+      const panSrc = stageCommandSource(src);
       copyCommandsAsCodexSkills(panSrc, skillsDir, 'pan', pathPrefix, runtime);
 
       // Upgrade path: remove pan-* skills left in the legacy .codex/skills/
@@ -2340,7 +2379,7 @@ function install(isGlobal, runtime = 'claude') {
       }
     } else if (isCopilot) {
       const skillsDir = path.join(targetDir, 'skills');
-      const panSrc = path.join(src, 'commands', 'pan');
+      const panSrc = stageCommandSource(src);
       copyCommandsAsCopilotSkills(panSrc, skillsDir, 'pan', pathPrefix, runtime);
       const installedSkills = fs.readdirSync(skillsDir, { withFileTypes: true })
         .filter(e => e.isDirectory() && e.name.startsWith('pan-'));
@@ -2354,7 +2393,7 @@ function install(isGlobal, runtime = 'claude') {
       const commandsDir = path.join(targetDir, 'commands');
       fs.mkdirSync(commandsDir, { recursive: true });
 
-      const panSrc = path.join(src, 'commands', 'pan');
+      const panSrc = stageCommandSource(src);
       const panDest = path.join(commandsDir, 'pan');
       copyWithPathReplacement(panSrc, panDest, pathPrefix, runtime, true);
       if (verifyInstalled(panDest, 'commands/pan')) {
@@ -2671,15 +2710,23 @@ function install(isGlobal, runtime = 'claude') {
       const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
       let agentsExisting = null;
       try { agentsExisting = fs.readFileSync(agentsMdPath, 'utf8'); } catch { /* absent */ }
-      fs.writeFileSync(agentsMdPath, lib.upsertAgentsMdSection(agentsExisting, lib.buildAgentsMdSection()));
-      console.log(`  ${green}✓${reset} ${agentsExisting === null ? 'Created' : 'Updated'} AGENTS.md (PAN section)`);
+      if (lib.sectionState(agentsExisting, 'agents') === 'edited') {
+        // The project rewrote PAN's section for itself: an update must not put PAN's
+        // generic text back over it (field report, 2026-10-21).
+        console.log(`  ${yellow}!${reset} AGENTS.md: kept the PAN section this project edited. To take PAN's current text, delete the section between the PAN WIZARD markers and run the installer again.`);
+      } else {
+        fs.writeFileSync(agentsMdPath, lib.upsertAgentsMdSection(agentsExisting, lib.buildAgentsMdSection()));
+        console.log(`  ${green}✓${reset} ${agentsExisting === null ? 'Created' : 'Updated'} AGENTS.md (PAN section)`);
+      }
 
       if (runtime === 'claude') {
         const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
         let claudeExisting = null;
         try { claudeExisting = fs.readFileSync(claudeMdPath, 'utf8'); } catch { /* absent */ }
         const bridged = lib.ensureClaudeMdImport(claudeExisting);
-        if (bridged !== claudeExisting) {
+        if (lib.sectionState(claudeExisting, 'claude') === 'edited') {
+          console.log(`  ${yellow}!${reset} CLAUDE.md: kept the PAN block this project edited (the @AGENTS.md import and compact instructions).`);
+        } else if (bridged !== claudeExisting) {
           fs.writeFileSync(claudeMdPath, bridged);
           console.log(`  ${green}✓${reset} Bridged CLAUDE.md to AGENTS.md (@AGENTS.md import)`);
         }
@@ -2795,7 +2842,7 @@ function install(isGlobal, runtime = 'claude') {
       // Print the path we actually wrote. The hardcoded '.codex/hooks.json' was
       // wrong for --global and for --config-dir, telling users to inspect a file
       // that does not exist while the real one sat elsewhere.
-      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksJsonPath)}: update check, context monitor, cost + trace loggers, stop guard, state re-injection)`);
+      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksJsonPath)}: update check, guard, cost + trace loggers, stop guard, state re-injection)`);
     } catch (e) {
       pushInstallWarning('codexHooks', 'hooks.json', e);
     }
@@ -2812,7 +2859,7 @@ function install(isGlobal, runtime = 'claude') {
       fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
       fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
       // Same as the Codex case: a global Copilot install writes to ~/.copilot/, not .github/.
-      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers, stop guard, state re-injection)`);
+      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, guard, cost + trace loggers, stop guard, state re-injection)`);
     } catch (e) {
       console.error(`  ${yellow}✗${reset} Failed to write Copilot hooks config: ${e.message}`);
     }

package/commands/pan/army.md

@@ -133,7 +133,7 @@ Spawn the conductor in campaign mode (it plans, it does not code). It decomposes
 Spawn the Quality squad on the built tree (parallel, read-only). Merge findings into one verdict (`/pan:review-deep` if available). `block` / `review_required` → fix serially, then re-review. Never integrate red.
 
 ### Phase 5 — Integrate (Release, human-gated)
-Spawn `pan-release`. It prepares the squash-merge, runs the configured `verification`, and surfaces an **always-ask** approval request. A human approves the merge to the protected branch; release then tags and records the rollback target. `--push` pushes the approved result.
+Spawn `pan-release`. It prepares the squash-merge, runs the configured `verification`, stages the merge with `pan-tools merge request <branch> --phase <N>`, and surfaces an **always-ask** approval request. A human approves the merge to the protected branch by running `pan-tools merge confirm <branch>` in their own terminal. The command refuses without an interactive terminal, so no agent can approve its own merge. On a runtime where nobody is at a terminal, the campaign stops at this gate; release then tags and records the rollback target. `--push` pushes the approved result.
 
 **Teardown after the merge lands (P-1815):** worktrees are scaffolding, not deliverables — the squash-merge is the permanent artifact. Once the approval lands, remove each integrated task's worktree **and** its branch in one call: `pan-tools worktree remove ../pan-army-<slug> --branch army/<slug>`. The `--branch` half is not optional: a squash-merged branch never looks merged to git, so nothing else will ever clean it. At campaign end — and on **any** abort path — sweep whatever remains: `pan-tools worktree cleanup` (`--force` also discards dirty worktrees and unintegrated branches; without it the sweep keeps anything that might hold the only copy of work, and says exactly why and how to delete it). A campaign that ends with `pan-tools worktree list` non-empty has skipped this step.