ai-maestro 1.0.0

package/src/orchestration/subtask-planner.mjs

@@ -0,0 +1,176 @@
+// src/orchestration/subtask-planner.mjs
+// Responsabilidade: Gerar subtarefas estruturadas a partir de uma task complexa.
+
+import { classifyTask, RISK_LEVELS } from './task-classifier.mjs';
+import { planSectorWork, SECTOR_MANAGERS } from './sector-managers.mjs';
+
+/**
+ * Gera subtarefas estruturadas a partir de uma task complexa.
+ * @param {object} input - Objeto de entrada contendo a task e contexto.
+ * @param {object} input.task - A tarefa a ser planejada.
+ * @param {object} input.classification - Classificação prévia da tarefa.
+ * @param {object} input.manager - O gerente de setor, se aplicável.
+ * @param {object} input.projectContext - Contexto geral do projeto.
+ * @param {object} input.constraints - Limites para a criação de subtarefas.
+ * @param {number} input.constraints.maxSubtasks - Número máximo de subtarefas permitidas.
+ * @param {number} input.constraints.maxDepth - Profundidade máxima de delegação.
+ * @returns {object} Um plano de subtarefas.
+ */
+export function planSubtasks(input) {
+  const { task, classification, constraints } = input;
+  const maxSubtasks = constraints.maxSubtasks || 8; // Default from spec
+  const maxDepth = constraints.maxDepth || 2; // Default from spec
+
+  if (classification.complexity < 3) {
+    return {
+      canSplit: false,
+      reason: ['Task é muito simples para ser dividida em subtarefas.'],
+      subtasks: [],
+      warnings: []
+    };
+  }
+
+  if (classification.risk === 'critical' && classification.requires.reasoning >= 4) {
+    return {
+      canSplit: false,
+      reason: ['Task de risco crítico e alta complexidade requer intervenção humana.'],
+      subtasks: [],
+      requiresHuman: true,
+      warnings: []
+    };
+  }
+
+  const { decision, subtasks: generatedSubtasks, reason: sectorReason } = planSectorWork(task, classification);
+
+  if (decision === 'no-manager' || decision === 'execute-directly') {
+    return {
+      canSplit: false,
+      reason: [`Nenhum gerente de setor aplicável ou gerente decide executar diretamente: ${sectorReason}`],
+      subtasks: [],
+      warnings: []
+    };
+  }
+
+  const subtasks = generatedSubtasks.slice(0, maxSubtasks).map((subtask, index) => ({
+    id: `subtask-${task.id || 't'}-${index + 1}`,
+    title: subtask.title,
+    taskKind: subtask.taskKind,
+    description: subtask.description,
+    requires: classifyTask(subtask).requires, // Classify each subtask to get its requirements
+    expectedFiles: subtask.files || [],
+    blockedBy: [],
+    parallelizable: false, // Default per spec for v0.5.2
+    risk: classifyTask(subtask).risk, // Classify each subtask to get its risk
+    verificationRequired: true
+  }));
+
+  const warnings = [];
+  if (generatedSubtasks.length > maxSubtasks) {
+    warnings.push(`O número de subtarefas geradas (${generatedSubtasks.length}) excedeu o limite (${maxSubtasks}). Apenas as primeiras ${maxSubtasks} foram incluídas.`);
+  }
+
+  return {
+    canSplit: subtasks.length > 0,
+    reason: [`Subtarefas geradas com sucesso. ${sectorReason}`],
+    subtasks: subtasks,
+    warnings: warnings
+  };
+}
+
+/**
+ * Valida um plano de subtarefas gerado.
+ * @param {object} plan - O plano de subtarefas a ser validado.
+ * @returns {object} Objeto com status de validade e lista de erros/avisos.
+ */
+export function validateSubtaskPlan(plan) {
+  const errors = [];
+  const warnings = [];
+
+  if (!plan || typeof plan !== 'object') {
+    errors.push('Plano inválido: objeto nulo ou não é um objeto.');
+    return { isValid: false, errors, warnings };
+  }
+
+  if (typeof plan.canSplit !== 'boolean') {
+    errors.push('Campo canSplit é obrigatório e deve ser um booleano.');
+  }
+
+  if (!Array.isArray(plan.reason) || plan.reason.some(r => typeof r !== 'string')) {
+    errors.push('Campo reason é obrigatório e deve ser um array de strings.');
+  }
+
+  if (!Array.isArray(plan.subtasks)) {
+    errors.push('Campo subtasks é obrigatório e deve ser um array.');
+  } else {
+    plan.subtasks.forEach((subtask, index) => {
+      if (typeof subtask !== 'object' || subtask === null) {
+        errors.push(`Subtarefa ${index} inválida: não é um objeto.`);
+        return;
+      }
+
+      if (!subtask.id || typeof subtask.id !== 'string') {
+        errors.push(`Subtarefa ${index}: ID é obrigatório e deve ser uma string.`);
+      }
+      if (!subtask.title || typeof subtask.title !== 'string') {
+        errors.push(`Subtarefa ${index}: title é obrigatório e deve ser uma string.`);
+      }
+      if (!subtask.taskKind || typeof subtask.taskKind !== 'string') {
+        errors.push(`Subtarefa ${index}: taskKind é obrigatório e deve ser uma string.`);
+      }
+      if (typeof subtask.description !== 'string') {
+        errors.push(`Subtarefa ${index}: description é obrigatório e deve ser uma string.`);
+      }
+      if (!subtask.requires || typeof subtask.requires !== 'object') {
+        errors.push(`Subtarefa ${index}: requires é obrigatório e deve ser um objeto.`);
+      }
+      if (!Array.isArray(subtask.expectedFiles)) {
+        errors.push(`Subtarefa ${index}: expectedFiles é obrigatório e deve ser um array.`);
+      }
+      if (!Array.isArray(subtask.blockedBy)) {
+        errors.push(`Subtarefa ${index}: blockedBy é obrigatório e deve ser um array.`);
+      }
+      if (typeof subtask.parallelizable !== 'boolean') {
+        errors.push(`Subtarefa ${index}: parallelizable é obrigatório e deve ser um booleano.`);
+      }
+      if (!RISK_LEVELS.includes(subtask.risk)) {
+        errors.push(`Subtarefa ${index}: risk inválido. Deve ser um de ${RISK_LEVELS.join(', ')}.`);
+      }
+      if (typeof subtask.verificationRequired !== 'boolean') {
+        errors.push(`Subtarefa ${index}: verificationRequired é obrigatório e deve ser um booleano.`);
+      }
+    });
+  }
+
+  return { isValid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Gera um resumo legível de um plano de subtarefas.
+ * @param {object} plan - O plano de subtarefas a ser resumido.
+ * @returns {string} Um resumo textual do plano.
+ */
+export function summarizeSubtaskPlan(plan) {
+  if (!plan || !plan.canSplit) {
+    return `Plano de subtarefas: Não é possível dividir a tarefa. Razão: ${plan?.reason?.[0] || 'Desconhecida'}`;
+  }
+
+  let summary = `Plano de Subtarefas:\n`;
+  summary += `- Razão: ${plan.reason.join(' ')}\n`;
+  summary += `- Total de Subtarefas: ${plan.subtasks.length}\n`;
+
+  plan.subtasks.forEach((subtask, index) => {
+    summary += `  ${index + 1}. [${subtask.taskKind}] ${subtask.title} (Risco: ${subtask.risk}, Verificação: ${subtask.verificationRequired ? 'Sim' : 'Não'})\n`;
+    if (subtask.expectedFiles && subtask.expectedFiles.length > 0) {
+      summary += `     Arquivos Esperados: ${subtask.expectedFiles.join(', ')}\n`;
+    }
+  });
+
+  if (plan.warnings && plan.warnings.length > 0) {
+    summary += `\nAvisos:\n`;
+    plan.warnings.forEach(warning => {
+      summary += `- ${warning}\n`;
+    });
+  }
+
+  return summary;
+}

package/src/orchestration/task-classifier.mjs

@@ -0,0 +1,241 @@
+import { stripAccents } from '../smart-planner.mjs';
+import { detectAffirmativeDeploymentIntent } from './deployment-intent.mjs';
+
+export const TASK_KINDS = [
+  'architecture', 'planning', 'frontend', 'backend', 'database', 'testing',
+  'debugging', 'security-review', 'code-review', 'documentation', 'research',
+  'file-inspection', 'simple-edit', 'data-transformation', 'image-analysis',
+  'deployment', 'memory-update', 'project-management'
+];
+
+export const RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
+
+// Keyword sets are intentionally bilingual (pt-BR + en) to match this
+// project's existing smart-planner.mjs convention. Each entry is a plain
+// (accent-stripped, lowercased) regex source, not a whole-word requirement,
+// mirroring smart-planner.mjs's own matching style.
+const KIND_PATTERNS = {
+  architecture: /\barquitetur|\bdesign do sistema|\bsystem design|\brefactor.*modul|\bcritical architecture/,
+  security: /\bseguranc|\bsecurity|\bvulnerab|\bexploit|\binjection|\bxss|\bcsrf|\bauth\b|\bcredencia|\bcredential|\bsecret/,
+  codeReview: /\brevis[aã]o de codigo|\bcode review|\bpull request|\brevisar (o )?codigo/,
+  review: /\brevis[aã]o|\breview\b|\bauditoria|\baudit\b/,
+  // Bare \bschema\b used to fire on "maestro schema-check" (a CLI verb,
+  // e.g. in a validation-step acceptance item), misclassifying an ordinary
+  // validation task as database/high-risk. The negative lookahead excludes
+  // "schema-check"/"schema check" specifically while still matching real
+  // database-schema mentions ("revisar o schema do banco", "database
+  // schema migration").
+  database: /\bbanco de dados|\bdatabase\b|\bsql\b|\bmigra(c|ç)[aã]o|\bmigration\b|\bschema\b(?![\s-]*check)|\bquery\b|\bpostgres|\bmysql|\bsqlite|\bmongo/,
+  testing: /\bteste|\btest\b|\bunit test|\bintegration test|\be2e\b|\bcobertura|\bcoverage/,
+  debugging: /\bbug|\berro\b|\berror\b|\bfalha|\bquebrado|\btravando|\bnao funciona|\bstack ?trace|\bdebug/,
+  frontend: /\bfrontend|\bfront-end|\bui\b|\binterface|\bbotao|\bbotões|\bbutton|\bcomponente|\bcomponent\b|\bcss\b|\bhtml\b|\breact\b|\bvue\b|\btela\b|\bpainel\b/,
+  backend: /\bbackend|\bback-end|\bapi\b|\bendpoint|\bservidor|\bserver\b|\brota\b|\broute\b|\bcontroller\b/,
+  documentation: /\bdocumenta[cç][aã]o|\bdocumentation\b|\breadme\b|\bhandoff\b|\bchangelog\b/,
+  research: /\bpesquisa|\bresearch\b|\binvestigar|\binvestigate\b|\bcomparar|\bcompare\b|\bavaliar op[cç][oõ]es/,
+  fileInspection: /\bmapear|\banalisar\b|\bidentificar\b|\blocalizar\b|\bdiagnosticar\b|\blistar\b|\bexplorar estrutura|\bmap the structure/,
+  dataTransformation: /\btransforma(c|ç)[aã]o de dados|\bdata transformation|\bconverter\b|\bconvert\b.*(csv|json|xml)|\bparser\b|\betl\b/,
+  imageAnalysis: /\bimagem\b|\bimage\b|\bscreenshot|\bvis[aã]o computacional|\bcomputer vision|\bocr\b|\banalisar (a )?foto/,
+  // Bare \bdeploy\b (and \bpublicar em produ) used to fire on negated
+  // acceptance criteria like "Sem deploy" -- detectAffirmativeDeploymentIntent
+  // rejects any deploy/publicar/implantar match that shares a clause with a
+  // negation or exclusion cue, in either word order. \brelease\b / ci-cd
+  // keywords are left as direct signals since they weren't part of the
+  // reported false-positive.
+  deployment: { test: text => /\brelease\b|\bci\/cd|\bpipeline de deploy/.test(text) || detectAffirmativeDeploymentIntent(text) },
+  memoryUpdate: /\bmemoria\b|\bmemory\b|\bcheckpoint\b|\b\.memory\//,
+  projectManagement: /\bplanejamento\b|\bplan\b|\bescopo\b|\bscope\b|\bbacklog\b|\bpriorizar\b|\bprioritize\b|\broadmap\b/,
+  simpleEdit: /\bcorrigir typo|\bfix typo|\brenomear\b|\brename\b|\bpequen[oa] ajuste|\bsmall fix|\bone[- ]line/
+};
+
+const CATEGORY_ORDER = [
+  ['architecture', KIND_PATTERNS.architecture],
+  ['security-review', KIND_PATTERNS.security],
+  ['code-review', KIND_PATTERNS.codeReview],
+  ['database', KIND_PATTERNS.database],
+  ['testing', KIND_PATTERNS.testing],
+  ['debugging', KIND_PATTERNS.debugging],
+  ['deployment', KIND_PATTERNS.deployment],
+  ['memory-update', KIND_PATTERNS.memoryUpdate],
+  ['documentation', KIND_PATTERNS.documentation],
+  ['data-transformation', KIND_PATTERNS.dataTransformation],
+  ['image-analysis', KIND_PATTERNS.imageAnalysis],
+  ['frontend', KIND_PATTERNS.frontend],
+  ['backend', KIND_PATTERNS.backend],
+  ['research', KIND_PATTERNS.research],
+  ['file-inspection', KIND_PATTERNS.fileInspection],
+  ['project-management', KIND_PATTERNS.projectManagement],
+  ['simple-edit', KIND_PATTERNS.simpleEdit],
+  // generic 'review' is checked last among the review-ish patterns so the
+  // more specific 'code-review'/'security-review' matches win first.
+  ['code-review', KIND_PATTERNS.review]
+];
+
+export function buildCombinedText(task) {
+  const parts = [
+    task.title || '',
+    task.description || '',
+    ...(Array.isArray(task.acceptance) ? task.acceptance : []),
+    task.requestKind || ''
+  ];
+  return stripAccents(parts.join(' ').toLowerCase());
+}
+
+function detectImageFiles(files = []) {
+  return files.some(file => /\.(png|jpe?g|gif|webp|svg|bmp)$/i.test(String(file)));
+}
+
+function detectTestFiles(files = []) {
+  return files.some(file => /\.(test|spec)\.[a-z]+$/i.test(String(file)) || /(^|\/)tests?\//i.test(String(file)));
+}
+
+function detectDbFiles(files = []) {
+  return files.some(file => /\.(sql)$/i.test(String(file)) || /migrations?\//i.test(String(file)));
+}
+
+function matchesPattern(pattern, text) {
+  return typeof pattern.test === 'function' && pattern.test(text);
+}
+
+function classifyByTitle(task) {
+  const titleText = stripAccents(String(task.title || '').toLowerCase());
+  if (!titleText) {
+    return null;
+  }
+  const matches = [];
+  for (const [kind, pattern] of CATEGORY_ORDER) {
+    if (matchesPattern(pattern, titleText)) {
+      matches.push(kind);
+    }
+  }
+  const uniqueMatches = [...new Set(matches)];
+  return uniqueMatches.length === 1 ? uniqueMatches[0] : null;
+}
+
+export function classifyTaskKind(task) {
+  const text = buildCombinedText(task);
+  const files = Array.isArray(task.files) ? task.files : [];
+
+  if (detectImageFiles(files)) {
+    return 'image-analysis';
+  }
+  if (detectDbFiles(files)) {
+    return 'database';
+  }
+  if (detectTestFiles(files)) {
+    return 'testing';
+  }
+
+  const titleKind = classifyByTitle(task);
+  if (titleKind) {
+    return titleKind;
+  }
+
+  for (const [kind, pattern] of CATEGORY_ORDER) {
+    if (matchesPattern(pattern, text)) {
+      return kind;
+    }
+  }
+
+  return 'simple-edit';
+}
+
+function estimateComplexity(task, kind) {
+  const text = buildCombinedText(task);
+  const files = Array.isArray(task.files) ? task.files : [];
+  let score = 1;
+
+  const HIGH_COMPLEXITY_KINDS = new Set(['architecture', 'security-review', 'database', 'deployment']);
+  const MEDIUM_COMPLEXITY_KINDS = new Set(['backend', 'frontend', 'testing', 'debugging', 'data-transformation', 'code-review']);
+
+  if (HIGH_COMPLEXITY_KINDS.has(kind)) {
+    score = 4;
+  } else if (MEDIUM_COMPLEXITY_KINDS.has(kind)) {
+    score = 3;
+  } else if (kind === 'file-inspection' || kind === 'research' || kind === 'documentation' || kind === 'memory-update' || kind === 'project-management') {
+    score = 2;
+  } else {
+    score = 1;
+  }
+
+  if (/\bcritic[ao]\b|\bcritical\b|\barquitetura critica|\bcritical architecture|\bfinal review\b/.test(text)) {
+    score = 5;
+  }
+
+  if (files.length > 5) {
+    score = Math.min(5, score + 1);
+  }
+
+  if (/\bmulti[- ]?arquivo|\bmultiple files\b|\bsistema inteiro\b|\bwhole system\b/.test(text)) {
+    score = Math.min(5, score + 1);
+  }
+
+  return Math.max(1, Math.min(5, score));
+}
+
+function estimateRisk(task, kind, complexity) {
+  const text = buildCombinedText(task);
+  const CRITICAL_KINDS = new Set(['security-review', 'deployment']);
+  const HIGH_KINDS = new Set(['database', 'architecture']);
+
+  // \bdeploy\b.*prod used to fire on negated text ("nao fazer deploy em
+  // producao" still contains "deploy" followed by "prod"); require an
+  // affirmative (non-negated) deploy intent plus a production mention.
+  const affirmativeProdDeploy = /\bprod/.test(text) && detectAffirmativeDeploymentIntent(text);
+  if (CRITICAL_KINDS.has(kind) || complexity >= 5 || /\bdrop table|\btruncate\b|\bforce push|\breset --hard/.test(text) || affirmativeProdDeploy) {
+    return 'critical';
+  }
+  if (HIGH_KINDS.has(kind) || complexity >= 4) {
+    return 'high';
+  }
+  if (complexity === 3 || kind === 'debugging' || kind === 'backend' || kind === 'code-review') {
+    return 'medium';
+  }
+  return 'low';
+}
+
+function estimateRequirements(task, kind, complexity) {
+  const files = Array.isArray(task.files) ? task.files : [];
+  const analysisOnlyKinds = new Set(['research', 'file-inspection', 'documentation', 'project-management', 'memory-update']);
+  const needsFsWrite = !analysisOnlyKinds.has(kind);
+  const needsShell = kind !== 'research' && kind !== 'documentation';
+  const needsTestExecution = kind === 'testing' || kind === 'debugging' || kind === 'backend' || kind === 'database';
+  const needsVision = kind === 'image-analysis' || detectImageFiles(files);
+
+  return {
+    reasoning: Math.min(5, Math.max(1, complexity)),
+    coding: analysisOnlyKinds.has(kind) ? 1 : Math.min(5, Math.max(2, complexity)),
+    shell: needsShell,
+    filesystemWrite: needsFsWrite,
+    browser: false,
+    vision: needsVision,
+    testExecution: needsTestExecution,
+    minimumContextTokens: complexity >= 4 ? 32000 : (complexity === 3 ? 16000 : 8000)
+  };
+}
+
+export function classifyTask(task, context = {}) {
+  const kind = classifyTaskKind(task);
+  const complexity = estimateComplexity(task, kind);
+  const risk = estimateRisk(task, kind, complexity);
+  const requires = estimateRequirements(task, kind, complexity);
+
+  return {
+    taskKind: kind,
+    complexity,
+    risk,
+    requires,
+    // Delegation to a sector manager only makes sense once there's real
+    // decomposition benefit (Phase 8 rule: complexity >= 3).
+    canDelegate: complexity >= 3,
+    // v0.5.0 deliberately never marks a task parallelizable: the delegation
+    // manager (Phase 9) only supports serial subagent execution this
+    // release, so nothing downstream should attempt to schedule two tasks'
+    // file writes concurrently regardless of what this field says.
+    parallelizable: false,
+    verificationRequired: risk !== 'low' || complexity >= 3,
+    context: {
+      stackHint: context.stackHint || null,
+      historyHint: context.historyHint || null
+    }
+  };
+}