pan-wizard 3.36.0 → 3.37.0

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,
-};

package/pan-wizard-core/templates/research-project/architecture.md

@@ -1,210 +0,0 @@
-# Architecture Research Template
-
-Template for `.planning/research/architecture.md` — system structure patterns for the project domain.
-
-<template>
-
-~~~markdown
-# Architecture Research
-
-**Domain:** [domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Standard Architecture
-
-### System Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        [Layer Name]                          │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
-│  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │        │
-│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
-│       │            │            │            │              │
-├───────┴────────────┴────────────┴────────────┴──────────────┤
-│                        [Layer Name]                          │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │                    [Component]                       │    │
-│  └─────────────────────────────────────────────────────┘    │
-├─────────────────────────────────────────────────────────────┤
-│                        [Layer Name]                          │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
-│  │ [Store]  │  │ [Store]  │  │ [Store]  │                   │
-│  └──────────┘  └──────────┘  └──────────┘                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Component Responsibilities
-
-| Component | Responsibility | Typical Implementation |
-|-----------|----------------|------------------------|
-| [name] | [what it owns] | [how it's usually built] |
-| [name] | [what it owns] | [how it's usually built] |
-| [name] | [what it owns] | [how it's usually built] |
-
-## Recommended Project Structure
-
-```
-src/
-├── [folder]/           # [purpose]
-│   ├── [subfolder]/    # [purpose]
-│   └── [file].ts       # [purpose]
-├── [folder]/           # [purpose]
-│   ├── [subfolder]/    # [purpose]
-│   └── [file].ts       # [purpose]
-├── [folder]/           # [purpose]
-└── [folder]/           # [purpose]
-```
-
-### Structure Rationale
-
-- **[folder]/:** [why organized this way]
-- **[folder]/:** [why organized this way]
-
-## Architectural Patterns
-
-### Pattern 1: [Pattern Name]
-
-**What:** [description]
-**When to use:** [conditions]
-**Trade-offs:** [pros and cons]
-
-**Example:**
-```typescript
-// [Brief code example showing the pattern]
-```
-
-### Pattern 2: [Pattern Name]
-
-**What:** [description]
-**When to use:** [conditions]
-**Trade-offs:** [pros and cons]
-
-**Example:**
-```typescript
-// [Brief code example showing the pattern]
-```
-
-### Pattern 3: [Pattern Name]
-
-**What:** [description]
-**When to use:** [conditions]
-**Trade-offs:** [pros and cons]
-
-## Data Flow
-
-### Request Flow
-
-```
-[User Action]
-    ↓
-[Component] → [Handler] → [Service] → [Data Store]
-    ↓              ↓           ↓            ↓
-[Response] ← [Transform] ← [Query] ← [Database]
-```
-
-### State Management
-
-```
-[State Store]
-    ↓ (subscribe)
-[Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]
-```
-
-### Key Data Flows
-
-1. **[Flow name]:** [description of how data moves]
-2. **[Flow name]:** [description of how data moves]
-
-## Scaling Considerations
-
-| Scale | Architecture Adjustments |
-|-------|--------------------------|
-| 0-1k users | [approach — usually monolith is fine] |
-| 1k-100k users | [approach — what to optimize first] |
-| 100k+ users | [approach — when to consider splitting] |
-
-### Scaling Priorities
-
-1. **First bottleneck:** [what breaks first, how to fix]
-2. **Second bottleneck:** [what breaks next, how to fix]
-
-## Anti-Patterns
-
-### Anti-Pattern 1: [Name]
-
-**What people do:** [the mistake]
-**Why it's wrong:** [the problem it causes]
-**Do this instead:** [the correct approach]
-
-### Anti-Pattern 2: [Name]
-
-**What people do:** [the mistake]
-**Why it's wrong:** [the problem it causes]
-**Do this instead:** [the correct approach]
-
-## Integration Points
-
-### External Services
-
-| Service | Integration Pattern | Notes |
-|---------|---------------------|-------|
-| [service] | [how to connect] | [gotchas] |
-| [service] | [how to connect] | [gotchas] |
-
-### Internal Boundaries
-
-| Boundary | Communication | Notes |
-|----------|---------------|-------|
-| [module A ↔ module B] | [API/events/direct] | [considerations] |
-
-## Claims
-
-| Claim | Type | Source | Checked |
-|-------|------|--------|---------|
-| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
-
-## Sources
-
-- [Architecture references]
-- [Official documentation]
-- [Case studies]
-
----
-*Architecture research for: [domain]*
-*Researched: [date]*
-~~~
-
-</template>
-
-<guidelines>
-
-**System Overview:**
-- Use ASCII box-drawing diagrams for clarity (├── └── │ ─ for structure visualization only)
-- Show major components and their relationships
-- Don't over-detail — this is conceptual, not implementation
-
-**Project Structure:**
-- Be specific about folder organization
-- Explain the rationale for grouping
-- Match conventions of the chosen stack
-
-**Patterns:**
-- Include code examples where helpful
-- Explain trade-offs honestly
-- Note when patterns are overkill for small projects
-
-**Scaling Considerations:**
-- Be realistic — most projects don't need to scale to millions
-- Focus on "what breaks first" not theoretical limits
-- Avoid premature optimization recommendations
-
-**Anti-Patterns:**
-- Specific to this domain
-- Include what to do instead
-- Helps prevent common mistakes during implementation
-
-</guidelines>

package/pan-wizard-core/templates/research-project/features.md

@@ -1,153 +0,0 @@
-# Features Research Template
-
-Template for `.planning/research/features.md` — feature landscape for the project domain.
-
-<template>
-
-```markdown
-# Feature Research
-
-**Domain:** [domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Feature Landscape
-
-### Table Stakes (Users Expect These)
-
-Features users assume exist. Missing these = product feels incomplete.
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|------------|-------|
-| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
-
-### Differentiators (Competitive Advantage)
-
-Features that set the product apart. Not required, but valuable.
-
-| Feature | Value Proposition | Complexity | Notes |
-|---------|-------------------|------------|-------|
-| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
-
-### Anti-Features (Commonly Requested, Often Problematic)
-
-Features that seem good but create problems.
-
-| Feature | Why Requested | Why Problematic | Alternative |
-|---------|---------------|-----------------|-------------|
-| [feature] | [surface appeal] | [actual problems] | [better approach] |
-| [feature] | [surface appeal] | [actual problems] | [better approach] |
-
-## Feature Dependencies
-
-```
-[Feature A]
-    └──requires──> [Feature B]
-                       └──requires──> [Feature C]
-
-[Feature D] ──enhances──> [Feature A]
-
-[Feature E] ──conflicts──> [Feature F]
-```
-
-### Dependency Notes
-
-- **[Feature A] requires [Feature B]:** [why the dependency exists]
-- **[Feature D] enhances [Feature A]:** [how they work together]
-- **[Feature E] conflicts with [Feature F]:** [why they're incompatible]
-
-## MVP Definition
-
-### Launch With (v1)
-
-Minimum viable product — what's needed to validate the concept.
-
-- [ ] [Feature] — [why essential]
-- [ ] [Feature] — [why essential]
-- [ ] [Feature] — [why essential]
-
-### Add After Validation (v1.x)
-
-Features to add once core is working.
-
-- [ ] [Feature] — [trigger for adding]
-- [ ] [Feature] — [trigger for adding]
-
-### Future Consideration (v2+)
-
-Features to defer until product-market fit is established.
-
-- [ ] [Feature] — [why defer]
-- [ ] [Feature] — [why defer]
-
-## Feature Prioritization Matrix
-
-| Feature | User Value | Implementation Cost | Priority |
-|---------|------------|---------------------|----------|
-| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
-| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
-| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
-
-**Priority key:**
-- P1: Must have for launch
-- P2: Should have, add when possible
-- P3: Nice to have, future consideration
-
-## Competitor Feature Analysis
-
-| Feature | Competitor A | Competitor B | Our Approach |
-|---------|--------------|--------------|--------------|
-| [feature] | [how they do it] | [how they do it] | [our plan] |
-| [feature] | [how they do it] | [how they do it] | [our plan] |
-
-## Claims
-
-| Claim | Type | Source | Checked |
-|-------|------|--------|---------|
-| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
-
-## Sources
-
-- [Competitor products analyzed]
-- [User research or feedback sources]
-- [Industry standards referenced]
-
----
-*Feature research for: [domain]*
-*Researched: [date]*
-```
-
-</template>
-
-<guidelines>
-
-**Table Stakes:**
-- These are non-negotiable for launch
-- Users don't give credit for having them, but penalize for missing them
-- Example: A community platform without user profiles is broken
-
-**Differentiators:**
-- These are where you compete
-- Should align with the Core Value from project.md
-- Don't try to differentiate on everything
-
-**Anti-Features:**
-- Prevent scope creep by documenting what seems good but isn't
-- Include the alternative approach
-- Example: "Real-time everything" often creates complexity without value
-
-**Feature Dependencies:**
-- Critical for roadmap phase ordering
-- If A requires B, B must be in an earlier phase
-- Conflicts inform what NOT to combine in same phase
-
-**MVP Definition:**
-- Be ruthless about what's truly minimum
-- "Nice to have" is not MVP
-- Launch with less, validate, then expand
-
-</guidelines>