oxe-cc 0.9.2 → 1.0.0

package/oxe/workflows/spec.md

@@ -13,10 +13,10 @@ Para trabalho **muito pequeno** que não justifica spec completa: redirecionar p
 Se **`.oxe/config.json`** tiver `discuss_before_plan: true`: mencionar no final da Fase 5 que o próximo passo é **`oxe:discuss`** antes do plano.
 </objective>
 
-<context>
-**Contrato de raciocínio:** aplicar `oxe/workflows/references/reasoning-discovery.md`. Antes de perguntar, explorar o que o repo e os artefatos já respondem; separar fatos, inferências e lacunas.
-
-**Pré-requisito preferível:** scan executado. Se não existir, mencionar na spec que o mapa está pendente.
+<context>
+**Contrato de raciocínio:** aplicar `oxe/workflows/references/reasoning-discovery.md`. Antes de perguntar, explorar o que o repo e os artefatos já respondem; separar fatos, inferências e lacunas.
+
+**Pré-requisito preferível:** scan executado. Se não existir, mencionar na spec que o mapa está pendente.
 
 **Contrato de robustez:** seguir `oxe/workflows/references/flow-robustness-contract.md`. Antes de escrever, resolver artefatos obrigatórios, validar pré-condições e só então produzir a spec. O output desta fase deve deixar evidência estruturada suficiente para o `plan` decidir se o plano é realmente o melhor disponível.
 
@@ -34,8 +34,8 @@ Ler no início:
 - `.oxe/codebase/OVERVIEW.md` e `STACK.md` se existirem — não contradizer o repo
 - **OBS do escopo ativo** — se houver entradas `pendente` com impacto `spec` ou `all`, incorporá-las na Fase 3 (Requisitos) e marcá-las `incorporada → spec (data)` após uso
 - **`.oxe/global/LESSONS.md`** — se existir, ler entradas com `Aplicar em: spec` e status `ativo`. **Priorizar entradas com `Frequência >= 2` ou `Impacto: alto`** — aplicar como restrições explícitas. Entradas com `Frequência: 1` e `Impacto: baixo` são contexto secundário. Usar durante a Fase 1 (perguntas) e Fase 3 (requisitos). Exemplo: se uma lição diz "perguntar explicitamente sobre integração com X", adicionar essa pergunta no Bloco B da Fase 1.
-- `.oxe/CAPABILITIES.md` e `.oxe/INVESTIGATIONS.md` — usar para sugerir capacidades e pesquisas já existentes antes de abrir novas lacunas
-- Se o problema tocar Azure, ler `.oxe/cloud/azure/profile.json`, `auth-status.json` e `INVENTORY.md` antes de fechar requisitos; se o inventário estiver ausente ou stale, exigir discovery via `oxe-cc azure sync` antes de consolidar a spec
+- `.oxe/CAPABILITIES.md` e `.oxe/INVESTIGATIONS.md` — usar para sugerir capacidades e pesquisas já existentes antes de abrir novas lacunas
+- Se o problema tocar Azure, ler `.oxe/cloud/azure/profile.json`, `auth-status.json` e `INVENTORY.md` antes de fechar requisitos; se o inventário estiver ausente ou stale, exigir discovery via `oxe-cc azure sync` antes de consolidar a spec
 
 **Brownfield (COBOL, JCL, copybooks, VB6, SP):** quando o objetivo for documentar ou planear migração, ver **`oxe/workflows/references/legacy-brownfield.md`** — épicos por trilha, critérios A* verificáveis por Grep/leitura/checklist.
 
@@ -88,9 +88,9 @@ Usar templates: **`oxe/templates/SPEC.template.md`** e **`oxe/templates/ROADMAP.
 
 **Objetivo:** investigar domínios incertos antes de escrever requisitos.
 
-**Proposta ao usuário:** com base na Fase 1, listar 2-4 áreas de investigação sugeridas e perguntar quais investigar. Exemplos:
-- "Há 3 áreas com incerteza técnica: autenticação JWT, integração com Stripe, e deploy em edge. Quer investigar alguma antes de avançar para requisitos?"
-- "A trilha depende de Azure e o inventário está incompleto. Quer sincronizar recursos reais antes de congelar os requisitos?"
+**Proposta ao usuário:** com base na Fase 1, listar 2-4 áreas de investigação sugeridas e perguntar quais investigar. Exemplos:
+- "Há 3 áreas com incerteza técnica: autenticação JWT, integração com Stripe, e deploy em edge. Quer investigar alguma antes de avançar para requisitos?"
+- "A trilha depende de Azure e o inventário está incompleto. Quer sincronizar recursos reais antes de congelar os requisitos?"
 
 **Se aprovado:**
 - Criar notas de pesquisa datadas em `research/YYYY-MM-DD-<slug>.md` no escopo ativo (usar fluxo de `research.md`)
@@ -127,6 +127,27 @@ Usar templates: **`oxe/templates/SPEC.template.md`** e **`oxe/templates/ROADMAP.
 **Apresentar ao usuário para validação** antes de avançar para Fase 4. Se ajustar: atualizar tabela e repetir até aprovação.
 </fase_3_requisitos>
 
+<fase_35_elevacao_robustez>
+## Fase 3.5 — Elevação de Robustez (automática)
+
+**Objetivo:** propor proativamente critérios de hardening baseados no stack detectado, antes de criar o roteiro. Garante que segurança e robustez entrem na spec — e portanto no plan, nos testes e no verify — em vez de ficarem como auditoria pós-hoc.
+
+**Referência:** `oxe/workflows/references/robustness-elevation.md`
+
+**Execução:**
+
+1. **Detectar domínios** presentes: AUTH, API, DB, FRONTEND, FILE — conforme tabela de detecção do arquivo de referência.
+2. **Para cada domínio detectado**, percorrer o checklist correspondente e filtrar critérios já cobertos por A* existentes.
+3. **Propor** os critérios restantes como R-RB-NN com prioridade sugerida (v1 / v2 / fora).
+4. **Apresentar ao usuário** em bloco único — domínios detectados, critérios propostos com justificativa breve para v1 críticos.
+5. **Aguardar decisão** — usuário confirma, ajusta versão ou descarta cada critério.
+6. **Incorporar aprovados** na tabela da Fase 3; registrar descartados com justificativa na seção "Suposições e riscos" da SPEC.
+
+**Regra:** nunca forçar inclusão. Se o usuário descartar um v1, registrar o motivo explicitamente.
+
+**Pulável apenas se:** stack não se encaixa em nenhum domínio detectável (ex.: script CLI puro sem auth, sem HTTP, sem DB).
+</fase_35_elevacao_robustez>
+
 <fase_4_roteiro>
 ## Fase 4 — Roteiro
 
@@ -178,6 +199,7 @@ Percorrer esta lista de verificação:
 | 4 | **Conflito com stack:** algum requisito v1 pressupõe tecnologia ou capacidade que `STACK.md` indica ausente? (ex.: requer WebSocket mas stack usa REST puro) | Marcar como suposição explícita ou remover |
 | 5 | **Critérios vagos:** algum A* usa linguagem não-mensurável ("deve ser rápido", "interface amigável") sem métrica? | Refinar: "resposta < 200ms p95", "WCAG 2.1 AA" |
 | 6 | **Dependências implícitas:** algum requisito v1 pressupõe que outro requisito (v2 ou fora) já esteja implementado? | Tornar dependência explícita ou reordenar versioning |
+| 7 | **Elevação de robustez:** todos os domínios detectados (AUTH, API, DB, FRONTEND, FILE) tiveram R-RB-NN propostos ou explicitamente descartados com justificativa? | Se Fase 3.5 foi pulada sem justificativa, executar agora ou registrar como risco em "Suposições e riscos" |
 
 **Resultado obrigatório antes de avançar:**
 - **0 problemas** → avançar para Fase 5 normalmente.
@@ -222,23 +244,24 @@ O resultado desta reflexão é **invisível ao usuário** — é trabalho intern
 - Atualizar `STATE.md`: `phase: spec_ready`, próximo passo conforme escolha
 </fase_5_aprovacao>
 
-<process>
-1. Ler `.oxe/STATE.md`, `OVERVIEW.md`, `STACK.md` e `OBSERVATIONS.md` do escopo ativo (verificar pendentes).
-2. Fazer uma exploração inicial do repo e dos artefatos antes da primeira rodada de perguntas. Consolidar internamente: fatos confirmados, inferências e lacunas.
-3. Aplicar `adaptive-discovery.md`: classificar a demanda, verificar se há capabilities úteis e se investigações anteriores reduzem incerteza.
-4. **Fase 1 — Perguntas:** enviar bloco coeso de 3-5 perguntas; máx 3 rodadas; confirmar entendimento.
-5. **Fase 2 — Pesquisa:** propor áreas de investigação; aguardar aprovação; executar se aprovado.
-6. **Fase 3 — Requisitos:** extrair tabela R-ID com v1/v2/fora e critérios A*; incorporar OBS pendentes; apresentar para validação.
-7. **Fase 4 — Roteiro:** agrupar requisitos v1 em fases; escrever `ROADMAP.md` no escopo ativo.
-8. Escrever **`SPEC.md`** usando `oxe/templates/SPEC.template.md` no escopo ativo:
-   - Frontmatter YAML (`oxe_doc: spec`, `status`, `updated`, `inputs`)
-   - Objetivo, Escopo (dentro/fora), Critérios de aceite (tabela A*), Suposições e riscos, Referências
-   - Preencher explicitamente `Tipo de demanda` e `Incertezas estruturadas`
-   - Preservar chaves existentes se SPEC.md já existir; atualizar `updated:`
-8b. **Auto-reflexão:** executar integralmente o bloco `<auto_reflexao>` antes de avançar. Corrigir a spec conforme necessário. Não apresentar a lista de verificação ao usuário — apenas a spec corrigida.
-9. **Fase 5 — Aprovação:** apresentar resumo, aguardar aprovação do roteiro, redirecionar.
-10. Atualizar **`.oxe/STATE.md`** global: `phase: spec_ready`, próximo passo e referência curta à sessão ativa quando existir.
-11. Marcar OBS incorporadas em `OBSERVATIONS.md` do escopo ativo se houver pendentes de impacto `spec`.
+<process>
+1. Ler `.oxe/STATE.md`, `OVERVIEW.md`, `STACK.md` e `OBSERVATIONS.md` do escopo ativo (verificar pendentes).
+2. Fazer uma exploração inicial do repo e dos artefatos antes da primeira rodada de perguntas. Consolidar internamente: fatos confirmados, inferências e lacunas.
+3. Aplicar `adaptive-discovery.md`: classificar a demanda, verificar se há capabilities úteis e se investigações anteriores reduzem incerteza.
+4. **Fase 1 — Perguntas:** enviar bloco coeso de 3-5 perguntas; máx 3 rodadas; confirmar entendimento.
+5. **Fase 2 — Pesquisa:** propor áreas de investigação; aguardar aprovação; executar se aprovado.
+6. **Fase 3 — Requisitos:** extrair tabela R-ID com v1/v2/fora e critérios A*; incorporar OBS pendentes; apresentar para validação.
+6.5. **Fase 3.5 — Elevação de Robustez:** detectar domínios (AUTH/API/DB/FRONTEND/FILE); propor R-RB-NN não cobertos; aguardar decisão; incorporar aprovados na tabela antes de avançar.
+7. **Fase 4 — Roteiro:** agrupar requisitos v1 em fases (incluindo R-RB aprovados); escrever `ROADMAP.md` no escopo ativo.
+8. Escrever **`SPEC.md`** usando `oxe/templates/SPEC.template.md` no escopo ativo:
+   - Frontmatter YAML (`oxe_doc: spec`, `status`, `updated`, `inputs`)
+   - Objetivo, Escopo (dentro/fora), Critérios de aceite (tabela A*), Suposições e riscos, Referências
+   - Preencher explicitamente `Tipo de demanda` e `Incertezas estruturadas`
+   - Preservar chaves existentes se SPEC.md já existir; atualizar `updated:`
+8b. **Auto-reflexão:** executar integralmente o bloco `<auto_reflexao>` antes de avançar. Corrigir a spec conforme necessário. Não apresentar a lista de verificação ao usuário — apenas a spec corrigida.
+9. **Fase 5 — Aprovação:** apresentar resumo, aguardar aprovação do roteiro, redirecionar.
+10. Atualizar **`.oxe/STATE.md`** global: `phase: spec_ready`, próximo passo e referência curta à sessão ativa quando existir.
+11. Marcar OBS incorporadas em `OBSERVATIONS.md` do escopo ativo se houver pendentes de impacto `spec`.
 </process>
 
 <success_criteria>
@@ -248,4 +271,5 @@ O resultado desta reflexão é **invisível ao usuário** — é trabalho intern
 - [ ] Usuário foi consultado no gate da Fase 5 e escolheu o próximo passo.
 - [ ] OBS pendentes com impacto `spec` foram incorporadas e marcadas `incorporada`.
 - [ ] Máximo 3 rodadas de perguntas utilizadas — não mais.
+- [ ] Fase 3.5 executada: domínios detectados tiveram R-RB-NN propostos, aprovados ou descartados com justificativa.
 </success_criteria>

package/oxe/workflows/verify.md

@@ -31,6 +31,7 @@ Se o usuário indicar uma tarefa (ex.: `T2`), focar só nela nas camadas 1–2;
 - **UI:** se existirem `UI-SPEC.md` / `UI-REVIEW.md` no escopo resolvido, incorporar na evidência quando os critérios **A*** ou tarefas **Tn** tocarem interface.
 - **Camada 5 — Validate-gaps (automático quando `verification_depth: "thorough"`):** após as 4 camadas, se `verification_depth: "thorough"` em `.oxe/config.json`, executar automaticamente a lógica de `oxe/workflows/validate-gaps.md` e produzir `.oxe/VALIDATION-GAPS.md` como parte deste verify. Não requer comando separado.
 - **Camada 6 — Security (automático quando `security_in_verify: true`):** se `security_in_verify: true` em `.oxe/config.json`, executar automaticamente a lógica de `oxe/workflows/security.md` e produzir `.oxe/SECURITY.md` como parte deste verify. Não requer comando separado.
+- **Camada QC — Quality Contract (automático quando SPEC.md contiver critérios R-RB):** se a SPEC.md do escopo resolvido contiver requisitos com ID `R-RB-NN` (gerados pela Fase 3.5 — Elevação de Robustez), executar a Camada QC conforme `<camada_qc_quality_contract>`. Não requer comando separado.
 - **Rotina compact/checkpoint (opcional):** se esta entrega alterou **estrutura**, **stack** ou **pastas** de forma relevante, `/oxe-scan` em modo refresh alinha `.oxe/codebase/` ao repo. Após **verify** com sucesso, `/oxe-project checkpoint` com slug curto pode marcar estado estável.
 </context>
 
@@ -103,6 +104,39 @@ Registrar em `VERIFY.md`: `Resultado de calibração | Confiança declarada | Re
 4. Usar esses artefatos como apoio para a seção de gaps e para a calibração do plano.
 </runtime_e_checkpoints>
 
+<camada_qc_quality_contract>
+**Camada QC — Contrato de Qualidade** (ativa quando SPEC.md contiver requisitos R-RB da Fase 3.5)
+
+**Objetivo:** verificar que os critérios de qualidade comprometidos na spec (R-RB aprovados como v1) foram efetivamente implementados — com o mesmo rigor de evidência aplicado aos critérios A*.
+
+**Execução:**
+
+1. Ler SPEC.md procurando requisitos com ID `R-RB-NN` e versão `v1` na tabela de requisitos.
+2. Localizar o **Accepted Risk Registry** da SPEC (seção "Suposições e riscos" ou "Riscos Aceitos") — anotar itens R-RB declinados.
+3. Para cada R-RB aprovado como v1, verificar implementação com evidência (Grep, Read, teste):
+
+   | ID R-RB | Critério (resumo) | Tier | Evidência | Implementado? |
+   |---------|-------------------|------|-----------|---------------|
+   | RB-SEC-A1 | Bcrypt salt≥10 | Piso | `grep bcrypt src/` → linha X | ✓ / ✗ |
+
+4. Calcular **Quality Score realizado:**
+   ```
+   QS_realizado = (Piso_implementados / Piso_aprovados × 60) + (Base_implementados / Base_aprovados × 40)
+   ```
+5. Comparar com Quality Score comprometido na spec (se registrado).
+6. Registrar na seção **Contrato de Qualidade** do VERIFY.md:
+   - Tabela de critérios R-RB (acima)
+   - Quality Score comprometido vs realizado
+   - Gap: itens aprovados como v1 mas não implementados
+
+**Severidade dos gaps:**
+- R-RB **Piso** não implementado → gap P0 → bloqueia `verify_complete` (mesma regra do security P0)
+- R-RB **Base** não implementado → gap P1 → registrar, não bloqueia
+- R-RB **Excelência** não implementado → informativo (estava em v2, não esperado)
+
+**Pulável apenas se:** SPEC.md não contiver nenhum R-RB-NN com versão v1.
+</camada_qc_quality_contract>
+
 <process>
 1. **Camada 1 — Auditoria de pré-execução:** checar integridade do PLAN.md e DISCUSS.md conforme `<camada_1_pre_exec_audit>`. Documentar resultado.
 2. Resolver o context pack `verify` primeiro:
@@ -142,6 +176,7 @@ O `calibration_error` de cada dimensão = `|score declarado - resultado observad
 8b. **Retrospectiva (pós-verify):** se `verify_complete`, sugerir **`/oxe-retro`** para capturar aprendizados do ciclo em `.oxe/LESSONS.md`. Especialmente importante quando: houve replanejamento (`--replan`), houve falhas em execute que precisaram de debug, critérios A* foram ajustados durante o ciclo, ou o ciclo durou mais de 2 ondas. Retro antes do próximo spec garante que lições orientem o próximo ciclo.
 8c. **Camada 5 — Validate-gaps automático:** se `verification_depth: "thorough"` em `.oxe/config.json`, executar a lógica de `oxe/workflows/validate-gaps.md` e adicionar seção **Gaps de Cobertura** ao VERIFY.md (mesmo conteúdo de VALIDATION-GAPS.md). Também escrever `.oxe/VALIDATION-GAPS.md` separado.
 8d. **Camada 6 — Security automático:** se `security_in_verify: true` em `.oxe/config.json`, executar a lógica de `oxe/workflows/security.md` e adicionar seção **Auditoria de Segurança** ao VERIFY.md. Também escrever `.oxe/SECURITY.md` separado. Achados P0 bloqueiam o `verify_complete` — registrar `verify_failed` até P0s serem resolvidos.
+8e. **Camada QC — Quality Contract automático:** se SPEC.md contiver requisitos `R-RB-NN` com versão `v1`, executar o bloco `<camada_qc_quality_contract>` e adicionar seção **Contrato de Qualidade** ao VERIFY.md. R-RB Piso não implementados bloqueiam `verify_complete` — registrar `verify_failed` até serem resolvidos ou explicitamente aceitos como risco P0.
 9. **Só se todas as verificações relevantes passarem:** se `after_verify_draft_commit` não for `false`: acrescentar em **VERIFY.md** a seção **Rascunho de commit** — mensagem convencional (ex.: `feat:` / `fix:`) + bullets alinhados aos critérios **A*** e decisões **D-NN**; **não** incluir segredos.
 10. **Só se passou:** se `after_verify_suggest_pr` não for `false`: acrescentar **Checklist PR** — branch base, título sugerido, screenshots se UI, links a SPEC/PLAN/DISCUSS, testes executados.
 11. No chat, responder nesta ordem:
@@ -161,4 +196,5 @@ O `calibration_error` de cada dimensão = `|score declarado - resultado observad
 - [ ] Se existiu DISCUSS.md: tabela de Fidelidade de decisões preenchida sem divergências não documentadas.
 - [ ] Se `verification_depth: "thorough"` em config: `.oxe/VALIDATION-GAPS.md` produzido como parte deste verify.
 - [ ] Se `security_in_verify: true` em config: `.oxe/SECURITY.md` produzido; achados P0 resolvidos ou `verify_failed` registrado.
+- [ ] Se SPEC.md contiver R-RB v1: seção **Contrato de Qualidade** presente em VERIFY.md com Quality Score realizado; R-RB Piso não implementados tratados como gaps P0.
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "oxe-cc",
-	"version": "0.9.2",
+	"version": "1.0.0",
 	"description": "OXE — spec-driven workflows in .oxe/; integrates with Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity (npx)",
 	"license": "GPL-3.0",
 	"author": "",
@@ -49,14 +49,20 @@
 		".github",
 		"commands",
 		"vscode-extension",
+		"packages/runtime/src",
+		"packages/runtime/package.json",
+		"packages/runtime/tsconfig.json",
 		"AGENTS.md",
 		"README.md",
 		"CHANGELOG.md"
 	],
 	"scripts": {
+		"build:runtime": "cd packages/runtime && npm run build",
 		"sync:runtime-metadata": "node scripts/sync-runtime-metadata.cjs",
 		"sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
-		"test": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs",
+		"test:root": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs",
+		"test:runtime": "cd packages/runtime && npm test",
+		"test": "npm run build:runtime && npm run test:root && npm run test:runtime",
 		"test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
 		"scan:assets": "node scripts/oxe-assets-scan.cjs",
 		"build:vscode-ext": "cd vscode-extension && npx @vscode/vsce package --no-yarn --allow-missing-repository",
@@ -83,4 +89,4 @@
 	"dependencies": {
 		"semver": "^7.7.4"
 	}
-}
+}

package/packages/runtime/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@oxe/runtime",
+  "version": "0.1.0",
+  "private": true,
+  "description": "OXE agentic execution engine — Runtime Foundation (R1)",
+  "main": "../../lib/runtime/index.js",
+  "types": "../../lib/runtime/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --project tsconfig.test.json && node --test dist-tests/tests/*.test.js",
+    "clean": "node -e \"const fs=require('fs');['../../lib/runtime','dist-tests'].forEach(d=>{try{fs.rmSync(d,{recursive:true})}catch{}});\""
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.4.5"
+  }
+}

package/packages/runtime/src/compiler/graph-compiler.ts

@@ -0,0 +1,245 @@
+import crypto from 'crypto';
+import type { WorkspaceStrategy } from '../models/workspace';
+
+// Mirror of SDK ParsedTask / ParsedSpec / ParsedPlan interfaces
+// (avoids a hard dependency on the CJS SDK from TypeScript source)
+export interface ParsedTask {
+  id: string;
+  title: string;
+  wave: number | null;
+  dependsOn: string[];
+  files: string[];
+  verifyCommand: string | null;
+  aceite: string[];
+  done: boolean;
+  meta?: Record<string, unknown> | null;
+}
+
+export interface ParsedSpecCriterion {
+  id: string;
+  criterion: string;
+  howToVerify: string;
+}
+
+export interface ParsedSpec {
+  objective: string | null;
+  criteria: ParsedSpecCriterion[];
+}
+
+export interface ParsedPlan {
+  tasks: ParsedTask[];
+  waves: Record<number, string[]>;
+  totalTasks: number;
+}
+
+export interface Action {
+  type: 'read_code' | 'generate_patch' | 'run_tests' | 'run_lint' | 'collect_evidence' | 'custom';
+  command?: string;
+  targets?: string[];
+}
+
+export interface VerifyContract {
+  must_pass: string[];
+  acceptance_refs: string[];
+  command: string | null;
+}
+
+export interface NodePolicy {
+  requires_human_approval: boolean;
+  max_retries: number;
+}
+
+export interface GraphNode {
+  id: string;
+  title: string;
+  wave: number;
+  depends_on: string[];
+  workspace_strategy: WorkspaceStrategy;
+  mutation_scope: string[];
+  actions: Action[];
+  verify: VerifyContract;
+  policy: NodePolicy;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  type: 'dependency' | 'wave_sequence';
+}
+
+export interface Wave {
+  wave_number: number;
+  node_ids: string[];
+}
+
+export interface ExecutionGraphMetadata {
+  compiled_at: string;
+  plan_hash: string;
+  spec_hash: string;
+  node_count: number;
+  wave_count: number;
+}
+
+export interface ExecutionGraph {
+  nodes: Map<string, GraphNode>;
+  edges: GraphEdge[];
+  waves: Wave[];
+  metadata: ExecutionGraphMetadata;
+}
+
+export interface CompilerOptions {
+  default_workspace_strategy?: WorkspaceStrategy;
+  default_max_retries?: number;
+  require_approval_for_all?: boolean;
+  skip_done_tasks?: boolean;
+}
+
+export function compile(
+  plan: ParsedPlan,
+  spec: ParsedSpec,
+  options: CompilerOptions = {}
+): ExecutionGraph {
+  const {
+    default_workspace_strategy = 'git_worktree',
+    default_max_retries = 2,
+    require_approval_for_all = false,
+    skip_done_tasks = false,
+  } = options;
+
+  const nodes = new Map<string, GraphNode>();
+  const edges: GraphEdge[] = [];
+  const waveMap = new Map<number, string[]>();
+
+  for (const task of plan.tasks) {
+    if (skip_done_tasks && task.done) continue;
+
+    const waveNumber = task.wave ?? 1;
+    const node: GraphNode = {
+      id: task.id,
+      title: task.title,
+      wave: waveNumber,
+      depends_on: task.dependsOn,
+      workspace_strategy: default_workspace_strategy,
+      mutation_scope: task.files,
+      actions: buildActions(task),
+      verify: {
+        must_pass: task.verifyCommand ? ['tests'] : [],
+        acceptance_refs: task.aceite,
+        command: task.verifyCommand,
+      },
+      policy: {
+        requires_human_approval: require_approval_for_all,
+        max_retries: default_max_retries,
+      },
+    };
+
+    nodes.set(task.id, node);
+
+    for (const dep of task.dependsOn) {
+      edges.push({ from: dep, to: task.id, type: 'dependency' });
+    }
+
+    if (!waveMap.has(waveNumber)) waveMap.set(waveNumber, []);
+    waveMap.get(waveNumber)!.push(task.id);
+  }
+
+  const waves: Wave[] = Array.from(waveMap.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([wave_number, node_ids]) => ({ wave_number, node_ids }));
+
+  return {
+    nodes,
+    edges,
+    waves,
+    metadata: {
+      compiled_at: new Date().toISOString(),
+      plan_hash: hashObject(plan),
+      spec_hash: hashObject(spec),
+      node_count: nodes.size,
+      wave_count: waves.length,
+    },
+  };
+}
+
+export function validateGraph(graph: ExecutionGraph): string[] {
+  const errors: string[] = [];
+  const nodeIds = new Set(graph.nodes.keys());
+
+  for (const [id, node] of graph.nodes) {
+    for (const dep of node.depends_on) {
+      if (!nodeIds.has(dep)) {
+        errors.push(`Node ${id} depends on unknown node ${dep}`);
+      }
+    }
+  }
+
+  // Detect cycles using DFS
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  function hasCycle(nodeId: string): boolean {
+    if (inStack.has(nodeId)) return true;
+    if (visited.has(nodeId)) return false;
+    visited.add(nodeId);
+    inStack.add(nodeId);
+    const node = graph.nodes.get(nodeId);
+    if (node) {
+      for (const dep of node.depends_on) {
+        if (hasCycle(dep)) return true;
+      }
+    }
+    inStack.delete(nodeId);
+    return false;
+  }
+
+  for (const id of nodeIds) {
+    if (hasCycle(id)) {
+      errors.push(`Cycle detected involving node ${id}`);
+      break;
+    }
+  }
+
+  return errors;
+}
+
+export function toSerializable(graph: ExecutionGraph): Record<string, unknown> {
+  return {
+    nodes: Object.fromEntries(graph.nodes),
+    edges: graph.edges,
+    waves: graph.waves,
+    metadata: graph.metadata,
+  };
+}
+
+export function fromSerializable(raw: Record<string, unknown>): ExecutionGraph {
+  const nodes = new Map<string, GraphNode>(
+    Object.entries(raw.nodes as Record<string, GraphNode>)
+  );
+  return {
+    nodes,
+    edges: raw.edges as GraphEdge[],
+    waves: raw.waves as Wave[],
+    metadata: raw.metadata as ExecutionGraphMetadata,
+  };
+}
+
+function buildActions(task: ParsedTask): Action[] {
+  const actions: Action[] = [];
+  if (task.files.length > 0) {
+    actions.push({ type: 'read_code', targets: task.files });
+  }
+  actions.push({ type: 'generate_patch' });
+  if (task.verifyCommand) {
+    actions.push({ type: 'run_tests', command: task.verifyCommand });
+  }
+  actions.push({ type: 'collect_evidence' });
+  return actions;
+}
+
+function hashObject(obj: unknown): string {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(obj))
+    .digest('hex')
+    .slice(0, 12);
+}

package/packages/runtime/src/compiler/index.ts

@@ -0,0 +1 @@
+export * from './graph-compiler';