atlas-workflow 0.9.1 → 0.9.3

package/hosts/zcode/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/zcode/skills/atlas-backlog-generator/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: atlas-backlog-generator
+description: Skill `atlas-backlog-generator`. Use somente quando o usuário acionar explicitamente `$atlas-backlog-generator` ou pedir explicitamente para criar, gerar, montar, estruturar ou atualizar um backlog mestre Atlas a partir de uma conversa, prompt, ideia de feature, briefing, PRD macro, lista solta de requisitos, roadmap ou objetivo de produto, usando `BACKLOG_MESTRE_TEMPLATE.md` como template canônico e aplicando fases, sprints, dependências, MoSCoW e esforço x ganho. Não usar por inferência implícita em pedidos genéricos de planejamento, brainstorming, PRD ou implementação.
+---
+
+# Atlas Backlog Generator
+
+Crie backlogs mestres Atlas em PT-BR, ancorados no template canônico, com decomposição gradual em fases e sprints pequenas, priorização MoSCoW, matriz esforço x ganho, dependências explícitas, gates, riscos e próxima sprint executável.
+
+Esta skill é documental: ela cria ou atualiza o `BACKLOG_MESTRE*.md` no projeto consumidor. Ela não implementa código, não gera PRDs de sprint e não substitui `atlas-sprint-prd-generator`.
+
+Acione esta skill apenas por pedido explícito. Se o usuário apenas pedir planejamento, brainstorming, PRD ou execução, não usar esta skill automaticamente.
+
+---
+
+## Entradas aceitas
+
+- Conversa livre, ideia de feature, prompt exploratório ou briefing incompleto.
+- PRD macro, roadmap, lista de requisitos, issue/backlog item ou texto colado pelo usuário.
+- Opcional: nome do projeto/feature, path de saída, fontes canônicas, restrições técnicas, prioridade de negócio e escopo fora do ciclo.
+
+Se faltar informação não bloqueante, gere o backlog com premissas marcadas e registre perguntas/riscos. Pergunte antes de salvar somente quando faltar uma das decisões bloqueantes: resultado final esperado, fronteira de escopo ou plataforma/produto alvo.
+
+---
+
+## Workflow obrigatório
+
+1. **Resolver template canônico:** descubra a raiz do plugin/bundle e leia `packages/templates/BACKLOG_MESTRE_TEMPLATE.md`. Se ausente, aborte com: `Template canônico ausente: BACKLOG_MESTRE_TEMPLATE.md`.
+2. **Entender pedido:** extraia objetivo, usuários, resultado final esperado, fora de escopo, restrições, dependências, riscos, stakeholders e sinais de valor.
+3. **Inspecionar contexto real:** quando houver repo/projeto ativo, busque documentos existentes (`BACKLOG_MESTRE*.md`, `PRD*.md`, `ROADMAP*.md`, specs, OpenAPI, docs de arquitetura) e código que influencie dependências. Não invente contrato técnico.
+4. **Fechar ambiguidade crítica:** se uma decisão bloquear a decomposição segura, faça até 3 perguntas objetivas. Se o usuário não responder e houver caminho razoável, registre a premissa como risco/decisão pendente.
+5. **Preencher o template:** mantenha todas as seções do template e substitua placeholders por conteúdo específico. Não apague seções; use `não aplicável` apenas com justificativa curta.
+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. **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.
+
+---
+
+## Regras de decomposição
+
+- Gere sprints como unidades de entrega, não períodos de tempo.
+- Mantenha cada sprint com 6 a 8 tasks no máximo quando o PRD futuro for detalhado; se uma sprint tiver mais de um objetivo, quebre em `S<NN>a/b/c`.
+- Comece com descoberta/contrato quando houver ambiguidade ou integração. Não pule para implementação quando o contrato ainda for desconhecido.
+- Preserve a ordem natural: descoberta → especificação/contrato → backend/infra quando necessário → front/app → hardening → QA → rollout.
+- Use dependências para permitir paralelismo seguro; não transforme fase em fila rígida se duas sprints independentes puderem avançar.
+- Inclua estados de erro, loading, empty, permission, observabilidade, QA e rollout onde aplicável. Esses itens não são “extras”; são parte do produto pronto.
+
+---
+
+## Regras de priorização
+
+- `Must`: obrigatório para resultado final, segurança, compliance, contrato ou desbloqueio.
+- `Should`: importante para qualidade/adoção, mas contornável por um ciclo.
+- `Could`: refinamento ou melhoria desejável que não bloqueia entrega.
+- `Won't now`: fora do ciclo atual; registre para reduzir reabertura de discussão.
+- `P0`: alto ganho com baixo/médio esforço ou Must desbloqueador.
+- `P1`: alto ganho com alto esforço, ou médio ganho com baixo esforço.
+- `P2`: médio ganho/médio esforço, ou baixo ganho/baixo esforço.
+- `P3`: baixo ganho com médio/alto esforço, candidato a adiar.
+
+Se MoSCoW e esforço x ganho conflitarem, MoSCoW vence; uma sprint `Must` de esforço alto deve ser quebrada, não rebaixada silenciosamente.
+
+---
+
+## Qualidade esperada do backlog
+
+O backlog final deve:
+
+- Declarar precedência documental e fontes canônicas.
+- Explicitar resultado esperado e fora do escopo.
+- Ter dependências internas/externas e decisões bloqueantes com dono/status.
+- Ter registro de sprints com MoSCoW, ganho, esforço, prioridade, PRD futuro, dependências, estado e gate.
+- Ter grafo de dependência coerente com a tabela de sprints.
+- 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.
+
+---
+
+## Proibições
+
+- Não entregar uma lista genérica de tarefas sem usar o template.
+- Não remover gates, DoR/DoD, riscos, decisões ou trilhas transversais.
+- 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/zcode/skills/atlas-backlog-generator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Atlas Backlog Generator"
+  short_description: "Cria backlog mestre Atlas a partir de ideia, prompt ou conversa."
+  default_prompt: "Crie um backlog mestre Atlas para esta ideia de feature:"

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

@@ -0,0 +1,221 @@
+---
+name: atlas-direct-execute
+description: Execute a scoped PRD, task, or implementation slice directly using a compact execution contract, PRD obligation tracking, finite task gates, bounded repair, and mandatory cold validation via atlas-task-validator. Use when the user provides a PRD/spec/path or a debated task and wants implementation now without first producing a separate planning artifact. Preserve evidence against acceptance criteria, dependencies, fixtures, and invariants.
+---
+
+# Atlas Direct Execute
+
+## Purpose
+
+Execute directly from a PRD/spec/task while preserving execution quality: explicit scope, obligations, invariants, task order, risks, and validation. Do not write a separate planning artifact unless the user asks.
+
+This is not planless execution. Replace the visible markdown plan with a compact operational contract held in the current turn and passed to validation.
+
+## Executor liveness checkpoints
+
+Depois de carregar esta skill e antes de qualquer discovery longo, emita um checkpoint MCP:
+
+```json
+atlas_lock_dispatch({
+  "action": "checkpoint",
+  "phase": "plan_execute",
+  "event": "executor_started"
+})
+```
+
+Em seguida, emita checkpoints materiais conforme avança:
+
+- `skill_loaded` — skill carregada e contrato reconhecido.
+- `plan_loaded` — PRD/spec/task de entrada lido.
+- `handoff_accepted` — boundary, obligations, `state_path` alvo e contrato direto aceitos.
+- `task_started` — primeira task começou.
+- `first_write` — primeira mutação de workspace feita.
+- `state_path_created` — state file escrito antes de devolver `validator_handoff_required`.
+
+Se não conseguir emitir checkpoint por MCP, retorne `blocked`: liveness não é comprovável. Sem `state_path_created` com o mesmo `state_path`, `atlas_lock_validator(start)` bloqueia em G12 e o orquestrador não pode despachar o validador frio.
+
+## Use Criteria
+
+Use when all are true:
+
+- User wants implementation, not a planning artifact.
+- Scope is a PRD/spec/path or a debated task with clear boundaries.
+- Work fits one coherent slice or a bounded task sequence.
+- Execution happens in the same chat/context.
+- A compact contract can be materialized into the state file boundary required by `atlas-task-validator`.
+
+Do not use when any are true:
+
+- User asks only for planning, review, explanation, or handoff artifact.
+- Product rules, permissions, backend contract, migrations, security, or data-loss risk are materially ambiguous.
+- The PRD/spec conflicts with code or adjacent docs in a way that blocks implementation.
+
+## Workflow
+
+### 0. Triage
+
+Before implementation, decide one exact path:
+
+- `direct`: proceed with this skill.
+- `blocked`: ask for the missing decision or environment.
+
+Ask at most 1-3 blocking questions only when a reasonable assumption could change product behavior, contract, permissions, persistence, or user-visible outcome. Otherwise state assumptions and proceed.
+
+### 1. Load inputs
+
+First, emit `executor_started`, then `skill_loaded`, before doing any long scan.
+
+Read the user-provided PRD/spec/task and any directly referenced files needed to resolve scope. If the input names repo artifacts, verify those artifacts exist before editing.
+
+Extract only execution-relevant items:
+
+- in scope / out of scope
+- acceptance criteria and required deliverables
+- accepted decisions
+- invariants and "do not change" rules
+- contracts, entities, routes, schemas, wrappers, generated files
+- dependency contracts that must be consumed, bridged, or preserved
+- fixture requirements and scenario language such as "weeks", "profiles", "matrix", "sequence", or "integration"
+- validation requirements
+- regression risks
+- likely files/modules
+
+If the PRD references another PRD or code contract as dependency, inspect enough to confirm the dependency shape and required bridge. Do not satisfy a dependency by creating parallel synthetic contracts unless the PRD explicitly allows it.
+
+After the input is loaded, emit `plan_loaded`. After validating the execution boundary, obligations, and `state_path` target, emit `handoff_accepted`.
+
+### 2. Build Compact Execution Contract
+
+Before editing, write a compact contract in the working response or internal task state. Size follows complexity: terse for simple tasks, denser only where needed to preserve scope, invariants, and validator quality.
+
+Required shape:
+
+```text
+Direct Execute Contract
+- Goal:
+- Boundary:
+- In scope:
+- Out of scope:
+- Obligations:
+- Invariants:
+- Dependency bridges:
+- Fixtures/scenarios:
+- Scenario probes:
+- Risk probes:
+- Task order:
+- Validation:
+- Stop conditions:
+```
+
+Do not expand this into a separate planning artifact. The goal is execution guardrails, not transfer documentation. The contract may be terse in the user-visible response, but it must be concrete enough to materialize into `.atlas/state/<run_id>/<slice>.json` and referenced evidence for `atlas-task-validator`.
+
+Obligations are mandatory. Convert every PRD acceptance criterion and explicit deliverable into one compact row:
+
+```text
+O1 <requirement> -> evidence: <file/test/check>
+```
+
+When the PRD asks for fixtures, profiles, weeks, matrices, bridges/adapters, immutability, determinism, or calendar semantics, name those explicitly in `Obligations`. Do not collapse them into generic "tests cover rules".
+
+Add a closure analysis packet before implementation starts. Keep it compact, but concrete enough that a cold validator can hunt omissions instead of only confirming obvious files:
+
+- `Invariant ledger`: each invariant or "do not change" rule, with expected code evidence.
+- `Scenario probes`: negative, repeated, empty/null, out-of-order, partial failure, stale state, permission, and cleanup scenarios relevant to this slice.
+- `Contract probes`: DTO/entity/schema/route/RPC/generated/localization/import boundaries that could drift.
+- `Risk probes`: each regression risk translated into a specific question the validator must answer from code.
+- `Validation map`: which checks prove which obligations, and which obligations remain only manually evidenced.
+
+If a probe is irrelevant, omit it. Do not write generic probes such as "check edge cases"; name the exact state, actor, field, route, or failure mode.
+
+### 3. Implement by finite tasks
+
+Execute one task at a time. Prefer this order when applicable:
+
+1. contracts/types/domain
+2. dependency bridges/adapters from existing models or contracts
+3. datasource/client boundary
+4. repository/use case/state
+5. UI/route wiring
+6. fixtures/tests/generation/docs required for closure
+
+For each task, keep a tiny task contract:
+
+- objective
+- files likely touched
+- invariants at risk
+- obligations satisfied
+- focused check
+- repair budget
+
+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
+
+Run focused checks appropriate to the diff:
+
+- targeted tests
+- analyzer/typecheck/lint
+- codegen/localization/schema checks when relevant
+- diff scan for scope creep
+- runtime/browser verification when UI changed
+
+If a check fails, classify:
+
+- `fixable`: caused by current diff and repairable inside budget
+- `blocked`: missing env, upstream failure, ambiguous contract, or required decision
+- `pre-existing`: outside slice; report, do not repair unless blocking closure
+
+Repair only current-diff failures. Stop after repeated failure or budget exhaustion.
+
+### 5. Mandatory cold validation
+
+After tasks and local gates pass, write `.atlas/state/<run_id>/<slice>.json` following `packages/templates/STATE_FILE_SCHEMA.md`.
+
+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`.
+
+Do not paste the compact contract, diff, obligation ledger, local checks, or closure analysis packet into the state file's handoff. Those belong in the state file and referenced artifacts.
+
+**Finish all local work before the handoff — then stop idle.** Finish every local gate (lint, analyze, tests, `git diff --check`, diff-stat) and write the state file **before** returning the handoff. After returning `validator_handoff_required`, do nothing: no diff hygiene checks, no extra reads, no opportunistic edits, no parallel work. The orchestrator now owns the slice; any mutation here would change what the sibling validator reads and breaks determinism (same failure class as the orchestrator's G9).
+
+The verdict is consumed by the **orchestrator**, not by this executor:
+
+- `pass` / `pass_with_observations`: terminal — the orchestrator closes the slice (observations are reported residuals, never a trigger for another validator dispatch).
+- `fail`: the orchestrator opens `repair_start`, dispatches `atlas-findings-repair`, closes with `repair_run_id`, and runs the **2nd and last** validator. This executor does not re-validate itself and is not reused for the repair retry.
+
+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 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
+
+Stop and report instead of improvising when:
+
+- code contradicts the PRD in product behavior, permissions, backend contract, or persistence shape
+- required dependency PRD/contract is missing or unstable
+- implementing would violate explicit out-of-scope
+- deterministic checks cannot run and no equivalent evidence exists
+- repair loops repeat the same failure twice
+- validator cannot receive a valid `.atlas/state/<run_id>/<slice>.json` state path
+- any PRD obligation lacks code/test/check evidence after implementation
+
+## Final Report
+
+Keep final report short:
+
+- changed scope
+- files touched
+- validations run
+- `validator_handoff_required` + `state_path`
+- blockers or residual risks
+
+Do not include the full internal contract unless the user asks.

package/hosts/zcode/skills/atlas-direct-execute/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Direct Execute"
+  short_description: "Direct PRD execution with cold validation"
+  default_prompt: "Use $atlas-direct-execute to implement this PRD or scoped task directly with a compact obligation ledger, focused gates, and validator closure."
+
+policy:
+  allow_implicit_invocation: true