ai-maestro 1.0.0

package/src/orchestration/spec-planner.mjs

@@ -0,0 +1,877 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { inferEngine } from '../smart-planner.mjs';
+
+export const SPEC_PLANNER_VERSION = 'spec-file-v1';
+const MAX_SPEC_BYTES = 128 * 1024;
+
+function projectRoot() {
+  return path.resolve(CONFIG.projectRoot || process.cwd());
+}
+
+function normalizeRelativePath(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function isInsideProject(root, resolvedPath) {
+  const relative = path.relative(root, resolvedPath);
+  return Boolean(relative) && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+function cleanPathCandidate(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^[\x60"'(<]+/, '')
+    .replace(/[\x60,.;:!?)>"']+$/, '');
+}
+
+function containsEnvPath(candidate) {
+  return /(^|[\\/])\.env($|[\\/.])/i.test(candidate) || /\.env/i.test(candidate);
+}
+
+function isAllowedSpecPath(relativePath) {
+  const normalized = relativePath.replace(/\\/g, '/').toLowerCase();
+  return normalized.startsWith('.maestro/') && normalized.endsWith('.md') && !normalized.includes('/../') && !containsEnvPath(normalized);
+}
+
+function findMarkdownCandidates(request) {
+  const text = String(request || '');
+  const candidates = [];
+  const pattern = /[\x60"']?((?:[A-Za-z]:[\\/]|\.\.?[\\/]|\.maestro[\\/])[^\s\x60"')]+?\.md)[\x60"']?/gi;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    candidates.push({ rawMatch: cleanPathCandidate(match[1]), index: match.index });
+  }
+  return candidates;
+}
+
+export async function detectSpecificationReference(request) {
+  const root = projectRoot();
+  for (const candidate of findMarkdownCandidates(request)) {
+    const rawMatch = cleanPathCandidate(candidate.rawMatch);
+    if (!rawMatch || rawMatch.includes('\0') || containsEnvPath(rawMatch)) {
+      continue;
+    }
+    const resolved = path.resolve(root, rawMatch);
+    if (!isInsideProject(root, resolved)) {
+      continue;
+    }
+    const specPath = normalizeRelativePath(path.relative(root, resolved));
+    if (!isAllowedSpecPath(specPath)) {
+      continue;
+    }
+    try {
+      const stat = await fs.stat(resolved);
+      if (!stat.isFile()) {
+        continue;
+      }
+      return { hasSpecFile: true, specPath, rawMatch };
+    } catch (error) {
+      continue;
+    }
+  }
+  return { hasSpecFile: false, specPath: null, rawMatch: null };
+}
+
+function normalizeText(value) {
+  return String(value || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase();
+}
+
+function normalizeHeading(title) {
+  return normalizeText(title)
+    .replace(/`/g, '')
+    .replace(/^\s*\d+(?:\.\d+)*\.?\s*/, '')
+    .replace(/[()[\]:;,_-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function markdownSections(content) {
+  const headings = [];
+  const pattern = /^(#{2,6})\s+(.+)$/gm;
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    headings.push({ level: match[1].length, title: match[2].trim(), headingStart: match.index, bodyStart: pattern.lastIndex });
+  }
+  return headings.map((heading, index) => {
+    const end = index + 1 < headings.length ? headings[index + 1].headingStart : content.length;
+    return {
+      level: heading.level,
+      title: heading.title,
+      start: heading.bodyStart,
+      end,
+      normalizedTitle: normalizeHeading(heading.title),
+      body: content.slice(heading.bodyStart, end).trim()
+    };
+  });
+}
+
+function sectionByTitle(sections, titlePart) {
+  const normalized = normalizeHeading(titlePart);
+  return sections.find(section => section.normalizedTitle.includes(normalized)) || null;
+}
+
+function bulletItems(text) {
+  const items = [];
+  const pattern = /^\s*-\s+(.+)$/gm;
+  let match;
+  while ((match = pattern.exec(text || '')) !== null) {
+    items.push(match[1].trim().replace(/;$/, ''));
+  }
+  return items;
+}
+
+function numberedItems(text) {
+  const items = [];
+  const pattern = /^\s*\d+\.\s+(.+)$/gm;
+  let match;
+  while ((match = pattern.exec(text || '')) !== null) {
+    items.push(match[1].trim().replace(/;$/, ''));
+  }
+  return items;
+}
+
+function fencedBlocks(text) {
+  const blocks = [];
+  const pattern = /\x60\x60\x60[a-zA-Z0-9_-]*\r?\n([\s\S]*?)\x60\x60\x60/g;
+  let match;
+  while ((match = pattern.exec(text || '')) !== null) {
+    blocks.push(match[1].trim());
+  }
+  return blocks;
+}
+
+function firstNonEmptyLine(text) {
+  return String(text || '').split(/\r?\n/).map(line => line.trim()).find(Boolean) || null;
+}
+
+function extractTargetFile(title, body) {
+  const combined = [title, body].join('\n');
+  const explicit = combined.match(/\x60([^\x60]*src\/orchestration\/[^\x60]+?\.mjs)\x60/i);
+  if (explicit) {
+    return explicit[1];
+  }
+  const loose = combined.match(/src\/orchestration\/[A-Za-z0-9_-]+\.mjs/i);
+  return loose ? loose[0] : null;
+}
+
+function extractExports(body) {
+  const exports = new Set();
+  for (const block of fencedBlocks(body)) {
+    for (const line of block.split(/\r?\n/)) {
+      const match = line.trim().match(/^([A-Za-z_$][\w$]*)\s*\(/);
+      if (match) {
+        exports.add(match[1]);
+      }
+    }
+  }
+  if (/detectFileConflicts/.test(body)) {
+    exports.add('detectFileConflicts');
+  }
+  return [...exports];
+}
+
+function sectionRules(body) {
+  const marker = body.match(/Regras:\s*([\s\S]*)/i);
+  return marker ? bulletItems(marker[1]) : [];
+}
+
+function docsToUpdateItems(body) {
+  const docsOnly = String(body || '').split(/^Explicar:/im)[0];
+  return bulletItems(docsOnly).map(item => item.replace(/\x60/g, '').replace(/\.$/, ''));
+}
+
+const INFORMATIONAL_HEADING_TERMS = [
+  'contexto',
+  'estado atual',
+  'estado confirmado',
+  'escopo',
+  'responsabilidade',
+  'nao escopo',
+  'fora de escopo',
+  'arquivos consultados',
+  'arquivos existentes',
+  'arquivos permitidos',
+  'arquivos proibidos',
+  'apis',
+  'contratos publicos',
+  'estados',
+  'estados separados',
+  'eventos',
+  'transicoes',
+  'estados terminais',
+  'runtime gate',
+  'dependencias',
+  'adapters',
+  'delegacao',
+  'subtarefas',
+  'conflito',
+  'conflitos',
+  'execucao simulada',
+  'consolidator',
+  'verifier',
+  'limites',
+  'deteccao de ciclos',
+  'trace',
+  'resultado final',
+  'recommended next action',
+  'exceptions',
+  'pureza',
+  'determinismo',
+  'nao mutacao',
+  'compatibilidade futura',
+  'cli',
+  'allowlist',
+  'acceptance criteria',
+  'itens nao confirmados',
+  'riscos',
+  'resultado esperado',
+  'commit esperado'
+];
+
+const NEGATIVE_SECTION_TERMS = [
+  'nao escopo',
+  'fora de escopo',
+  'arquivos proibidos',
+  'itens nao confirmados',
+  'riscos',
+  'adiado',
+  'futuro',
+  'opcional posterior',
+  'nao implementar ainda',
+  'proibidos na implementacao',
+  'nao alterar'
+];
+
+const NEGATIVE_INTENT_PATTERN = /\b(nao implementar|nao alterar|nao criar|nao executar|fora do escopo|adiado|futuro|somente posteriormente|nao deve|nao pode)\b/;
+const POSITIVE_ACTION_PATTERN = /\b(criar|implementar|adicionar|atualizar|modificar|evoluir|alterar)\b/;
+
+function titleHasTerm(normalizedTitle, term) {
+  return normalizedTitle === term || normalizedTitle.includes(term);
+}
+
+function isNegativeSection(section) {
+  const title = section.normalizedTitle;
+  return NEGATIVE_SECTION_TERMS.some(term => titleHasTerm(title, term));
+}
+
+function isInformationalSection(section) {
+  const title = section.normalizedTitle;
+  return INFORMATIONAL_HEADING_TERMS.some(term => titleHasTerm(title, term));
+}
+
+function hasNegativeIntent(text) {
+  return NEGATIVE_INTENT_PATTERN.test(normalizeHeading(text));
+}
+
+function positiveLines(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line && !hasNegativeIntent(line));
+}
+
+function uniqueStrings(values) {
+  return [...new Set((values || []).map(value => String(value || '').trim()).filter(Boolean))];
+}
+
+function normalizeTaskFile(filePath) {
+  return cleanPathCandidate(filePath).replace(/\\/g, '/');
+}
+
+function isSafeTaskFile(filePath) {
+  const normalized = normalizeTaskFile(filePath);
+  return Boolean(normalized) &&
+    !path.isAbsolute(normalized) &&
+    !normalized.split('/').includes('..') &&
+    !containsEnvPath(normalized);
+}
+
+function extractFileCandidates(text) {
+  const candidates = [];
+  const patterns = [
+    /\x60([^`\r\n]+?)\x60/g,
+    /(?:^|[\s(["'])((?:src|tests|bin)\/[A-Za-z0-9_./*-]+|package\.json|README\.md|\.maestro\/[A-Za-z0-9_./*-]+|\.memory\/[A-Za-z0-9_./*-]+)(?=$|[\s)"',.;:])/g
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text || '')) !== null) {
+      const value = normalizeTaskFile(match[1]);
+      if (/^(src|tests|bin)\/|^package\.json$|^README\.md$|^\.maestro\/|^\.memory\//i.test(value)) {
+        candidates.push(value);
+      }
+    }
+  }
+  return uniqueStrings(candidates);
+}
+
+function extractConstraintFiles(sections) {
+  const allowed = [];
+  const prohibited = [];
+  for (const section of sections) {
+    let mode = null;
+    const title = section.normalizedTitle;
+    if (title.includes('arquivos permitidos') || title.includes('permitidos para alteracao')) {
+      mode = 'allowed';
+    }
+    if (title.includes('arquivos proibidos') || title.includes('proibidos para alteracao')) {
+      mode = 'prohibited';
+    }
+    if (title.includes('allowlist futura')) {
+      mode = null;
+    }
+    for (const rawLine of String(section.body || '').split(/\r?\n/)) {
+      const line = rawLine.trim();
+      const normalized = normalizeHeading(line);
+      if (!normalized) {
+        continue;
+      }
+      if ((normalized.includes('permitidos') || normalized.includes('allowlist')) && !normalized.includes('proibidos')) {
+        mode = 'allowed';
+        continue;
+      }
+      if (normalized.includes('proibidos') || normalized.startsWith('nao alterar')) {
+        mode = 'prohibited';
+        continue;
+      }
+      const files = extractFileCandidates(line);
+      if (mode === 'allowed') {
+        allowed.push(...files);
+      } else if (mode === 'prohibited') {
+        prohibited.push(...files);
+      }
+    }
+  }
+  return {
+    allowedFiles: uniqueStrings(allowed),
+    prohibitedFiles: uniqueStrings(prohibited)
+  };
+}
+
+function extractAcceptanceCriteria(sections) {
+  const criteria = [];
+  for (const section of sections) {
+    const title = section.normalizedTitle;
+    if (title.includes('acceptance criteria') || title.includes('criterios de aceite')) {
+      criteria.push(...bulletItems(section.body));
+    }
+  }
+  return uniqueStrings(criteria);
+}
+
+function extractValidationCommandsFromSections(sections, fallbackNeedsTest) {
+  const commands = [];
+  const commandPattern = /\b(npm run check|npm test|maestro schema-check)\b/g;
+  for (const section of sections) {
+    const title = section.normalizedTitle;
+    if (!title.includes('validacoes') && !title.includes('validation') && !title.includes('acceptance criteria') && !title.includes('criterios de aceite')) {
+      continue;
+    }
+    for (const block of fencedBlocks(section.body)) {
+      commands.push(...block.split(/\r?\n/).map(line => line.trim()).filter(Boolean));
+    }
+    let match;
+    while ((match = commandPattern.exec(section.body || '')) !== null) {
+      commands.push(match[1]);
+    }
+  }
+  if (fallbackNeedsTest && commands.includes('npm run check') && !commands.includes('npm test')) {
+    commands.splice(commands.indexOf('npm run check') + 1, 0, 'npm test');
+  }
+  return uniqueStrings(commands);
+}
+
+function deliverableKind(title) {
+  const normalized = normalizeHeading(title);
+  if (/\bcriar\b/.test(normalized)) return 'create-module';
+  if (/\bevoluir\b/.test(normalized)) return 'evolve-module';
+  if (/\batualizar\b/.test(normalized)) return 'update-file';
+  return 'other';
+}
+
+function targetFileKind(filePath) {
+  const normalized = String(filePath || '').toLowerCase();
+  if (normalized.startsWith('tests/') || /\.(test|spec)\.[a-z]+$/i.test(normalized)) return 'tests';
+  if (normalized === 'package.json') return 'check-script';
+  if (normalized.startsWith('src/') && /\.mjs$/i.test(normalized)) return 'module';
+  return 'file';
+}
+
+function explicitDeliverableEvidence(section) {
+  const titleText = normalizeHeading(section.title);
+  const bodyText = normalizeHeading(positiveLines(section.body).join('\n'));
+  const titleFiles = extractFileCandidates(section.title);
+  const targetFiles = extractFileCandidates(section.title + '\n' + positiveLines(section.body).join('\n'));
+  const hasAction = POSITIVE_ACTION_PATTERN.test(titleText) || /\b(criar funcao|adicionar funcao|exportar|devera ser adicionado|deve ser adicionado)\b/.test(bodyText);
+  const hasModuleTarget = titleFiles.some(file => targetFileKind(file) === 'module');
+  const hasTestTarget = targetFiles.some(file => targetFileKind(file) === 'tests');
+  const hasPackageCheck = targetFiles.includes('package.json') && /\b(check|script)\b/.test(bodyText);
+  return { hasAction, hasModuleTarget, hasTestTarget, hasPackageCheck, targetFiles };
+}
+
+function parseDeliverables(sections) {
+  const deliverables = [];
+  for (const section of sections) {
+    const title = section.normalizedTitle;
+    if (isNegativeSection(section) || title.includes('testes obrigatorios') || title.includes('docs') || title.includes('validacoes') || title.includes('commit') || title.includes('entrega final')) {
+      continue;
+    }
+    const evidence = explicitDeliverableEvidence(section);
+    if (isInformationalSection(section)) {
+      const bodyText = normalizeHeading(positiveLines(section.body).join('\n'));
+      const explicitUtility = title.includes('conflito') && /\b(criar funcao|adicionar funcao)\b/.test(bodyText);
+      if (!evidence.hasModuleTarget && !explicitUtility) {
+        continue;
+      }
+    }
+    if (!evidence.hasAction && !evidence.hasModuleTarget) {
+      continue;
+    }
+    const positiveBody = positiveLines(section.body).join('\n');
+    const targetFile = extractTargetFile(section.title, positiveBody) || evidence.targetFiles.find(file => targetFileKind(file) === 'module') || null;
+    const kind = targetFile ? targetFileKind(targetFile) : deliverableKind(section.title);
+    if (kind === 'file' || kind === 'tests' || kind === 'check-script') {
+      continue;
+    }
+    deliverables.push({
+      title: section.title.replace(/^\d+(?:\.\d+)*\.?\s*/, '').trim(),
+      kind,
+      targetFile,
+      exports: extractExports(positiveBody),
+      rules: sectionRules(positiveBody)
+    });
+  }
+  return dedupeDeliverables(deliverables);
+}
+
+function parseTestTargetFile(sections, allowedFiles) {
+  for (const section of sections) {
+    if (!section.normalizedTitle.includes('testes obrigatorios')) {
+      continue;
+    }
+    const explicit = extractFileCandidates(section.title + '\n' + section.body).find(file => targetFileKind(file) === 'tests');
+    if (explicit) {
+      return explicit;
+    }
+  }
+  return (allowedFiles || []).find(file => targetFileKind(file) === 'tests') || null;
+}
+
+function parsePackageCheckTarget(sections, allowedFiles, prohibitedFiles) {
+  const packageAllowed = (allowedFiles || []).includes('package.json');
+  const packageProhibited = (prohibitedFiles || []).includes('package.json');
+  if (packageProhibited) {
+    return null;
+  }
+  for (const section of sections) {
+    const text = normalizeHeading(section.title + '\n' + section.body);
+    if (text.includes('package.json') && text.includes('check') && (packageAllowed || text.includes('script'))) {
+      return 'package.json';
+    }
+  }
+  return null;
+}
+
+function deliverableActionKey(deliverable) {
+  const title = normalizeHeading(deliverable.title);
+  if (deliverable.kind === 'module') return 'implement';
+  if (deliverable.kind === 'tests') return 'test';
+  if (deliverable.kind === 'check-script') return 'check';
+  if (title.includes('conflito') || (deliverable.exports || []).includes('detectFileConflicts')) return 'file-conflicts';
+  if (title.includes('delegation')) return 'delegation';
+  if (title.includes('subtask')) return 'subtasks';
+  return title.replace(/\b(criar|implementar|adicionar|atualizar|modificar|evoluir|alterar)\b/g, '').trim();
+}
+
+function deliverableKey(deliverable) {
+  const file = deliverable.targetFile || (deliverable.exports || []).join('+') || normalizeHeading(deliverable.title);
+  return [deliverable.kind || 'other', file, deliverableActionKey(deliverable)].join('|');
+}
+
+function dedupeDeliverables(deliverables) {
+  const byKey = new Map();
+  for (const deliverable of deliverables || []) {
+    const key = deliverableKey(deliverable);
+    if (!byKey.has(key)) {
+      byKey.set(key, {
+        ...deliverable,
+        exports: uniqueStrings(deliverable.exports),
+        rules: uniqueStrings(deliverable.rules)
+      });
+      continue;
+    }
+    const existing = byKey.get(key);
+    existing.exports = uniqueStrings([...(existing.exports || []), ...(deliverable.exports || [])]);
+    existing.rules = uniqueStrings([...(existing.rules || []), ...(deliverable.rules || [])]);
+  }
+  return [...byKey.values()];
+}
+
+function objectiveText(section) {
+  if (!section) return null;
+  const text = section.body
+    .replace(/\x60\x60\x60[\s\S]*?\x60\x60\x60/g, '')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('-'))
+    .join(' ')
+    .trim();
+  return text || null;
+}
+
+export function parseSpecificationMarkdown(specContent, specPath) {
+  try {
+    const content = String(specContent || '').slice(0, MAX_SPEC_BYTES);
+    const sections = markdownSections(content);
+    const objectiveSection = sectionByTitle(sections, 'Objetivo');
+    const doNotSection = sectionByTitle(sections, 'Nao implementar ainda');
+    const rulesSection = sectionByTitle(sections, 'Regras');
+    const testsSection = sectionByTitle(sections, 'Testes obrigatorios');
+    const docsSection = sectionByTitle(sections, 'Docs');
+    const validationSection = sectionByTitle(sections, 'Validacoes');
+    const commitSection = sectionByTitle(sections, 'Commit');
+    const deliverySection = sectionByTitle(sections, 'Entrega final');
+    const commitBlocks = fencedBlocks(commitSection ? commitSection.body : '');
+    const constraints = extractConstraintFiles(sections);
+    const deliverables = parseDeliverables(sections);
+    const mandatoryTests = numberedItems(testsSection ? testsSection.body : '');
+    const validationCommands = validationSection
+      ? fencedBlocks(validationSection.body).flatMap(block => block.split(/\r?\n/).map(line => line.trim()).filter(Boolean))
+      : extractValidationCommandsFromSections(sections, mandatoryTests.length > 0);
+
+    return {
+      specPath,
+      objective: objectiveText(objectiveSection),
+      doNotImplementYet: bulletItems(doNotSection ? doNotSection.body : ''),
+      rules: bulletItems(rulesSection ? rulesSection.body : ''),
+      deliverables,
+      mandatoryTests,
+      testTargetFile: parseTestTargetFile(sections, constraints.allowedFiles),
+      packageCheckTargetFile: parsePackageCheckTarget(sections, constraints.allowedFiles, constraints.prohibitedFiles),
+      docsToUpdate: docsToUpdateItems(docsSection ? docsSection.body : ''),
+      validationCommands,
+      expectedCommit: commitBlocks.length > 0 ? firstNonEmptyLine(commitBlocks[0]) : null,
+      deliveryChecklist: bulletItems(deliverySection ? deliverySection.body : ''),
+      acceptanceCriteria: extractAcceptanceCriteria(sections),
+      allowedFiles: constraints.allowedFiles,
+      prohibitedFiles: constraints.prohibitedFiles,
+      warnings: []
+    };
+  } catch (error) {
+    return {
+      specPath,
+      objective: null,
+      doNotImplementYet: [],
+      rules: [],
+      deliverables: [],
+      mandatoryTests: [],
+      testTargetFile: null,
+      packageCheckTargetFile: null,
+      docsToUpdate: [],
+      validationCommands: [],
+      expectedCommit: null,
+      deliveryChecklist: [],
+      acceptanceCriteria: [],
+      allowedFiles: [],
+      prohibitedFiles: [],
+      warnings: []
+    };
+  }
+}
+
+function taskTitleForDeliverable(deliverable) {
+  const target = String(deliverable.targetFile || '').toLowerCase();
+  const exports = deliverable.exports.join(' ');
+  if (target.includes('subtask-planner')) return 'Implementar subtask-planner';
+  if (target.includes('delegation-executor')) return 'Implementar delegation-executor';
+  if (target.includes('sector-managers')) return 'Evoluir sector-managers';
+  if (target.includes('orchestration-loop')) return 'Implementar orchestration loop deterministico em dry-run';
+  if (/detectFileConflicts/.test(exports) || /conflito/i.test(deliverable.title)) return 'Implementar detecção de conflitos de arquivos';
+  return 'Implementar ' + deliverable.title.replace(/\x60/g, '');
+}
+
+function specTaskBase(spec, request) {
+  return {
+    priority: 'high',
+    sourceRequest: request,
+    sourceSpec: spec.specPath,
+    requestKind: 'specification-file'
+  };
+}
+
+function restrictionAcceptance(spec) {
+  const acceptance = [];
+  if ((spec.allowedFiles || []).length > 0) {
+    acceptance.push('Respeitar arquivos permitidos extraidos do sourceSpec');
+  }
+  if ((spec.prohibitedFiles || []).length > 0) {
+    acceptance.push('Respeitar arquivos proibidos extraidos do sourceSpec');
+  }
+  return acceptance;
+}
+
+function safeExpectedFiles(files, spec) {
+  const prohibited = new Set((spec.prohibitedFiles || []).map(normalizeTaskFile));
+  return uniqueStrings(files)
+    .map(normalizeTaskFile)
+    .filter(file => isSafeTaskFile(file) && !prohibited.has(file));
+}
+
+function isSingleModuleSpecification(spec) {
+  const moduleFiles = uniqueStrings((spec.deliverables || [])
+    .map(deliverable => deliverable.targetFile)
+    .filter(file => targetFileKind(file) === 'module'));
+  return moduleFiles.length === 1;
+}
+
+function ensureConservativeSingleModulePlan(tasks, spec) {
+  if (!isSingleModuleSpecification(spec) || tasks.length <= 6) {
+    return tasks;
+  }
+  const requiredRoles = new Set(['implementation', 'tests', 'validation', 'commit']);
+  const implementation = tasks.find(task => task.planRole === 'implementation');
+  const checkTask = tasks.find(task => task.planRole === 'check-script');
+  if (implementation && checkTask && tasks.length > 6) {
+    implementation.files = safeExpectedFiles([...(implementation.files || []), ...(checkTask.files || [])], spec);
+    implementation.acceptance = uniqueStrings([...(implementation.acceptance || []), ...(checkTask.acceptance || [])]);
+    tasks = tasks.filter(task => task !== checkTask);
+  }
+  const extras = tasks.filter(task => !requiredRoles.has(task.planRole) && task.planRole !== 'check-script' && task.planRole !== 'docs');
+  if (implementation && extras.length > 0) {
+    implementation.files = safeExpectedFiles([...(implementation.files || []), ...extras.flatMap(task => task.files || [])], spec);
+    implementation.acceptance = uniqueStrings([
+      ...(implementation.acceptance || []),
+      ...extras.flatMap(task => task.acceptance || []),
+      'Conceitos internos agrupados na implementacao principal; sem criar microtasks artificiais.'
+    ]);
+    tasks = tasks.filter(task => !extras.includes(task));
+  }
+  return tasks;
+}
+
+function taskDedupeKey(task) {
+  const files = Array.isArray(task.files) && task.files.length > 0 ? task.files.join('+') : normalizeHeading(task.title);
+  return [task.planRole || 'task', files, normalizeHeading(task.title)].join('|');
+}
+
+function dedupeTasks(tasks) {
+  const byKey = new Map();
+  for (const task of tasks || []) {
+    const key = taskDedupeKey(task);
+    if (!byKey.has(key)) {
+      byKey.set(key, {
+        ...task,
+        files: uniqueStrings(task.files || []),
+        acceptance: uniqueStrings(task.acceptance || [])
+      });
+      continue;
+    }
+    const existing = byKey.get(key);
+    existing.files = uniqueStrings([...(existing.files || []), ...(task.files || [])]);
+    existing.acceptance = uniqueStrings([...(existing.acceptance || []), ...(task.acceptance || [])]);
+  }
+  return [...byKey.values()];
+}
+
+function buildTasksFromSpecificationLegacy(spec, request) {
+  const tasks = [];
+  for (const deliverable of spec.deliverables || []) {
+    const title = taskTitleForDeliverable(deliverable);
+    const files = deliverable.targetFile ? [deliverable.targetFile] : [];
+    const acceptance = [
+      'Implementação limitada ao deliverable do spec ' + spec.specPath,
+      'Regras do spec respeitadas',
+      'Sem executar comandos descritos no Markdown durante o planejamento'
+    ];
+    for (const exported of deliverable.exports || []) {
+      acceptance.push('Exportar ' + exported);
+    }
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title,
+      description: 'Implementar o deliverable definido em ' + spec.specPath + ': ' + deliverable.title + '.',
+      files,
+      acceptance,
+      engine: inferEngine(title)
+    });
+  }
+
+  if ((spec.mandatoryTests || []).length > 0) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Adicionar testes obrigatórios',
+      description: 'Adicionar a cobertura obrigatória definida em ' + spec.specPath + '.',
+      priority: 'high',
+      files: ['tests/'],
+      acceptance: ['Cobrir os ' + spec.mandatoryTests.length + ' testes obrigatórios do spec', 'Não chamar worker real, engine paga, Claude ou rede nos testes'],
+      engine: 'codex9'
+    });
+  }
+
+  if ((spec.docsToUpdate || []).length > 0) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Atualizar documentação',
+      description: 'Atualizar somente a documentação solicitada em ' + spec.specPath + '.',
+      priority: 'medium',
+      files: spec.docsToUpdate,
+      acceptance: spec.docsToUpdate.map(item => 'Atualizar ' + item),
+      engine: 'memory'
+    });
+  }
+
+  if ((spec.validationCommands || []).length > 0) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Validar implementação',
+      description: 'Rodar as validações listadas no spec depois da implementação, sem executá-las durante o planejamento.',
+      priority: 'medium',
+      files: [],
+      acceptance: spec.validationCommands.map(command => 'Validar com: ' + command),
+      engine: 'codex9'
+    });
+  }
+
+  tasks.push({
+    ...specTaskBase(spec, request),
+    title: 'Criar commit',
+    description: 'Criar o commit final solicitado pelo spec após validações e revisão do escopo.',
+    priority: 'medium',
+    files: [],
+    acceptance: [spec.expectedCommit ? 'Commit esperado: ' + spec.expectedCommit : 'Commit criado com mensagem coerente', 'Parte seguinte não implementada fora do spec'],
+    engine: 'codex9'
+  });
+
+  return tasks;
+}
+
+export function buildTasksFromSpecification(spec, request) {
+  const tasks = [];
+  for (const deliverable of spec.deliverables || []) {
+    const title = taskTitleForDeliverable(deliverable);
+    const acceptance = [
+      'Implementar codigo backend somente nos arquivos esperados',
+      'Regras tecnicas do spec respeitadas',
+      'Sem executar comandos descritos no Markdown durante o planejamento'
+    ];
+    for (const exported of deliverable.exports || []) {
+      acceptance.push('Exportar ' + exported);
+    }
+    acceptance.push(...restrictionAcceptance(spec));
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title,
+      description: 'Implementar codigo backend definido em ' + spec.specPath + ': ' + deliverable.title.replace(/\x60/g, '') + '.',
+      files: safeExpectedFiles(deliverable.targetFile ? [deliverable.targetFile] : [], spec),
+      acceptance,
+      engine: inferEngine(title),
+      planRole: 'implementation'
+    });
+  }
+
+  if ((spec.mandatoryTests || []).length > 0) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Adicionar testes obrigat\u00f3rios',
+      description: 'Adicionar a cobertura obrigatoria definida em ' + spec.specPath + '.',
+      priority: 'high',
+      files: safeExpectedFiles([spec.testTargetFile || 'tests/'], spec),
+      acceptance: ['Cobrir os ' + spec.mandatoryTests.length + ' testes obrigatorios do spec', 'Nao chamar worker real, engine paga, Claude ou rede nos testes', ...restrictionAcceptance(spec)],
+      engine: 'codex9',
+      planRole: 'tests'
+    });
+  }
+
+  if (spec.packageCheckTargetFile) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Atualizar script check no package.json',
+      description: 'Atualizar somente o script check quando o spec exigir inclusao de novo modulo.',
+      priority: 'medium',
+      files: safeExpectedFiles([spec.packageCheckTargetFile], spec),
+      acceptance: ['Script check cobre o novo modulo solicitado', 'Nenhum outro script e alterado sem necessidade', ...restrictionAcceptance(spec)],
+      engine: 'codex9',
+      planRole: 'check-script'
+    });
+  }
+
+  if ((spec.docsToUpdate || []).length > 0) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Atualizar documenta\u00e7\u00e3o',
+      description: 'Atualizar somente a documentacao solicitada em ' + spec.specPath + '.',
+      priority: 'medium',
+      files: safeExpectedFiles(spec.docsToUpdate, spec),
+      acceptance: spec.docsToUpdate.map(item => 'Atualizar ' + item),
+      engine: 'memory',
+      planRole: 'docs'
+    });
+  }
+
+  if ((spec.validationCommands || []).length > 0) {
+    tasks.push({
+      ...specTaskBase(spec, request),
+      title: 'Validar implementa\u00e7\u00e3o',
+      description: 'Rodar as validacoes listadas no spec depois da implementacao, sem executa-las durante o planejamento.',
+      priority: 'medium',
+      files: [],
+      acceptance: [...spec.validationCommands.map(command => 'Validar com: ' + command), ...restrictionAcceptance(spec)],
+      engine: 'codex9',
+      planRole: 'validation'
+    });
+  }
+
+  tasks.push({
+    ...specTaskBase(spec, request),
+    title: 'Criar commit',
+    description: 'Criar o commit final solicitado pelo spec apos validacoes e revisao tecnica.',
+    priority: 'medium',
+    files: [],
+    acceptance: [spec.expectedCommit ? 'Commit esperado: ' + spec.expectedCommit : 'Commit criado com mensagem coerente', 'Parte seguinte nao implementada fora do spec'],
+    engine: 'codex9',
+    planRole: 'commit'
+  });
+
+  return ensureConservativeSingleModulePlan(dedupeTasks(tasks), spec).map(task => {
+    const { planRole, ...publicTask } = task;
+    return publicTask;
+  });
+}
+
+export async function buildSpecPlan(request) {
+  const reference = await detectSpecificationReference(request);
+  if (!reference.hasSpecFile) {
+    return { usedSpec: false };
+  }
+  const root = projectRoot();
+  const absoluteSpecPath = path.resolve(root, reference.specPath);
+  const stat = await fs.stat(absoluteSpecPath);
+  if (!stat.isFile() || stat.size > MAX_SPEC_BYTES) {
+    return { usedSpec: false };
+  }
+  const content = await fs.readFile(absoluteSpecPath, 'utf-8');
+  const spec = parseSpecificationMarkdown(content, reference.specPath);
+  if (!spec.deliverables || spec.deliverables.length === 0) {
+    return { usedSpec: false };
+  }
+  const tasks = buildTasksFromSpecification(spec, request);
+  return {
+    usedSpec: true,
+    specPath: reference.specPath,
+    plannerKind: SPEC_PLANNER_VERSION,
+    kind: 'specification',
+    tasks
+  };
+}
+
+export async function tryBuildSpecTasks(request) {
+  try {
+    return await buildSpecPlan(request);
+  } catch (error) {
+    return { usedSpec: false };
+  }
+}