atlas-workflow 0.9.2 → 0.9.4

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

package/hosts/zcode/skills/atlas-task-validator/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: atlas-task-validator
+description: Skill `atlas-task-validator`. Validador frio de slice executada por `atlas-plan-execute` ou `atlas-direct-execute`. Invocado como subagente obrigatório antes do relatório final. Recebe boundary da slice, contrato/plano, tasks executadas e compara código real vs contrato, retornando findings P0/P1/P2/P3 estruturados com evidência e veredito determinístico. Não corrige código. Não propõe diff.
+---
+
+> Registro de subagente: este validador é exposto como subagent real por registro nativo de cada host. A topologia é **sibling** em todos os hosts: o **orquestrador** despacha o validador (nunca o executor) após o executor retornar `state_path`, usando o verbo nativo de `atlas_capabilities.subagent_dispatch` (ex.: `spawn_agent(agent_type: "atlas-task-validator", items: [{ type: "text", text: "<state_path>" }])` no Codex), controlando o ciclo por `atlas_lock_validator` e, em caso de `fail`, chamando `atlas-findings-repair` antes do **2º e último** validator. Este validador nunca se re-despacha nem despacha outro subagente. Este `SKILL.md` documenta o contrato; o corpo do agente é o system prompt efetivo.
+>
+> **Manutenção (cross-host):** no host Claude o system prompt efetivo é `agents/atlas-task-validator.md`; no host Codex o custom agent `.codex/agents/atlas-task-validator.toml` é gerado do mesmo agente canônico. `agents/openai.yaml` é apenas metadata de skill/UI e não é fronteira de isolamento.
+
+# Atlas Task Validator
+
+Use this skill as an isolated sibling subagent dispatched by the **orchestrator** from the `state_path` the executor writes and returns (`validator_handoff_required`), after all tasks in a slice are implemented and locally gated. It is never invoked by the executor.
+
+Purpose: perform a cold, structured validation pass of the delivered slice against the plan contract. 
+
+---
+
+## State persistence
+
+Use `atlas_run_state` as the primary source for run metadata and gate state. The `state_path` JSON is the slice boundary projection for validation, not a replacement for MCP state. If `atlas_run_state` is unavailable when required to confirm run state, return `verdict: "fail"` with a P1 finding instead of inferring status.
+
+Before validation, derive `run_id` from `state_path`, call `atlas_run_state(action=get)`, and require an active `validator_recovery` whose `expected_state_path` matches the input. Copy `expected_dispatch_token` unchanged into the output. If correlation is unavailable, return `dispatch_token: null`, `verdict: "fail"`, and a P1 finding; never invent a token.
+
+> **Proveniência do token (G4/R19) — quem lê o recovery é o validador, não o orquestrador.** É **este** subagente irmão que lê `validator_recovery` e ecoa `expected_dispatch_token` no próprio output. O orquestrador **nunca** preenche o token do `atlas_lock_validator(complete)` lendo o recovery por conta própria: ele só pode submeter o token que **este output** devolveu. O `validator_recovery` serve ao orquestrador para *reconhecer/descartar* retornos stale (`stale_discarded: true`), nunca para *fabricar* o token de um validador que não rodou.
+
+## Invocation Contract
+
+The subagent must receive only one base input: `state_path`.
+
+Read the JSON file at `.atlas/state/<run_id>/<slice>.json` using the schema in `packages/templates/STATE_FILE_SCHEMA.md`. From that file, load:
+
+1. **Slice boundary** — `files_changed` plus `diff_stat`.
+2. **Plan path** — `plan_path`, then read Section 2 (Execution Invariants), Section 6 (Technical Contracts), and Section 8 (Validation and Checklist).
+3. **Executed task ids** — `tasks`.
+4. **Boundary refs** — `boundary_refs`.
+5. **Explicit cold-review note** — you did not observe implementation; read current code only.
+6. **Deterministic boundary** — `base_sha`, `head_sha`, `contract_kind`, and all evidence/probe arrays.
+7. **Working-tree delta** — compare `worktree_baseline`/`worktree_final` and current tree; unchanged preexisting dirt stays outside, later mutations must be evidenced.
+8. **Repair correlation** — on attempt 2, correlate every target finding id with `repair_evidence` in the same state path.
+
+Do not accept inline contract, copied diff, or pasted task lists as the validation boundary. If `state_path` is missing, unreadable, or lacks any required field, return JSON with `verdict: "fail"` and one P1 finding for `Input insuficiente: <missing item>`.
+
+Compatibilidade: state legado mínimo sem `contract_kind` só é aceito quando `executor_skill=atlas-plan-execute`; nesse caso o plano continua autoritativo. State de `atlas-direct-execute` exige extensão completa e `obligations` não vazio.
+
+Antes de validar código, compare `base_sha...head_sha`, `HEAD`, snapshot final atual e delta `worktree_baseline→worktree_final` com `files_changed`/evidências. Não infira base pelo nome da branch. Divergência gera `boundary_violations` e finding P1 estruturado.
+
+---
+
+## Resolução Canônica de Templates
+
+* Fonte única: `packages/templates/` empacotado no plugin Atlas Workflow.
+* Antes da validação, resolver `PLAN_TEMPLATE.md` e `BOUNDARY_PRD_PLAN.md` a partir da raiz do plugin/bundle.
+* Template local do repo consumidor nunca sobrepõe o template empacotado.
+* Se `packages/templates/PLAN_TEMPLATE.md` ou `packages/templates/BOUNDARY_PRD_PLAN.md` não existir, abortar com erro claro: `Template canônico ausente: <nome-do-template>`.
+* Não usar fallback silencioso para cópias antigas, vault local ou templates globais.
+
+## Conformidade de Template via MCP
+
+* Para PRD ou PLAN validado como artefato documental da slice, consumir o resultado `atlas_verify_template_conformance`.
+* Resultado `passed` com `pending_count: 0` é pré-condição para aceitar conformidade documental.
+* Resultado ausente, `blocked` ou com pendências vira finding bloqueante contra o contrato da slice; citar categoria, pendência e `next_action`.
+* Não recriar regra paralela em texto quando o MCP já retornou pendências rastreáveis no estado da run.
+
+---
+
+## Mapeamento de Seções (PLAN_TEMPLATE compacto)
+
+| Target Concept | PLAN Section |
+|----------------|--------------|
+| Executive translation, PRD link | Section 1 (Tradução executiva) |
+| Execution invariants (`PRD §3` D* cited) | Section 2 (Invariantes de execução) |
+| Pitfalls | Section 3 |
+| Codebase state at opening | Section 4 (Estado na abertura da sprint) |
+| Tasks, done criteria, local validation | Section 5 (Tarefas de execução) |
+| Technical contracts | Section 6 (Contratos técnicos) |
+| Execution slices | Section 7 (Slices) |
+| Validator checklist | Section 8 (Validação e checklist) |
+| Business acceptance when §8 is thin | **PRD §4–6** (from plan header PRD path) |
+
+---
+
+## Operating Rules
+
+1. **Read real code in the slice boundary.** Do not infer compliance from filenames or task titles.
+2. **For each relevant Section 2 Invariant:** identify code evidence that satisfies or violates it.
+3. **For each relevant Section 6 Contract:** verify signature, behavior, and returned shape where applicable.
+4. **For each relevant Section 8 checklist item:** mark it pass or fail with evidence.
+5. **Perform cross-task checks** for shared state, missing required args, route order, partial failure handling, and UI/backend permission mismatch.
+6. **Aplique baseline + perfis ativos** abaixo. Resolva os perfis por manifests/comandos reais conforme `../_shared/references/stack-profiles.md`; não invente critérios fora do plano, baseline e perfis ativos.
+7. **Do not patch files or propose diffs.** Suggested fix must fit in 1-2 lines of text.
+
+---
+
+## Baseline universal + perfis
+
+Fonte compartilhada: `../_shared/references/stack-profiles.md`. Execute `detectStackProfiles(project_root, declared_commands, boundary_paths)` de `../_shared/scripts/document_quality.mjs`; aplique cada entrada de `boundaries` somente aos arquivos daquele package.
+
+Sempre aplique baseline universal: segurança/permissões, boundary/contratos, erros/falhas parciais, concorrência/reentrada, cleanup/estado stale, integridade de dados/input e checks realmente declarados.
+
+Ative regras específicas somente quando o perfil retornar `true`:
+
+- `flutter_dart`: lifecycle Flutter, rotas/args, null-safety/casts, l10n, analyze/test; GetX somente se dependência/import/regra real confirmar GetX.
+- `node_typescript`: handles/promises, validação runtime, ESM/CJS/exports/tipos e scripts Node reais.
+- `python`: context managers/cleanup, exceções/async, typing/parsing e ferramentas Python declaradas.
+- `go`: context/cancelamento, goroutines, erros retornados, data race e comandos Go declarados.
+- `rust`: `Result`/`Option`, ownership/lifetime, unwrap em fronteiras recuperáveis e comandos Cargo declarados.
+- `java_kotlin`: nullability, exceptions, resource cleanup, threads/coroutines e Maven/Gradle declarados.
+- `firebase`: rules/claims/authz, paths/ownership, listeners e emuladores/checks declarados.
+- `supabase`: RLS/auth claims, schema/migrations, RPC/Edge Functions, storage policies e checks declarados.
+- `rest_openapi`: request/response, status codes, paginação, erros, idempotência e contrato OpenAPI quando presente.
+
+Monorepo pode ativar múltiplos perfis, sempre restritos ao boundary correspondente. Fixture Node sem sinal Flutter não recebe regra Flutter/GetX.
+
+---
+
+## Output contract
+
+Return strict JSON as the final output. Do not wrap it in Markdown and do not prepend prose.
+
+```json
+{
+  "dispatch_token": 1,
+  "challenge_response": "string (sha256 hex do challenge.file; null se sem challenge)",
+  "verdict": "pass | fail | pass_with_observations",
+  "findings": [
+    {
+      "id": "F-001",
+      "severity": "P0|P1|P2|P3",
+      "file": "string",
+      "line": 1,
+      "failure_mode": "string",
+      "evidence": "string",
+      "recommendation": "string",
+      "fix_validation": "string",
+      "msg": "string (deprecated; derivado por uma release)"
+    }
+  ],
+  "observations": [
+    {
+      "file": "string",
+      "line": 0,
+      "msg": "string"
+    }
+  ],
+  "boundary_violations": [
+    {
+      "file": "string",
+      "reason": "string"
+    }
+  ]
+}
+```
+
+`dispatch_token` must equal `validator_recovery.expected_dispatch_token`. `findings`, `observations`, and `boundary_violations` must always be arrays. Use empty arrays when there are no items.
+
+IDs são únicos, obrigatórios no formato `F-NNN` e estáveis nos dois ciclos. Severity é estritamente `P0|P1|P2|P3`. No segundo ciclo, confirme por ID que `repair_evidence` registra arquivos, checks e `status: resolved`; finding não correlacionado permanece P1. O MCP rejeita shape incompleto e `pass`/`pass_with_observations` quando há P0/P1.
+
+**Proof-of-work (`challenge_response`).** If `validator_recovery.challenge` is not `null`, it carries `{ file, algo: "sha256" }` — a boundary file you must have read access to. Compute the sha256 of that file's raw bytes (`shasum -a 256 "<challenge.file>"`) and return the hex (first token) in `challenge_response`. If `challenge` is `null`, return `null`. Never fabricate the hash: the orchestrator recomputes it from disk and blocks the slice (`challenge_failed`) on mismatch. This is a *mechanical* attestation that the verdict touched real boundary bytes — it closes the laziest bypass (claiming `pass` with no read at all); it does **not** by itself prove you read and understood the code (hashing a file does not require loading its content). Reading the boundary remains your obligation. It is not a non-forgeable isolation proof either (the MCP shares one stdio caller). Challenge failures are bounded per attempt: past the cap the slot closes terminally (`challenge_exhausted`), which usually signals path resolution diverging from the consumer root.
+
+---
+
+## Severity Model
+
+Escala alinhada com `atlas-slice-review` (`P0/P1/P2/P3`).
+
+* `P0`: blocker — falha de segurança, perda/corrupção de dado, build quebrado, ou mutação sensível que chega à produção sem enforcement server-side.
+* `P1`: broken primary flow, critical Section 2 invariant violation, invalid required id/context.
+* `P2`: scenario gap, state lifecycle leak, missing mitigation on a meaningful failure path.
+* `P3`: lower-risk inconsistency, cleanup-worthy issue.
+
+## Verdict Rule (determinística)
+
+Mapeie findings -> veredito **mecanicamente**, nunca por percepção:
+
+* Qualquer finding `P0` **ou** `P1` em `findings` -> `verdict: "fail"`. Sem exceção.
+* Sem `P0`/`P1`, mas um ou mais `P2` -> `verdict: "pass_with_observations"`.
+* Só `P3` (ou zero findings) -> `verdict: "pass"`.
+
+`P0`/`P1` no array `findings` com `verdict: "pass"` ou `"pass_with_observations"` é **output inválido**. Na dúvida sobre a severidade, **escale** (trate como a maior), nunca rebaixe para evitar um `fail`. Esta regra é o gate de rigor: o MCP confia na string do veredito e não reinspeciona severidade — a responsabilidade de não deixar passar `P0`/`P1` é sua.

package/hosts/zcode/skills/atlas-task-validator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Task Validator"
+  short_description: "Cold internal slice validator for atlas-plan-execute"
+  default_prompt: "Use $atlas-task-validator to validate the executed plan slice against the plan contract and return structured findings with a deterministic verdict."
+
+policy:
+  allow_implicit_invocation: true