pan-wizard 2.8.1 → 2.9.0

package/pan-wizard-core/bin/lib/verify.cjs

@@ -826,6 +826,16 @@ function repairIssues(cwd, repairs) {
           repairActions.push({ action: repair, success: true, path: CONFIG_FILE });
           break;
         }
+        case 'syncRequirements': {
+          const syncResult = syncRequirementCheckboxes(cwd);
+          repairActions.push({ action: repair, success: !syncResult.error, fixed: syncResult.fixed, error: syncResult.error || undefined });
+          break;
+        }
+        case 'syncRoadmap': {
+          const syncResult = syncRoadmapPlanCheckboxes(cwd);
+          repairActions.push({ action: repair, success: !syncResult.error, fixed: syncResult.fixed, error: syncResult.error || undefined });
+          break;
+        }
         case 'regenerateState': {
           // Create timestamped backup before overwriting to prevent data loss
           try {
@@ -950,13 +960,112 @@ function checkVerificationGate(cwd, addIssue) {
   }
 }
 
+/**
+ * Sync REQUIREMENTS.md checkboxes — mark requirements as complete if their
+ * linked phases are completed in roadmap.md. Returns count of boxes fixed.
+ * @param {string} cwd
+ * @returns {{ fixed: number, error?: string }}
+ */
+function syncRequirementCheckboxes(cwd) {
+  const planDir = planningPath(cwd);
+  const reqPath = path.join(planDir, REQUIREMENTS_FILE);
+  const roadmapPath = path.join(planDir, ROADMAP_FILE);
+
+  let reqContent, roadmapContent;
+  try { reqContent = fs.readFileSync(reqPath, 'utf-8'); } catch { return { fixed: 0, error: 'requirements.md not found' }; }
+  try { roadmapContent = fs.readFileSync(roadmapPath, 'utf-8'); } catch { return { fixed: 0, error: 'roadmap.md not found' }; }
+
+  // Find completed phases (checkbox marked [x] in roadmap)
+  const completedPhases = [];
+  const phaseRe = /- \[x\]\s*.*Phase\s+(\d+(?:\.\d+)?)/gi;
+  let m;
+  while ((m = phaseRe.exec(roadmapContent)) !== null) {
+    completedPhases.push(m[1]);
+  }
+
+  if (completedPhases.length === 0) return { fixed: 0 };
+
+  // For each completed phase, find linked requirement IDs and check their boxes
+  let fixed = 0;
+  for (const phaseNum of completedPhases) {
+    const reqMatch = roadmapContent.match(
+      new RegExp(`Phase\\s+${phaseNum.replace(/\./g, '\\.')}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
+    );
+    if (!reqMatch) continue;
+    const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(id => id.trim()).filter(Boolean);
+    for (const reqId of reqIds) {
+      const escaped = reqId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const re = new RegExp(`(- \\[) (\\]\\s*\\*\\*${escaped}\\*\\*)`, 'gi');
+      const before = reqContent;
+      reqContent = reqContent.replace(re, '$1x$2');
+      if (reqContent !== before) fixed++;
+    }
+  }
+
+  if (fixed > 0) {
+    try { fs.writeFileSync(reqPath, reqContent, 'utf-8'); } catch (e) { return { fixed: 0, error: e.message }; }
+  }
+  return { fixed };
+}
+
+/**
+ * Sync ROADMAP.md plan checkboxes — mark plans as checked if corresponding
+ * summary files exist on disk (indicating execution completed).
+ * @param {string} cwd
+ * @returns {{ fixed: number, error?: string }}
+ */
+function syncRoadmapPlanCheckboxes(cwd) {
+  const planDir = planningPath(cwd);
+  const roadmapPath = path.join(planDir, ROADMAP_FILE);
+
+  let roadmapContent;
+  try { roadmapContent = fs.readFileSync(roadmapPath, 'utf-8'); } catch { return { fixed: 0, error: 'roadmap.md not found' }; }
+
+  // Collect all summary files on disk (indicates plan was executed)
+  const phasesDir = path.join(planDir, PHASES_DIR);
+  const summaryFiles = new Set();
+  try {
+    const dirs = fs.readdirSync(phasesDir, { withFileTypes: true }).filter(d => d.isDirectory());
+    for (const dir of dirs) {
+      try {
+        const files = fs.readdirSync(path.join(phasesDir, dir.name));
+        for (const f of files) {
+          if (isSummaryFile(f)) {
+            // Extract plan stem: "01-02-summary.md" → "01-02"
+            const stem = f.replace(/-summary\.md$/i, '');
+            summaryFiles.add(stem);
+          }
+        }
+      } catch { /* unreadable phase dir */ }
+    }
+  } catch { return { fixed: 0 }; }
+
+  if (summaryFiles.size === 0) return { fixed: 0 };
+
+  // Mark plan checkboxes: "- [ ] 01-02-plan.md" → "- [x] 01-02-plan.md"
+  let fixed = 0;
+  for (const stem of summaryFiles) {
+    const escaped = stem.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(- \\[) (\\]\\s*${escaped}-plan)`, 'gi');
+    const before = roadmapContent;
+    roadmapContent = roadmapContent.replace(re, '$1x$2');
+    if (roadmapContent !== before) fixed++;
+  }
+
+  if (fixed > 0) {
+    try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch (e) { return { fixed: 0, error: e.message }; }
+  }
+  return { fixed };
+}
+
 /**
  * Cross-check STATE.md progress counts against REQUIREMENTS.md checkboxes and ROADMAP.md plan checkboxes.
  * Reports mismatches as warnings so users can run --repair or investigate.
  * @param {string} cwd - Working directory path
  * @param {Function} addIssue - Issue recording callback
+ * @param {string[]} [repairs] - Repair action list (pushed to when repairable)
  */
-function checkStateConsistency(cwd, addIssue) {
+function checkStateConsistency(cwd, addIssue, repairs) {
   const planDir = planningPath(cwd);
   const statePath = path.join(planDir, STATE_FILE);
   const reqPath = path.join(planDir, REQUIREMENTS_FILE);
@@ -983,7 +1092,8 @@ function checkStateConsistency(cwd, addIssue) {
       if (completedPlans > 0 && completedPlans >= totalPlans && uncheckedBoxes > 0) {
         addIssue('warning', 'STATE_REQ_DRIFT',
           `STATE.md shows all plans complete but REQUIREMENTS.md has ${uncheckedBoxes}/${totalBoxes} unchecked checkboxes`,
-          'Run syncRequirementCheckboxes or manually check completed requirement boxes');
+          'Run /pan:health --repair to auto-check completed requirement boxes', true);
+        if (repairs) repairs.push('syncRequirements');
       }
     }
   } catch { /* no REQUIREMENTS.md — not required */ }
@@ -1001,7 +1111,8 @@ function checkStateConsistency(cwd, addIssue) {
       if (completedPlans > 0 && completedPlans >= totalPlans && uncheckedPlans > 0) {
         addIssue('warning', 'STATE_ROADMAP_DRIFT',
           `STATE.md shows all plans complete but ROADMAP.md has ${uncheckedPlans} unchecked plan checkboxes`,
-          'Run cmdRoadmapUpdatePlanProgress for each phase or manually check completed plan boxes');
+          'Run /pan:health --repair to auto-check completed plan boxes', true);
+        if (repairs) repairs.push('syncRoadmap');
       }
     }
   } catch { /* no ROADMAP.md — other checks handle this */ }
@@ -1050,7 +1161,7 @@ function cmdValidateHealth(cwd, options, raw) {
   checkPhaseContents(cwd, addIssue);
 
   // Check 8b: cross-document state consistency
-  checkStateConsistency(cwd, addIssue);
+  checkStateConsistency(cwd, addIssue, repairs);
 
   // Check 8c: verification gate (phases with verifier enabled need verification.md)
   checkVerificationGate(cwd, addIssue);
@@ -1783,6 +1894,169 @@ function cmdRetro(cwd, raw) {
   output(result, raw, rawLines.join('\n'));
 }
 
+// ─── Deployment Validation ──────────────────────────────────────────────────
+
+/**
+ * Detect which PAN runtimes are installed in cwd.
+ * @param {string} cwd
+ * @returns {Array<{runtime: string, configDir: string}>}
+ */
+function detectInstalledRuntimes(cwd) {
+  const RUNTIME_DIRS = [
+    { runtime: 'claude', configDir: '.claude' },
+    { runtime: 'opencode', configDir: '.opencode' },
+    { runtime: 'gemini', configDir: '.gemini' },
+    { runtime: 'codex', configDir: '.codex' },
+    { runtime: 'copilot', configDir: '.github' },
+  ];
+  const found = [];
+  for (const rt of RUNTIME_DIRS) {
+    const manifestPath = path.join(cwd, rt.configDir, 'pan-file-manifest.json');
+    try {
+      fs.accessSync(manifestPath);
+      found.push(rt);
+    } catch (_) { /* not installed */ }
+  }
+  return found;
+}
+
+/**
+ * Validate a single PAN runtime installation.
+ * Checks: manifest files exist, hashes match, settings integrity.
+ * @param {string} cwd
+ * @param {string} configDir - e.g. '.claude'
+ * @param {string} runtime - e.g. 'claude'
+ * @returns {{ status: string, version: string, total_files: number, missing: string[], modified: string[], orphaned: string[], settings_ok: boolean, settings_issues: string[] }}
+ */
+function validateRuntimeInstall(cwd, configDir, runtime) {
+  const crypto = require('crypto');
+  const baseDir = path.join(cwd, configDir);
+  const manifestPath = path.join(baseDir, 'pan-file-manifest.json');
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    return { status: 'broken', version: null, error: `Cannot read manifest: ${e.message}`, total_files: 0, missing: [], modified: [], orphaned: [], settings_ok: false, settings_issues: ['manifest unreadable'] };
+  }
+
+  const missing = [];
+  const modified = [];
+  const files = manifest.files || {};
+  const totalFiles = Object.keys(files).length;
+
+  for (const [relPath, expectedHash] of Object.entries(files)) {
+    const absPath = path.join(baseDir, relPath);
+    try {
+      const content = fs.readFileSync(absPath);
+      const actualHash = crypto.createHash('sha256').update(content).digest('hex');
+      if (actualHash !== expectedHash) {
+        modified.push(relPath);
+      }
+    } catch (_) {
+      missing.push(relPath);
+    }
+  }
+
+  // Check settings integrity (hook paths resolve to real files)
+  const settingsIssues = [];
+  const settingsFile = runtime === 'copilot' ? 'config.json' : 'settings.json';
+  const settingsPath = path.join(baseDir, settingsFile);
+  let settingsOk = true;
+  try {
+    const settingsContent = fs.readFileSync(settingsPath, 'utf8');
+    const settings = JSON.parse(settingsContent);
+    // Check hook paths in settings
+    // Collect all hook command strings from settings
+    const hookCommands = [];
+    const hooks = settings.hooks;
+    if (hooks && typeof hooks === 'object') {
+      for (const hookArr of Object.values(hooks)) {
+        if (!Array.isArray(hookArr)) continue;
+        for (const hook of hookArr) {
+          if (hook.command) hookCommands.push(hook.command);
+        }
+      }
+    }
+    // Copilot/Gemini statusLine
+    if (settings.statusLine && settings.statusLine.command) {
+      hookCommands.push(settings.statusLine.command);
+    }
+    // Claude statusline
+    if (settings.statusline && settings.statusline.command) {
+      hookCommands.push(settings.statusline.command);
+    }
+    for (const cmd of hookCommands) {
+      const parts = cmd.split(/\s+/);
+      const hookFile = parts.find(p => p.endsWith('.js'));
+      if (hookFile) {
+        // Hook paths are relative to cwd, not to config dir
+        const resolvedPath = path.isAbsolute(hookFile) ? hookFile : path.join(cwd, hookFile);
+        try { fs.accessSync(resolvedPath); } catch (_) {
+          settingsIssues.push(`Hook path not found: ${hookFile}`);
+          settingsOk = false;
+        }
+      }
+    }
+  } catch (_) {
+    // No settings file is OK for some runtimes (codex, opencode)
+    if (runtime !== 'codex' && runtime !== 'opencode') {
+      settingsIssues.push(`${settingsFile} missing or unreadable`);
+      settingsOk = false;
+    }
+  }
+
+  const status = missing.length > 0 ? 'broken' : modified.length > 0 ? 'modified' : 'clean';
+
+  return {
+    status,
+    version: manifest.version || null,
+    total_files: totalFiles,
+    missing,
+    modified,
+    orphaned: [],
+    settings_ok: settingsOk,
+    settings_issues: settingsIssues,
+  };
+}
+
+/**
+ * CLI command: validate deployment
+ * Validates PAN installations in the current directory.
+ * @param {string} cwd
+ * @param {boolean} raw
+ */
+function cmdValidateDeployment(cwd, raw) {
+  const runtimes = detectInstalledRuntimes(cwd);
+  if (runtimes.length === 0) {
+    output({ error: 'No PAN installations found in this directory' }, raw);
+    return;
+  }
+
+  const results = {};
+  let overallStatus = 'clean';
+
+  for (const { runtime, configDir } of runtimes) {
+    const result = validateRuntimeInstall(cwd, configDir, runtime);
+    results[runtime] = result;
+    if (result.status === 'broken') overallStatus = 'broken';
+    else if (result.status === 'modified' && overallStatus !== 'broken') overallStatus = 'modified';
+  }
+
+  const summary = {
+    status: overallStatus,
+    runtimes_found: runtimes.length,
+    runtimes: results,
+  };
+
+  const rawLines = [`Deployment status: ${overallStatus} (${runtimes.length} runtimes)`];
+  for (const [rt, r] of Object.entries(results)) {
+    rawLines.push(`  ${rt}: ${r.status} (${r.total_files} files, ${r.missing.length} missing, ${r.modified.length} modified)`);
+  }
+
+  output(summary, raw, rawLines.join('\n'));
+}
+
 module.exports = {
   cmdVerifySummary,
   cmdVerifyPlanStructure,
@@ -1805,4 +2079,9 @@ module.exports = {
   countRoadmapPhases,
   groupGapPatterns,
   checkVerificationGate,
+  cmdValidateDeployment,
+  validateRuntimeInstall,
+  detectInstalledRuntimes,
+  syncRequirementCheckboxes,
+  syncRoadmapPlanCheckboxes,
 };

package/pan-wizard-core/bin/pan-tools.cjs

@@ -309,7 +309,14 @@ async function main() {
     }
 
     case 'resolve-model': {
-      commands.cmdResolveModel(cwd, args[1], raw);
+      const metadataIdx = args.indexOf('--metadata');
+      const metadataJson = metadataIdx !== -1 ? args[metadataIdx + 1] : undefined;
+      commands.cmdResolveModel(cwd, args[1], raw, metadataJson);
+      break;
+    }
+
+    case 'estimate-cost': {
+      commands.cmdEstimateCost(cwd, raw);
       break;
     }
 
@@ -534,8 +541,10 @@ async function main() {
         const fullFlag = args.includes('--full');
         const driftFlag = args.includes('--drift');
         verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag }, raw);
+      } else if (subcommand === 'deployment') {
+        verify.cmdValidateDeployment(cwd, raw);
       } else {
-        error('Unknown validate subcommand. Available: consistency, health');
+        error('Unknown validate subcommand. Available: consistency, health, deployment');
       }
       break;
     }

package/pan-wizard-core/references/model-profiles.md

@@ -1,52 +1,142 @@
-# Model Profiles
+# Model Profiles & Routing
 
-Model profiles control which Claude model each PAN agent uses. This allows balancing quality vs token spend.
+Model profiles control which model tier each PAN agent uses. The routing system maps abstract tiers to provider-specific models, allowing PAN to work across Anthropic, OpenAI, and Google providers.
+
+---
+
+## Tier System
+
+PAN uses three abstract tiers instead of hardcoded model names:
+
+| Tier | Purpose | Anthropic | OpenAI | Google |
+|------|---------|-----------|--------|--------|
+| `reasoning` | Architecture, planning, complex decisions | inherit (Opus) | inherit | inherit |
+| `mid` | Execution, research, verification | Sonnet | mid | mid |
+| `fast` | Read-only extraction, budget tasks | Haiku | fast | fast |
+
+**Why `inherit` for reasoning?** Host runtimes map "opus" to a specific model version. PAN returns `inherit` for reasoning-tier agents, so they use whatever top-tier model the user has configured. This avoids version conflicts and silent fallbacks.
+
+### Legacy Aliases
+
+For backward compatibility, legacy Anthropic model names still work:
+
+| Legacy Name | Maps To | Tier |
+|-------------|---------|------|
+| `opus` | `reasoning` | Top-tier |
+| `sonnet` | `mid` | Mid-tier |
+| `haiku` | `fast` | Budget |
+
+---
 
 ## Profile Definitions
 
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
-| pan-planner | opus | opus | sonnet |
-| pan-roadmapper | opus | sonnet | sonnet |
-| pan-executor | opus | sonnet | sonnet |
-| pan-phase-researcher | opus | sonnet | haiku |
-| pan-project-researcher | opus | sonnet | haiku |
-| pan-research-synthesizer | opus | sonnet | haiku |
-| pan-debugger | opus | sonnet | sonnet |
-| pan-document_code | opus | haiku | haiku |
-| pan-verifier | opus | sonnet | haiku |
-| pan-plan-checker | opus | sonnet | haiku |
-| pan-integration-checker | opus | sonnet | haiku |
-| pan-reviewer | opus | haiku | haiku |
-
-## Profile Philosophy
-
-**quality** - Maximum reasoning power (Opus 4.6 for everything)
-- Opus for ALL agents — no exceptions
-- Use when: quota available, critical architecture work, maximum quality desired
-
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
-- Use when: normal development, good balance of quality and cost
-
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
-- Use when: conserving quota, high-volume work, less critical phases
-
-## Resolution Logic
-
-Orchestrators resolve model before spawning:
+| pan-planner | reasoning | reasoning | mid |
+| pan-roadmapper | reasoning | mid | mid |
+| pan-executor | reasoning | mid | mid |
+| pan-phase-researcher | reasoning | mid | fast |
+| pan-project-researcher | reasoning | mid | fast |
+| pan-research-synthesizer | reasoning | mid | fast |
+| pan-debugger | reasoning | mid | mid |
+| pan-document_code | reasoning | fast | fast |
+| pan-verifier | reasoning | mid | fast |
+| pan-plan-checker | reasoning | mid | fast |
+| pan-integration-checker | reasoning | mid | fast |
+| pan-reviewer | reasoning | fast | fast |
+
+### Profile Philosophy
+
+**quality** — Maximum reasoning power
+- Reasoning tier for ALL agents. Use when quota is available, critical architecture work, or maximum quality is desired.
+
+**balanced** (default) — Smart allocation
+- Reasoning only for planning (where architecture decisions happen). Mid for execution. Fast for read-only tasks. Good balance of quality and cost.
+
+**budget** — Minimal token spend
+- Mid for anything that writes code. Fast for research and verification. Use for high-volume work or less critical phases.
+
+### Cost Multipliers
+
+Relative cost per tier (fast = 1× baseline):
+
+| Tier | Multiplier |
+|------|------------|
+| reasoning | 15× |
+| mid | 3× |
+| fast | 1× |
+
+Use `/pan:profile <profile>` to see estimated cost differences before switching.
 
+---
+
+## Routing Pipeline
+
+Model resolution follows this priority chain:
+
+```
+1. Per-agent override (model_overrides in config.json)     ← highest priority
+2. Per-phase override (<!-- model_tier: X --> in roadmap)
+3. Complexity routing (if strategy = "complexity")
+4. Profile lookup (MODEL_PROFILES[agent][profile])          ← lowest priority
+```
+
+### Provider Detection
+
+PAN auto-detects the LLM provider to map tiers to the right model names:
+
+1. **Explicit config** — `routing.provider` in config.json (if not `"auto"`)
+2. **Environment variable** — `PAN_PROVIDER` env var
+3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google
+4. **Fallback** — Default provider map (Anthropic-style names)
+
+---
+
+## Routing Strategies
+
+Set in `.planning/config.json` under the `routing` section:
+
+### Static (default)
+
+```json
+{
+  "routing": {
+    "strategy": "static"
+  }
+}
 ```
-1. Read .planning/config.json
-2. Check model_overrides for agent-specific override
-3. If no override, look up agent in profile table
-4. Pass model parameter to Task call
+
+Every agent always gets the tier assigned by its profile. Predictable and simple.
+
+### Complexity
+
+```json
+{
+  "routing": {
+    "strategy": "complexity",
+    "complexity_thresholds": {
+      "downgrade_max": 2,
+      "upgrade_min": 6
+    }
+  }
+}
 ```
 
+Adjusts tiers up or down based on task metadata:
+
+| Factor | Score 0 | Score 1 | Score 2 | Score 3 |
+|--------|---------|---------|---------|---------|
+| fileCount | ≤5 | 6–15 | >15 | — |
+| waveCount | ≤1 | 2–3 | >3 | — |
+| requirementCount | ≤2 | 3–5 | >5 | — |
+| isArchitectural | false | — | — | true |
+
+- Score ≤ `downgrade_max` (default 2): tier steps down one level (e.g., mid → fast)
+- Score ≥ `upgrade_min` (default 6): tier steps up one level (e.g., mid → reasoning)
+- Otherwise: tier stays as assigned by profile
+
+---
+
 ## Per-Agent Overrides
 
 Override specific agents without changing the entire profile:
@@ -61,51 +151,90 @@ Override specific agents without changing the entire profile:
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
+Overrides accept tier names (`reasoning`, `mid`, `fast`) or legacy names (`opus`, `sonnet`, `haiku`). They take highest priority — above per-phase overrides, complexity routing, and profile lookup.
 
-## Switching Profiles
+---
 
-Runtime: `/pan:profile <profile>`
+## Per-Phase Overrides
+
+Override the model tier for all agents within a specific roadmap phase by adding an HTML comment to the phase section:
+
+```markdown
+## Phase 3: Quick UI polish
+**Goal:** Style cleanup
+<!-- model_tier: fast -->
+```
+
+When an orchestrator passes `phaseNum` in task metadata, the routing pipeline checks the roadmap phase for a `model_tier` comment. This lets you use a cheaper tier for simple phases without changing the global profile.
+
+Valid values: `reasoning`, `mid`, `fast`, `opus`, `sonnet`, `haiku`.
+
+---
+
+## Configuration Reference
+
+Full routing config in `.planning/config.json`:
 
-Per-project default: Set in `.planning/config.json`:
 ```json
 {
-  "model_profile": "balanced"
+  "model_profile": "balanced",
+  "model_overrides": {
+    "pan-executor": "opus"
+  },
+  "routing": {
+    "strategy": "static",
+    "provider": "auto",
+    "cascade_quality_gate": true,
+    "complexity_thresholds": {
+      "downgrade_max": 2,
+      "upgrade_min": 6
+    }
+  }
 }
 ```
 
-### Downgrade Confirmation
+| Field | Values | Default | Description |
+|-------|--------|---------|-------------|
+| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Base tier assignment for all agents |
+| `model_overrides` | `{ agent: tier }` | `{}` | Per-agent tier override |
+| `routing.strategy` | `static`, `complexity` | `static` | How tiers are adjusted at runtime |
+| `routing.provider` | `auto`, `anthropic`, `openai`, `google` | `auto` | LLM provider for tier→model mapping |
+| `routing.cascade_quality_gate` | `true`, `false` | `true` | Reserved for future cascade routing |
+| `routing.complexity_thresholds.downgrade_max` | number | `2` | Max complexity score to downgrade tier |
+| `routing.complexity_thresholds.upgrade_min` | number | `6` | Min complexity score to upgrade tier |
+
+---
+
+## Switching Profiles
 
-When switching to a **lower-tier** profile, PAN asks for confirmation:
+Runtime: `/pan:profile <profile>`
+
+### Downgrade Confirmation
 
 | Direction | Example | Behavior |
 |-----------|---------|----------|
-| Downgrade | quality → balanced | ⚠️ Confirmation required |
-| Downgrade | balanced → budget | ⚠️ Confirmation required |
-| Upgrade | budget → balanced | ✓ Proceeds silently |
-| Upgrade | balanced → quality | ✓ Proceeds silently |
-| Same | balanced → balanced | ✓ Proceeds silently |
+| Downgrade | quality → balanced | Confirmation required |
+| Downgrade | balanced → budget | Confirmation required |
+| Upgrade | budget → balanced | Proceeds silently |
+| Same | balanced → balanced | Proceeds silently |
 
 **Tier Order:** `quality` (3) > `balanced` (2) > `budget` (1)
 
-This prevents accidental quality reductions. Upgrades proceed without prompting since higher quality is always safe.
+---
 
 ## Design Rationale
 
-**Why Opus for pan-planner?**
+**Why reasoning for pan-planner?**
 Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
 
-**Why Sonnet for pan-executor?**
+**Why mid for pan-executor?**
 Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
 
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+**Why mid (not fast) for verifiers in balanced?**
+Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching.
 
-**Why Haiku for pan-document_code?**
+**Why fast for pan-document_code?**
 Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
 
-**Why Haiku for pan-reviewer in balanced?**
-Code review is pattern-matching against known conventions and security rules. Haiku handles checklist-style verification efficiently. Quality profile uses Sonnet for nuanced review when accuracy matters most.
-
-**Why `inherit` instead of passing `opus` directly?**
-Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. PAN returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.
+**Why fast for pan-reviewer in balanced?**
+Code review is pattern-matching against known conventions and security rules. Fast handles checklist-style verification efficiently.