@codexa/cli 9.0.5 → 9.0.7

package/context/assembly.ts

@@ -0,0 +1,82 @@
+// v8.3: Limite maximo de contexto para subagents (16KB)
+export const MAX_CONTEXT_SIZE = 16384;
+
+export interface ContextSection {
+    name: string;
+    content: string;
+    priority: number; // Lower = kept during truncation
+}
+
+export interface ContextData {
+    db: any;
+    task: any;
+    spec: any;
+    context: any;
+    project: any;
+    taskFiles: string[];
+    domain: string;
+    archAnalysis: any;
+    decisions: any[];
+    allDecisions: any[];
+    relevantStandards: any[];
+    criticalKnowledge: any[];
+    truncatedCritical: number;
+    infoKnowledge: any[];
+    truncatedInfo: number;
+    productContext: any;
+    patterns: any[];
+    depReasoning: any[];
+    libContexts: any[];
+    graphDecisions: any[];
+    discoveredPatterns: any[];
+}
+
+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);
+
+    let output = header;
+    for (const section of sorted) {
+        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"}}
+\`\`\`
+`;
+
+    // v8.3: Overall size cap com truncamento inteligente por secao
+    if (output.length > MAX_CONTEXT_SIZE) {
+        const parts = output.split('\n### ');
+        let trimmed = parts[0]; // Sempre manter header
+
+        for (let i = 1; i < parts.length; i++) {
+            const candidate = trimmed + '\n### ' + parts[i];
+            if (candidate.length > MAX_CONTEXT_SIZE - 200) {
+                break;
+            }
+            trimmed = candidate;
+        }
+
+        const omittedSections = parts.length - trimmed.split('\n### ').length;
+        if (omittedSections > 0) {
+            trimmed += `\n\n[CONTEXTO TRUNCADO: ${omittedSections} secao(oes) omitida(s) por limite de ${MAX_CONTEXT_SIZE} chars. Use: context-export para contexto completo]`;
+        }
+
+        output = trimmed;
+    }
+
+    return output;
+}
+
+// v9.3: Secoes relevantes por tipo de agente.
+// Agentes nao listados recebem TODAS as secoes (comportamento atual).
+export const AGENT_SECTIONS: Record<string, string[]> = {
+  "testing-unit":          ["STANDARDS", "DECISOES", "ALERTAS", "PATTERNS", "UTILITIES", "HINTS"],
+  "deep-explore":          ["STACK", "ARQUITETURA"],
+  "security-specialist":   ["STANDARDS", "DECISOES", "ALERTAS", "STACK", "HINTS"],
+  "expert-code-reviewer":  ["STANDARDS", "DECISOES", "ARQUITETURA", "UTILITIES", "ALERTAS", "HINTS"],
+};

package/context/generator.ts

@@ -0,0 +1,273 @@
+import { getDb } from "../db/connection";
+import { initSchema, getPatternsForFiles, getRelatedDecisions, getArchitecturalAnalysisForSpec } from "../db/schema";
+import { getKnowledgeForTask } from "../commands/knowledge";
+import type { ContextSection, ContextData } from "./assembly";
+import { assembleSections, AGENT_SECTIONS } from "./assembly";
+import { filterRelevantDecisions, filterRelevantStandards } from "./scoring";
+import {
+    buildProductSection,
+    buildArchitectureSection,
+    buildStandardsSection,
+    buildDecisionsSection,
+    buildReasoningSection,
+    buildAlertsSection,
+    buildDiscoveriesSection,
+    buildPatternsSection,
+    buildUtilitiesSection,
+    buildGraphSection,
+    buildStackSection,
+    buildHintsSection,
+} from "./sections";
+
+// v9.0: Contexto minimo para subagent (max ~2KB)
+const MAX_MINIMAL_CONTEXT = 2048;
+
+export function getMinimalContextForSubagent(taskId: number): string {
+    initSchema();
+    const db = getDb();
+
+    const task = db.query("SELECT * FROM tasks WHERE id = ?").get(taskId) as any;
+    if (!task) return "ERRO: Task nao encontrada";
+
+    const spec = db.query("SELECT * FROM specs WHERE id = ?").get(task.spec_id) as any;
+    const context = db.query("SELECT * FROM context WHERE spec_id = ?").get(task.spec_id) as any;
+
+    const taskFiles = task.files ? JSON.parse(task.files) : [];
+    const domain = task.agent?.split("-")[0] || "all";
+
+    // 1. Standards REQUIRED apenas (nao recommended)
+    const requiredStandards = db.query(
+        `SELECT rule FROM standards
+         WHERE enforcement = 'required' AND (scope = 'all' OR scope = ?)
+         LIMIT 10`
+    ).all(domain) as any[];
+
+    // 2. Blockers CRITICAL apenas
+    const criticalBlockers = db.query(
+        `SELECT content FROM knowledge
+         WHERE spec_id = ? AND severity = 'critical'
+         ORDER BY created_at DESC LIMIT 5`
+    ).all(task.spec_id) as any[];
+
+    // 3. Decisoes da task anterior (dependency direta)
+    const dependsOn = task.depends_on ? JSON.parse(task.depends_on) : [];
+    let depDecisions: any[] = [];
+    if (dependsOn.length > 0) {
+        const placeholders = dependsOn.map(() => '?').join(',');
+        const depTasks = db.query(
+            `SELECT id FROM tasks WHERE spec_id = ? AND number IN (${placeholders})`
+        ).all(task.spec_id, ...dependsOn) as any[];
+
+        for (const dt of depTasks) {
+            const reasoning = db.query(
+                `SELECT thought FROM reasoning_log
+                 WHERE spec_id = ? AND task_id = ? AND category = 'recommendation'
+                 ORDER BY created_at DESC LIMIT 2`
+            ).all(task.spec_id, dt.id) as any[];
+            depDecisions.push(...reasoning);
+        }
+    }
+
+    // Montar output minimo
+    let output = `## CONTEXTO MINIMO (Task #${task.number})
+
+**Feature:** ${spec.name}
+**Objetivo:** ${context?.objective || "N/A"}
+**Arquivos:** ${taskFiles.join(", ") || "Nenhum especificado"}
+`;
+
+    if (requiredStandards.length > 0) {
+        output += `\n**Standards (OBRIGATORIOS):**\n${requiredStandards.map((s: any) => `- ${s.rule}`).join("\n")}\n`;
+    }
+
+    if (criticalBlockers.length > 0) {
+        output += `\n**BLOCKERS CRITICOS:**\n${criticalBlockers.map((b: any) => `[X] ${b.content}`).join("\n")}\n`;
+    }
+
+    if (depDecisions.length > 0) {
+        output += `\n**Recomendacoes de tasks anteriores:**\n${depDecisions.map((d: any) => `- ${d.thought}`).join("\n")}\n`;
+    }
+
+    output += `
+**Contexto expandido**: Se precisar de mais contexto, execute:
+  codexa context detail standards    # Todos os standards
+  codexa context detail decisions    # Todas as decisoes
+  codexa context detail patterns     # Patterns do projeto
+  codexa context detail knowledge    # Knowledge completo
+  codexa context detail architecture # Analise arquitetural
+`;
+
+    // Truncar se exceder limite
+    if (output.length > MAX_MINIMAL_CONTEXT) {
+        output = output.substring(0, MAX_MINIMAL_CONTEXT - 100) + "\n\n[CONTEXTO TRUNCADO - use: codexa context detail <secao>]\n";
+    }
+
+    return output;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// CONTEXT BUILDER (v9.0 — decomposed from v8.1 monolith)
+// ═══════════════════════════════════════════════════════════════
+
+function fetchContextData(taskId: number): ContextData | null {
+    const db = getDb();
+
+    const task = db.query("SELECT * FROM tasks WHERE id = ?").get(taskId) as any;
+    if (!task) return null;
+
+    const spec = db.query("SELECT * FROM specs WHERE id = ?").get(task.spec_id) as any;
+    const context = db.query("SELECT * FROM context WHERE spec_id = ?").get(task.spec_id) as any;
+    const project = db.query("SELECT * FROM project WHERE id = 'default'").get() as any;
+
+    // v8.4: Analise arquitetural (link explicito via analysis_id ou nome)
+    const archAnalysis = getArchitecturalAnalysisForSpec(spec.name, task.spec_id);
+
+    // Arquivos da task para filtrar contexto relevante
+    const taskFiles = task.files ? JSON.parse(task.files) : [];
+    const domain = task.agent?.split("-")[0] || "all";
+
+    // 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")
+        .all(task.spec_id) as any[];
+    const decisions = filterRelevantDecisions(allDecisions, taskFiles, 8);
+
+    // Standards required + recommended que se aplicam aos arquivos
+    const standards = db
+        .query(
+            `SELECT * FROM standards
+       WHERE (scope = 'all' OR scope = ?)
+       ORDER BY enforcement DESC, category`
+        )
+        .all(domain) as any[];
+    const relevantStandards = filterRelevantStandards(standards, taskFiles);
+
+    // Knowledge com caps e indicadores de truncamento
+    const allKnowledge = getKnowledgeForTask(task.spec_id, taskId);
+    const allCriticalKnowledge = allKnowledge.filter((k: any) => k.severity === 'critical' || k.severity === 'warning');
+    const criticalKnowledge = allCriticalKnowledge.slice(0, 20);
+    const truncatedCritical = allCriticalKnowledge.length - criticalKnowledge.length;
+    const allInfoKnowledge = allKnowledge.filter((k: any) => k.severity === 'info');
+    const infoKnowledge = allInfoKnowledge.slice(0, 10);
+    const truncatedInfo = allInfoKnowledge.length - infoKnowledge.length;
+
+    const productContext = db.query("SELECT * FROM product_context WHERE id = 'default'").get() as any;
+    const patterns = getPatternsForFiles(taskFiles);
+
+    // v8.2: Reasoning de tasks dependentes + todas tasks completas recentes
+    const dependsOn = task.depends_on ? JSON.parse(task.depends_on) : [];
+    const depReasoning: any[] = [];
+    const seenTaskIds = new Set<number>();
+
+    if (dependsOn.length > 0) {
+        const placeholders = dependsOn.map(() => '?').join(',');
+        const depTasks = db.query(
+            `SELECT id, number FROM tasks WHERE spec_id = ? AND number IN (${placeholders})`
+        ).all(task.spec_id, ...dependsOn) as any[];
+
+        for (const depTask of depTasks) {
+            seenTaskIds.add(depTask.id);
+            const reasoning = db.query(
+                `SELECT category, thought FROM reasoning_log
+                 WHERE spec_id = ? AND task_id = ?
+                 AND category IN ('recommendation', 'decision', 'challenge')
+                 ORDER BY
+                   CASE importance WHEN 'critical' THEN 1 WHEN 'high' THEN 2 ELSE 3 END,
+                   created_at DESC
+                 LIMIT 3`
+            ).all(task.spec_id, depTask.id) as any[];
+            for (const r of reasoning) {
+                depReasoning.push({ ...r, fromTask: depTask.number });
+            }
+        }
+    }
+
+    const completedTasks = db.query(
+        `SELECT t.id, t.number FROM tasks t
+         WHERE t.spec_id = ? AND t.status = 'done' AND t.id != ?
+         ORDER BY t.completed_at DESC LIMIT 10`
+    ).all(task.spec_id, taskId) as any[];
+
+    for (const ct of completedTasks) {
+        if (seenTaskIds.has(ct.id)) continue;
+        const reasoning = db.query(
+            `SELECT category, thought FROM reasoning_log
+             WHERE spec_id = ? AND task_id = ?
+             AND category IN ('recommendation', 'challenge')
+             AND importance IN ('critical', 'high')
+             ORDER BY
+               CASE importance WHEN 'critical' THEN 1 ELSE 2 END,
+               created_at DESC
+             LIMIT 2`
+        ).all(task.spec_id, ct.id) as any[];
+        for (const r of reasoning) {
+            depReasoning.push({ ...r, fromTask: ct.number });
+        }
+    }
+
+    const libContexts = db.query(
+        "SELECT lib_name, version FROM lib_contexts ORDER BY lib_name LIMIT 10"
+    ).all() as any[];
+
+    const graphDecisions: any[] = [];
+    for (const file of taskFiles) {
+        try {
+            const related = getRelatedDecisions(file, "file");
+            for (const d of related) {
+                if (!graphDecisions.find((gd: any) => gd.id === d.id)) {
+                    graphDecisions.push(d);
+                }
+            }
+        } catch { /* ignore if graph empty */ }
+    }
+
+    const discoveredPatterns = context?.patterns ? JSON.parse(context.patterns) : [];
+
+    return {
+        db, task, spec, context, project, taskFiles, domain, archAnalysis,
+        decisions, allDecisions, relevantStandards,
+        criticalKnowledge, truncatedCritical, infoKnowledge, truncatedInfo,
+        productContext, patterns, depReasoning, libContexts,
+        graphDecisions, discoveredPatterns,
+    };
+}
+
+// ── Main Entry Point ──────────────────────────────────────────
+
+export function getContextForSubagent(taskId: number): string {
+    initSchema();
+
+    const data = fetchContextData(taskId);
+    if (!data) return "ERRO: Task nao encontrada";
+
+    const header = `## CONTEXTO (Task #${data.task.number})
+
+**Feature:** ${data.spec.name}
+**Objetivo:** ${data.context?.objective || "N/A"}
+**Arquivos:** ${data.taskFiles.join(", ") || "Nenhum especificado"}
+`;
+
+    const allSections = [
+        buildProductSection(data),
+        buildArchitectureSection(data),
+        buildStandardsSection(data),
+        buildDecisionsSection(data),
+        buildReasoningSection(data),
+        buildAlertsSection(data),
+        buildDiscoveriesSection(data),
+        buildPatternsSection(data),
+        buildUtilitiesSection(data),
+        buildGraphSection(data),
+        buildStackSection(data),
+        buildHintsSection(data),
+    ].filter((s): s is ContextSection => s !== null);
+
+    // v9.3: Filtrar secoes por tipo de agente
+    const agentType = data.task.agent || "";
+    const allowedSections = AGENT_SECTIONS[agentType];
+    const sections = allowedSections
+        ? allSections.filter(s => allowedSections.includes(s.name))
+        : allSections;
+
+    return assembleSections(header, sections);
+}

package/context/index.ts

@@ -0,0 +1,19 @@
+// Re-exports for backward compatibility
+export { getContextForSubagent, getMinimalContextForSubagent } from "./generator";
+export { assembleSections, MAX_CONTEXT_SIZE, AGENT_SECTIONS } from "./assembly";
+export type { ContextSection, ContextData } from "./assembly";
+export { filterRelevantDecisions, filterRelevantStandards } from "./scoring";
+export {
+    buildProductSection,
+    buildArchitectureSection,
+    buildStandardsSection,
+    buildDecisionsSection,
+    buildReasoningSection,
+    buildAlertsSection,
+    buildDiscoveriesSection,
+    buildPatternsSection,
+    buildUtilitiesSection,
+    buildGraphSection,
+    buildStackSection,
+    buildHintsSection,
+} from "./sections";

package/context/scoring.ts

@@ -0,0 +1,106 @@
+// v8.3: Filtrar decisoes relevantes com scoring melhorado
+export function filterRelevantDecisions(decisions: any[], taskFiles: string[], maxCount: number): any[] {
+    if (decisions.length === 0) return [];
+    if (taskFiles.length === 0) return decisions.slice(0, maxCount);
+
+    // Extrair keywords semanticas dos arquivos da task
+    const fileExtensions = new Set(taskFiles.map(f => f.split('.').pop()?.toLowerCase()).filter(Boolean));
+    const fileDirs = new Set(taskFiles.flatMap(f => f.split('/').slice(0, -1)).filter(Boolean));
+
+    // Keywords de dominio para scoring contextual
+    const domainKeywords: Record<string, string[]> = {
+        frontend: ['component', 'page', 'layout', 'css', 'style', 'ui', 'react', 'next', 'hook'],
+        backend: ['api', 'route', 'handler', 'middleware', 'server', 'endpoint', 'controller'],
+        database: ['schema', 'migration', 'query', 'table', 'index', 'sql', 'model'],
+        testing: ['test', 'spec', 'mock', 'fixture', 'assert', 'jest', 'vitest'],
+    };
+
+    const scored = decisions.map((d) => {
+        let score = 0;
+        const combined = `${d.decision || ''} ${d.title || ''} ${d.rationale || ''}`.toLowerCase();
+
+        // Arquivo exato e diretorio (+10/+5)
+        for (const file of taskFiles) {
+            const fileName = file.split("/").pop() || file;
+            const dirName = file.split("/").slice(-2, -1)[0] || "";
+
+            if (combined.includes(fileName.toLowerCase())) score += 10;
+            if (dirName && combined.includes(dirName.toLowerCase())) score += 5;
+        }
+
+        // v8.3: Extensao dos arquivos (+3)
+        for (const ext of fileExtensions) {
+            if (combined.includes(`.${ext}`)) { score += 3; break; }
+        }
+
+        // v8.3: Diretorio mencionado (+4)
+        for (const dir of fileDirs) {
+            if (combined.includes(dir.toLowerCase())) { score += 4; break; }
+        }
+
+        // v8.3: Keywords de dominio (+2)
+        const taskCombined = taskFiles.join(' ').toLowerCase();
+        for (const [, keywords] of Object.entries(domainKeywords)) {
+            for (const kw of keywords) {
+                if (combined.includes(kw) && taskCombined.includes(kw)) {
+                    score += 2;
+                    break;
+                }
+            }
+        }
+
+        // Recencia (+3/+1)
+        const age = Date.now() - new Date(d.created_at).getTime();
+        const hoursOld = age / (1000 * 60 * 60);
+        if (hoursOld < 1) score += 3;
+        else if (hoursOld < 24) score += 1;
+
+        return { ...d, _relevanceScore: score };
+    });
+
+    return scored
+        .sort((a, b) => b._relevanceScore - a._relevanceScore)
+        .slice(0, maxCount)
+        .map(({ _relevanceScore, ...d }) => d);
+}
+
+// v8.0: Filtrar standards relevantes para os arquivos da task
+export function filterRelevantStandards(standards: any[], taskFiles: string[]): any[] {
+    if (standards.length === 0) return [];
+    if (taskFiles.length === 0) return standards;
+
+    // Extrair extensoes e diretorios dos arquivos da task
+    const extensions = new Set(taskFiles.map((f) => {
+        const ext = f.split(".").pop();
+        return ext ? `.${ext}` : "";
+    }).filter(Boolean));
+
+    const directories = new Set(taskFiles.map((f) => {
+        const parts = f.split("/");
+        return parts.length > 1 ? parts.slice(0, -1).join("/") : "";
+    }).filter(Boolean));
+
+    // Filtrar standards que se aplicam
+    return standards.filter((s) => {
+        // Standards de naming sempre aplicam
+        if (s.category === "naming") return true;
+
+        // Standards de code aplicam se mencionam extensao dos arquivos
+        if (s.category === "code") {
+            for (const ext of extensions) {
+                if (s.rule?.includes(ext) || s.scope === "all") return true;
+            }
+        }
+
+        // Standards de structure aplicam se mencionam diretorio
+        if (s.category === "structure") {
+            for (const dir of directories) {
+                if (s.rule?.includes(dir)) return true;
+            }
+            return s.scope === "all";
+        }
+
+        // Outros standards: incluir se scope combina
+        return true;
+    });
+}

package/context/sections.ts

@@ -0,0 +1,246 @@
+import { getUtilitiesForContext, getAgentHints } from "../db/schema";
+import type { ContextSection, ContextData } from "./assembly";
+
+// ── Section Builders ──────────────────────────────────────────
+
+export function buildProductSection(data: ContextData): ContextSection | null {
+    if (!data.productContext) return null;
+
+    let content = `
+### PRODUTO
+- **Problema:** ${data.productContext.problem || "N/A"}
+- **Usuarios:** ${data.productContext.target_users || "N/A"}`;
+    if (data.productContext.constraints) {
+        try {
+            const constraints = JSON.parse(data.productContext.constraints);
+            if (constraints.length > 0) {
+                content += `\n- **Restricoes:** ${constraints.slice(0, 3).join("; ")}${constraints.length > 3 ? ` [+${constraints.length - 3} mais]` : ''}`;
+            }
+        } catch { /* ignore parse errors */ }
+    }
+    content += "\n";
+
+    return { name: "PRODUTO", content, priority: 7 };
+}
+
+export function buildArchitectureSection(data: ContextData): ContextSection | null {
+    if (!data.archAnalysis) return null;
+
+    let content = `
+### ARQUITETURA (${data.archAnalysis.id})`;
+    if (data.archAnalysis.approach) {
+        const approachPreview = data.archAnalysis.approach.length > 500
+            ? data.archAnalysis.approach.substring(0, 500) + "..."
+            : data.archAnalysis.approach;
+        content += `\n**Abordagem:** ${approachPreview}`;
+    }
+    if (data.archAnalysis.risks) {
+        try {
+            const risks = JSON.parse(data.archAnalysis.risks);
+            if (risks.length > 0) {
+                const highRisks = risks.filter((r: any) => r.impact === 'high' || r.probability === 'high');
+                const risksToShow = highRisks.length > 0 ? highRisks.slice(0, 3) : risks.slice(0, 3);
+                content += `\n**Riscos:**`;
+                for (const r of risksToShow) {
+                    content += `\n  - ${r.description} (${r.probability}/${r.impact}) -> ${r.mitigation}`;
+                }
+                if (risks.length > risksToShow.length) {
+                    content += `\n  [+${risks.length - risksToShow.length} mais riscos]`;
+                }
+            }
+        } catch { /* ignore */ }
+    }
+    if (data.archAnalysis.decisions) {
+        try {
+            const archDecisions = JSON.parse(data.archAnalysis.decisions);
+            if (archDecisions.length > 0) {
+                content += `\n**Decisoes arquiteturais:**`;
+                for (const d of archDecisions.slice(0, 5)) {
+                    content += `\n  - ${d.decision}: ${d.rationale || ''}`;
+                }
+                if (archDecisions.length > 5) {
+                    content += `\n  [+${archDecisions.length - 5} mais]`;
+                }
+            }
+        } catch { /* ignore */ }
+    }
+    content += "\n";
+
+    return { name: "ARQUITETURA", content, priority: 3 };
+}
+
+export function buildStandardsSection(data: ContextData): ContextSection {
+    const requiredStds = data.relevantStandards.filter((s: any) => s.enforcement === 'required');
+    const recommendedStds = data.relevantStandards.filter((s: any) => s.enforcement === 'recommended');
+
+    let content = `
+### STANDARDS (${data.relevantStandards.length})`;
+    if (requiredStds.length > 0) {
+        content += `\n**Obrigatorios:**\n${requiredStds.map((s: any) => `- ${s.rule}`).join("\n")}`;
+    }
+    if (recommendedStds.length > 0) {
+        content += `\n**Recomendados:**\n${recommendedStds.map((s: any) => `- ${s.rule}`).join("\n")}`;
+    }
+    if (data.relevantStandards.length === 0) {
+        content += "\nNenhum standard aplicavel";
+    }
+    content += "\n";
+
+    return { name: "STANDARDS", content, priority: 1 };
+}
+
+export function buildDecisionsSection(data: ContextData): ContextSection {
+    const truncatedDecisions = data.allDecisions.length - data.decisions.length;
+    const content = `
+### DECISOES (${data.decisions.length}${truncatedDecisions > 0 ? ` [+${truncatedDecisions} mais - use: decisions list]` : ''})
+${data.decisions.length > 0 ? data.decisions.map((d) => `- **${d.title}**: ${d.decision}`).join("\n") : "Nenhuma"}
+`;
+    return { name: "DECISOES", content, priority: 4 };
+}
+
+export function buildReasoningSection(data: ContextData): ContextSection | null {
+    if (data.depReasoning.length === 0) return null;
+
+    const content = `
+### CONTEXTO DE TASKS ANTERIORES
+${data.depReasoning.map((r: any) => `- [Task #${r.fromTask}/${r.category}] ${r.thought}`).join("\n")}
+`;
+    return { name: "CONTEXTO DE TASKS ANTERIORES", content, priority: 5 };
+}
+
+export function buildAlertsSection(data: ContextData): ContextSection | null {
+    if (data.criticalKnowledge.length === 0) return null;
+
+    const severityIcon: Record<string, string> = { warning: "!!", critical: "XX" };
+    const content = `
+### ALERTAS (${data.criticalKnowledge.length}${data.truncatedCritical > 0 ? ` [+${data.truncatedCritical} mais - use: knowledge list --severity warning]` : ''})
+${data.criticalKnowledge.map((k: any) => `[${severityIcon[k.severity] || "!"}] ${k.content}`).join("\n")}
+`;
+    return { name: "ALERTAS", content, priority: 2 };
+}
+
+export function buildDiscoveriesSection(data: ContextData): ContextSection | null {
+    if (data.infoKnowledge.length === 0) return null;
+
+    const content = `
+### DISCOVERIES DE TASKS ANTERIORES (${data.infoKnowledge.length}${data.truncatedInfo > 0 ? ` [+${data.truncatedInfo} mais - use: knowledge list]` : ''})
+${data.infoKnowledge.map((k: any) => `- ${k.content}`).join("\n")}
+`;
+    return { name: "DISCOVERIES", content, priority: 8 };
+}
+
+export function buildPatternsSection(data: ContextData): ContextSection | null {
+    let content = "";
+
+    if (data.patterns.length > 0) {
+        content += `
+### PATTERNS DO PROJETO (${data.patterns.length})
+${data.patterns.map((p: any) => {
+    const tmpl = p.template || "";
+    const preview = tmpl.length > 200 ? tmpl.substring(0, 200) + `... [truncado de ${tmpl.length} chars]` : tmpl;
+    return `- **${p.name}** (${p.category}): ${preview || p.description || "Sem template"}`;
+}).join("\n")}
+`;
+    }
+
+    if (data.discoveredPatterns.length > 0) {
+        const patternsToShow = data.discoveredPatterns.slice(-10);
+        content += `
+### PATTERNS DESCOBERTOS (${data.discoveredPatterns.length})
+${data.discoveredPatterns.length > 10 ? `[mostrando ultimos 10 de ${data.discoveredPatterns.length}]\n` : ''}${patternsToShow.map((p: any) => `- ${p.pattern}${p.source_task ? ` (Task #${p.source_task})` : ""}`).join("\n")}
+`;
+    }
+
+    if (!content) return null;
+    return { name: "PATTERNS", content, priority: 9 };
+}
+
+export function buildUtilitiesSection(data: ContextData): ContextSection | null {
+    try {
+        const taskDirs = [...new Set(data.taskFiles.map((f: string) => {
+            const parts = f.replace(/\\/g, "/").split("/");
+            return parts.slice(0, -1).join("/");
+        }).filter(Boolean))];
+
+        const agentScope = data.task.agent?.split("-")[0] || undefined;
+        let relevantUtilities = getUtilitiesForContext(taskDirs, undefined, 15);
+
+        if (relevantUtilities.length < 5 && agentScope) {
+            const scopeUtils = getUtilitiesForContext([], agentScope, 15);
+            const existingKeys = new Set(relevantUtilities.map((u: any) => `${u.file_path}:${u.utility_name}`));
+            for (const u of scopeUtils) {
+                if (!existingKeys.has(`${u.file_path}:${u.utility_name}`)) {
+                    relevantUtilities.push(u);
+                }
+                if (relevantUtilities.length >= 15) break;
+            }
+        }
+
+        if (relevantUtilities.length === 0) return null;
+
+        const totalCount = (data.db.query("SELECT COUNT(*) as c FROM project_utilities").get() as any)?.c || 0;
+        const truncated = totalCount - relevantUtilities.length;
+        const content = `
+### UTILITIES EXISTENTES (${relevantUtilities.length}${truncated > 0 ? ` [+${truncated} mais]` : ''})
+**REGRA DRY**: Reutilize ao inves de recriar. Importe do arquivo existente.
+${relevantUtilities.map((u: any) => {
+    const sig = u.signature ? ` ${u.signature}` : '';
+    return `- **${u.utility_name}** [${u.utility_type}]${sig} <- \`${u.file_path}\``;
+}).join("\n")}
+`;
+        return { name: "UTILITIES", content, priority: 8 };
+    } catch { /* tabela pode nao existir ainda */ }
+    return null;
+}
+
+export function buildGraphSection(data: ContextData): ContextSection | null {
+    let content = "";
+
+    if (data.graphDecisions.length > 0) {
+        content += `
+### DECISOES QUE AFETAM SEUS ARQUIVOS (${data.graphDecisions.length})
+${data.graphDecisions.map((d: any) => `- **${d.title}**: ${d.decision}`).join("\n")}
+`;
+    }
+
+    if (!content) return null;
+    return { name: "GRAPH", content, priority: 6 };
+}
+
+export function buildStackSection(data: ContextData): ContextSection | null {
+    let content = "";
+
+    if (data.project) {
+        const stack = JSON.parse(data.project.stack);
+        const allStackEntries = Object.entries(stack);
+        const mainStack = allStackEntries.slice(0, 6);
+        content += `
+### STACK
+${mainStack.map(([k, v]) => `${k}: ${v}`).join(" | ")}${allStackEntries.length > 6 ? ` [+${allStackEntries.length - 6} mais]` : ''}
+`;
+    }
+
+    if (data.libContexts.length > 0) {
+        content += `
+### BIBLIOTECAS
+${data.libContexts.map((l: any) => `- ${l.lib_name}${l.version ? ` v${l.version}` : ""}`).join("\n")}
+`;
+    }
+
+    if (!content) return null;
+    return { name: "STACK", content, priority: 11 };
+}
+
+export function buildHintsSection(data: ContextData): ContextSection | null {
+    const agentType = data.task.agent;
+    if (!agentType) return null;
+
+    const hints = getAgentHints(agentType);
+    if (hints.length === 0) return null;
+
+    const content = `
+### HISTORICO DO AGENTE (${agentType})
+${hints.map(h => `- ${h}`).join("\n")}
+`;
+    return { name: "HINTS", content, priority: 10 };
+}

package/errors.ts

@@ -0,0 +1,59 @@
+/**
+ * Codexa error hierarchy.
+ * Thrown instead of process.exit() on critical paths.
+ * Caught by wrapAction() in workflow.ts which prints the message and exits.
+ */
+
+export class CodexaError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, exitCode: number = 1) {
+    super(message);
+    this.name = "CodexaError";
+    this.exitCode = exitCode;
+  }
+}
+
+export interface RecoverySuggestion {
+  diagnostic: string;
+  steps: string[];
+  command?: string;
+}
+
+export class GateError extends CodexaError {
+  readonly gateName: string;
+  readonly resolution: string;
+  readonly recovery?: RecoverySuggestion;
+
+  constructor(reason: string, resolution: string, gateName?: string, recovery?: RecoverySuggestion) {
+    super(`BLOQUEADO: ${reason}\nResolva: ${resolution}`);
+    this.name = "GateError";
+    this.gateName = gateName || "";
+    this.resolution = resolution;
+    this.recovery = recovery;
+  }
+}
+
+export class ValidationError extends CodexaError {
+  constructor(message: string) {
+    super(message, 2);
+    this.name = "ValidationError";
+  }
+}
+
+export class TaskStateError extends CodexaError {
+  constructor(message: string) {
+    super(message, 2);
+    this.name = "TaskStateError";
+  }
+}
+
+export class KnowledgeBlockError extends CodexaError {
+  readonly unackedItems: any[];
+
+  constructor(message: string, unackedItems: any[]) {
+    super(message);
+    this.name = "KnowledgeBlockError";
+    this.unackedItems = unackedItems;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexa/cli",
-  "version": "9.0.5",
+  "version": "9.0.7",
   "description": "Orchestrated workflow system for Claude Code - manages feature development through parallel subagents with structured phases, gates, and quality enforcement.",
   "type": "module",
   "bin": {
@@ -8,11 +8,14 @@
   },
   "files": [
     "workflow.ts",
+    "errors.ts",
     "commands/",
+    "context/",
     "db/",
     "gates/",
     "protocol/",
-    "detectors/"
+    "detectors/",
+    "templates/"
   ],
   "scripts": {
     "cli": "bun run workflow.ts",

package/templates/loader.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+
+const TEMPLATES_DIR = join(dirname(import.meta.path), ".");
+
+const templateCache = new Map<string, string>();
+
+export function loadTemplate(name: string, vars: Record<string, string> = {}): string {
+  let content = templateCache.get(name);
+  if (!content) {
+    const filePath = join(TEMPLATES_DIR, `${name}.md`);
+    content = readFileSync(filePath, "utf-8");
+    templateCache.set(name, content);
+  }
+
+  let result = content;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+
+  return result.trim();
+}

package/templates/subagent-context.md

@@ -0,0 +1,34 @@
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  DIRETIVA CRITICA: USE Write/Edit PARA CRIAR OS ARQUIVOS                     ║
+║  NAO descreva. NAO planeje. NAO simule. EXECUTE AGORA.                       ║
+║  Se retornar sem usar Write/Edit, a task FALHA.                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+
+ARQUIVOS QUE VOCE DEVE CRIAR (use Write para cada um):
+{{filesList}}
+
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  POLLING OBRIGATORIO: Verifique blockers a cada 3 arquivos modificados       ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+
+ANTES de criar o 4o, 7o, 10o arquivo (a cada 3), execute:
+  codexa knowledge list --severity critical --unread
+
+Se retornar QUALQUER blocker:
+1. PARE imediatamente
+2. Retorne com status "blocked" e inclua o blocker encontrado
+3. NAO continue criando arquivos apos encontrar blocker
+
+CHECKLIST OBRIGATORIO (verifique ANTES de retornar):
+- [ ] Usei Write ou Edit para criar/modificar arquivos?
+- [ ] Verifiquei blockers a cada 3 arquivos?
+- [ ] Os arquivos que vou listar em files_created EXISTEM no disco?
+
+Se nao marcou todos os items, PARE e corrija AGORA.
+
+CONTEXTO ON-DEMAND: Se precisar de mais contexto alem do fornecido, execute:
+  codexa context detail standards    # Regras do projeto
+  codexa context detail decisions    # Decisoes tomadas
+  codexa context detail patterns     # Patterns de codigo
+  codexa context detail knowledge    # Discoveries de outras tasks
+NAO execute todos - apenas o que for NECESSARIO para sua task.

package/templates/subagent-return-protocol.md

@@ -0,0 +1,29 @@
+FORMATO DE RETORNO (apos criar os arquivos):
+{
+  "status": "completed | blocked | needs_decision",
+  "summary": "Resumo do que foi feito (10-500 chars)",
+  "files_created": ["path/arquivo.ts"],
+  "files_modified": ["path/outro.ts"],
+  "reasoning": {
+    "approach": "OBRIGATORIO (min 20 chars): Como voce abordou o problema e POR QUE tomou essas decisoes",
+    "challenges": ["Desafios encontrados"],
+    "recommendations": "Sugestoes para proximas tasks"
+  },
+  "patterns_discovered": ["Pattern identificado"],
+  "decisions_made": [{"title": "...", "decision": "..."}],
+  "blockers": ["Se status != completed"],
+  "knowledge_to_broadcast": [{"category": "discovery|pattern|constraint", "content": "...", "severity": "info|warning|critical"}]
+}
+
+ATENCAO: O campo "reasoning.approach" e OBRIGATORIO para status "completed".
+Se retornar sem ele, Gate 4.4 BLOQUEIA a finalizacao da task.
+Descreva COMO abordou o problema, nao apenas O QUE fez.
+
+Se NAO conseguir criar arquivos (sem permissao, sem ferramentas), retorne:
+{
+  "status": "blocked",
+  "blockers": ["Descreva por que nao conseguiu criar os arquivos"]
+}
+
+Veja .claude/agents/PROTOCOL.md para detalhes completos.
+{{patternsNote}}