@codexa/cli 9.0.3 → 9.0.5

package/db/schema.ts

@@ -408,6 +408,57 @@ const MIGRATIONS: Migration[] = [
       db.exec(`ALTER TABLE tasks ADD COLUMN started_at TEXT`);
     },
   },
+  {
+    version: "9.3.0",
+    description: "Criar tabela agent_performance para feedback loop",
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS agent_performance (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          agent_type TEXT NOT NULL,
+          spec_id TEXT NOT NULL,
+          task_id INTEGER NOT NULL,
+          gates_passed_first_try INTEGER DEFAULT 0,
+          gates_total INTEGER DEFAULT 0,
+          bypasses_used INTEGER DEFAULT 0,
+          files_created INTEGER DEFAULT 0,
+          files_modified INTEGER DEFAULT 0,
+          context_size_bytes INTEGER DEFAULT 0,
+          execution_duration_ms INTEGER DEFAULT 0,
+          created_at TEXT DEFAULT CURRENT_TIMESTAMP
+        )
+      `);
+      db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_perf_type ON agent_performance(agent_type)`);
+      db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_perf_created ON agent_performance(created_at)`);
+    },
+  },
+  {
+    version: "9.4.0",
+    description: "Migrar acknowledged_by de JSON para tabela separada",
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS knowledge_acknowledgments (
+          knowledge_id INTEGER NOT NULL REFERENCES knowledge(id) ON DELETE CASCADE,
+          task_id INTEGER NOT NULL,
+          acknowledged_at TEXT DEFAULT CURRENT_TIMESTAMP,
+          PRIMARY KEY (knowledge_id, task_id)
+        )
+      `);
+      db.exec(`CREATE INDEX IF NOT EXISTS idx_ka_task ON knowledge_acknowledgments(task_id)`);
+
+      // Migrar dados existentes do campo JSON
+      const rows = db.query("SELECT id, acknowledged_by FROM knowledge WHERE acknowledged_by IS NOT NULL").all() as any[];
+      const insert = db.prepare("INSERT OR IGNORE INTO knowledge_acknowledgments (knowledge_id, task_id) VALUES (?, ?)");
+      for (const row of rows) {
+        try {
+          const taskIds = JSON.parse(row.acknowledged_by) as number[];
+          for (const taskId of taskIds) {
+            insert.run(row.id, taskId);
+          }
+        } catch { /* JSON invalido, ignorar */ }
+      }
+    },
+  },
 ];
 
 export function runMigrations(): void {
@@ -449,19 +500,13 @@ export function runMigrations(): void {
 // Exportar MIGRATIONS para testes
 export { MIGRATIONS };
 
-// Gera proximo ID de decisao para um spec (DEC-001, DEC-002, ...)
-// Usa MAX() atomico para evitar race condition entre tasks paralelas
+// Gera proximo ID de decisao para um spec
+// Usa timestamp + random hash para eliminar race conditions entre tasks paralelas
 export function getNextDecisionId(specId: string): string {
-  const db = getDb();
-  const result = db
-    .query(
-      `SELECT MAX(CAST(REPLACE(id, 'DEC-', '') AS INTEGER)) as max_num
-       FROM decisions WHERE spec_id = ?`
-    )
-    .get(specId) as any;
-
-  const nextNum = (result?.max_num || 0) + 1;
-  return `DEC-${nextNum.toString().padStart(3, "0")}`;
+  const slug = specId.split("-").slice(1, 3).join("-");
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).substring(2, 6);
+  return `DEC-${slug}-${ts}-${rand}`;
 }
 
 // Claim atomico de task: retorna true se task estava pending e agora esta running.
@@ -754,3 +799,82 @@ export function findDuplicateUtilities(
     "SELECT * FROM project_utilities WHERE utility_name = ?"
   ).all(utilityName) as any[];
 }
+
+// ═══════════════════════════════════════════════════════════════
+// v9.3: Agent Performance Tracking (Feedback Loop)
+// ═══════════════════════════════════════════════════════════════
+
+export interface AgentPerformanceData {
+  agentType: string;
+  specId: string;
+  taskId: number;
+  gatesPassedFirstTry: number;
+  gatesTotal: number;
+  bypassesUsed: number;
+  filesCreated: number;
+  filesModified: number;
+  contextSizeBytes: number;
+  executionDurationMs: number;
+}
+
+export function recordAgentPerformance(data: AgentPerformanceData): void {
+  const db = getDb();
+  const now = new Date().toISOString();
+  db.run(
+    `INSERT INTO agent_performance
+     (agent_type, spec_id, task_id, gates_passed_first_try, gates_total, bypasses_used, files_created, files_modified, context_size_bytes, execution_duration_ms, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      data.agentType, data.specId, data.taskId,
+      data.gatesPassedFirstTry, data.gatesTotal, data.bypassesUsed,
+      data.filesCreated, data.filesModified,
+      data.contextSizeBytes, data.executionDurationMs, now,
+    ]
+  );
+}
+
+export function getAgentHints(agentType: string, limit: number = 5): string[] {
+  const db = getDb();
+  const hints: string[] = [];
+
+  try {
+    const recent = db.query(
+      `SELECT * FROM agent_performance
+       WHERE agent_type = ?
+       ORDER BY created_at DESC LIMIT ?`
+    ).all(agentType, limit) as any[];
+
+    if (recent.length === 0) return [];
+
+    const avgBypass = recent.reduce((sum: number, r: any) => sum + r.bypasses_used, 0) / recent.length;
+    const avgGateRate = recent.reduce((sum: number, r: any) => {
+      return sum + (r.gates_total > 0 ? r.gates_passed_first_try / r.gates_total : 1);
+    }, 0) / recent.length;
+
+    if (avgBypass > 0.5) {
+      hints.push(`ATENCAO: Este agente usa bypasses frequentemente (media ${avgBypass.toFixed(1)}/task). Revise standards antes de iniciar.`);
+    }
+
+    if (avgGateRate < 0.7) {
+      hints.push(`ATENCAO: Gate pass rate baixo (${(avgGateRate * 100).toFixed(0)}%). Verifique standards e DRY obrigatorios.`);
+    }
+
+    const bypassTypes = db.query(
+      `SELECT gb.gate_name, COUNT(*) as cnt FROM gate_bypasses gb
+       JOIN tasks t ON gb.task_id = t.id
+       WHERE t.agent = ?
+       GROUP BY gb.gate_name
+       ORDER BY cnt DESC LIMIT 3`
+    ).all(agentType) as any[];
+
+    for (const bp of bypassTypes) {
+      if (bp.cnt >= 2) {
+        hints.push(`Gate '${bp.gate_name}' frequentemente ignorado (${bp.cnt}x). Preste atencao especial.`);
+      }
+    }
+  } catch {
+    // Tabela pode nao existir ainda
+  }
+
+  return hints;
+}

package/gates/validator.test.ts

@@ -615,3 +615,61 @@ describe("enforceGate", () => {
     expect(result.resolution).toBeDefined();
   });
 });
+
+// ═══════════════════════════════════════════════════════════════
+// v9.3: Recovery Strategies
+// ═══════════════════════════════════════════════════════════════
+
+describe("Recovery Strategies (P3.3)", () => {
+  it("GateError should carry recovery suggestion", () => {
+    try {
+      // "task-done" with no taskId fails on "task-is-running"
+      // task-is-running has no recovery strategy, so recovery should be undefined
+      enforceGate("task-done", {});
+      expect(true).toBe(false);
+    } catch (e) {
+      const ge = e as GateError;
+      expect(ge instanceof GateError).toBe(true);
+      // task-is-running has no recovery strategy
+      expect(ge.recovery).toBeUndefined();
+    }
+  });
+
+  it("validateGate should return recovery for checkpoint-filled failure", () => {
+    // Simulate a task-done call where task-is-running passes but checkpoint fails
+    // We pass taskId to skip task-is-running (it needs DB), so we test checkpoint directly
+    const result = validateGate("task-done", { taskId: null });
+    // Without taskId, task-is-running fails first (no recovery for it)
+    expect(result.passed).toBe(false);
+  });
+
+  it("GateError recovery field should have correct structure when present", () => {
+    const { RecoverySuggestion } = require("../errors");
+    const recovery = {
+      diagnostic: "Erros TypeScript encontrados:\nsrc/foo.ts:10 - TS2322",
+      steps: [
+        "Corrija os erros de tipo listados",
+        "Verifique imports e definicoes de tipo",
+      ],
+      command: "bunx tsc --noEmit",
+    };
+
+    const err = new GateError("test reason", "test resolution", "typecheck-pass", recovery);
+    expect(err.recovery).toBeDefined();
+    expect(err.recovery!.diagnostic).toContain("Erros TypeScript");
+    expect(err.recovery!.steps).toHaveLength(2);
+    expect(err.recovery!.steps[0]).toContain("Corrija");
+    expect(err.recovery!.command).toBe("bunx tsc --noEmit");
+  });
+
+  it("GateError without recovery should have undefined recovery", () => {
+    const err = new GateError("test reason", "test resolution", "unknown-gate");
+    expect(err.recovery).toBeUndefined();
+  });
+
+  it("validateGate for unknown command should pass with no recovery", () => {
+    const result = validateGate("nonexistent", {});
+    expect(result.passed).toBe(true);
+    expect(result.recovery).toBeUndefined();
+  });
+});

package/gates/validator.ts

@@ -5,12 +5,14 @@ import { validateAgainstStandards, printValidationResult } from "./standards-val
 import { runTypecheck, printTypecheckResult } from "./typecheck-validator";
 import { extractUtilitiesFromFile } from "../commands/patterns";
 import { findDuplicateUtilities } from "../db/schema";
-import { GateError } from "../errors";
+import { GateError, RecoverySuggestion } from "../errors";
+import { resolveSpecOrNull } from "../commands/spec-resolver";
 
 export interface GateResult {
   passed: boolean;
   reason?: string;
   resolution?: string;
+  recovery?: RecoverySuggestion;
 }
 
 interface GateCheck {
@@ -64,8 +66,8 @@ const GATES: Record<string, GateCheck[]> = {
     },
     {
       check: "checkpoint-filled",
-      message: "Checkpoint obrigatorio (min 30 chars, 5 palavras)",
-      resolution: "Forneca --checkpoint 'resumo detalhado do que foi feito' (min 30 caracteres e 5 palavras)",
+      message: "Checkpoint obrigatorio (min 10 chars)",
+      resolution: "Forneca --checkpoint 'resumo do que foi feito' (min 10 caracteres)",
     },
     {
       check: "files-exist",
@@ -109,9 +111,59 @@ const GATES: Record<string, GateCheck[]> = {
   ],
 };
 
-function getActiveSpec(): any {
-  const db = getDb();
-  return db.query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1").get();
+// v9.3: Estrategias de recuperacao por gate — diagnostico + passos concretos
+const RECOVERY_STRATEGIES: Record<string, (details?: string) => RecoverySuggestion> = {
+  "standards-follow": (details) => ({
+    diagnostic: `Violacoes de standards detectadas:\n${details || "Detalhes nao disponiveis"}`,
+    steps: [
+      "Revise as violacoes listadas acima",
+      "Corrija o codigo para seguir os standards obrigatorios",
+      "Ou use --force --force-reason 'motivo' para bypass (auditado no review)",
+    ],
+    command: "codexa context detail standards",
+  }),
+  "dry-check": (details) => ({
+    diagnostic: `Utilities duplicadas encontradas:\n${details || "Detalhes nao disponiveis"}`,
+    steps: [
+      "Verifique as utilities existentes",
+      "Importe do arquivo existente em vez de recriar",
+      "Se intencional, use --force --force-reason 'motivo'",
+    ],
+  }),
+  "typecheck-pass": (details) => ({
+    diagnostic: `Erros TypeScript encontrados:\n${details || "Detalhes nao disponiveis"}`,
+    steps: [
+      "Corrija os erros de tipo listados",
+      "Verifique imports e definicoes de tipo",
+      "Se erros em deps externas, use --force --force-reason 'motivo'",
+    ],
+  }),
+  "files-exist": (details) => ({
+    diagnostic: `Arquivos esperados nao encontrados:\n${details || "Detalhes nao disponiveis"}`,
+    steps: [
+      "Verifique se o subagent usou Write/Edit para criar os arquivos",
+      "Confirme que os caminhos em --files correspondem aos arquivos reais",
+      "Verifique conteudo valido (nao vazio, estrutura correta)",
+    ],
+  }),
+  "checkpoint-filled": (details) => ({
+    diagnostic: `Checkpoint invalido: ${details || "muito curto ou incompleto"}`,
+    steps: [
+      "Forneca --checkpoint com resumo do que foi feito (min 10 chars)",
+      "Descreva O QUE foi feito, nao apenas 'feito' ou 'ok'",
+    ],
+  }),
+  "reasoning-provided": () => ({
+    diagnostic: "Subagent retornou sem reasoning.approach adequado",
+    steps: [
+      "Inclua 'reasoning.approach' no retorno JSON do subagent (min 20 chars)",
+      "Descreva COMO o problema foi abordado",
+    ],
+  }),
+};
+
+function getActiveSpec(specId?: string): any {
+  return resolveSpecOrNull(specId);
 }
 
 function executeCheck(check: string, context: any): { passed: boolean; details?: string } {
@@ -119,24 +171,24 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
 
   switch (check) {
     case "plan-exists": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       return { passed: spec !== null };
     }
 
     case "has-tasks": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       if (!spec) return { passed: false };
       const count = db.query("SELECT COUNT(*) as c FROM tasks WHERE spec_id = ?").get(spec.id) as any;
       return { passed: count.c > 0 };
     }
 
     case "phase-is-checking": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       return { passed: spec?.phase === "checking" };
     }
 
     case "spec-approved": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       return { passed: spec?.approved_at !== null };
     }
 
@@ -166,18 +218,14 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
 
     case "checkpoint-filled": {
       const cp = context.checkpoint?.trim() || "";
-      if (cp.length < 30) {
-        return { passed: false, details: "Checkpoint deve ter pelo menos 30 caracteres" };
-      }
-      const wordCount = cp.split(/\s+/).filter((w: string) => w.length > 1).length;
-      if (wordCount < 5) {
-        return { passed: false, details: "Checkpoint deve ter pelo menos 5 palavras" };
+      if (cp.length < 10) {
+        return { passed: false, details: "Checkpoint deve ter pelo menos 10 caracteres" };
       }
       return { passed: true };
     }
 
     case "all-tasks-done": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       if (!spec) return { passed: false };
       const pending = db.query(
         "SELECT number FROM tasks WHERE spec_id = ? AND status != 'done'"
@@ -189,7 +237,7 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
     }
 
     case "review-exists": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       if (!spec) return { passed: false };
       const review = db.query("SELECT * FROM review WHERE spec_id = ?").get(spec.id);
       return { passed: review !== null };
@@ -200,6 +248,8 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
 
       // v8.0: Validar não apenas existência, mas conteúdo mínimo
       // v9.2: Validar que arquivo foi modificado DURANTE a task
+      // v9.3: Tolerancia de 5s para clock skew em sandbox
+      const MTIME_TOLERANCE_MS = 5000;
       const issues: string[] = [];
 
       // Buscar started_at da task para comparacao temporal
@@ -217,13 +267,14 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
           issues.push(`${file}: ${validation.reason}`);
           continue;
         }
-        // Verificar que arquivo foi tocado durante a task
+        // Verificar que arquivo foi tocado durante a task (com tolerancia)
         if (taskStartTime) {
           try {
             const stat = statSync(file);
             const mtime = stat.mtimeMs;
-            if (mtime < taskStartTime) {
-              issues.push(`${file}: arquivo nao foi modificado durante esta task (mtime anterior ao start)`);
+            if (mtime < (taskStartTime - MTIME_TOLERANCE_MS)) {
+              const diffSec = Math.round((taskStartTime - mtime) / 1000);
+              issues.push(`${file}: arquivo nao foi modificado durante esta task (mtime ${diffSec}s anterior ao start)`);
             }
           } catch {
             // statSync falhou — arquivo pode nao existir (ja reportado por validateFileContent)
@@ -342,7 +393,7 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
     }
 
     case "no-critical-blockers": {
-      const spec = getActiveSpec();
+      const spec = getActiveSpec(context.specId);
       if (!spec) return { passed: true };
 
       const allKnowledge = db
@@ -356,13 +407,10 @@ function executeCheck(check: string, context: any): { passed: boolean; details?:
         .all(spec.id) as any[];
 
       const unresolved = allKnowledge.filter((k: any) => {
-        if (!k.acknowledged_by) return true;
-        try {
-          const acked = JSON.parse(k.acknowledged_by) as number[];
-          return acked.length === 0;
-        } catch {
-          return true;
-        }
+        const hasAck = db.query(
+          "SELECT 1 FROM knowledge_acknowledgments WHERE knowledge_id = ?"
+        ).get(k.id);
+        return !hasAck;
       });
 
       if (unresolved.length === 0) return { passed: true };
@@ -422,12 +470,16 @@ export function validateGate(command: string, context: any = {}): GateResult {
     const result = executeCheck(gate.check, context);
 
     if (!result.passed) {
+      const recoveryFn = RECOVERY_STRATEGIES[gate.check];
+      const recovery = recoveryFn ? recoveryFn(result.details) : undefined;
+
       return {
         passed: false,
         reason: result.details
           ? `${gate.message}: ${result.details}`
           : gate.message,
         resolution: gate.resolution,
+        recovery,
       };
     }
   }
@@ -442,7 +494,8 @@ export function enforceGate(command: string, context: any = {}): void {
     throw new GateError(
       result.reason || "Gate falhou",
       result.resolution || "Verifique o estado atual",
-      command
+      command,
+      result.recovery
     );
   }
 }

package/package.json

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