atlas-workflow 0.9.2 → 0.9.4

package/hosts/zcode/skills/atlas-prd-interview/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: atlas-prd-interview
+description: Skill `atlas-prd-interview`. Use quando o usuário quer validar, interrogar ou amadurecer um PRD antes do planejamento ou implementação. Esta skill lê o PRD, cruza-o com código e contratos, detecta ambiguidades/discrepâncias, faz perguntas de múltipla escolha e para quando não restam gaps bloqueadores.
+---
+
+# PRD Interview (Atlas)
+
+Valide maturidade de PRD por entrevista guiada antes do planejamento ou implementação técnica. Não gere o PRD do zero. Não avance para o planejamento enquanto houver bloqueadores ativos (`❌`).
+
+## Resolução Canônica de Templates
+
+* Fonte única: `packages/templates/` empacotado no plugin Atlas Workflow.
+* Antes da entrevista, resolver `PRD_TEMPLATE.md` a partir da raiz do plugin/bundle.
+* 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.
+
+---
+
+## Escopo da Skill
+
+Ataque principalmente as seguintes seções do template de PRD:
+* **§3 Decisões de produto (fechadas)**
+* **§4 Fluxos e cenários UX**
+* **§5 Contrato funcional e invariantes** (regras de negócio + contrato de dados)
+* **§6 Critérios de aceite (negócio)**
+
+---
+
+## Workflow Obrigatório
+
+1. **Leitura e Inspecção:** Leia o PRD e cruze com o código do repositório para verificar discrepâncias físicas reais (se componentes, rotas e APIs descritos batem com a codebase).
+2. **Mapeamento de Gaps:** Classifique cada lacuna como:
+   * `✅` **Completo:** Decisão suficiente e verificável.
+   * `⚠️` **Pendente:** Falta detalhe de negócio que pode ser resolvido depois (não-bloqueante).
+   * `❌` **Bloqueador:** Ambiguidade, conflito com o código ou falta de fluxo de UX crítico que impede o planejamento de engenharia.
+
+**Mapeamento por Seções (Novo Template):**
+* **§3 Decisões de produto (fechadas):** `❌` se faltar decisão que altere fluxo principal, mappers, roteamento ou comportamento crítico.
+* **§4 Fluxos e cenários UX:** `❌` se impactar o fluxo principal e faltarem os caminhos de loading, erro, vazio ou permissões.
+* **§5 Contrato funcional e invariantes:** `❌` se campos críticos não possuírem regras de formato (ex: decimais) ou se a regra de negócio for ambígua/impossível de verificar na codebase.
+* **§6 Critérios de aceite (negócio):** `❌` se o critério for subjetivo, não observável ou não testável.
+
+3. **Resolver mecanismo estruturado:** chame `atlas_capabilities`, leia `question_prompt` e use seu `mechanism`/shape. Nunca hardcode nome de ferramenta de host. Se o descriptor estiver ausente ou indisponível, bloqueie a rodada; não degrade para pergunta livre sem correlação.
+4. **Perguntas por rodada:** formule no máximo 4 perguntas concisas, exatamente 3 opções, recomendada explícita e `decision_id` D* estável. Antes de perguntar, use `pendingInterviewQuestions` de `../_shared/scripts/document_quality.mjs` para excluir decisões já fechadas.
+5. **Persistência imediata:** ao receber respostas, grave-as no mesmo PRD antes de qualquer nova pergunta, preservando IDs/anchors e acrescentando histórico. Use `persistInterviewRound(prd_path, answers)`, que escreve via arquivo temporário + rename e valida readback; falha bloqueia. Nunca acumule respostas apenas no chat.
+6. **Reindexação:** releia o PRD salvo, reexecute o índice §3–§6 e recalcule perguntas pendentes. Decisão fechada não pode reaparecer em rodada posterior.
+7. **Veredito Final:** só emita `Pronto para planejamento` quando zerar todos os `❌`; no workflow, devolva controle ao orquestrador para reexecutar artifact/scan/TC.
+
+---
+
+## Índice Provisório (fim de cada rodada)
+
+```text
+§3 Decisões:      ✅/⚠️/❌
+§4 Experiência:   ✅/⚠️/❌
+§5 Contrato+inv:  ✅/⚠️/❌
+§6 Aceite:        ✅/⚠️/❌
+```
+
+O índice é materializado novamente após cada persistência; não reutilize índice anterior à resposta.
+
+---
+
+## Uso standalone vs protocolo interno no workflow (PRD D10/D11)
+
+Esta skill é de **autoria documental** (maturar um PRD). A fronteira de determinismo do Atlas é a **mutação de código** (PRD D10): como esta skill não muta código, **autoria é livre, execução é gateada**.
+
+### (a) Uso standalone permitido
+
+Você pode invocar `atlas-prd-interview` diretamente, fora do pipeline, para amadurecer um PRD. Não há restrição: autoria documental não muta o produto. O artefato resultante (`PRD_*.md`) é livre para existir e ser editado.
+
+### (b) O artefato NÃO é confiável só por existir
+
+Um PRD amadurecido standalone **não vale como gate aprovado** pelo simples fato de existir. Ao entrar em execução (modos `full`/`direct`/`execute`), ele é **re-gateado obrigatoriamente** por `atlas_verify_artifact` + `atlas_verify_template_conformance` (TC). PRD velho, manual ou inválido **trava na entrada da execução**, não na autoria. Esta skill não emite veredito de execução nem declara o PRD "pronto para implementar de forma determinística".
+
+### (c) Standalone vs protocolo interno no workflow
+
+- **Standalone:** o usuário conduz a skill diretamente; o produto é o PRD maturado, sujeito a re-validação posterior.
+- **No workflow:** quem conduz a fase de PRD é o **orquestrador principal** (agente principal), que decide quando entrevistar (scan de ambiguidade / `--interview`) e roda os gates MCP do pipeline. A skill é a mesma; o que muda é quem orquestra e os gates que cercam a fase.
+
+> **Invariante:** autoria é livre, execução é gateada. Um PRD só vira confiável para execução após `atlas_verify_artifact` + TC na entrada (PRD D11).

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas PRD Interview"
+  short_description: "Entrevista e saneia ambiguidades de PRD"
+  default_prompt: "Use $atlas-prd-interview para validar este PRD, cruzar com o código e fechar ambiguidades críticas em rodadas curtas de múltipla escolha."
+
+policy:
+  allow_implicit_invocation: true

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())