@codexa/cli 9.0.19 → 9.0.21

package/commands/decide.ts

@@ -2,6 +2,7 @@ import { getDb } from "../db/connection";
 import { initSchema, getNextDecisionId } from "../db/schema";
 import { resolveSpec } from "./spec-resolver";
 import { CodexaError } from "../errors";
+import { invalidateCache } from "../context/cache";
 
 export interface ConflictAnalysis {
   hasConflict: boolean;
@@ -193,6 +194,9 @@ export function decide(title: string, decision: string, options: { rationale?: s
     }
   }
 
+  // v10.0: Invalidate context cache (new decision affects context)
+  invalidateCache(spec.id);
+
   console.log(`\nDecisao registrada: ${decisionId}`);
   console.log(`Titulo: ${title}`);
   console.log(`Decisao: ${decision}`);

package/commands/knowledge.ts

@@ -2,6 +2,7 @@ import { getDb } from "../db/connection";
 import { initSchema, getRelatedDecisions, getRelatedFiles } from "../db/schema";
 import { resolveSpec } from "./spec-resolver";
 import { CodexaError, ValidationError } from "../errors";
+import { invalidateCache } from "../context/cache";
 
 type KnowledgeCategory = "discovery" | "decision" | "blocker" | "pattern" | "constraint";
 type KnowledgeSeverity = "info" | "warning" | "critical";
@@ -48,6 +49,9 @@ export function addKnowledge(options: AddKnowledgeOptions): void {
     [spec.id, currentTask.id, options.category, options.content, severity, broadcastTo, now]
   );
 
+  // v10.0: Invalidate context cache (new knowledge affects context)
+  invalidateCache(spec.id);
+
   const severityIcon = {
     info: "i",
     warning: "!",
@@ -516,4 +520,64 @@ export function resolveKnowledge(ids: string, resolution?: string, specId?: stri
   }
 
   console.log();
+}
+
+// v10.0: Compact reasoning_log during phase advance
+export function compactReasoning(options: {
+  specId: string | number;
+  dryRun?: boolean;
+}): { archived: number; kept: number } {
+  const db = getDb();
+
+  const doneTasks = db.query(
+    "SELECT id FROM tasks WHERE spec_id = ? AND status = 'done'"
+  ).all(options.specId) as any[];
+
+  if (doneTasks.length === 0) return { archived: 0, kept: 0 };
+
+  const doneTaskIds = doneTasks.map((t: any) => t.id);
+  const placeholders = doneTaskIds.map(() => "?").join(",");
+
+  // Phase 1: Remove low-importance entries from completed tasks (keep recommendations always)
+  const lowImportance = db.query(
+    `SELECT id FROM reasoning_log
+     WHERE spec_id = ? AND task_id IN (${placeholders})
+     AND importance IN ('normal', 'low')
+     AND category != 'recommendation'`
+  ).all(options.specId, ...doneTaskIds) as any[];
+
+  // Phase 2: Cap at 5 entries per task (keep most important)
+  const overflow: number[] = [];
+  for (const taskId of doneTaskIds) {
+    const entries = db.query(
+      `SELECT id FROM reasoning_log
+       WHERE spec_id = ? AND task_id = ?
+       ORDER BY
+         CASE importance WHEN 'critical' THEN 1 WHEN 'high' THEN 2 WHEN 'normal' THEN 3 ELSE 4 END,
+         created_at DESC`
+    ).all(options.specId, taskId) as any[];
+
+    if (entries.length > 5) {
+      for (let i = 5; i < entries.length; i++) {
+        overflow.push((entries[i] as any).id);
+      }
+    }
+  }
+
+  const archiveIds = new Set([
+    ...lowImportance.map((r: any) => r.id),
+    ...overflow,
+  ]);
+
+  if (!options.dryRun && archiveIds.size > 0) {
+    const ids = Array.from(archiveIds);
+    const ph = ids.map(() => "?").join(",");
+    db.run(`DELETE FROM reasoning_log WHERE id IN (${ph})`, ids);
+  }
+
+  const kept = (db.query(
+    "SELECT COUNT(*) as c FROM reasoning_log WHERE spec_id = ?"
+  ).get(options.specId) as any)?.c || 0;
+
+  return { archived: archiveIds.size, kept };
 }

package/commands/review.ts

@@ -3,6 +3,7 @@ import { initSchema, getArchitecturalAnalysisForSpec } from "../db/schema";
 import { enforceGate } from "../gates/validator";
 import { resolveSpec } from "./spec-resolver";
 import { CodexaError, GateError } from "../errors";
+import { cleanupContextFiles } from "../context/file-writer";
 
 // ═══════════════════════════════════════════════════════════════
 // P1-2: Review Score — Threshold Automatico
@@ -313,6 +314,9 @@ export function reviewApprove(options?: { specId?: string; force?: boolean; forc
   // Atualizar spec para completed
   db.run("UPDATE specs SET phase = 'completed', updated_at = ? WHERE id = ?", [now, spec.id]);
 
+  // v10.0: Clean up stale context files
+  cleanupContextFiles(spec.id);
+
   // Buscar todos os dados para snapshot e relatorio
   const tasks = db.query("SELECT * FROM tasks WHERE spec_id = ? ORDER BY number").all(spec.id) as any[];
   const decisions = db.query("SELECT * FROM decisions WHERE spec_id = ?").all(spec.id) as any[];
@@ -379,6 +383,9 @@ export function reviewSkip(specId?: string): void {
   // Atualizar spec para completed
   db.run("UPDATE specs SET phase = 'completed', updated_at = ? WHERE id = ?", [now, spec.id]);
 
+  // v10.0: Clean up stale context files
+  cleanupContextFiles(spec.id);
+
   // Criar snapshot final
   const review = db.query("SELECT * FROM review WHERE spec_id = ?").get(spec.id) as any;
   const allData = {

package/commands/task.ts

@@ -4,13 +4,18 @@ import { enforceGate } from "../gates/validator";
 import { parseSubagentReturn, formatValidationErrors } from "../protocol/subagent-protocol";
 import { processSubagentReturn, formatProcessResult } from "../protocol/process-return";
 import { getContextForSubagent, getMinimalContextForSubagent } from "./utils";
-import { getUnreadKnowledgeForTask, compactKnowledge } from "./knowledge";
+import { getUnreadKnowledgeForTask, compactKnowledge, compactReasoning } from "./knowledge";
 import { loadTemplate } from "../templates/loader";
 import { TaskStateError, ValidationError, KnowledgeBlockError } from "../errors";
 import { resolveSpec, resolveSpecOrNull } from "./spec-resolver";
 import { getAgentDomain, domainToScope } from "../context/domains";
 import { resolveAgent } from "../context/agent-registry";
 import { loadAgentExpertise, getAgentDescription } from "../context/agent-expertise";
+import { generateContextFile } from "../context/generator";
+import { getModelForTask } from "../context/model-profiles";
+import { getContextBudget, formatContextWarning, estimateTokens } from "../context/monitor";
+import { invalidateCache } from "../context/cache";
+import { cleanupContextFiles } from "../context/file-writer";
 
 export function taskNext(json: boolean = false, specId?: string): void {
   initSchema();
@@ -146,7 +151,7 @@ function showStuckWarning(stuck: any[]): void {
   console.log(`  Use: task done <id> --force --force-reason "timeout" para liberar\n`);
 }
 
-export function taskStart(ids: string, json: boolean = false, minimalContext: boolean = false, specId?: string): void {
+export function taskStart(ids: string, json: boolean = false, minimalContext: boolean = false, specId?: string, inlineContext: boolean = false): void {
   initSchema();
   enforceGate("task-start");
 
@@ -207,51 +212,10 @@ export function taskStart(ids: string, json: boolean = false, minimalContext: bo
   }
 
   if (json) {
-    // NOVO: Incluir contexto COMPLETO para cada task
     const contexts = startedTasks.map((task) => {
-      // v10.0: Contexto completo por padrao, reduzido via --minimal-context
-      const contextText = minimalContext
-        ? getMinimalContextForSubagent(task.id)
-        : getContextForSubagent(task.id);
-      const unreadKnowledge = getUnreadKnowledgeForTask(spec.id, task.id);
-
-      // NOVO v7.4: Buscar implementation patterns relevantes
       const taskFiles = task.files ? JSON.parse(task.files) : [];
-      const agentScope = domainToScope(getAgentDomain(task.agent));
-
-      // Buscar patterns por escopo do agente E por arquivos esperados
-      let relevantPatterns: any[] = [];
-
-      // Primeiro: patterns que correspondem aos arquivos esperados
-      if (taskFiles.length > 0) {
-        const filePatterns = getPatternsForFiles(taskFiles);
-        relevantPatterns.push(...filePatterns);
-      }
-
-      // Segundo: patterns do escopo do agente (se nao foram encontrados via arquivos)
-      if (relevantPatterns.length === 0) {
-        const scopePatterns = getPatternsByScope(agentScope);
-        relevantPatterns.push(...scopePatterns);
-      }
-
-      // Formatar patterns para o contexto (sem duplicatas)
-      const patternNames = new Set<string>();
-      const formattedPatterns = relevantPatterns
-        .filter(p => {
-          if (patternNames.has(p.name)) return false;
-          patternNames.add(p.name);
-          return true;
-        })
-        .map(p => ({
-          name: p.name,
-          category: p.category,
-          applies_to: p.applies_to,
-          template: p.template,
-          structure: JSON.parse(p.structure || "{}"),
-          examples: JSON.parse(p.examples || "[]").slice(0, 3), // Top 3 exemplos
-          anti_patterns: JSON.parse(p.anti_patterns || "[]"),
-          confidence: p.confidence,
-        }));
+      const agentDomain = getAgentDomain(task.agent);
+      const agentScope = domainToScope(agentDomain);
 
       // R1: Load condensed expertise from agent .md
       const agentExpertise = task.agent ? loadAgentExpertise(task.agent) : "";
@@ -265,43 +229,134 @@ export function taskStart(ids: string, json: boolean = false, minimalContext: bo
       // R5: Get description for orchestrator use
       const agentDescription = task.agent ? getAgentDescription(task.agent) : null;
 
-      return {
+      // v10.0: Model profile based on agent domain
+      const modelProfile = getModelForTask(agentDomain);
+
+      // v10.0: File-based context (default) vs inline (backward compat)
+      const useFileContext = !inlineContext && !minimalContext;
+      let contextFile: string | null = null;
+      let contextText: string | null = null;
+      let contextSummary: string;
+
+      if (useFileContext) {
+        // Write context to file, subagent reads via Read tool
+        contextFile = generateContextFile(task.id);
+        contextSummary = getMinimalContextForSubagent(task.id);
+      } else if (minimalContext) {
+        contextSummary = getMinimalContextForSubagent(task.id);
+      } else {
+        // --inline-context: backward compat
+        contextText = getContextForSubagent(task.id);
+        contextSummary = getMinimalContextForSubagent(task.id);
+      }
+
+      // v10.0: Pre-built lean prompt for subagent (orchestrator just passes it)
+      const subagentPrompt = useFileContext
+        ? loadTemplate("subagent-prompt-lean", {
+            taskName: task.name,
+            filesList: taskFiles.map((f: string) => `  - ${f}`).join('\n') || '  (nenhum arquivo especificado)',
+            taskDescription: task.checkpoint || task.name,
+            contextSummary: contextSummary!,
+            contextFile: contextFile || "",
+            agentIdentity,
+            agentExpertise: agentExpertise
+              ? `\n## EXPERTISE DO AGENTE\n\n${agentExpertise}\n`
+              : '',
+          })
+        : null;
+
+      // v10.0: Context budget estimation
+      const completedTaskCount = (db.query(
+        "SELECT COUNT(*) as c FROM tasks WHERE spec_id = ? AND status = 'done'"
+      ).get(spec.id) as any)?.c || 0;
+
+      const promptText = subagentPrompt || contextText || contextSummary!;
+      const contextFileContent = contextFile
+        ? (Bun.file(contextFile).size > 0 ? String(Bun.file(contextFile).size) : "")
+        : "";
+      const contextBudget = getContextBudget(
+        promptText,
+        contextFileContent,
+        completedTaskCount,
+        contextFile || undefined,
+      );
+
+      const contextWarning = formatContextWarning(contextBudget);
+      if (contextWarning) {
+        console.error(contextWarning);
+      }
+
+      // Base output (lean by default)
+      const output: any = {
         taskId: task.id,
         number: task.number,
         name: task.name,
         agent: task.agent,
         agentDescription,
         files: taskFiles,
-        // AVISO PARA O ORQUESTRADOR - NAO EXECUTE, DELEGUE
-        _orchestratorWarning: "NAO execute esta task diretamente. Use Task tool com subagent_type='general-purpose' para delegar. O campo 'subagentContext' abaixo e o prompt para o SUBAGENT.",
-        // Contexto para o subagent (NAO para o orquestrador)
-        context: contextText,
-        contextMode: minimalContext ? "minimal" : "full",
-        // Knowledge nao lido (broadcast de outras tasks)
-        unreadKnowledge: unreadKnowledge.map((k: any) => ({
-          id: k.id,
-          category: k.category,
-          content: k.content,
-          severity: k.severity,
-          origin_task: k.task_origin,
-        })),
-        // NOVO v7.4: Implementation patterns extraidos do projeto
-        implementationPatterns: formattedPatterns,
-        // Contexto para o SUBAGENT (o orquestrador deve passar isso via Task tool)
-        subagentContext: loadTemplate("subagent-context", {
-          filesList: taskFiles.map(f => `  - ${f}`).join('\n') || '  (nenhum arquivo especificado - analise o contexto)',
+        modelProfile,
+        contextBudget,
+        _orchestratorWarning: "NAO execute esta task diretamente. Use Task tool para delegar. Use o campo 'subagentPrompt' como prompt.",
+      };
+
+      if (useFileContext) {
+        // v10.0: File-based context (new default)
+        output.contextFile = contextFile;
+        output.contextSummary = contextSummary!;
+        output.contextMode = "file";
+        output.subagentPrompt = subagentPrompt;
+      } else if (inlineContext) {
+        // Backward compat: full inline
+        output.context = contextText;
+        output.contextMode = "inline";
+
+        const unreadKnowledge = getUnreadKnowledgeForTask(spec.id, task.id);
+        output.unreadKnowledge = unreadKnowledge.map((k: any) => ({
+          id: k.id, category: k.category, content: k.content,
+          severity: k.severity, origin_task: k.task_origin,
+        }));
+
+        // Patterns (only in inline mode — in file mode they're in the context file)
+        let relevantPatterns: any[] = [];
+        if (taskFiles.length > 0) {
+          relevantPatterns.push(...getPatternsForFiles(taskFiles));
+        }
+        if (relevantPatterns.length === 0) {
+          relevantPatterns.push(...getPatternsByScope(agentScope));
+        }
+        const patternNames = new Set<string>();
+        output.implementationPatterns = relevantPatterns
+          .filter(p => {
+            if (patternNames.has(p.name)) return false;
+            patternNames.add(p.name);
+            return true;
+          })
+          .map(p => ({
+            name: p.name, category: p.category, applies_to: p.applies_to,
+            template: p.template,
+            structure: JSON.parse(p.structure || "{}"),
+            examples: JSON.parse(p.examples || "[]").slice(0, 3),
+            anti_patterns: JSON.parse(p.anti_patterns || "[]"),
+            confidence: p.confidence,
+          }));
+
+        output.subagentContext = loadTemplate("subagent-context", {
+          filesList: taskFiles.map((f: string) => `  - ${f}`).join('\n') || '  (nenhum arquivo especificado)',
           agentIdentity,
-          agentExpertise: agentExpertise
-            ? `\n## EXPERTISE DO AGENTE\n\n${agentExpertise}\n\n`
+          agentExpertise: agentExpertise ? `\n## EXPERTISE DO AGENTE\n\n${agentExpertise}\n\n` : '',
+        });
+        output.subagentReturnProtocol = loadTemplate("subagent-return-protocol", {
+          patternsNote: output.implementationPatterns.length > 0
+            ? `\nPATTERNS: ${output.implementationPatterns.length} patterns extraidos do projeto.\n`
             : '',
-        }),
-        // Instrucoes de retorno para o SUBAGENT
-        subagentReturnProtocol: loadTemplate("subagent-return-protocol", {
-          patternsNote: formattedPatterns.length > 0
-            ? `\nPATTERNS: Voce recebeu ${formattedPatterns.length} implementation patterns extraidos do projeto.\nUse os TEMPLATES fornecidos para criar codigo CONSISTENTE com o projeto existente.\n`
-            : '',
-        }),
-      };
+        });
+      } else {
+        // --minimal-context
+        output.contextSummary = contextSummary!;
+        output.contextMode = "minimal";
+      }
+
+      return output;
     });
     console.log(JSON.stringify({ started: contexts }));
     return;
@@ -403,6 +458,9 @@ export function taskDone(id: string, options: { checkpoint: string; files?: stri
     const processResult = processSubagentReturn(spec.id, taskId, task.number, subagentData);
     console.log(formatProcessResult(processResult));
 
+    // v10.0: Invalidate context cache (knowledge/decisions changed)
+    invalidateCache(spec.id);
+
     // v8.3: BLOCKING check para knowledge critico nao reconhecido (substitui warning v8.2)
     const unackedCritical = getUnreadKnowledgeForTask(spec.id, taskId)
         .filter((k: any) => k.severity === 'critical' && k.task_origin !== taskId);
@@ -490,7 +548,7 @@ export function taskDone(id: string, options: { checkpoint: string; files?: stri
       bypassesUsed: bypassCount,
       filesCreated: subagentData?.files_created?.length || 0,
       filesModified: subagentData?.files_modified?.length || 0,
-      contextSizeBytes: 0,
+      contextSizeBytes: estimateTokens(getContextForSubagent(task.id)) * 4,
       executionDurationMs: duration,
     });
   } catch { /* nao-critico: nao falhar task done por tracking de performance */ }
@@ -716,10 +774,15 @@ export function taskPhaseAdvance(options: { noCompact?: boolean; json?: boolean;
 
   const now = new Date().toISOString();
 
-  // Compact knowledge (unless --no-compact)
+  // Compact knowledge, reasoning, and clean up stale files (unless --no-compact)
   if (!options.noCompact) {
     console.log(`\nCompactando contexto da fase ${currentPhase}...`);
     compactKnowledge({ specId: spec.id });
+    const reasoningResult = compactReasoning({ specId: spec.id });
+    if (reasoningResult.archived > 0) {
+      console.log(`  Reasoning compactado: ${reasoningResult.archived} entradas removidas, ${reasoningResult.kept} mantidas`);
+    }
+    cleanupContextFiles(spec.id);
   }
 
   // Create phase summary as critical knowledge

package/context/assembly.ts

@@ -31,6 +31,13 @@ export interface ContextData {
     discoveredPatterns: any[];
 }
 
+const RETURN_PROTOCOL = `
+### RETORNO OBRIGATORIO
+\`\`\`json
+{"status": "completed|blocked", "summary": "...", "files_created": [], "files_modified": [], "reasoning": {"approach": "como abordou", "challenges": [], "recommendations": "para proximas tasks"}}
+\`\`\`
+`;
+
 export function assembleSections(header: string, sections: ContextSection[]): string {
     // Sort by priority (lower = higher priority, kept during truncation)
     const sorted = [...sections].sort((a, b) => a.priority - b.priority);
@@ -40,42 +47,88 @@ export function assembleSections(header: string, sections: ContextSection[]): st
         output += section.content;
     }
 
-    // Protocolo de retorno (sempre incluido)
-    output += `
-### RETORNO OBRIGATORIO
-\`\`\`json
-{"status": "completed|blocked", "summary": "...", "files_created": [], "files_modified": [], "reasoning": {"approach": "como abordou", "challenges": [], "recommendations": "para proximas tasks"}}
-\`\`\`
-`;
+    output += RETURN_PROTOCOL;
 
-    // v8.3: Overall size cap com truncamento inteligente por secao
+    // v10.0: Progressive truncation — halve sections before dropping them entirely
     if (output.length > MAX_CONTEXT_SIZE) {
-        const parts = output.split('\n### ');
-        let trimmed = parts[0]; // Sempre manter header
-        let breakIndex = parts.length;
-
-        for (let i = 1; i < parts.length; i++) {
-            const candidate = trimmed + '\n### ' + parts[i];
-            if (candidate.length > MAX_CONTEXT_SIZE - 200) {
-                breakIndex = i;
-                break;
-            }
-            trimmed = candidate;
+        return truncateWithBudget(header, sorted, MAX_CONTEXT_SIZE);
+    }
+
+    return output;
+}
+
+function truncateWithBudget(header: string, sections: ContextSection[], maxSize: number): string {
+    const reservedSize = header.length + RETURN_PROTOCOL.length + 120;
+    const budgetForSections = maxSize - reservedSize;
+
+    // Mutable map of section content
+    const sectionContent = new Map<string, string>();
+    let totalContentSize = 0;
+    for (const s of sections) {
+        sectionContent.set(s.name, s.content);
+        totalContentSize += s.content.length;
+    }
+
+    if (totalContentSize <= budgetForSections) {
+        let result = header;
+        for (const s of sections) result += s.content;
+        result += RETURN_PROTOCOL;
+        return result;
+    }
+
+    // Phase 1: Halve content of lowest-priority sections iteratively
+    // Sort descending (highest priority number = least important = truncated first)
+    const byLowestPriority = [...sections].sort((a, b) => b.priority - a.priority);
+
+    for (const s of byLowestPriority) {
+        if (totalContentSize <= budgetForSections) break;
+
+        const current = sectionContent.get(s.name);
+        if (!current) continue;
+
+        const halfSize = Math.floor(current.length / 2);
+
+        if (halfSize < 80) {
+            // Too small to truncate — drop entirely
+            totalContentSize -= current.length;
+            sectionContent.delete(s.name);
+        } else {
+            const truncated = current.substring(0, halfSize) + "\n[... secao truncada]\n";
+            totalContentSize -= (current.length - truncated.length);
+            sectionContent.set(s.name, truncated);
         }
+    }
 
-        // Coletar nomes das secoes omitidas
-        const omittedNames: string[] = [];
-        for (let i = breakIndex; i < parts.length; i++) {
-            const name = parts[i].split('\n')[0].trim();
-            if (name) omittedNames.push(name);
+    // Phase 2: If still over budget, drop entire sections (fallback)
+    if (totalContentSize > budgetForSections) {
+        for (const s of byLowestPriority) {
+            if (totalContentSize <= budgetForSections) break;
+            const content = sectionContent.get(s.name);
+            if (content) {
+                totalContentSize -= content.length;
+                sectionContent.delete(s.name);
+            }
         }
+    }
 
-        if (omittedNames.length > 0) {
-            trimmed += `\n\n[CONTEXTO TRUNCADO: ${omittedNames.length} secao(oes) omitida(s) (${omittedNames.join(', ')}). Use: codexa context detail <secao>]`;
+    // Reassemble in original priority order
+    let result = header;
+    const omitted: string[] = [];
+
+    for (const s of sections) {
+        const content = sectionContent.get(s.name);
+        if (content) {
+            result += content;
+        } else {
+            omitted.push(s.name);
         }
+    }
 
-        output = trimmed;
+    result += RETURN_PROTOCOL;
+
+    if (omitted.length > 0) {
+        result += `\n[CONTEXTO TRUNCADO: ${omitted.length} secao(oes) omitida(s) (${omitted.join(', ')}). Use: codexa context detail <secao>]`;
     }
 
-    return output;
+    return result;
 }

package/context/cache.ts

@@ -0,0 +1,85 @@
+// ═══════════════════════════════════════════════════════════════
+// CONTEXT CACHE (v10.0)
+// Content-addressable cache to avoid regenerating identical context.
+// Invalidated when knowledge, decisions, or task state changes.
+// ═══════════════════════════════════════════════════════════════
+
+import { getDb } from "../db/connection";
+
+interface CacheEntry {
+  hash: string;
+  filePath: string;
+  specId: string;
+  createdAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+export function computeContextHash(specId: string, taskId: number): string {
+  const db = getDb();
+
+  const spec = db.query("SELECT updated_at FROM specs WHERE id = ?").get(specId) as any;
+  const ctx = db.query("SELECT updated_at FROM context WHERE spec_id = ?").get(specId) as any;
+  const knowledgeCount = (db.query(
+    "SELECT COUNT(*) as c FROM knowledge WHERE spec_id = ?"
+  ).get(specId) as any)?.c || 0;
+  const decisionCount = (db.query(
+    "SELECT COUNT(*) as c FROM decisions WHERE spec_id = ? AND status = 'active'"
+  ).get(specId) as any)?.c || 0;
+  const task = db.query("SELECT depends_on, agent, files FROM tasks WHERE id = ?").get(taskId) as any;
+
+  // Hash key components that affect context content
+  const parts = [
+    specId,
+    String(taskId),
+    spec?.updated_at || "",
+    ctx?.updated_at || "",
+    String(knowledgeCount),
+    String(decisionCount),
+    task?.depends_on || "[]",
+    task?.agent || "",
+    task?.files || "[]",
+  ];
+
+  // Simple hash using Bun's built-in hashing
+  const raw = parts.join("|");
+  const hasher = new Bun.CryptoHasher("md5");
+  hasher.update(raw);
+  return hasher.digest("hex");
+}
+
+export function getCachedContextPath(hash: string): string | null {
+  const entry = cache.get(hash);
+  if (!entry) return null;
+
+  // Check if file still exists
+  const file = Bun.file(entry.filePath);
+  if (file.size === 0) {
+    cache.delete(hash);
+    return null;
+  }
+
+  return entry.filePath;
+}
+
+export function setCachedContext(hash: string, filePath: string, specId: string): void {
+  cache.set(hash, {
+    hash,
+    filePath,
+    specId,
+    createdAt: Date.now(),
+  });
+}
+
+export function invalidateCache(specId: string): void {
+  // v10.0: Selective invalidation — only remove entries for the given spec
+  for (const [key, entry] of cache.entries()) {
+    if (entry.specId === specId) {
+      cache.delete(key);
+    }
+  }
+}
+
+export function clearCache(): void {
+  cache.clear();
+}

package/context/file-writer.ts

@@ -0,0 +1,47 @@
+// ═══════════════════════════════════════════════════════════════
+// CONTEXT FILE WRITER (v10.0)
+// Writes context to .codexa/context/task-{id}.md instead of
+// injecting 16KB inline into the subagent prompt.
+// Subagents read the file on-demand via Read tool.
+// ═══════════════════════════════════════════════════════════════
+
+import { existsSync, mkdirSync } from "fs";
+import { join, resolve } from "path";
+
+const CONTEXT_DIR = ".codexa/context";
+
+export function ensureContextDir(): string {
+  const dir = resolve(process.cwd(), CONTEXT_DIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+export function writeContextFile(taskId: number, content: string): string {
+  const dir = ensureContextDir();
+  const filePath = join(dir, `task-${taskId}.md`);
+  Bun.write(filePath, content);
+  return resolve(filePath);
+}
+
+export function getContextFilePath(taskId: number): string {
+  return resolve(process.cwd(), CONTEXT_DIR, `task-${taskId}.md`);
+}
+
+export function cleanupContextFiles(specId: string): void {
+  const dir = resolve(process.cwd(), CONTEXT_DIR);
+  if (!existsSync(dir)) return;
+
+  try {
+    const { readdirSync, unlinkSync } = require("fs");
+    const files = readdirSync(dir) as string[];
+    for (const file of files) {
+      if (file.startsWith("task-") && file.endsWith(".md")) {
+        unlinkSync(join(dir, file));
+      }
+    }
+  } catch {
+    // Non-critical: don't fail if cleanup fails
+  }
+}

package/context/generator.ts

@@ -5,6 +5,8 @@ import type { ContextSection, ContextData } from "./assembly";
 import { assembleSections } from "./assembly";
 import { getAgentDomain, adjustSectionPriorities, domainToScope } from "./domains";
 import { filterRelevantDecisions, filterRelevantStandards } from "./scoring";
+import { computeContextHash, getCachedContextPath, setCachedContext } from "./cache";
+import { writeContextFile } from "./file-writer";
 import {
     buildProductSection,
     buildArchitectureSection,
@@ -131,7 +133,7 @@ function fetchContextData(taskId: number): ContextData | null {
 
     // Decisoes relevantes (max 8, priorizando as que mencionam arquivos da task)
     const allDecisions = db
-        .query("SELECT * FROM decisions WHERE spec_id = ? AND status = 'active' ORDER BY created_at DESC")
+        .query("SELECT * FROM decisions WHERE spec_id = ? AND status = 'active' ORDER BY created_at DESC LIMIT 30")
         .all(task.spec_id) as any[];
     const decisions = filterRelevantDecisions(allDecisions, taskFiles, 8);
 
@@ -237,11 +239,9 @@ function fetchContextData(taskId: number): ContextData | null {
 
 // ── Main Entry Point ──────────────────────────────────────────
 
-export function getContextForSubagent(taskId: number): string {
-    initSchema();
-
+function buildFullContext(taskId: number): { content: string; data: ContextData } | null {
     const data = fetchContextData(taskId);
-    if (!data) return "ERRO: Task nao encontrada";
+    if (!data) return null;
 
     const header = `## CONTEXTO (Task #${data.task.number})
 
@@ -266,9 +266,39 @@ export function getContextForSubagent(taskId: number): string {
         buildHintsSection(data),
     ].filter((s): s is ContextSection => s !== null);
 
-    // v9.4: Domain-based priority adjustment (replaces binary AGENT_SECTIONS)
     const agentDomain = getAgentDomain(data.task.agent);
     const sections = adjustSectionPriorities(allSections, agentDomain);
 
-    return assembleSections(header, sections);
+    return { content: assembleSections(header, sections), data };
+}
+
+export function getContextForSubagent(taskId: number): string {
+    initSchema();
+    const result = buildFullContext(taskId);
+    return result?.content || "ERRO: Task nao encontrada";
+}
+
+// ── v10.0: File-Based Context ─────────────────────────────────
+
+export function generateContextFile(taskId: number): string {
+    initSchema();
+
+    const db = getDb();
+    const task = db.query("SELECT spec_id FROM tasks WHERE id = ?").get(taskId) as any;
+    if (!task) return "";
+
+    // Check cache first
+    const hash = computeContextHash(task.spec_id, taskId);
+    const cached = getCachedContextPath(hash);
+    if (cached) return cached;
+
+    // Generate fresh context
+    const result = buildFullContext(taskId);
+    if (!result) return "";
+
+    // Write to file and cache
+    const filePath = writeContextFile(taskId, result.content);
+    setCachedContext(hash, filePath, task.spec_id);
+
+    return filePath;
 }

package/context/index.ts

@@ -1,5 +1,5 @@
 // Re-exports for backward compatibility
-export { getContextForSubagent, getMinimalContextForSubagent } from "./generator";
+export { getContextForSubagent, getMinimalContextForSubagent, generateContextFile } from "./generator";
 export { assembleSections, MAX_CONTEXT_SIZE } from "./assembly";
 export { AGENT_DOMAIN, DOMAIN_PROFILES, getAgentDomain, adjustSectionPriorities, domainToScope } from "./domains";
 export type { AgentDomain, Relevance, SectionName, DomainProfile } from "./domains";
@@ -25,3 +25,10 @@ export type { ReferenceFile } from "./references";
 export { AGENT_REGISTRY, resolveAgent, resolveAgentName, suggestAgent, buildAgentDomainMap, getAllAgentNames, getCanonicalAgentNames } from "./agent-registry";
 export type { AgentEntry } from "./agent-registry";
 export { loadAgentExpertise, getAgentDescription, findAgentsDir, clearExpertiseCache } from "./agent-expertise";
+// v10.0: Context engineering
+export { computeContextHash, getCachedContextPath, setCachedContext, invalidateCache, clearCache } from "./cache";
+export { writeContextFile, ensureContextDir, getContextFilePath, cleanupContextFiles } from "./file-writer";
+export { getModelForTask, getProfileForDomain, DOMAIN_MODEL_MAP, MODEL_NAMES } from "./model-profiles";
+export type { ModelProfile } from "./model-profiles";
+export { estimateTokens, getContextBudget, formatContextWarning } from "./monitor";
+export type { ContextBudget, WarningLevel, ContentType } from "./monitor";

package/context/model-profiles.ts

@@ -0,0 +1,39 @@
+// ═══════════════════════════════════════════════════════════════
+// MODEL PROFILES (v10.0)
+// Maps agent domains to optimal model tiers.
+// quality = opus (complex, architecture, security)
+// balanced = sonnet (standard implementation)
+// budget = haiku (exploration only — does NOT use Write/Edit)
+// ═══════════════════════════════════════════════════════════════
+
+import type { AgentDomain } from "./domains";
+
+export type ModelProfile = "quality" | "balanced" | "budget";
+
+export const MODEL_NAMES: Record<ModelProfile, string> = {
+  quality: "opus",
+  balanced: "sonnet",
+  budget: "haiku",
+};
+
+export const DOMAIN_MODEL_MAP: Record<AgentDomain, ModelProfile> = {
+  backend: "balanced",
+  frontend: "balanced",
+  database: "quality",
+  testing: "balanced",
+  review: "quality",
+  security: "quality",
+  explore: "budget",
+  architecture: "quality",
+};
+
+export function getModelForTask(agentDomain: AgentDomain | null): string {
+  if (!agentDomain) return MODEL_NAMES.quality;
+  const profile = DOMAIN_MODEL_MAP[agentDomain];
+  return MODEL_NAMES[profile];
+}
+
+export function getProfileForDomain(agentDomain: AgentDomain | null): ModelProfile {
+  if (!agentDomain) return "quality";
+  return DOMAIN_MODEL_MAP[agentDomain];
+}

package/context/monitor.ts

@@ -0,0 +1,106 @@
+// ═══════════════════════════════════════════════════════════════
+// CONTEXT MONITOR (v10.0)
+// Estimates token usage and warns when context budget is high.
+// Thresholds: 65% = caution, 75% = critical
+// ═══════════════════════════════════════════════════════════════
+
+export type WarningLevel = "ok" | "caution" | "critical";
+export type ContentType = "code" | "markdown" | "mixed";
+
+export interface ContextBudget {
+  promptTokens: number;
+  contextFileTokens: number;
+  orchestratorEstimate: number;
+  totalEstimated: number;
+  warningLevel: WarningLevel;
+}
+
+const CAUTION_THRESHOLD = 0.65;
+const CRITICAL_THRESHOLD = 0.75;
+// Claude Code context window practical limit (~200k tokens, but 80% usable)
+const MAX_USABLE_TOKENS = 160_000;
+
+function detectContentType(text: string): ContentType {
+  if (text.length === 0) return "mixed";
+
+  // Count code indicators (braces, semicolons, operators)
+  const codeIndicators = (text.match(/[{}\[\];=()]/g) || []).length;
+  // Count markdown indicators (headers, lists, bold)
+  const markdownIndicators = (text.match(/^#{1,6}\s|^\s*[-*]\s|\*\*/gm) || []).length;
+
+  const codeRatio = codeIndicators / text.length;
+
+  if (codeRatio > 0.03) return "code";
+  if (markdownIndicators > 5 && codeRatio < 0.01) return "markdown";
+  return "mixed";
+}
+
+export function estimateTokens(text: string, contentType?: ContentType): number {
+  const type = contentType || detectContentType(text);
+
+  switch (type) {
+    case "code":
+      // Code has more tokens per character (operators, short identifiers)
+      return Math.ceil(text.length / 3);
+    case "markdown":
+      // Portuguese markdown has longer words, fewer tokens per character
+      return Math.ceil(text.length / 5);
+    default:
+      // Mixed content — conservative estimate
+      return Math.ceil(text.length / 3.5);
+  }
+}
+
+export function getContextBudget(
+  promptText: string,
+  contextFileText: string,
+  taskCount: number,
+  contextFilePath?: string,
+): ContextBudget {
+  const promptTokens = estimateTokens(promptText);
+
+  // Use real file size if path provided
+  let contextFileTokens: number;
+  if (contextFilePath) {
+    try {
+      const realSize = Bun.file(contextFilePath).size;
+      contextFileTokens = Math.ceil(realSize / 3.5);
+    } catch {
+      contextFileTokens = estimateTokens(contextFileText);
+    }
+  } else {
+    contextFileTokens = estimateTokens(contextFileText);
+  }
+
+  // Orchestrator overhead: base + per-task accumulation (conservative)
+  const orchestratorEstimate = 2000 + (taskCount * 1200);
+
+  const totalEstimated = promptTokens + contextFileTokens + orchestratorEstimate;
+  const ratio = totalEstimated / MAX_USABLE_TOKENS;
+
+  let warningLevel: WarningLevel = "ok";
+  if (ratio >= CRITICAL_THRESHOLD) {
+    warningLevel = "critical";
+  } else if (ratio >= CAUTION_THRESHOLD) {
+    warningLevel = "caution";
+  }
+
+  return {
+    promptTokens,
+    contextFileTokens,
+    orchestratorEstimate,
+    totalEstimated,
+    warningLevel,
+  };
+}
+
+export function formatContextWarning(budget: ContextBudget): string | null {
+  if (budget.warningLevel === "ok") return null;
+
+  const pct = Math.round((budget.totalEstimated / MAX_USABLE_TOKENS) * 100);
+
+  if (budget.warningLevel === "critical") {
+    return `[CRITICAL] Contexto estimado em ${pct}% do limite. Considere: --minimal-context ou knowledge compact`;
+  }
+  return `[CAUTION] Contexto estimado em ${pct}% do limite. Monitore o uso.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexa/cli",
-  "version": "9.0.19",
+  "version": "9.0.21",
   "description": "Orchestrated workflow system for Claude Code - manages feature development through parallel subagents with structured phases, gates, and quality enforcement.",
   "type": "module",
   "bin": {

package/protocol/process-return.ts

@@ -164,6 +164,10 @@ export function processSubagentReturn(
       const currentPatterns = context?.patterns ? JSON.parse(context.patterns) : [];
 
       for (const pattern of data.patterns_discovered) {
+        // v10.0: Dedup — skip if pattern text already exists
+        if (currentPatterns.some((p: any) => p.pattern === pattern)) {
+          continue;
+        }
         currentPatterns.push({
           pattern,
           detected_at: now,
@@ -172,6 +176,11 @@ export function processSubagentReturn(
         result.patternsAdded++;
       }
 
+      // v10.0: Cap at 50 patterns (keep most recent)
+      if (currentPatterns.length > 50) {
+        currentPatterns.splice(0, currentPatterns.length - 50);
+      }
+
       db.run(
         "UPDATE context SET patterns = ?, updated_at = ? WHERE spec_id = ?",
         [JSON.stringify(currentPatterns), now, specId]

package/templates/subagent-prompt-lean.md

@@ -0,0 +1,28 @@
+{{agentIdentity}}
+
+## TASK: {{taskName}}
+
+**ARQUIVOS**: {{filesList}}
+**MUDANCA**: {{taskDescription}}
+
+{{contextSummary}}
+
+## CONTEXTO COMPLETO
+
+Leia o arquivo de contexto completo com Read tool (apenas secoes relevantes para sua task):
+  {{contextFile}}
+
+## EXECUTE AGORA
+
+1. Read o arquivo de contexto acima (secoes que precisar)
+2. Read arquivos existentes que precisa modificar
+3. Edit/Write para criar/modificar os arquivos listados
+4. Retorne JSON:
+
+```json
+{"status": "completed", "summary": "...", "files_created": [], "files_modified": [], "reasoning": {"approach": "como abordou (min 20 chars)", "challenges": [], "recommendations": "para proximas tasks"}, "knowledge_to_broadcast": [], "decisions_made": []}
+```
+
+**REGRA**: Se retornar sem usar Edit/Write = FALHA.
+
+{{agentExpertise}}

package/workflow.ts

@@ -254,9 +254,10 @@ taskCmd
   .description("Inicia task(s) - pode ser multiplas separadas por virgula")
   .option("--json", "Saida em JSON")
   .option("--minimal-context", "Usar contexto reduzido (2KB) em vez do completo (16KB)")
+  .option("--inline-context", "Incluir contexto inline no JSON (modo legado, 16KB)")
   .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action(wrapAction((ids: string, options) => {
-    taskStart(ids, options.json, options.minimalContext, options.spec);
+    taskStart(ids, options.json, options.minimalContext, options.spec, options.inlineContext);
   }));
 
 taskCmd
@@ -498,6 +499,47 @@ contextCmd
     contextDetail(section, opts.json, opts.spec);
   });
 
+contextCmd
+  .command("budget")
+  .description("Mostra estimativa de uso de contexto para uma task")
+  .option("--task <id>", "ID da task")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action(wrapAction((options: { task?: string; spec?: string }) => {
+    const { getContextForSubagent, getMinimalContextForSubagent } = require("./context/generator");
+    const { getContextBudget, formatContextWarning } = require("./context/monitor");
+    const { getDb } = require("./db/connection");
+    const { initSchema } = require("./db/schema");
+    initSchema();
+    const db = getDb();
+
+    const taskId = options.task ? parseInt(options.task) : null;
+    if (!taskId) {
+      console.log("Use --task <id> para especificar a task.");
+      return;
+    }
+
+    const fullCtx = getContextForSubagent(taskId);
+    const minCtx = getMinimalContextForSubagent(taskId);
+
+    const task = db.query("SELECT spec_id FROM tasks WHERE id = ?").get(taskId) as any;
+    const completedCount = task ? (db.query(
+      "SELECT COUNT(*) as c FROM tasks WHERE spec_id = ? AND status = 'done'"
+    ).get(task.spec_id) as any)?.c || 0 : 0;
+
+    const budget = getContextBudget(minCtx, fullCtx, completedCount);
+    const warning = formatContextWarning(budget);
+
+    console.log(`\nContext Budget (Task #${taskId}):`);
+    console.log(`${"─".repeat(40)}`);
+    console.log(`  Prompt (lean):     ~${budget.promptTokens} tokens`);
+    console.log(`  Context file:      ~${budget.contextFileTokens} tokens`);
+    console.log(`  Orchestrator est.: ~${budget.orchestratorEstimate} tokens`);
+    console.log(`  Total estimado:    ~${budget.totalEstimated} tokens`);
+    console.log(`  Warning level:     ${budget.warningLevel}`);
+    if (warning) console.log(`\n  ${warning}`);
+    console.log();
+  }));
+
 // Manter compatibilidade: context sem subcomando = export
 program
   .command("ctx")