atlas-workflow 0.9.1 → 0.9.3

package/hosts/opencode/.opencode/atlas/packages/templates/BACKLOG_MESTRE_TEMPLATE.md

@@ -811,7 +811,17 @@ Ações imediatas:
 
 ---
 
-## 21. Como usar este template
+## 21. Registro de alterações
+
+Registro append-only de atualizações deste backlog. Não substitui decisões da seção 18.
+
+| Data | IDs afetados | Alteração | Motivo / fonte |
+|---|---|---|---|
+| [AAAA-MM-DD] | [SNN/DEC-N/RN] | [resumo objetivo] | [pedido, PRD, contrato ou código] |
+
+---
+
+## 22. Como usar este template
 
 ### Setup inicial
 
@@ -840,5 +850,6 @@ Ações imediatas:
 ### Manter vivo
 
 16. Toda decisão que muda escopo, contrato ou sequência atualiza: fonte canônica → PRD afetado → este backlog.
-17. Registrar decisões na seção 18 e riscos na seção 19.
-18. Manter o registro de sprints (seção 7) e o progresso (seção 8.2) como fonte de estado do projeto.
+17. Em updates, preservar IDs, sprints `done`, decisões fechadas e itens não relacionados; bloquear ciclos, enums inválidos e placeholders acidentais.
+18. Registrar decisões na seção 18, riscos na seção 19 e cada update no registro append-only da seção 21.
+19. Manter o registro de sprints (seção 7) e o progresso (seção 8.2) como fonte de estado do projeto.

package/hosts/opencode/.opencode/atlas/packages/templates/PRD_TEMPLATE.md

@@ -16,6 +16,7 @@
 | **Data** | <YYYY-MM-DD> |
 | **Dependências de negócio** | <Entregas anteriores necessárias — ex.: “dashboard com lista”> |
 | **Relacionado** | <Regras de negócio, MVP, backlog §X, DEC-*, Q-* — links> |
+| **Fonte da sprint** | <path explícito do backlog autoritativo + anchor único SNN> |
 
 ### Metadados de execução
 
@@ -134,7 +135,7 @@
 
 **Dependências:** <ID entrega — por que bloqueia ou alimenta> · <decisão externa, se houver>
 
-**Referências:** <PRD pai, regras de negócio, backlog — sem listar arquivos de código>
+**Referências:** <PRD pai, regras de negócio, backlog autoritativo + anchor; anchors de contrato/código usados na validação, sem copiar implementação>
 
 **Histórico:** <YYYY-MM-DD — evento>
 

package/hosts/opencode/.opencode/atlas/packages/templates/STATE_FILE_SCHEMA.md

@@ -8,7 +8,7 @@ Path:
 .atlas/state/<run_id>/<slice>.json
 ```
 
-Schema mínimo:
+Schema legado mínimo (reader compatível):
 
 ```json
 {
@@ -24,9 +24,33 @@ Schema mínimo:
 }
 ```
 
+Extensão determinística (writer atual):
+
+```json
+{
+  "base_sha": "40-char git commit SHA",
+  "head_sha": "40-char git commit SHA",
+  "contract_kind": "plan | direct",
+  "obligations": [{"id": "O1", "requirement": "...", "expected_evidence": ["path/test/check"]}],
+  "invariants": [{"id": "I1", "requirement": "...", "expected_evidence": ["path/check"]}],
+  "scenario_probes": [{"id": "S1", "scenario": "...", "expected": "..."}],
+  "risk_probes": [{"id": "R1", "risk": "...", "probe": "..."}],
+  "validation_map": [{"obligation_ids": ["O1"], "checks": ["node --test ..."], "status": "passed"}],
+  "task_evidence": [{"task": "T01", "files": ["packages/foo.js"], "checks": ["node --test ..."], "result": "passed"}],
+  "repair_evidence": [{"finding_id": "F-001", "files_touched": ["packages/foo.js"], "checks_run": ["node --test ..."], "status": "resolved"}],
+  "worktree_baseline": [{"path": "preexisting.txt", "status": "M", "sha256": "<64 hex>"}],
+  "worktree_final": [{"path": "preexisting.txt", "status": "M", "sha256": "<64 hex>"}]
+}
+```
+
 Regras:
 
 - `run_id`, `slice`, `tasks`, `files_changed`, `diff_stat`, `plan_path`, `boundary_refs`, `executed_at` e `executor_skill` são obrigatórios.
 - `files_changed` contém paths relativos ao repositório consumidor.
 - `boundary_refs` aponta para invariantes, contratos ou tasks do plano que delimitam a validação.
 - O arquivo é uma projeção de boundary para o validator; estado de run continua tendo `atlas_run_state` como fonte primária quando MCP estiver disponível.
+- Writers atuais sempre preenchem a extensão. `contract_kind=direct` exige `obligations` não vazio; `plan` mantém o contrato autoritativo em `plan_path`.
+- Writers capturam `worktree_baseline` antes da primeira mutação e `worktree_final` imediatamente antes do handoff. Ambos usam entradas únicas/ordenadas `{path,status,sha256}`; `status` é `A|M|D|R|C|T|U`, delete usa `sha256:null`, symlink usa SHA-256 do target textual.
+- Readers aceitam temporariamente o schema legado mínimo somente para `atlas-plan-execute` sem `contract_kind`. `atlas-direct-execute` nunca degrada para legado.
+- `base_sha` e `head_sha` são commits explícitos; não inferir base pelo nome da branch. `files_changed` e os arquivos de `task_evidence`/`repair_evidence` devem ser exatamente o diff `base_sha...head_sha` somado ao delta `worktree_baseline→worktree_final`. Dirty preexistente byte/status-idêntico fica fora.
+- `repair_evidence` é aditivo e obrigatório por finding P0/P1 estruturado após repair; o segundo validator correlaciona pelo mesmo `finding_id`.

package/hosts/opencode/.opencode/skills/_shared/references/stack-profiles.md

@@ -0,0 +1,36 @@
+# Baseline universal e perfis de stack
+
+Ativação é determinística: inspecione manifests no boundary e comandos realmente declarados no repo/plano. Use `detectStackProfiles(project_root, declared_commands, boundary_paths)`; consuma o array `boundaries` e não deduza stack por extensão isolada.
+
+## Baseline universal — sempre ativo
+
+- segurança, autenticação/autorização e dados sensíveis;
+- boundary real, contratos, schemas e consumidores afetados;
+- erros, falhas parciais, concorrência, idempotência e reentrada;
+- setup/cleanup, recursos, estado stale e persistência;
+- integridade de dados, nulos, enums, validação de input;
+- checks declarados pelo repo/plano, sem inventar ferramenta.
+
+## Flutter/Dart — `pubspec.yaml` ou comando `flutter`/`dart`
+
+- lifecycle de Widget/Controller/Store, dispose/reset e async stale;
+- rotas literais antes de parametrizadas quando o roteador exigir;
+- args obrigatórios, null-safety, casts defensivos, coleções `?? []`;
+- l10n em todos os locales e geração limpa;
+- `flutter analyze`/`flutter test` somente quando declarados/aplicáveis;
+- GetX apenas quando dependência/import/regras reais do repo confirmarem GetX.
+
+## Node/TypeScript — `package.json`, `tsconfig.json` ou comando Node real
+
+- lifecycle de processos/handles, abort/cleanup e promises rejeitadas;
+- validação runtime nas fronteiras JSON/HTTP/MCP;
+- ESM/CJS, exports, tipos e scripts realmente declarados;
+- `node --test`, test runner, lint/typecheck apenas se presentes no repo/plano.
+
+## Python — `pyproject.toml`, `requirements.txt`, `setup.py` ou comando Python real
+
+- context managers, cleanup, exceções e async/cancelamento;
+- parsing/typing nas fronteiras e mutabilidade de defaults;
+- `pytest`, `ruff`, `mypy` ou equivalente apenas se declarados.
+
+Perfis podem coexistir em monorepo. Regra de perfil nunca vira finding fora do boundary onde seu sinal foi ativado.

package/hosts/opencode/.opencode/skills/_shared/scripts/document_quality.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const VALID = Object.freeze({
+  moscow: new Set(['Must', 'Should', 'Could', "Won't now"]),
+  gain: new Set(['alto', 'médio', 'baixo']),
+  effort: new Set(['alto', 'médio', 'baixo']),
+  priority: new Set(['P0', 'P1', 'P2', 'P3']),
+  state: new Set(['backlog', 'ready', 'doing', 'review', 'done', 'blocked']),
+});
+
+const STACK_MANIFESTS = ['package.json', 'tsconfig.json', 'pubspec.yaml', 'pyproject.toml', 'requirements.txt', 'setup.py'];
+
+function boundaryRoot(projectRoot, boundary) {
+  const project = path.resolve(projectRoot);
+  let current = path.resolve(project, boundary ?? '.');
+  const relative = path.relative(project, current);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`BOUNDARY_OUTSIDE_PROJECT:${boundary}`);
+  }
+  if (fs.existsSync(current) && fs.statSync(current).isFile()) current = path.dirname(current);
+  while (current === project || current.startsWith(`${project}${path.sep}`)) {
+    if (STACK_MANIFESTS.some((name) => fs.existsSync(path.join(current, name)))) return current;
+    if (current === project) break;
+    current = path.dirname(current);
+  }
+  return path.resolve(project, boundary ?? '.');
+}
+
+function containsGetxImport(root) {
+  const queue = ['lib', 'test'].map((name) => path.join(root, name)).filter((dir) => fs.existsSync(dir));
+  let inspected = 0;
+  while (queue.length > 0 && inspected < 5000) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) queue.push(target);
+      else if (entry.isFile() && entry.name.endsWith('.dart')) {
+        inspected += 1;
+        if (/package:get\/get(?:_core)?\.dart/.test(fs.readFileSync(target, 'utf8'))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function detectBoundaryProfile(root, declaredCommands) {
+  const exists = (name) => fs.existsSync(path.join(root, name));
+  const commands = declaredCommands.filter((v) => typeof v === 'string');
+  let packageJson = null;
+  if (exists('package.json')) {
+    try { packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch {}
+  }
+  let pubspec = '';
+  if (exists('pubspec.yaml')) {
+    try { pubspec = fs.readFileSync(path.join(root, 'pubspec.yaml'), 'utf8'); } catch {}
+  }
+  const packageCommands = Object.values(packageJson?.scripts ?? {}).filter((v) => typeof v === 'string');
+  const allCommands = [...commands, ...packageCommands];
+  const hasCommand = (re) => allCommands.some((command) => re.test(command));
+  return {
+    universal: true,
+    flutter_dart: exists('pubspec.yaml') || hasCommand(/\b(flutter|dart)\b/),
+    node_typescript: exists('package.json') || exists('tsconfig.json') || hasCommand(/\b(node|npm|pnpm|yarn|bun|tsc)\b/),
+    python: exists('pyproject.toml') || exists('requirements.txt') || exists('setup.py') || hasCommand(/\b(python3?|pytest|ruff|mypy)\b/),
+    getx: /^\s{0,4}get\s*:/m.test(pubspec) || containsGetxImport(root),
+  };
+}
+
+export function detectStackProfiles(root, declaredCommands = [], boundaryPaths = ['.']) {
+  const project = path.resolve(root);
+  const requested = boundaryPaths.length > 0 ? boundaryPaths : ['.'];
+  const boundaries = [...new Set(requested.map((boundary) => boundaryRoot(project, boundary)))].map((dir) => ({
+    boundary: path.relative(project, dir).replaceAll('\\', '/') || '.',
+    ...detectBoundaryProfile(dir, declaredCommands),
+  }));
+  return {
+    universal: true,
+    flutter_dart: boundaries.some((profile) => profile.flutter_dart),
+    node_typescript: boundaries.some((profile) => profile.node_typescript),
+    python: boundaries.some((profile) => profile.python),
+    getx: boundaries.some((profile) => profile.getx),
+    boundaries,
+  };
+}
+
+function parseTable(markdown, heading) {
+  const start = markdown.indexOf(heading);
+  if (start < 0) return [];
+  const tail = markdown.slice(start + heading.length);
+  const end = tail.search(/\n##?\s/);
+  return (end < 0 ? tail : tail.slice(0, end)).split('\n')
+    .filter((line) => /^\|.*\|\s*$/.test(line))
+    .map((line) => line.split('|').slice(1, -1).map((cell) => cell.trim()))
+    .filter((cells) => cells.length && !cells.every((cell) => /^-+$/.test(cell)));
+}
+
+export function parseSprintRows(markdown) {
+  const rows = parseTable(markdown, '## 7. Registro de sprints');
+  const header = rows.findIndex((row) => row[0] === 'ID');
+  return rows.slice(header + 1).filter((row) => /^S\d{2}[a-z]?$/.test(row[0])).map((row) => ({
+    id: row[0], name: row[1], phase: row[2], objective: row[3], moscow: row[4], gain: row[5].toLowerCase(),
+    effort: row[6].toLowerCase(), priority: row[7], prd: row[8], dependencies: row[9], state: row[10], gate: row[11], raw: row,
+  }));
+}
+
+export function parseDecisionRows(markdown) {
+  const rows = parseTable(markdown, '### Decisões bloqueantes');
+  const header = rows.findIndex((row) => row[0] === 'ID');
+  return rows.slice(header + 1).filter((row) => /^D\d+$/.test(row[0])).map((row) => ({
+    id: row[0], decision: row[1], blocks: row[2], owner: row[3], status: row[4], raw: row,
+  }));
+}
+
+function dependencyIds(value) {
+  if (!value || value === '—') return [];
+  return [...value.matchAll(/S\d{2}[a-z]?/g)].map((match) => match[0]);
+}
+
+function findCycle(rows) {
+  const graph = new Map(rows.map((row) => [row.id, dependencyIds(row.dependencies)]));
+  const visiting = new Set(); const visited = new Set();
+  const walk = (id, chain = []) => {
+    if (visiting.has(id)) return [...chain.slice(chain.indexOf(id)), id];
+    if (visited.has(id)) return null;
+    visiting.add(id);
+    for (const dep of graph.get(id) ?? []) {
+      const cycle = walk(dep, [...chain, id]);
+      if (cycle) return cycle;
+    }
+    visiting.delete(id); visited.add(id); return null;
+  };
+  for (const id of graph.keys()) { const cycle = walk(id); if (cycle) return cycle; }
+  return null;
+}
+
+function changeLogBody(markdown) {
+  const match = /^##\s+(?:Registro de alterações|Histórico de alterações)\s*$/im.exec(markdown);
+  if (!match) return null;
+  const tail = markdown.slice(match.index + match[0].length);
+  const end = tail.search(/\n##\s+/);
+  return (end < 0 ? tail : tail.slice(0, end)).trim();
+}
+
+export function validateBacklogUpdate(before, after, { authorizedIds = [] } = {}) {
+  const errors = [];
+  const authorized = new Set(authorizedIds);
+  const oldRows = parseSprintRows(before); const newRows = parseSprintRows(after);
+  const oldById = new Map(oldRows.map((row) => [row.id, row]));
+  const newById = new Map(newRows.map((row) => [row.id, row]));
+  if (oldById.size !== oldRows.length) errors.push('DUPLICATE_SPRINT_ID_BEFORE');
+  if (newById.size !== newRows.length) errors.push('DUPLICATE_SPRINT_ID_AFTER');
+  for (const [id, oldRow] of oldById) {
+    const next = newById.get(id);
+    if (!next) errors.push(`SPRINT_REMOVED:${id}`);
+    else if (JSON.stringify(oldRow.raw) !== JSON.stringify(next.raw) && !authorized.has(id)) {
+      errors.push(oldRow.state === 'done' ? `DONE_SPRINT_CHANGED:${id}` : `UNAUTHORIZED_SPRINT_CHANGED:${id}`);
+    }
+  }
+  const oldDecisions = new Map(parseDecisionRows(before).map((row) => [row.id, row]));
+  const newDecisions = new Map(parseDecisionRows(after).map((row) => [row.id, row]));
+  for (const [id, row] of oldDecisions) {
+    const next = newDecisions.get(id);
+    if (!next) errors.push(`DECISION_REMOVED:${id}`);
+    else if (/^(decidido|fechado|aprovado)$/i.test(row.status)
+      && JSON.stringify(row.raw) !== JSON.stringify(next.raw) && !authorized.has(id)) errors.push(`CLOSED_DECISION_CHANGED:${id}`);
+  }
+  for (const row of newRows) {
+    for (const [field, values] of Object.entries(VALID)) if (!values.has(row[field])) errors.push(`INVALID_ENUM:${row.id}:${field}:${row[field]}`);
+    for (const dependency of dependencyIds(row.dependencies)) {
+      if (!newById.has(dependency)) errors.push(`DEPENDENCY_NOT_FOUND:${row.id}:${dependency}`);
+    }
+  }
+  const cycle = findCycle(newRows); if (cycle) errors.push(`DEPENDENCY_CYCLE:${cycle.join('>')}`);
+  if (/\[(?:NOME_|RESULTADO_|observação|decisão|slug|pendente\])/i.test(after)) errors.push('UNRESOLVED_PLACEHOLDER');
+  if (before !== after) {
+    const oldLog = changeLogBody(before);
+    const newLog = changeLogBody(after);
+    if (newLog === null) errors.push('CHANGELOG_REQUIRED');
+    else if (oldLog !== null && !newLog.startsWith(oldLog)) errors.push('CHANGELOG_REWRITTEN');
+    else if (newLog === oldLog) errors.push('CHANGELOG_ENTRY_REQUIRED');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function resolveSprintAuthority({ sprintId, explicitPath, canonicalPath, candidates }) {
+  const normalized = candidates.map((candidate) => ({ ...candidate, path: path.resolve(candidate.path) }));
+  const byPath = (target) => normalized.find((candidate) => candidate.path === path.resolve(target));
+  if (explicitPath) {
+    const match = byPath(explicitPath); if (!match?.sprints.includes(sprintId)) throw new Error(`SPRINT_NOT_FOUND_IN_EXPLICIT_PATH:${sprintId}`); return match;
+  }
+  if (canonicalPath) {
+    const match = byPath(canonicalPath); if (!match?.sprints.includes(sprintId)) throw new Error(`SPRINT_NOT_FOUND_IN_CANONICAL_BACKLOG:${sprintId}`); return match;
+  }
+  const matches = normalized.filter((candidate) => candidate.sprints.includes(sprintId));
+  if (matches.length !== 1) throw new Error(matches.length ? `AMBIGUOUS_BACKLOG_AUTHORITY:${matches.map((m) => m.path).join(',')}` : `SPRINT_NOT_FOUND:${sprintId}`);
+  return matches[0];
+}
+
+export function closedDecisionIds(prd) {
+  return new Set([...prd.matchAll(/^\|\s*(D\d+)\s*\|\s*(?!<|\[)(.+?)\s*\|\s*$/gm)].map((match) => match[1]));
+}
+
+export function pendingInterviewQuestions(prd, questions) {
+  const closed = closedDecisionIds(prd);
+  return questions.filter((question) => !closed.has(question.decision_id));
+}
+
+export function applyInterviewRound(prd, answers, date = new Date().toISOString().slice(0, 10)) {
+  const ids = new Set();
+  for (const answer of answers) {
+    if (!answer || typeof answer.decision_id !== 'string' || !/^D\d+$/.test(answer.decision_id)) throw new Error('INVALID_DECISION_ID');
+    if (ids.has(answer.decision_id)) throw new Error(`DUPLICATE_DECISION_ID:${answer.decision_id}`);
+    if (typeof answer.value !== 'string' || !answer.value.trim()) throw new Error(`EMPTY_DECISION_VALUE:${answer.decision_id}`);
+    ids.add(answer.decision_id);
+  }
+  let updated = prd;
+  for (const answer of answers) {
+    const row = new RegExp(`^\\|\\s*${answer.decision_id}\\s*\\|.*$`, 'm');
+    const replacement = `| ${answer.decision_id} | ${answer.value} |`;
+    updated = row.test(updated) ? updated.replace(row, replacement) : updated.replace(/(\| ID \| Decisão \|\n\|[-| ]+\|)/, `$1\n${replacement}`);
+  }
+  const log = `${date} — entrevista: ${answers.map((answer) => answer.decision_id).join(', ')} persistida(s)`;
+  updated = /\*\*Histórico:\*\*/.test(updated)
+    ? updated.replace(/(\*\*Histórico:\*\*[^\n]*)/, `$1 · ${log}`)
+    : `${updated.trimEnd()}\n\n**Histórico:** ${log}\n`;
+  return updated;
+}
+
+export function persistInterviewRound(prdPath, answers, date = new Date().toISOString().slice(0, 10)) {
+  const absolute = path.resolve(prdPath);
+  const temporary = path.join(path.dirname(absolute), `.${path.basename(absolute)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    const current = fs.readFileSync(absolute, 'utf8');
+    const updated = applyInterviewRound(current, answers, date);
+    const materialized = closedDecisionIds(updated);
+    const missingBeforeWrite = answers.filter((answer) => !materialized.has(answer.decision_id));
+    if (missingBeforeWrite.length > 0) {
+      throw new Error(`DECISION_NOT_MATERIALIZED:${missingBeforeWrite.map((answer) => answer.decision_id).join(',')}`);
+    }
+    const mode = fs.statSync(absolute).mode;
+    fs.writeFileSync(temporary, updated, { encoding: 'utf8', mode });
+    fs.renameSync(temporary, absolute);
+    const readback = fs.readFileSync(absolute, 'utf8');
+    if (readback !== updated) throw new Error('READBACK_DIVERGENT');
+    return readback;
+  } catch (error) {
+    try { fs.rmSync(temporary, { force: true }); } catch {}
+    throw new Error(`INTERVIEW_PERSISTENCE_FAILED:${error.message}`);
+  }
+}

package/hosts/opencode/.opencode/skills/atlas-backlog-generator/SKILL.md

@@ -33,8 +33,10 @@ Se faltar informação não bloqueante, gere o backlog com premissas marcadas e
 6. **Decompor em sprints:** transforme o objetivo em fatias verticais pequenas, cada uma com objetivo único, dependências e PRD futuro (`PRD_S<NN>_<slug>.md`).
 7. **Priorizar:** para cada sprint, preencha MoSCoW, ganho, esforço e prioridade usando a regra da seção 8.3 do template.
 8. **Selecionar próxima sprint:** escolha a primeira sprint executável respeitando dependências, DoR, MoSCoW, esforço x ganho e risco. Registre a justificativa na seção 20.
-9. **Salvar artefato:** grave o backlog no path pedido ou, se não houver path, crie o diretório `.atlas/backlog/` no projeto consumidor e use `.atlas/backlog/BACKLOG_MESTRE_<slug>.md`.
-10. **Validar antes de finalizar:** releia o arquivo salvo e confirme que não restaram placeholders acidentais, exceto campos conscientemente pendentes e marcados.
+9. **Atualização não destrutiva:** se o arquivo já existe, compare antes/depois com `validateBacklogUpdate(before, after, { authorizedIds })` de `../_shared/scripts/document_quality.mjs`. `authorizedIds` contém somente IDs cuja mudança foi explicitamente decidida pelo usuário. Preserve demais IDs, linhas `done`, decisões `decidido|fechado|aprovado`, itens/sprints e ordem histórica.
+10. **Registrar alterações:** toda atualização acrescenta `## Registro de alterações` (data, IDs afetados, motivo e fonte). Não reescreva histórico anterior.
+11. **Salvar artefato:** grave o backlog no path pedido ou, se não houver path, crie o diretório `.atlas/backlog/` no projeto consumidor e use `.atlas/backlog/BACKLOG_MESTRE_<slug>.md`.
+12. **Validar antes de finalizar:** bloqueie se `validateBacklogUpdate` apontar sprint/decisão removida, sprint `done` alterada, enum inválido, ciclo de dependência, placeholder acidental ou falta de registro. Confirme também que dependências referenciam IDs existentes.
 
 ---
 
@@ -76,6 +78,7 @@ O backlog final deve:
 - Ter catálogo de fases preservado e adaptado apenas quando necessário.
 - Ter riscos, decisões e próxima sprint executável preenchidos.
 - Ser específico o bastante para gerar PRDs de sprint depois com `atlas-sprint-prd-generator`.
+- Preservar histórico/IDs em update e passar validação de ciclos/enums/placeholders.
 
 ---
 
@@ -86,3 +89,5 @@ O backlog final deve:
 - Não inventar endpoints, tabelas, schemas, fornecedores, métricas ou responsabilidades como fatos. Quando forem hipóteses, marcar como premissa.
 - Não transformar o backlog em plano técnico de implementação. Código, classes e comandos entram no plano/PRD quando apropriado, não no backlog mestre.
 - Não deixar `[...]` ou placeholders óbvios no arquivo final, salvo quando o campo estiver deliberadamente pendente e explicado.
+- Não renumerar IDs, reabrir/editar sprint `done`, alterar decisão fechada ou remover item não relacionado por conveniência editorial.
+- Não ser acionada pelo orquestrador: permanece **explicit-only**, fora de qualquer cadeia automática.

package/hosts/opencode/.opencode/skills/atlas-direct-execute/SKILL.md

@@ -149,6 +149,8 @@ For each task, keep a tiny task contract:
 
 Do not widen scope for opportunistic cleanup.
 
+**Minimalism rung (per task, before writing):** prefer the minimal viable implementation that satisfies the obligation — reuse existing repo code/symbol before introducing a new abstraction; use a stdlib/native platform feature before a new dependency; avoid indirection, factory, wrapper, extra layer, config option, or extra file not required by an obligation or invariant. This rung constrains only new abstraction/indirection/file/dependency. It never reduces trust-boundary validation, error handling, data-loss handling, invariants, scenario/test coverage, or negative paths. When minimal and safe conflict, choose safe.
+
 Before the first concrete task, emit `task_started`. After the first workspace mutation, emit `first_write`.
 
 ### 4. Gate each task
@@ -175,6 +177,8 @@ After tasks and local gates pass, write `.atlas/state/<run_id>/<slice>.json` fol
 
 For direct execution, the state file is still the only validator input. Use the user-provided PRD/spec path as `plan_path` when no handoff plan exists, and include direct-contract anchors in `boundary_refs` such as `direct.O1`, `direct.invariant.permissions`, or `direct.risk.partial_failure`.
 
+Persist the full direct contract using the additive state extension: `base_sha`, `head_sha`, `contract_kind: direct`, non-empty `obligations`, `invariants`, `scenario_probes`, `risk_probes`, `validation_map`, `task_evidence`, empty `repair_evidence`, `worktree_baseline` and `worktree_final`. Capture baseline before the first mutation and final immediately before handoff; `files_changed`/evidence must equal `base_sha...head_sha` + snapshot delta. Capture base from an explicit task/spec anchor or execution-start `HEAD`; never infer it from branch name. Recompute `head_sha` and `diff_stat` immediately before handoff. A direct state without obligations is invalid and must block.
+
 The state file is the only validator input. Validation is always **sibling**, on every host: this executor **never** dispatches `atlas-task-validator` itself and never validates its own work in the same context. After tasks and local gates pass and the state file is written, this executor **stops mutation** and returns `validator_handoff_required` with the `state_path`. The orchestrator then dispatches `atlas-task-validator` as the next isolated sibling phase, locks it via `atlas_lock_validator`, and — if the verdict is `fail` — dispatches `atlas-findings-repair` (not this executor) before the **2nd and last** validator.
 
 After writing the state file and before returning, emit `state_path_created` with the same `state_path`.
@@ -190,7 +194,7 @@ The verdict is consumed by the **orchestrator**, not by this executor:
 
 This executor only re-engages if the orchestrator explicitly re-dispatches it for a new slice. It must not "fix" observations and reopen a closed slice; real follow-up from an observation goes to the final report or backlog, not into an extra in-slice change.
 
-If isolated subagents are unavailable in the current environment, do not pretend the slice is validator-closed. Run a local self-check against the same contract, report `validator not run`, and mark residual risk explicitly.
+If isolated subagents or MCP are unavailable, return `blocked` with the missing prerequisite and next safe action. Never replace cold validation with a local self-check or report `validator not run` as an accepted pipeline outcome.
 
 ## Stop Conditions
 
@@ -211,7 +215,7 @@ Keep final report short:
 - changed scope
 - files touched
 - validations run
-- validator verdict/cycles
+- `validator_handoff_required` + `state_path`
 - blockers or residual risks
 
 Do not include the full internal contract unless the user asks.

package/hosts/opencode/.opencode/skills/atlas-findings-repair/SKILL.md

@@ -49,6 +49,7 @@ Leia `atlas_run_state` como fonte primária do estado da run. O `state_path` con
 5. **Não despachar validator, review ou qualquer subagente.** O orquestrador faz isso.
 6. **Não iniciar terceiro ciclo.** Esta skill existe só entre validator 1 e validator 2.
 7. **Não trocar o `state_path`.** Atualize o arquivo original em lugar; redirecionar o boundary invalida a correlação do repair.
+8. **Não inventar correlação.** IDs devem existir no packet recebido, sem duplicatas; todo arquivo tocado pertence a pelo menos um `repair_evidence` recebido e nenhum arquivo extra é permitido.
 
 ## Fluxo
 
@@ -67,6 +68,8 @@ Leia do plano apenas o mínimo necessário:
 - Section 6 — contratos técnicos
 - Section 8 — checklist
 
+Capture também `base_sha`, `head_sha`, `task_evidence`, `repair_evidence`, `worktree_baseline` e `worktree_final` do state.
+
 ### 2. Ler os findings recebidos
 
 Trabalhe somente com findings de severidade:
@@ -75,6 +78,8 @@ Trabalhe somente com findings de severidade:
 - `P1`
 - `P2`
 
+Cada finding novo deve ter `id`, `failure_mode`, `evidence`, `recommendation` e `fix_validation`. `msg` é compatibilidade deprecated e não substitui esses campos.
+
 Se o pacote vier vazio, inconsistente ou sem finding reparável, pare em `blocked`.
 
 ### 3. Montar contrato mínimo de reparo
@@ -115,7 +120,11 @@ Se o finding persistir por falta de decisão de produto, dependência externa ou
 
 Ao terminar:
 
-- atualize o conteúdo do `state_path` original se a evidência do boundary mudou
+- atualize `files_changed` com todo arquivo tocado, inclusive novo/adjacente
+- recompute `head_sha` (`git rev-parse HEAD`) e `diff_stat`; preserve `base_sha`
+- preserve `worktree_baseline` e recapture `worktree_final` após o repair; derive o boundary completo do delta entre snapshots
+- acrescente `repair_evidence[]` no shape `{finding_id, files_touched, checks_run, status}`
+- garanta que cada `repair_evidence.files_touched` esteja em `files_changed`
 - mantenha a mesma slice
 - não invente novo run state paralelo
 
@@ -128,6 +137,7 @@ Retorne saída curta e estruturada com:
 - `state_path`
 - `files_touched`
 - `checks_run`
+- `repairs`: array `{finding_id, files_touched, checks_run, status: resolved|blocked}`
 - `residual_risk` (se houver)
 
 O orquestrador chamará `atlas_lock_validator(action=repair_complete, repair_run_id=..., state_path=<mesmo path original>)` e só então poderá despachar o validator final.

package/hosts/opencode/.opencode/skills/atlas-plan-execute/SKILL.md

@@ -130,16 +130,30 @@ Create `.atlas/state/<run_id>/<slice>.json` following `packages/templates/STATE_
 {
   "run_id": "<run_id>",
   "slice": "<slice id>",
+  "base_sha": "<base commit explícito do plano/handoff>",
+  "head_sha": "<git rev-parse HEAD ao fechar a execução>",
+  "contract_kind": "plan",
   "tasks": ["T01"],
   "files_changed": ["relative/path.ext"],
   "diff_stat": "N files, +X -Y",
   "plan_path": ".atlas/plans/<id>.plan.md",
   "boundary_refs": ["§2.I1", "§6.1", "§8"],
+  "obligations": [],
+  "invariants": [{"id": "I1", "requirement": "<invariante>", "expected_evidence": ["<path/check>"]}],
+  "scenario_probes": [{"id": "S1", "scenario": "<cenário>", "expected": "<resultado>"}],
+  "risk_probes": [{"id": "R1", "risk": "<risco>", "probe": "<pergunta verificável>"}],
+  "validation_map": [{"obligation_ids": [], "checks": ["<comando>"], "status": "passed"}],
+  "task_evidence": [{"task": "T01", "files": ["relative/path.ext"], "checks": ["<comando>"], "result": "passed"}],
+  "repair_evidence": [],
+  "worktree_baseline": [{"path": "relative/preexisting.ext", "status": "M", "sha256": "<64 hex>"}],
+  "worktree_final": [{"path": "relative/preexisting.ext", "status": "M", "sha256": "<64 hex>"}],
   "executed_at": "ISO8601",
   "executor_skill": "atlas-plan-execute"
 }
 ```
 
+Capture `base_sha` da referência explícita do plano/handoff; nunca infira pelo nome da branch. Antes da primeira mutação, capture `worktree_baseline`; imediatamente antes do handoff, capture `worktree_final`. `files_changed` e `task_evidence` representam exatamente `base_sha...head_sha` + delta entre snapshots. Dirty preexistente byte/status-idêntico fica fora; qualquer alteração posterior entra.
+
 Validation is always **sibling**, on every host. The validator is registered as a real subagent on every host, but this executor **never** dispatches it and never validates its own work. After tasks and local gates pass and the state file is written, this executor **stops mutation** and returns `validator_handoff_required` with the `state_path`. The orchestrator dispatches `atlas-task-validator` as the next isolated sibling phase, locks it via `atlas_lock_validator`, and — if the verdict is `fail` — dispatches `atlas-findings-repair` (not this executor) before the **2nd and last** validator.
 
 After writing the state file and before returning, emit `state_path_created` with the same `state_path`.
@@ -157,5 +171,5 @@ This executor does not parse the validator output — the **orchestrator** does,
 
 Never decide by substring matching prose. Once the slice is closed, do not edit code, tests, or boundary files just to satisfy an observation; that reopens the slice and forces an avoidable re-validation. Real follow-up from an observation goes to the final report or a backlog item, not into an extra in-slice change.
 
-### 10. Report final outcome
-At the end of execution, report completed tasks, validations run, validator outcome, and any residual gaps.
+### 10. Report executor handoff
+Report only completed tasks, local validations, files changed, and `validator_handoff_required` with `state_path`. Validator verdict/cycles and final residuals belong exclusively to the orchestrator's final report.

package/hosts/opencode/.opencode/skills/atlas-plan-handoff/SKILL.md

@@ -47,8 +47,8 @@ No workflow `full`, `atlas-plan-handoff` é autoria documental do agente princip
 
 ## Fluxo obrigatório
 
-1. **Classificação da tarefa:** feature, ui, contract, navigation, shared, security, diagnostic, refactoring, testing. Leia `project-rules/index/<tipo>.md` e regras em `project-rules/rules/` (ou equivalente do repo ativo).
-2. **Grounding no código:** confirme padrões, contratos e comandos locais (`flutter analyze` / `flutter test` com path do package) antes de inferir.
+1. **Classificação da tarefa:** feature, ui, contract, navigation, shared, security, diagnostic, refactoring, testing. Leia instruções reais aplicáveis do repo; `project-rules/` é apenas um formato possível, nunca requisito universal.
+2. **Grounding no código:** confirme padrões, contratos, manifests e comandos reais antes de inferir. Resolva baseline/perfis via `../_shared/references/stack-profiles.md` + `detectStackProfiles(project_root, declared_commands, boundary_paths)`; não presuma Flutter nem aplique perfil fora do package correspondente.
 3. **Decisões estáveis:** sanar bloqueios com perguntas ao usuário; registrar no plano (não recopiar tabela D* do PRD — referenciar `PRD §3`).
 4. **Escrita:** artefato markdown no path canônico `.atlas/plans/`. Teto orientativo ~250–350 linhas (até ~450 com slices).
 
@@ -112,7 +112,9 @@ Tarefas `#### T01.` … `#### TNN.` com schema de `BOUNDARY_PRD_PLAN.md` canôni
 - **Quality gates** (opcional em tasks críticas)
 - **Casos mínimos** (somente em tasks de teste)
 
-Última task típica: **Validação final** (`flutter analyze`, `flutter test`, passos manuais alinhados a **PRD §4–6**).
+**Regra de minimalismo estrutural (autoria de task):** ao redigir `Mudança esperada`, prefira a forma mínima viável que cumpre o `Critério de done` — reusar módulo/símbolo já existente no repo antes de introduzir nova abstração; usar stdlib/feature nativa antes de dependência nova; evitar indireção, factory, wrapper, camada ou opção de config não exigida por PRD/invariante. A regra recai **somente** sobre abstração/indireção/arquivo/dependência nova. **Nunca** reduz: validação de trust-boundary, error-handling, data-loss, invariantes §2, cobertura de cenário/teste e negative paths. Em dúvida entre enxuto e seguro, escolha seguro.
+
+Última task típica: **Validação final** (checks reais da stack ativa e passos manuais alinhados a **PRD §4–6**). Flutter usa `flutter analyze/test`; Node e Python usam somente scripts/ferramentas declarados no repo/plano.
 
 ### 6. Contratos técnicos (só ambiguidade PRD → código)
 
@@ -126,7 +128,7 @@ Tarefas `#### T01.` … `#### TNN.` com schema de `BOUNDARY_PRD_PLAN.md` canôni
 
 - Critérios derivados de **PRD §6** + invariantes **§2** deste plano.
 - Título recomendado: `## 8. Validação e checklist (validator)`.
-- Comandos globais de analyze/test do package.
+- Comandos globais aplicáveis ao package, derivados de manifests/scripts reais; nunca inventar `flutter`, `npm` ou `pytest`.
 
 ---
 

package/hosts/opencode/.opencode/skills/atlas-prd-interview/SKILL.md

@@ -41,8 +41,11 @@ Ataque principalmente as seguintes seções do template de PRD:
 * **§5 Contrato funcional e invariantes:** `❌` se campos críticos não possuírem regras de formato (ex: decimais) ou se a regra de negócio for ambígua/impossível de verificar na codebase.
 * **§6 Critérios de aceite (negócio):** `❌` se o critério for subjetivo, não observável ou não testável.
 
-3. **Perguntas por Rodada (AskUserQuestion):** Formule rodadas de no máximo 4 perguntas concisas via ferramenta nativa `AskUserQuestion`, com exatamente 3 opções e indicando a recomendada. **Pare o turno e aguarde a resposta.**
-4. **Veredito Final:** Só emita o veredito de `Pronto para planejamento` quando zerar todos os `❌`.
+3. **Resolver mecanismo estruturado:** chame `atlas_capabilities`, leia `question_prompt` e use seu `mechanism`/shape. Nunca hardcode nome de ferramenta de host. Se o descriptor estiver ausente ou indisponível, bloqueie a rodada; não degrade para pergunta livre sem correlação.
+4. **Perguntas por rodada:** formule no máximo 4 perguntas concisas, exatamente 3 opções, recomendada explícita e `decision_id` D* estável. Antes de perguntar, use `pendingInterviewQuestions` de `../_shared/scripts/document_quality.mjs` para excluir decisões já fechadas.
+5. **Persistência imediata:** ao receber respostas, grave-as no mesmo PRD antes de qualquer nova pergunta, preservando IDs/anchors e acrescentando histórico. Use `persistInterviewRound(prd_path, answers)`, que escreve via arquivo temporário + rename e valida readback; falha bloqueia. Nunca acumule respostas apenas no chat.
+6. **Reindexação:** releia o PRD salvo, reexecute o índice §3–§6 e recalcule perguntas pendentes. Decisão fechada não pode reaparecer em rodada posterior.
+7. **Veredito Final:** só emita `Pronto para planejamento` quando zerar todos os `❌`; no workflow, devolva controle ao orquestrador para reexecutar artifact/scan/TC.
 
 ---
 
@@ -55,6 +58,8 @@ Ataque principalmente as seguintes seções do template de PRD:
 §6 Aceite:        ✅/⚠️/❌
 ```
 
+O índice é materializado novamente após cada persistência; não reutilize índice anterior à resposta.
+
 ---
 
 ## Uso standalone vs protocolo interno no workflow (PRD D10/D11)