oxe-cc 1.12.0 → 1.16.0

package/README.md

@@ -1,736 +1,600 @@
-<div align="center">
-
-<p align="center">
-  <img src="assets/readme-banner.svg" alt="OXE" width="920" />
-</p>
-
-[![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.12.0` · [package.json](package.json)
-
-**Framework OXE — Orchestrated eXperience Engineering**
-
-```bash
-npx oxe-cc@latest
-```
-
-</div>
-
----
-
-## O que é o OXE
-
-> **OXE é a camada de disciplina entre você e seu agente de IA. Qualquer agente, qualquer IDE, qualquer projeto — o mesmo ciclo estruturado, com memória persistente que melhora a cada entrega.**
-
-OXE é o **Framework OXE — Orchestrated eXperience Engineering**: um sistema de desenvolvimento assistido por IA orientado por artefatos, contexto em disco e execução verificável. Funciona em Cursor, GitHub Copilot, Claude Code, Gemini CLI, Windsurf e qualquer outro agente — o estado fica em `.oxe/` no seu projeto, não preso a nenhuma IDE.
-
-A partir da v1.12.0, o OXE opera em três camadas complementares:
-
-- **modo autônomo** — `/oxe <objetivo>` → Conductor Agent classifica, recupera memória, seleciona personas e decide automaticamente Agent Mode ou Swarm Mode
-- **framework de método** — `spec → plan → execute → verify`, sessões, workstreams, lessons loop e contratos de raciocínio multi-runtime
-- **runtime enterprise** — `ExecutionGraph`, evidence store, verification manifest, gates, policy, promotion, recovery e auditoria operacional
-
-Seus princípios:
-
-- **Spec-driven design** — antes de escrever código, você define *o que* construir e *como saber que está pronto*.
-- **Context engineering** — o estado do trabalho fica em arquivos pequenos em `.oxe/`, não na memória do chat. O agente lê o que precisa, quando precisa.
-- **Memory Kernel** — memória cross-session em `.oxe/memory/REPO-MEMORY.md` injetada automaticamente antes de cada run. Decisões, pitfalls e padrões não se perdem entre sessões.
-- **Learning Kernel** — ao fim de cada ciclo, padrões são destilados, lições atualizadas com dedup e skills candidatas enfileiradas para promoção. Os próximos planos ficam melhores porque os erros anteriores não se repetem.
-- **Plan-Driven Dynamic Agents** — quando há múltiplos domínios, o Conductor cria agentes específicos para *aquela demanda* com ownership de arquivo e coordenação por ondas.
-- **Semântica de raciocínio multi-runtime** — discovery, planning, execution, review e status seguem contratos cognitivos explícitos em qualquer IDE.
-
-O resultado: **menos requisições**, **mais coerência**, e uma experiência de engenharia orquestrada que aprende com cada ciclo.
-
----
-
-## Modo autônomo — `/oxe <objetivo>`
-
-A forma mais direta de usar o OXE a partir da v1.12.0:
-
-```
-/oxe cria um módulo de importação de arquivos com histórico e validação
-```
-
-O **Conductor Agent** (`oxe/workflows/conduct.md`) faz automaticamente:
-
-1. **Classifica** a complexidade: simples | médio | complexo
-2. **Recupera memória** das 5 camadas (runtime_state → session → project → lessons → observations)
-3. **Seleciona personas** aplicáveis ao objetivo (executor, architect, ui-specialist, db-specialist…)
-4. **Decide o modo** e executa:
-
-```
-intent_score = simples ou médio
-  → Agent Mode: Conductor age sozinho com a persona correta
-    artefatos: .oxe/agent/AGENT-SESSION.json
-
-intent_score = complexo (3+ domínios, 8+ arquivos, feature end-to-end)
-  → Swarm Mode: Scout → Coordinator → Builders → Reviewer → Verifier
-    artefatos: .oxe/swarm/SWARM-RUN.json, BOARD.md, FILE-OWNERSHIP.json
-```
-
-### Agent Mode
-
-Para objetivos de 1–2 domínios. O Conductor age como implementador com a persona mais adequada:
-
-```
-/oxe ajusta o texto do botão de exportar para "Exportar CSV"
-→ persona: executor
-→ discovery mínimo → implementa → verifica → grava AGENT-SESSION.json
-→ OXE-EVENTS.ndjson: RunStarted + WorkItemCompleted + RunCompleted
-```
-
-Artefatos em `.oxe/agent/`:
-- `AGENT-SESSION.json` — intent, skills carregadas, work_items, reconciliação
-- `MEMORY-INJECTIONS.md` — contexto de memória injetado (auditável)
-- `SKILLS-LOADED.json` — personas ativas no run
-- `RECONCILIATION.md` — resultado final: objective_satisfied, arquivos alterados
-
-### Swarm Mode
-
-Para objetivos complexos com múltiplos domínios. Uma equipe de agentes especializados opera em pipeline:
-
-```
-/oxe criar módulo de importação com histórico, validação e tela de acompanhamento
-→ Swarm: Scout + builder-backend + builder-frontend + builder-storage + Reviewer + Verifier
-→ FILE-OWNERSHIP.json: sem conflito, 3 builders em paralelo na wave 1
-→ reviews/T001..T005-REVIEW.md por task
-→ FINAL-INTEGRATION.md com evidências
-→ LESSONS.md atualizado automaticamente
-```
-
-Artefatos em `.oxe/swarm/`:
-- `SWARM-RUN.json` — estado completo do run multi-agente
-- `TASK-GRAPH.json` — tarefas, dependências e waves
-- `FILE-OWNERSHIP.json` — qual agente toca qual arquivo (sem conflitos)
-- `BOARD.md` / `BOARD.json` — visão em tempo real: status por task, bloqueios, gates
-- `scout/` — `CODEBASE-MAP.md`, `PATTERNS.md`, `RISK-MAP.md`, `FILE-CANDIDATES.json`
-- `reviews/` — um arquivo por task, produzido pelo Reviewer
-- `FINAL-INTEGRATION.md` — resultado da integração pelo Verifier
-- `QUALITY-GATES.md` — gates automáticos por risk_score
-
-### Memory Kernel
-
-Memória ativa injetada automaticamente antes de cada run:
-
-```
-.oxe/memory/
-├── REPO-MEMORY.md      ← decisões arquiteturais, pitfalls, preferências, padrões validados
-├── MEMORY-INDEX.json   ← índice com relevance_tags por fase
-└── retrieved/          ← snapshots do contexto injetado (auditável por run)
-    ├── conduct.md
-    ├── agent.md
-    └── swarm.md
-```
-
-`bin/lib/oxe-memory-kernel.cjs` — `retrieveMemory(intent_tags, phase)` filtra por relevância e ranking; `bin/lib/oxe-skill-loader.cjs` — `selectPersonasForIntent(tags)` mapeia domínios para personas.
-
-### Learning Kernel
-
-Ao final de cada run, `oxe/workflows/distill.md` aciona automaticamente:
-
-```
-Run completo
-  ↓
-Detecta padrões: blocker_pattern, success_pattern, anti_pattern, file_conflict…
-  ↓
-CANDIDATES.ndjson ← candidatos categorizados
-  ↓
-LESSONS.md ← dedup: mesma raiz → Frequência++; novo → C-NN-L1
-  ↓
-lessons-metrics.json ← success_rate; deprecação auto se < 0.5 em 3+ aplicações
-  ↓
-PROMOTION-QUEUE.md ← skills candidatas para revisão humana
-  ↓
-REPO-MEMORY.md ← decisões e pitfalls persistidos cross-session
-```
-
----
-
-## Modos de uso
-
-Escolha o ponto de entrada certo para o nível de controle que você quer.
-
-### Autônomo — 1 comando, Conductor decide
-
-Para quando você quer só entregar:
-
-```
-/oxe <objetivo em linguagem natural>
-```
-
-### Nano — tarefa pontual, sem overhead
-
-```
-/oxe-quick → objetivo → passos → verify
-```
-
-### Standard — ciclo completo com controle manual
-
-Para features, refatorações ou quando você quer conduzir cada fase:
-
-```
-/oxe → /oxe-spec → /oxe-plan → /oxe-execute → /oxe-verify
-```
-
-> scan, research, debug, retro e validações especializadas são acionados automaticamente
-> pelos estágios corretos ou por flags explícitas (`--research`, `--debug`, `--security`).
-
-### Full — orquestração avançada de times
-
-Para projetos longos, multi-domínio ou com revisão em equipe:
-
-```
-/oxe-session new <nome>   ← isola o ciclo numa sessão
-/oxe-plan --agents        ← blueprint multi-agente explícito
-/oxe-execute              ← runtime tracking, checkpoints e eventos
-/oxe-dashboard            ← visão web para revisão de equipe
-```
-
----
-
-## Trilha principal
-
-```
-/oxe              → autônomo (Conductor) | status | help | perguntas situacionais
-/oxe-quick        → tarefa pequena, sem cerimônia
-/oxe-spec         → nova feature: perguntas → requisitos → roteiro
-                    (absorve scan, research e ui-spec via flags)
-/oxe-plan         → tarefas por onda (--agents para multi-agente explícito)
-/oxe-execute      → implementar (A: completo | B: por onda | C: por tarefa)
-                    (absorve obs, debug, forensics, checkpoint, loop via flags)
-/oxe-verify       → validar e fechar o ciclo (retro automática)
-                    (absorve gaps, security, ui-review, review-pr via flags)
-```
-
-## Trilha avançada
-
-```
-/oxe-session      → criar, alternar, retomar, fechar ou migrar sessões OXE
-/oxe-dashboard    → visualizar runtime, ondas, checkpoints e estado operacional
-```
-
-## Comandos administrativos
-
-```
-/oxe-capabilities → catálogo nativo de capabilities
-/oxe-skill        → skills OXE via @<id> — list, explain, new, @<id>
-oxe-cc azure      → autenticar, sincronizar inventário e operar Azure com checkpoint formal
-```
-
----
-
-## Semântica de raciocínio
-
-O OXE distingue cinco famílias de raciocínio aplicadas por cada workflow:
-
-- `discovery` — explorar antes de perguntar; separar fatos, inferências e lacunas
-- `planning` — produzir plano decision-complete, com riscos, validação e confidence gate
-- `execution` — reconhecimento curto antes de mutar; menor write set viável; validação por fatia
-- `review` — findings primeiro, severidade, evidência e risco residual
-- `status` — leitura curta do estado, recomendação única e motivo
-
-Contratos em `oxe/workflows/references/reasoning-*.md`, derivados para cada runtime em `.github/prompts/`, `.cursor/commands/`, `commands/oxe/` e `.codex/prompts/`. `oxe/workflows/**` e `workflow-runtime-contracts.json` são contratos obrigatórios da release.
-
----
-
-## Estado atual do produto
-
-O OXE combina hoje cinco camadas:
-
-- **modo autônomo** — Conductor Agent decide Agent Mode vs Swarm Mode a partir de linguagem natural
-- **artefatos canónicos em `.oxe/`** — continuidade entre sessões, IDEs e agentes
-- **Memory Kernel** — `REPO-MEMORY.md` + `MEMORY-INDEX.json` + context packs injetados antes de cada run
-- **Learning Kernel** — destilação de padrões → `LESSONS.md` (dedup) + `PROMOTION-QUEUE.md` (skills candidatas)
-- **runtime TypeScript compilado para CJS** em `packages/runtime/` — ExecutionGraph, scheduler multi-agente (parallel/competitive/cooperative), evidence store, gates, policy, promotion e recovery
-
-O estado operacional real passa por:
-
-```
-.oxe/
-├── OXE-EVENTS.ndjson         ← tracing append-only, agora efetivamente populado
-├── ACTIVE-RUN.json           ← cursor e estado do run atual
-├── agent/                    ← artefatos de Agent Mode runs
-│   ├── AGENT-SESSION.json
-│   ├── MEMORY-INJECTIONS.md
-│   ├── SKILLS-LOADED.json
-│   └── RECONCILIATION.md
-├── swarm/                    ← artefatos de Swarm Mode runs
-│   ├── SWARM-RUN.json
-│   ├── TASK-GRAPH.json
-│   ├── FILE-OWNERSHIP.json
-│   ├── BOARD.md / BOARD.json
-│   ├── QUALITY-GATES.md
-│   ├── FINAL-INTEGRATION.md
-│   ├── scout/
-│   └── reviews/
-├── memory/                   ← Memory Kernel
-│   ├── REPO-MEMORY.md
-│   ├── MEMORY-INDEX.json
-│   └── retrieved/
-├── learning/                 ← Learning Kernel
-│   ├── CANDIDATES.ndjson
-│   ├── PROMOTION-QUEUE.md
-│   └── LEARNING-EVENTS.ndjson
-├── runs/<run_id>/            ← runtime enterprise por run
-│   ├── verification-manifest.json
-│   ├── residual-risk-ledger.json
-│   ├── evidence-coverage.json
-│   └── workspace-merge-report.json
-├── execution/GATES.json
-└── global/
-    └── LESSONS.md            ← lições prescritivas cumulativas
-```
-
-Contrato estável desta release:
-
-- `/oxe <objetivo>` → Conductor → Agent Mode ou Swarm Mode (automático)
-- `execute` e `verify` são `runtime-first` quando `oxe-cc runtime` está disponível
-- `multi-agent` é GA apenas com isolamento real (`git_worktree`)
-- `OXE-EVENTS.ndjson` é populado em todo run (RunStarted, WorkItemCompleted, GateRequested, LessonPromoted, RunCompleted)
-- `REPO-MEMORY.md` é atualizado automaticamente ao final de Swarm Mode runs
-
-→ [Guia por papel](docs/ROLES.md) · [Quickstart](QUICKSTART.md) · [Walkthrough](docs/WALKTHROUGH.md)
-
----
-
-## Para times
-
-| Recurso | Link |
-|---------|------|
-| Primeiros 15 minutos | [QUICKSTART.md](QUICKSTART.md) |
-| Guia por papel (executor / reviewer / operador) | [docs/ROLES.md](docs/ROLES.md) |
-| Fluxo recomendado para times | [docs/TEAM-ADOPTION.md](docs/TEAM-ADOPTION.md) |
-| Exemplo completo reproduzível | [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md) |
-| Incidentes e gates | [docs/INCIDENT-PLAYBOOK.md](docs/INCIDENT-PLAYBOOK.md) |
-| Suporte por runtime (Cursor, Copilot, Claude Code…) | [docs/RUNTIME-SMOKE-MATRIX.md](docs/RUNTIME-SMOKE-MATRIX.md) |
-| Release readiness e publicação | [docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md) |
-
----
-
-## Sessões OXE
-
-Sessões organizam um ciclo completo em `.oxe/sessions/sNNN-slug/` sem misturar artefatos de entregas diferentes na raiz. `spec`, `plan`, `execute`, `verify`, `checkpoint`, `research` e afins respeitam `active_session` em `.oxe/STATE.md`.
-
-```text
-.oxe/
-├── STATE.md
-├── SESSIONS.md
-├── global/
-│   ├── LESSONS.md
-│   └── MILESTONES.md
-├── memory/         ← cross-session (não scoped)
-├── learning/       ← cross-session (não scoped)
-├── codebase/
-└── sessions/
-    └── s001-exemplo/
-        ├── SESSION.md
-        ├── spec/
-        ├── plan/
-        ├── execution/
-        ├── verification/
-        ├── checkpoints/
-        ├── research/
-        └── workstreams/
-```
-
-| Subcomando | O que faz |
-|------------|-----------|
-| `/oxe-session new <nome>` | Cria a sessão e define `active_session` |
-| `/oxe-session list` | Lista sessões em `.oxe/SESSIONS.md` |
-| `/oxe-session switch <id>` | Alterna a sessão ativa |
-| `/oxe-session resume <id>` | Alias de `switch` |
-| `/oxe-session status` | Mostra os metadados da sessão ativa |
-| `/oxe-session close` | Arquiva a sessão ativa |
-| `/oxe-session migrate <nome>` | Cria sessão nova e move artefatos session-scoped da raiz |
-
----
-
-## A cadeia
-
-```
-/oxe <objetivo>
-  ↓ Conductor (automático)
-  ├── Agent Mode ──────────────────────────── → .oxe/agent/
-  └── Swarm Mode (Scout→Builders→Reviewer→Verifier) → .oxe/swarm/
-          ↓
-     Learning Kernel → .oxe/learning/ + .oxe/global/LESSONS.md
-          ↓
-     Memory Kernel → .oxe/memory/REPO-MEMORY.md (próximo run lê)
-
-/oxe-spec → /oxe-plan → /oxe-execute → /oxe-verify  (controle manual)
-                ↓                            ↓
-          /oxe-quick               .oxe/global/LESSONS.md
-         (trabalho pequeno)         (alimenta próximo ciclo)
-```
-
-**Comportamentos absorvidos por cada estágio:**
-
-| Estágio | Absorve (via flags ou automático) |
-|---------|-----------------------------------|
-| `/oxe` | Conductor (objetivos), ask (perguntas situacionais), route, status, help |
-| `/oxe-spec` | scan (`--refresh`/`--full`), research (`--research`), ui-spec (`--ui`) |
-| `/oxe-execute` | obs (`--note`), debug (`--debug`), forensics (`--deep-diagnosis`), checkpoint (`--checkpoint`), loop (`--iterative`) |
-| `/oxe-verify` | gaps (`--gaps`), security (`--security`), ui-review (`--ui`), review-pr (`--pr`), retro (automática) |
-
----
-
-## Como cada comando funciona
-
-| Comando | O que entrega |
-|---------|--------------|
-| `/oxe` | Com objetivo de implementação → Conductor (Agent/Swarm). Sem input → próximo passo. Com pergunta → situação atual. Com "help" → trilha principal. |
-| `/oxe-spec` | **5 fases**: perguntas → pesquisa → requisitos R-ID → roteiro → aprovação. `--refresh`/`--full` fazem scan antes. `--research` ativa spike. `--ui` gera UI-SPEC. Imagem/screenshot no chat → materializa `VISUAL-INPUTS` quando o runtime suportar visão. |
-| `/oxe-plan` | **Test-first:** `Verificar` antes de `Implementar`. `PLAN.md` com `## Autoavaliação do Plano`. `--agents` gera `plan-agents.json` (schema v3 com personas e model_hint). |
-| `/oxe-execute` | Modos A/B/C. Valida autoavaliação antes de implementar. `--note` → observação. `--debug` → diagnóstico inline. `--deep-diagnosis` → forensics. `--checkpoint` → snapshot. `--iterative` → loop de retry. |
-| `/oxe-verify` | Até 6 camadas: audit + critérios + decisões + coerência operacional + calibração + UAT. `--gaps` → cobertura. `--security` → OWASP. `--ui` → UI-REVIEW. `--pr`/`--diff` → revisão de PR. Retro automática ao fechar. |
-| `/oxe-quick` | Objetivo → passos → agentes opcionais (PDDA lean) → verify. Para correções pontuais. |
-| `/oxe-session` | `new`, `list`, `switch`, `resume`, `status`, `close`, `migrate`, `milestone`, `workstream`. |
-| `/oxe-dashboard` | Consolida STATE, PLAN, ACTIVE-RUN, trace log, runtime, checkpoints e verify numa visão visual de ciclo, ondas e aprovação. |
-| `/oxe-skill` | `list` (active/proposed/archived/global) · `explain <id>` · `new <id>` · `@<id>` (inline). Resolução: projeto → capabilities → global. |
-| `oxe-cc azure` | Provider Azure nativo: autenticação, inventário via Resource Graph, operações guiadas para Service Bus, Event Grid e Azure SQL. |
-
----
-
-## Personas disponíveis
-
-O OXE tem 8 personas builtin em `oxe/personas/`. O Conductor as seleciona automaticamente por `intent_tags`; você pode invocá-las diretamente em qualquer workflow com `@<id>`:
-
-| ID | Papel | Domínio |
-|----|-------|---------|
-| `executor` | Implementador de precisão | código, commits atômicos, write set mínimo |
-| `planner` | Arquiteto de grafo | decomposição, waves, mutation_scope |
-| `verifier` | Auditor cético | verificação 4-camadas, evidence-only |
-| `architect` | Design de sistema | boundaries, contratos, decisões D-NN |
-| `ui-specialist` | UI/UX | componentes, estados, acessibilidade |
-| `db-specialist` | Banco de dados | schema, migrations, N+1, integridade |
-| `researcher` | Exploração | descoberta, redução de incerteza, POC |
-| `debugger` | Root cause | RCA, hotfix mínimo, reprodução |
-
-Skills de projeto ficam em `.oxe/skills/active/` e têm precedência sobre as globais.
-
----
-
-## Quando usar cada modo do execute
-
-```
-A) Completo   → todas as ondas numa só execução  (ideal: Claude, Copilot, Gemini)
-B) Por onda   → onda 1, você verifica, chama de novo  (1 rodada por onda)
-C) Por tarefa → máximo controle  (1 rodada por tarefa)
-```
-
-Se uma tarefa falha: diagnóstico inline automático (2-3 hipóteses → fix → retry). O Modo B inclui loop iterativo com escalada automática para diagnóstico profundo.
-
----
-
-## Comportamentos especializados (via flags)
-
-| Comportamento | Como ativar |
-|---------------|-------------|
-| Scan / refresh do codebase | `/oxe-spec --refresh` ou `--full` |
-| Research / spike | `/oxe-spec --research` |
-| Contrato UI/UX | `/oxe-spec --ui` |
-| 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` |
-| Snapshot nomeado | `/oxe-execute --checkpoint "<nome>"` |
-| Loop de retry | `/oxe-execute --iterative` |
-| Auditoria de cobertura | `/oxe-verify --gaps` |
-| Auditoria OWASP | `/oxe-verify --security` |
-| Auditoria de implementação UI | `/oxe-verify --ui` |
-| Revisão de PR ou diff | `/oxe-verify --pr` ou `--diff branchA...branchB` |
-| Retrospectiva | automática ao fechar `/oxe-verify` (desativar: `--skip-retro`) |
-
-**Compatibilidade:** comandos legados (`/oxe-debug`, `/oxe-forensics`, `/oxe-research`, etc.) continuam funcionando desde v1.1.0 com aviso de migração.
-
----
-
-## Azure no OXE
-
-Provider Azure nativo, local-first, via Azure CLI. Não guarda segredos no repositório; usa a sessão oficial da CLI e materializa contexto em `.oxe/cloud/azure/`.
-
-```bash
-# Autenticação
-npx oxe-cc azure auth login [--tenant <entra-tenant-id>]
-npx oxe-cc azure auth set-subscription --subscription "<dev-sub-id>"
-
-# Diagnóstico
-npx oxe-cc azure doctor
-npx oxe-cc azure status
-
-# Inventário
-npx oxe-cc azure sync [--diff]
-npx oxe-cc azure find servicebus [--type servicebus]
-
-# Operações (com --dry-run disponível)
-npx oxe-cc azure servicebus plan --kind namespace --name sb-core --resource-group rg-app --location brazilsouth
-npx oxe-cc azure servicebus apply --kind namespace --name sb-core --resource-group rg-app --location brazilsouth --approve
-```
-
-Princípios: opt-in, discovery via Resource Graph, mutação só com checkpoint formal, evidência persistida e redacted em `.oxe/cloud/azure/operations/`.
-
----
-
-## Concepts-chave
-
-### Context engineering — estado em disco, não no chat
-
-```
-.oxe/
-├── STATE.md              ← índice global: fase, sessão ativa, próximo passo
-├── SESSIONS.md           ← índice de sessões
-├── CAPABILITIES.md       ← catálogo de capabilities instaladas
-├── ACTIVE-RUN.json       ← cursor e estado durável do run atual
-├── OXE-EVENTS.ndjson     ← tracing append-only (populado em todo run)
-├── agent/                ← artefatos de Agent Mode
-├── swarm/                ← artefatos de Swarm Mode
-├── memory/               ← Memory Kernel (cross-session)
-├── learning/             ← Learning Kernel (cross-session)
-├── cloud/azure/          ← profile, auth-status, inventory e operações Azure
-├── global/
-│   ├── LESSONS.md        ← lições prescritivas cumulativas
-│   └── MILESTONES.md     ← marcos globais de entrega
-├── codebase/             ← mapa do repo (stack, estrutura, testes…)
-└── sessions/
-    └── sNNN-slug/
-        ├── spec/         ← SPEC.md, ROADMAP.md, DISCUSS.md, UI-SPEC.md
-        ├── plan/         ← PLAN.md, QUICK.md, blueprints de agentes
-        ├── execution/    ← STATE.md local, OBSERVATIONS.md, DEBUG.md
-        ├── verification/ ← VERIFY.md, VALIDATION-GAPS.md, SECURITY.md
-        ├── checkpoints/
-        ├── research/
-        └── workstreams/
-```
-
-### `/oxe-spec` — spec em 5 fases com auto-reflexão
-
-1. **Perguntas** — blocos de 3-5 por rodada, máximo 3 rodadas
-2. **Pesquisa** — proposta inline na Fase 2 com investigações estruturadas
-3. **Requisitos** — tabela R-ID com v1/v2/fora e critérios A*
-4. **Roteiro** — fases de entrega → `.oxe/ROADMAP.md`
-5. **Auto-reflexão** — detecta contradições, critérios vagos, escopo creep, conflitos com stack
-6. **Aprovação** → instrui `/oxe-plan` ou `/oxe-plan --agents`
-
-A spec lê `.oxe/global/LESSONS.md` e `.oxe/memory/REPO-MEMORY.md` antes de iniciar.
-
-### `/oxe-plan` — test-first com complexidade explícita
-
-Cada tarefa usa a ordem **Verificar → Implementar**:
-```
-Verificar: como saberei que está pronto?   ← definido PRIMEIRO
-Implementar: o mínimo para passar o Verificar
-Complexidade: S | M | L | XL
-```
-
-Tarefas `XL` bloqueiam o gate sem sub-tarefas ou justificativa. `/oxe-obs` propaga automaticamente constraints para R-IDs e Tns afetados.
-
-### Learning loop completo
-
-```
-/oxe-verify completo (ou Swarm Verifier)
-     ↓
-distill.md → detecta padrões do run
-     ↓
-.oxe/learning/CANDIDATES.ndjson
-     ↓
-.oxe/global/LESSONS.md (dedup: Frequência++ se mesma raiz)
-     ↓
-lessons-metrics.json (success_rate, deprecação automática)
-     ↓
-.oxe/learning/PROMOTION-QUEUE.md (skills candidatas → revisão humana)
-     ↓
-/oxe-skill new <id> (promove skill aprovada)
-     ↓
-próximo run: Conductor carrega skill como persona ativa
-```
-
-### Runtime tracking e inspeção no terminal
-
-```bash
-oxe-cc status --full          # health + coverage matrix + readiness gate
-oxe-cc runtime status         # run ativo, cursor, onda atual
-oxe-cc runtime verify         # suite + evidence + manifest + risk ledger
-oxe-cc runtime gates list
-oxe-cc runtime agents --json
-oxe-cc runtime promote --target pr_draft
-```
-
-### Dashboard web — opt-in para revisões de equipe
-
-`oxe-cc dashboard` sobe uma interface web local para revisar o plano antes da execução — indicado para apresentações, operação de gates e revisões em equipe. Lê os artefatos OXE reais (não é uma segunda fonte de verdade). Inclui: ciclo principal, mapa de artefatos, active run, trace log, trilha de ondas, handoffs, checkpoints, agentes, evidências, gates e promotion state.
-
----
-
-## Instalação
-
-**Requisito:** Node.js 18+
-
-```bash
-npx oxe-cc@latest
-```
-
-**Confirmar que funcionou:**
-
-| IDE | Comando |
-|-----|---------|
-| Cursor | `/oxe` |
-| Copilot (VS Code) | `/oxe` (requer `"chat.promptFiles": true`) |
-| Claude Code | `/oxe` ou `oxe` |
-| Gemini CLI | `/oxe` após `/commands reload` |
-| Codex | `/prompts:oxe` |
-
-<details>
-<summary><strong>Flags de instalação</strong></summary>
-
-| Flag | Efeito |
-|------|--------|
-| `--cursor` / `--copilot` | Só uma das stacks da IDE |
-| `--copilot-cli` | Skills globais do Copilot CLI em `~/.copilot/skills/` |
-| `--all-agents` | Cursor + Copilot + Claude + OpenCode + Gemini + Codex + Windsurf + Antigravity |
-| `--global` | Layout clássico: `oxe/` na raiz + `.oxe/` |
-| `--local` | Layout mínimo, só `.oxe/` (padrão) |
-| `--ide-local` | Instala integração no próprio repositório |
-| `--ide-global` | Instala integração no HOME do utilizador |
-| `--force` / `-f` | Sobrescreve arquivos existentes (use para atualizar) |
-| `--dry-run` | Lista ações sem escrever |
-| `--oxe-only` | Só workflows em `.oxe/`, sem integrações IDE |
-| `--no-global-cli` / `-l` | Não instala `oxe-cc` globalmente (útil em CI) |
-| `OXE_NO_PROMPT=1` | Modo não-interativo (CI) |
-
-</details>
-
-<details>
-<summary><strong>Atualizar e desinstalar</strong></summary>
-
-```bash
-npx oxe-cc@latest --force        # atualizar workflows
-npx oxe-cc update --check        # verificar versão sem atualizar
-npx oxe-cc uninstall --ide-only  # remove integrações (mantém .oxe/)
-```
-
-</details>
-
-<details>
-<summary><strong>Desenvolvimento (contribuir)</strong></summary>
-
-```bash
-git clone https://github.com/propagno/oxe-build.git
-cd oxe-build
-npm test          # suíte completa: root + runtime TypeScript
-npm run scan:assets
-node bin/oxe-cc.js --help
-```
-
-</details>
-
----
-
-## CLI (`oxe-cc`)
-
-| Comando | O que faz |
-|---------|-----------|
-| `oxe-cc` / `oxe-cc install` | Instala workflows e integrações |
-| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, contratos semânticos, config, sessão ativa, saúde lógica (`healthy` \| `warning` \| `broken`) |
-| `oxe-cc doctor --release --write-manifest` | Gate de publicação: valida árvore canónica, `workflow-runtime-contracts.json`, versões, CHANGELOG, runtime compilado; persiste `release-manifest.json` |
-| `oxe-cc status` | Próximo passo sugerido + saúde lógica |
-| `oxe-cc status --full` | Coverage matrix + readiness gate + active run (ANSI) |
-| `oxe-cc status --json` | Estado completo em JSON (schema v5): workspaceMode, healthStatus, activeSession, planSelfEvaluation, contextQuality, semanticsDrift, verificationSummary, pendingGates, multiAgent, promotionSummary e mais |
-| `oxe-cc context build` | Gera context pack em `.oxe/context/packs/` por contrato de workflow |
-| `oxe-cc context inspect` | Inspeciona context pack sem escrita |
-| `oxe-cc update` | Atualiza workflows para a versão mais recente |
-| `oxe-cc init-oxe` | Bootstrap do `.oxe/` |
-| `oxe-cc dashboard` | Interface web local para revisão, comentários e aprovação |
-| `oxe-cc runtime <status\|start\|pause\|resume\|replay\|compile\|verify\|project\|ci\|promote\|recover\|gates\|agents>` | Controla o runtime enterprise |
-| `oxe-cc runtime gates <list\|show\|resolve>` | Lista, inspeciona e resolve gates operacionais |
-| `oxe-cc runtime agents status` | Ownership, handoffs, heartbeats e failover multi-agent |
-| `oxe-cc runtime promote --target pr_draft` | Promoção remota governada por verify, gates, risk e coverage |
-| `oxe-cc runtime recover` | Reidrata journal, gates, evidence e estado canónico |
-| `oxe-cc capabilities <list\|install\|remove\|update>` | Mantém catálogo de capabilities em `.oxe/` |
-| `oxe-cc plugins <list\|install\|remove>` | Gerencia plugins de lifecycle |
-| `oxe-cc uninstall` | Remove integrações OXE |
-| `oxe-cc uninstall --global-cli` | Também remove o pacote npm global |
-
----
-
-## Configuração
-
-Arquivo `.oxe/config.json`. Principais opções:
-
-| Chave | Padrão | Descrição |
-|-------|--------|-----------|
-| `profile` | `"balanced"` | `strict` / `balanced` / `fast` / `legacy` |
-| `verification_depth` | `"standard"` | `"thorough"` ativa gaps automático no verify |
-| `plan_confidence_threshold` | `90` | Limiar para `execute` aceitar um `PLAN.md` |
-| `security_in_verify` | `false` | `true` ativa OWASP automático no verify |
-| `discuss_before_plan` | `false` | Exige aprovação de decisões antes do plano |
-| `scale_adaptive` | `true` | Scan sugere o profile pelo tamanho do projeto |
-| `plugins` | `[]` | Hooks de lifecycle em `.oxe/plugins/*.cjs` |
-| `permissions` | `[]` | Regras glob+ação para gate de arquivos em execute/apply |
-| `runtime.quotas.*` | `Infinity` | Limites enterprise para work items, mutações e retries por run |
-
----
-
-## SDK
-
-```js
-const oxe = require('oxe-cc');
-
-const plan  = oxe.parsePlan(fs.readFileSync('.oxe/PLAN.md', 'utf8'));
-const spec  = oxe.parseSpec(fs.readFileSync('.oxe/SPEC.md', 'utf8'));
-const state = oxe.parseState(fs.readFileSync('.oxe/STATE.md', 'utf8'));
-
-const fidelity = oxe.validateDecisionFidelity(discussMd, planMd);
-const result   = oxe.runDoctorChecks({ projectRoot: process.cwd() });
-
-async function verifyActiveRun() {
-  return oxe.verifyRun?.({
-    projectRoot: process.cwd(),
-    runId: 'oxe-run-123',
-    workItemId: 'T1',
-    cwd: process.cwd(),
-  });
-}
-```
-
-O SDK reexporta bridges do runtime enterprise: `verifyRun`, `operational.buildRuntimePluginRegistry`, `operational.readRuntimeGates`, `operational.resolveRuntimeGate`, `operational.runRuntimeVerify`, `operational.runRuntimePromotion`, `operational.recoverRuntimeState`.
-
-TypeScript: [`lib/sdk/index.d.ts`](lib/sdk/index.d.ts) · Docs: [`lib/sdk/README.md`](lib/sdk/README.md)
-
----
-
-## Critérios de publicação
-
-O pacote está pronto para publicação quando estes sinais estiverem verdes:
-
-```bash
-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: `release-manifest.json`, `runtime-smoke-report.json`, `runtime-real-report.json`, `recovery-fixture-report.json`, `multi-agent-soak-report.json`, `multi-agent-real-report.json` em `.oxe/release/`.
-
----
-
-## Resolução de problemas
-
-| Situação | O que tentar |
-|----------|-------------|
-| Comandos não aparecem no Cursor | Confirme `~/.cursor/commands/`; reinicie o Cursor |
-| `/oxe-*` não aparecem no Copilot | Ative `"chat.promptFiles": true`; confirme `.github/prompts/` e `.github/copilot-instructions.md` |
-| Copilot responde fora do workflow OXE | `npx oxe-cc doctor`; se houver blocos mistos de outros frameworks, `npx oxe-cc uninstall --copilot-legacy-clean` |
-| Runtime não responde com nova semântica | Verifique drift entre `oxe/workflows/` e prompts instalados; `npm run sync:runtime-metadata` |
-| Arquivos não atualizam | `npx oxe-cc@latest --force` |
-| `ETARGET` / versão não encontrada | `npm cache clean --force` |
-| Erro no WSL sobre Node | Use Node instalado dentro do WSL |
-
-`oxe-cc --help` · `oxe-cc doctor` · `OXE_NO_BANNER=1` desativa o banner
-
----
-
-## Licença
-
-[MIT](LICENSE)
+<div align="center">
+
+<p align="center">
+  <img src="assets/readme-banner.svg" alt="OXE — Orchestrated eXperience Engineering" width="920" />
+</p>
+
+[![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)
+
+**Framework OXE — Orchestrated eXperience Engineering**
+
+Desenvolvimento assistido por IA com especificação, contexto persistente, execução rastreável e verificação por evidências — independente da IDE ou do agente.
+
+```bash
+npx oxe-cc@latest
+```
+
+**Versão:** `1.16.0` · **Node.js:** `>=18`
+
+</div>
+
+---
+
+## Por que o OXE existe
+
+Agentes de IA escrevem código rapidamente, mas velocidade sem método costuma gerar quatro problemas: contexto perdido entre conversas, requisitos implícitos, mudanças difíceis de auditar e uma falsa sensação de conclusão porque “o código parece pronto”.
+
+O OXE adiciona uma camada de engenharia entre a intenção humana e a execução do agente:
+
+```text
+objetivo
+   ↓
+contexto e decisões persistidos em .oxe/
+   ↓
+spec → plan → execute → verify
+   ↓
+código + evidências + aprendizado para o próximo ciclo
+```
+
+O framework não substitui a IDE, o modelo ou o processo da equipe. Ele oferece um protocolo comum para que Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf e outros runtimes trabalhem sobre o mesmo estado canônico.
+
+### O que muda na prática
+
+| Sem uma camada de método | Com OXE |
+|---|---|
+| O contexto fica preso no chat | Estado e decisões ficam em `.oxe/` |
+| Cada agente interpreta a demanda de um jeito | Workflows canônicos definem o contrato de cada etapa |
+| O plano descreve tarefas, mas não prova conclusão | Cada tarefa nasce com uma forma explícita de verificar |
+| Trocar de IDE significa recomeçar a explicação | As integrações projetam o mesmo núcleo para cada runtime |
+| “Terminou” significa apenas que o código foi gerado | `verify` exige critérios, evidências, integração e riscos |
+| Erros e decisões se perdem entre ciclos | Memory e Learning Kernel alimentam os próximos planos |
+
+### Benefícios esperados
+
+- **Menos reexplicação:** o agente reconstrói contexto a partir de artefatos pequenos e selecionados por workflow.
+- **Escopo mais previsível:** requisitos, decisões e exclusões são registrados antes da mutação.
+- **Execução auditável:** runs, eventos, checkpoints, gates e evidências formam uma trilha operacional.
+- **Verificação independente:** o resultado é confrontado com critérios de aceite, não apenas com o plano produzido.
+- **Portabilidade:** o método permanece igual mesmo quando a equipe troca de IDE, CLI ou modelo.
+- **Escala proporcional:** tarefas pequenas usam um fluxo lean; entregas complexas ganham sessões, ondas e agentes especializados.
+
+---
+
+## Evidência operacional do projeto
+
+O OXE procura demonstrar suas próprias promessas no pipeline do repositório. O snapshot abaixo vem da validação local registrada em **18 de julho de 2026**; não representa métricas de adoção externa ou produtividade humana.
+
+| Indicador verificável | Resultado |
+|---|---:|
+| Quality gates obrigatórios | **10/10 aprovados** |
+| Testes raiz validados no Node 18 | **628/628** |
+| Testes do runtime TypeScript | **384/384** |
+| Cenários smoke, runtime real, recovery e multiagente | **30/30** |
+| Cobertura de linhas/statements | **83,05%** |
+| Cobertura de funções | **92,48%** |
+| Cobertura de branches | **61,76%** |
+| Vulnerabilidades reportadas por `npm audit` | **0** |
+| Participantes ativados em VS Code Extension Host real | **13/13** |
+| Arquivos validados no tarball npm | **507** |
+
+Esses números são recalculados pelos gates do repositório. Consulte [QUALITY-GATES.md](docs/QUALITY-GATES.md) e [RELEASE-READINESS.md](docs/RELEASE-READINESS.md) para o contrato completo. Métricas de produto devem ser interpretadas como sinais: cobertura não substitui bons critérios, contagem de testes não mede valor entregue e número de agentes não equivale a produtividade.
+
+---
+
+## Comece em cinco minutos
+
+### 1. Instale no projeto
+
+```bash
+cd meu-projeto
+npx oxe-cc@latest
+```
+
+O instalador cria um `.oxe/` enxuto e adiciona as integrações escolhidas. Artefatos como `SPEC.md`, `PLAN.md`, runs, sessões e mapas nascem sob demanda.
+
+### 2. Confirme a saúde
+
+```bash
+npx oxe-cc doctor
+npx oxe-cc status --full
+```
+
+### 3. Entregue um objetivo
+
+```text
+/oxe adicionar importação de CSV com validação e histórico
+```
+
+O Conductor classifica a complexidade, recupera contexto, seleciona personas e escolhe entre execução individual e Swarm Mode.
+
+### 4. Ou controle o ciclo manualmente
+
+```text
+/oxe-spec
+/oxe-plan
+/oxe-execute
+/oxe-verify
+```
+
+Ao terminar, o projeto contém não só a implementação, mas também os requisitos, decisões, evidências e lições que explicam como ela foi construída.
+
+---
+
+## Escolha o fluxo certo
+
+### Nano — mudança pequena e isolada
+
+```text
+/oxe-quick → objetivo → passos curtos → implementação → verify
+```
+
+Use para texto, configuração, estilo, teste pontual ou bug local. O Quick evita SPEC e PLAN longos, mas preserva objetivo e verificação. Promova para o ciclo Standard quando surgirem API pública, segurança, muitos arquivos ou mais de dois domínios.
+
+### Standard — padrão para features e refatorações
+
+```text
+/oxe → /oxe-spec → /oxe-plan → /oxe-execute → /oxe-verify
+```
+
+É o fluxo recomendado para a maioria das entregas. A spec define o problema, o plan converte critérios em tarefas verificáveis, o execute implementa com tracking e o verify fecha o ciclo por evidência.
+
+### Full — entregas complexas ou de equipe
+
+```text
+/oxe-session new <nome>
+  → /oxe-spec --full --research
+  → /oxe-plan --agents
+  → /oxe-execute por onda
+  → /oxe-dashboard
+  → /oxe-verify --gaps --security --pr
+  → /oxe-session close
+```
+
+Use quando existirem três ou mais domínios, trabalho paralelo, risco operacional, modernização brownfield ou necessidade de aprovação intermediária.
+
+### Guia rápido de decisão
+
+| Situação | Fluxo sugerido |
+|---|---|
+| Correção local bem compreendida | `/oxe-quick` |
+| Nova feature ou refatoração relevante | ciclo Standard |
+| UI com contrato visual | `/oxe-spec --ui` → ciclo Standard → `/oxe-verify --ui` |
+| Segurança, autenticação ou dados sensíveis | profile `strict` + `--research` + `--security` |
+| Bug intermitente durante execução | `/oxe-execute --debug` |
+| Falha persistente após tentativas | `/oxe-execute --deep-diagnosis` |
+| Modernização de legado | sessão + `--full --research` + execução por onda |
+| Revisão antes do merge | `/oxe-verify --pr --gaps` |
+| Trabalho simultâneo em frentes diferentes | `/oxe-session workstream new <nome>` |
+| Não sei onde o ciclo parou | `/oxe` ou `oxe-cc status --full` |
+
+---
+
+## A trilha principal
+
+São seis comandos para o uso cotidiano:
+
+| Comando | Responsabilidade |
+|---|---|
+| `/oxe` | Entrada universal: situação, ajuda, pergunta contextual ou objetivo autônomo |
+| `/oxe-quick` | Demanda pequena com miniobjetivo, passos e verificação |
+| `/oxe-spec` | Perguntas → pesquisa opcional → requisitos → roteiro → aprovação |
+| `/oxe-plan` | Plano test-first por ondas; `--agents` gera blueprint multiagente |
+| `/oxe-execute` | Implementação completa, por onda ou por tarefa, com runtime tracking |
+| `/oxe-verify` | Critérios, evidências, integração, riscos, UAT e retrospectiva |
+
+### Flags que absorvem fluxos especializados
+
+```text
+/oxe-spec --refresh           atualiza o mapa do codebase
+/oxe-spec --full              força scan completo
+/oxe-spec --research          pesquisa ou spike técnico
+/oxe-spec --deep              aumenta profundidade da investigação
+/oxe-spec --ui                produz UI-SPEC
+
+/oxe-execute --note "texto"   registra observação contextual
+/oxe-execute --debug          diagnóstico técnico inline
+/oxe-execute --deep-diagnosis investigação pós-falha persistente
+/oxe-execute --checkpoint "x" snapshot nomeado
+/oxe-execute --iterative      retries controlados por onda
+
+/oxe-verify --gaps            auditoria de cobertura dos critérios
+/oxe-verify --security        auditoria OWASP aderente ao stack
+/oxe-verify --ui              compara implementação com UI-SPEC
+/oxe-verify --pr              revisão do PR/diff
+/oxe-verify --diff A...B      revisão de intervalo específico
+/oxe-verify --skip-retro      não gera retrospectiva ao fechar
+```
+
+Os antigos comandos `scan`, `research`, `debug`, `forensics`, `checkpoint`, `security`, `ui-review`, `review-pr` e `retro` continuam reconhecidos, mas os estágios acima são a interface preferencial.
+
+---
+
+## Modo autônomo e agentes dinâmicos
+
+Quando recebe `/oxe <objetivo>`, o Conductor aplica uma heurística explícita:
+
+| Complexidade | Sinal típico | Modo |
+|---|---|---|
+| simples | 1 domínio e até 3 arquivos esperados | Agent Mode |
+| média | 1–2 domínios e aproximadamente 3–8 arquivos | Agent Mode |
+| complexa | 3+ domínios, 8+ arquivos ou integração transversal | Swarm Mode |
+
+### Agent Mode
+
+O próprio Conductor executa a demanda com a persona adequada. A sessão fica registrada em `.oxe/agent/AGENT-SESSION.json` e passa por verificação antes de fechar.
+
+### Swarm Mode
+
+O trabalho é decomposto em tarefas e ondas. Agentes recebem papéis específicos, ownership de arquivos, dependências e `model_hint`. Um reviewer adversarial e um verifier independente avaliam a integração. O run fica em `.oxe/swarm/<run-id>/`.
+
+### Personas builtin
+
+`executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist` e `db-specialist`. Personas customizadas podem ser adicionadas em `.oxe/personas/`.
+
+O princípio é **Plan-Driven Dynamic Agents**: os agentes derivam do plano da demanda atual e são invalidados ao terminar. Eles não são uma equipe genérica permanente.
+
+---
+
+## Como o OXE mantém contexto sem inflar o prompt
+
+### Estado canônico em disco
+
+`.oxe/STATE.md` é a porta de entrada curta. Os demais artefatos aparecem quando necessários:
+
+```text
+.oxe/
+├── STATE.md                 fase e próximo passo
+├── config.json              profile e políticas
+├── SPEC.md                  requisitos e critérios
+├── PLAN.md                  ondas, tarefas e verificação
+├── VERIFY.md                evidências e resultado
+├── context/packs/           contexto selecionado por workflow
+├── runs/                    estado operacional e journal
+├── sessions/                ciclos isolados
+├── memory/                  memória persistente
+├── swarm/                   coordenação multiagente
+└── release/                 evidências dos gates de publicação
+```
+
+Use `oxe-cc map` para distinguir o que já existe do que será criado sob demanda.
+
+### Context Engine
+
+Cada workflow declara artefatos obrigatórios, opcionais, tier de contexto e política de freshness. O engine seleciona e comprime apenas o necessário:
+
+```bash
+oxe-cc context build --workflow plan
+oxe-cc context inspect --workflow verify --json
+```
+
+### Memory e Learning Kernel
+
+Memória de repositório, decisões, observações e lições são recuperadas antes de novos runs. Ao final do `verify`, a retrospectiva automática destila padrões úteis e evita que o próximo ciclo dependa da lembrança de uma conversa antiga.
+
+---
+
+## Runtime enterprise: execução como estado, não como narrativa
+
+Em `execute` e `verify`, o caminho recomendado é runtime-first. O runtime compila SPEC e PLAN para um grafo formal, registra transições e depois projeta Markdown para leitura humana.
+
+```text
+SPEC + PLAN
+   ↓ runtime compile
+ExecutionGraph + verification suite
+   ↓ execute / events / gates
+ACTIVE-RUN + journal + evidence
+   ↓ runtime verify
+verification manifest + risk ledger
+   ↓ project
+VERIFY.md e demais projeções
+```
+
+Comandos principais:
+
+```bash
+oxe-cc runtime status
+oxe-cc runtime compile
+oxe-cc runtime execute
+oxe-cc runtime verify
+oxe-cc runtime gates list
+oxe-cc runtime recover
+oxe-cc runtime promote --target pr_draft
+```
+
+Isso permite pausar, retomar, repetir uma onda, recuperar um journal interrompido e exigir aprovação formal sem depender do histórico do chat.
+
+---
+
+## Sessões, workstreams e milestones
+
+Sessões isolam ciclos longos e evitam colisão entre artefatos:
+
+```text
+/oxe-session new checkout
+/oxe-session status
+/oxe-session switch sessions/s002-checkout
+/oxe-session close
+```
+
+Workstreams organizam frentes paralelas; milestones agrupam entregas maiores:
+
+```text
+/oxe-session workstream new backend
+/oxe-session workstream switch frontend
+/oxe-session milestone new beta
+/oxe-session milestone audit
+```
+
+Para trabalho diário, `oxe-cc status --full` é a inspeção preferencial. O `oxe-cc dashboard` é opt-in para revisão visual de planos, ondas, agentes, checkpoints, gates e evidências.
+
+---
+
+## Instalação por ambiente
+
+### Instalação padrão
+
+```bash
+npx oxe-cc@latest
+```
+
+### Todas as integrações suportadas
+
+```bash
+npx oxe-cc@latest --all-agents
+```
+
+| Ambiente | Superfície instalada/invocação |
+|---|---|
+| Cursor | comandos em `~/.cursor/commands/`; use `/oxe` |
+| GitHub Copilot no VS Code | `.github/copilot-instructions.md` + `.github/prompts/`; habilite `chat.promptFiles` |
+| Copilot CLI | skills em `~/.copilot/skills/`; recarregue com `/skills reload` |
+| Claude Code | comandos em `~/.claude/commands/` |
+| OpenCode | comandos nas pastas de configuração OpenCode |
+| Gemini CLI | comandos em `~/.gemini/commands/`; use `/commands reload` |
+| Codex | skills em `~/.agents/skills` e prompts em `~/.codex/prompts` |
+| Windsurf | workflows globais do Windsurf |
+| Antigravity | skills na árvore do Gemini Antigravity |
+
+Flags relevantes:
+
+| Flag | Uso |
+|---|---|
+| `--cursor`, `--copilot`, `--copilot-cli` | instala uma integração específica |
+| `--opencode`, `--gemini`, `--codex`, `--windsurf`, `--antigravity` | instala somente o runtime indicado |
+| `--ide-local` | mantém integrações suportadas dentro do repositório |
+| `--ide-global` | instala integrações no HOME do usuário |
+| `--local` | layout mínimo em `.oxe/` |
+| `--global` | layout clássico com `oxe/` canônico na raiz |
+| `--oxe-only` | instala o núcleo sem integrações de IDE |
+| `--dry-run` | mostra as alterações sem gravar |
+| `--force` | atualiza/sobrescreve artefatos gerenciados |
+
+CI sem interação:
+
+```bash
+OXE_NO_PROMPT=1 npx oxe-cc@latest --oxe-only --no-global-cli
+```
+
+Atualização e remoção:
+
+```bash
+npx oxe-cc update --check
+npx oxe-cc update --if-newer
+npx oxe-cc uninstall --ide-only
+npx oxe-cc uninstall --global-cli
+```
+
+No WSL, use uma instalação do Node dentro do próprio WSL.
+
+---
+
+## Profiles de execução
+
+Defina `profile` em `.oxe/config.json`:
+
+| Profile | Indicado para | Comportamento |
+|---|---|---|
+| `balanced` | maioria das features | cerimônia e verificação moderadas |
+| `fast` | manutenção de baixo risco | menos discussão e verificação rápida |
+| `strict` | segurança, API pública, dados e releases | discussão, verificação profunda e UAT |
+| `legacy` | brownfield e stacks pouco conhecidas | investigação e verificação thorough |
+
+```json
+{
+  "profile": "strict",
+  "security_in_verify": true,
+  "plan_confidence_threshold": 90,
+  "runtime": {
+    "quotas": {
+      "max_retries_per_task": 2
+    }
+  }
+}
+```
+
+Chaves explícitas prevalecem sobre os defaults do profile.
+
+---
+
+## Capabilities, plugins e Azure
+
+Capabilities são extensões nativas declarativas do projeto:
+
+```bash
+oxe-cc capabilities list
+oxe-cc capabilities install <id>
+oxe-cc capabilities update
+```
+
+Plugins adicionam hooks de lifecycle. A instalação via CLI aceita somente pacotes npm validados; plugins por path devem ser criados e referenciados explicitamente no `config.json`:
+
+```bash
+oxe-cc plugins list
+oxe-cc plugins install <pacote> [versão]
+```
+
+O provider Azure é local-first e usa Azure CLI, inventário materializado, dry-run e checkpoint antes de mutações:
+
+```bash
+oxe-cc azure auth login --tenant <tenant-id>
+oxe-cc azure auth set-subscription --subscription <dev-sub-id>
+oxe-cc azure sync --diff
+oxe-cc azure find api --type servicebus
+oxe-cc azure operations list
+```
+
+---
+
+## CLI de referência
+
+| Comando | Função |
+|---|---|
+| `oxe-cc install` | instala núcleo e integrações |
+| `oxe-cc doctor` | valida estrutura, configuração e saúde lógica |
+| `oxe-cc doctor --release --write-manifest` | executa o gate de release e grava o manifesto |
+| `oxe-cc status --full` | mostra próximo passo, coverage matrix e active run |
+| `oxe-cc status --json` | saída estruturada para hosts e CI |
+| `oxe-cc map --json` | catálogo dos artefatos existentes e lazy |
+| `oxe-cc context build\|inspect` | produz ou inspeciona context packs |
+| `oxe-cc events --tail 50 --json` | lê eventos operacionais incrementalmente |
+| `oxe-cc dashboard` | inicia a interface web local |
+| `oxe-cc runtime ...` | controla compile, execute, verify, gates, recovery e promotion |
+| `oxe-cc update` | atualiza os artefatos gerenciados |
+| `oxe-cc uninstall` | remove integrações e, conforme flags, o núcleo |
+
+Ajuda completa:
+
+```bash
+npx oxe-cc@latest --help
+```
+
+---
+
+## SDK para automação
+
+O mesmo núcleo pode ser consumido programaticamente:
+
+```js
+const oxe = require('oxe-cc');
+
+const health = oxe.runDoctorChecks({ projectRoot: process.cwd() });
+const plan = oxe.parsePlan(planMarkdown);
+const spec = oxe.parseSpec(specMarkdown);
+
+if (!health.ok || !oxe.validateDecisionFidelity(discussMarkdown, planMarkdown).ok) {
+  process.exitCode = 1;
+}
+```
+
+O SDK também expõe bridges operacionais para runtime, gates, verificação, promotion e recovery. Tipos: [index.d.ts](lib/sdk/index.d.ts) · fonte das declarações: [index.types.ts](lib/sdk/index.types.ts) · [documentação do SDK](lib/sdk/README.md).
+
+---
+
+## Uso em equipe
+
+Uma adoção saudável costuma seguir três estágios:
+
+1. **Individual:** `/oxe-quick`, ciclo Standard e `status --full`.
+2. **Equipe:** profiles compartilhados, sessões, revisão de SPEC/PLAN e dashboard.
+3. **Governado:** runtime-first, gates formais, CI, evidências de release e promotion controlada.
+
+Métricas úteis para acompanhar a adoção:
+
+| Dimensão | Métrica recomendada | Interpretação |
+|---|---|---|
+| Fluxo | ciclos que terminam em `verify_complete` | mede fechamento, não apenas início |
+| Requisitos | critérios A* com evidência | revela cobertura real da entrega |
+| Planejamento | tarefas com comando de verificação | mede executabilidade do plano |
+| Qualidade | gaps e riscos residuais por ciclo | mostra onde o método ainda é frágil |
+| Operação | retries, gates e recoveries por run | indica instabilidade ou políticas excessivas |
+| Aprendizado | lições reutilizadas em ciclos posteriores | mede memória útil, não volume de documentação |
+| Eficiência | tempo por gate e por onda | ajuda a localizar gargalos sem premiar pressa |
+
+Não use quantidade de prompts, agentes ou linhas geradas como métrica isolada de sucesso. O objetivo é reduzir retrabalho e aumentar confiança na entrega.
+
+Guias: [adoção por papéis](docs/ROLES.md) · [adoção em equipe](docs/TEAM-ADOPTION.md) · [walkthrough](docs/WALKTHROUGH.md) · [playbook de incidentes](docs/INCIDENT-PLAYBOOK.md).
+
+---
+
+## Desenvolvimento e qualidade do próprio OXE
+
+```bash
+git clone https://github.com/propagno/oxe-build.git
+cd oxe-build
+npm ci
+npm test
+```
+
+O repositório usa um único lockfile e npm workspaces para raiz, runtime e extensão.
+
+Gates principais:
+
+```bash
+npm run lint
+npm run format:check
+npm run test:sdk-types
+npm run test:coverage
+npm run test:packed-consumer
+npm run test:vscode-ext
+npm audit
+npm run scan:assets
+npm run build:vscode-ext
+npm run release:manifest
+npm run release:pack-check
+npm run quality:report
+```
+
+O consumidor empacotado instala o tarball em um projeto temporário limpo e valida CLI, SDK, runtime e TypeScript. O teste da extensão ativa os 13 participantes em um VS Code Extension Host real. O ratchet de cobertura impede regressão dos pisos globais e dos módulos críticos.
+
+O pipeline de release usa GitHub Actions fixadas por SHA, valida correspondência entre tag e versão e produz o VSIX antes de criar a GitHub Release. A publicação no npm é uma promoção manual e separada, executada pelo mantenedor depois da aprovação da release.
+
+---
+
+## Solução de problemas
+
+| Sintoma | Diagnóstico sugerido |
+|---|---|
+| Não sei qual é o próximo passo | `npx oxe-cc status --full` |
+| Workflows ausentes ou incoerentes | `npx oxe-cc doctor` |
+| Comandos não aparecem no Cursor | confira `~/.cursor/commands/` e reinicie a IDE |
+| Prompts não aparecem no Copilot | habilite `"chat.promptFiles": true` e confira `.github/prompts/` |
+| Copilot CLI não atualizou skills | execute `/skills reload` |
+| Gemini não atualizou comandos | execute `/commands reload` |
+| Context pack está stale | `oxe-cc context build --workflow <slug>` |
+| Execute falha repetidamente | `/oxe-execute --deep-diagnosis` |
+| Runtime interrompido | `oxe-cc runtime recover` |
+| `npx` usa uma versão antiga | `npx clear-npx-cache` e repita com `@latest` |
+
+---
+
+## Documentação complementar
+
+- [Quickstart](QUICKSTART.md)
+- [Walkthrough completo](docs/WALKTHROUGH.md)
+- [Papéis e responsabilidades](docs/ROLES.md)
+- [Adoção em equipe](docs/TEAM-ADOPTION.md)
+- [Matriz de cenários do runtime](docs/RUNTIME-SMOKE-MATRIX.md)
+- [Quality gates](docs/QUALITY-GATES.md)
+- [Release readiness](docs/RELEASE-READINESS.md)
+- [SDK](lib/sdk/README.md)
+- [Workflows canônicos](oxe/workflows/)
+- [Referência brownfield](oxe/workflows/references/legacy-brownfield.md)
+
+---
+
+## Princípios de uso
+
+1. Comece por `/oxe`; aumente a estrutura apenas quando o risco exigir.
+2. Trate `.oxe/` como estado do trabalho, não como documentação decorativa.
+3. Defina como verificar antes de implementar.
+4. Prefira runtime-first para `execute` e `verify`.
+5. Não encerre um ciclo sem evidência ou risco residual explícito.
+6. Use agentes por domínio e por demanda; não por disponibilidade.
+7. Faça o próximo ciclo aprender com o anterior.
+
+---
+
+## Licença
+
+[MIT](LICENSE)