atlas-workflow 0.9.2 → 0.9.4

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

@@ -0,0 +1,288 @@
+#!/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',
+  'go.mod', 'Cargo.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts',
+  'firebase.json', '.firebaserc', 'openapi.yaml', 'openapi.yml', 'openapi.json', 'swagger.yaml', 'swagger.yml', 'swagger.json',
+];
+
+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 readIfExists = (name) => {
+    try { return exists(name) ? fs.readFileSync(path.join(root, name), 'utf8') : ''; } catch { return ''; }
+  };
+  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 packageDeps = Object.keys({
+    ...(packageJson?.dependencies ?? {}),
+    ...(packageJson?.devDependencies ?? {}),
+    ...(packageJson?.peerDependencies ?? {}),
+    ...(packageJson?.optionalDependencies ?? {}),
+  });
+  const cargo = readIfExists('Cargo.toml');
+  const pom = readIfExists('pom.xml');
+  const gradle = `${readIfExists('build.gradle')}\n${readIfExists('build.gradle.kts')}\n${readIfExists('settings.gradle')}\n${readIfExists('settings.gradle.kts')}`;
+  const allCommands = [...commands, ...packageCommands];
+  const hasCommand = (re) => allCommands.some((command) => re.test(command));
+  const hasPackageDep = (re) => packageDeps.some((dep) => re.test(dep));
+  const javaKotlinSignal = exists('pom.xml') || exists('build.gradle') || exists('build.gradle.kts')
+    || exists('settings.gradle') || exists('settings.gradle.kts') || hasCommand(/\b(gradle|mvn|java|javac|kotlinc)\b/);
+  const restSignal = exists('openapi.yaml') || exists('openapi.yml') || exists('openapi.json')
+    || exists('swagger.yaml') || exists('swagger.yml') || exists('swagger.json')
+    || hasPackageDep(/\b(openapi|swagger|express|fastify|koa|hono|axios|ky)\b/i)
+    || /openapi|swagger|spring-boot-starter-web|ktor|retrofit/i.test(`${pom}\n${gradle}\n${pubspec}`);
+  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/),
+    go: exists('go.mod') || hasCommand(/\bgo\s+(test|build|run|vet|fmt)\b/),
+    rust: exists('Cargo.toml') || hasCommand(/\bcargo\s+(test|build|run|check|clippy|fmt)\b/) || /^\s*\[package\]/m.test(cargo),
+    java_kotlin: javaKotlinSignal,
+    firebase: exists('firebase.json') || exists('.firebaserc') || hasPackageDep(/^firebase$|^@firebase\/|firebase-admin/i)
+      || /firebase_core|cloud_firestore|firebase_auth|firebase_messaging|firebase_storage/i.test(pubspec),
+    supabase: hasPackageDep(/^@supabase\/|supabase-js/i) || /supabase_flutter|supabase|postgrest/i.test(pubspec),
+    rest_openapi: restSignal,
+    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),
+    go: boundaries.some((profile) => profile.go),
+    rust: boundaries.some((profile) => profile.rust),
+    java_kotlin: boundaries.some((profile) => profile.java_kotlin),
+    firebase: boundaries.some((profile) => profile.firebase),
+    supabase: boundaries.some((profile) => profile.supabase),
+    rest_openapi: boundaries.some((profile) => profile.rest_openapi),
+    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-audit/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: atlas-audit
+description: Skill/mode universal de auditoria Atlas. Use para `/workflow audit <target>` com flags opcionais `--handoff` e `--scope <descrição>`. Audita código contra regras locais, boas práticas da stack detectada e complexidade acidental estilo Ponytail, sem corrigir código nem executar plano.
+---
+
+# Atlas Audit
+
+Auditoria universal, framework-agnóstica. Esta skill lê o repositório real, audita o `target` informado e entrega relatório de achados. Opcionalmente gera handoff Atlas-style para correção futura. **Nunca altera código. Nunca executa plano.**
+
+## Sintaxe
+
+```text
+/workflow audit <target>
+/workflow audit <target> --handoff
+/workflow audit <target> --scope <descrição>
+```
+
+`target` pode ser arquivo, diretório, pacote, módulo, feature, PRD/plano como referência ou descrição que aponte para um boundary localizável. Se não for possível resolver o boundary em disco, pare e peça um target mais preciso.
+
+## Contrato duro
+
+- Auditar o target informado, não o repo inteiro por padrão.
+- Diagnóstico factual vem antes de proposta de correção.
+- Todo achado precisa de evidência concreta `arquivo:linha`.
+- Não criar finding por preferência genérica sem evidência local.
+- Regras locais reais prevalecem sobre boas práticas genéricas.
+- Não migrar lógica especialista de Flutter/Dart para o core universal.
+- Adapters por stack/backend são opcionais; fallback universal deve funcionar.
+- Não inventar comandos de validação: usar apenas manifests/configs/scripts reais.
+- `--handoff` gera artefato de plano em `.atlas/plans/`, mas não chama executor.
+
+## Fluxo obrigatório
+
+1. **Resolver boundary**
+   - Identificar `project_root`, `target`, paths reais e exclusões óbvias (`node_modules`, `build`, `dist`, `.git`, caches).
+   - Se `--scope` existir, tratar como recorte adicional, não expansão automática para repo inteiro.
+   - Registrar limitações se parte do target estiver ausente, gerada ou ilegível.
+
+2. **Ler regras locais reais**
+   - Procurar e consultar, quando existirem e forem relevantes ao boundary: `AGENTS.md`, `CLAUDE.md`, `README.md`, docs de rules, `project-rules/`, configs de lint/format/typecheck/test, manifests e arquivos de workspace.
+   - Não copiar regras integralmente no relatório; listar só fontes consultadas e regras aplicáveis.
+
+3. **Detectar stack/perfis**
+   - Usar `../_shared/references/stack-profiles.md` como baseline.
+   - Detectar por manifests/configs/comandos reais, não só por extensão.
+   - Perfis esperados quando houver sinal: Dart/Flutter, TypeScript/Node, Python, Go, Rust, Java/Kotlin, Firebase, Supabase, REST/OpenAPI.
+   - Se múltiplos perfis coexistirem, aplicar cada regra só ao boundary onde o sinal foi ativado.
+
+4. **Entender arquitetura antes de julgar**
+   - Mapear camadas reais, fluxo de dados, contratos, entrypoints, DI, estado, side effects, testes e consumidores afetados.
+   - Comparar com padrões existentes do repo antes de classificar algo como violação.
+
+5. **Auditar por lentes**
+   - Arquitetura e ownership.
+   - Contrato/dados/schemas/mappers/DTOs.
+   - Erros, falhas parciais, retries, cleanup.
+   - Segurança, authz/authn, segredos, trust boundaries.
+   - Estado, concorrência, lifecycle, idempotência.
+   - Fluxos previstos e imprevistos.
+   - Testes e validação declarada.
+   - Observabilidade, logs e diagnóstico.
+   - Manutenção/DX.
+
+6. **Ponytail pass final**
+   - Procurar abstração inútil, wrapper sem valor, código morto, duplicação simples, dependência excessiva, branching/config acidental e complexidade que não protege segurança/contrato/dados.
+   - Só registrar se houver simplificação clara e segura, com evidência local.
+
+## Severidade
+
+- `P0`: quebra crítica, perda/corrupção de dados, bypass de segurança, execução impossível.
+- `P1`: bug provável em fluxo principal, contrato errado, regressão relevante, risco alto.
+- `P2`: gap importante, cenário não coberto, arquitetura frágil, teste/validação faltante com risco real.
+- `P3`: melhoria localizada, simplificação Ponytail, DX/manutenção, observação de baixo risco.
+
+## Formato do achado
+
+```md
+### AUDIT-001 — P1 — <categoria>
+- Arquivo: `path/to/file.ext:123`
+- Evidência: <fato observado no código>
+- Impacto: <falha/risco concreto>
+- Correção proposta: <direção, sem implementar>
+- Dependências/bloqueios: <se houver>
+- Status: `open`
+```
+
+Se não houver linha precisa, não promova a finding; registre em limitações ou perguntas.
+
+## Relatório de auditoria
+
+Responder em pt-BR com:
+
+```md
+# Auditoria Atlas — <target>
+
+## Stack detectada
+...
+
+## Regras locais consultadas
+...
+
+## Boundary auditado
+...
+
+## Achados
+### P0
+...
+### P1
+...
+### P2
+...
+### P3
+...
+
+## Gaps por área
+- Contrato/dados:
+- Segurança:
+- Testes:
+- Arquitetura:
+
+## Limitações
+...
+
+## Próximo passo seguro
+...
+```
+
+Se zero achados, diga explicitamente `Nenhum achado P0/P1/P2/P3 com evidência suficiente no boundary auditado` e liste risco residual/limitações.
+
+## `--handoff`
+
+Quando `--handoff` estiver presente, escrever em `.atlas/plans/PLAN_AUDIT_<slug>.md` um plano **conforme ao `PLAN_TEMPLATE.md` canônico** (resolver em `<raiz-do-plugin>/packages/templates/`), para que passe no gate TC (`atlas_verify_template_conformance`) e seja consumível por `/workflow execute plan <path>` ou por `atlas-plan-execute`. O plano só pode conter tasks derivadas dos achados evidenciados. Se a escrita falhar, reportar bloqueio e não fingir que há handoff executável.
+
+A auditoria **não tem PRD**: a fonte de verdade é o relatório de auditoria + achados + regras locais reais. O plano espelha o template, mas reancorado na auditoria — **sem inventar decisões `D*` nem referências PRD inexistentes**.
+
+### Cabeçalho obrigatório (gate TC)
+
+O gate TC exige literalmente a linha `| **PRD** |`, referência a `BOUNDARY_PRD_PLAN.md` e tarefas `#### T01.`. Em `execution_mode: sequencial`, a §7 Slices é dispensável.
+
+```md
+# PLAN AUDIT — <target> (correção de auditoria)
+
+| Campo | Valor |
+|-------|-------|
+| **PRD** | N/A — origem auditoria; ver **Source audit** abaixo |
+| **Package / app** | `<boundary auditado>` |
+| **Tipo** | `audit-fix` |
+| **execution_mode** | `sequencial (T01→TN)` |
+| **Data** | <YYYY-MM-DD> |
+
+**Escopo técnico:** boundary da auditoria. **Fora:** <o que ficou fora do target/scope>.
+
+Política: [BOUNDARY_PRD_PLAN.md](./BOUNDARY_PRD_PLAN.md).
+
+## Metadados de execução
+- Plan prefix: `atlas`
+- Execution mode: `sequencial (T01→TN)`
+- Executor skill: `atlas-plan-execute`
+- Internal validator: `atlas-task-validator`
+- Source audit: `<título/path/data do relatório>`
+```
+
+> `N/A — origem auditoria` satisfaz o regex do TC declarando a proveniência sem inventar PRD.
+
+### Seções obrigatórias (§1–§6, §8)
+
+Sem PRD, as âncoras "derivados do PRD" do template passam a apontar para achados/regras locais:
+
+- **§1 Tradução executiva** — 1 parágrafo do que será corrigido + resultado observável; referência ao relatório de auditoria.
+- **§2 Invariantes de execução** — invariantes derivados das regras locais reais e do boundary (não de `D*`).
+- **§3 Pitfalls** — anti-padrões evidenciados na auditoria → correção canônica.
+- **§4 Estado na abertura da sprint** — 3–6 bullets do que está quebrado hoje, ancorados nos achados.
+- **§5 Tarefas de execução** — `#### T01.`…`#### TNN.`, uma por achado evidenciado (schema abaixo).
+- **§6 Contratos técnicos** — só se a auditoria revelou contrato/dados/schema afetado; senão `Não aplicável`.
+- **§8 Validação e checklist (validator)** — comandos reais detectados (manifests/scripts) + checkboxes derivados dos achados. Nunca inventar `flutter`/`npm`/`pytest`.
+
+### Schema de cada task (§5)
+
+```md
+#### T01. <correção curta>
+- **Objetivo:** <resultado observável>
+- **Referência ao achado:** `AUDIT-NNN` — `arquivo:linha`
+- **Mudança esperada:** <o que muda concretamente>
+- **Invariantes preservados:** <§2 / regra local>
+- **Não mudar:** <…>
+- **Dependências:** <nenhuma | T0X>
+- **Riscos:** <se relevante>
+- **Critério de done:** <sinal objetivo>
+- **Validação local:**
+  ```bash
+  cd <package> && <comando real>
+  ```
+```
+
+### Regras do handoff
+
+- Incluir apenas validações derivadas de manifests/configs reais.
+- Não usar task vaga como "refatorar geral".
+- Não incluir achado sem `arquivo:linha`; toda task aponta para um `AUDIT-NNN`.
+- Não chamar executor automaticamente.
+- Reportar o path final do plano e deixar claro que ele não foi executado.

package/hosts/zcode/skills/atlas-audit/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Audit"
+  short_description: "Auditoria universal sem correção de código"
+  default_prompt: "Use $atlas-audit para auditar o target informado contra regras locais, stack detectada e Ponytail pass, sem alterar código."
+
+policy:
+  allow_implicit_invocation: true

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:"