pan-wizard 3.33.0 → 3.34.0

package/agents/pan-research-synthesizer.md

@@ -1,6 +1,6 @@
 ---
 name: pan-research-synthesizer
-description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project after 4 researcher agents complete.
+description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project or /pan:milestone-new after 4 researcher agents complete.
 tools: Read, Write, Bash
 color: purple
 effort: medium
@@ -11,7 +11,7 @@ You are a PAN research synthesizer. You read the outputs from 4 parallel researc
 
 You are spawned by:
 
-- `/pan:new-project` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
+- `/pan:new-project` or `/pan:milestone-new` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
 
 Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
 

package/agents/pan-reviewer.md

@@ -26,7 +26,7 @@ Before reviewing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.agents/skills/` directory if it exists:
-1. List available skills (subdirectories)
+1. List available skills (subdirectories), skipping PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there)
 2. Read `SKILL.md` for each skill
 3. Load specific `rules/*.md` files as needed during review
 4. Apply skill rules when checking conventions and quality
@@ -45,7 +45,7 @@ Discover project-specific conventions from these sources (in priority order):
 
 **CRITICAL: Project Scope Boundary**
 These directories are PAN Wizard infrastructure — NEVER review, flag, or suggest changes to files inside them:
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/`
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and PAN's files under `.github/`: `pan-wizard-core/`, `pan-local-patches/`, the `pan-*` entries in `agents/`, `skills/` and `hooks/`, `hooks/pan.json`, `package.json` and `pan-file-manifest.json`
 If a changed file path starts with any of these prefixes, **skip it silently**.
 
 ## Security Patterns
@@ -69,6 +69,28 @@ If a changed file path starts with any of these prefixes, **skip it silently**.
 | Duplicate code | > 10 identical lines across files | INFO |
 | TODO/FIXME/HACK | New instances added in this phase | INFO |
 
+## Design smells (baseline)
+
+A fixed baseline that applies even when the project documents no standards (Fowler, *Refactoring*, ch. 3). Rules:
+- Each is a judgement call: always **INFO**, written as "possible <smell>", never a reason for a non-PASS verdict on its own.
+- **The project wins.** Where a documented project standard, or an established pattern in the code, endorses what a smell would flag, do not report it. Skip anything a linter or formatter already enforces.
+- Only for code this phase changed, and only with a file:line and the hunk that shows it.
+
+| Smell | What it looks like in the diff | Usual fix |
+|-------|-------------------------------|-----------|
+| Mysterious Name | A name that does not say what it does or holds | Rename; if no honest name comes, the design is unclear |
+| Duplicated Code | The same logic shape in more than one hunk or file | Extract it and call it from both |
+| Feature Envy | A function reaching into another object's data more than its own | Move it onto the data it uses |
+| Data Clumps | The same few fields or parameters always travelling together | Bundle them into one type |
+| Primitive Obsession | A string or number standing in for a domain concept | Give the concept a small type |
+| Repeated Switches | The same switch or if-chain on the same type in several places | One map or polymorphism both sites share |
+| Shotgun Surgery | One logical change forcing scattered edits across many files | Gather what changes together into one module |
+| Divergent Change | One file edited for several unrelated reasons | Split so each module changes for one reason |
+| Speculative Generality | Abstractions, parameters or hooks no task or requirement needs | Inline it back until a real need shows. Unrequested *behaviour* is the Scope section's `Unrequested` finding, not this smell; report the same code once |
+| Message Chains | Long `a.b().c().d()` navigation the caller should not depend on | Hide the walk behind one method |
+| Middle Man | A function or class that mostly delegates onward | Call the real target directly |
+| Refused Bequest | An implementer that ignores or overrides most of what it inherits | Prefer composition |
+
 ## Scope (unrequested work)
 
 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.

package/agents/pan-roadmapper.md

@@ -1,6 +1,6 @@
 ---
 name: pan-roadmapper
-description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /pan:new-project orchestrator.
+description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /pan:new-project or /pan:milestone-new orchestrator.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
 effort: high
@@ -12,6 +12,7 @@ You are a PAN roadmapper. You create project roadmaps that map requirements to p
 You are spawned by:
 
 - `/pan:new-project` orchestrator (unified project initialization)
+- `/pan:milestone-new` orchestrator (the next milestone's roadmap)
 
 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.
 
@@ -129,7 +130,7 @@ Requirement that supports no criterion:
 
 ## Example Gap Resolution
 
-```
+```text
 Phase 2: Authentication
 Goal: Users can securely access their accounts
 
@@ -208,7 +209,7 @@ Read depth from config.json. Depth controls compression tolerance.
 ## Good Phase Patterns
 
 **Foundation → Features → Enhancement**
-```
+```text
 Phase 1: Setup (project scaffolding, CI/CD)
 Phase 2: Auth (user accounts)
 Phase 3: Core Content (main features)
@@ -217,7 +218,7 @@ Phase 5: Polish (performance, edge cases)
 ```
 
 **Vertical Slices (Independent Features)**
-```
+```text
 Phase 1: Setup
 Phase 2: User Profiles (complete feature)
 Phase 3: Content Creation (complete feature)
@@ -225,7 +226,7 @@ Phase 4: Discovery (complete feature)
 ```
 
 **Anti-Pattern: Horizontal Layers**
-```
+```text
 Phase 1: All database models ← Too coupled
 Phase 2: All API endpoints ← Can't verify independently
 Phase 3: All UI components ← Nothing works until end
@@ -241,7 +242,7 @@ After phase identification, verify every v1 requirement is mapped.
 
 **Build coverage map:**
 
-```
+```text
 AUTH-01 → Phase 2
 AUTH-02 → Phase 2
 AUTH-03 → Phase 2
@@ -256,7 +257,7 @@ Mapped: 12/12 ✓
 
 **If orphaned requirements found:**
 
-```
+```text
 ⚠️ Orphaned requirements (no phase):
 - NOTF-01: User receives in-app notifications
 - NOTF-02: User receives email for followers
@@ -304,17 +305,17 @@ After roadmap creation, requirements.md gets updated with phase mappings:
 
 ```markdown
 ### Phase 1: Name
-**Goal**: What this phase delivers
-**Depends on**: Nothing (first phase)
-**Requirements**: REQ-01, REQ-02
+**Goal:** What this phase delivers
+**Depends on:** Nothing (first phase)
+**Requirements:** REQ-01, REQ-02
 **Success Criteria** (what must be TRUE):
   1. Observable behavior from user perspective
   2. Observable behavior from user perspective
-**Plans**: TBD
+**Plans:** TBD
 
 ### Phase 2: Name
-**Goal**: What this phase delivers
-**Depends on**: Phase 1
+**Goal:** What this phase delivers
+**Depends on:** Phase 1
 ...
 ```
 
@@ -363,7 +364,7 @@ Parse requirements.md:
 - Extract categories (AUTH, CONTENT, etc.)
 - Build requirement list with IDs
 
-```
+```text
 Categories: 4
 - Authentication: 3 requirements (AUTH-01, AUTH-02, AUTH-03)
 - Profiles: 2 requirements (PROF-01, PROF-02)

package/agents/pan-verifier.md

@@ -23,7 +23,7 @@ Before verifying, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.agents/skills/` directory if it exists:
-1. List available skills (subdirectories)
+1. List available skills (subdirectories), skipping PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
 4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
@@ -57,7 +57,7 @@ cat "$PHASE_DIR"/*-verification.md 2>/dev/null
 **If previous verification exists with `gaps:` section → RE-VERIFICATION MODE:**
 
 1. Parse previous verification.md frontmatter
-2. Extract `must_haves` (truths, artifacts, key_links)
+2. Take `must_haves` (truths, artifacts, key_links) from the plans' frontmatter (Step 2, Option A): the verification frontmatter does not store them
 3. Extract `gaps` (items that failed)
 4. Set `is_re_verification = true`
 5. **Skip to Step 3** with optimization:
@@ -73,8 +73,9 @@ Set `is_re_verification = false`, proceed with Step 0b.
 If the current phase number > 1, check that the previous phase was verified:
 
 ```bash
-# 10# reads a zero-padded number like 08 as decimal (bash would read it as octal)
-PREV_PHASE=$((10#${PHASE_NUM%%[!0-9]*} - 1))
+# The previous phase: 2.1 → 2, 12A → 12, otherwise N-1 (10# reads a zero-padded 08 as
+# decimal; bash would read it as octal). verify-phase computes it the same way.
+case "$PHASE_NUM" in *.*) PREV_PHASE="${PHASE_NUM%%.*}" ;; *[A-Za-z]) PREV_PHASE="${PHASE_NUM%[A-Za-z]}" ;; *) PREV_PHASE=$((10#$PHASE_NUM - 1)) ;; esac
 PREV_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "$PREV_PHASE" --raw 2>/dev/null)
 [ -n "$PREV_DIR" ] && ls "$PREV_DIR"/*-verification.md 2>/dev/null
 ```
@@ -96,10 +97,10 @@ Proceed to Step 1.
 ls "$PHASE_DIR"/*-plan.md 2>/dev/null
 ls "$PHASE_DIR"/*-summary.md 2>/dev/null
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM"
-grep -E "^\|[^|]*\| *Phase +$PHASE_NUM " .planning/requirements.md 2>/dev/null
+grep -E "^\|[^|]*\| *Phase +0*${PHASE_NUM#0} " .planning/requirements.md 2>/dev/null
 ```
 
-Extract phase goal from roadmap.md — this is the outcome to verify, not the tasks.
+Extract the phase goal from the `get-phase` output — this is the outcome to verify, not the tasks. If your prompt names a roadmap slice, read it for the phase's requirement lines. Do not read roadmap.md or requirements.md whole: `get-phase`, the slice and the greps here carry what verification needs.
 
 ## Step 1c: Repo-Norms-First Verification (P-RES-005)
 
@@ -173,7 +174,7 @@ must_haves:
 If no must_haves in frontmatter, check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
+PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM")
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -272,8 +273,8 @@ Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, ver
 
 For each link:
 - `verified=true` → WIRED
-- `verified=false` with "not found" in detail → NOT_WIRED
-- `verified=false` with "Pattern not found" → PARTIAL
+- `verified=false` with detail "Source file not found" or "Target not referenced in source" → NOT_WIRED
+- `verified=false` with detail `Pattern "…" not found in source or target` → PARTIAL
 
 **Fallback patterns** (if must_haves.key_links not defined in PLAN):
 
@@ -327,7 +328,7 @@ Extract the tier table rows (T1/T2/T3/T4) and their expected coverage areas.
 
 | Check | Action | Status |
 |-------|--------|--------|
-| T1 declared | Scan for unit test files matching plan `test_pattern` | COVERED / GAP |
+| T1 declared | Scan for the unit test files the plan's `<verify>` commands run | COVERED / GAP |
 | T2 declared | Verify integration test + infrastructure (Docker/testcontainers) present | COVERED / GAP |
 | T3 declared | Verify E2E/CLI tests exist with setup instructions | COVERED / GAP |
 | T4 declared | Verify visual/Playwright tests with snapshot baseline | COVERED / GAP |
@@ -354,7 +355,7 @@ Collect ALL requirement IDs declared across plans for this phase.
 **6b. Cross-reference against requirements.md:**
 
 For each requirement ID from plans:
-1. Find its full description in requirements.md (`**REQ-ID**: description`)
+1. Find its full description (`**REQ-ID**: description`) in the slice's `## Its requirements`, or with `grep -n "REQ-ID" .planning/requirements.md` when there is no slice or the ID is missing from it
 2. Map to supporting truths/artifacts verified in Steps 3-5
 3. Determine status:
    - ✓ SATISFIED: Implementation evidence found that fulfills the requirement
@@ -364,7 +365,7 @@ For each requirement ID from plans:
 **6c. Check for orphaned requirements:**
 
 ```bash
-grep -E "Phase $PHASE_NUM" .planning/requirements.md 2>/dev/null
+grep -E "^\|[^|]*\| *Phase +0*${PHASE_NUM#0} " .planning/requirements.md 2>/dev/null
 ```
 
 If requirements.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
@@ -375,10 +376,10 @@ Identify files modified in this phase from summary.md key-files section, or extr
 
 ```bash
 # Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$PHASE_DIR"/*-summary.md --fields key-files)
+SUMMARY_FILES=$(for s in "$PHASE_DIR"/*-summary.md; do node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$s" --fields key_files; done)
 
 # Option 2: Verify commits exist (if commit hashes documented)
-COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-summary.md | head -10)
+COMMIT_HASHES=$(grep -ohE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-summary.md | head -10)
 if [ -n "$COMMIT_HASHES" ]; then
   COMMITS_VALID=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify commits $COMMIT_HASHES)
 fi
@@ -533,27 +534,32 @@ gaps:
 
 Record `verified_commit` from `git rev-parse HEAD` before you write the file. It ties the verdict to the code you checked: `pan-tools verify stale <phase>` and `pan-tools progress` compare the phase's files against it, and a file changed since then marks this verification stale.
 
-Create `.planning/phases/{phase_dir}/{phase_num}-verification.md`:
+Create `{phase_dir}/{phase_number}-verification.md` (`{phase_dir}` is already the full path from the project root, e.g. `.planning/phases/05-auth` or `.planning/tracks/<name>/phases/05-auth`: do not prefix it):
 
 ```markdown
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
-verified_commit: <sha> # `git rev-parse HEAD` before you write this file: the code you verified
+# verified_commit: `git rev-parse HEAD` before you write this file: the code you verified
+verified_commit: <sha>
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
-test_gate: passed | failed | skipped # Step 8b
-not_checked: # Only for checks that could not run — never count them as passed
+# test_gate: Step 8b
+test_gate: passed | failed | skipped
+# not_checked: only for checks that could not run — never count them as passed
+not_checked:
   - check: "tests"
     reason: "no test script in package.json"
-re_verification: # Only if previous verification.md existed
+# re_verification: only if a previous verification.md existed
+re_verification:
   previous_status: gaps_found
   previous_score: 2/5
   gaps_closed:
     - "Truth that was fixed"
   gaps_remaining: []
   regressions: []
-gaps: # Only if status: gaps_found
+# gaps: only if status: gaps_found
+gaps:
   - truth: "Observable truth that failed"
     status: failed
     reason: "Why it failed"
@@ -562,11 +568,13 @@ gaps: # Only if status: gaps_found
         issue: "What's wrong"
     missing:
       - "Specific thing to add/fix"
-human_verification: # Only if status: human_needed
+# human_verification: only if status: human_needed
+human_verification:
   - test: "What to do"
     expected: "What should happen"
     why_human: "Why can't verify programmatically"
-unrequested: # Only if Step 7c found work no plan asked for
+# unrequested: only if Step 7c found work no plan asked for
+unrequested:
   - path: "src/path/to/file.tsx"
     what: "What it adds that no plan or requirement asked for"
 ---
@@ -639,7 +647,7 @@ Return with:
 
 **Status:** {passed | gaps_found | human_needed}
 **Score:** {N}/{M} must-haves verified
-**Report:** .planning/phases/{phase_dir}/{phase_num}-verification.md
+**Report:** {phase_dir}/{phase_number}-verification.md
 
 {If passed:}
 All must-haves verified. Phase goal achieved. Ready to proceed.
@@ -735,7 +743,7 @@ return <div>No messages</div>  // Always shows "no messages"
 <success_criteria>
 
 - [ ] Previous verification.md checked (Step 0)
-- [ ] If re-verification: must-haves loaded from previous, focus on failed items
+- [ ] If re-verification: must-haves taken from the plans' frontmatter, focus on the previous gaps
 - [ ] If initial: must-haves established (from frontmatter or derived)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels (exists, substantive, wired)

package/bin/install-lib.cjs

@@ -564,6 +564,8 @@ function rewriteSharedCoreMarkdown(content, { corePrefix, pathPrefix, projectDir
   content = content.replace(/\.\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
   content = content.replace(/~\/\.claude\//g, pathPrefix);
   content = content.replace(/\.\/\.claude\//g, projectDirPrefix);
+  // No `pan-tools` bin is on PATH: invoke it via node, as the skill rewrite does.
+  content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${corePrefix}pan-wizard-core/bin/pan-tools.cjs`);
   content = processAttribution(content, attribution);
   return convertSlashCommandsToCopilotSkillMentions(content);
 }
@@ -573,9 +575,29 @@ function rewriteSharedCoreMarkdown(content, { corePrefix, pathPrefix, projectDir
  * under `<shared core>/agents/` — reading material for agents, not a runtime
  * registration (ADR-0028 agent-ref canonicalization).
  */
+/**
+ * Name the agent file this runtime actually installs. A prompt that says "read
+ * ~/.claude/agents/pan-planner.md for your role" becomes `<prefix>agents/pan-planner.md`
+ * after the prefix rewrite, but Codex installs agents as `pan-planner.toml` and Copilot
+ * as `pan-planner.agent.md`, so the spawned agent read nothing and ran with no role.
+ * Idempotent; other runtimes keep `.md`.
+ * @param {string} content
+ * @param {string} runtime - claude | codex | gemini | opencode | copilot
+ * @param {string} pathPrefix - the runtime's rewritten config-dir prefix (ends in `/`)
+ * @returns {string}
+ */
+function rewriteAgentFileRefs(content, runtime, pathPrefix) {
+  const ext = runtime === 'codex' ? '.toml' : runtime === 'copilot' ? '.agent.md' : null;
+  if (!ext || !pathPrefix) return content;
+  const prefix = pathPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return content.replace(new RegExp(`(${prefix}agents/pan-[a-z0-9_-]+)\\.md\\b`, 'g'), (_, base) => base + ext);
+}
+
 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/`);
+  // No `pan-tools` bin is on PATH: invoke it via node, as the skill rewrite does.
+  content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${corePrefix}pan-wizard-core/bin/pan-tools.cjs`);
   return convertSlashCommandsToCopilotSkillMentions(content);
 }
 
@@ -1654,6 +1676,12 @@ function detectModelCapabilities(modelName) {
   if (n.includes('sonnet-5')) {
     return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'mid' };
   }
+  // Haiku 5 family (Haiku 5.5): 1M context and adaptive thinking (pricing page and
+  // Claude Code 2.1.293 changelog, read 2026-10-10). It is a forward release, so
+  // without this it took the fallback's Haiku profile, which is Haiku 4's.
+  if (n.includes('haiku-5')) {
+    return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'fast' };
+  }
   if (n.includes('opus-4-8') || n.includes('opus-4.8')
     || n.includes('opus-4-7') || n.includes('opus-4.7')
     || n.includes('opus-4-6') || n.includes('opus-4.6')) {
@@ -1673,10 +1701,9 @@ function detectModelCapabilities(modelName) {
   if (n.includes('sonnet-4') && !isForwardRelease) {
     return { has_1m_ctx: false, has_thinking: true, has_cache: true, tier: 'mid' };
   }
-  // Haiku 4.x — fast tier, no extended thinking. Guarded for the same reason,
-  // though today it is behavior-neutral: the fallback's Haiku profile is
-  // identical to this one, so a forward Haiku release lands on the same answer
-  // either way. The guard is here so that stops being true only deliberately.
+  // Haiku 4.x — fast tier, no extended thinking. Guarded for the same reason: a
+  // Haiku release newer than 4.5 takes the fallback's modern Haiku profile, which
+  // since Haiku 5.5 has 1M context and thinking.
   if ((n.includes('haiku-4-5') || n.includes('haiku-4.5') || n.includes('haiku-4')) && !isForwardRelease) {
     return { has_1m_ctx: false, has_thinking: false, has_cache: true, tier: 'fast' };
   }
@@ -1749,7 +1776,8 @@ function detectModelCapabilities(modelName) {
     const MODERN = {
       opus: { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'reasoning' },
       sonnet: { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'mid' },
-      haiku: { has_1m_ctx: false, has_thinking: false, has_cache: true, tier: 'fast' },
+      // Haiku 5.5 (the branch above) is the newest Haiku with known capabilities.
+      haiku: { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'fast' },
     };
     return { ...MODERN[family] };
   }
@@ -2035,11 +2063,11 @@ so the result is greppable out of the transcript.
 /**
  * Build the plugin's MCP registration (`.mcp.json` at the plugin root).
  *
- * Plugins may declare MCP servers in a plugin-root `.mcp.json`, and unlike
- * command markdown — where `${CLAUDE_PLUGIN_ROOT}` expansion is unverified and
- * is why marketplace publishing is still gated — hook and MCP *configs* are the
- * documented place the variable is substituted. So the same form
- * `buildPluginHooksConfig()` relies on is correct here.
+ * Plugins may declare MCP servers in a plugin-root `.mcp.json`. Hook and MCP
+ * *configs* are the documented place `${CLAUDE_PLUGIN_ROOT}` is substituted (it
+ * expands in plugin command markdown too: measured 2026-08-14, which lifted the
+ * marketplace-publishing gate). So the same form `buildPluginHooksConfig()` relies
+ * on is correct here.
  *
  * No `env` block: a plugin serves whatever project the session is in, so pinning
  * PAN_PROJECT_ROOT would be wrong, and the server resolves its engine from its
@@ -2097,7 +2125,7 @@ function buildNativeWorkflowScripts() {
   const reviewPipeline = `export const meta = {
   name: 'pan-review-pipeline',
   description: 'PAN deep review: reviewer + hardener fan-out, meta-reviewer merge',
-  whenToUse: 'Deterministic version of the /pan-review-deep fan-out. Pass the phase number or a description of the change set as args.',
+  whenToUse: 'Deterministic version of the /pan:review-deep fan-out. Pass the phase number or a description of the change set as args.',
   phases: [
     { title: 'Find', detail: 'reviewer + security hardener in parallel' },
     { title: 'Merge', detail: 'meta-reviewer dedupes, disputes, and issues the verdict' },
@@ -2162,7 +2190,7 @@ return merged
   const mapCodebase = `export const meta = {
   name: 'pan-map-codebase',
   description: 'PAN codebase mapping: shard fan-out per top-level area, then synthesis',
-  whenToUse: 'Deterministic version of the /pan-map-codebase shard pattern for repositories too large for a single pass.',
+  whenToUse: 'Deterministic version of the /pan:map-codebase shard pattern for repositories too large for a single pass.',
   phases: [
     { title: 'Scan', detail: 'discover top-level areas worth documenting' },
     { title: 'Map', detail: 'one documenter per area, in parallel' },
@@ -2223,7 +2251,7 @@ return { areas_mapped: maps.filter(Boolean).length, synthesis }
   const execWaves = `export const meta = {
   name: 'pan-exec-waves',
   description: 'PAN phase execution: wave-grouped executor fan-out for a checkpoint-free phase, then verification',
-  whenToUse: 'Deterministic version of the /pan-exec-phase wave dispatch. Pass the phase number as args. Refuses a phase that contains checkpoint plans (a workflow cannot pause for a human) — run /pan-exec-phase for those.',
+  whenToUse: 'Deterministic version of the /pan:exec-phase wave dispatch. Pass the phase number as args. Refuses a phase that contains checkpoint plans (a workflow cannot pause for a human) — run /pan:exec-phase for those.',
   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' },
@@ -2249,6 +2277,7 @@ const INDEX = {
     phase_name: { type: 'string' },
     phase_dir: { type: 'string' },
     parallelization: { type: 'boolean' },
+    verifier_enabled: { type: 'boolean' },
     has_checkpoints: { type: 'boolean' },
     plans: {
       type: 'array',
@@ -2269,11 +2298,11 @@ 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; (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, 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.',
   { label: 'index', phase: 'Index', schema: INDEX })
 if (!index || !index.phase_found) return { error: 'phase ' + phaseArg + ' not found' }
 if (index.has_checkpoints) {
-  return { error: 'phase ' + phaseArg + ' contains checkpoint plans (autonomous: false). A workflow cannot pause for a human — run /pan-exec-phase ' + phaseArg + ' instead.', plans: index.plans.map(p => p.id) }
+  return { error: 'phase ' + phaseArg + ' contains checkpoint plans (autonomous: false). A workflow cannot pause for a human — run /pan:exec-phase ' + phaseArg + ' instead.', plans: index.plans.map(p => p.id) }
 }
 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' }
@@ -2297,7 +2326,7 @@ const EXEC_RESULT = {
 const executorPrompt = (p) =>
   'Execute plan ' + p.id + ' of phase ' + (index.phase_number || phaseArg) + (index.phase_name ? '-' + index.phase_name : '') + '. Commit each task atomically. Create summary.md. Update state.md and roadmap.md (via roadmap update-plan-progress).\\n\\n'
   + 'Read first, in this order: ' + CORE_DOCS + '\\n\\n'
-  + 'Then read: ' + (p.file || (index.phase_dir + '/' + p.id)) + ' (the plan), .planning/state.md, .planning/config.json (if present), ./CLAUDE.md (if present — follow its conventions), .agents/skills/ (if present — follow relevant skills), and every .planning/memory/*.md (apply every rule without exception).\\n\\n'
+  + 'Then read: ' + (p.file || (index.phase_dir + '/' + p.id)) + ' (the plan), .planning/state.md, .planning/config.json (if present), ./CLAUDE.md (if present — follow its conventions), and .agents/skills/ (if present — follow relevant skills).\\n\\n'
   + '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
@@ -2326,7 +2355,11 @@ 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 }
+  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 }
+}
+// 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)' }
 }
 
 phase('Verify')
@@ -2344,13 +2377,13 @@ const verdict = await agent(
   'Verify phase ' + phaseArg + ' following the PAN verify-phase protocol (PAN core: workflows/verify-phase.md — ' + PAN_TOOLS + '). Check the phase goals against what the plans delivered, write the verification file the protocol prescribes, and report status (passed | gaps_found | human_needed | failed), the verification file path, any gaps, and a summary. Do not mark the phase complete or advance state — that decision stays with the user.',
   { agentType: 'pan-verifier', label: 'verify', phase: 'Verify', schema: VERIFY })
 
-return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, next: 'Review the verification, then 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, verification: verdict, next: 'Review the verification, then continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
 `;
 
   const diagnoseIssues = `export const meta = {
   name: 'pan-diagnose-issues',
   description: 'PAN UAT diagnosis: one debugger per failed UAT truth, in parallel, then root causes written back',
-  whenToUse: 'Deterministic version of /pan-diagnose-issues. Pass the phase number as args. Investigates only — fixes come from /pan-plan-phase --gaps.',
+  whenToUse: 'Deterministic version of the diagnose-issues workflow. Pass the phase number as args. Investigates only — fixes come from /pan:plan-phase --gaps.',
   phases: [
     { title: 'Gaps', detail: 'read the phase UAT file and list the failed truths' },
     { title: 'Diagnose', detail: 'one pan-debugger per gap, in parallel, root cause only' },
@@ -2404,6 +2437,7 @@ const DIAGNOSIS = {
     issue_id: { type: 'string' },
     status: { type: 'string', enum: ['root_cause_found', 'inconclusive'] },
     root_cause: { type: 'string' },
+    reproduction: { type: 'string' },
     evidence: { type: 'array', items: { type: 'string' } },
     files: { type: 'array', items: { type: 'string' } },
     suggested_fix: { type: 'string' },
@@ -2413,9 +2447,9 @@ const DIAGNOSIS = {
   required: ['issue_id', 'status'],
 }
 const diagnoses = await parallel(gaps.map(g => () => agent(
-  'Debug issue UAT-' + g.test_num + ' for phase ' + phaseArg + ' — root cause ONLY, do not fix (fixes come from /pan-plan-phase --gaps).\\n\\n'
+  'Debug issue UAT-' + g.test_num + ' for phase ' + phaseArg + ' — root cause ONLY, do not fix (fixes come from /pan:plan-phase --gaps).\\n\\n'
   + 'Symptoms (pre-filled from UAT, treat as given): expected: ' + (g.expected || g.truth) + '. actual: ' + (g.reason || 'not recorded') + '. reproduction: test ' + g.test_num + ' in ' + found.uat_path + '. severity: ' + g.severity + '.\\n\\n'
-  + 'Follow the PAN debugger protocol: create the debug session file under .planning/debug/ named from the issue, investigate autonomously (read code, form hypotheses, test them), and report issue_id, status (root_cause_found | inconclusive), root_cause with evidence, files involved, a suggested fix direction, and the debug session path. If inconclusive, list the remaining possibilities. Also read ' + found.uat_path + ' and .planning/state.md for context.',
+  + 'Follow the PAN debugger protocol: create the debug session file under .planning/debug/ named from the issue, build and run a command that fails on the symptom before forming any hypothesis, investigate autonomously (read code, form hypotheses, test them), and report issue_id, status (root_cause_found | inconclusive), the reproduction command (or none, with what you tried), root_cause with evidence, files involved, a suggested fix direction, and the debug session path. If inconclusive, list the remaining possibilities. Also read ' + found.uat_path + ' and .planning/state.md for context.',
   { agentType: 'pan-debugger', label: 'debug:UAT-' + g.test_num, phase: 'Diagnose', schema: DIAGNOSIS })))
 const results = diagnoses.filter(Boolean)
 log(results.filter(r => r.status === 'root_cause_found').length + ' root cause(s) found, ' + results.filter(r => r.status === 'inconclusive').length + ' inconclusive')
@@ -2427,10 +2461,10 @@ const RECORDED = {
   required: ['uat_path', 'gaps_updated'],
 }
 const recorded = await agent(
-  'Update the Gaps section of ' + found.uat_path + ' with these diagnoses, following the PAN diagnose-issues protocol: for each gap add root_cause, artifacts (the debug session path), the files involved, and the suggested fix direction; mark inconclusive ones as needing manual review with their remaining possibilities. Edit in place — do not rewrite unrelated content. Report the path and how many gaps you updated.\\n\\nDiagnoses:\\n' + JSON.stringify(results, null, 2),
+  'Update the Gaps section of ' + found.uat_path + ' with these diagnoses, following the PAN diagnose-issues protocol: for each gap add root_cause, artifacts (each file involved, with its issue), missing (the suggested fix direction) and debug_session (the debug session path); mark inconclusive ones as needing manual review with their remaining possibilities. Edit the Gaps section in place and set the frontmatter status to diagnosed (the --gaps mode of pan-planner reads UAT gaps only from a diagnosed file); do not rewrite other content. Report the path and how many gaps you updated.\\n\\nDiagnoses:\\n' + JSON.stringify(results, null, 2),
   { label: 'record', phase: 'Record', schema: RECORDED })
 
-return { phase: phaseArg, uat_path: found.uat_path, gaps: gaps.length, root_causes_found: results.filter(r => r.status === 'root_cause_found').length, inconclusive: results.filter(r => r.status === 'inconclusive').length, recorded, next: 'Run /pan-plan-phase ' + phaseArg + ' --gaps to plan the fixes' }
+return { phase: phaseArg, uat_path: found.uat_path, gaps: gaps.length, root_causes_found: results.filter(r => r.status === 'root_cause_found').length, inconclusive: results.filter(r => r.status === 'inconclusive').length, recorded, next: 'Run /pan:plan-phase ' + phaseArg + ' --gaps to plan the fixes' }
 `;
 
   return [
@@ -2532,6 +2566,7 @@ module.exports = {
   rewriteUnifiedSkillCommandContent,
   rewriteSharedCoreMarkdown,
   rewriteAgentReferenceCopy,
+  rewriteAgentFileRefs,
   stripInternalLearningsTopics,
   AGENT_PLUGINS_VERSION,
   AGENT_PLUGIN_MANIFEST_SCHEMA,