dual-brain 7.1.29 → 7.1.30

package/bin/dual-brain.mjs

@@ -2783,6 +2783,29 @@ async function settingsScreen(rl, ask) {
   const _stC = typeof _stCal.corrections === 'number' ? _stCal.corrections.toFixed(1) : String(_stCal.corrections ?? 3);
   const _stA = typeof _stCal.autonomy    === 'number' ? _stCal.autonomy.toFixed(1)    : String(_stCal.autonomy    ?? 3);
 
+  // Cost efficiency summary (graceful — only shown when data exists)
+  let _stEffScore = null;
+  let _stEffRate  = null;
+  let _stEffTrend = null;
+  let _stEffTier  = null;
+  try {
+    const _stCt = await import('../src/cost-tracker.mjs');
+    const _stSummary = _stCt.getCostSummary(cwd, 7);
+    if (_stSummary.totalActions > 0) {
+      _stEffScore = _stCt.getEfficiencyScore(cwd);
+      _stEffRate  = Math.round(_stSummary.savingsRate * 100);
+      _stEffTrend = _stSummary.trend;
+      const tierOrder = ['recall', 'quick', 'standard', 'deep', 'ultra'];
+      const _stTierKeys = tierOrder.filter(k => _stSummary.byTier[k]);
+      _stEffTier = _stTierKeys.map(k => {
+        const t = _stSummary.byTier[k];
+        return `${k.padEnd(8)} ${String(t.count).padStart(3)}`;
+      }).join('  ');
+    }
+  } catch { /* non-fatal */ }
+
+  const _stTrendIcon = _stEffTrend === 'improving' ? '↗' : _stEffTrend === 'degrading' ? '↘' : '→';
+
   const lines = [
     top,
     row('Settings'),
@@ -2799,6 +2822,12 @@ async function settingsScreen(rl, ask) {
     row('User Calibration'),
     row(`  Specificity: ${_stS}  Corrections: ${_stC}  Autonomy: ${_stA}`),
     row(`  Level: ${_stLevel} · Style: ${_stStyle}`),
+    ...(_stEffScore !== null ? [
+      sep,
+      row('Cost Efficiency (7 days)'),
+      row(`  Score: ${_stEffScore}/100  Savings: ${_stEffRate}%  Trend: ${_stTrendIcon} ${_stEffTrend}`),
+      ...(_stEffTier ? [row(`  Tiers: ${_stEffTier}`)] : []),
+    ] : []),
     sep,
     row('[1-3] change style  [r] reset calibration  [b] back'),
     row('[m] subscriptions  [e] sessions  [x] diagnostics'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "7.1.29",
+  "version": "7.1.30",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -77,6 +77,8 @@
     "src/awareness.mjs",
     "src/tui.mjs",
     "src/living-docs.mjs",
+    "src/cost-tracker.mjs",
+    "src/think-engine.mjs",
     "src/install-hooks.mjs",
     "src/update-check.mjs",
     "src/prompt-intel.mjs",

package/src/cost-tracker.mjs

@@ -0,0 +1,184 @@
+// cost-tracker.mjs — Lightweight cost estimation and efficiency tracking for .dual-brain/costs.jsonl.
+
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TOKEN_COSTS = {
+  'claude-opus-4-6':           0.03,
+  'claude-sonnet-4-6':         0.006,
+  'claude-haiku-4-5-20251001': 0.001,
+  'gpt-5.5':                   0.04,
+  'o3':                        0.03,
+  'gpt-4o':                    0.005,
+  'gpt-4o-mini':               0.0003,
+  'default':                   0.01,
+};
+
+export function estimateTokenCost(model, tokens) {
+  const rate = TOKEN_COSTS[model] ?? TOKEN_COSTS['default'];
+  return (tokens / 1000) * rate;
+}
+
+export function trackCost(action, cwd = process.cwd()) {
+  try {
+    const dir = join(cwd, '.dual-brain');
+    mkdirSync(dir, { recursive: true });
+    const entry = {
+      timestamp:      new Date().toISOString(),
+      action:         action.action         ?? 'execute',
+      model:          action.model          ?? 'default',
+      tokensEstimated: action.tokensEstimated ?? 0,
+      costEstimated:  estimateTokenCost(action.model ?? 'default', action.tokensEstimated ?? 0),
+      tier:           action.tier           ?? 'standard',
+      wasCacheHit:    action.wasCacheHit    ?? false,
+      tokensSaved:    action.tokensSaved    ?? 0,
+    };
+    appendFileSync(join(dir, 'costs.jsonl'), JSON.stringify(entry) + '\n', 'utf8');
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+function readCostLines(cwd) {
+  const p = join(cwd, '.dual-brain', 'costs.jsonl');
+  if (!existsSync(p)) return [];
+  try {
+    return readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).flatMap(line => {
+      try { return [JSON.parse(line)]; } catch { return []; }
+    });
+  } catch { return []; }
+}
+
+export function getCostSummary(cwd = process.cwd(), days = 7) {
+  const cutoff = new Date(Date.now() - days * 86400000).toISOString();
+  const all    = readCostLines(cwd).filter(e => e.timestamp >= cutoff);
+
+  if (all.length === 0) {
+    return {
+      period: `${days} days`,
+      totalCost: 0, totalTokens: 0, totalActions: 0,
+      cacheHits: 0, tokensSaved: 0, costSaved: 0, savingsRate: 0,
+      byTier: {}, byModel: {}, trend: 'stable',
+    };
+  }
+
+  let totalCost = 0, totalTokens = 0, cacheHits = 0, tokensSaved = 0;
+  const byTier  = {};
+  const byModel = {};
+
+  for (const e of all) {
+    totalCost    += e.costEstimated   ?? 0;
+    totalTokens  += e.tokensEstimated ?? 0;
+    if (e.wasCacheHit) { cacheHits++; tokensSaved += e.tokensSaved ?? 0; }
+
+    const tier = e.tier ?? 'standard';
+    if (!byTier[tier]) byTier[tier] = { count: 0, tokens: 0, cost: 0 };
+    byTier[tier].count  += 1;
+    byTier[tier].tokens += e.tokensEstimated ?? 0;
+    byTier[tier].cost   += e.costEstimated   ?? 0;
+
+    const model = e.model ?? 'default';
+    if (!byModel[model]) byModel[model] = { count: 0, tokens: 0, cost: 0 };
+    byModel[model].count  += 1;
+    byModel[model].tokens += e.tokensEstimated ?? 0;
+    byModel[model].cost   += e.costEstimated   ?? 0;
+  }
+
+  const costSaved    = estimateTokenCost('default', tokensSaved);
+  const savingsRate  = (tokensSaved + totalTokens) > 0
+    ? tokensSaved / (tokensSaved + totalTokens)
+    : 0;
+
+  // Trend: compare first half vs second half savings rate
+  const mid   = Math.floor(all.length / 2);
+  const first = all.slice(0, mid);
+  const second = all.slice(mid);
+  const halfSavings = (half) => {
+    const ts = half.reduce((s, e) => s + (e.tokensSaved ?? 0), 0);
+    const tt = half.reduce((s, e) => s + (e.tokensEstimated ?? 0), 0);
+    return (ts + tt) > 0 ? ts / (ts + tt) : 0;
+  };
+  let trend = 'stable';
+  if (all.length >= 4) {
+    const delta = halfSavings(second) - halfSavings(first);
+    if (delta > 0.05)       trend = 'improving';
+    else if (delta < -0.05) trend = 'degrading';
+  }
+
+  return {
+    period: `${days} days`,
+    totalCost, totalTokens, totalActions: all.length,
+    cacheHits, tokensSaved, costSaved, savingsRate,
+    byTier, byModel, trend,
+  };
+}
+
+export function formatCostReport(summary) {
+  const {
+    period, totalCost, totalTokens, totalActions,
+    cacheHits, tokensSaved, costSaved, savingsRate,
+    byTier, byModel, trend,
+  } = summary;
+
+  const lines = [`COST EFFICIENCY (${period})`];
+
+  const fmtK = (n) => n >= 1000 ? `${Math.round(n / 1000)}K` : String(Math.round(n));
+  const fmtD = (n) => `~$${n.toFixed(2)}`;
+
+  lines.push(`  Total: ${fmtD(totalCost)} (${fmtK(totalTokens)} tokens, ${totalActions} actions)`);
+
+  if (cacheHits > 0) {
+    const pct = Math.round(savingsRate * 100);
+    lines.push(`  Saved: ${fmtD(costSaved)} (${fmtK(tokensSaved)} tokens from ${cacheHits} cache hits)`);
+    lines.push(`  Savings rate: ${pct}%`);
+  }
+
+  const tierOrder = ['recall', 'quick', 'standard', 'deep', 'ultra'];
+  const tierKeys  = [...new Set([...tierOrder, ...Object.keys(byTier)])].filter(k => byTier[k]);
+  if (tierKeys.length > 0) {
+    lines.push('');
+    lines.push('  Tier breakdown:');
+    for (const tier of tierKeys) {
+      const t = byTier[tier];
+      const isRecall = tier === 'recall' && (t.cost < 0.001 || t.tokens === 0);
+      const costStr  = isRecall ? '$0.00  (cache hits!)' : fmtD(t.cost);
+      lines.push(`    ${tier.padEnd(10)}${String(t.count).padStart(4)} actions  ${costStr}`);
+    }
+  }
+
+  const trendIcon = trend === 'improving' ? '↗' : trend === 'degrading' ? '↘' : '→';
+  lines.push('');
+  if (trend !== 'stable') {
+    const pct = Math.round(Math.abs(savingsRate) * 100);
+    lines.push(`  Trend: ${trendIcon} ${trend} (savings rate ${trend === 'improving' ? 'up' : 'down'} vs last half)`);
+  } else {
+    lines.push(`  Trend: ${trendIcon} stable`);
+  }
+
+  return lines.join('\n');
+}
+
+export function getEfficiencyScore(cwd = process.cwd()) {
+  const summary = getCostSummary(cwd, 7);
+  if (summary.totalActions === 0) return 50;
+
+  const TIER_WEIGHTS = { recall: 0, quick: 1, standard: 2, deep: 4, ultra: 6 };
+  const totalTierCost = Object.entries(summary.byTier).reduce((s, [tier, v]) => {
+    return s + (TIER_WEIGHTS[tier] ?? 2) * v.count;
+  }, 0);
+  const maxPossible = summary.totalActions * (TIER_WEIGHTS['ultra'] ?? 6);
+  const tierScore   = maxPossible > 0 ? 1 - (totalTierCost / maxPossible) : 0.5;
+
+  const cacheScore = summary.savingsRate;
+  const trendBonus = summary.trend === 'improving' ? 10 : summary.trend === 'degrading' ? -10 : 0;
+
+  const raw = Math.round(
+    tierScore   * 40 +
+    cacheScore  * 40 +
+    20          +
+    trendBonus
+  );
+
+  return Math.max(1, Math.min(100, raw));
+}

package/src/decide.mjs

@@ -682,10 +682,10 @@ function applyCriticalRiskFloor(model, provider, available, risk) {
 
 /**
  * Main routing decision function.
- * @param {{ profile: object, detection: object, cwd?: string }} input
+ * @param {{ profile: object, detection: object, cwd?: string, thinkResult?: object }} input
  * @returns {object} Routing decision
  */
-export function decideRoute({ profile = {}, detection = {}, cwd } = {}) {
+export function decideRoute({ profile = {}, detection = {}, cwd, thinkResult } = {}) {
   const available = getAvailableModels(profile);
 
   // Resolve active work style
@@ -786,6 +786,51 @@ export function decideRoute({ profile = {}, detection = {}, cwd } = {}) {
   // Apply profile mode bias (cost-saver / quality-first / preferences) using patched profile
   model = applyProfileBias(model, profileWithEffectiveBias, provider, available[provider], detection.tier);
 
+  // Think-engine tier hint: use as a HINT to allow cheaper model when think-engine
+  // classifies the task as recall/quick. Never escalate — only downgrade when safe to do so.
+  let thinkTier = null;
+  try {
+    if (thinkResult?.tier) thinkTier = thinkResult.tier;
+  } catch (e) {}
+
+  if (thinkTier && !isHighStakes) {
+    const claudeRankAsc = ['haiku', 'sonnet', 'opus'];
+    const openaiRankAsc = ['gpt-4o-mini', 'gpt-4.1-mini', 'gpt-4.1', 'gpt-4o', 'o4-mini', 'o3'];
+
+    if (thinkTier === 'recall' && provider === 'claude') {
+      // recall → haiku is fine if available
+      const target = 'haiku';
+      const currentIdx = claudeRankAsc.indexOf(model);
+      const targetIdx  = claudeRankAsc.indexOf(target);
+      if (targetIdx !== -1 && targetIdx < currentIdx && available.claude.includes(target)) {
+        model = target;
+      }
+    } else if (thinkTier === 'recall' && provider === 'openai') {
+      const target = 'gpt-4o-mini';
+      const currentIdx = openaiRankAsc.indexOf(model);
+      const targetIdx  = openaiRankAsc.indexOf(target);
+      if (targetIdx !== -1 && targetIdx < currentIdx && available.openai.includes(target)) {
+        model = target;
+      }
+    } else if (thinkTier === 'quick' && provider === 'claude') {
+      // quick → sonnet is sufficient
+      const target = 'sonnet';
+      const currentIdx = claudeRankAsc.indexOf(model);
+      const targetIdx  = claudeRankAsc.indexOf(target);
+      if (targetIdx !== -1 && targetIdx < currentIdx && available.claude.includes(target)) {
+        model = target;
+      }
+    } else if (thinkTier === 'quick' && provider === 'openai') {
+      const target = 'gpt-4o';
+      const currentIdx = openaiRankAsc.indexOf(model);
+      const targetIdx  = openaiRankAsc.indexOf(target);
+      if (targetIdx !== -1 && targetIdx < currentIdx && available.openai.includes(target)) {
+        model = target;
+      }
+    }
+    // 'standard', 'deep', 'ultra' — leave model unchanged; existing routing already picked correctly
+  }
+
   // Safety floor: critical-risk tasks must never use haiku/gpt-4.1-mini even in cost-saver mode
   model = applyCriticalRiskFloor(model, provider, available[provider], detection.risk);
 

package/src/pipeline.mjs

@@ -72,6 +72,10 @@ export function createPipelineRun(trigger = '', prompt = '') {
     environment: null,      // from scanEnvironment
     modelSuggestion: null,  // from suggestModel
 
+    // Think-engine fields
+    thinkResult: null,       // from think-engine
+    decisionPreflight: null, // from lookupDecision
+
     completedAt: null,
   };
 }
@@ -385,7 +389,7 @@ export function buildExecutionPlan(contextPack, trigger, options = {}) {
     effort: depthToEffort[reasoningDepth] ?? detection.effort,
   };
 
-  const decision = decideRoute({ profile, detection: detectionWithDepth, cwd: contextPack.cwd });
+  const decision = decideRoute({ profile, detection: detectionWithDepth, cwd: contextPack.cwd, thinkResult: options.thinkResult });
 
   // Resolve full model ID for display (mirrors dispatch.mjs CLAUDE_MODEL_IDS)
   const CLAUDE_MODEL_IDS = { opus: 'claude-opus-4-6', sonnet: 'claude-sonnet-4-6', haiku: 'claude-haiku-4-5-20251001' };
@@ -727,6 +731,34 @@ export async function runPipeline(trigger, prompt, options = {}) {
       // awareness not available
     }
 
+    // Knowledge preflight — check if we already know the answer
+    try {
+      const { lookupDecision, triageQuestion } = await import('./think-engine.mjs');
+      const cwd = options.cwd || process.cwd();
+
+      run.decisionPreflight = lookupDecision(prompt, options.tags || [], cwd);
+
+      // If exact reuse found, we can short-circuit
+      if (run.decisionPreflight.recommendation === 'reuse' && run.decisionPreflight.candidates[0]) {
+        // Add cached decision info to situation brief
+        if (run.situationBrief) {
+          run.situationBrief += '\nCACHED DECISION: Found prior decision with ' +
+            Math.round(run.decisionPreflight.candidates[0].relevance * 100) + '% relevance';
+        }
+      }
+
+      // Triage to determine thinking tier
+      const triage = triageQuestion(prompt, run.projectBrief, run.decisionPreflight);
+      run.thinkResult = { tier: triage.recommendedTier, estimatedTokens: triage.estimatedTokens, triage };
+
+      // Add to situation brief
+      if (run.situationBrief) {
+        run.situationBrief += '\nTHINK TIER: ' + triage.recommendedTier + ' (' + triage.estimatedTokens + ' tokens est.)';
+      }
+    } catch (e) {
+      // think-engine not available
+    }
+
     // Prompt intelligence
     try {
       const { analyzePrompt, enrichPrompt, shouldBlock, getBlockReason } = await import('./prompt-intel.mjs');
@@ -793,7 +825,7 @@ export async function runPipeline(trigger, prompt, options = {}) {
 
     // ── Phase 2: Plan ─────────────────────────────────────────────────────────
 
-    run.plan = buildExecutionPlan(run.context, trigger, { forceDepth, forceChallenger });
+    run.plan = buildExecutionPlan(run.context, trigger, { forceDepth, forceChallenger, thinkResult: run.thinkResult });
 
     // Model intelligence
     try {
@@ -956,6 +988,23 @@ export async function runPipeline(trigger, prompt, options = {}) {
       return { success: false, gateFailure: 'outcome', reason: run.gates.outcome.reason, run };
     }
 
+    // Persist decision for future recall
+    if (run.result && !run.result?.error) {
+      try {
+        const { persistDecision } = await import('./think-engine.mjs');
+        const cwd = options.cwd || process.cwd();
+        persistDecision(
+          prompt,
+          typeof run.result === 'string' ? run.result : JSON.stringify(run.result).slice(0, 1000),
+          run.thinkResult?.tier || 'standard',
+          { tags: options.tags || [], projectBrief: run.projectBrief },
+          cwd
+        );
+      } catch (e) {
+        // persist failed — non-blocking
+      }
+    }
+
   } catch (err) {
     log(`[pipeline] error in pipeline step: ${err.message}`);
     run.result = { status: 'error', error: err.message };
@@ -977,6 +1026,8 @@ export async function runPipeline(trigger, prompt, options = {}) {
     promptAnalysis: run.promptAnalysis,
     environment: run.environment,
     modelSuggestion: run.modelSuggestion,
+    thinkResult: run.thinkResult,
+    decisionPreflight: run.decisionPreflight,
     // Legacy compatibility
     plan: run.plan,
     result: run.result,

package/src/think-engine.mjs

@@ -0,0 +1,428 @@
+// think-engine.mjs — Adaptive thinking ladder: recall → triage → tier decision.
+// Replaces fixed "always dual-brain" with knowledge preflight + heuristic classification.
+// Zero network calls. All matching is keyword-based.
+
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DOCS_DIR = '.dual-brain';
+const DECISIONS_FILE = 'decisions.jsonl';
+
+const STOP_WORDS = new Set([
+  'a','an','the','and','or','but','in','on','at','to','for','of','with',
+  'by','from','is','it','its','be','as','are','was','were','been','has',
+  'have','had','do','does','did','will','would','could','should','may',
+  'might','shall','can','this','that','these','those','i','we','you',
+  'he','she','they','my','our','your','his','her','their','what','how',
+  'when','where','why','which','who','all','any','more','most','also',
+  'not','no','so','if','then','than','into','up','out','about','just',
+  'after','before','between','through','during','each','get','use',
+]);
+
+const HARD_ESCALATION_KEYWORDS = [
+  'auth','credential','secret','token','security','migration','billing',
+  'payment','deploy production','delete','drop','force push','routing logic',
+  'dispatcher','pipeline gate',
+];
+
+const TIER_TOKENS = {
+  recall: 0,
+  quick: 2000,
+  standard: 8000,
+  deep: 20000,
+  ultra: 50000,
+};
+
+const TIER_COST = {
+  recall: 'zero',
+  quick: 'minimal',
+  standard: 'moderate',
+  deep: 'significant',
+  ultra: 'heavy',
+};
+
+export function normalizeIntent(text) {
+  if (!text || typeof text !== 'string') return [];
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w));
+}
+
+function decisionsPath(cwd) {
+  return join(cwd, DOCS_DIR, DECISIONS_FILE);
+}
+
+function readDecisions(cwd) {
+  const path = decisionsPath(cwd);
+  if (!existsSync(path)) return [];
+  try {
+    const raw = readFileSync(path, 'utf8');
+    return raw
+      .split('\n')
+      .filter(l => l.trim())
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function getFreshness(timestamp) {
+  if (!timestamp) return 'stale';
+  const ageMs = Date.now() - new Date(timestamp).getTime();
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+  if (ageDays < 7) return 'current';
+  if (ageDays < 30) return 'aging';
+  return 'stale';
+}
+
+function keywordOverlap(kwA, kwB) {
+  if (!kwA.length || !kwB.length) return 0;
+  const setA = new Set(kwA);
+  const matches = kwB.filter(w => setA.has(w)).length;
+  return matches / Math.max(kwA.length, kwB.length);
+}
+
+function getApplicability(relevance, freshness) {
+  if (relevance > 0.8 && freshness === 'current') return 'exact_reuse';
+  if (relevance > 0.8 && freshness === 'aging') return 'reuse_with_validation';
+  if (relevance > 0.8 && freshness === 'stale') return 'stale';
+  if (relevance >= 0.4) return 'related_precedent';
+  return null;
+}
+
+export function lookupDecision(intent, tags = [], cwd = process.cwd()) {
+  const queryKw = normalizeIntent(intent);
+  const queryTags = tags.map(t => t.toLowerCase());
+  const decisions = readDecisions(cwd);
+
+  const candidates = [];
+  for (const dec of decisions) {
+    const decKw = dec.normalizedIntent
+      ? dec.normalizedIntent.split(' ').filter(Boolean)
+      : normalizeIntent(dec.question || dec.decision || '');
+
+    let relevance = keywordOverlap(queryKw, decKw);
+
+    const decTags = (dec.tags || []).map(t => t.toLowerCase());
+    const tagMatch = queryTags.some(t => decTags.includes(t));
+    if (tagMatch) relevance = Math.min(1, relevance + 0.15);
+
+    if (relevance < 0.4) continue;
+
+    const freshness = getFreshness(dec.timestamp);
+    const applicability = getApplicability(relevance, freshness);
+    if (!applicability) continue;
+
+    candidates.push({ decision: dec, relevance, freshness, applicability });
+  }
+
+  candidates.sort((a, b) => b.relevance - a.relevance);
+
+  const highRelevance = candidates.filter(c => c.relevance > 0.8);
+  let recommendation = 'new_thinking_needed';
+
+  if (highRelevance.length > 1) {
+    const decisions_set = highRelevance.map(c =>
+      normalizeIntent(typeof c.decision.decision === 'string' ? c.decision.decision : JSON.stringify(c.decision.decision)).join(' ')
+    );
+    const pairOverlap = keywordOverlap(
+      normalizeIntent(decisions_set[0]),
+      normalizeIntent(decisions_set[1])
+    );
+    if (pairOverlap < 0.3) {
+      for (const c of highRelevance) c.applicability = 'conflicting';
+      recommendation = 'new_thinking_needed';
+    } else if (candidates[0]?.applicability === 'exact_reuse') {
+      recommendation = 'reuse';
+    } else {
+      recommendation = 'validate';
+    }
+  } else if (candidates[0]?.applicability === 'exact_reuse') {
+    recommendation = 'reuse';
+  } else if (candidates[0]?.applicability === 'reuse_with_validation') {
+    recommendation = 'validate';
+  } else if (candidates.length > 0) {
+    recommendation = 'new_thinking_needed';
+  }
+
+  return {
+    found: candidates.length > 0,
+    candidates: candidates.slice(0, 5),
+    recommendation,
+  };
+}
+
+function detectRisk(question) {
+  const q = question.toLowerCase();
+  const critical = ['auth','credential','secret','token','security','billing','payment','force push','drop table','delete production'];
+  const high = ['migration','deploy production','routing logic','dispatcher','pipeline gate','delete','drop'];
+  const low = ['readme','doc','comment','explain','list','show','what is','how does'];
+
+  if (critical.some(k => q.includes(k))) return 'critical';
+  if (high.some(k => q.includes(k))) return 'high';
+  if (low.some(k => q.includes(k))) return 'low';
+  return 'medium';
+}
+
+function detectComplexity(question) {
+  const wordCount = question.trim().split(/\s+/).length;
+  const hasMultiStep = /and then|then also|first.*then|step \d|multiple|several|across|all/i.test(question);
+  const hasComparison = /vs|versus|compare|difference|between|trade.?off/i.test(question);
+
+  if (wordCount > 80 || (hasMultiStep && hasComparison)) return 'complex';
+  if (wordCount > 30 || hasMultiStep || hasComparison) return 'moderate';
+  return 'simple';
+}
+
+function detectNovelty(preflight) {
+  if (!preflight || !preflight.found) return 'novel';
+  if (preflight.recommendation === 'reuse') return 'known';
+  if (preflight.candidates?.some(c => c.applicability === 'related_precedent' || c.applicability === 'reuse_with_validation')) {
+    return 'variation';
+  }
+  return 'novel';
+}
+
+function hasHardEscalation(question) {
+  const q = question.toLowerCase();
+  return HARD_ESCALATION_KEYWORDS.some(k => q.includes(k));
+}
+
+export function triageQuestion(question, projectBrief, preflight) {
+  const risk = detectRisk(question);
+  const complexity = detectComplexity(question);
+  const novelty = detectNovelty(preflight);
+  const hardEscalation = hasHardEscalation(question);
+
+  let recommendedTier;
+  let reason;
+
+  if (preflight?.recommendation === 'reuse') {
+    recommendedTier = 'recall';
+    reason = 'exact match found in decision log';
+  } else if (hardEscalation || risk === 'critical') {
+    recommendedTier = 'ultra';
+    reason = hardEscalation
+      ? `hard escalation keyword detected`
+      : 'critical risk requires maximum deliberation';
+  } else if (preflight?.candidates?.some(c => c.applicability === 'conflicting')) {
+    recommendedTier = 'ultra';
+    reason = 'conflicting prior decisions require reconciliation';
+  } else if (risk === 'high' && (novelty === 'novel' || complexity === 'complex')) {
+    recommendedTier = 'deep';
+    reason = `high risk + ${novelty === 'novel' ? 'novel question' : 'complex scope'}`;
+  } else if (novelty === 'novel' && (risk === 'medium' || complexity === 'complex')) {
+    recommendedTier = 'standard';
+    reason = 'novel question with non-trivial risk or complexity';
+  } else if (novelty === 'variation' && risk === 'low') {
+    recommendedTier = 'quick';
+    reason = 'similar precedent found, low risk variation';
+  } else if (preflight?.candidates?.length > 0 && novelty !== 'novel') {
+    recommendedTier = 'quick';
+    reason = 'related precedent available, minor adaptation needed';
+  } else if (novelty === 'novel' && risk === 'low' && complexity === 'simple') {
+    recommendedTier = 'quick';
+    reason = 'novel but simple and low risk';
+  } else {
+    recommendedTier = 'standard';
+    reason = 'default tier for unclassified novel questions';
+  }
+
+  const riskRank = { low: 0, medium: 1, high: 2, critical: 3 };
+  const tierRank = { recall: 0, quick: 1, standard: 2, deep: 3, ultra: 4 };
+  const minTierForRisk = { low: 'recall', medium: 'quick', high: 'deep', critical: 'ultra' };
+  const riskFloor = minTierForRisk[risk] ?? 'quick';
+  if (tierRank[recommendedTier] < tierRank[riskFloor]) {
+    recommendedTier = riskFloor;
+    reason += ` (escalated to ${riskFloor} by risk floor)`;
+  }
+
+  const confidenceBase = novelty === 'known' ? 0.9
+    : novelty === 'variation' ? 0.75
+    : 0.6;
+  const confidence = Math.max(0.3, confidenceBase - (risk === 'critical' ? 0.2 : 0));
+
+  const estimatedTokens = TIER_TOKENS[recommendedTier] ?? 0;
+
+  return {
+    novelty,
+    risk,
+    complexity,
+    confidence,
+    recommendedTier,
+    reason,
+    estimatedTokens,
+    hardEscalation,
+  };
+}
+
+export async function think(question, options = {}, cwd = process.cwd()) {
+  const result = {
+    question,
+    startedAt: Date.now(),
+    tier: null,
+    phases: [],
+    answer: null,
+    tokensUsed: 0,
+    cost: 'minimal',
+    fromCache: false,
+    decision: null,
+  };
+
+  if (!options.skipRecall) {
+    const preflight = lookupDecision(question, options.tags || [], cwd);
+    result.phases.push({ phase: 'recall', ...preflight });
+
+    if (preflight.recommendation === 'reuse' && preflight.candidates[0]) {
+      result.tier = 'recall';
+      result.answer = preflight.candidates[0].decision;
+      result.fromCache = true;
+      result.cost = 'zero';
+      result.tokensUsed = 0;
+      return result;
+    }
+  }
+
+  const recallPhase = result.phases[0] ?? null;
+  const triage = triageQuestion(question, options.projectBrief, recallPhase);
+  result.phases.push({ phase: 'triage', ...triage });
+  result.tier = options.forceLevel || triage.recommendedTier;
+
+  result.tokensUsed = TIER_TOKENS[result.tier] ?? triage.estimatedTokens;
+  result.cost = TIER_COST[result.tier] ?? 'moderate';
+
+  return result;
+}
+
+export function persistDecision(question, answer, tier, options = {}, cwd = process.cwd()) {
+  const dir = join(cwd, DOCS_DIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const kw = normalizeIntent(question);
+  const normalizedIntent = kw.join(' ');
+
+  const answerText = typeof answer === 'string' ? answer : JSON.stringify(answer);
+  const sentences = answerText.match(/[^.!?]+[.!?]+/g) ?? [];
+  const rationale = sentences.slice(0, 3).map(s => s.trim()).filter(Boolean);
+
+  const autoTags = [];
+  const q = question.toLowerCase();
+  if (/auth|security|credential|secret|token/.test(q)) autoTags.push('security');
+  if (/migration|migrate|upgrade/.test(q)) autoTags.push('migration');
+  if (/architecture|design|structure|pattern/.test(q)) autoTags.push('architecture');
+  if (/test|spec|coverage/.test(q)) autoTags.push('testing');
+  if (/deploy|release|publish|production/.test(q)) autoTags.push('deployment');
+  if (/routing|dispatch|pipeline/.test(q)) autoTags.push('routing');
+
+  const tags = [...new Set([...(options.tags || []), ...autoTags])];
+
+  const contextSpecific = /this session|right now|current branch|today|temporary|one.?off/i.test(answerText);
+  const reusable = !contextSpecific;
+
+  const tokensUsed = options.tokensUsed ?? TIER_TOKENS[tier] ?? 0;
+
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000).toISOString();
+
+  const confScore = options.confidence ?? (
+    tier === 'ultra' || tier === 'deep' ? 'high'
+    : tier === 'standard' ? 'medium'
+    : 'low'
+  );
+
+  const entry = {
+    id: `dec_${Date.now()}`,
+    timestamp: now.toISOString(),
+    question,
+    normalizedIntent,
+    decision: answerText,
+    rationale,
+    tags,
+    confidence: typeof confScore === 'string' ? confScore : (confScore > 0.7 ? 'high' : confScore > 0.4 ? 'medium' : 'low'),
+    tier,
+    tokensUsed,
+    expiresAt,
+    reusable,
+  };
+
+  appendFileSync(join(dir, DECISIONS_FILE), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function getThinkingStats(cwd = process.cwd()) {
+  const decisions = readDecisions(cwd);
+  if (!decisions.length) {
+    return {
+      totalDecisions: 0,
+      cacheHits: 0,
+      cacheHitRate: 0,
+      tierDistribution: { recall: 0, quick: 0, standard: 0, deep: 0, ultra: 0 },
+      totalTokensSaved: 0,
+      avgTier: 'none',
+    };
+  }
+
+  const tierDist = { recall: 0, quick: 0, standard: 0, deep: 0, ultra: 0 };
+  let cacheHits = 0;
+  let totalTokensSaved = 0;
+  const tierCounts = {};
+
+  for (const dec of decisions) {
+    const t = dec.tier ?? 'standard';
+    if (tierDist[t] !== undefined) tierDist[t]++;
+    tierCounts[t] = (tierCounts[t] ?? 0) + 1;
+
+    if (t === 'recall') {
+      cacheHits++;
+      totalTokensSaved += TIER_TOKENS.standard;
+    }
+  }
+
+  const cacheHitRate = decisions.length > 0 ? cacheHits / decisions.length : 0;
+
+  let maxCount = 0;
+  let avgTier = 'standard';
+  for (const [tier, count] of Object.entries(tierCounts)) {
+    if (count > maxCount) { maxCount = count; avgTier = tier; }
+  }
+
+  return {
+    totalDecisions: decisions.length,
+    cacheHits,
+    cacheHitRate: Math.round(cacheHitRate * 1000) / 1000,
+    tierDistribution: tierDist,
+    totalTokensSaved,
+    avgTier,
+  };
+}
+
+export function formatThinkResult(result) {
+  const { tier, phases, cost, fromCache, tokensUsed } = result;
+
+  const tierLabel = tier ? tier.charAt(0).toUpperCase() + tier.slice(1) : 'Unknown';
+  const tokenStr = tokensUsed > 0 ? `${(tokensUsed / 1000).toFixed(0)}K tokens estimated` : 'zero tokens';
+
+  const lines = [`THINKING: ${tierLabel} tier (${tokenStr})`];
+
+  for (const phase of phases ?? []) {
+    if (phase.phase === 'recall') {
+      const count = phase.candidates?.length ?? 0;
+      const found = count > 0
+        ? `${count} related precedent${count === 1 ? '' : 's'} found`
+        : 'no prior decisions found';
+      lines.push(`  Phase 1: Recall — ${found}`);
+    } else if (phase.phase === 'triage') {
+      lines.push(`  Phase 2: Triage — ${phase.novelty ?? 'novel'} question, ${phase.risk ?? 'medium'} risk`);
+    }
+  }
+
+  lines.push(`  Cost: ${cost ?? 'unknown'}`);
+  if (fromCache) lines.push('  Source: decision cache (no model call needed)');
+
+  return lines.join('\n');
+}