@codexa/cli 9.0.3 → 9.0.5

package/commands/review.ts

@@ -1,17 +1,135 @@
 import { getDb } from "../db/connection";
 import { initSchema, getArchitecturalAnalysisForSpec } from "../db/schema";
 import { enforceGate } from "../gates/validator";
+import { resolveSpec } from "./spec-resolver";
+import { CodexaError, GateError } from "../errors";
+
+// ═══════════════════════════════════════════════════════════════
+// P1-2: Review Score — Threshold Automatico
+// ═══════════════════════════════════════════════════════════════
+
+export interface ReviewScore {
+  total: number;        // 0-100
+  breakdown: {
+    tasksCompleted: number;      // % tasks done vs planned (25 pts)
+    gatesPassedClean: number;    // % gates sem bypass (25 pts)
+    filesDelivered: number;      // % arquivos planejados vs criados (25 pts)
+    standardsFollowed: number;   // % standards sem violacao (25 pts)
+  };
+  autoApproveEligible: boolean;  // score >= 80 AND zero critical bypasses
+  mustReviewItems: string[];     // Items que exigem atencao humana
+}
+
+export function calculateReviewScore(specId: string): ReviewScore {
+  const db = getDb();
+
+  const mustReviewItems: string[] = [];
+
+  // 1. Tasks: (completed / total) * 25
+  const totalTasks = (db.query(
+    "SELECT COUNT(*) as c FROM tasks WHERE spec_id = ?"
+  ).get(specId) as any).c;
+  const completedTasks = (db.query(
+    "SELECT COUNT(*) as c FROM tasks WHERE spec_id = ? AND status = 'done'"
+  ).get(specId) as any).c;
+  const tasksCompleted = totalTasks > 0
+    ? Math.round((completedTasks / totalTasks) * 25)
+    : 25;
+
+  if (completedTasks < totalTasks) {
+    mustReviewItems.push(`${totalTasks - completedTasks} task(s) nao concluida(s)`);
+  }
+
+  // 2. Gates: (clean passes / total gate events) * 25
+  // Total gate events = tasks * 7 gates per task
+  const totalGateEvents = totalTasks * 7;
+  const bypassCount = (db.query(
+    "SELECT COUNT(*) as c FROM gate_bypasses WHERE spec_id = ?"
+  ).get(specId) as any).c;
+  const cleanGateEvents = Math.max(0, totalGateEvents - bypassCount);
+  const gatesPassedClean = totalGateEvents > 0
+    ? Math.round((cleanGateEvents / totalGateEvents) * 25)
+    : 25;
+
+  // Check for critical bypasses
+  const criticalBypasses = db.query(
+    "SELECT * FROM gate_bypasses WHERE spec_id = ? AND gate_name IN ('standards-follow', 'dry-check', 'typecheck-pass')"
+  ).all(specId) as any[];
+  if (criticalBypasses.length > 0) {
+    mustReviewItems.push(`${criticalBypasses.length} bypass(es) de gates criticos`);
+  }
+
+  // 3. Files: (delivered / planned) * 25
+  const plannedFiles = db.query(
+    "SELECT files FROM tasks WHERE spec_id = ? AND files IS NOT NULL"
+  ).all(specId) as any[];
+  const allPlannedFiles = new Set<string>();
+  for (const t of plannedFiles) {
+    try {
+      const files = JSON.parse(t.files) as string[];
+      for (const f of files) allPlannedFiles.add(f);
+    } catch { /* ignore */ }
+  }
+
+  const deliveredFiles = new Set(
+    (db.query(
+      "SELECT DISTINCT path FROM artifacts WHERE spec_id = ?"
+    ).all(specId) as any[]).map(a => a.path)
+  );
+
+  let filesDelivered: number;
+  if (allPlannedFiles.size === 0) {
+    filesDelivered = deliveredFiles.size > 0 ? 25 : 0;
+  } else {
+    let matchCount = 0;
+    for (const f of allPlannedFiles) {
+      if (deliveredFiles.has(f)) matchCount++;
+    }
+    filesDelivered = Math.round((matchCount / allPlannedFiles.size) * 25);
+  }
+
+  const missingFiles = [...allPlannedFiles].filter(f => !deliveredFiles.has(f));
+  if (missingFiles.length > 0) {
+    mustReviewItems.push(`${missingFiles.length} arquivo(s) planejado(s) nao entregue(s)`);
+  }
 
-export function reviewStart(json: boolean = false): void {
+  // 4. Standards: (followed / total) * 25
+  // Inverse of standards-follow bypasses relative to total tasks
+  const standardsBypasses = (db.query(
+    "SELECT COUNT(*) as c FROM gate_bypasses WHERE spec_id = ? AND gate_name = 'standards-follow'"
+  ).get(specId) as any).c;
+  const standardsFollowed = totalTasks > 0
+    ? Math.round(((totalTasks - standardsBypasses) / totalTasks) * 25)
+    : 25;
+
+  if (standardsBypasses > 0) {
+    mustReviewItems.push(`${standardsBypasses} bypass(es) de standards`);
+  }
+
+  const total = tasksCompleted + gatesPassedClean + filesDelivered + standardsFollowed;
+  const autoApproveEligible = total >= 80 && criticalBypasses.length === 0;
+
+  return {
+    total,
+    breakdown: {
+      tasksCompleted,
+      gatesPassedClean,
+      filesDelivered,
+      standardsFollowed,
+    },
+    autoApproveEligible,
+    mustReviewItems,
+  };
+}
+
+export function reviewStart(json: boolean = false, specId?: string): void {
   initSchema();
   enforceGate("review-start");
 
   const db = getDb();
   const now = new Date().toISOString();
 
-  const spec = db
-    .query("SELECT * FROM specs WHERE phase = 'implementing' ORDER BY created_at DESC LIMIT 1")
-    .get() as any;
+  const spec = resolveSpec(specId, ["implementing"]);
 
   const tasks = db
     .query("SELECT * FROM tasks WHERE spec_id = ? ORDER BY number")
@@ -87,8 +205,11 @@ export function reviewStart(json: boolean = false): void {
   // Atualizar fase
   db.run("UPDATE specs SET phase = 'reviewing', updated_at = ? WHERE id = ?", [now, spec.id]);
 
+  // P1-2: Calcular score automatico
+  const score = calculateReviewScore(spec.id);
+
   if (json) {
-    console.log(JSON.stringify({ spec, reviewData, deviations }));
+    console.log(JSON.stringify({ spec, reviewData, deviations, score }));
     return;
   }
 
@@ -96,6 +217,25 @@ export function reviewStart(json: boolean = false): void {
   console.log(`REVIEW: ${spec.name}`);
   console.log(`${"=".repeat(60)}`);
 
+  // P1-2: Mostrar score
+  const scoreIcon = score.total >= 80 ? "[OK]" : score.total >= 50 ? "[!]" : "[X]";
+  console.log(`\n${scoreIcon} REVIEW SCORE: ${score.total}/100`);
+  console.log(`  Tasks concluidas:    ${score.breakdown.tasksCompleted}/25`);
+  console.log(`  Gates limpos:        ${score.breakdown.gatesPassedClean}/25`);
+  console.log(`  Arquivos entregues:  ${score.breakdown.filesDelivered}/25`);
+  console.log(`  Standards seguidos:  ${score.breakdown.standardsFollowed}/25`);
+
+  if (score.autoApproveEligible) {
+    console.log(`\n  Elegivel para aprovacao automatica.`);
+  }
+
+  if (score.mustReviewItems.length > 0) {
+    console.log(`\n  Items que exigem atencao:`);
+    for (const item of score.mustReviewItems) {
+      console.log(`    - ${item}`);
+    }
+  }
+
   console.log(`\nResumo da implementacao:`);
   console.log(`  Tasks concluidas: ${tasks.length}`);
   console.log(`  Artefatos criados: ${artifacts.length}`);
@@ -123,24 +263,48 @@ export function reviewStart(json: boolean = false): void {
     console.log(`\nNenhum desvio encontrado.`);
   }
 
-  console.log(`\nPara aprovar: review approve`);
+  if (score.total < 50) {
+    console.log(`\n[!] Score abaixo de 50. Aprovacao requer: review approve --force --force-reason "motivo"`);
+  } else {
+    console.log(`\nPara aprovar: review approve`);
+  }
   console.log(`Para ver status: status\n`);
 }
 
-export function reviewApprove(): void {
+export function reviewApprove(options?: { specId?: string; force?: boolean; forceReason?: string } | string): void {
   initSchema();
   enforceGate("review-approve");
 
   const db = getDb();
   const now = new Date().toISOString();
 
-  const spec = db
-    .query("SELECT * FROM specs WHERE phase = 'reviewing' ORDER BY created_at DESC LIMIT 1")
-    .get() as any;
+  // Backward compat: accept string (old API) or options object
+  const opts = typeof options === "string"
+    ? { specId: options }
+    : (options || {});
+
+  const spec = resolveSpec(opts.specId, ["reviewing"]);
+
+  // P1-2: Enforce minimum score
+  const score = calculateReviewScore(spec.id);
+  if (score.total < 50 && !opts.force) {
+    throw new GateError(
+      `Review score muito baixo: ${score.total}/100.\n` +
+      `  Items criticos:\n` +
+      score.mustReviewItems.map(i => `    - ${i}`).join("\n"),
+      `Use: review approve --force --force-reason "motivo" para aprovar mesmo assim`,
+      "review-approve"
+    );
+  }
 
-  if (!spec) {
-    console.error("\nNenhum review em andamento.\n");
-    process.exit(1);
+  if (score.total < 50 && opts.force) {
+    // Log the forced approval
+    db.run(
+      `INSERT INTO gate_bypasses (spec_id, task_id, gate_name, reason, created_at)
+       VALUES (?, 0, 'review-low-score', ?, ?)`,
+      [spec.id, opts.forceReason || `Score ${score.total}/100 - forced approval`, now]
+    );
+    console.log(`\n[!] Review aprovado com score baixo (${score.total}/100). Bypass registrado.`);
   }
 
   // Atualizar review
@@ -175,27 +339,19 @@ export function reviewApprove(): void {
   ]);
 
   // Mostrar relatorio final completo
-  showReviewReport(spec, tasks, artifacts, decisions, knowledge, review);
+  showReviewReport(spec, tasks, artifacts, decisions, knowledge, review, score);
 }
 
 /**
  * Pula o review e finaliza a feature diretamente
  */
-export function reviewSkip(): void {
+export function reviewSkip(specId?: string): void {
   initSchema();
 
   const db = getDb();
   const now = new Date().toISOString();
 
-  // Buscar spec em implementacao com todas tasks concluidas
-  const spec = db
-    .query("SELECT * FROM specs WHERE phase = 'implementing' ORDER BY created_at DESC LIMIT 1")
-    .get() as any;
-
-  if (!spec) {
-    console.error("\nNenhuma feature em fase de implementacao.\n");
-    process.exit(1);
-  }
+  const spec = resolveSpec(specId, ["implementing"]);
 
   // Verificar se todas tasks estao done
   const pending = db
@@ -203,9 +359,7 @@ export function reviewSkip(): void {
     .get(spec.id) as any;
 
   if (pending.c > 0) {
-    console.error(`\nAinda existem ${pending.c} tasks pendentes.`);
-    console.error("Complete todas as tasks antes de pular o review.\n");
-    process.exit(1);
+    throw new CodexaError(`Ainda existem ${pending.c} tasks pendentes.\nComplete todas as tasks antes de pular o review.`);
   }
 
   // Buscar dados
@@ -265,7 +419,8 @@ function showReviewReport(
   artifacts: any[],
   decisions: any[],
   knowledge: any[],
-  review: any
+  review: any,
+  score?: ReviewScore
 ): void {
   const reviewData = review.planned_vs_done ? JSON.parse(review.planned_vs_done) : {};
   const deviations = review.deviations ? JSON.parse(review.deviations) : [];
@@ -278,6 +433,13 @@ function showReviewReport(
   console.log(`   Status: ✅ COMPLETA E APROVADA`);
   console.log(`   ID: ${spec.id}`);
 
+  // P1-2: Score no relatorio final
+  if (score) {
+    const scoreIcon = score.total >= 80 ? "✅" : score.total >= 50 ? "⚠️" : "❌";
+    console.log(`   Score: ${scoreIcon} ${score.total}/100`);
+    console.log(`     Tasks: ${score.breakdown.tasksCompleted}/25 | Gates: ${score.breakdown.gatesPassedClean}/25 | Files: ${score.breakdown.filesDelivered}/25 | Standards: ${score.breakdown.standardsFollowed}/25`);
+  }
+
   // Resumo de execucao
   console.log(`\n${"─".repeat(60)}`);
   console.log(`📊 RESUMO DA EXECUCAO`);

package/commands/spec-resolver.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { resolveSpec, getAllActiveSpecs } from "./spec-resolver";
+import { getDb } from "../db/connection";
+import { initSchema } from "../db/schema";
+
+beforeEach(() => {
+  initSchema();
+  const db = getDb();
+  // Limpar em ordem que respeita foreign keys
+  db.run("DELETE FROM reasoning_log");
+  db.run("DELETE FROM knowledge_graph");
+  db.run("DELETE FROM knowledge");
+  db.run("DELETE FROM gate_bypasses");
+  db.run("DELETE FROM snapshots");
+  db.run("DELETE FROM review");
+  db.run("DELETE FROM artifacts");
+  db.run("DELETE FROM decisions");
+  db.run("DELETE FROM tasks");
+  db.run("DELETE FROM context");
+  db.run("DELETE FROM specs");
+});
+
+function createSpec(id: string, name: string, phase: string, createdAt?: string) {
+  const db = getDb();
+  const now = createdAt || new Date().toISOString();
+  db.run(
+    "INSERT INTO specs (id, name, phase, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
+    [id, name, phase, now, now]
+  );
+}
+
+describe("resolveSpec", () => {
+  it("returns spec by ID when specId provided", () => {
+    createSpec("spec-a", "Feature A", "planning");
+    createSpec("spec-b", "Feature B", "implementing");
+
+    const result = resolveSpec("spec-a");
+    expect(result.id).toBe("spec-a");
+    expect(result.name).toBe("Feature A");
+  });
+
+  it("returns most recent active spec when no specId", () => {
+    createSpec("spec-old", "Old Feature", "planning", "2026-01-01T00:00:00Z");
+    createSpec("spec-new", "New Feature", "implementing", "2026-02-01T00:00:00Z");
+
+    const result = resolveSpec();
+    expect(result.id).toBe("spec-new");
+  });
+
+  it("validates requiredPhases", () => {
+    createSpec("spec-a", "Feature A", "planning");
+
+    // Should work with matching phase
+    const result = resolveSpec("spec-a", ["planning"]);
+    expect(result.phase).toBe("planning");
+  });
+
+  it("accepts multiple requiredPhases", () => {
+    createSpec("spec-a", "Feature A", "checking");
+    const result = resolveSpec("spec-a", ["planning", "checking"]);
+    expect(result.phase).toBe("checking");
+  });
+
+  it("skips completed specs when no specId", () => {
+    createSpec("spec-done", "Done Feature", "completed", "2026-02-01T00:00:00Z");
+    createSpec("spec-active", "Active Feature", "planning", "2026-01-01T00:00:00Z");
+
+    const result = resolveSpec();
+    expect(result.id).toBe("spec-active");
+  });
+
+  it("skips cancelled specs when no specId", () => {
+    createSpec("spec-cancelled", "Cancelled Feature", "cancelled", "2026-02-01T00:00:00Z");
+    createSpec("spec-active", "Active Feature", "implementing", "2026-01-01T00:00:00Z");
+
+    const result = resolveSpec();
+    expect(result.id).toBe("spec-active");
+  });
+});
+
+describe("getAllActiveSpecs", () => {
+  it("returns empty array when no active specs", () => {
+    const result = getAllActiveSpecs();
+    expect(result).toEqual([]);
+  });
+
+  it("returns all active specs ordered by created_at DESC", () => {
+    createSpec("spec-old", "Old Feature", "planning", "2026-01-01T00:00:00Z");
+    createSpec("spec-new", "New Feature", "implementing", "2026-02-01T00:00:00Z");
+
+    const result = getAllActiveSpecs();
+    expect(result.length).toBe(2);
+    expect(result[0].id).toBe("spec-new");
+    expect(result[1].id).toBe("spec-old");
+  });
+
+  it("excludes completed and cancelled specs", () => {
+    createSpec("spec-active", "Active", "planning");
+    createSpec("spec-done", "Done", "completed");
+    createSpec("spec-cancelled", "Cancelled", "cancelled");
+
+    const result = getAllActiveSpecs();
+    expect(result.length).toBe(1);
+    expect(result[0].id).toBe("spec-active");
+  });
+
+  it("returns multiple specs in different phases", () => {
+    createSpec("spec-plan", "Planning Feature", "planning", "2026-01-01T00:00:00Z");
+    createSpec("spec-impl", "Implementing Feature", "implementing", "2026-01-02T00:00:00Z");
+    createSpec("spec-rev", "Reviewing Feature", "reviewing", "2026-01-03T00:00:00Z");
+
+    const result = getAllActiveSpecs();
+    expect(result.length).toBe(3);
+    // Ordered by created_at DESC
+    expect(result[0].id).toBe("spec-rev");
+    expect(result[1].id).toBe("spec-impl");
+    expect(result[2].id).toBe("spec-plan");
+  });
+});

package/commands/spec-resolver.ts

@@ -0,0 +1,90 @@
+import { getDb } from "../db/connection";
+import { initSchema } from "../db/schema";
+import { CodexaError } from "../errors";
+
+export interface ResolvedSpec {
+  id: string;
+  name: string;
+  phase: string;
+  approved_at: string | null;
+  analysis_id: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/**
+ * Resolve qual spec usar para um comando.
+ * - Se specId fornecido: busca esse spec (erro se nao encontrado ou finalizado)
+ * - Se nao fornecido: busca o mais recente ativo (ORDER BY created_at DESC LIMIT 1)
+ * - Se requiredPhases: valida que spec.phase esta na lista
+ */
+export function resolveSpec(specId?: string, requiredPhases?: string[]): ResolvedSpec {
+  const db = getDb();
+
+  let spec: any;
+
+  if (specId) {
+    spec = db
+      .query("SELECT * FROM specs WHERE id = ?")
+      .get(specId);
+
+    if (!spec) {
+      throw new CodexaError(`Spec '${specId}' nao encontrado.`);
+    }
+
+    if (spec.phase === "completed" || spec.phase === "cancelled") {
+      throw new CodexaError(`Spec '${specId}' ja esta ${spec.phase}.`);
+    }
+  } else {
+    spec = db
+      .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
+      .get();
+
+    if (!spec) {
+      throw new CodexaError("Nenhuma feature ativa.");
+    }
+  }
+
+  if (requiredPhases && !requiredPhases.includes(spec.phase)) {
+    throw new CodexaError(
+      `Spec '${spec.name}' esta na fase '${spec.phase}', esperado: ${requiredPhases.join(" ou ")}.\nSpec ID: ${spec.id}`
+    );
+  }
+
+  return spec as ResolvedSpec;
+}
+
+/**
+ * Versao silenciosa de resolveSpec que retorna null em vez de process.exit(1).
+ * Util para comandos que tem tratamento especial (ex: json output, throw customizado).
+ */
+export function resolveSpecOrNull(specId?: string, requiredPhases?: string[]): ResolvedSpec | null {
+  const db = getDb();
+
+  let spec: any;
+
+  if (specId) {
+    spec = db.query("SELECT * FROM specs WHERE id = ?").get(specId);
+    if (!spec) return null;
+    if (spec.phase === "completed" || spec.phase === "cancelled") return null;
+  } else {
+    spec = db
+      .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
+      .get();
+    if (!spec) return null;
+  }
+
+  if (requiredPhases && !requiredPhases.includes(spec.phase)) return null;
+
+  return spec as ResolvedSpec;
+}
+
+/**
+ * Retorna todos os specs ativos (nao completed/cancelled).
+ */
+export function getAllActiveSpecs(): ResolvedSpec[] {
+  const db = getDb();
+  return db
+    .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC")
+    .all() as ResolvedSpec[];
+}

package/commands/standards.ts

@@ -1,6 +1,7 @@
 import { getDb } from "../db/connection";
 import { initSchema } from "../db/schema";
 import { generateStandardsMarkdown } from "./discover";
+import { CodexaError, ValidationError } from "../errors";
 
 export function standardsList(options: { category?: string; scope?: string; json?: boolean }): void {
   initSchema();
@@ -69,22 +70,16 @@ export function standardsAdd(options: {
   const validEnforcement = ["required", "recommended"];
 
   if (!validCategories.includes(options.category)) {
-    console.error(`\nCategoria invalida: ${options.category}`);
-    console.error(`Validas: ${validCategories.join(", ")}\n`);
-    process.exit(2);
+    throw new ValidationError(`Categoria invalida: ${options.category}\nValidas: ${validCategories.join(", ")}`);
   }
 
   if (!validScopes.includes(options.scope)) {
-    console.error(`\nEscopo invalido: ${options.scope}`);
-    console.error(`Validos: ${validScopes.join(", ")}\n`);
-    process.exit(2);
+    throw new ValidationError(`Escopo invalido: ${options.scope}\nValidos: ${validScopes.join(", ")}`);
   }
 
   const enforcement = options.enforcement || "required";
   if (!validEnforcement.includes(enforcement)) {
-    console.error(`\nEnforcement invalido: ${enforcement}`);
-    console.error(`Validos: ${validEnforcement.join(", ")}\n`);
-    process.exit(2);
+    throw new ValidationError(`Enforcement invalido: ${enforcement}\nValidos: ${validEnforcement.join(", ")}`);
   }
 
   let examples = null;
@@ -131,8 +126,7 @@ export function standardsEdit(
   const existing = db.query("SELECT * FROM standards WHERE id = ?").get(standardId) as any;
 
   if (!existing) {
-    console.error(`\nStandard #${id} nao encontrado.\n`);
-    process.exit(1);
+    throw new CodexaError(`Standard #${id} nao encontrado.`);
   }
 
   const updates: string[] = [];
@@ -159,8 +153,7 @@ export function standardsEdit(
   }
 
   if (updates.length === 0) {
-    console.error("\nNenhuma alteracao fornecida.\n");
-    process.exit(2);
+    throw new ValidationError("Nenhuma alteracao fornecida.");
   }
 
   params.push(standardId);
@@ -181,8 +174,7 @@ export function standardsRemove(id: string): void {
   const existing = db.query("SELECT * FROM standards WHERE id = ?").get(standardId) as any;
 
   if (!existing) {
-    console.error(`\nStandard #${id} nao encontrado.\n`);
-    process.exit(1);
+    throw new CodexaError(`Standard #${id} nao encontrado.`);
   }
 
   db.run("DELETE FROM standards WHERE id = ?", [standardId]);

package/commands/sync.ts

@@ -1,6 +1,7 @@
 import { execSync } from "child_process";
 import { existsSync, mkdirSync, copyFileSync, readdirSync, readFileSync } from "fs";
 import { join } from "path";
+import { CodexaError } from "../errors";
 
 // Agents que sao referencias (nao spawnables como subagent_type)
 const REFERENCE_FILES = new Set([
@@ -47,9 +48,7 @@ export function syncAgents(options: { force?: boolean } = {}): void {
   const pluginDir = findPluginAgentsDir();
 
   if (!pluginDir) {
-    console.error("\n[ERRO] Diretorio de agents do plugin nao encontrado.");
-    console.error("  Verifique se voce esta no repositorio codexa ou se @codexa/cli esta instalado globalmente.\n");
-    process.exit(1);
+    throw new CodexaError("Diretorio de agents do plugin nao encontrado.\nVerifique se voce esta no repositorio codexa ou se @codexa/cli esta instalado globalmente.");
   }
 
   const targetDir = join(process.cwd(), ".claude", "agents");

package/commands/task.ts

@@ -1,5 +1,5 @@
 import { getDb } from "../db/connection";
-import { initSchema, getPatternsForFiles, getPatternsByScope, getRecentReasoning, claimTask } from "../db/schema";
+import { initSchema, getPatternsForFiles, getPatternsByScope, getRecentReasoning, claimTask, recordAgentPerformance } from "../db/schema";
 import { enforceGate } from "../gates/validator";
 import { parseSubagentReturn, formatValidationErrors } from "../protocol/subagent-protocol";
 import { processSubagentReturn, formatProcessResult } from "../protocol/process-return";
@@ -7,14 +7,13 @@ import { getContextForSubagent, getMinimalContextForSubagent } from "./utils";
 import { getUnreadKnowledgeForTask } from "./knowledge";
 import { loadTemplate } from "../templates/loader";
 import { TaskStateError, ValidationError, KnowledgeBlockError } from "../errors";
+import { resolveSpec, resolveSpecOrNull } from "./spec-resolver";
 
-export function taskNext(json: boolean = false): void {
+export function taskNext(json: boolean = false, specId?: string): void {
   initSchema();
 
   const db = getDb();
-  const spec = db
-    .query("SELECT * FROM specs WHERE phase = 'implementing' ORDER BY created_at DESC LIMIT 1")
-    .get() as any;
+  const spec = resolveSpecOrNull(specId, ["implementing"]);
 
   if (!spec) {
     if (json) {
@@ -101,16 +100,14 @@ export function taskNext(json: boolean = false): void {
   console.log(`Use: task start <id> ou task start <id1>,<id2>,...\n`);
 }
 
-export function taskStart(ids: string, json: boolean = false, fullContext: boolean = false): void {
+export function taskStart(ids: string, json: boolean = false, fullContext: boolean = false, specId?: string): void {
   initSchema();
   enforceGate("task-start");
 
   const db = getDb();
   const now = new Date().toISOString();
 
-  const spec = db
-    .query("SELECT * FROM specs WHERE phase = 'implementing' ORDER BY created_at DESC LIMIT 1")
-    .get() as any;
+  const spec = resolveSpec(specId, ["implementing"]);
 
   const taskIds = ids.split(",").map((s) => parseInt(s.trim()));
   const startedTasks: any[] = [];
@@ -411,6 +408,30 @@ export function taskDone(id: string, options: { checkpoint: string; files?: stri
     [checkpoint, now, taskId]
   );
 
+  // v9.3: Registrar performance do agente
+  try {
+    const agentType = task.agent || "general-purpose";
+    const startedAt = task.started_at ? new Date(task.started_at).getTime() : Date.now();
+    const duration = Date.now() - startedAt;
+    const bypassCount = (db.query(
+      "SELECT COUNT(*) as c FROM gate_bypasses WHERE task_id = ?"
+    ).get(taskId) as any)?.c || 0;
+    const totalGates = 7;
+
+    recordAgentPerformance({
+      agentType,
+      specId: spec.id,
+      taskId,
+      gatesPassedFirstTry: Math.max(0, totalGates - bypassCount),
+      gatesTotal: totalGates,
+      bypassesUsed: bypassCount,
+      filesCreated: subagentData?.files_created?.length || 0,
+      filesModified: subagentData?.files_modified?.length || 0,
+      contextSizeBytes: 0,
+      executionDurationMs: duration,
+    });
+  } catch { /* nao-critico: nao falhar task done por tracking de performance */ }
+
   // Registrar artefatos se NAO veio do subagent (ja foi processado acima)
   if (!subagentData && options.files) {
     const files = options.files.split(",").map((s) => s.trim());