ai-maestro 1.0.0

package/src/orchestration/delegation-executor.mjs

@@ -0,0 +1,262 @@
+// src/orchestration/delegation-executor.mjs
+// Responsabilidade: Criar plano de delegação, não executar ainda.
+
+import { selectSectorManager, shouldUseManager } from './sector-managers.mjs';
+import { planSubtasks, validateSubtaskPlan } from './subtask-planner.mjs';
+import { detectFileConflicts } from './file-conflict-detector.mjs';
+
+// detectFileConflicts moved to file-conflict-detector.mjs (single source of
+// truth, per spec section 4); re-exported here so existing importers of
+// this module keep working.
+export { detectFileConflicts };
+
+/**
+ * Plano de delegação para uma tarefa.
+ * @param {object} input - Objeto contendo task, classification, projectContext, etc.
+ * @returns {object} Plano de delegação estruturado.
+ */
+export async function planDelegation(input) {
+  const { 
+    task, 
+    classification, 
+    projectContext = {},
+    engines = [],
+    history = []
+  } = input;
+
+  // Decidir se precisa delegação
+  if (!classification || !shouldUseManager(classification)) {
+    return {
+      decision: 'NO_DELEGATION',
+      manager: null,
+      subtasks: [],
+      assignments: [],
+      executionMode: 'serial',
+      requiresHuman: false,
+      warnings: [`Tarefa não atende critérios para delegação. Complexidade: ${classification?.complexity || 'unknown'}, Risk: ${classification?.risk || 'unknown'}`]
+    };
+  }
+
+  // Selecionar gerente
+  const manager = selectSectorManager(classification);
+  if (!manager) {
+    return {
+      decision: 'NO_DELEGATION',
+      manager: null,
+      subtasks: [],
+      assignments: [],
+      executionMode: 'serial',
+      requiresHuman: false,
+      warnings: [`Nenhum gerente de setor aplicável para taskKind: ${classification.taskKind}`]
+    };
+  }
+
+  // Planejar subtarefas
+  const subtaskPlanInput = {
+    task,
+    classification,
+    manager,
+    projectContext,
+    constraints: {
+      maxSubtasks: manager.maxSubtasks || 4,
+      maxDepth: 2
+    }
+  };
+
+  const subtaskPlan = planSubtasks(subtaskPlanInput);
+
+  if (!subtaskPlan.canSplit) {
+    // Task não será dividida, mas ainda pode ser delegada ao manager
+    return {
+      decision: 'PLAN_ONLY',
+      manager,
+      subtasks: [],
+      assignments: [
+        {
+          subtaskId: task.id,
+          role: 'worker',
+          candidateEngine: selectBestEngine(classification, engines, history),
+          reason: [`Delegada ao gerente ${manager.id} para execução direta.`]
+        }
+      ],
+      executionMode: 'serial',
+      requiresHuman: classification.risk === 'critical',
+      warnings: subtaskPlan.warnings || []
+    };
+  }
+
+  // Validar plano de subtarefas
+  const validation = validateSubtaskPlan(subtaskPlan);
+  if (!validation.isValid) {
+    return {
+      decision: 'NO_DELEGATION',
+      manager,
+      subtasks: [],
+      assignments: [],
+      executionMode: 'serial',
+      requiresHuman: true,
+      warnings: validation.errors
+    };
+  }
+
+  // Detectar conflitos de arquivo
+  const fileConflicts = detectFileConflicts(subtaskPlan.subtasks);
+  let executionMode = 'serial'; // v0.5.2: sempre serial
+  if (fileConflicts.length > 0) {
+    // Conflito força serial
+    executionMode = 'serial';
+  }
+
+  // Criar assignments
+  const assignments = subtaskPlan.subtasks.map(subtask => {
+    let role = 'worker';
+    if (subtask.verificationRequired && subtask === subtaskPlan.subtasks[subtaskPlan.subtasks.length - 1]) {
+      role = 'verifier';
+    }
+
+    const engine = selectBestEngine(subtask, engines, history);
+    return {
+      subtaskId: subtask.id,
+      role,
+      candidateEngine: engine,
+      reason: [
+        `Subtarefa de tipo ${subtask.taskKind}`,
+        `Risco: ${subtask.risk}`,
+        `Motor candidato: ${engine}`
+      ]
+    };
+  });
+
+  const requiresHuman = 
+    classification.risk === 'critical' ||
+    (manager.requiresHumanFor || []).some(cond => classification.taskKind === cond);
+
+  const warnings = subtaskPlan.warnings || [];
+  if (fileConflicts.length > 0) {
+    warnings.push(`${fileConflicts.length} conflito(s) de arquivo detectado(s). Executar em modo serial.`);
+  }
+
+  return {
+    decision: 'READY',
+    manager,
+    subtasks: subtaskPlan.subtasks,
+    assignments,
+    executionMode,
+    requiresHuman,
+    warnings
+  };
+}
+
+/**
+ * Seleciona o melhor motor para uma tarefa/subtarefa.
+ * Versão simplificada: retorna o primeiro motor válido.
+ */
+function selectBestEngine(classification, engines = [], history = []) {
+  if (!engines || engines.length === 0) {
+    return 'codex-default';
+  }
+
+  const available = engines.filter(e => e.enabled === true);
+  if (available.length === 0) {
+    return 'codex-default';
+  }
+
+  const preferred = available.find(e => e.id === 'codex9' || e.id === 'codex8');
+  return preferred ? preferred.id : available[0].id;
+}
+
+/**
+ * Valida um plano de delegação.
+ */
+export function validateDelegationPlan(plan) {
+  const errors = [];
+  const warnings = [];
+
+  if (!plan || typeof plan !== 'object') {
+    errors.push('Plano inválido: nulo ou não é um objeto.');
+    return { isValid: false, errors, warnings };
+  }
+
+  const validDecisions = ['NO_DELEGATION', 'PLAN_ONLY', 'READY'];
+  if (!validDecisions.includes(plan.decision)) {
+    errors.push(`Campo decision inválido. Deve ser um de: ${validDecisions.join(', ')}`);
+  }
+
+  if (plan.decision === 'READY' && !plan.manager) {
+    errors.push('Decisão READY requer um gerente válido.');
+  }
+
+  if (!Array.isArray(plan.subtasks)) {
+    errors.push('Campo subtasks deve ser um array.');
+  }
+
+  if (!Array.isArray(plan.assignments)) {
+    errors.push('Campo assignments deve ser um array.');
+  } else {
+    plan.assignments.forEach((assignment, idx) => {
+      if (!assignment.subtaskId || typeof assignment.subtaskId !== 'string') {
+        errors.push(`Assignment ${idx}: subtaskId inválido.`);
+      }
+      if (!['worker', 'reviewer', 'fixer', 'verifier'].includes(assignment.role)) {
+        errors.push(`Assignment ${idx}: role inválida.`);
+      }
+      if (!assignment.candidateEngine || typeof assignment.candidateEngine !== 'string') {
+        errors.push(`Assignment ${idx}: candidateEngine inválido.`);
+      }
+      if (!Array.isArray(assignment.reason)) {
+        errors.push(`Assignment ${idx}: reason deve ser um array.`);
+      }
+    });
+  }
+
+  if (plan.executionMode !== 'serial') {
+    warnings.push(`v0.5.2: executionMode deve ser 'serial', encontrado '${plan.executionMode}'.`);
+  }
+
+  if (typeof plan.requiresHuman !== 'boolean') {
+    errors.push('Campo requiresHuman deve ser um booleano.');
+  }
+
+  if (!Array.isArray(plan.warnings)) {
+    errors.push('Campo warnings deve ser um array.');
+  }
+
+  return { isValid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Gera um resumo legível de um plano de delegação.
+ */
+export function summarizeDelegationPlan(plan) {
+  if (!plan) {
+    return 'Plano de delegação inválido.';
+  }
+
+  let summary = `Plano de Delegação:\n`;
+  summary += `Decisão: ${plan.decision}\n`;
+
+  if (plan.manager) {
+    summary += `Gerente: ${plan.manager.displayName || plan.manager.id || 'desconhecido'}\n`;
+  }
+
+  summary += `Subtarefas: ${plan.subtasks?.length || 0}\n`;
+  summary += `Assignments: ${plan.assignments?.length || 0}\n`;
+  summary += `Modo de Execução: ${plan.executionMode || 'serial'}\n`;
+  summary += `Requer Intervenção Humana: ${plan.requiresHuman ? 'Sim' : 'Não'}\n`;
+
+  if (plan.assignments && plan.assignments.length > 0) {
+    summary += `\nAssignments:\n`;
+    plan.assignments.forEach((assignment, idx) => {
+      summary += `  ${idx + 1}. ${assignment.subtaskId} → ${assignment.candidateEngine} (role: ${assignment.role})\n`;
+    });
+  }
+
+  if (plan.warnings && plan.warnings.length > 0) {
+    summary += `\nAvisos:\n`;
+    plan.warnings.forEach(w => {
+      summary += `- ${w}\n`;
+    });
+  }
+
+  return summary;
+}

package/src/orchestration/delegation-manager.mjs

@@ -0,0 +1,116 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { stampSchemaVersion } from '../schema.mjs';
+import { planSectorWork } from './sector-managers.mjs';
+
+const delegationLogPath = path.join(CONFIG.maestroPath, 'delegation-log.jsonl');
+
+// Hard limits from the spec (Phase 9). These are enforced here, not just
+// documented — buildDelegationPlan() below refuses to exceed them rather
+// than trusting callers to check first.
+export const DELEGATION_LIMITS = {
+  maxDepth: 2,
+  maxSubagentsPerManager: 4,
+  maxAutoSubtasksPerTask: 8,
+  maxEnginesTriedPerTask: 3,
+  maxRetryPerEngine: 1
+};
+
+export function getDelegationLogPath() {
+  return delegationLogPath;
+}
+
+export async function logDelegationEvent(entry) {
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const stamped = stampSchemaVersion({
+    timestamp: new Date().toISOString(),
+    ...entry
+  });
+  await fs.appendFile(delegationLogPath, JSON.stringify(stamped) + '\n');
+  return stamped;
+}
+
+// Two subtasks conflict if they declare overlapping `files`. Conflicting
+// subtasks MUST run sequentially (never concurrently) in this release —
+// v0.5.0 does not implement parallel writes at all (see
+// .maestro/SUBAGENT_POLICY.md), so this function currently only exists to
+// make that guarantee inspectable/testable, not to unlock parallelism.
+export function detectFileConflicts(subtasks) {
+  const conflicts = [];
+  for (let i = 0; i < subtasks.length; i++) {
+    for (let j = i + 1; j < subtasks.length; j++) {
+      const filesA = new Set(subtasks[i].files || []);
+      const filesB = subtasks[j].files || [];
+      const overlap = filesB.filter(file => filesA.has(file));
+      if (overlap.length > 0) {
+        conflicts.push({ a: i, b: j, files: overlap });
+      }
+    }
+  }
+  return conflicts;
+}
+
+// depth: how many delegation levels already happened above this call
+// (0 = top-level task, 1 = subtask of a sector manager, 2 = would be a
+// sub-subtask — refused, since maxDepth is 2 meaning "at most 2 manager
+// hops from the original task").
+export function buildDelegationPlan(task, classification, { depth = 0 } = {}) {
+  if (depth >= DELEGATION_LIMITS.maxDepth) {
+    return {
+      delegate: false,
+      sector: null,
+      reason: 'max delegation depth (' + DELEGATION_LIMITS.maxDepth + ') reached at depth=' + depth + '; task must execute directly or be declined.',
+      subtasks: []
+    };
+  }
+
+  const plan = planSectorWork(task, classification);
+  if (plan.decision !== 'decompose') {
+    return { delegate: false, sector: plan.sector, reason: plan.reason, subtasks: [] };
+  }
+
+  let subtasks = plan.subtasks;
+  if (subtasks.length > DELEGATION_LIMITS.maxSubagentsPerManager) {
+    subtasks = subtasks.slice(0, DELEGATION_LIMITS.maxSubagentsPerManager);
+  }
+  if (subtasks.length > DELEGATION_LIMITS.maxAutoSubtasksPerTask) {
+    subtasks = subtasks.slice(0, DELEGATION_LIMITS.maxAutoSubtasksPerTask);
+  }
+
+  const conflicts = detectFileConflicts(subtasks);
+
+  return {
+    delegate: true,
+    sector: plan.sector,
+    reason: plan.reason,
+    subtasks,
+    fileConflicts: conflicts,
+    executionOrder: 'serial',
+    depth: depth + 1
+  };
+}
+
+export async function recordDelegation({ task, plan, delegatedBy = 'maestro', outcome = null }) {
+  return logDelegationEvent({
+    taskId: task.id ?? null,
+    delegatedBy,
+    sector: plan.sector,
+    delegate: plan.delegate,
+    reason: plan.reason,
+    subtaskCount: plan.subtasks ? plan.subtasks.length : 0,
+    subtaskTitles: (plan.subtasks || []).map(subtask => subtask.title),
+    fileConflicts: plan.fileConflicts || [],
+    executionOrder: plan.executionOrder || null,
+    depth: plan.depth ?? 0,
+    outcome
+  });
+}
+
+export function withinEngineAttemptLimit(attemptCount) {
+  return attemptCount < DELEGATION_LIMITS.maxEnginesTriedPerTask;
+}
+
+export function withinRetryLimit(retryCount) {
+  return retryCount < DELEGATION_LIMITS.maxRetryPerEngine;
+}

package/src/orchestration/deployment-intent.mjs

@@ -0,0 +1,36 @@
+import { stripAccents } from '../smart-planner.mjs';
+
+// A bare "deploy"-shaped word is not enough on its own: acceptance criteria
+// and task descriptions routinely mention deploy only to forbid it ("sem
+// deploy", "nao fazer deploy", "deployment is out of scope"). This helper
+// only reports an affirmative deploy intent when a deploy-action word
+// appears in a clause that has no negation/exclusion cue anywhere in that
+// same clause. Negation can precede ("nao fazer deploy") or follow ("deploy
+// nao deve ser realizado") the action word, so a fixed look-behind window
+// isn't enough -- splitting the text into clauses and checking each one as
+// a whole handles both orders without depending solely on \bdeploy\b.
+const DEPLOY_ACTION_PATTERN = /\bdeploy(ment)?\b|\bpublicar\b|\bimplantar\b|\bimplanta(c|ç)[aã]o\b|\bpush to prod|\brelease to prod|\bpublish to prod/;
+const NEGATION_PATTERN = /\bnao\b|\bsem\b|\bnunca\b|\bjamais\b|\bnot\b|\bdon'?t\b|\bdo not\b/;
+const EXCLUSION_PATTERN = /fora do escopo|out of scope|nao faz parte|not part of/;
+
+function splitClauses(text) {
+  const parts = text.split(/[.,;:!?\n]+/).map(part => part.trim()).filter(Boolean);
+  return parts.length ? parts : [text];
+}
+
+export function detectAffirmativeDeploymentIntent(rawText) {
+  const text = stripAccents(String(rawText || '').toLowerCase());
+  if (!DEPLOY_ACTION_PATTERN.test(text)) {
+    return false;
+  }
+  for (const clause of splitClauses(text)) {
+    if (!DEPLOY_ACTION_PATTERN.test(clause)) {
+      continue;
+    }
+    if (NEGATION_PATTERN.test(clause) || EXCLUSION_PATTERN.test(clause)) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}

package/src/orchestration/engine-history.mjs

@@ -0,0 +1,110 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { pathExists } from '../files.mjs';
+import { stampSchemaVersion } from '../schema.mjs';
+
+const historyPath = path.join(CONFIG.maestroPath, 'engine-history.jsonl');
+
+export function getEngineHistoryPath() {
+  return historyPath;
+}
+
+// entry shape (all fields optional except engine/success):
+// { engine, provider, model, taskKind, complexity, success, failureCategory,
+//   durationMs, estimatedTokens, estimatedCost, toolsAvailable, retries,
+//   fallbackUsed, verifierResult, runKind, taskId }
+export async function recordEngineOutcome(entry) {
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const stamped = stampSchemaVersion({
+    timestamp: new Date().toISOString(),
+    ...entry
+  });
+  if (await pathExists(historyPath)) {
+    await fs.copyFile(historyPath, historyPath + '.bak');
+  }
+  await fs.appendFile(historyPath, JSON.stringify(stamped) + '\n');
+  return stamped;
+}
+
+export async function readEngineHistory(limit = Infinity) {
+  try {
+    const content = await fs.readFile(historyPath, 'utf-8');
+    const rows = content
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map(line => {
+        try {
+          return JSON.parse(line);
+        } catch (error) {
+          return { parseError: error.message, raw: line };
+        }
+      });
+    return Number.isFinite(limit) ? rows.slice(-limit) : rows;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export async function getHistoryForEngine(engineId, { limit = 50 } = {}) {
+  const rows = await readEngineHistory(Infinity);
+  return rows.filter(row => row.engine === engineId).slice(-limit);
+}
+
+export function computeSuccessRate(entries) {
+  const valid = entries.filter(entry => typeof entry.success === 'boolean');
+  if (valid.length === 0) {
+    return null;
+  }
+  return valid.filter(entry => entry.success === true).length / valid.length;
+}
+
+export function toEngineSelectorHistory(entries) {
+  return entries
+    .filter(entry => typeof entry.success === 'boolean' && entry.engine)
+    .map(entry => ({ engine: entry.engine, success: entry.success }));
+}
+
+export async function summarizeHistoryByEngine() {
+  const rows = await readEngineHistory(Infinity);
+  const byEngine = {};
+  for (const row of rows) {
+    if (!row.engine) continue;
+    const bucket = byEngine[row.engine] || (byEngine[row.engine] = {
+      engine: row.engine,
+      totalRuns: 0,
+      successes: 0,
+      failures: 0,
+      failureCategories: {},
+      totalDurationMs: 0,
+      durationSamples: 0,
+      lastRunAt: null
+    });
+    bucket.totalRuns += 1;
+    if (row.success === true) bucket.successes += 1;
+    if (row.success === false) {
+      bucket.failures += 1;
+      const category = row.failureCategory || 'unknown_failure';
+      bucket.failureCategories[category] = (bucket.failureCategories[category] || 0) + 1;
+    }
+    if (typeof row.durationMs === 'number') {
+      bucket.totalDurationMs += row.durationMs;
+      bucket.durationSamples += 1;
+    }
+    if (!bucket.lastRunAt || row.timestamp > bucket.lastRunAt) {
+      bucket.lastRunAt = row.timestamp;
+    }
+  }
+  return Object.values(byEngine).map(bucket => ({
+    engine: bucket.engine,
+    totalRuns: bucket.totalRuns,
+    successRate: bucket.totalRuns > 0 ? bucket.successes / bucket.totalRuns : null,
+    failures: bucket.failures,
+    failureCategories: bucket.failureCategories,
+    averageDurationMs: bucket.durationSamples > 0 ? Math.round(bucket.totalDurationMs / bucket.durationSamples) : null,
+    lastRunAt: bucket.lastRunAt
+  }));
+}

package/src/orchestration/engine-policy.mjs

@@ -0,0 +1,73 @@
+// Categorical engine-usage policy (Phase 14), separate from budget-manager.mjs
+// (which enforces numeric limits: runs/subagents/depth/tokens/currency).
+// This module answers "is this engine even allowed to be used this way",
+// independent of how much budget remains.
+
+function envAllows(name) {
+  return process.env[name] === '1';
+}
+
+// Only checks `id`/`provider` — short, structured slugs — not the free-text
+// `model` field. Some fiches (e.g. ai-router) put a whole descriptive
+// sentence in `model` ("delegates to whichever CLI ... fcc-claude"), and a
+// naive substring check there false-positives on any engine that merely
+// mentions Claude as one option among several, not one that IS Claude.
+function looksLikeClaude(engineRecord) {
+  const id = String((engineRecord && engineRecord.id) || '').toLowerCase();
+  const provider = String((engineRecord && engineRecord.provider) || '').toLowerCase();
+  return id.includes('claude') || provider.includes('claude') || provider.includes('anthropic');
+}
+
+function looksLikeDirectOpenAI(engineRecord) {
+  const provider = String((engineRecord && engineRecord.provider) || '').toLowerCase();
+  const id = String((engineRecord && engineRecord.id) || '').toLowerCase();
+  // Explicitly excludes 9router-routed models even if the underlying model
+  // happens to be a GPT/OpenAI model — 9Router is the allowed path; only a
+  // provider that talks to OpenAI's API directly is gated by this rule.
+  if (provider === '9router' || id.startsWith('9router')) {
+    return false;
+  }
+  return provider === 'openai' || provider === 'openai-direct' || id.includes('openai-direct');
+}
+
+// context: { role: 'worker'|'review'|'manager'|..., isClaudeReview: boolean,
+//            allowClaudeReviewFlag: boolean, allowDirectOpenAIFlag: boolean }
+// The `*Flag` fields let a caller pass budget.json's allowClaudeReview /
+// allowDirectOpenAI values in directly; the env vars are checked either way,
+// matching the spec's "bloqueado sem <ENV>=1" language.
+export function checkEnginePolicy(engineRecord, context = {}) {
+  const violations = [];
+  const warnings = [];
+  const role = context.role || 'worker';
+
+  if (looksLikeClaude(engineRecord)) {
+    if (role === 'worker' && context.isClaudeReview !== true) {
+      violations.push(
+        'Claude-family engine "' + (engineRecord && engineRecord.id) + '" must not be used as a default worker. ' +
+        'See .maestro/ENGINE_SELECTION_POLICY.md — Claude/premium review is opt-in only, never routine task execution.'
+      );
+    } else if (!envAllows('MAESTRO_ALLOW_CLAUDE_REVIEW') && context.allowClaudeReviewFlag !== true) {
+      violations.push(
+        'Claude review requires MAESTRO_ALLOW_CLAUDE_REVIEW=1 or .maestro/budget.json allowClaudeReview=true.'
+      );
+    }
+  }
+
+  if (looksLikeDirectOpenAI(engineRecord)) {
+    if (!envAllows('MAESTRO_ALLOW_DIRECT_OPENAI') && context.allowDirectOpenAIFlag !== true) {
+      violations.push(
+        'Direct OpenAI access ("' + (engineRecord && engineRecord.id) + '", provider="' + (engineRecord && engineRecord.provider) + '") requires ' +
+        'MAESTRO_ALLOW_DIRECT_OPENAI=1 or .maestro/budget.json allowDirectOpenAI=true.'
+      );
+    }
+  }
+
+  if (engineRecord && engineRecord.validated !== true) {
+    warnings.push(
+      'Engine "' + engineRecord.id + '" is not validated (validated=false in .maestro/engines.json); ' +
+      'treat any result with reduced confidence until it is explicitly validated (see "maestro engines validate").'
+    );
+  }
+
+  return { ok: violations.length === 0, violations, warnings };
+}