oxe-cc 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ Todas as versões seguem [Semantic Versioning](https://semver.org/). As mudança
 
 ---
 
+## [1.11.0] — 2026-05-06
+
+### Spec Lifecycle Automation & CLI Gaps
+
+Esta release fecha os gaps de adoção identificados na análise de maturidade v1.10.0, com foco em automação do ciclo de vida do SPEC, configuração de provider e tolerância de formato no parser de planos.
+
+#### Automação do ciclo de vida (SPEC.md)
+
+- nova função `applySpecChecklistSync` em `oxe-operational.cjs`: ao executar `runtime project` com um run `completed`, marca automaticamente `**DoD Wave N:**` e seções MVP/v0.x.x do checklist no `SPEC.md` com `[x]`
+- v1.0.0 checklist não é marcado automaticamente — requer sign-off explícito
+- exportada no módulo para testes de integração e uso programático
+
+#### CLI — `runtime execute`
+
+- novo flag `--agents-plan <path>`: override explícito para localização do `plan-agents.json`, com prioridade sobre detecção automática por sessão e raiz do projeto
+- novo flag `--api-key-env <VAR>`: lê API key de variável de ambiente nomeada em vez de `OXE_LLM_API_KEY`
+- novo subcomando `runtime configure`: wizard interativo que persiste `baseUrl`, `model`, `apiKey` em `.oxe/config.json` (seção `runtime.provider`)
+
+#### Provider LLM auto-wired
+
+- `createExecutionContext` passa a instanciar `PolicyEngine.fromConfigFile()` automaticamente quando `.oxe/config.json` contém seção `runtime.policy`
+- `loadRuntimeProviderConfig` / `saveRuntimeProviderConfig` exportados de `oxe-operational.cjs`
+- health checks de `runtime.provider` e `runtime.policy` adicionados ao `oxe-cc status`
+
+#### Parser de planos — tolerância de formato (Gap E)
+
+- `parsePlan` agora aceita `**Verificação:**`, `**Verify command:**` e `**Verification:**` além do formato `Verificação:` sem negrito
+- planos gerados por LLM com markdown bold deixam de silenciosamente omitir verify commands
+
+#### Spec-criteria enrichment (Gap B)
+
+- `compileExecutionGraphFromArtifacts` extrai comandos backtick dos campos `howToVerify` dos critérios de aceite da SPEC e os anexa a `node.verify.command` quando ausente no PLAN
+
+#### Testes e benchmark
+
+- novo `test:runtime-llm` (`scripts/test-runtime-llm.cjs`): valida `LlmTaskExecutor` end-to-end com LLM real; skipa automaticamente quando `OXE_LLM_API_KEY` não está definido
+- novo `benchmark:autonomy` (`scripts/benchmark-autonomy.cjs`): 5 fixtures de referência (simple → medium → parallel), mede taxa de compilação→execução→verify sem intervenção; saída em `.oxe/release/benchmark-autonomy-report.json`
+- novos testes: `gap-spec-enrichment.test.cjs` (5 casos) e `gap-spec-checklist-sync.test.cjs` (4 casos)
+
 ## [1.10.0] — 2026-05-05
 
 ### Operational Maturity

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
 [![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
 
-**Versão:** `1.10.0` · [package.json](package.json)
+**Versão:** `1.11.0` · [package.json](package.json)
 
 **Framework OXE — Orchestrated eXperience Engineering**
 
@@ -34,10 +34,10 @@ Ele se apoia em três princípios:
 
 - **Spec-driven design** — antes de escrever código, você define *o que* construir e *como saber que está pronto*. Essa especificação restringe e guia tudo o que vem depois.
 - **Context engineering** — o estado do trabalho fica em arquivos pequenos dentro de `.oxe/`, não na memória do chat. O agente lê o que precisa, quando precisa — sem sobrecarregar o contexto com decisões já tomadas.
-- **Lessons loop** — ao fim de cada ciclo, `/oxe-retro` extrai 3–5 lições prescritivas que o próximo spec/plan lê automaticamente. Depois de alguns ciclos, os planos ficam dramaticamente melhores porque os erros anteriores não se repetem.
-- **Plan-Driven Dynamic Agents** — quando há múltiplos domínios, o plano cria agentes específicos para *aquela demanda*. Agentes não são reaproveitados entre projetos ou demandas.
-- **Semântica de raciocínio multi-runtime** — discovery, planning, execution, review e status seguem contratos cognitivos explícitos. O mesmo workflow OXE deve gerar respostas exploratórias, decision-complete e auditáveis em Copilot, Cursor, Claude, Codex e demais runtimes suportados.
-- **Entradas visuais rastreáveis** — imagens, screenshots e mockups enviados ao chat são interpretados pelo runtime hospedeiro quando ele tem visão, mas o OXE exige que essa interpretação vire `VISUAL-INPUTS.md/json` e anchors antes de alimentar plan/execute.
+- **Lessons loop** — ao fim de cada ciclo, `/oxe-retro` extrai 3–5 lições prescritivas que o próximo spec/plan lê automaticamente. Depois de alguns ciclos, os planos ficam dramaticamente melhores porque os erros anteriores não se repetem.
+- **Plan-Driven Dynamic Agents** — quando há múltiplos domínios, o plano cria agentes específicos para *aquela demanda*. Agentes não são reaproveitados entre projetos ou demandas.
+- **Semântica de raciocínio multi-runtime** — discovery, planning, execution, review e status seguem contratos cognitivos explícitos. O mesmo workflow OXE deve gerar respostas exploratórias, decision-complete e auditáveis em Copilot, Cursor, Claude, Codex e demais runtimes suportados.
+- **Entradas visuais rastreáveis** — imagens, screenshots e mockups enviados ao chat são interpretados pelo runtime hospedeiro quando ele tem visão, mas o OXE exige que essa interpretação vire `VISUAL-INPUTS.md/json` e anchors antes de alimentar plan/execute.
 
 O resultado: **menos requisições**, **mais coerência**, e uma experiência de engenharia orquestrada que funciona do mesmo jeito em qualquer IDE.
 
@@ -69,16 +69,16 @@ O OXE já não é só um conjunto de prompts e markdowns. Hoje ele combina:
 
 Em termos práticos, o estado operacional real agora passa por:
 
-- `ACTIVE-RUN.json`
-- `.oxe/runs/<run_id>.json`
-- `.oxe/runs/<run_id>/verification-manifest.json`
-- `.oxe/runs/<run_id>/residual-risk-ledger.json`
-- `.oxe/runs/<run_id>/evidence-coverage.json`
-- `.oxe/runs/<run_id>/workspace-merge-report.json`
-- `.oxe/execution/GATES.json`
-- `OXE-EVENTS.ndjson`
-
-Contrato estável desta release:
+- `ACTIVE-RUN.json`
+- `.oxe/runs/<run_id>.json`
+- `.oxe/runs/<run_id>/verification-manifest.json`
+- `.oxe/runs/<run_id>/residual-risk-ledger.json`
+- `.oxe/runs/<run_id>/evidence-coverage.json`
+- `.oxe/runs/<run_id>/workspace-merge-report.json`
+- `.oxe/execution/GATES.json`
+- `OXE-EVENTS.ndjson`
+
+Contrato estável desta release:
 
 - `execute` e `verify` são `runtime-first` quando `oxe-cc runtime` está disponível
 - `status`, `doctor`, dashboard e CLI de runtime leem o mesmo estado canónico
@@ -252,7 +252,7 @@ Cada passo lê o anterior como contexto e escreve seu artefato no escopo correto
 | Comando | O que entrega |
 |---------|--------------|
 | `/oxe` | Sem input → próximo passo. Com pergunta → situação atual (artefatos reais). Com "help" → trilha principal. |
-| `/oxe-spec` | **5 fases**: perguntas → pesquisa → requisitos R-ID → roteiro → aprovação. `--refresh` / `--full` fazem scan antes. `--research` ativa spike explícito. `--ui` gera UI-SPEC ao final. Se houver imagem/screenshot/mockup no chat, materializa `VISUAL-INPUTS` quando o runtime suportar visão ou registra limitação explícita. |
+| `/oxe-spec` | **5 fases**: perguntas → pesquisa → requisitos R-ID → roteiro → aprovação. `--refresh` / `--full` fazem scan antes. `--research` ativa spike explícito. `--ui` gera UI-SPEC ao final. Se houver imagem/screenshot/mockup no chat, materializa `VISUAL-INPUTS` quando o runtime suportar visão ou registra limitação explícita. |
 | `/oxe-plan` | **Test-first:** `Verificar` vem antes de `Implementar` em cada tarefa. `PLAN.md` com `## Autoavaliação do Plano` (rubrica fixa + confiança determinística). Usa investigações e capabilities como evidência. |
 | `/oxe-execute` | Execução A/B/C. Valida autoavaliação antes de implementar. `--note` registra observação. `--debug` aciona diagnóstico inline. `--deep-diagnosis` escalona para forensics. `--checkpoint "<nome>"` cria snapshot. `--iterative` ativa loop de retry. Usa `EXECUTION-RUNTIME.md`, `ACTIVE-RUN.json`, `OXE-EVENTS.ndjson`. |
 | `/oxe-verify` | Até 6 camadas: audit + critérios + decisões + coerência operacional + calibração + UAT. `--gaps` ativa Camada 5 (cobertura). `--security` ativa Camada 6 (OWASP). `--ui` inclui UI-REVIEW. `--pr` / `--diff` incluem revisão de PR. Retro automática ao fechar (`--skip-retro` para desativar). |
@@ -285,8 +285,8 @@ Estes comportamentos continuam existindo, mas agora são ativados como flags dos
 |---------------|-------------|
 | Scan / refresh do codebase | `/oxe-spec --refresh` (incremental) ou `--full` (completo) |
 | Research / spike / engenharia reversa | `/oxe-spec --research` |
-| Contrato UI/UX | `/oxe-spec --ui` |
-| Imagem, screenshot ou mockup como entrada de spec | anexar no chat junto com `/oxe-spec`; o OXE materializa a interpretação em `.oxe/investigations/visual/VISUAL-INPUTS.*` quando o runtime tiver visão |
+| Contrato UI/UX | `/oxe-spec --ui` |
+| Imagem, screenshot ou mockup como entrada de spec | anexar no chat junto com `/oxe-spec`; o OXE materializa a interpretação em `.oxe/investigations/visual/VISUAL-INPUTS.*` quando o runtime tiver visão |
 | Registrar observação durante execução | `/oxe-execute --note "texto"` |
 | Diagnóstico técnico inline | `/oxe-execute --debug` |
 | Diagnóstico pós-falha persistente | `/oxe-execute --deep-diagnosis` |
@@ -462,23 +462,23 @@ O `status --full` mostra em ANSI: readiness do ciclo, autoavaliação do plano,
 
 O pacote está pronto para uma publicação robusta quando estes sinais estiverem verdes no repositório da release:
 
-- `npm test`
-- `npm run scan:assets`
-- `npm run build:vscode-ext`
-- `node bin/oxe-cc.js doctor --release --write-manifest`
-- `npm run release:pack-check`
-- `node bin/oxe-cc.js status --full`
+- `npm test`
+- `npm run scan:assets`
+- `npm run build:vscode-ext`
+- `node bin/oxe-cc.js doctor --release --write-manifest`
+- `npm run release:pack-check`
+- `node bin/oxe-cc.js status --full`
 
 Artefatos obrigatórios desta fase:
 
-- `.oxe/release/release-manifest.json`
-- `.oxe/release/runtime-smoke-report.json`
-- `.oxe/release/runtime-real-report.json`
-- `.oxe/release/recovery-fixture-report.json`
-- `.oxe/release/multi-agent-soak-report.json`
-- `.oxe/release/multi-agent-real-report.json`
-
-Na linha `1.9.1`, `runtime-real-report.json` prova o ciclo real `compile -> execute mockado -> verify -> project -> status --json`, e `multi-agent-real-report.json` prova coordenação com `git_worktree`, ownership, arbitragem e merge readiness antes da publicação.
+- `.oxe/release/release-manifest.json`
+- `.oxe/release/runtime-smoke-report.json`
+- `.oxe/release/runtime-real-report.json`
+- `.oxe/release/recovery-fixture-report.json`
+- `.oxe/release/multi-agent-soak-report.json`
+- `.oxe/release/multi-agent-real-report.json`
+
+Na linha `1.9.1`, `runtime-real-report.json` prova o ciclo real `compile -> execute mockado -> verify -> project -> status --json`, e `multi-agent-real-report.json` prova coordenação com `git_worktree`, ownership, arbitragem e merge readiness antes da publicação.
 
 ### `/oxe-retro` — loop de aprendizado