pan-wizard 3.35.0 → 3.37.0

package/commands/pan/optimize.md

@@ -1,115 +0,0 @@
----
-name: pan:optimize
-group: Self-Improvement
-description: Manage the circular optimization loop — record a report's suggestions, undo them, view stats, list reports, manage trace sessions
-argument-hint: "apply [--report <file>] | revert <apply_id> | revert --last | list | stats | trace init|end|current|list"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
----
-
-# /pan:optimize
-
-Manage the circular optimization loop: record a report's suggestions, view stats, list reports.
-
-**Usage:**
-```
-/pan:optimize apply
-/pan:optimize apply --report <filename>
-/pan:optimize revert <apply_id>
-/pan:optimize revert --last
-/pan:optimize list
-/pan:optimize stats
-/pan:optimize trace init [--description "what you're building"]
-/pan:optimize trace end
-/pan:optimize trace current
-/pan:optimize trace list
-```
-
-**Subcommands:**
-
-### apply
-Record the suggestions from the most recent (or specified) optimization report.
-
-Recorded automatically:
-- Suggestions appended to `.planning/optimization/suggestions.md`: lessons, prompt changes and workflow changes, each naming where it belongs
-- Config notes appended to `.planning/optimization/config-suggestions.md`
-- An older report's memory actions (`memory_entry`, `memory`, `memory_append`) still write to `.planning/memory/`, a `memory_entry` only if it passes the checks of the `memory record` command. The result warns that PAN's workflows do not load that folder into agents
-
-A person makes every change the suggestions describe (never auto-applied):
-- Lessons, written into the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
-- Agent prompt changes
-- Workflow step additions
-- Structural changes to commands
-
-After applying, the report lists what was applied and what still needs review, plus the `apply_id` that undoes it. Every apply is recorded action by action in `.planning/optimization/applied.jsonl`: the path, whether the file was created or appended to, the exact text, and a hash of the file after the write. Applying the same report a second time writes nothing: each action names the apply that already wrote it.
-
-### revert
-Undo one apply exactly: delete the files it created and cut the text it appended (`revert --last` for the newest).
-
-Revert never destroys work someone did since:
-- It refuses a file whose content changed after the apply. The comparison ignores line endings, so a CRLF checkout still matches.
-- It refuses a file that a later apply also wrote. Revert that later apply first.
-- It says which files it refused, and why.
-
-A CRLF file comes back CRLF. Applies logged before apply records existed cannot be reverted. After a revert, the same report can be applied again.
-
-### list
-List all optimization reports in `.planning/optimization/reports/`, most recent first.
-
-### stats
-Show cumulative optimization statistics:
-- Total trace sessions run
-- Total events traced
-- Total errors seen (`total_errors_traced`; gaps and redundancies are not totalled)
-- Total optimizations applied across all runs, the apply runs, the reverted runs, and the last `apply_id`
-- Current active trace session (if any)
-
-### trace init
-Start a trace session before running a build — or join the active one: `trace init` reuses an unended session started within the last hour (`reused: true`, keeping that session's description) instead of opening a new one. The hook fires automatically on SubagentStop, but calling `trace init` first lets you attach a description to a new session.
-
-```
-/pan:optimize trace init --description "building express web server"
-/pan:exec-phase 1
-/pan:learn
-```
-
-### trace end
-Finalize the current trace session (writes summary stats to session.json).
-
-### trace current
-Show the active trace session ID (`optimize trace current` returns only `session_id` and `active`; `trace list` carries each session's event count).
-
-### trace list
-List all trace sessions, most recent first.
-
----
-
-**The circular loop:**
-
-```
-┌─────────────────────────────────────────────────────┐
-│                                                     │
-│  /pan:optimize trace init                           │
-│         ↓                                          │
-│  /pan:exec-phase N    ← agents run, hook traces    │
-│         ↓                                          │
-│  /pan:learn           ← analyze + report           │
-│         ↓                                          │
-│  /pan:optimize apply  ← record suggestions         │
-│         ↓                                          │
-│  You make the changes ← instructions, tests, code  │
-│         ↑                                          │
-│         └──────────────────────────────────────────┘
-└─────────────────────────────────────────────────────┘
-```
-
-Each iteration puts what the last run lacked where the next run's agents read it: fewer repeated errors and gaps.
-
-**See also:** `/pan:learn`, `/pan:exec-phase`
-
-Follow the workflow at `~/.claude/pan-wizard-core/workflows/optimize.md`. Each subcommand runs `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize <subcommand> [flags]` — e.g. `optimize apply --report <path>`, `optimize revert --last`, `optimize trace init --description "..."`.

package/commands/pan/profile.md

@@ -1,76 +0,0 @@
----
-name: pan:profile
-group: Session & Progress
-description: Switch model profile for PAN agents (quality/balanced/budget)
-argument-hint: <profile>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Switch the model profile used by PAN agents. Sets the model tier PAN's workflows pass when they spawn an agent (mapped to the detected provider's models), balancing quality vs token spend. `/pan:army` and `pan-conductor` spawn with no model, so the agents they run use their own `model:` pin, else the session model, under every profile.
-
-Routes to the profile workflow which handles:
-- Argument validation (quality/balanced/budget)
-- Downgrade confirmation (quality → balanced → budget requires 'yes')
-- Config file creation if missing
-- Profile update in config.json
-- Confirmation with model table display
-</objective>
-
-<execution_context>
-@~/.claude/pan-wizard-core/workflows/profile.md
-</execution_context>
-
-<process>
-**Follow the profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
-
-The workflow handles all logic including:
-1. Profile argument validation
-2. Config file ensuring
-3. Config reading and updating
-4. Model table generation from MODEL_PROFILES
-5. Cost estimation display (relative cost multiplier per profile)
-6. Confirmation display
-</process>
-
-<tier_decision_tree>
-**Capability-aware routing** (shipped v2.10.0 — E-7). `resolveModel` can adjust the profile's tier per call from three hints — context estimate, whether the task needs extended thinking, and whether prompt cache is warm — but only when the caller passes them (`resolve-model <agent> --metadata '{…}'`). No shipped workflow, command or agent passes them, so the tree and the quick guide below describe what a caller's hints would do.
-
-The decision order `resolveModel` applies after the baseline profile pick:
-
-```
-Baseline tier (from MODEL_PROFILES[agent][profile])
-        │
-        ▼
-┌─────────────────────────────────────────────┐
-│ context_estimate > 700K tokens?             │── yes ──▶ force reasoning (widest ctx tier)
-└─────────────────────────────────────────────┘
-        │ no
-        ▼
-┌─────────────────────────────────────────────┐
-│ needs_thinking AND tier == fast?            │── yes ──▶ upgrade fast → mid
-└─────────────────────────────────────────────┘
-        │ no
-        ▼
-┌─────────────────────────────────────────────┐
-│ cache_warm AND !needs_thinking              │── yes ──▶ downgrade mid → fast
-│ AND context_estimate < 50K AND tier == mid  │
-└─────────────────────────────────────────────┘
-        │ no
-        ▼
-Final tier → provider-native model name
-```
-
-**Quick guide:**
-- Heavy verification (plan-checker, verifier, integration-checker, reviewer, debugger): `needs_thinking: true` — baseline upgrades fast→mid.
-- Whole-repo context estimates above the large-context threshold (`context_estimate > 700K` tokens — `LARGE_CONTEXT_TOKEN_THRESHOLD`): forced to reasoning, which inherits the model you launched with. Note the direction: `/pan:map-codebase` picks `single-shot` **at or below** 700K and `sharded` above it, so the repos that trip this rule are the ones the mapper is already sharding.
-- Routine exec tasks with project.md cached: `cache_warm + small ctx` — mid gets downgraded to fast for a cost win.
-- All rules are additive to the `quality` / `balanced` / `budget` profile you pick here — profile sets the floor, capability hints adjust upward or downward within that floor's band.
-
-**Inspecting routing:** use `pan-tools resolve-model <agent> --metadata '{"context_estimate":900000,"needs_thinking":true}'` to see what tier a given hint set resolves to.
-
-**Effort dimension (2026-06):** `resolve-model` also returns an `effort` level (`low`/`medium`/`high`/`xhigh`) per agent — the within-model reasoning-depth dial on current models. Profiles modulate it: `budget` steps each agent's base effort down one level (floor `low`); `quality`/`balanced` keep the base. Per-agent override: `.planning/config.json` → `"effort_overrides": { "pan-verifier": "xhigh" }`.
-</tier_decision_tree>

package/commands/pan/research-phase.md

@@ -1,189 +0,0 @@
----
-name: pan:research-phase
-group: Phase Lifecycle
-description: Research how to implement a phase (standalone - usually use /pan:plan-phase instead)
-argument-hint: "<phase>"
-allowed-tools:
-  - Read
-  - Bash
-  - Task
----
-
-<objective>
-Research how to implement a phase. Spawns pan-phase-researcher agent with phase context.
-
-**Note:** This is a standalone research command. For most workflows, use `/pan:plan-phase` which integrates research automatically.
-
-**Use this command when:**
-- You want to research without planning yet
-- You want to re-research after planning is complete
-- You need to investigate before deciding if a phase is feasible
-
-**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
-
-**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). A fresh context window for investigation. Main context stays lean for user interaction.
-</objective>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Normalize phase input in step 1 before any directory lookups.
-</context>
-
-<process>
-
-## 0. Initialize Context
-
-```bash
-INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "$ARGUMENTS")
-```
-
-Extract from init JSON: `phase_dir`, `padded_phase`, `phase_slug`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`. `phase_dir` is null when the phase is in the roadmap but has no directory yet: create it (`mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"`) and use that path as `phase_dir`, as discuss-phase does.
-
-Resolve researcher model:
-```bash
-RESEARCHER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-phase-researcher --raw)
-```
-
-## 1. Validate Phase
-
-```bash
-PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}")
-```
-
-**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
-
-## 2. Check Existing Research
-
-Use `has_research` and `research_path` from INIT.
-
-**If exists:** Offer: 1) Update research, 2) View existing (`research_path`), 3) Skip. Wait for response.
-
-**If doesn't exist:** Continue.
-
-## 3. Gather Phase Context
-
-Write this phase's roadmap slice (its section, its dependencies' goals and its requirement lines), then use paths from INIT (do not inline file contents in orchestrator context):
-```bash
-SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${phase_number}" --write --raw)
-```
-- `slice_path` (from the command above; `requirements_path` if it is empty)
-- `context_path`
-- `state_path`
-
-Present summary with phase description and what files the researcher will load.
-
-## 4. Spawn pan-phase-researcher Agent
-
-Research mode: the prompt below names `ecosystem`; pan-phase-researcher defines no modes, so treat it as context, not a switch.
-
-```markdown
-<research_type>
-Phase Research — investigating HOW to implement a specific phase well.
-</research_type>
-
-<key_insight>
-The question is NOT "which library should I use?"
-
-The question is: "What do I not know that I don't know?"
-
-For this phase, discover:
-- What's the established architecture pattern?
-- What libraries form the standard stack?
-- What problems do people commonly hit?
-- What's SOTA vs what Claude's training thinks is SOTA?
-- What should NOT be hand-rolled?
-</key_insight>
-
-<objective>
-Research implementation approach for Phase {phase_number}: {phase_name}
-Mode: ecosystem
-</objective>
-
-<files_to_read>
-- {slice_path} (This phase's roadmap and requirements)
-- {context_path} (Phase context from discuss-phase, if exists)
-- {state_path} (Prior project decisions and blockers)
-</files_to_read>
-
-<additional_context>
-**Phase description:** {phase_description}
-</additional_context>
-
-<downstream_consumer>
-Your research.md will be loaded by `/pan:plan-phase` which uses specific sections:
-- `## Standard Stack` → Plans use these libraries
-- `## Architecture Patterns` → Task structure follows these
-- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
-- `## Common Pitfalls` → Verification steps check for these
-- `## Code Examples` → Task actions reference these patterns
-
-Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
-</downstream_consumer>
-
-<quality_gate>
-Before declaring complete, verify:
-- [ ] All domains investigated (not just some)
-- [ ] Negative claims verified with official docs
-- [ ] Multiple sources for critical claims
-- [ ] Confidence levels assigned honestly
-- [ ] Section names match what plan-phase expects
-</quality_gate>
-
-<output>
-Write to: {phase_dir}/{padded_phase}-research.md
-</output>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="pan-phase-researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
-```
-
-## 5. Handle Agent Return
-
-**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
-
-**`## RESEARCH BLOCKED`:** Show the blocker and what was attempted, offer: Provide context (then spawn a continuation, step 6), Skip research, Abort.
-
-## 6. Spawn Continuation Agent
-
-```markdown
-<objective>
-Continue research for Phase {phase_number}: {phase_name}
-</objective>
-
-<prior_state>
-<files_to_read>
-- {phase_dir}/{padded_phase}-research.md (Existing research)
-</files_to_read>
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-```
-
-```
-Task(
-  prompt=continuation_prompt,
-  subagent_type="pan-phase-researcher",
-  model="{researcher_model}",
-  description="Continue research Phase {phase}"
-)
-```
-
-</process>
-
-<success_criteria>
-- [ ] Phase validated against roadmap
-- [ ] Existing research checked
-- [ ] pan-phase-researcher spawned with context
-- [ ] Checkpoints handled correctly
-- [ ] User knows next steps
-</success_criteria>

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

@@ -1,269 +0,0 @@
-/**
- * Bridge — MCP tool discovery + per-phase recommendation (Spec B v2 Y-5, v3.3).
- *
- * Discovery-only scope. We discover what MCP tools are reachable from the
- * host runtime and what their shapes look like, then recommend which tools
- * a given phase plan might use. We do NOT auto-inject tools into plans or
- * auto-invoke them — those belong to a future wave once MCP schemas stabilize.
- *
- * Data lives at `.planning/bridge/available-tools.json`:
- *   {
- *     cached_at: "2026-04-18T...",
- *     runtime: "claude",
- *     servers: [
- *       {
- *         name: "linear",
- *         version: "1.2.3",
- *         tools: [
- *           { name: "linear.updateTicket", description: "...", schema: {...} },
- *           ...
- *         ]
- *       },
- *       ...
- *     ]
- *   }
- *
- * Nothing populates this file on its own: no hook or host writes it.
- * `bridge cache --servers <json>` (or an external script) seeds it; this module
- * reads the cache and reasons over it.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { output, error, safeReadFile, toPosix, findPhaseInternal } = require('./core.cjs');
-const { planningPath } = require('./utils.cjs');
-
-const BRIDGE_DIR = 'bridge';
-const TOOLS_FILE = 'available-tools.json';
-
-function bridgeDir(cwd) {
-  return path.join(planningPath(cwd), BRIDGE_DIR);
-}
-
-function toolsCacheFile(cwd) {
-  return path.join(bridgeDir(cwd), TOOLS_FILE);
-}
-
-/**
- * Load the cached tool list. Returns an empty catalog if the cache is
- * missing or malformed.
- *
- * @param {string} cwd - Project root
- * @returns {{cached_at: string|null, runtime: string|null, servers: Array, source: 'cache'|'empty'}}
- */
-function loadToolCache(cwd) {
-  const raw = safeReadFile(toolsCacheFile(cwd));
-  if (!raw) return { cached_at: null, runtime: null, servers: [], source: 'empty' };
-  try {
-    const parsed = JSON.parse(raw);
-    return {
-      cached_at: parsed.cached_at || null,
-      runtime: parsed.runtime || null,
-      servers: Array.isArray(parsed.servers) ? parsed.servers : [],
-      source: 'cache',
-    };
-  } catch {
-    return { cached_at: null, runtime: null, servers: [], source: 'empty' };
-  }
-}
-
-/**
- * Write the tool cache. Used by the command when the host runtime provides
- * a fresh tool list (or by tests for fixture setup).
- *
- * @param {string} cwd - Project root
- * @param {{runtime, servers}} data
- * @returns {{written: true, file: string}|{error: string}}
- */
-function writeToolCache(cwd, data) {
-  if (!data || typeof data !== 'object') return { error: 'data required' };
-  try {
-    fs.mkdirSync(bridgeDir(cwd), { recursive: true });
-  } catch (e) {
-    return { error: `Failed to create bridge dir: ${e.message}` };
-  }
-  const payload = {
-    cached_at: new Date().toISOString(),
-    runtime: data.runtime || null,
-    servers: Array.isArray(data.servers) ? data.servers : [],
-  };
-  const file = toolsCacheFile(cwd);
-  try {
-    fs.writeFileSync(file, JSON.stringify(payload, null, 2), 'utf-8');
-  } catch (e) {
-    return { error: `Failed to write ${file}: ${e.message}` };
-  }
-  return { written: true, file: toPosix(path.relative(cwd, file)) };
-}
-
-/**
- * Flatten server → tool hierarchy into a single list for easier reasoning.
- *
- * @param {Array} servers - From loadToolCache().servers
- * @returns {Array<{server, name, description, schema}>}
- */
-function flattenTools(servers) {
-  const tools = [];
-  for (const server of servers || []) {
-    if (!server || !Array.isArray(server.tools)) continue;
-    for (const tool of server.tools) {
-      if (!tool || !tool.name) continue;
-      tools.push({
-        server: server.name,
-        name: tool.name,
-        description: tool.description || '',
-        schema: tool.schema || null,
-      });
-    }
-  }
-  return tools;
-}
-
-/**
- * List all available MCP tools, flattened.
- *
- * @param {string} cwd - Project root
- * @returns {Object}
- */
-function listTools(cwd) {
-  const cache = loadToolCache(cwd);
-  const tools = flattenTools(cache.servers);
-  return {
-    cached_at: cache.cached_at,
-    runtime: cache.runtime,
-    server_count: cache.servers.length,
-    tool_count: tools.length,
-    tools,
-    source: cache.source,
-  };
-}
-
-// ─── Recommendation scoring ────────────────────────────────────────────────
-
-/**
- * Score a tool's relevance to a phase by matching plan keywords against
- * tool name + description. Naive frequency-based scoring (no embeddings).
- *
- * @param {string} phaseText - Combined plan text
- * @param {{server, name, description}} tool
- * @returns {{score: number, hits: Array<string>}}
- */
-function scoreToolForPhase(phaseText, tool) {
-  if (!phaseText || !tool) return { score: 0, hits: [] };
-  const body = phaseText.toLowerCase();
-  const haystack = `${tool.server || ''} ${tool.name || ''} ${tool.description || ''}`.toLowerCase();
-
-  // Extract keywords from the tool's identity: split on non-word chars, dedupe, keep ≥3 chars.
-  const keywords = [...new Set(haystack.split(/\W+/).filter(w => w.length >= 3))];
-
-  let score = 0;
-  const hits = [];
-  for (const kw of keywords) {
-    const re = new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
-    const count = (body.match(re) || []).length;
-    if (count > 0) {
-      score += count;
-      hits.push(kw);
-    }
-  }
-  return { score, hits };
-}
-
-/**
- * Recommend MCP tools for a specific phase based on plan text keyword match.
- *
- * @param {string} cwd - Project root
- * @param {string|number} phaseNum - Phase identifier
- * @param {Object} [opts] - {max_recommendations, min_score}
- * @returns {Object}
- */
-function recommendForPhase(cwd, phaseNum, opts) {
-  const cache = loadToolCache(cwd);
-  const tools = flattenTools(cache.servers);
-  if (tools.length === 0) {
-    return {
-      phase: String(phaseNum),
-      runtime: cache.runtime,
-      recommendations: [],
-      reason: 'no MCP tools cached — seed .planning/bridge/available-tools.json with `pan-tools bridge cache --servers <json>`; no hook or host writes it',
-    };
-  }
-
-  const phaseInfo = findPhaseInternal(cwd, phaseNum);
-  if (!phaseInfo || !phaseInfo.found) {
-    return {
-      phase: String(phaseNum),
-      error: `Phase ${phaseNum} not found in .planning/phases/`,
-    };
-  }
-
-  const phaseDir = path.join(cwd, phaseInfo.directory);
-  const planTexts = (phaseInfo.plans || [])
-    .map(f => safeReadFile(path.join(phaseDir, f)) || '')
-    .join('\n');
-
-  const max = Math.max(1, Math.min(50, Number(opts?.max_recommendations) || 10));
-  const minScore = Math.max(0, Number(opts?.min_score) || 1);
-
-  const scored = tools
-    .map(tool => ({
-      ...tool,
-      ...scoreToolForPhase(planTexts, tool),
-    }))
-    .filter(t => t.score >= minScore)
-    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
-    .slice(0, max);
-
-  return {
-    phase: String(phaseNum),
-    phase_name: phaseInfo.phase_name || null,
-    runtime: cache.runtime,
-    total_candidates: tools.length,
-    recommendations: scored.map(t => ({
-      server: t.server,
-      name: t.name,
-      description: t.description,
-      score: t.score,
-      hits: t.hits,
-    })),
-  };
-}
-
-// ─── CLI wrappers ───────────────────────────────────────────────────────────
-
-function cmdBridgeList(cwd, raw) {
-  output(listTools(cwd), raw);
-}
-
-function cmdBridgeRecommend(cwd, phaseNum, opts, raw) {
-  if (!phaseNum) error('Usage: bridge recommend <phase> [--max N] [--min-score N]');
-  output(recommendForPhase(cwd, phaseNum, opts), raw);
-}
-
-function cmdBridgeCache(cwd, serversJson, runtime, raw) {
-  // The cache's only writer: no hook or host runtime populates the file, so this
-  // CLI path (or an external script) is how users seed it.
-  if (!serversJson) {
-    // No payload — just echo the current cache path/state.
-    output(listTools(cwd), raw);
-    return;
-  }
-  let servers;
-  try { servers = JSON.parse(serversJson); }
-  catch (e) { error(`Invalid --servers JSON: ${e.message}`); }
-  output(writeToolCache(cwd, { runtime, servers }), raw);
-}
-
-module.exports = {
-  loadToolCache,
-  writeToolCache,
-  flattenTools,
-  listTools,
-  scoreToolForPhase,
-  recommendForPhase,
-  cmdBridgeList,
-  cmdBridgeRecommend,
-  cmdBridgeCache,
-  BRIDGE_DIR,
-  TOOLS_FILE,
-};