ai-maestro 1.0.0

package/src/orchestration/rc-policy.mjs

@@ -0,0 +1,200 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+
+import { CONFIG } from '../config.mjs';
+import { redactObject } from '../format.mjs';
+
+export const RC_POLICY_SCHEMA_VERSION = 1;
+
+export const DEFAULT_REQUIRED_CHECKS = Object.freeze([
+  'git-state',
+  'npm-run-check',
+  'npm-test',
+  'schema-check',
+  'provider-health',
+  'engine-config',
+  'budget-config',
+  'safety-config',
+  'credential-audit',
+  'lock-observation',
+  'fallback-chain-state',
+  'temp-files'
+]);
+
+export const STRICT_EXTRA_CHECKS = Object.freeze(['readiness', 'doctor']);
+
+export const DEFAULT_RC_POLICY = Object.freeze({
+  schemaVersion: RC_POLICY_SCHEMA_VERSION,
+  requiredHealthTargets: [],
+  optionalHealthTargets: [],
+  canaryRequired: false,
+  allowInfraWarning: true,
+  requiredChecks: DEFAULT_REQUIRED_CHECKS,
+  skippedChecks: [],
+  timeouts: {},
+  reportOutput: {
+    enabled: false,
+    path: null
+  },
+  strictGitState: false,
+  knownDirtyPaths: [],
+  strictExtraChecks: []
+});
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+function arrayOfStrings(value, name, errors) {
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+    errors.push(name + ' must be an array of strings');
+    return [];
+  }
+  return value;
+}
+
+function booleanField(value, name, errors) {
+  if (typeof value !== 'boolean') {
+    errors.push(name + ' must be boolean');
+    return false;
+  }
+  return value;
+}
+
+function normalizeTimeouts(value, errors) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push('timeouts must be an object');
+    return {};
+  }
+  const timeouts = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (!Number.isInteger(raw) || raw < 1) {
+      errors.push('timeouts.' + key + ' must be a positive integer');
+    } else {
+      timeouts[key] = raw;
+    }
+  }
+  return timeouts;
+}
+
+function normalizeReportOutput(value, errors) {
+  if (value === undefined) return { ...DEFAULT_RC_POLICY.reportOutput };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push('reportOutput must be an object');
+    return { ...DEFAULT_RC_POLICY.reportOutput };
+  }
+  const enabled = value.enabled === undefined ? false : booleanField(value.enabled, 'reportOutput.enabled', errors);
+  const reportPath = value.path === undefined || value.path === null ? null : value.path;
+  if (reportPath !== null && typeof reportPath !== 'string') {
+    errors.push('reportOutput.path must be null or string');
+  }
+  return { enabled, path: typeof reportPath === 'string' ? reportPath : null };
+}
+
+function normalizePolicy(raw) {
+  const errors = [];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { policy: { ...DEFAULT_RC_POLICY }, errors: ['policy must be an object'] };
+  }
+  if (raw.schemaVersion !== RC_POLICY_SCHEMA_VERSION) {
+    errors.push('schemaVersion must be 1');
+  }
+
+  const requiredHealthTargets = raw.requiredHealthTargets === undefined
+    ? []
+    : arrayOfStrings(raw.requiredHealthTargets, 'requiredHealthTargets', errors);
+  const optionalHealthTargets = raw.optionalHealthTargets === undefined
+    ? []
+    : arrayOfStrings(raw.optionalHealthTargets, 'optionalHealthTargets', errors);
+  const requiredChecks = raw.requiredChecks === undefined
+    ? [...DEFAULT_REQUIRED_CHECKS]
+    : arrayOfStrings(raw.requiredChecks, 'requiredChecks', errors);
+  const skippedChecks = raw.skippedChecks === undefined
+    ? []
+    : arrayOfStrings(raw.skippedChecks, 'skippedChecks', errors);
+  const knownDirtyPaths = raw.knownDirtyPaths === undefined
+    ? []
+    : arrayOfStrings(raw.knownDirtyPaths, 'knownDirtyPaths', errors);
+  const strictExtraChecks = raw.strictExtraChecks === undefined
+    ? []
+    : arrayOfStrings(raw.strictExtraChecks, 'strictExtraChecks', errors);
+
+  for (const checkId of strictExtraChecks) {
+    if (!STRICT_EXTRA_CHECKS.includes(checkId)) {
+      errors.push('strictExtraChecks contains unsupported check: ' + checkId);
+    }
+  }
+
+  const requiredSet = new Set(requiredChecks);
+  for (const checkId of DEFAULT_REQUIRED_CHECKS) {
+    if (!requiredSet.has(checkId) && !skippedChecks.includes(checkId)) {
+      errors.push('required check omitted without explicit skippedChecks: ' + checkId);
+    }
+  }
+
+  const policy = {
+    schemaVersion: RC_POLICY_SCHEMA_VERSION,
+    requiredHealthTargets,
+    optionalHealthTargets,
+    canaryRequired: raw.canaryRequired === undefined ? false : booleanField(raw.canaryRequired, 'canaryRequired', errors),
+    allowInfraWarning: raw.allowInfraWarning === undefined ? true : booleanField(raw.allowInfraWarning, 'allowInfraWarning', errors),
+    requiredChecks,
+    skippedChecks,
+    timeouts: normalizeTimeouts(raw.timeouts, errors),
+    reportOutput: normalizeReportOutput(raw.reportOutput, errors),
+    strictGitState: raw.strictGitState === undefined ? false : booleanField(raw.strictGitState, 'strictGitState', errors),
+    knownDirtyPaths,
+    strictExtraChecks
+  };
+
+  return { policy, errors };
+}
+
+export async function loadRcPolicy(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const policyPath = options.policyPath || path.join(projectRoot, CONFIG.maestroPath, 'rc-policy.json');
+  try {
+    const rawText = await fs.readFile(policyPath, 'utf-8');
+    const parsed = JSON.parse(rawText);
+    const normalized = normalizePolicy(parsed);
+    const valid = normalized.errors.length === 0;
+    return redactObject({
+      source: 'file',
+      path: policyPath,
+      valid,
+      hash: sha256(rawText),
+      defaultsApplied: false,
+      policy: normalized.policy,
+      errors: normalized.errors
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {
+        source: 'defaults',
+        path: null,
+        valid: true,
+        hash: null,
+        defaultsApplied: true,
+        policy: JSON.parse(JSON.stringify(DEFAULT_RC_POLICY)),
+        errors: []
+      };
+    }
+    const errors = [error instanceof SyntaxError ? 'policy JSON is invalid' : (error.message || String(error))];
+    return redactObject({
+      source: 'file',
+      path: policyPath,
+      valid: false,
+      hash: null,
+      defaultsApplied: false,
+      policy: JSON.parse(JSON.stringify(DEFAULT_RC_POLICY)),
+      errors
+    });
+  }
+}
+
+export function hashPolicyInfo(policyInfo) {
+  if (policyInfo && policyInfo.hash) return policyInfo.hash;
+  return sha256(JSON.stringify((policyInfo && policyInfo.policy) || DEFAULT_RC_POLICY));
+}

package/src/orchestration/runtime-gate.mjs

@@ -0,0 +1,146 @@
+// v0.5.1 "Enforce Orchestra Runtime": the single choke point every real
+// worker execution must pass through. Everything here is read-only /
+// decision-only — this module never calls an engine, never mutates a task,
+// and never writes to RUNS.jsonl itself. Callers (src/task-commands.mjs)
+// own all side effects; this module only answers "what should happen".
+import { classifyTask } from './task-classifier.mjs';
+import { listEngineRecords, getEngineRecord } from './capability-registry.mjs';
+import { runPreflight } from './preflight.mjs';
+import { selectEngine } from './engine-selector.mjs';
+import { planSectorWork } from './sector-managers.mjs';
+import { loadBudget, evaluateBudget } from './budget-manager.mjs';
+import { checkEnginePolicy } from './engine-policy.mjs';
+import { classifyFailure, planFallback } from './fallback-graph.mjs';
+import { getRecentRuns } from '../runner.mjs';
+
+export const GATE_DECISIONS = ['EXECUTE', 'BLOCK', 'NEEDS_HUMAN', 'DELEGATE', 'FALLBACK'];
+
+// The only preflight outcomes that can ever become a NEEDS_HUMAN or FALLBACK
+// gate decision; everything else in this set is a hard BLOCK (or FALLBACK
+// when an alternative engine already exists) that --force can never lift.
+const HARD_PREFLIGHT_BLOCKS = new Set(['UNAVAILABLE', 'DECLINE', 'NEEDS_CAPABILITY', 'NEEDS_CONTEXT']);
+
+export async function countRunsForTask(taskId) {
+  const runs = await getRecentRuns(Infinity);
+  return runs.filter(run => String(run.taskId) === String(taskId)).length;
+}
+
+// Among selectEngine()'s rejected alternatives, one that lost only on score
+// (not a hard filter) is a legitimate fallback candidate — it already
+// passed tools/cost/context/health checks on its own.
+function findAlternativeCandidateId(selection) {
+  const runnerUp = (selection.alternatives || []).find(alt => /^lower score/.test(alt.rejectedBecause || ''));
+  return runnerUp ? runnerUp.engine : null;
+}
+
+// Deterministic, ficha-only decision. No model is ever consulted to decide
+// this (project principle: "Claude pensa somente quando necessário").
+function computeDecision({ selection, preflight, budgetResult, policyResult, managerPlan }) {
+  if (!selection.selectedEngine) {
+    return {
+      decision: 'BLOCK',
+      blockCategory: 'no-candidate',
+      reasons: ['No engine satisfies this task\'s hard requirements: ' + selection.reason.join('; ')]
+    };
+  }
+  if (!budgetResult.allowed) {
+    return { decision: 'BLOCK', blockCategory: 'budget', reasons: ['Budget: ' + budgetResult.reason] };
+  }
+  if (!policyResult.ok) {
+    return { decision: 'BLOCK', blockCategory: 'policy', reasons: policyResult.violations };
+  }
+  if (HARD_PREFLIGHT_BLOCKS.has(preflight.decision)) {
+    const alternativeId = findAlternativeCandidateId(selection);
+    return {
+      decision: alternativeId ? 'FALLBACK' : 'BLOCK',
+      blockCategory: alternativeId ? null : 'preflight',
+      alternativeEngineId: alternativeId,
+      reasons: [preflight.reason]
+    };
+  }
+  if (preflight.decision === 'NEEDS_HUMAN') {
+    return { decision: 'NEEDS_HUMAN', blockCategory: null, reasons: [preflight.reason] };
+  }
+  if (managerPlan.decision === 'decompose') {
+    return { decision: 'DELEGATE', blockCategory: null, reasons: [managerPlan.reason] };
+  }
+  return { decision: 'EXECUTE', blockCategory: null, reasons: ['Classification, engine selection, preflight, budget, and policy all passed.'] };
+}
+
+/**
+ * The mandatory pre-execution pipeline: classify -> select manager ->
+ * select engine -> preflight -> budget -> policy -> decide.
+ *
+ * @param {object} params
+ * @param {object} params.task - the task record (id, title, description, files, acceptance, requestKind, engine, ...)
+ * @param {string} [params.projectRoot] - informational only; all sub-modules already resolve paths via CONFIG.maestroPath
+ * @param {'real'|'dry-run'} [params.mode]
+ * @param {boolean} [params.force] - may only ever promote a NEEDS_HUMAN decision to EXECUTE; never touches BLOCK/DELEGATE/FALLBACK
+ * @param {number} [params.runsSoFar] - defaults to counting .maestro/RUNS.jsonl rows for this task
+ * @param {boolean} [params.allowCritical] - if true, a critical-risk task does not trigger NEEDS_HUMAN by itself (still subject to every other gate). Defaults to false; --force is the intended way to move past NEEDS_HUMAN, not this flag.
+ */
+export async function evaluateTaskRun({ task, projectRoot = process.cwd(), mode = 'real', force = false, runsSoFar, allowCritical = false } = {}) {
+  const classification = classifyTask(task);
+  const managerPlan = planSectorWork(task, classification);
+  const engines = await listEngineRecords();
+  const selection = await selectEngine(classification, { engines });
+  const engineRecord = selection.selectedEngine ? await getEngineRecord(selection.selectedEngine) : null;
+
+  // skipDelegationCheck: the gate derives DELEGATE from the sector-manager
+  // plan (managerPlan.decision === 'decompose'), not from preflight's own
+  // simplified complexity>=3 heuristic — see runtime-gate design notes in
+  // .maestro/AUTONOMOUS_ORCHESTRA.md.
+  const preflight = engineRecord
+    ? runPreflight(task, engineRecord, classification, { skipDelegationCheck: true, allowCritical })
+    : { decision: 'UNAVAILABLE', confidence: 0.9, reason: 'No engine selected.', missingCapabilities: [], recommendedRole: null, recommendedSuccessor: null, suggestedSubtasks: [] };
+
+  const resolvedRunsSoFar = typeof runsSoFar === 'number' ? runsSoFar : await countRunsForTask(task.id);
+  const budgetPolicy = await loadBudget();
+  const budgetResult = await evaluateBudget({ runsSoFar: resolvedRunsSoFar, engineRecord });
+  const policyResult = checkEnginePolicy(engineRecord, { role: 'worker' });
+
+  const outcome = computeDecision({ selection, preflight, budgetResult, policyResult, managerPlan });
+
+  let decision = outcome.decision;
+  let forced = false;
+  const reasons = [...outcome.reasons];
+  if (force === true && decision === 'NEEDS_HUMAN') {
+    decision = 'EXECUTE';
+    forced = true;
+    reasons.push('Forced by user (--force): NEEDS_HUMAN sign-off bypassed. Budget, policy, and capability gates were still enforced and all passed.');
+  }
+
+  let fallback = null;
+  if (decision === 'FALLBACK' || (decision === 'BLOCK' && outcome.blockCategory === 'preflight')) {
+    const category = classifyFailure({ preflightDecision: preflight.decision, missingCapabilities: preflight.missingCapabilities });
+    fallback = await planFallback({ category });
+  }
+
+  const warnings = [...(policyResult.warnings || [])];
+  if (mode === 'dry-run') {
+    warnings.push('dry-run: this evaluation was computed but no engine/worker will be called.');
+  }
+
+  return {
+    decision,
+    blockCategory: outcome.blockCategory,
+    mode,
+    forced,
+    projectRoot,
+    taskClassification: classification,
+    selectedManager: managerPlan,
+    selectedEngine: {
+      id: selection.selectedEngine,
+      score: selection.score,
+      reason: selection.reason,
+      alternatives: selection.alternatives,
+      record: engineRecord
+    },
+    preflight,
+    budget: { policy: budgetPolicy, evaluation: budgetResult },
+    policy: policyResult,
+    fallback,
+    warnings,
+    reason: reasons
+  };
+}

package/src/orchestration/sector-managers.mjs

@@ -0,0 +1,215 @@
+// A "sector manager" is a role the Maestro assigns for a task, not a fixed
+// engine or a separate running process. It exists only long enough to
+// decide whether a task should be executed directly or decomposed into a
+// short list of subtasks handed to the delegation manager (Phase 9). All
+// decomposition here is deterministic/heuristic, matching this project's
+// existing planner style (src/smart-planner.mjs) — no LLM call is made to
+// "decide" anything, per the project principle "Claude pensa somente quando
+// necessário."
+
+export const SECTOR_MANAGERS = [
+  {
+    id: "architecture-manager",
+    displayName: "Architecture Manager",
+    handles: ["architecture"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: [],
+    preferredVerifier: "testing-manager"
+  },
+  {
+    id: "security-manager",
+    displayName: "Security Manager",
+    handles: ["security-review"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: ["critical-security"],
+    preferredVerifier: "testing-manager"
+  },
+  {
+    id: "backend-manager",
+    displayName: "Backend Manager",
+    handles: ["backend", "database"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: [],
+    preferredVerifier: "testing-manager"
+  },
+  {
+    id: "frontend-manager",
+    displayName: "Frontend Manager",
+    handles: ["frontend", "ui-app"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: [],
+    preferredVerifier: "testing-manager"
+  },
+  {
+    id: "testing-manager",
+    displayName: "Testing Manager",
+    handles: ["testing", "debugging"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: [],
+    preferredVerifier: "testing-manager"
+  },
+  {
+    id: "documentation-manager",
+    displayName: "Documentation Manager",
+    handles: ["documentation", "memory-update"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: [],
+    preferredVerifier: "testing-manager"
+  },
+  {
+    id: "research-manager",
+    displayName: "Research Manager",
+    handles: ["research", "file-inspection", "code-review"],
+    canDelegate: true,
+    maxSubtasks: 4,
+    requiresHumanFor: [],
+    preferredVerifier: "testing-manager"
+  }
+];
+
+const MINIMUM_COMPLEXITY_FOR_MANAGER = 3;
+
+function findSectorForTaskKind(taskKind) {
+  for (const manager of SECTOR_MANAGERS) {
+    if (manager.handles.includes(taskKind)) {
+      return manager;
+    }
+  }
+  return null;
+}
+
+// Managers only get involved when there is real benefit: complexity high
+// enough that decomposition helps (spec rule: complexity >= 3), and a
+// recognized sector actually claims this taskKind. A trivial task or an
+// unmapped taskKind (e.g. 'simple-edit', 'project-management',
+// 'deployment', 'data-transformation', 'image-analysis') stays with the
+// Maestro/worker directly — coordination overhead would exceed the gain.
+export function resolveSectorManager(classification) {
+  if (!classification || classification.complexity < MINIMUM_COMPLEXITY_FOR_MANAGER) {
+    return null;
+  }
+  return findSectorForTaskKind(classification.taskKind);
+}
+
+const SUBTASK_TEMPLATES = {
+  'architecture-manager': [
+    { suffix: 'Mapear estado atual e restrições', taskKind: 'file-inspection' },
+    { suffix: 'Definir mudança proposta e riscos', taskKind: 'architecture' },
+    { suffix: 'Validar decisão com verificação independente', taskKind: 'code-review' }
+  ],
+  'security-manager': [
+    { suffix: 'Levantar superfície de risco e arquivos afetados', taskKind: 'file-inspection' },
+    { suffix: 'Aplicar correção de segurança', taskKind: 'security-review' },
+    { suffix: 'Verificar correção com checagem independente', taskKind: 'code-review' }
+  ],
+  'backend-manager': [
+    { suffix: 'Mapear rotas/serviços/schema envolvidos', taskKind: 'file-inspection' },
+    { suffix: 'Implementar mudança de backend', taskKind: 'backend' },
+    { suffix: 'Rodar testes relacionados', taskKind: 'testing' }
+  ],
+  'frontend-manager': [
+    { suffix: 'Mapear componentes/telas envolvidas', taskKind: 'file-inspection' },
+    { suffix: 'Implementar mudança de frontend', taskKind: 'frontend' },
+    { suffix: 'Validar fluxo manualmente ou via teste', taskKind: 'testing' }
+  ],
+  'testing-manager': [
+    { suffix: 'Reproduzir ou isolar o problema', taskKind: 'debugging' },
+    { suffix: 'Corrigir causa raiz', taskKind: 'debugging' },
+    { suffix: 'Adicionar/rodar testes de regressão', taskKind: 'testing' }
+  ],
+  'documentation-manager': [
+    { suffix: 'Levantar o que mudou e precisa de documentação', taskKind: 'file-inspection' },
+    { suffix: 'Atualizar documentação/memória', taskKind: 'documentation' }
+  ],
+  'research-manager': [
+    { suffix: 'Levantar fontes e opções', taskKind: 'research' },
+    { suffix: 'Consolidar achados e recomendação', taskKind: 'documentation' }
+  ]
+};
+
+const MAX_SUBTASKS_PER_SECTOR = 4;
+
+export function generateSubtasksForSector(sector, task) {
+  if (!sector) {
+    return [];
+  }
+  const templates = SUBTASK_TEMPLATES[sector.id] || [];
+  const baseTitle = task.title || task.description || 'tarefa';
+  return templates.slice(0, MAX_SUBTASKS_PER_SECTOR).map((template, index) => ({
+    title: baseTitle + ' — ' + template.suffix,
+    description: template.suffix + ' (subtarefa ' + (index + 1) + '/' + templates.length + ' de "' + baseTitle + '", gerenciada por ' + sector.displayName + ').',
+    taskKind: template.taskKind,
+    files: [],
+    sector: sector.id,
+    parentTaskId: task.id ?? null
+  }));
+}
+
+// Top-level entry point: given a task + its classification, decide whether
+// a sector manager should handle it, and if so, what it would do
+// (execute directly vs. decompose). This does not perform any I/O and does
+// not itself enforce the delegation-manager's depth/count limits — see
+// src/orchestration/delegation-manager.mjs for that.
+export function planSectorWork(task, classification) {
+  const sector = resolveSectorManager(classification);
+  if (!sector) {
+    return {
+      sector: null,
+      decision: 'no-manager',
+      reason: classification && classification.complexity < MINIMUM_COMPLEXITY_FOR_MANAGER
+        ? 'complexity ' + (classification ? classification.complexity : 'unknown') + ' below manager threshold (' + MINIMUM_COMPLEXITY_FOR_MANAGER + ')'
+        : 'no sector manager maps to taskKind "' + (classification ? classification.taskKind : 'unknown') + '"',
+      subtasks: []
+    };
+  }
+
+  // Complexity 3 is handled directly by the manager acting as a strong
+  // worker (coordination overhead of decomposing a merely-medium task isn't
+  // worth it); complexity >= 4 decomposes into the sector's subtask
+  // template. This mirrors the spec's own examples (a complexity-3 frontend
+  // task in the spec's own metadata example is still a single unit of work).
+  if (classification.complexity < 4) {
+    return {
+      sector: sector.id,
+      decision: 'execute-directly',
+      reason: sector.displayName + ' handles this task directly (complexity ' + classification.complexity + ').',
+      subtasks: []
+    };
+  }
+
+  const subtasks = generateSubtasksForSector(sector, task);
+  return {
+    sector: sector.id,
+    decision: 'decompose',
+    reason: sector.displayName + ' decomposes this task (complexity ' + classification.complexity + ') into ' + subtasks.length + ' subtasks.',
+    subtasks
+  };
+}
+/**
+ * Seleciona um gerente de setor baseado na classificação.
+ * Alias para resolveSectorManager para compatibilidade com delegation-executor.
+ */
+export function selectSectorManager(classification) {
+  return resolveSectorManager(classification);
+}
+
+/**
+ * Determina se um gerente de setor deve ser usado para a tarefa.
+ */
+export function shouldUseManager(classification) {
+  if (!classification) {
+    return false;
+  }
+  // Manager é útil quando complexidade >= 3 e existe um sector aplicável
+  if (classification.complexity < MINIMUM_COMPLEXITY_FOR_MANAGER) {
+    return false;
+  }
+  const manager = resolveSectorManager(classification);
+  return manager !== null;
+}