pan-wizard 2.9.0 → 3.4.1

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

@@ -0,0 +1,251 @@
+/**
+ * Bus — file-backed message channels for agent-to-agent communication
+ *
+ * Part of Spec B v2 Y-7 infrastructure (v3.0). Enables future hierarchical
+ * agent spawning (exec-phase --hierarchical, Wave 5) and inter-agent
+ * coordination (review-deep, Wave 3) without committing to an in-process
+ * IPC mechanism.
+ *
+ * Storage model:
+ *   .planning/bus/<channel>.jsonl — append-only JSON Lines
+ *   Each line: {ts, source, payload}
+ *
+ * Channels are created on first publish. Readers use cursor-based drain
+ * (read N lines from an offset) or consume-all drain (read + truncate).
+ *
+ * Concurrent-write safety: each publish opens the file with append flag
+ * (`a`) which the OS treats atomically for writes <PIPE_BUF on POSIX and
+ * sub-buffer writes on Windows. Entries are single lines. For parallel
+ * publishers writing large payloads, see the safety note below.
+ *
+ * Agent-name / channel-name validation: restricted to
+ * `^[a-zA-Z0-9_-]+$` to block path traversal.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const BUS_DIR = 'bus';
+const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+const DEFAULT_DRAIN_LIMIT = 1000;
+
+function busDir(cwd) {
+  return path.join(planningPath(cwd), BUS_DIR);
+}
+
+function channelFile(cwd, channel) {
+  return path.join(busDir(cwd), `${channel}.jsonl`);
+}
+
+function validateName(name, label) {
+  if (typeof name !== 'string' || !NAME_RE.test(name)) {
+    return `Invalid ${label}: ${name}. Must match ${NAME_RE}`;
+  }
+  return null;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Publish a message to a channel. Creates channel file + dir if missing.
+ *
+ * @param {string} cwd - Project root
+ * @param {string} channel - Channel name (validated)
+ * @param {*} payload - JSON-serializable payload
+ * @param {Object} [opts] - {source: string} — who sent it (agent name, command name)
+ * @returns {{published: true, ts: string, file: string, size: number}|{error: string}}
+ */
+function publish(cwd, channel, payload, opts) {
+  const chErr = validateName(channel, 'channel');
+  if (chErr) return { error: chErr };
+  const source = opts?.source;
+  // Treat null + undefined + empty string as "no source provided".
+  if (source !== undefined && source !== null && source !== '') {
+    const sErr = validateName(source, 'source');
+    if (sErr) return { error: sErr };
+  }
+
+  const normalizedSource = (source !== undefined && source !== null && source !== '') ? source : null;
+  let line;
+  try {
+    line = JSON.stringify({ ts: nowIso(), source: normalizedSource, payload }) + '\n';
+  } catch (e) {
+    return { error: `payload not JSON-serializable: ${e.message}` };
+  }
+
+  try {
+    fs.mkdirSync(busDir(cwd), { recursive: true });
+  } catch (e) {
+    return { error: `Failed to create bus dir: ${e.message}` };
+  }
+
+  const file = channelFile(cwd, channel);
+  try {
+    fs.appendFileSync(file, line, { encoding: 'utf-8' });
+  } catch (e) {
+    return { error: `Failed to append to channel ${channel}: ${e.message}` };
+  }
+
+  let size = 0;
+  try { size = fs.statSync(file).size; } catch { /* race — ignore */ }
+
+  return { published: true, ts: JSON.parse(line).ts, file, size };
+}
+
+/**
+ * Parse a channel file into an array of entries.
+ * @param {string} cwd - Project root
+ * @param {string} channel - Channel name
+ * @param {Object} [opts] - {offset: number, limit: number}
+ * @returns {{entries: Array, total: number, offset: number, more: boolean}|{error: string}}
+ */
+function readChannel(cwd, channel, opts) {
+  const chErr = validateName(channel, 'channel');
+  if (chErr) return { error: chErr };
+  const offset = Math.max(0, Number(opts?.offset) || 0);
+  const rawLimit = Number(opts?.limit);
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : DEFAULT_DRAIN_LIMIT;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(channelFile(cwd, channel), 'utf-8');
+  } catch {
+    return { entries: [], total: 0, offset: 0, more: false };
+  }
+
+  const lines = raw.split('\n').filter(Boolean);
+  const total = lines.length;
+  const slice = lines.slice(offset, offset + limit);
+  const entries = [];
+  for (let i = 0; i < slice.length; i++) {
+    try {
+      entries.push(JSON.parse(slice[i]));
+    } catch {
+      // Skip malformed lines but don't fail the whole read.
+      entries.push({ ts: null, source: null, payload: null, malformed: true, raw: slice[i] });
+    }
+  }
+
+  return { entries, total, offset, more: offset + entries.length < total };
+}
+
+/**
+ * Drain (read + optionally truncate) messages from a channel.
+ *
+ * Three drain modes:
+ *  - `peek` (default): read entries, leave file untouched
+ *  - `consume`: read entries, truncate file to zero bytes
+ *  - `archive`: read entries, rename file to `<channel>-<ts>.archive.jsonl` so
+ *    historical data is preserved while the channel restarts empty
+ *
+ * @param {string} cwd - Project root
+ * @param {string} channel - Channel name
+ * @param {Object} [opts] - {mode: 'peek'|'consume'|'archive', limit, offset}
+ * @returns {Object} Drain result
+ */
+function drain(cwd, channel, opts) {
+  const mode = opts?.mode || 'peek';
+  const read = readChannel(cwd, channel, opts);
+  if (read.error) return read;
+
+  if (mode === 'peek' || read.total === 0) return { ...read, mode };
+
+  const file = channelFile(cwd, channel);
+  if (mode === 'consume') {
+    try {
+      fs.writeFileSync(file, '', 'utf-8');
+    } catch (e) {
+      return { ...read, mode, drain_error: e.message };
+    }
+  } else if (mode === 'archive') {
+    const stamp = nowIso().replace(/[:.]/g, '-');
+    const archivePath = path.join(busDir(cwd), `${channel}-${stamp}.archive.jsonl`);
+    try {
+      fs.renameSync(file, archivePath);
+    } catch (e) {
+      return { ...read, mode, drain_error: e.message };
+    }
+  } else {
+    return { error: `unknown drain mode: ${mode}` };
+  }
+
+  return { ...read, mode };
+}
+
+/**
+ * List channels + message counts + sizes for observability.
+ * @param {string} cwd - Project root
+ * @returns {{channels: Array<{channel: string, messages: number, bytes: number, archive: boolean}>}}
+ */
+function listChannels(cwd) {
+  let files;
+  try {
+    files = fs.readdirSync(busDir(cwd));
+  } catch {
+    return { channels: [] };
+  }
+
+  const channels = [];
+  for (const f of files) {
+    if (!f.endsWith('.jsonl')) continue;
+    const archive = f.includes('.archive.');
+    const nameBase = f.replace(/\.jsonl$/, '');
+    const channel = archive ? nameBase.replace(/\.archive$/, '') : nameBase;
+    const filePath = path.join(busDir(cwd), f);
+    let bytes = 0;
+    let messages = 0;
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      bytes = Buffer.byteLength(content, 'utf-8');
+      messages = content.split('\n').filter(Boolean).length;
+    } catch { /* unreadable — skip */ }
+    channels.push({ channel, messages, bytes, archive });
+  }
+  channels.sort((a, b) => a.channel.localeCompare(b.channel) || (a.archive ? 1 : -1));
+  return { channels };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdBusPublish(cwd, channel, rawPayload, opts, raw) {
+  if (!channel || rawPayload === undefined) {
+    error('Usage: bus publish <channel> <json-payload> [--source <name>]');
+  }
+  let payload;
+  try {
+    payload = JSON.parse(rawPayload);
+  } catch {
+    // Fall back: treat as plain string if not valid JSON.
+    payload = rawPayload;
+  }
+  const result = publish(cwd, channel, payload, opts);
+  output(result, raw);
+}
+
+function cmdBusDrain(cwd, channel, opts, raw) {
+  if (!channel) error('Usage: bus drain <channel> [--mode peek|consume|archive] [--limit N] [--offset N]');
+  const result = drain(cwd, channel, opts);
+  output(result, raw);
+}
+
+function cmdBusList(cwd, raw) {
+  output(listChannels(cwd), raw);
+}
+
+module.exports = {
+  publish,
+  readChannel,
+  drain,
+  listChannels,
+  validateName,
+  cmdBusPublish,
+  cmdBusDrain,
+  cmdBusList,
+  BUS_DIR,
+  DEFAULT_DRAIN_LIMIT,
+};

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

@@ -721,6 +721,121 @@ function cmdBestPractices(cwd, raw) {
   output(result, raw);
 }
 
+// ─── E-2: Repo token-size estimation (Opus 4.7 single-shot map-codebase) ────
+
+/**
+ * Estimate total token count of source files in a repository.
+ *
+ * Uses CHARS_PER_TOKEN as a rough approximation (no tokenizer shipped).
+ * Walks source files via walkSourceFiles (respects SKIP_DIRS) plus a curated
+ * set of "planning" files the map-codebase agent actually reads (top-level
+ * README, package.json, CLAUDE.md, docs/ top level).
+ *
+ * Returns enough info for map-codebase to choose between single-shot mode
+ * (all files fit in 1M context) and sharded mode (6-way parallel today).
+ *
+ * @param {string} cwd - Project root
+ * @param {Object} [opts]
+ * @param {number} [opts.threshold=700000] - Single-shot cutoff (tokens)
+ * @param {boolean} [opts.include_docs=true] - Whether to include docs/*.md top level
+ * @returns {{
+ *   total_bytes: number,
+ *   total_tokens: number,
+ *   threshold: number,
+ *   mode: 'single-shot'|'sharded',
+ *   file_count: number,
+ *   languages: Object<string, number>
+ * }}
+ */
+function estimateRepoTokenSize(cwd, opts) {
+  const { CHARS_PER_TOKEN } = require('./constants.cjs');
+  const threshold = (opts && typeof opts.threshold === 'number' && opts.threshold > 0)
+    ? opts.threshold
+    : 700000;
+  const includeDocs = !opts || opts.include_docs !== false;
+
+  let totalBytes = 0;
+  let fileCount = 0;
+  const languages = {};
+
+  // Source files via the existing walker — respects gitignore-like skip list.
+  const walked = walkSourceFiles(cwd, cwd);
+  for (const [lang, files] of Object.entries(walked.files_by_language)) {
+    for (const relPath of files) {
+      const abs = path.join(cwd, relPath);
+      try {
+        const stat = fs.statSync(abs);
+        totalBytes += stat.size;
+        languages[lang] = (languages[lang] || 0) + stat.size;
+        fileCount += 1;
+      } catch { /* file may have been removed between walk and stat — ignore */ }
+    }
+  }
+
+  // Curated top-level planning files the agent actually reads.
+  const planningCandidates = [
+    'README.md',
+    'CLAUDE.md',
+    'AGENTS.md',
+    'package.json',
+    'pyproject.toml',
+    'go.mod',
+    'Cargo.toml',
+  ];
+  for (const rel of planningCandidates) {
+    try {
+      const stat = fs.statSync(path.join(cwd, rel));
+      if (stat.isFile()) {
+        totalBytes += stat.size;
+        languages.docs = (languages.docs || 0) + stat.size;
+        fileCount += 1;
+      }
+    } catch { /* missing — expected */ }
+  }
+
+  // docs/*.md at top level only (avoid recursing into specs/decisions/archive).
+  if (includeDocs) {
+    const docsDir = path.join(cwd, 'docs');
+    try {
+      const entries = fs.readdirSync(docsDir, { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith('.md')) continue;
+        try {
+          const stat = fs.statSync(path.join(docsDir, e.name));
+          totalBytes += stat.size;
+          languages.docs = (languages.docs || 0) + stat.size;
+          fileCount += 1;
+        } catch { /* ignore */ }
+      }
+    } catch { /* no docs dir — expected in greenfield */ }
+  }
+
+  const totalTokens = Math.ceil(totalBytes / CHARS_PER_TOKEN);
+  const mode = totalTokens <= threshold ? 'single-shot' : 'sharded';
+
+  return {
+    total_bytes: totalBytes,
+    total_tokens: totalTokens,
+    threshold,
+    mode,
+    file_count: fileCount,
+    languages,
+  };
+}
+
+function cmdEstimateRepoSize(cwd, raw, args) {
+  const thresholdIdx = Array.isArray(args) ? args.indexOf('--threshold') : -1;
+  const threshold = thresholdIdx !== -1 && args[thresholdIdx + 1]
+    ? Number(args[thresholdIdx + 1])
+    : undefined;
+  const noDocs = Array.isArray(args) && args.includes('--no-docs');
+  const opts = {};
+  if (threshold && Number.isFinite(threshold) && threshold > 0) opts.threshold = threshold;
+  if (noDocs) opts.include_docs = false;
+  const result = estimateRepoTokenSize(cwd, opts);
+  output(result, raw);
+}
+
 // ─── Exports ────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -743,4 +858,7 @@ module.exports = {
   cmdDetectLanguages,
   cmdAnalyzeImports,
   cmdBestPractices,
+  cmdEstimateRepoSize,
+  // E-2
+  estimateRepoTokenSize,
 };

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

@@ -33,6 +33,7 @@ const CONTEXT_SUFFIX = '-context.md';
 const RESEARCH_SUFFIX = '-research.md';
 const VERIFICATION_SUFFIX = '-verification.md';
 const UAT_SUFFIX = '-uat.md';
+const VALIDATION_SUFFIX = '-validation.md';
 
 // ─── File matching helpers ───────────────────────────────────────────────────
 
@@ -123,7 +124,7 @@ const FOCUS_DIR = 'focus';
 const AUTO_RUN_FILE = 'auto-run.json';
 
 /** Focus auto-runner categories */
-const FOCUS_CATEGORIES = ['cleanup', 'tests', 'stability', 'features', 'docs', 'optimize'];
+const FOCUS_CATEGORIES = ['cleanup', 'tests', 'stability', 'features', 'docs', 'optimize', 'prompts'];
 
 /** Category → priority index range (indices into PRIORITY_LEVELS) */
 const CATEGORY_PRIORITY_RANGE = {
@@ -133,6 +134,7 @@ const CATEGORY_PRIORITY_RANGE = {
   features:  { min: 3, max: 5 },  // P3-P5
   docs:      { min: 5, max: 6 },  // P5-P6
   optimize:  { min: 1, max: 4 },  // P1-P4
+  prompts:   { min: 0, max: 6 },  // P0-P6 (all priorities — prompt order is authoritative)
 };
 
 /** Category → default mode + budget */
@@ -143,6 +145,7 @@ const CATEGORY_DEFAULTS = {
   features:  { mode: 'features', budget: 50 },
   docs:      { mode: 'balanced', budget: 30 },
   optimize:  { mode: 'balanced', budget: 50 },
+  prompts:   { mode: 'balanced', budget: 100 },
 };
 
 /** Doc files to scan for staleness (focus sync) */
@@ -593,6 +596,37 @@ const AUTORUN_STATUSES = {
 const FILLED_BLOCK = '\u2588';
 const EMPTY_BLOCK = '\u2591';
 
+// ─── Opus 4.7 capability thresholds ─────────────────────────────────────────
+// Used by resolveModel to pick tier given cache/thinking/context hints.
+
+/** Context estimate (tokens) above which only 1M-context models (reasoning tier) apply */
+const LARGE_CONTEXT_TOKEN_THRESHOLD = 700000;
+/** Context estimate below which fast tier is viable for cached + non-thinking work */
+const SMALL_CONTEXT_TOKEN_THRESHOLD = 50000;
+/** Files whose content is stable across agent calls in a phase — candidates for prompt caching */
+const CACHEABLE_CONTEXT_FILES = [
+  'project.md',
+  'requirements.md',
+  'roadmap.md',
+  'state.md',
+  'standards.md',
+];
+/** Default thinking budget (tokens) for verification-heavy agents */
+const THINKING_BUDGETS = {
+  'pan-plan-checker': 8000,
+  'pan-verifier': 6000,
+  'pan-integration-checker': 6000,
+  'pan-reviewer': 4000,
+  'pan-debugger': 8000,
+  'pan-roadmapper': 4000,
+  default: 2000,
+};
+/** Whether focus-auto should insert a thinking-gated reflection step between cycles */
+const REFLECTION_THRESHOLD = {
+  enabled_default: false,
+  enable_on_tiers: ['reasoning'],
+};
+
 module.exports = {
   // Directories
   PLANNING_DIR,
@@ -617,6 +651,7 @@ module.exports = {
   RESEARCH_SUFFIX,
   VERIFICATION_SUFFIX,
   UAT_SUFFIX,
+  VALIDATION_SUFFIX,
   // File matchers
   isPlanFile,
   isSummaryFile,
@@ -672,6 +707,12 @@ module.exports = {
   MAX_SLUG_LENGTH,
   FILLED_BLOCK,
   EMPTY_BLOCK,
+  // Opus 4.7 capabilities
+  LARGE_CONTEXT_TOKEN_THRESHOLD,
+  SMALL_CONTEXT_TOKEN_THRESHOLD,
+  CACHEABLE_CONTEXT_FILES,
+  THINKING_BUDGETS,
+  REFLECTION_THRESHOLD,
   CONTEXT_WINDOW,
   WARNING_THRESHOLD,
   CRITICAL_THRESHOLD,

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -101,6 +101,29 @@ function cmdContextBudget(cwd, raw) {
     recommendation = `Within budget. ~${additionalPlans} more plans could fit before degradation.`;
   }
 
+  // E-8: cache metrics — surface how much of the total context would be
+  // served from prompt cache when Opus 4.7 cache_control is active.
+  const { buildCachedContext } = require('./core.cjs');
+  let cache = null;
+  try {
+    const cached = buildCachedContext(cwd);
+    const cacheTokens = Math.ceil(cached.total_bytes / 4); // CHARS_PER_TOKEN ~ 4
+    const eligiblePct = totalTokens > 0
+      ? Math.round((cacheTokens / totalTokens) * 1000) / 10
+      : 0;
+    cache = {
+      block_count: cached.blocks.length,
+      block_paths: cached.blocks.map(b => b.path),
+      total_bytes: cached.total_bytes,
+      total_tokens: cacheTokens,
+      eligible_pct: eligiblePct,
+      sha: cached.sha,
+    };
+  } catch {
+    // buildCachedContext failed — surface as null, not as an error.
+    cache = null;
+  }
+
   const result = {
     status,
     currentPhase: currentPhase || null,
@@ -117,6 +140,7 @@ function cmdContextBudget(cwd, raw) {
     },
     contextWindow: CONTEXT_WINDOW,
     budgetUtilization: Math.round(utilization * 1000) / 1000,
+    cache,
     recommendation,
   };
 
@@ -136,6 +160,9 @@ function cmdContextBudget(cwd, raw) {
       `  Total:       ${totalTokens.toLocaleString()} / ${CONTEXT_WINDOW.toLocaleString()}`,
       ``,
       `Utilization: ${(utilization * 100).toFixed(1)}%`,
+      cache && cache.block_count > 0
+        ? `Cache: ${cache.block_count} blocks, ${cache.total_tokens.toLocaleString()} tokens (${cache.eligible_pct}% of total)`
+        : `Cache: 0 blocks (no cacheable .planning files)`,
       `${recommendation}`,
     ];
     return output(result, true, lines.join('\n'));

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

@@ -33,10 +33,10 @@ const {
  * "inherit" means the host runtime uses its own top-tier model selection.
  */
 const PROVIDER_MODELS = {
-  anthropic: { reasoning: 'inherit', mid: 'sonnet', fast: 'haiku' },
-  openai:    { reasoning: 'inherit', mid: 'mid',    fast: 'fast'  },
-  google:    { reasoning: 'inherit', mid: 'mid',    fast: 'fast'  },
-  default:   { reasoning: 'inherit', mid: 'sonnet', fast: 'haiku' },
+  anthropic: { reasoning: 'inherit', mid: 'sonnet',                 fast: 'haiku' },
+  openai:    { reasoning: 'inherit', mid: 'mid',                    fast: 'fast'  },
+  google:    { reasoning: 'inherit', mid: 'gemini-2.5-flash',       fast: 'gemini-2.5-flash-lite' },
+  default:   { reasoning: 'inherit', mid: 'sonnet',                 fast: 'haiku' },
 };
 
 /** Maps legacy Anthropic model names to provider-agnostic tier aliases. */
@@ -493,7 +493,7 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
     const sectionEnd = nextHeaderMatch ? headerIndex + nextHeaderMatch.index : content.length;
     const section = content.slice(headerIndex, sectionEnd).trim();
 
-    const goalMatch = section.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+    const goalMatch = section.match(/(?:\*\*Goal:\*\*|\*\*Goal\*\*:)\s*([^\n]+)/i);
     const goal = goalMatch ? goalMatch[1].trim() : null;
 
     return {
@@ -522,12 +522,49 @@ function getPhaseModelTier(cwd, phaseNum) {
   return match ? match[1] : null;
 }
 
+/**
+ * Adjust a resolved tier given Opus 4.7-era capability hints.
+ *
+ * Rules, in priority order:
+ *   1. context_estimate > LARGE_CONTEXT_TOKEN_THRESHOLD → force reasoning (only 1M-ctx tier).
+ *   2. needs_thinking → upgrade fast → mid; leave mid/reasoning alone.
+ *   3. cache_warm + !needs_thinking + context_estimate < SMALL_CONTEXT_TOKEN_THRESHOLD →
+ *      allow downgrade mid → fast (cheap, cached, simple tasks don't need mid).
+ *
+ * @param {string} tier - Baseline tier (reasoning|mid|fast)
+ * @param {Object} [opts] - {context_estimate, needs_thinking, cache_warm}
+ * @returns {string} Possibly-adjusted tier
+ */
+function adjustTierForCapabilities(tier, opts) {
+  if (!opts) return tier;
+  const { context_estimate, needs_thinking, cache_warm } = opts;
+  const { LARGE_CONTEXT_TOKEN_THRESHOLD, SMALL_CONTEXT_TOKEN_THRESHOLD } = require('./constants.cjs');
+
+  if (typeof context_estimate === 'number' && context_estimate > LARGE_CONTEXT_TOKEN_THRESHOLD) {
+    return 'reasoning';
+  }
+  if (needs_thinking && tier === 'fast') {
+    return 'mid';
+  }
+  if (
+    cache_warm &&
+    !needs_thinking &&
+    typeof context_estimate === 'number' &&
+    context_estimate < SMALL_CONTEXT_TOKEN_THRESHOLD &&
+    tier === 'mid'
+  ) {
+    return 'fast';
+  }
+  return tier;
+}
+
 /**
  * Resolve the model for a given agent type based on profile, provider, and routing strategy.
  * Returns "inherit" for reasoning-tier to let the host runtime use its top-tier model.
  * @param {string} cwd - Project root directory
  * @param {string} agentType - Agent name (e.g., "pan-planner", "pan-executor")
- * @param {Object} [taskMetadata] - Optional metadata for complexity routing
+ * @param {Object} [taskMetadata] - Optional metadata. Supports complexity fields and
+ *   Opus 4.7 capability hints: {context_estimate, needs_thinking, cache_warm}.
  * @returns {string} Model identifier: "inherit", "sonnet", "haiku", "mid", "fast", etc.
  */
 function resolveModelInternal(cwd, agentType, taskMetadata) {
@@ -562,6 +599,15 @@ function resolveModelInternal(cwd, agentType, taskMetadata) {
     tier = resolveComplexityTier(tier, { ...taskMetadata, thresholds });
   }
 
+  // Opus 4.7 capability adjustment (only when hints are present)
+  if (taskMetadata && (
+    taskMetadata.context_estimate !== undefined ||
+    taskMetadata.needs_thinking !== undefined ||
+    taskMetadata.cache_warm !== undefined
+  )) {
+    tier = adjustTierForCapabilities(tier, taskMetadata);
+  }
+
   return resolveTierToModel(tier, provider);
 }
 
@@ -731,6 +777,43 @@ function scanPendingTodos(cwd, area) {
  * @param {string} cwd - Project root
  * @returns {{ count: number, items: Array<{file: string, line: number, tag: string, text: string}> }}
  */
+/**
+ * Build an ordered list of cacheable context blocks for agent prompts.
+ *
+ * Reads files from .planning/ that are stable across agent calls within a phase
+ * (project.md, requirements.md, roadmap.md, state.md, standards.md). Each block
+ * is tagged `cache: true` so the host runtime (or installer) can translate to
+ * the appropriate per-runtime caching syntax (Anthropic cache_control, etc.).
+ *
+ * Files that don't exist are skipped silently. The order matches the file list
+ * in constants.cjs to keep prompt prefixes byte-stable across calls (which is
+ * what cache key matching requires).
+ *
+ * @param {string} cwd - Project root
+ * @returns {{blocks: Array<{path: string, content: string, cache: true}>, total_bytes: number, sha: string}}
+ */
+function buildCachedContext(cwd) {
+  const { PLANNING_DIR, CACHEABLE_CONTEXT_FILES } = require('./constants.cjs');
+  const crypto = require('crypto');
+  const blocks = [];
+  let totalBytes = 0;
+  const hasher = crypto.createHash('sha256');
+
+  for (const file of CACHEABLE_CONTEXT_FILES) {
+    const abs = path.join(cwd, PLANNING_DIR, file);
+    try {
+      const content = fs.readFileSync(abs, 'utf-8');
+      blocks.push({ path: toPosix(path.join(PLANNING_DIR, file)), content, cache: true });
+      totalBytes += Buffer.byteLength(content, 'utf-8');
+      hasher.update(file + '\0' + content + '\0');
+    } catch {
+      // Missing files are expected (e.g. standards.md in non-regulated projects).
+    }
+  }
+
+  return { blocks, total_bytes: totalBytes, sha: hasher.digest('hex').slice(0, 16) };
+}
+
 function scanSourceTodos(cwd) {
   const items = [];
   const libDir = path.join(cwd, 'pan-wizard-core', 'bin', 'lib');
@@ -783,6 +866,7 @@ module.exports = {
   getArchivedPhaseDirs,
   getRoadmapPhaseInternal,
   resolveModelInternal,
+  adjustTierForCapabilities,
   detectProvider,
   resolveTierToModel,
   resolveComplexityTier,
@@ -792,6 +876,7 @@ module.exports = {
   generateSlugInternal,
   getMilestoneInfo,
   toPosix,
+  buildCachedContext,
   scanPendingTodos,
   scanSourceTodos,
 };