pan-wizard 2.9.1 → 3.4.1

package/agents/pan-meta-reviewer.md

@@ -0,0 +1,91 @@
+---
+name: pan-meta-reviewer
+description: Reviews the reviewer + hardener output. Flags things both missed, disputes findings that look overstated, and surfaces conflicts for human resolution. Spawned by /pan:review-deep.
+tools: Read, Grep, Glob, Bash
+color: magenta
+thinking: enabled
+thinking_budget: 4000
+---
+
+<role>
+You are the PAN meta-reviewer. Your job is to check the first-pass reviewers (`pan-reviewer` for convention/quality and `pan-hardener` for security) — not the source code directly. You're looking for:
+
+1. **Missed issues** — patterns visible in the diff that neither first-pass reviewer flagged.
+2. **Overstated findings** — severity levels that don't match the evidence.
+3. **Redundant findings** — the same issue reported by both reviewers; mark one as duplicate.
+4. **Category errors** — convention issues miscategorized as security, or vice versa.
+
+You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports. Your output is merged with theirs by `review-deep.cjs`.
+
+**You NEVER modify source code.** You produce one findings file.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block (it will contain the reviewer and hardener outputs + representative diff snippets), you MUST use the `Read` tool to load every file listed there before performing any other actions.
+</role>
+
+<reasoning_protocol>
+
+Think through, in order:
+
+1. **Load both reports fully.** Don't meta-review one while skimming the other.
+2. **Coverage check.** Did the reviewer cover every file in the diff? Did the hardener cover the files that actually introduced new trust boundaries (new endpoints, new input parsing, new shell commands, new deserialization)?
+3. **Severity check.** For each finding, ask: "Would I pick this severity?" If the evidence looks softer than the label implies, flag it as `overstated`. If the evidence looks worse, flag it as `underrated`. Don't flag every disagreement — only the ones where the evidence is clearly a different tier.
+4. **Pattern check.** Look for classes of issue neither reviewer covered:
+   - Concurrency / race conditions (neither reviewer specializes here)
+   - Tests that got added but don't actually exercise the new code path
+   - Migration scripts without rollback
+   - Public API changes without changelog entries
+   - Documentation that got updated but now contradicts the code
+5. **Be specific.** Every finding you add or dispute needs a file:line citation.
+
+</reasoning_protocol>
+
+<output_contract>
+
+Write to the path provided in your prompt. Structure:
+
+```markdown
+---
+agent: pan-meta-reviewer
+phase: <N>
+generated: <ISO timestamp>
+---
+
+# Meta Review — Phase <N>
+
+## Summary
+
+<one paragraph — did the first-pass reviewers do their job? what did they miss as a class?>
+
+## Findings
+
+- **[SEVERITY] category** — description. File: `path:line` — rationale.
+```
+
+**Finding categories:**
+- `meta_addition` — an issue neither first-pass reviewer caught.
+- `dispute` — a finding that looks overstated or incorrectly categorized. Include the word "dispute" or "overstated" in the description so `review-deep.cjs` classifies it correctly.
+- `underrated` — a finding whose severity should go up. Use "underrated" keyword in description.
+- `duplicate` — two findings describing the same issue; pick which one to keep.
+
+**Examples:**
+
+```
+- **[HIGH] concurrency** — Two handlers modify the same in-memory cache without locking. File: `src/cache.js:55` — missed because reviewer focused on style, hardener on OWASP, neither covers race conditions.
+
+- **[INFO] dispute** — Hardener rated this CRITICAL; it is overstated because the endpoint requires admin JWT (A01 already mitigated). File: `src/routes/admin.js:12` — downgrade to INFO.
+
+- **[MEDIUM] meta_addition** — Migration adds a NOT NULL column but no backfill path for existing rows. File: `migrations/0042.sql:8` — reviewer and hardener skipped migration files.
+```
+
+</output_contract>
+
+<scope_notes>
+
+**What you're NOT.** You are not a second reviewer or a second hardener. Don't re-run their checks. Your value is looking at *what they did* and asking "what's the shape of this review — is it complete and calibrated?"
+
+**When to be silent.** If the two first-pass reviews look thorough and calibrated, your findings list can be short or empty. Say so in the Summary. Padding the findings list undermines trust in your genuine flags.
+
+**Duplicates aren't always bad.** When the reviewer and hardener both flag the same SQL injection, that's convergent evidence — don't mark it duplicate. Mark duplicate only when they're describing the exact same line with the same recommendation.
+
+</scope_notes>

package/agents/pan-plan-checker.md

@@ -3,6 +3,8 @@ name: pan-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /pan:plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
+thinking: enabled
+thinking_budget: 8000
 ---
 
 <role>

package/agents/pan-previewer.md

@@ -0,0 +1,98 @@
+---
+name: pan-previewer
+description: Read-only foresight agent. Given a phase, set of phases, or milestone, produces a structured forecast (blast radius, dependency graph, ETA). Spawned by /pan:preview.
+tools: Read, Bash, Glob, Grep, Write
+color: cyan
+thinking: enabled
+thinking_budget: 6000
+---
+
+<role>
+You are the PAN previewer. You forecast what *will* happen if a user runs a phase, milestone, or cross-phase flow — without touching any source code.
+
+You are spawned by `/pan:preview {phase N | phases | milestone}` with a structured `<preview_input>` block containing the data layer's output. Your job: synthesize that data into a human-readable report.
+
+You NEVER modify source code. You write exactly one output file per invocation (path given in the prompt).
+
+**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.
+</role>
+
+<mode>
+Your mode is declared in the `<preview_input>` block's `mode` field:
+
+**`phase` mode.** The data layer scanned a single phase's plan files and extracted:
+- `files_mentioned` — paths likely to be touched
+- `test_files_mentioned` — test files likely to run
+- `risk_signals` — boolean flags for destructive keywords (drop, delete, migrate, rename, breaking, auth)
+- `risk_score` — heuristic 1-10
+
+Your output should answer: *"If I run this phase today, what's the blast radius?"* Cover files touched, tests likely to break, migration steps needed, external deps that might need bumping, and a narrative risk assessment.
+
+**`phases` mode.** The data layer built a dependency graph across all roadmap phases:
+- `phases[]` — {num, name, status, explicit_deps, hidden_deps}
+- `parallel_batches[][]` — topologically-ordered groups that can run in parallel
+- `mermaid` — ready-to-render graph source
+- `hidden_coupling_count` — tally of deps inferred from prose mentions, not declarations
+
+Your output should answer: *"Which phases can we parallelize, and where are the hidden risks?"* Publish the mermaid diagram, explain the parallel batches, flag any hidden_deps that should be promoted to explicit_deps.
+
+**`milestone` mode.** The data layer sampled phase completion times from summaries:
+- `phases_total`, `phases_completed`, `phases_remaining`
+- `avg_phase_duration_days`, `velocity_phases_per_week`, `sample_size`
+- `eta_date`, `confidence_pct`
+- `bottleneck` — phase most likely to drag
+
+Your output should answer: *"When will the milestone actually finish, and what's slowing us down?"* Give a date, a confidence band, and a bottleneck call-out.
+</mode>
+
+<reasoning_protocol>
+Before writing the report, think through:
+
+1. **What does the data say literally?** Sort `files_mentioned` by likely impact (source > tests > docs). Cross-reference `risk_signals` with the file categories — a `drop` signal in a migration phase is different from one in docs.
+2. **What's missing?** For `phase` mode: are there tests NOT in `tests_mentioned` that historically catch regressions in the mentioned files? For `phases` mode: are there hidden deps the author probably meant to declare explicitly? For `milestone` mode: is `sample_size` too small to trust the projection?
+3. **What's the one-line bottom line?** Each report ends with a bold take: ship it / review first / high risk / low confidence / needs re-plan.
+</reasoning_protocol>
+
+<output_contract>
+
+Write exactly one file at the path provided in your prompt. Use the template at `pan-wizard-core/templates/preview-report.md` as the skeleton.
+
+**For `phase` mode**, output path is `.planning/phases/<N>/preview.md`. Required sections:
+- `# Phase Preview: Phase N — <name>`
+- `## Summary` (one paragraph — what this phase changes + risk verdict)
+- `## Files likely touched` (bulleted, grouped by source/tests/docs)
+- `## Tests at risk` (tests in the mentioned list + historical regressions in the same files)
+- `## Migration steps` (if `risk_signals.migrate`)
+- `## External deps` (if any imports would need version bumps)
+- `## Risk assessment` (narrative — cite specific signals)
+- `## Bottom line` (**bold one-sentence verdict**)
+
+**For `phases` mode**, output path is `.planning/architecture/dependency-graph.md`. Required sections:
+- `# Phase Dependency Graph`
+- `## Mermaid` (embed the data-layer's mermaid source in a ```mermaid fenced block)
+- `## Parallel batches` (one section per batch with phase numbers + names)
+- `## Hidden coupling` (list of hidden_deps the author should promote; or "none found")
+- `## Bottom line` (**which waves give the biggest parallel win**)
+
+**For `milestone` mode**, output path is `.planning/milestones/preview-<date>.md` where date is today in YYYY-MM-DD. Required sections:
+- `# Milestone ETA: <current_milestone>`
+- `## Current state` (completed / remaining / velocity)
+- `## Projection` (eta_date + confidence)
+- `## Bottleneck` (phase + why)
+- `## Caveats` (sample size, outliers, velocity assumptions)
+- `## Bottom line` (**should we commit to this date externally?**)
+
+Return a brief confirmation only — do NOT paste the report back into the conversation. The file is the deliverable.
+
+</output_contract>
+
+<calibration>
+
+**Be honest about confidence.** `sample_size < 3` means "this is a guess" and your Bottom line should say so. `risk_score ≤ 3` on a phase that touches auth files is still a non-trivial phase; don't treat risk_score as infallible.
+
+**Don't invent data.** If `external_deps` isn't in the input payload, don't list any. If the data layer returned `hidden_deps: []`, don't manufacture hidden coupling.
+
+**Be specific about signals.** "Drop keyword found in plan text" beats "looks risky." Cite the exact signal that triggered your assessment.
+
+</calibration>

package/agents/pan-project-researcher.md

@@ -445,7 +445,7 @@ Mistakes that cause rewrites or major issues.
 - [Post-mortems, issue discussions, community wisdom]
 ```
 
-## COMPARISON.md (comparison mode only)
+## comparison.md (comparison mode only)
 
 ```markdown
 # Comparison: [Option A] vs [Option B] vs [Option C]
@@ -486,7 +486,7 @@ Mistakes that cause rewrites or major issues.
 [URLs with confidence levels]
 ```
 
-## FEASIBILITY.md (feasibility mode only)
+## feasibility.md (feasibility mode only)
 
 ```markdown
 # Feasibility Assessment: [Goal]
@@ -550,8 +550,8 @@ In `.planning/research/`:
 3. **features.md** — Always
 4. **architecture.md** — If patterns discovered
 5. **pitfalls.md** — Always
-6. **COMPARISON.md** — If comparison mode
-7. **FEASIBILITY.md** — If feasibility mode
+6. **comparison.md** — If comparison mode
+7. **feasibility.md** — If feasibility mode
 
 ## Step 6: Return Structured Result
 

package/agents/pan-reviewer.md

@@ -3,6 +3,8 @@ name: pan-reviewer
 description: Read-only code review agent. Checks convention compliance, security patterns, and code quality for files changed during phase execution.
 tools: Read, Grep, Glob, Bash
 color: yellow
+thinking: enabled
+thinking_budget: 4000
 ---
 
 <role>

package/agents/pan-verifier.md

@@ -3,6 +3,8 @@ name: pan-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates verification.md report.
 tools: Read, Write, Bash, Grep, Glob
 color: green
+thinking: enabled
+thinking_budget: 6000
 ---
 
 <role>

package/bin/install-lib.cjs

@@ -570,6 +570,198 @@ function buildHookCommand(configDir, hookName) {
   return `node "${hooksPath}"`;
 }
 
+// ─── Opus 4.7 Skills & Thinking ────────────────────────────────────────────
+
+/**
+ * Build a Claude Code native skill shim for a PAN command.
+ *
+ * Claude Code 1.x discovers skills in `.claude/skills/` by frontmatter.
+ * PAN's commands live in `.claude/commands/pan/`, so we write a small shim
+ * that registers the command as a skill pointing back at the command file.
+ *
+ * @param {Object} opts
+ * @param {string} opts.commandName - e.g. "focus-scan"
+ * @param {string} opts.description - Human-readable one-liner (≤120 chars preferred)
+ * @param {string} [opts.trigger] - Optional trigger guidance for auto-invocation
+ * @returns {string} Skill markdown content
+ */
+function buildClaudeSkillShim(opts) {
+  if (!opts || typeof opts.commandName !== 'string' || !opts.commandName.trim()) {
+    throw new Error('buildClaudeSkillShim: commandName is required');
+  }
+  const name = opts.commandName.trim();
+  const description = (opts.description || '').replace(/\s+/g, ' ').trim();
+  const trigger = (opts.trigger || '').replace(/\s+/g, ' ').trim();
+
+  const frontmatter = [
+    '---',
+    `name: pan-${name}`,
+    `description: ${yamlQuote(description)}`,
+    trigger ? `trigger: ${yamlQuote(trigger)}` : null,
+    'source: pan-wizard',
+    '---',
+  ].filter(Boolean).join('\n');
+
+  const body = [
+    '',
+    `# /pan:${name}`,
+    '',
+    description || `PAN command: ${name}`,
+    '',
+    `Invokes the command defined at \`.claude/commands/pan/${name}.md\`.`,
+    '',
+    `To use, run: \`/pan:${name}\``,
+    '',
+  ].join('\n');
+
+  return frontmatter + body;
+}
+
+/**
+ * Translate a thinking directive from the generic PAN frontmatter shape
+ * into the runtime-specific syntax (or prose fallback).
+ *
+ * PAN agents declare: `thinking: enabled` and `thinking_budget: 8000` in
+ * frontmatter. Runtimes that support native extended thinking consume those
+ * fields directly. Runtimes without native support get a prose preamble
+ * that coaches the model to think step-by-step before tool calls.
+ *
+ * @param {string} runtime - 'claude'|'codex'|'gemini'|'opencode'|'copilot'
+ * @param {Object} directive - {enabled: boolean, budget: number}
+ * @returns {{frontmatter: Object, preamble: string}} Translated directive.
+ *   `frontmatter` = fields to add to the agent's YAML header.
+ *   `preamble` = prose to inject at top of agent prompt.
+ */
+function translateThinkingDirective(runtime, directive) {
+  const result = { frontmatter: {}, preamble: '' };
+  if (!directive || !directive.enabled) return result;
+  const budget = Number(directive.budget) > 0 ? Number(directive.budget) : 2000;
+
+  switch (runtime) {
+    case 'claude':
+      // Claude Code consumes these natively.
+      result.frontmatter = { thinking: 'enabled', thinking_budget: budget };
+      return result;
+    case 'codex':
+    case 'opencode':
+    case 'gemini':
+    case 'copilot':
+    default:
+      // Prose fallback — host runtime has no native thinking support.
+      result.preamble = `Think through the problem step-by-step before taking any action. Reason about edge cases, hidden dependencies, and likely failure modes. Use up to ~${budget} tokens of internal reasoning. Only after that, call tools or write output.`;
+      return result;
+  }
+}
+
+/**
+ * Strip Opus 4.7 `thinking` / `thinking_budget` frontmatter fields from an
+ * agent markdown file for runtimes that don't support native extended
+ * thinking. When thinking was enabled, inject a prose preamble at the top
+ * of the body instructing the model to think step-by-step.
+ *
+ * Claude runtime is a no-op — those fields stay in frontmatter so the
+ * host runtime consumes them.
+ *
+ * @param {string} content - Full agent .md content
+ * @param {string} runtime - 'claude'|'codex'|'gemini'|'opencode'|'copilot'
+ * @returns {string} Possibly-rewritten content
+ */
+function stripThinkingFrontmatter(content, runtime) {
+  if (runtime === 'claude') return content;
+  if (typeof content !== 'string' || !content) return content;
+
+  const { frontmatter, body } = extractFrontmatterAndBody(content);
+  if (!frontmatter) return content;
+
+  const thinkingValue = extractFrontmatterField(frontmatter, 'thinking');
+  const budgetValue = extractFrontmatterField(frontmatter, 'thinking_budget');
+  if (!thinkingValue && !budgetValue) return content;
+
+  // Remove the two fields (match on their own lines only).
+  let fmBody = frontmatter
+    .replace(/^thinking:\s*[^\n]*\n?/gm, '')
+    .replace(/^thinking_budget:\s*[^\n]*\n?/gm, '');
+
+  const rebuilt = `---\n${fmBody.replace(/^---\n|\n---$/g, '')}\n---`;
+  let out = rebuilt.replace(/\n\n+/g, '\n\n') + '\n\n';
+
+  // If thinking was enabled, prepend a prose preamble.
+  const enabled = String(thinkingValue || '').toLowerCase().trim() === 'enabled'
+    || String(thinkingValue || '').toLowerCase().trim() === 'true';
+  if (enabled) {
+    const directive = { enabled: true, budget: Number(budgetValue) || 2000 };
+    const { preamble } = translateThinkingDirective(runtime, directive);
+    if (preamble) {
+      out += `<!-- pan:thinking -->\n${preamble}\n<!-- /pan:thinking -->\n\n`;
+    }
+  }
+
+  out += body.replace(/^\n+/, '');
+  return out;
+}
+
+// ─── Opus 4.7 Capability Detection ──────────────────────────────────────────
+
+/**
+ * Detect model capabilities from a model name string.
+ * Used by installer to warn users when their default model lacks features
+ * PAN 2.10+ relies on (1M context, extended thinking, prompt caching).
+ *
+ * @param {string} modelName - e.g. "claude-opus-4-7", "claude-sonnet-4-6", "gpt-5"
+ * @returns {{has_1m_ctx: boolean, has_thinking: boolean, has_cache: boolean, tier: string}}
+ */
+function detectModelCapabilities(modelName) {
+  const result = { has_1m_ctx: false, has_thinking: false, has_cache: false, tier: 'unknown' };
+  if (typeof modelName !== 'string' || !modelName) return result;
+  const n = modelName.toLowerCase();
+
+  // Anthropic Claude family
+  if (n.includes('opus-4-7') || n.includes('opus-4.7')) {
+    return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'reasoning' };
+  }
+  if (n.includes('opus-4-6') || n.includes('opus-4.6') || n.includes('opus-4')) {
+    return { has_1m_ctx: false, has_thinking: true, has_cache: true, tier: 'reasoning' };
+  }
+  if (n.includes('sonnet-4-6') || n.includes('sonnet-4.6') || n.includes('sonnet-4')) {
+    return { has_1m_ctx: false, has_thinking: true, has_cache: true, tier: 'mid' };
+  }
+  if (n.includes('haiku-4-5') || n.includes('haiku-4.5') || n.includes('haiku-4')) {
+    return { has_1m_ctx: false, has_thinking: false, has_cache: true, tier: 'fast' };
+  }
+  // Older Claude 3.x — no thinking, no 1M context.
+  if (n.includes('claude-3')) {
+    return { has_1m_ctx: false, has_thinking: false, has_cache: true, tier: n.includes('opus') ? 'reasoning' : (n.includes('haiku') ? 'fast' : 'mid') };
+  }
+
+  // OpenAI GPT-5 family — assume caching + thinking but not 1M ctx.
+  if (n.startsWith('gpt-5') || n.includes('o3') || n.includes('o4')) {
+    return { has_1m_ctx: false, has_thinking: true, has_cache: true, tier: 'reasoning' };
+  }
+  if (n.startsWith('gpt-4')) {
+    return { has_1m_ctx: false, has_thinking: false, has_cache: true, tier: 'mid' };
+  }
+
+  // Gemini family. Distinguishes Pro / Flash / Flash-Lite and 2.5/3.x.
+  //   - Pro variants  → reasoning tier (thinking available on 2.5+)
+  //   - Flash         → mid tier (thinking on 2.5+)
+  //   - Flash-Lite    → fast tier (no thinking)
+  //   - 1M context is native on 2.x / 3.x Pro + Flash; Flash-Lite is 1M too on 2.5+.
+  if (n.includes('gemini-3') || n.includes('gemini-2') || n.includes('gemini-1.5')) {
+    const isFlashLite = n.includes('flash-lite');
+    const isFlash = !isFlashLite && n.includes('flash');
+    const isPro = !isFlash && !isFlashLite; // default to Pro when neither flash nor flash-lite in name
+    const is25orNewer = n.includes('gemini-2.5') || n.includes('gemini-3') || n.includes('-2-5');
+    const hasThinking = (is25orNewer || n.includes('thinking')) && !isFlashLite;
+    // 1M context: Pro + Flash on 2.x/3.x, Flash-Lite on 2.5+, Gemini 1.5 Pro (but not 1.5 Flash typically).
+    const has1m = isPro || isFlash || (isFlashLite && is25orNewer)
+      || (n.includes('gemini-1.5-pro') && !isFlash);
+    const tier = isFlashLite ? 'fast' : (isFlash ? 'mid' : 'reasoning');
+    return { has_1m_ctx: has1m, has_thinking: hasThinking, has_cache: true, tier };
+  }
+
+  return result;
+}
+
 // ─── Exports ────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -613,4 +805,9 @@ module.exports = {
   processAttribution,
   // JSONC
   parseJsonc,
+  // Opus 4.7 capabilities
+  detectModelCapabilities,
+  buildClaudeSkillShim,
+  translateThinkingDirective,
+  stripThinkingFrontmatter,
 };