@codexa/cli 9.0.14 → 9.0.16

package/commands/architect.test.ts

@@ -237,6 +237,78 @@ describe("parseBabySteps", () => {
     const result = parseBabySteps(section);
     expect(result[0].files).toEqual(["file1.ts", "file2.ts"]);
   });
+
+  // v9.9: Phase support in baby steps
+  it("should parse steps with explicit phase headers", () => {
+    const section = `## Fase 1: Fundacao
+### 1. Create schema
+**O que**: Build database schema
+**Agente**: expert-database
+
+### 2. Setup testes
+**O que**: Configure test framework
+**Agente**: expert-testing
+
+## Fase 2: Core
+### 3. Implement API
+**O que**: Create REST endpoints
+**Agente**: expert-backend
+**Depende de**: 1`;
+
+    const result = parseBabySteps(section);
+    expect(result).toHaveLength(3);
+    expect(result[0].phase).toBe(1);
+    expect(result[1].phase).toBe(1);
+    expect(result[2].phase).toBe(2);
+  });
+
+  it("should not assign phases when no phase headers exist", () => {
+    const section = `### 1. First step
+**O que**: Do first thing
+
+### 2. Second step
+**O que**: Do second thing`;
+
+    const result = parseBabySteps(section);
+    expect(result).toHaveLength(2);
+    expect(result[0].phase).toBeUndefined();
+    expect(result[1].phase).toBeUndefined();
+  });
+
+  it("should handle 'Phase N:' header format (English)", () => {
+    const section = `## Phase 1: Foundation
+### 1. Create schema
+**O que**: Build database
+
+## Phase 2: Features
+### 2. Implement API
+**O que**: Create endpoints`;
+
+    const result = parseBabySteps(section);
+    expect(result).toHaveLength(2);
+    expect(result[0].phase).toBe(1);
+    expect(result[1].phase).toBe(2);
+  });
+
+  it("should parse 3+ phases correctly", () => {
+    const section = `## Fase 1: Base
+### 1. Step one
+**O que**: First
+
+## Fase 2: Core
+### 2. Step two
+**O que**: Second
+
+## Fase 3: Polish
+### 3. Step three
+**O que**: Third`;
+
+    const result = parseBabySteps(section);
+    expect(result).toHaveLength(3);
+    expect(result[0].phase).toBe(1);
+    expect(result[1].phase).toBe(2);
+    expect(result[2].phase).toBe(3);
+  });
 });
 
 describe("parseRisks", () => {

package/commands/architect.ts

@@ -17,6 +17,7 @@ export interface BabyStep {
   files: string[];
   agent: string;
   dependsOn?: number[];
+  phase?: number;
 }
 
 export interface Risk {
@@ -180,36 +181,85 @@ export function extractSection(content: string, header: string): string {
 export function parseBabySteps(section: string): BabyStep[] {
   if (!section) return [];
   const steps: BabyStep[] = [];
-  // Match "### N. Name" or "### Step N: Name"
-  const stepBlocks = section.split(/^###\s+/m).filter(Boolean);
 
-  for (const block of stepBlocks) {
-    const headerMatch = block.match(/^(?:Step\s+)?(\d+)[.:]\s*(.+)/);
-    if (!headerMatch) continue;
+  // Detect phase headers: "## Fase N:" or "## Phase N:"
+  let currentPhase = 1;
+  let hasExplicitPhases = false;
+  const phaseRegex = /^##\s+(?:Fase|Phase)\s+(\d+)/im;
+  if (phaseRegex.test(section)) {
+    hasExplicitPhases = true;
+  }
 
-    const number = parseInt(headerMatch[1]);
-    const name = headerMatch[2].trim();
-    const what = block.match(/\*\*O que\*\*:\s*(.+)/)?.[1]?.trim() || "";
-    const why = block.match(/\*\*Por que\*\*:\s*(.+)/)?.[1]?.trim() || "";
-    const result = block.match(/\*\*Resultado\*\*:\s*(.+)/)?.[1]?.trim() || "";
-    const filesStr = block.match(/\*\*Arquivos?\*\*:\s*(.+)/)?.[1]?.trim() || "";
-    const agent = block.match(/\*\*Agente\*\*:\s*(.+)/)?.[1]?.trim() || "general";
-    const depsStr = block.match(/\*\*Depende de\*\*:\s*(.+)/)?.[1]?.trim() || "";
+  // Split by phase headers first, then by step headers
+  // We process the section line-by-line to track phase context
+  const lines = section.split("\n");
+  let currentBlock = "";
+  let blockPhase = currentPhase;
 
-    const files = filesStr
-      ? filesStr.split(/[,;]/).map(f => f.trim().replace(/`/g, "")).filter(Boolean)
-      : [];
+  for (const line of lines) {
+    const phaseMatch = line.match(/^##\s+(?:Fase|Phase)\s+(\d+)/i);
+    if (phaseMatch) {
+      // Process pending block BEFORE changing phase
+      if (currentBlock.trim()) {
+        const step = parseStepBlock(currentBlock, hasExplicitPhases ? blockPhase : undefined);
+        if (step) steps.push(step);
+        currentBlock = "";
+      }
+      currentPhase = parseInt(phaseMatch[1]);
+      blockPhase = currentPhase;
+      continue;
+    }
 
-    const dependsOn = depsStr
-      ? (depsStr.match(/\d+/g) || []).map(Number)
-      : [];
+    // When we hit a new step header, process the previous block
+    if (line.match(/^###\s+/) && currentBlock.trim()) {
+      const step = parseStepBlock(currentBlock, hasExplicitPhases ? blockPhase : undefined);
+      if (step) steps.push(step);
+      currentBlock = line + "\n";
+      blockPhase = currentPhase;
+    } else {
+      currentBlock += line + "\n";
+    }
+  }
 
-    steps.push({ number, name, what, why, result, files, agent, dependsOn: dependsOn.length > 0 ? dependsOn : undefined });
+  // Process the last block
+  if (currentBlock.trim()) {
+    const step = parseStepBlock(currentBlock, hasExplicitPhases ? blockPhase : undefined);
+    if (step) steps.push(step);
   }
 
   return steps;
 }
 
+function parseStepBlock(block: string, phase?: number): BabyStep | null {
+  // Remove leading "### " prefix for matching
+  const content = block.replace(/^###\s+/, "");
+  const headerMatch = content.match(/^(?:Step\s+)?(\d+)[.:]\s*(.+)/);
+  if (!headerMatch) return null;
+
+  const number = parseInt(headerMatch[1]);
+  const name = headerMatch[2].trim();
+  const what = block.match(/\*\*O que\*\*:\s*(.+)/)?.[1]?.trim() || "";
+  const why = block.match(/\*\*Por que\*\*:\s*(.+)/)?.[1]?.trim() || "";
+  const result = block.match(/\*\*Resultado\*\*:\s*(.+)/)?.[1]?.trim() || "";
+  const filesStr = block.match(/\*\*Arquivos?\*\*:\s*(.+)/)?.[1]?.trim() || "";
+  const agent = block.match(/\*\*Agente\*\*:\s*(.+)/)?.[1]?.trim() || "general";
+  const depsStr = block.match(/\*\*Depende de\*\*:\s*(.+)/)?.[1]?.trim() || "";
+
+  const files = filesStr
+    ? filesStr.split(/[,;]/).map(f => f.trim().replace(/`/g, "")).filter(Boolean)
+    : [];
+
+  const dependsOn = depsStr
+    ? (depsStr.match(/\d+/g) || []).map(Number)
+    : [];
+
+  return {
+    number, name, what, why, result, files, agent,
+    dependsOn: dependsOn.length > 0 ? dependsOn : undefined,
+    phase,
+  };
+}
+
 export function parseRisks(section: string): Risk[] {
   if (!section) return [];
   const risks: Risk[] = [];

package/commands/plan.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "bun:test";
-import { generateSpecId } from "./plan";
+import { generateSpecId, estimateContextPressure, assignPhases, SAFE_TASKS_PER_PHASE } from "./plan";
 
 describe("generateSpecId", () => {
   it("generates ID with date-slug-hash format", () => {
@@ -71,3 +71,151 @@ describe("generateSpecId", () => {
     expect(id).toContain("add-user-auth");
   });
 });
+
+// ═══════════════════════════════════════════════════════════════
+// v9.9: Context Pressure Budget Calculator
+// ═══════════════════════════════════════════════════════════════
+
+describe("estimateContextPressure", () => {
+  it("returns green for small task counts", () => {
+    const result = estimateContextPressure(5);
+    expect(result.level).toBe("green");
+    expect(result.taskCount).toBe(5);
+    expect(result.suggestedPhases).toBe(1);
+  });
+
+  it("returns green at the threshold boundary", () => {
+    const result = estimateContextPressure(SAFE_TASKS_PER_PHASE);
+    expect(result.level).toBe("green");
+    expect(result.suggestedPhases).toBe(1);
+  });
+
+  it("returns yellow for moderate task counts", () => {
+    const result = estimateContextPressure(18);
+    expect(result.level).toBe("yellow");
+    expect(result.suggestedPhases).toBe(2);
+  });
+
+  it("returns red for large task counts", () => {
+    const result = estimateContextPressure(30);
+    expect(result.level).toBe("red");
+    expect(result.suggestedPhases).toBe(3);
+  });
+
+  it("calculates decision coverage correctly", () => {
+    const result = estimateContextPressure(10);
+    // 10 tasks * 3 decisions = 30, coverage = 8/30 = 27%
+    expect(result.estimatedDecisions).toBe(30);
+    expect(result.decisionCoverage).toBe(27);
+  });
+
+  it("caps coverage at 100%", () => {
+    const result = estimateContextPressure(1);
+    // 1 task * 3 = 3 decisions, 8/3 = 267% -> capped at 100
+    expect(result.decisionCoverage).toBe(100);
+    expect(result.knowledgeCoverage).toBe(100);
+  });
+
+  it("respects custom maxPerPhase", () => {
+    const result = estimateContextPressure(20, 20);
+    expect(result.level).toBe("green");
+    expect(result.suggestedPhases).toBe(1);
+    expect(result.maxTasksPerPhase).toBe(20);
+  });
+
+  it("suggests correct number of phases for 38 tasks", () => {
+    const result = estimateContextPressure(38);
+    expect(result.level).toBe("red");
+    expect(result.suggestedPhases).toBe(4); // ceil(38/12) = 4
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════
+// v9.9: Phase Auto-Assignment (Topological Sort)
+// ═══════════════════════════════════════════════════════════════
+
+describe("assignPhases", () => {
+  it("assigns single phase for small task lists", () => {
+    const tasks = [
+      { number: 1, dependsOn: [] },
+      { number: 2, dependsOn: [1] },
+      { number: 3, dependsOn: [2] },
+    ];
+    const result = assignPhases(tasks, 12);
+    expect(result.get(1)).toBe(1);
+    expect(result.get(2)).toBe(1);
+    expect(result.get(3)).toBe(1);
+  });
+
+  it("splits tasks into phases based on topological depth", () => {
+    // Create 15 tasks: levels 0-4 with 3 tasks each
+    const tasks = [];
+    for (let i = 1; i <= 15; i++) {
+      const level = Math.floor((i - 1) / 3);
+      const deps = level > 0 ? [(level - 1) * 3 + 1] : [];
+      tasks.push({ number: i, dependsOn: deps });
+    }
+    const result = assignPhases(tasks, 6);
+
+    // Should split into at least 2 phases
+    const phases = new Set(result.values());
+    expect(phases.size).toBeGreaterThanOrEqual(2);
+  });
+
+  it("returns empty map for empty task list", () => {
+    const result = assignPhases([], 12);
+    expect(result.size).toBe(0);
+  });
+
+  it("handles independent tasks (no dependencies)", () => {
+    const tasks = Array.from({ length: 20 }, (_, i) => ({
+      number: i + 1,
+      dependsOn: [] as number[],
+    }));
+    const result = assignPhases(tasks, 10);
+
+    // All independent tasks are at level 0, but can't fit in one phase
+    // They should be split: 10 in phase 1, 10 in phase 2
+    const phases = new Set(result.values());
+    expect(phases.size).toBe(2);
+  });
+
+  it("respects dependency order across phases", () => {
+    const tasks = [
+      { number: 1, dependsOn: [] },
+      { number: 2, dependsOn: [] },
+      { number: 3, dependsOn: [1, 2] },
+      { number: 4, dependsOn: [3] },
+    ];
+    const result = assignPhases(tasks, 3);
+
+    // Task 3 depends on 1 and 2, so it must be in same or later phase
+    const phase1 = result.get(1)!;
+    const phase3 = result.get(3)!;
+    const phase4 = result.get(4)!;
+    expect(phase3).toBeGreaterThanOrEqual(phase1);
+    expect(phase4).toBeGreaterThanOrEqual(phase3);
+  });
+
+  it("handles a linear chain exceeding maxPerPhase", () => {
+    // 6 tasks in a linear chain, max 2 per phase
+    const tasks = [
+      { number: 1, dependsOn: [] },
+      { number: 2, dependsOn: [1] },
+      { number: 3, dependsOn: [2] },
+      { number: 4, dependsOn: [3] },
+      { number: 5, dependsOn: [4] },
+      { number: 6, dependsOn: [5] },
+    ];
+    const result = assignPhases(tasks, 2);
+
+    // Each level has 1 task, so we accumulate 2 per phase
+    const phases = new Set(result.values());
+    expect(phases.size).toBe(3);
+
+    // Verify order is preserved
+    for (let i = 1; i <= 5; i++) {
+      expect(result.get(i)!).toBeLessThanOrEqual(result.get(i + 1)!);
+    }
+  });
+});

package/commands/plan.ts

@@ -2,7 +2,144 @@ import { getDb } from "../db/connection";
 import { initSchema, getArchitecturalAnalysisForSpec } from "../db/schema";
 import { resolveSpec } from "./spec-resolver";
 import { CodexaError, ValidationError } from "../errors";
-import { resolveAgent, resolveAgentName, suggestAgent, getCanonicalAgentNames } from "../context/agent-registry";
+import { resolveAgent, resolveAgentName, suggestAgent, getCanonicalAgentNames, getAgentsByDomain } from "../context/agent-registry";
+
+// ═══════════════════════════════════════════════════════════════
+// CONTEXT PRESSURE: Budget Calculator + Phase Auto-Assignment
+// ═══════════════════════════════════════════════════════════════
+
+export const SAFE_TASKS_PER_PHASE = 12;
+const DECISIONS_PER_TASK = 3;
+const KNOWLEDGE_PER_TASK = 5;
+const MAX_DECISIONS_IN_CONTEXT = 8;
+const MAX_KNOWLEDGE_IN_CONTEXT = 30; // 20 critical + 10 info
+
+export type PressureLevel = "green" | "yellow" | "red";
+
+export interface ContextPressureEstimate {
+    level: PressureLevel;
+    taskCount: number;
+    estimatedDecisions: number;
+    decisionCoverage: number;
+    estimatedKnowledge: number;
+    knowledgeCoverage: number;
+    suggestedPhases: number;
+    maxTasksPerPhase: number;
+}
+
+export function estimateContextPressure(taskCount: number, maxPerPhase: number = SAFE_TASKS_PER_PHASE): ContextPressureEstimate {
+    const estimatedDecisions = taskCount * DECISIONS_PER_TASK;
+    const estimatedKnowledge = taskCount * KNOWLEDGE_PER_TASK;
+    const decisionCoverage = Math.min(100, Math.round((MAX_DECISIONS_IN_CONTEXT / estimatedDecisions) * 100));
+    const knowledgeCoverage = Math.min(100, Math.round((MAX_KNOWLEDGE_IN_CONTEXT / estimatedKnowledge) * 100));
+
+    let level: PressureLevel = "green";
+    if (taskCount > 25) level = "red";
+    else if (taskCount > maxPerPhase) level = "yellow";
+
+    const suggestedPhases = Math.max(1, Math.ceil(taskCount / maxPerPhase));
+
+    return {
+        level,
+        taskCount,
+        estimatedDecisions,
+        decisionCoverage,
+        estimatedKnowledge,
+        knowledgeCoverage,
+        suggestedPhases,
+        maxTasksPerPhase: maxPerPhase,
+    };
+}
+
+interface TaskForPhasing {
+    number: number;
+    dependsOn: number[];
+    phase?: number;
+}
+
+export function assignPhases(tasks: TaskForPhasing[], maxPerPhase: number = SAFE_TASKS_PER_PHASE): Map<number, number> {
+    const phaseMap = new Map<number, number>();
+    if (tasks.length === 0) return phaseMap;
+
+    // Build dependency graph and compute topological depth via BFS
+    const depthMap = new Map<number, number>();
+    const taskNums = new Set(tasks.map(t => t.number));
+    const depsOf = new Map<number, number[]>();
+    for (const t of tasks) {
+        depsOf.set(t.number, t.dependsOn.filter(d => taskNums.has(d)));
+    }
+
+    // Kahn's algorithm for topological levels
+    const inDegree = new Map<number, number>();
+    const children = new Map<number, number[]>();
+    for (const t of tasks) {
+        inDegree.set(t.number, 0);
+        children.set(t.number, []);
+    }
+    for (const t of tasks) {
+        for (const dep of depsOf.get(t.number) || []) {
+            inDegree.set(t.number, (inDegree.get(t.number) || 0) + 1);
+            children.get(dep)?.push(t.number);
+        }
+    }
+
+    // BFS by level
+    let queue = tasks.filter(t => (inDegree.get(t.number) || 0) === 0).map(t => t.number);
+    let level = 0;
+    while (queue.length > 0) {
+        const nextQueue: number[] = [];
+        for (const num of queue) {
+            depthMap.set(num, level);
+            for (const child of children.get(num) || []) {
+                inDegree.set(child, (inDegree.get(child) || 0) - 1);
+                if ((inDegree.get(child) || 0) === 0) {
+                    nextQueue.push(child);
+                }
+            }
+        }
+        queue = nextQueue;
+        level++;
+    }
+
+    // Handle cycles (tasks not reached): assign max level
+    for (const t of tasks) {
+        if (!depthMap.has(t.number)) {
+            depthMap.set(t.number, level);
+        }
+    }
+
+    // Group by level, then assign phases by accumulating up to maxPerPhase
+    const maxLevel = Math.max(...Array.from(depthMap.values()));
+    let currentPhase = 1;
+    let tasksInCurrentPhase = 0;
+
+    for (let l = 0; l <= maxLevel; l++) {
+        const levelTasks = tasks.filter(t => depthMap.get(t.number) === l);
+        if (levelTasks.length === 0) continue;
+
+        // If adding this level would exceed max, start a new phase
+        if (tasksInCurrentPhase > 0 && tasksInCurrentPhase + levelTasks.length > maxPerPhase) {
+            currentPhase++;
+            tasksInCurrentPhase = 0;
+        }
+
+        // Handle levels with more tasks than maxPerPhase (split within level)
+        for (const t of levelTasks) {
+            if (tasksInCurrentPhase >= maxPerPhase) {
+                currentPhase++;
+                tasksInCurrentPhase = 0;
+            }
+            phaseMap.set(t.number, currentPhase);
+            tasksInCurrentPhase++;
+        }
+    }
+
+    return phaseMap;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// COMMANDS
+// ═══════════════════════════════════════════════════════════════
 
 export function generateSpecId(name: string): string {
     const date = new Date().toISOString().split("T")[0];
@@ -16,7 +153,8 @@ export function generateSpecId(name: string): string {
 }
 
 // v8.4: Suporte a --from-analysis para import automatico de baby steps
-export function planStart(description: string, options: { fromAnalysis?: string; json?: boolean } = {}): void {
+// v9.9: Suporte a fases com budget calculator e auto-split
+export function planStart(description: string, options: { fromAnalysis?: string; json?: boolean; maxTasksPerPhase?: number } = {}): void {
     initSchema();
     const db = getDb();
 
@@ -80,27 +218,52 @@ export function planStart(description: string, options: { fromAnalysis?: string;
     );
 
     // v8.4: Import automatico de baby steps da analise
+    // v9.9: Com suporte a fases (phase column + auto-split)
     let tasksCreated = 0;
+    let totalPhases = 1;
+    const maxPerPhase = options.maxTasksPerPhase || SAFE_TASKS_PER_PHASE;
+
     if (analysis && analysis.baby_steps) {
         try {
             const babySteps = JSON.parse(analysis.baby_steps);
+
+            // v9.9: Determine phases
+            const hasExplicitPhases = babySteps.some((s: any) => s.phase != null);
+            let phaseMap: Map<number, number>;
+
+            if (hasExplicitPhases) {
+                // Use phases from architect markdown
+                phaseMap = new Map(babySteps.map((s: any) => [s.number, s.phase || 1]));
+            } else {
+                // Auto-assign phases based on dependency topology + budget
+                const tasksForPhasing: TaskForPhasing[] = babySteps.map((s: any) => ({
+                    number: s.number,
+                    dependsOn: s.dependsOn || [],
+                }));
+                phaseMap = assignPhases(tasksForPhasing, maxPerPhase);
+            }
+
+            totalPhases = Math.max(1, ...Array.from(phaseMap.values()));
+
             for (const step of babySteps) {
                 const files = step.files && step.files.length > 0 ? JSON.stringify(step.files) : null;
                 const dependsOn = step.dependsOn && step.dependsOn.length > 0 ? JSON.stringify(step.dependsOn) : null;
+                const phase = phaseMap.get(step.number) || 1;
 
                 const normalizedStepAgent = step.agent ? resolveAgentName(step.agent) : null;
                 db.run(
-                    `INSERT INTO tasks (spec_id, number, name, agent, depends_on, can_parallel, files)
-                     VALUES (?, ?, ?, ?, ?, ?, ?)`,
-                    [specId, step.number, step.name, normalizedStepAgent, dependsOn, 1, files]
+                    `INSERT INTO tasks (spec_id, number, name, agent, depends_on, can_parallel, files, phase)
+                     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+                    [specId, step.number, step.name, normalizedStepAgent, dependsOn, 1, files, phase]
                 );
                 tasksCreated++;
             }
 
-            // Atualizar total de tasks no contexto
-            db.run("UPDATE context SET total_tasks = ?, updated_at = ? WHERE spec_id = ?", [
-                tasksCreated, now, specId
-            ]);
+            // Atualizar total de tasks e fases no contexto
+            db.run(
+                "UPDATE context SET total_tasks = ?, total_phases = ?, current_phase = 1, updated_at = ? WHERE spec_id = ?",
+                [tasksCreated, totalPhases, now, specId]
+            );
 
             // Marcar analise como implemented
             db.run(
@@ -114,6 +277,9 @@ export function planStart(description: string, options: { fromAnalysis?: string;
         }
     }
 
+    // v9.9: Context pressure analysis
+    const pressure = tasksCreated > 0 ? estimateContextPressure(tasksCreated, maxPerPhase) : null;
+
     if (options.json) {
         console.log(JSON.stringify({
             success: true,
@@ -122,6 +288,8 @@ export function planStart(description: string, options: { fromAnalysis?: string;
             phase: "planning",
             analysisId: analysis?.id || null,
             tasksImported: tasksCreated,
+            totalPhases,
+            contextPressure: pressure,
         }));
     } else {
         console.log(`\nFeature iniciada: ${description}`);
@@ -131,6 +299,32 @@ export function planStart(description: string, options: { fromAnalysis?: string;
         if (tasksCreated > 0) {
             console.log(`Analise: ${analysis.id}`);
             console.log(`Tasks importadas: ${tasksCreated}`);
+
+            // v9.9: Show pressure warning + phase breakdown
+            if (pressure && pressure.level !== "green") {
+                const icon = pressure.level === "red" ? "[ALTO]" : "[MEDIO]";
+                console.log(`\n${icon} Pressao de contexto: ${pressure.level.toUpperCase()} (${tasksCreated} tasks)`);
+                console.log(`    Apos ~${maxPerPhase} tasks, a qualidade do contexto degrada.`);
+                console.log(`    Cobertura estimada: ${pressure.decisionCoverage}% decisions, ${pressure.knowledgeCoverage}% knowledge`);
+
+                if (totalPhases > 1) {
+                    console.log(`\n    Plano dividido em ${totalPhases} fases:`);
+                    // Count tasks per phase
+                    const tasksByPhase = new Map<number, number>();
+                    const allTasks = db.query("SELECT phase FROM tasks WHERE spec_id = ?").all(specId) as any[];
+                    for (const t of allTasks) {
+                        tasksByPhase.set(t.phase || 1, (tasksByPhase.get(t.phase || 1) || 0) + 1);
+                    }
+                    for (let p = 1; p <= totalPhases; p++) {
+                        const count = tasksByPhase.get(p) || 0;
+                        console.log(`      Fase ${p}: ${count} tasks`);
+                    }
+                    console.log(`\n    Entre cada fase, o contexto sera compactado automaticamente.`);
+                }
+            } else if (totalPhases > 1) {
+                console.log(`\nFases: ${totalPhases} (definidas pela analise arquitetural)`);
+            }
+
             console.log(`\nProximos passos:`);
             console.log(`1. Visualize o plano: plan show`);
             console.log(`2. Solicite aprovacao: check request\n`);
@@ -162,6 +356,9 @@ export function planShow(json: boolean = false, specId?: string): void {
         return;
     }
 
+    const currentPhase = context?.current_phase || 1;
+    const totalPhases = context?.total_phases || 1;
+
     console.log(`\n${"=".repeat(60)}`);
     console.log(`PLANO: ${spec.name}`);
     console.log(`${"=".repeat(60)}`);
@@ -176,25 +373,53 @@ export function planShow(json: boolean = false, specId?: string): void {
         return;
     }
 
-    console.log(`\nTasks (${tasks.length}):`);
-    console.log(`${"─".repeat(60)}`);
+    // v9.9: Show phase-aware progress
+    if (totalPhases > 1) {
+        const totalDone = tasks.filter(t => t.status === "done").length;
+        const phaseTasks = tasks.filter(t => (t.phase || 1) === currentPhase);
+        const phaseDone = phaseTasks.filter(t => t.status === "done").length;
+        console.log(`\nFase atual: ${currentPhase}/${totalPhases}`);
+        console.log(`Progresso: ${phaseDone}/${phaseTasks.length} (fase ${currentPhase}) | ${totalDone}/${tasks.length} (total)`);
+    }
 
-    for (const task of tasks) {
-        const deps = task.depends_on ? JSON.parse(task.depends_on) : [];
-        const depsStr = deps.length > 0 ? ` [deps: ${deps.join(",")}]` : "";
-        const parallelStr = task.can_parallel ? " ||" : "";
-        const statusIcon =
-            task.status === "done" ? "[x]" :
-                task.status === "running" ? "[>]" :
-                    task.status === "failed" ? "[!]" : "[ ]";
+    // v9.9: Group tasks by phase
+    if (totalPhases > 1) {
+        for (let phase = 1; phase <= totalPhases; phase++) {
+            const phaseTasks = tasks.filter(t => (t.phase || 1) === phase);
+            if (phaseTasks.length === 0) continue;
 
-        console.log(`${statusIcon} #${task.number}: ${task.name} (${task.agent || "geral"})${depsStr}${parallelStr}`);
+            const phaseLabel = phase === currentPhase ? "(atual)" :
+                phase < currentPhase ? "(concluida)" : "(bloqueada)";
+            console.log(`\n--- Fase ${phase} ${phaseLabel} ---`);
+
+            for (const task of phaseTasks) {
+                printTaskLine(task);
+            }
+        }
+    } else {
+        console.log(`\nTasks (${tasks.length}):`);
+        console.log(`${"─".repeat(60)}`);
+        for (const task of tasks) {
+            printTaskLine(task);
+        }
     }
 
     console.log(`${"─".repeat(60)}`);
     console.log(`Legenda: [ ] pendente  [>] executando  [x] concluido  || paralelizavel\n`);
 }
 
+function printTaskLine(task: any): void {
+    const deps = task.depends_on ? JSON.parse(task.depends_on) : [];
+    const depsStr = deps.length > 0 ? ` [deps: ${deps.join(",")}]` : "";
+    const parallelStr = task.can_parallel ? " ||" : "";
+    const statusIcon =
+        task.status === "done" ? "[x]" :
+            task.status === "running" ? "[>]" :
+                task.status === "failed" ? "[!]" : "[ ]";
+
+    console.log(`${statusIcon} #${task.number}: ${task.name} (${task.agent || "geral"})${depsStr}${parallelStr}`);
+}
+
 export function planTaskAdd(options: {
     name: string;
     agent?: string;
@@ -273,6 +498,14 @@ export function planTaskAdd(options: {
     if (normalizedAgent) {
         const entry = resolveAgent(normalizedAgent);
         if (!entry) {
+            // Check if it's an ambiguous domain name (multiple agents)
+            const domainAgents = getAgentsByDomain(normalizedAgent.toLowerCase());
+            if (domainAgents.length > 1) {
+                const agentList = domainAgents.map(a => `"${a.canonical}"`).join(", ");
+                throw new ValidationError(
+                    `"${normalizedAgent}" e um dominio com ${domainAgents.length} agentes: ${agentList}.\nEspecifique qual agente usar.`
+                );
+            }
             const suggestion = suggestAgent(normalizedAgent);
             const hint = suggestion
                 ? `\nVoce quis dizer: "${suggestion}"?`

package/commands/task.ts

@@ -4,7 +4,7 @@ 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 } from "./knowledge";
+import { getUnreadKnowledgeForTask, compactKnowledge } from "./knowledge";
 import { loadTemplate } from "../templates/loader";
 import { TaskStateError, ValidationError, KnowledgeBlockError } from "../errors";
 import { resolveSpec, resolveSpecOrNull } from "./spec-resolver";
@@ -26,6 +26,11 @@ export function taskNext(json: boolean = false, specId?: string): void {
     throw new TaskStateError("Nenhuma feature em fase de implementacao.\nAprove o plano com: check approve");
   }
 
+  // v9.9: Get current phase info
+  const context = db.query("SELECT * FROM context WHERE spec_id = ?").get(spec.id) as any;
+  const currentPhase = context?.current_phase || 1;
+  const totalPhases = context?.total_phases || 1;
+
   // Buscar tasks pendentes cujas dependencias estao todas concluidas
   const allTasks = db
     .query("SELECT * FROM tasks WHERE spec_id = ? ORDER BY number")
@@ -36,6 +41,9 @@ export function taskNext(json: boolean = false, specId?: string): void {
   for (const task of allTasks) {
     if (task.status !== "pending") continue;
 
+    // v9.9: Only show tasks from current phase (if phases are configured)
+    if (totalPhases > 1 && (task.phase || 1) !== currentPhase) continue;
+
     // Verificar dependencias
     const deps = task.depends_on ? JSON.parse(task.depends_on) : [];
     const allDepsDone = deps.every((depNum: number) => {
@@ -49,13 +57,25 @@ export function taskNext(json: boolean = false, specId?: string): void {
   }
 
   if (json) {
-    console.log(JSON.stringify({ available }));
+    console.log(JSON.stringify({ available, currentPhase, totalPhases }));
     return;
   }
 
   if (available.length === 0) {
+    // v9.9: Check if current phase is complete but more phases remain
+    if (totalPhases > 1) {
+      const phaseTasks = allTasks.filter((t) => (t.phase || 1) === currentPhase);
+      const phaseDone = phaseTasks.every((t) => t.status === "done");
+
+      if (phaseDone && currentPhase < totalPhases) {
+        console.log(`\nFase ${currentPhase}/${totalPhases} concluida!`);
+        console.log(`Avance para a proxima fase com: task phase-advance\n`);
+        return;
+      }
+    }
+
     // Verificar se todas estao concluidas
-    const pending = allTasks.filter((t) => t.status !== "done");
+    const pending = allTasks.filter((t) => t.status !== "done" && t.status !== "cancelled");
     if (pending.length === 0) {
       console.log("\nTodas as tasks foram concluidas!");
       console.log("Inicie o review com: review start\n");
@@ -72,6 +92,13 @@ export function taskNext(json: boolean = false, specId?: string): void {
     return;
   }
 
+  // v9.9: Show phase context
+  if (totalPhases > 1) {
+    const phaseTasks = allTasks.filter((t) => (t.phase || 1) === currentPhase);
+    const phaseDone = phaseTasks.filter((t) => t.status === "done").length;
+    console.log(`\nFase ${currentPhase}/${totalPhases} (${phaseDone}/${phaseTasks.length} concluidas)`);
+  }
+
   console.log(`\nTasks disponiveis para execucao (${available.length}):`);
   console.log(`${"─".repeat(50)}`);
 
@@ -493,10 +520,48 @@ export function taskDone(id: string, options: { checkpoint: string; files?: stri
     [checkpoint, now, spec.id]
   );
 
+  // v9.9: Phase-aware progress
+  const ctx = db.query("SELECT * FROM context WHERE spec_id = ?").get(spec.id) as any;
+  const currentPhase = ctx?.current_phase || 1;
+  const totalPhases = ctx?.total_phases || 1;
+
   console.log(`\nTask #${task.number} concluida!`);
   console.log(`Checkpoint: ${options.checkpoint}`);
   console.log(`Progresso: ${doneCount.c}/${totalCount.c} tasks`);
 
+  if (totalPhases > 1) {
+    const phaseTasks = db
+      .query("SELECT * FROM tasks WHERE spec_id = ? AND phase = ?")
+      .all(spec.id, currentPhase) as any[];
+    const phaseDone = phaseTasks.filter((t: any) => t.status === "done").length;
+    console.log(`Fase ${currentPhase}/${totalPhases}: ${phaseDone}/${phaseTasks.length} tasks`);
+
+    if (phaseDone === phaseTasks.length && currentPhase < totalPhases) {
+      // Phase complete — show phase summary
+      const phaseDecisions = db
+        .query("SELECT COUNT(*) as c FROM decisions WHERE spec_id = ?")
+        .get(spec.id) as any;
+      const phaseKnowledge = db
+        .query("SELECT COUNT(*) as c FROM knowledge WHERE spec_id = ? AND severity != 'archived'")
+        .get(spec.id) as any;
+
+      const nextPhaseTasks = db
+        .query("SELECT COUNT(*) as c FROM tasks WHERE spec_id = ? AND phase = ?")
+        .get(spec.id, currentPhase + 1) as any;
+
+      console.log(`\n${"=".repeat(55)}`);
+      console.log(`FASE ${currentPhase} CONCLUIDA (${phaseDone}/${phaseTasks.length} tasks)`);
+      console.log(`${"=".repeat(55)}`);
+      console.log(`  Decisions acumuladas: ${phaseDecisions.c}`);
+      console.log(`  Knowledge acumulado: ${phaseKnowledge.c}`);
+      console.log(`\n  Proxima fase: ${currentPhase + 1}/${totalPhases} (${nextPhaseTasks?.c || 0} tasks)`);
+      console.log(`\n  Recomendacao: Compactar contexto antes de continuar`);
+      console.log(`  -> codexa task phase-advance [--no-compact] [--spec ${spec.id}]`);
+      console.log(`${"=".repeat(55)}\n`);
+      return;
+    }
+  }
+
   if (doneCount.c === totalCount.c) {
     // Mostrar resumo completo da implementacao
     const allTasks = db.query("SELECT * FROM tasks WHERE spec_id = ?").all(spec.id) as any[];
@@ -613,4 +678,86 @@ function showImplementationSummary(
   console.log(`  Para pular o review:    review skip`);
   console.log(`\n  O agente aguarda sua decisao.`);
   console.log(`${"─".repeat(50)}\n`);
+}
+
+// v9.9: Phase advance — compact context and move to next phase
+export function taskPhaseAdvance(options: { noCompact?: boolean; spec?: string } = {}): void {
+  initSchema();
+  const db = getDb();
+
+  const spec = resolveSpec(options.spec, ["implementing"]);
+  const ctx = db.query("SELECT * FROM context WHERE spec_id = ?").get(spec.id) as any;
+  const currentPhase = ctx?.current_phase || 1;
+  const totalPhases = ctx?.total_phases || 1;
+
+  if (totalPhases <= 1) {
+    console.log("\nEsta feature nao possui multiplas fases.\n");
+    return;
+  }
+
+  if (currentPhase >= totalPhases) {
+    console.log("\nTodas as fases ja foram concluidas!");
+    console.log("Inicie o review com: review start\n");
+    return;
+  }
+
+  // Verify current phase is fully complete
+  const phaseTasks = db
+    .query("SELECT * FROM tasks WHERE spec_id = ? AND phase = ?")
+    .all(spec.id, currentPhase) as any[];
+  const pendingInPhase = phaseTasks.filter((t: any) => t.status !== "done" && t.status !== "cancelled");
+
+  if (pendingInPhase.length > 0) {
+    console.log(`\n[ERRO] Fase ${currentPhase} nao esta completa.`);
+    console.log(`  Tasks pendentes: ${pendingInPhase.map((t: any) => `#${t.number}`).join(", ")}`);
+    console.log(`  Complete todas as tasks antes de avancar.\n`);
+    return;
+  }
+
+  const now = new Date().toISOString();
+
+  // Compact knowledge (unless --no-compact)
+  if (!options.noCompact) {
+    console.log(`\nCompactando contexto da fase ${currentPhase}...`);
+    compactKnowledge({ specId: spec.id });
+  }
+
+  // Create phase summary as critical knowledge
+  const phaseTaskNames = phaseTasks.map((t: any) => t.name).join(", ");
+  const decisionCount = (db.query("SELECT COUNT(*) as c FROM decisions WHERE spec_id = ?").get(spec.id) as any).c;
+  const artifactCount = (db.query("SELECT COUNT(*) as c FROM artifacts WHERE spec_id = ?").get(spec.id) as any).c;
+
+  const summaryContent = `Resumo Fase ${currentPhase}: ${phaseTasks.length} tasks concluidas (${phaseTaskNames.substring(0, 200)}). ${decisionCount} decisions, ${artifactCount} artefatos acumulados.`;
+
+  db.run(
+    `INSERT INTO knowledge (spec_id, category, content, severity, source, created_at)
+     VALUES (?, 'phase_summary', ?, 'critical', 'system', ?)`,
+    [spec.id, summaryContent, now]
+  );
+
+  // Advance to next phase
+  const nextPhase = currentPhase + 1;
+  db.run(
+    "UPDATE context SET current_phase = ?, updated_at = ? WHERE spec_id = ?",
+    [nextPhase, now, spec.id]
+  );
+
+  // Show next phase info
+  const nextPhaseTasks = db
+    .query("SELECT * FROM tasks WHERE spec_id = ? AND phase = ? ORDER BY number")
+    .all(spec.id, nextPhase) as any[];
+
+  console.log(`\n${"=".repeat(55)}`);
+  console.log(`FASE ${nextPhase}/${totalPhases} INICIADA`);
+  console.log(`${"=".repeat(55)}`);
+  console.log(`  Tasks nesta fase: ${nextPhaseTasks.length}`);
+
+  for (const t of nextPhaseTasks) {
+    const deps = t.depends_on ? JSON.parse(t.depends_on) : [];
+    const depsStr = deps.length > 0 ? ` [deps: ${deps.join(",")}]` : "";
+    console.log(`    #${t.number}: ${t.name} (${t.agent || "geral"})${depsStr}`);
+  }
+
+  console.log(`\n  Proxima task: task next`);
+  console.log(`${"=".repeat(55)}\n`);
 }

package/context/agent-registry.test.ts

@@ -7,6 +7,7 @@ import {
   buildAgentDomainMap,
   getAllAgentNames,
   getCanonicalAgentNames,
+  getAgentsByDomain,
 } from "./agent-registry";
 
 // ── AGENT_REGISTRY structure ─────────────────────────────────
@@ -90,6 +91,27 @@ describe("resolveAgent", () => {
   it("returns null for empty/null-like input", () => {
     expect(resolveAgent("")).toBeNull();
   });
+
+  // Domain-based resolution (v9.5)
+  it("resolves unambiguous domain names (1 agent in domain)", () => {
+    expect(resolveAgent("database")?.canonical).toBe("expert-postgres-developer");
+    expect(resolveAgent("testing")?.canonical).toBe("testing-unit");
+    expect(resolveAgent("review")?.canonical).toBe("expert-code-reviewer");
+    expect(resolveAgent("security")?.canonical).toBe("security-specialist");
+    expect(resolveAgent("explore")?.canonical).toBe("deep-explore");
+    expect(resolveAgent("architecture")?.canonical).toBe("architect");
+  });
+
+  it("returns null for ambiguous domain names (multiple agents)", () => {
+    // frontend has nextjs + flutter, backend has go + csharp + js
+    expect(resolveAgent("frontend")).toBeNull();
+    expect(resolveAgent("backend")).toBeNull();
+  });
+
+  it("domain resolution is case-insensitive", () => {
+    expect(resolveAgent("DATABASE")?.canonical).toBe("expert-postgres-developer");
+    expect(resolveAgent("Testing")?.canonical).toBe("testing-unit");
+  });
 });
 
 // ── resolveAgentName ─────────────────────────────────────────
@@ -111,6 +133,16 @@ describe("resolveAgentName", () => {
     expect(resolveAgentName("custom-agent")).toBe("custom-agent");
     expect(resolveAgentName("my-special-agent")).toBe("my-special-agent");
   });
+
+  it("resolves unambiguous domain names to canonical", () => {
+    expect(resolveAgentName("database")).toBe("expert-postgres-developer");
+    expect(resolveAgentName("testing")).toBe("testing-unit");
+  });
+
+  it("returns ambiguous domain names unchanged (backward compat)", () => {
+    expect(resolveAgentName("frontend")).toBe("frontend");
+    expect(resolveAgentName("backend")).toBe("backend");
+  });
 });
 
 // ── suggestAgent ─────────────────────────────────────────────
@@ -163,6 +195,35 @@ describe("buildAgentDomainMap", () => {
   });
 });
 
+// ── getAgentsByDomain ────────────────────────────────────────
+
+describe("getAgentsByDomain", () => {
+  it("returns agents in multi-agent domains", () => {
+    const frontend = getAgentsByDomain("frontend");
+    expect(frontend).toHaveLength(2);
+    expect(frontend.map(a => a.canonical)).toContain("expert-nextjs-developer");
+    expect(frontend.map(a => a.canonical)).toContain("frontend-flutter");
+
+    const backend = getAgentsByDomain("backend");
+    expect(backend).toHaveLength(3);
+  });
+
+  it("returns agents in single-agent domains", () => {
+    const database = getAgentsByDomain("database");
+    expect(database).toHaveLength(1);
+    expect(database[0].canonical).toBe("expert-postgres-developer");
+
+    const testing = getAgentsByDomain("testing");
+    expect(testing).toHaveLength(1);
+    expect(testing[0].canonical).toBe("testing-unit");
+  });
+
+  it("returns empty array for unknown domains", () => {
+    expect(getAgentsByDomain("unknown")).toHaveLength(0);
+    expect(getAgentsByDomain("general")).toHaveLength(0);
+  });
+});
+
 // ── getAllAgentNames / getCanonicalAgentNames ─────────────────
 
 describe("getAllAgentNames", () => {

package/context/agent-registry.ts

@@ -115,12 +115,21 @@ for (const entry of AGENT_REGISTRY) {
 
 /**
  * Resolve any agent name variant (canonical, filename, alias) to registry entry.
- * Case-insensitive. Returns null if no match found.
+ * Case-insensitive. Falls back to domain-based resolution when exactly 1 agent
+ * exists in the matching domain (e.g., "database" → expert-postgres-developer).
+ * Returns null if no match found or if domain has multiple agents (ambiguous).
  */
 export function resolveAgent(name: string): AgentEntry | null {
   if (!name) return null;
   const lower = name.toLowerCase();
-  return byCanonical.get(lower) ?? byAlias.get(lower) ?? null;
+  const direct = byCanonical.get(lower) ?? byAlias.get(lower);
+  if (direct) return direct;
+
+  // Domain fallback: resolve "frontend", "backend", etc. when unambiguous
+  const domainAgents = getAgentsByDomain(lower);
+  if (domainAgents.length === 1) return domainAgents[0];
+
+  return null;
 }
 
 /**
@@ -171,6 +180,14 @@ export function suggestAgent(input: string): string | null {
   return null;
 }
 
+/**
+ * Get all agents belonging to a specific domain.
+ * Used for domain-based resolution (e.g., "frontend" → agents in frontend domain).
+ */
+export function getAgentsByDomain(domain: string): AgentEntry[] {
+  return AGENT_REGISTRY.filter(e => e.domain === domain);
+}
+
 /**
  * Derive AGENT_DOMAIN map from registry (backward compat with domains.ts).
  */

package/db/schema.ts

@@ -487,6 +487,15 @@ const MIGRATIONS: Migration[] = [
       db.exec(`ALTER TABLE project ADD COLUMN grepai_workspace TEXT`);
     },
   },
+  {
+    version: "9.9.0",
+    description: "Adicionar suporte a fases: phase em tasks, total_phases/current_phase em context",
+    up: (db) => {
+      db.exec(`ALTER TABLE tasks ADD COLUMN phase INTEGER DEFAULT 1`);
+      db.exec(`ALTER TABLE context ADD COLUMN total_phases INTEGER DEFAULT 1`);
+      db.exec(`ALTER TABLE context ADD COLUMN current_phase INTEGER DEFAULT 1`);
+    },
+  },
 ];
 
 export function runMigrations(): void {

package/package.json

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

package/workflow.ts

@@ -3,7 +3,7 @@
 import { Command } from "commander";
 import { planStart, planShow, planTaskAdd, planCancel } from "./commands/plan";
 import { checkRequest, checkApprove, checkReject } from "./commands/check";
-import { taskNext, taskStart, taskDone } from "./commands/task";
+import { taskNext, taskStart, taskDone, taskPhaseAdvance } from "./commands/task";
 import { decide, listDecisions, revokeDecision, supersedeDecision } from "./commands/decide";
 import { reviewStart, reviewApprove, reviewSkip } from "./commands/review";
 import { addKnowledge, listKnowledge, acknowledgeKnowledge, queryGraph, resolveKnowledge, compactKnowledge } from "./commands/knowledge";
@@ -168,8 +168,9 @@ planCmd
   .command("start <description>")
   .description("Inicia uma nova feature")
   .option("--from-analysis <id>", "Importar baby steps de analise arquitetural aprovada")
+  .option("--max-tasks-per-phase <n>", "Maximo de tasks por fase (padrao: 12)", parseInt)
   .option("--json", "Saida em JSON")
-  .action((description: string, options: { fromAnalysis?: string; json?: boolean }) => {
+  .action((description: string, options: { fromAnalysis?: string; maxTasksPerPhase?: number; json?: boolean }) => {
     planStart(description, options);
   });
 
@@ -306,6 +307,15 @@ taskCmd
     });
   }));
 
+taskCmd
+  .command("phase-advance")
+  .description("Avanca para a proxima fase (compacta contexto automaticamente)")
+  .option("--no-compact", "Nao compactar knowledge antes de avancar")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action(wrapAction((options) => {
+    taskPhaseAdvance({ noCompact: options.compact === false, spec: options.spec });
+  }));
+
 // ═══════════════════════════════════════════════════════════════
 // DECISOES
 // ═══════════════════════════════════════════════════════════════