atlas-workflow 0.8.2

package/plugins/atlas-workflow-orchestrator/skills/atlas-slice-review/SKILL.md

@@ -0,0 +1,121 @@
+---
+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:
+* diff physical boundary (`git diff --name-only main...HEAD`).
+* 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.
+
+### 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. 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]
+
+### 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/plugins/atlas-workflow-orchestrator/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/plugins/atlas-workflow-orchestrator/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/plugins/atlas-workflow-orchestrator/skills/atlas-slice-review/references/scenario-lenses.md

@@ -0,0 +1,49 @@
+# 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?
+
+## 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/plugins/atlas-workflow-orchestrator/skills/atlas-slice-review/scripts/classify_findings.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Normalize raw findings into a severity-oriented review structure."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from typing import Any
+
+SEVERITY_ORDER = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+
+
+def load_findings(path: pathlib.Path) -> list[dict[str, Any]]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, list):
+        raise ValueError("Findings input must be a JSON array")
+    return payload
+
+
+def normalize_finding(finding: dict[str, Any]) -> dict[str, Any]:
+    severity = finding.get("severity", "P2")
+    if severity not in SEVERITY_ORDER:
+        severity = "P2"
+    return {
+        "severity": severity,
+        "task_id": finding.get("task_id", ""),
+        "title": finding.get("title", ""),
+        "file": finding.get("file", ""),
+        "line": finding.get("line"),
+        "summary": finding.get("summary", ""),
+        "evidence": finding.get("evidence", ""),
+        "diff_attributed": bool(finding.get("diff_attributed", True)),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("findings_json", help="Path to a JSON array of findings")
+    args = parser.parse_args()
+
+    try:
+        normalized = [normalize_finding(item) for item in load_findings(pathlib.Path(args.findings_json))]
+    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 1
+
+    normalized.sort(key=lambda item: (SEVERITY_ORDER[item["severity"]], item["task_id"], item["file"], item["line"] or 0))
+    json.dump(normalized, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/atlas-workflow-orchestrator/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/plugins/atlas-workflow-orchestrator/skills/atlas-sprint-prd-generator/SKILL.md

@@ -0,0 +1,74 @@
+---
+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.
+
+*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 backlog/roadmap no repo ativo (`**/BACKLOG_MESTRE*.md`).
+2. **Extração da Sprint:** Leia a fonte de backlog/roadmap. Localize a sprint, extraindo fase-fonte, objetivo, dependências e filename do PRD.
+3. **Inspecionar Código:** Busque no codebase por classes, tabelas, RPCs, mappers e rotas existentes que influenciam a feature.
+4. **Redação do PRD:** Siga estritamente o layout enxuto e focado do `PRD_TEMPLATE.md` (teto orientativo de ~180-220 linhas), separando dores e regras de negócio de implementações de código.
+
+### 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).
+* **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/plugins/atlas-workflow-orchestrator/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