atlas-workflow 0.8.2

package/plugins/atlas-workflow-orchestrator/packages/skills/atlas-task-validator/SKILL.md

@@ -0,0 +1,158 @@
+---
+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.
+
+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>`.
+
+---
+
+## 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. **Apply universal baseline checks** below. Do not invent new mandatory criteria outside the plan and baseline.
+7. **Do not patch files or propose diffs.** Suggested fix must fit in 1-2 lines of text.
+
+---
+
+## Universal Baseline
+
+Always apply these checks:
+* **Naming cross-layer:** New read methods use `get*` prefix. Mutation uses explicit verbs (`create`, `update`, `delete`, `add`, `remove`). Concepts keep consistent root names across layers.
+* **State lifecycle:** Shared stores or controllers reused across modes or routes must reset previous mode state in `init()` or transition.
+* **Navigation args:** Argument resolvers validate required fields; navigation passes all required ids (no empty placeholder `''`).
+* **Partial failure paths:** Multi-step mutations surface partial persistence clearly if a later step fails.
+* **Backend and UI gate match:** Sensitive mutations require server-side enforcement. UI gating alone is insufficient (Page reads `canManage` from Store).
+* **Route registration:** Literal routes are registered before parameterized routes (`/:id`, `/:id/edit`) under the same prefix.
+* **Localization:** New localization keys must exist in every required locale file; generated l10n is clean.
+* **Analyzer:** `flutter analyze` (or stack equivalent) returns zero issues for touched files in boundary.
+* **Casts and nullability:** Remote payload casts use safe defensive patterns; nulos in collections treated with `?? []`.
+
+---
+
+## 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": [
+    {
+      "severity": "P0|P1|P2|P3",
+      "file": "string",
+      "line": 0,
+      "msg": "string"
+    }
+  ],
+  "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.
+
+**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/plugins/atlas-workflow-orchestrator/packages/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