atlas-workflow 0.9.2 → 0.9.3

package/hosts/zcode/skills/atlas-slice-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: atlas-slice-review
+description: Skill `atlas-slice-review`. Revisa uma slice implementada após `atlas-plan-execute`, usando o plano (`atlas-plan-handoff`), invariantes e código tocado como contrato. Revisão fria focada na slice — regressões ocultas, gaps de lógica, cenários em falta, riscos de segurança, violações arquiteturais e testes em falta.
+---
+
+# Atlas Slice Review
+
+Use this skill only when `--review` is present after `atlas-plan-execute` or any equivalent implementation pass has finished a specific plan slice.
+
+Review only the slice that was executed. Do not widen into a generic repo audit unless the user explicitly asks for that.
+
+## Invocation gate
+
+`--review` is the only automatic dispatch condition. Do not auto-trigger from heuristics, diff size, risk level, or validator observations. If `--review` is absent, report that external review was skipped by contract.
+
+## Uso standalone — rótulo de garantia reduzida obrigatório (PRD D10/D11)
+
+Esta skill é **análise de leitura**: revisa código, **não muta código**. Pela fronteira de determinismo do Atlas (mutação de código, PRD D10), leitura standalone é **permitida**, mas carrega **risco epistêmico** — a análise não passou pela defesa fria do pipeline (`atlas-task-validator`, que é pipeline-only, só `state_path`). Esse risco é mitigado por **rótulo**, não por gate.
+
+**Regra dura:** quando `atlas-slice-review` roda **fora do pipeline** (sem o `atlas-task-validator` ter fechado a slice via state file), a saída **SEMPRE** sai rotulada como garantia reduzida. É **proibido** simular `validator_status: passed` ou qualquer veredito de validação aprovado — a review é leitura, não validação fria.
+
+### Formato exato do rótulo (obrigatório no topo da saída standalone)
+
+```text
+guarantee_level: reduced_standalone
+validator_status: not_run (sem validator-closed)
+scope: standalone
+```
+
+- `guarantee_level: reduced_standalone` — enum fixo (PRD D12); nunca `full_pipeline` em uso standalone.
+- `validator_status: not_run (sem validator-closed)` — declara explicitamente que a defesa fria não rodou. **Proibido** escrever `passed`/`pass`.
+- `scope: standalone` — marca que a review não está ancorada num state file de pipeline.
+
+Quando a review roda **dentro do pipeline** (despachada pelo orquestrador após o validator frio fechar a slice), o nível de garantia da slice vem do pipeline (`full_pipeline`) e este rótulo de redução **não** se aplica — mas a própria review continua sendo leitura e nunca emite veredito de validador.
+
+> **Invariante:** uma análise de leitura standalone nunca se declara fechada por validação; sai rotulada `reduced_standalone` e jamais simula `validator_status: passed` (PRD D10/D11, fecha Q-08).
+
+## State persistence
+
+Use `atlas_run_state` as the primary source for run state, dispatch status, and validator status. Do not read or write run ledger files directly. If MCP state is unavailable, block the review rather than accepting a local file fallback.
+
+---
+
+## Review Contract
+
+Base the review on three inputs:
+1. **The plan artifact** produced by `atlas-plan-handoff` (Section 2 - Invariantes, Section 6 - Contratos, Section 8 - Validação).
+2. **The executed task ids** or slice boundaries.
+3. **The real code** touched by the implementation.
+
+---
+
+## Required Workflow
+
+### 1. Build the slice boundary first
+Before reviewing code, identify:
+* boundary físico do diff a partir do state/task ids; use a base configurada ou upstream e inclua mudanças não commitadas pertencentes à slice.
+* Section 2 - Invariants of Execution (contract).
+* Section 6 - Technical Contracts (signatures and shapes).
+* Section 8 - Validation and Checklist (QA criteria).
+* touch files expected vs actual.
+* resolved conflicts and permission matrices that apply.
+
+If the diff and the plan disagree materially, call that out as a structural finding or blocker. Do not silently review an invented scope.
+
+### 2. Review in code-review mode, not implementation mode
+This skill is not for fixing code first. It is for finding problems first.
+Look for:
+* behavioral regressions introduced by the slice.
+* hidden logic gaps or missing business scenarios.
+* state-transition bugs and view/store mismatches.
+* security or privacy issues.
+* contract drift from the plan.
+* validation and tests gaps.
+
+### 3. Use the plan to hunt missing scenarios
+For each executed task, compare: stated objective, expected change, invariants preserved, and done criteria with real code.
+Ask what the implementation forgot:
+* **State & orquestration:** transition states reativity (loading, success, empty, error), rapid triggers concurency, setup/cleanup symmetry, async stale.
+* **Business rules:** negative paths, closed decisions, fallsback that weaken invariants.
+* **View & rendering:** inputs empty, null, partial, out of order, UI permission conditional.
+* **Contracts:** shape drift, enums, mappers, RLS server-side, i18n parity.
+
+Aplique estes probes determinísticos a cada símbolo ou hunk alterado relevante:
+* **Linha a linha:** leia cada hunk alterado e a função completa que o contém; construa entradas, estados, timings ou plataformas concretas capazes de provocar falha.
+* **Comportamento removido:** para cada guard, validação, cleanup, error path ou teste removido/substituído, identifique o invariante protegido e prove onde o novo código o restabelece.
+* **Rastreamento cross-file:** inspecione callers e callees quando assinaturas, shapes de retorno, erros, timing, ordem ou pré-condições mudarem.
+* **Altitude:** confirme que a mudança corrige o componente proprietário do invariante, sem empilhar um caso especial local sobre um defeito compartilhado.
+* **Regras aplicáveis:** inspecione arquivos de instruções do repo que governam os arquivos alterados. Reporte apenas violações exatas, com path da regra, texto da regra, linha violadora e impacto concreto.
+
+Reuse, simplificação e eficiência só viram findings quando o diff atual cria custo comportamental, operacional ou de manutenção concreto. Não reporte preferências de estilo.
+
+### 4. Distinguish current-diff findings from pre-existing issues
+Prefer findings attributable to the executed slice. Mark pre-existing issues as observations or separate notes to keep signals clean and actionable.
+
+### 5. Verifique candidatos antes de reportar
+
+Elimine duplicatas que descrevam o mesmo defeito no mesmo local. Classifique cada candidato restante como:
+* `CONFIRMED` — evidência e cenário de falha alcançável sustentam o defeito.
+* `REFUTED` — código, tipo, invariante ou guard prova que o candidato é falso ou já está tratado.
+* `NEEDS_EVIDENCE` — o cenário é relevante, mas a evidência disponível não estabelece o defeito.
+
+Apenas `CONFIRMED` vira finding. Descarte `REFUTED`. Mova `NEEDS_EVIDENCE` para `Perguntas Abertas ou Suposições`, sem apresentá-lo como defeito. Nunca mantenha um candidato apenas por ser plausível.
+
+Antes de renderizar a saída, materialize os findings confirmados como JSON e execute o gate canônico Node `node scripts/classify_findings.mjs <findings.json>`. Cada item deve conter `severity`, `task_id`, `title`, `file`, `line`, `failure_mode`, `evidence`, `recommendation` e `fix_validation`. Saída não-zero bloqueia o relatório até o payload ser corrigido; é proibido ignorar o gate ou substituir campos ausentes por texto vazio. Array vazio é válido quando não há findings confirmados.
+
+Node é o único requisito runtime deste gate e funciona em Linux/macOS/Windows. `scripts/classify_findings.py` permanece por uma release somente como wrapper compatível que delega ao Node; não é fonte canônica nem torna Python obrigatório.
+
+### 6. Recomende uma correção de causa raiz
+
+Todo finding deve incluir exatamente uma recomendação principal de correção e uma validação que comprove a correção. A recomendação deve:
+* atacar a causa raiz no componente proprietário do invariante violado;
+* ser cirúrgica e permanecer no boundary revisado, salvo quando a evidência provar que o proprietário está fora dele;
+* preservar contratos do plano, arquitetura e comportamento existente não implicado pelo finding;
+* nomear concretamente componente, condição e comportamento esperado;
+* ser a melhor correção sustentada pela evidência disponível, nunca uma alegação sem suporte de superioridade absoluta.
+
+Não ofereça alternativas A/B. Não forneça patch completo nem altere código. Se a evidência for insuficiente para recomendar uma correção com segurança, classifique o candidato como `NEEDS_EVIDENCE` em vez de emitir finding.
+
+### 7. Output Expectations
+
+Return exactly this structure:
+
+```markdown
+## Findings
+
+### P0 - <short title>
+- **Slice/Task:** T0N
+- **Por que importa:** [impacto real]
+- **Arquivo:** `relative/path.ext:line`
+- **Modo de falha:** [o que quebra e como]
+- **Evidência:** [o que suporta o finding]
+- **Correção recomendada:** [uma correção cirúrgica na causa raiz]
+- **Validação da correção:** [teste/check específico que comprova a resolução]
+
+### P1 - <short title>
+[same shape]
+
+### P2 - <short title>
+[same shape]
+
+### P3 - <short title>
+[same shape]
+
+---
+
+## Perguntas Abertas ou Suposições
+[questões que precisam de confirmação antes de agir nos findings]
+
+---
+
+## Resumo da Slice
+[breve — o que foi bem implementado, o que precisa atenção, se a slice pode ser considerada fechada]
+```
+
+Do not add extra sections or narrative conclusions.

package/hosts/zcode/skills/atlas-slice-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Atlas Slice Review"
+  short_description: "Slice-focused post-plan review gate (atlas-slice-review)"
+  default_prompt: "Use $atlas-slice-review to review the executed plan slice for hidden regressions, logic gaps, missing scenarios, security risks, and test omissions."

package/hosts/zcode/skills/atlas-slice-review/references/review-contract.md

@@ -0,0 +1,58 @@
+# Review Contract
+
+This skill assumes the implementation was guided by a plan with task-level structure close to `atlas-plan-handoff`.
+
+## Minimum expected inputs
+
+- the plan artifact
+- the executed task ids or a clearly described slice
+- the real changed files or diff
+
+The plan should also expose execution metadata:
+
+- `Plan prefix: atlas`
+- `Execution mode: sequencial (T01→TN)` or `orchestrated-per-slice`
+
+## Minimum expected task fields
+
+For each reviewed task, try to recover:
+
+- `Objective`
+- `Likely files/modules`
+- `Expected change`
+- `Invariants preserved`
+- `Do not change`
+- `Do not do`
+- `Risks / pitfalls`
+- `Done criteria`
+- `Task-local validation`
+- `Quality gates (recommended)`
+- `Stop and ask if`
+
+Recover these plan-level constraints when present:
+
+- resolved source conflicts and chosen authority
+- permission or responsibility matrices
+- generated-file, localization, import, route, RPC, or schema constraints
+- explicit final validation gates
+
+## Review scope discipline
+
+The review scope is the intersection of:
+
+- what the plan asked for
+- what the executor claims to have completed
+- what the diff actually changed
+
+If these three disagree, that disagreement is part of the review result.
+
+If the implementation chose a path that the plan explicitly rejected, treat it as a contract violation even if the UI appears to work.
+
+## Typical review outcomes
+
+- the slice matches the plan and no material findings are present
+- the slice works but missed scenarios, validations, or tests
+- the slice violates a plan invariant or broadens scope incorrectly
+- the slice ignores a resolved source conflict or permission matrix
+- the slice introduced a regression outside the intended task boundary
+- the slice appears correct but validation evidence is too weak to trust closure

package/hosts/zcode/skills/atlas-slice-review/references/scenario-lenses.md

@@ -0,0 +1,57 @@
+# Scenario Lenses
+
+Use these lenses to find hidden bugs in the executed slice. Apply only the relevant ones.
+
+## State and orchestration
+
+- Can the state machine enter a half-updated state?
+- Are loading, success, empty, and error states all representable?
+- What happens on repeated triggers or rapid taps?
+- Is cleanup symmetrical with setup?
+- Can stale async results overwrite newer state?
+
+## Business rules
+
+- Which negative path did the plan imply but the code does not implement?
+- Are closed decisions from the plan really enforced?
+- Did the implementation honor the plan's resolved source-of-truth decisions?
+- If roles differ by resource, can any actor mutate a resource the matrix forbids?
+- Is there any fallback that weakens a business invariant?
+- Does the implementation silently infer data that the plan said must be explicit?
+
+## View and rendering
+
+- Can the UI render a shape the store never guarantees?
+- Can the store produce a shape the UI does not handle?
+- Are empty, null, partial, and reordered inputs rendered safely?
+- Is user feedback tied to the real pipeline or only to a local shortcut?
+
+## Contracts and integration
+
+- Did any field, enum, or payload meaning drift from the plan?
+- Are all relevant consumers updated after a shape change?
+- Does the code assume a backend guarantee that is not actually enforced?
+- Is retry or re-entry behavior still coherent after this slice?
+- Did generated files, localization keys, imports, routes, RPC signatures, or schemas match the verified repo convention?
+
+## Mecânica da mudança
+
+- Qual invariante cada guard, validação, cleanup, error path ou teste removido/substituído protegia, e onde ele foi restabelecido?
+- Callers e callees alterados ainda concordam sobre pré-condições, shapes de retorno, erros, timing e ordem?
+- A mudança corrige o componente proprietário do invariante ou adiciona um caso especial local frágil?
+- Algum novo problema de reuse, simplificação ou eficiência tem custo comportamental, operacional ou de manutenção concreto?
+- As instruções aplicáveis do repo expõem uma violação exata, atribuível a uma linha e com impacto concreto?
+
+## Security and safety
+
+- Did the slice weaken permission, ownership, or visibility checks?
+- Can an untrusted input reach a sensitive path without validation?
+- Was any auth, session, or cleanup invariant softened?
+- Did logging or observability leak sensitive information?
+
+## Validation and tests
+
+- Do the tests cover only the happy path?
+- Which regression would still pass the current tests?
+- Was a required manual check skipped or replaced by weaker evidence?
+- Did the executor claim closure despite an environment-limited validation gap?

package/hosts/zcode/skills/atlas-slice-review/scripts/classify_findings.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export const SEVERITY_ORDER = Object.freeze({ P0: 0, P1: 1, P2: 2, P3: 3 });
+export const REQUIRED_TEXT_FIELDS = Object.freeze([
+  'task_id', 'title', 'file', 'failure_mode', 'evidence', 'recommendation', 'fix_validation',
+]);
+
+export function normalizeFinding(finding, index) {
+  if (!finding || typeof finding !== 'object' || Array.isArray(finding)) {
+    throw new Error(`Finding ${index} must be a JSON object`);
+  }
+  if (!(finding.severity in SEVERITY_ORDER)) {
+    throw new Error(`Finding ${index} has invalid severity: ${JSON.stringify(finding.severity)}`);
+  }
+  const missing = REQUIRED_TEXT_FIELDS.filter(
+    (field) => typeof finding[field] !== 'string' || !finding[field].trim(),
+  );
+  if (missing.length) throw new Error(`Finding ${index} missing required fields: ${missing.join(', ')}`);
+  if (!Number.isInteger(finding.line) || finding.line < 1) {
+    throw new Error(`Finding ${index} has invalid line: ${JSON.stringify(finding.line)}`);
+  }
+  return {
+    severity: finding.severity,
+    task_id: finding.task_id,
+    title: finding.title,
+    file: finding.file,
+    line: finding.line,
+    summary: typeof finding.summary === 'string' ? finding.summary : '',
+    failure_mode: finding.failure_mode,
+    evidence: finding.evidence,
+    recommendation: finding.recommendation,
+    fix_validation: finding.fix_validation,
+    diff_attributed: finding.diff_attributed !== false,
+  };
+}
+
+export function classifyFindings(payload) {
+  if (!Array.isArray(payload)) throw new Error('Findings input must be a JSON array');
+  return payload.map(normalizeFinding).sort((a, b) => (
+    SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]
+      || a.task_id.localeCompare(b.task_id)
+      || a.file.localeCompare(b.file)
+      || a.line - b.line
+  ));
+}
+
+export function run(argv = process.argv.slice(2)) {
+  if (argv.length !== 1) throw new Error('Usage: node classify_findings.mjs <findings.json>');
+  const payload = JSON.parse(fs.readFileSync(argv[0], 'utf8'));
+  process.stdout.write(`${JSON.stringify(classifyFindings(payload), null, 2)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  try { run(); } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/hosts/zcode/skills/atlas-slice-review/scripts/classify_findings.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Wrapper legado: delega ao gate Node canônico por uma release."""
+
+from __future__ import annotations
+
+import pathlib
+import subprocess
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        sys.stderr.write("Usage: python classify_findings.py <findings.json>\n")
+        return 1
+    script = pathlib.Path(__file__).with_name("classify_findings.mjs")
+    try:
+        return subprocess.run(["node", str(script), sys.argv[1]], check=False).returncode
+    except FileNotFoundError:
+        sys.stderr.write("Node.js ausente: requisito runtime do Atlas\n")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/zcode/skills/atlas-slice-review/scripts/extract_review_slice.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Extract the review slice from a atlas-plan-handoff-style markdown artifact."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import re
+import sys
+from typing import Any
+
+TASK_HEADING_RE = re.compile(r"^####\s+(T\d{2})\.\s+(.*)$")
+FIELD_RE = re.compile(r"^- ([^:]+):\s*(.*)$")
+HEADING_RE = re.compile(r"^(#{1,4})\s+(.*\S)\s*$")
+
+
+def normalize_heading(text: str) -> str:
+    text = re.sub(r"^\d+\.\s*", "", text.strip())
+    return re.sub(r"[^a-z0-9]+", "_", text.lower()).strip("_")
+
+
+def normalize_field(text: str) -> str:
+    text = text.strip().strip("*").strip()
+    text = re.sub(r"^\d+\.\s*", "", text)
+    return re.sub(r"[^a-z0-9]+", "_", text.lower()).strip("_")
+
+
+def parse_sections(text: str) -> dict[str, list[str]]:
+    sections: dict[str, list[str]] = {}
+    current_key: str | None = None
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        heading_match = HEADING_RE.match(line)
+        if heading_match:
+            current_key = normalize_heading(heading_match.group(2).strip())
+            sections.setdefault(current_key, [])
+            continue
+        if current_key is not None and line.strip():
+            sections[current_key].append(line)
+    return sections
+
+
+def first_section(sections: dict[str, list[str]], keys: list[str]) -> list[str]:
+    for key in keys:
+        if key in sections:
+            return sections[key]
+    return []
+
+
+def parse_tasks(text: str) -> list[dict[str, Any]]:
+    tasks: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+    current_field: str | None = None
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        task_match = TASK_HEADING_RE.match(line)
+        if task_match:
+            current = {
+                "id": task_match.group(1),
+                "title": task_match.group(2).strip(),
+                "fields": {},
+            }
+            tasks.append(current)
+            current_field = None
+            continue
+        if current is None:
+            continue
+        field_match = FIELD_RE.match(line)
+        if field_match:
+            key = normalize_field(field_match.group(1))
+            current["fields"][key] = field_match.group(2).strip().strip("*").strip()
+            current_field = key
+            continue
+        if current_field and line.strip():
+            previous = current["fields"].get(current_field, "")
+            current["fields"][current_field] = f"{previous}\n{line.strip()}".strip()
+    return tasks
+
+
+def expected_files_for(task: dict[str, Any]) -> str:
+    fields = task["fields"]
+    for key in ("likely_files/modules", "files", "arquivos_verificados", "arquivos", "m_dulos"):
+        value = fields.get(key)
+        if value:
+            return value
+    return ""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("plan", help="Path to the plan markdown file")
+    parser.add_argument("--task-id", action="append", dest="task_ids", default=[], help="Task id to extract, repeatable")
+    parser.add_argument("--changed-file", action="append", dest="changed_files", default=[], help="Changed file path, repeatable")
+    args = parser.parse_args()
+
+    text = pathlib.Path(args.plan).read_text(encoding="utf-8")
+    sections = parse_sections(text)
+    tasks = parse_tasks(text)
+    selected = [task for task in tasks if not args.task_ids or task["id"] in args.task_ids]
+
+    payload = {
+        "task_ids": args.task_ids,
+        "selected_tasks": selected,
+        "changed_files": args.changed_files,
+        "expected_files": [expected_files_for(task) for task in selected],
+        "execution_metadata": {
+            "plan_prefix": "",
+            "execution_mode": "",
+        },
+        "plan_constraints": {
+            "rules_and_decisions": first_section(
+                sections,
+                [
+                    "project_rules_constraints_and_decisions_already_made",
+                    "regras_e_restri_es_do_projeto",
+                    "regras_decis_es",
+                    "decis_es_fechadas",
+                ],
+            ),
+            "contracts_invariants_quality": first_section(
+                sections,
+                ["contracts_invariants_and_quality_guarantees", "contratos_e_invariantes"],
+            ),
+            "risk_and_regression": first_section(
+                sections,
+                ["risk_and_regression_matrix", "regression_risks", "matriz_de_risco_e_regress_o", "riscos"],
+            ),
+            "validation": first_section(sections, ["validation", "valida_o", "valida_o_final"]),
+        },
+        "review_focus": [
+            "logic gaps",
+            "hidden scenarios",
+            "regressions",
+            "security risks",
+            "missing tests",
+            "plan contract drift",
+            "source conflict drift",
+            "permission matrix drift",
+        ],
+    }
+    metadata_section = first_section(
+        sections,
+        ["execution_metadata", "metadados_de_execu_o", "metadados_execu_o"],
+    )
+    for line in metadata_section:
+        lowered = line.lower()
+        if "plan prefix" in lowered:
+            payload["execution_metadata"]["plan_prefix"] = line.split(":", 1)[-1].strip().strip("`")
+        elif "execution mode" in lowered:
+            payload["execution_metadata"]["execution_mode"] = line.split(":", 1)[-1].strip().strip("`")
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/zcode/skills/atlas-sprint-prd-generator/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: atlas-sprint-prd-generator
+description: Skill `atlas-sprint-prd-generator`. Use quando o usuário pedir para criar, gerar, montar ou atualizar um PRD de Sprint a partir de um sprint ID como S01/S02, usando o template de PRD e o backlog/roadmap real do repositório como fonte de escopo, dependências e fase-fonte.
+---
+
+# Atlas Sprint PRD Generator
+
+Gere PRDs de Sprint em PT-BR ancorados no backlog/roadmap real, no template canônico empacotado e no código real do repositório atual. Não invente contrato.
+
+Todo PRD gerado por esta skill deve declarar explicitamente a cadeia de execução Atlas (`atlas-*`) para consumo posterior por `atlas-plan-handoff` e `atlas-plan-execute`.
+
+---
+
+## Entrada Esperada
+
+* Sprint ID: `S<NN>` (`S01`, `S02`, etc.).
+* Opcional: app/projeto alvo quando houver mais de uma fonte de backlog/roadmap.
+* Opcional: path de saída.
+* Opcional: path explícito do backlog autoritativo. Quando fornecido, vence qualquer descoberta.
+
+*Se faltar o Sprint ID, peça antes de gerar.*
+
+---
+
+## Workflow Obrigatório
+
+1. **Localizar Insumos:** Descubra a raiz do repo com `git rev-parse --show-toplevel`. Localize o template canônico em `<raiz-do-plugin>/packages/templates/PRD_TEMPLATE.md`. Localize backlogs candidatos (`**/BACKLOG_MESTRE*.md`) sem escolher por heurística silenciosa.
+2. **Fechar autoridade:** use `../_shared/scripts/document_quality.mjs#resolveSprintAuthority` com precedência fixa: path explícito → backlog canônico referenciado pelo artefato/input → único candidato contendo o Sprint ID. Zero match bloqueia. Múltiplos matches sem autoridade, mesmo com conteúdo parecido, bloqueiam com paths conflitantes e `next_action` para informar o path.
+3. **Extração da Sprint:** leia somente a fonte autoritativa. Extraia fase-fonte, objetivo, dependências e filename do PRD; registre no PRD o path + anchor exato da linha/seção do backlog.
+4. **Inspecionar Código:** Busque no codebase por contratos reais que influenciam a feature e registre anchors estáveis (`path:símbolo` ou `path:linha`) nas referências; não copie implementação para o PRD.
+5. **Redação/atualização:** siga `PRD_TEMPLATE.md`. Ao atualizar, preserve IDs `D*`, decisões fechadas, anchors e histórico; novos IDs são append-only. Mudança deliberada em D* exige decisão explícita e registro histórico.
+
+### Resolução Canônica de Templates
+
+* Fonte única: `packages/templates/` empacotado no plugin Atlas Workflow.
+* Resolver `PRD_TEMPLATE.md` a partir da raiz do plugin/bundle, antes de olhar qualquer arquivo do repo consumidor.
+* Template local do repo consumidor nunca sobrepõe o template empacotado.
+* Se `packages/templates/PRD_TEMPLATE.md` não existir, abortar com erro claro: `Template canônico ausente: PRD_TEMPLATE.md`.
+* Não usar fallback silencioso para cópias antigas, vault local ou templates globais.
+
+---
+
+## Metadados Atlas Obrigatórios
+
+Todo PRD criado ou atualizado por esta skill deve incluir, perto do topo e sem substituir o template, o seguinte bloco de metadados:
+
+```md
+## Metadados de execução
+- Plan prefix: `atlas`
+- Target planner: `atlas-plan-handoff`
+- Target executor: `atlas-plan-execute`
+- Internal validator: `atlas-task-validator`
+- External review: `atlas-slice-review` (optional)
+```
+
+---
+
+## Regras de Conteúdo
+
+* **Status final:** `Aprovado para implementação`. Setar **automaticamente** ao finalizar a geração — é o status que o gate TC do orquestrador exige (`required_status=Aprovado para implementação`) para o PRD avançar no pipeline. Não deixar `Draft` (trava o gate e força correção manual). O sinal de determinismo que sustenta o avanço é o `atlas_scan_prd` (varredura de ambiguidade) + entrevista quando houver padrões bloqueantes — não o campo Status, que é marcador documental.
+* **Data:** ISO `YYYY-MM-DD` (hoje).
+* **Autoridade:** `Relacionado`/`Referências` inclui backlog autoritativo + anchor da sprint e anchors de código/contrato usados.
+* **Escopo:** Lista fechada de capacidades funcionais.
+* **UX:** Cobrir caminhos de `loading`, `empty`, `error`, `success` e `permission` sob a perspectiva do usuário.
+* **Critérios de Aceite:** Binários e observáveis, divididos conforme `PRD_TEMPLATE.md` em: **Produto**, **UX**, **Dados** e **Regressão de produto**.
+* **Proibições Estritas:** 
+  * Não inventar schemas, RPCs, endpoints ou tabelas.
+  * Não misturar plano de implementação, classes Dart, imports, clean architecture ou comandos de terminal com o PRD. Seguir estritamente o `BOUNDARY_PRD_PLAN.md`.
+
+---
+
+## Validação Mínima
+
+Antes de salvar:
+* Confirme que todas as seções do template estão presentes.
+* Garanta que o bloco de `Metadados de execução` existe e está preenchido com `atlas`.
+* Certifique-se de que não há nomes de classes de código ou arquivos Dart dentro do PRD.

package/hosts/zcode/skills/atlas-sprint-prd-generator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Sprint PRD Generator"
+  short_description: "Gera PRDs de Sprint com prefixo atlas-*"
+  default_prompt: "Use $atlas-sprint-prd-generator para criar o PRD da sprint S01 com metadados de execução atlas-* a partir do backlog mestre e do PRD template reais."
+
+policy:
+  allow_implicit_invocation: true