oxe-cc 1.12.0 → 1.16.0

package/docs/INTEGRATION.md

@@ -0,0 +1,182 @@
+# Integração com hosts (IDEs, OXESpace, …)
+
+Este documento descreve o **contrato estável** que o `oxe-cc` expõe para um *host* — um app que embute o oxe-cc e mostra o estado de um projeto OXE (ex.: o [OXESpace](https://github.com/propagno) embute o painel OXE).
+
+O `oxe-cc` e o host têm **releases independentes**. Para que evoluam sem se quebrar:
+
+- Toda saída de máquina é **versionada** com um campo `oxe*Schema` próprio (independente da versão do pacote).
+- Os campos são **aditivos**: campos novos podem aparecer; campos existentes não mudam de tipo nem somem dentro da mesma `*Schema`.
+- O host deve **degradar graciosamente**: detectar a versão / o schema e usar o caminho antigo quando um recurso novo não existir.
+
+Detecte a versão com `oxe --version` (imprime `oxe-cc vX.Y.Z`). Tabela de disponibilidade:
+
+| Recurso | Desde | Schema |
+|---|---|---|
+| `status --json` (completo) | 1.0 | `oxeStatusSchema: 5` |
+| `status --json --summary` | 1.13.0 | `oxeSummarySchema: 1` |
+| `agentSkills[]` no `status --json` + `agentSkills` no summary | 1.13.0 | — |
+| `events --tail --json` | 1.14.0 | `oxeEventsSchema: 1` |
+| `dashboard --json` + `--port 0` efêmero | 1.14.0 | `oxeDashboardSchema: 1` |
+| `map --json` (mapa de artefatos do `.oxe/`) | 1.15.0 | `oxeMapSchema: 1` |
+
+> **Estável:** `status --json --summary`, `agentSkills`, `events --json`, `dashboard --json`, `map --json`.
+> **Experimental (pode mudar):** o conteúdo de `payload` dentro de cada evento; o HTML servido pelo dashboard; o corpo de `status --json` completo (`oxeStatusSchema`) além dos campos listados abaixo.
+
+---
+
+## 1. Glance barato — `status --json --summary`
+
+Em vez do `status --json` completo (~100KB), use a projeção compacta no *hot path* (atualizações frequentes):
+
+```bash
+oxe status --json --summary --dir <projeto>
+```
+
+```jsonc
+{
+  "oxeSummarySchema": 1,
+  "projectRoot": "/abs/path",
+  "workspaceMode": "oxe_project",
+  "phase": "execute",
+  "healthStatus": "warning",
+  "activeSession": "sessions/s003-foo",
+  "nextStep": "execute",
+  "cursorCmd": "/oxe-execute",
+  "reason": "…",
+  "eventsCount": 42,
+  "warningsCount": 7,
+  "agentSkills": [ { "agent": "copilot-cli", "skillsInstalled": false } ]
+}
+```
+
+O `status --json` completo (`oxeStatusSchema: 5`) continua disponível para a vista detalhada (diagnósticos, `criticalExecutionGaps`, `planSelfEvaluation`, artefatos, `agentSkills[]` detalhado).
+
+---
+
+## 2. Skills por-agente — `agentSkills`
+
+O summary traz um `agentSkills` compacto (`{ agent, skillsInstalled }`). O `status --json` completo traz a forma detalhada:
+
+```jsonc
+{
+  "agent": "copilot-cli",        // copilot-vscode | codex | copilot-cli | cursor | …
+  "detected": true,               // o agente está configurado neste ambiente
+  "skillsInstalled": false,       // as skills /oxe-* estão instaladas neste workspace
+  "skillsPath": "/abs/.../skills",
+  "status": "no_skills",
+  "issues": ["…"]                 // por que falhou (caminho ausente, frontmatter, versão)
+}
+```
+
+Via SDK, sem shell: `require('oxe-cc').health.agentSkillsReport(target)`.
+
+**Uso típico do host:** se algum agente relevante tem `skillsInstalled:false`, ofereça instalar as skills daquele agente **antes** de lançá-lo (resolve o "Failed to load N skills"). Hoje o host dispara a instalação via os comandos `install` do oxe-cc (no terminal); uma saída `install --json` silenciosa está planejada (ver §5).
+
+---
+
+## 3. Reatividade — observar eventos
+
+O `oxe-cc` mantém um log **append-only** em:
+
+```
+.oxe/OXE-EVENTS.ndjson                                  # projeto sem sessão ativa
+.oxe/<session>/execution/OXE-EVENTS.ndjson              # quando há sessão ativa (ex.: sessions/s003-foo)
+```
+
+Cada linha é um JSON (NDJSON). Campos estáveis por evento:
+
+```jsonc
+{
+  "event_id": "evt-...",      // único; use como cursor em --since
+  "type": "RunStarted",       // RunStarted, WorkItemReady, ToolInvoked, GateRequested, RunCompleted, …
+  "timestamp": "2026-05-30T10:00:00.000Z",
+  "run_id": "run-1" | null,
+  "session_id": "sessions/s003-foo" | null,
+  "wave_id": 1 | null,
+  "task_id": "T1" | null,
+  "payload": { /* experimental — específico do tipo */ }
+}
+```
+
+**Padrão recomendado (reativo + barato):**
+
+1. O host faz `fs.watch` do `OXE-EVENTS.ndjson` (com debounce ~400ms).
+2. A cada mudança, re-chama `status --json --summary` para atualizar a UI.
+3. Um poll lento de segurança (~15s) cobre o caso de o watch falhar (rede/symlink).
+
+Para **ler os eventos** sem reparsear o arquivo inteiro, use o comando read-only:
+
+```bash
+oxe events --tail 50 --json --dir <projeto>
+oxe events --since evt-abc123 --json --dir <projeto>   # só os novos desde um event_id
+```
+
+```jsonc
+{
+  "oxeEventsSchema": 1,
+  "projectRoot": "/abs/path",
+  "activeSession": "sessions/s003-foo" | null,
+  "summary": { "total": 3, "byType": { "RunStarted": 1, "…": 1 }, "lastEvent": { /* … */ } },
+  "events": [ /* … */ ]
+}
+```
+
+Via SDK: `oxe.operational.readEvents(root, session)` e `oxe.operational.summarizeEvents(events)`.
+
+---
+
+## 4. Dashboard embutível — `dashboard --json`
+
+O dashboard é um servidor HTTP local (serve `/` HTML + `/api/context` + endpoints de review/runtime). Para embutir num webview/iframe, suba-o em modo host:
+
+```bash
+oxe dashboard --no-open --port 0 --json --dir <projeto>
+```
+
+A **primeira linha** do stdout é, assim que o servidor está ouvindo, e o processo **continua servindo** até ser morto:
+
+```json
+{"oxeDashboardSchema":1,"projectRoot":"/abs/path","url":"http://127.0.0.1:52555/","port":52555,"readOnly":false}
+```
+
+- `--port 0` → o SO escolhe uma porta efêmera; leia a porta real do `port`/`url`.
+- `--read-only` → UI visual sem persistir mudanças (embed seguro).
+- O servidor é localhost-only (`127.0.0.1`), sem autenticação — adequado a embed local.
+
+**Ciclo de vida (host):** faça spawn do processo, leia a primeira linha JSON, carregue `url` no webview, e **mate o processo** ao fechar o workspace/app. Fallback para versões < 1.14: rode `dashboard` sem `--json` e raspe a linha `URL: …`, ou abra no navegador externo.
+
+---
+
+## 5. Mapa de artefatos — `map --json`
+
+A partir da `1.15.0` o `.oxe/` é **enxuto no install** (só `STATE.md`, `config.json` e o `README.md`-legenda); o resto nasce sob demanda. Para projetar o estado real do diretório — o que já existe, o que está disponível sob demanda, e o estado de cada item — use:
+
+```bash
+oxe map --json --dir <projeto>
+```
+
+```jsonc
+{
+  "oxeMapSchema": 1,
+  "projectRoot": "/abs/path",
+  "oxeExists": true,
+  "groups": [ { "key": "core", "label": "…", "present": [ … ], "available": [ … ] } ],
+  "present":   [ { "path": "STATE.md", "kind": "file", "purpose": "…", "createdBy": "install", "group": "core", "state": "active" } ],
+  "available": [ { "path": "codebase/", "kind": "dir", "purpose": "…", "createdBy": "scan", "group": "discovery", "state": "absent" } ],
+  "extras": ["WHATEVER.md"],
+  "counts": { "total": 56, "present": 6, "active": 5, "empty": 1, "stale": 0, "available": 50, "extras": 1 }
+}
+```
+
+- `state`: `active` (com conteúdo) · `empty` (existe mas vazio/zero-byte) · `stale` (scan desatualizado) · `absent` (disponível sob demanda).
+- `createdBy`: a origem do artefato (workflow/CLI/kernel) — use `SOURCE_LABELS` no SDK para rótulos amigáveis.
+- O mesmo modelo está no SDK: `require('oxe-cc').artifacts.buildMapModel(projectRoot)` e `renderLegend()` (o conteúdo do `.oxe/README.md`).
+
+O texto humano (`oxe map`, sem `--json`) imprime a árvore anotada e agrupa os itens "disponível sob demanda" por comando de origem.
+
+---
+
+## 6. Roadmap de integração (ainda não estável)
+
+- **`install … --json`** — saída idempotente `{ ok, agents:[{agent, installedPaths[]}], skipped[], errors[] }` para instalar skills sem terminal. Hoje a instalação é via os comandos `install` (no terminal) + reconferir com `agentSkills`.
+- **`events --follow` / streaming (SSE)** — hoje a reatividade é via `fs.watch` + `events --tail`/`--since`.

package/docs/QUALITY-GATES.md

@@ -0,0 +1,46 @@
+# OXE quality gates
+
+O pipeline de qualidade produz evidência legível por máquina e por pessoas em:
+
+- `.oxe/release/quality-gates-report.json`
+- `.oxe/release/quality-gates-report.md`
+- `coverage/coverage-summary.json`
+
+O relatório registra resultado e duração de cada gate, cobertura, tamanho e quantidade de arquivos do pacote npm e tamanho do VSIX. Cada indicador é comparado ao baseline verificado da versão 1.15.0. A comparação é informativa; os thresholds e ratchets executáveis continuam sendo a fonte de bloqueio.
+
+## Execução local
+
+```bash
+node scripts/quality-report.cjs reset
+node scripts/quality-report.cjs exec --name tests -- npm run test:coverage
+node scripts/quality-report.cjs exec --name extension-host -- npm test --workspace oxe-agents
+node scripts/quality-report.cjs exec --name vsix -- npm run build:vscode-ext
+node scripts/quality-report.cjs finalize
+```
+
+`exec` sempre grava o resultado antes de devolver o exit code do processo filho. `finalize` também devolve código diferente de zero quando algum gate falhou ou quando cobertura, pacote npm ou VSIX estão ausentes. Com isso, a telemetria nunca transforma uma execução vermelha em sucesso.
+
+## Extension Host
+
+O teste usa `@vscode/test-electron` e executa as fontes de produção no VS Code 1.95.3 real. Ele comprova:
+
+- descoberta da extensão `oxe-cc.oxe-agents`;
+- ativação no Extension Development Host;
+- contrato e registro efetivo dos 13 chat participants.
+
+O Copilot Chat proprietário não é baixado no CI. Uma extensão fixture mínima, com o mesmo identificador de dependência, é carregada como segundo development path. Ela apenas satisfaz a resolução da dependência; não substitui nem altera o manifesto OXE. Portanto, o teste não valida autenticação, disponibilidade de modelos, quotas ou respostas reais do Copilot. Esses comportamentos exigem um smoke separado com credenciais.
+
+## Segurança da automação
+
+Os workflows aplicam permissões mínimas, timeouts, cancelamento de CI obsoleta, ações fixadas por SHA completo e `persist-credentials: false`. A publicação npm usa OIDC Trusted Publishing, Node 22.14+ e npm 11.5.1+, sem token de escrita persistente. Antes da primeira release, o pacote `oxe-cc` precisa autorizar `.github/workflows/release.yml` como trusted publisher no npm e o environment GitHub `npm` deve existir.
+
+Dependabot monitora o lockfile único do workspace npm e os SHAs das GitHub Actions. O comentário de versão na mesma linha de cada SHA permite que o Dependabot preserve a identificação da release.
+
+Referências oficiais:
+
+- [GitHub: Secure use reference](https://docs.github.com/en/actions/reference/security/secure-use)
+- [GitHub: concurrency](https://docs.github.com/en/actions/concepts/workflows-and-actions/concurrency)
+- [GitHub: Dependabot para Actions](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/auto-update-actions)
+- [VS Code: Testing Extensions](https://code.visualstudio.com/api/working-with-extensions/testing-extension)
+- [VS Code: Continuous Integration](https://code.visualstudio.com/api/working-with-extensions/continuous-integration)
+- [npm: Trusted publishing](https://docs.npmjs.com/trusted-publishers/)

package/docs/RELEASE-READINESS.md

@@ -1,61 +1,86 @@
-# Release Readiness — OXE
-
-Este é o contrato mínimo para publicar uma versão estável do OXE sem drift entre pacote, runtime, wrappers e operação enterprise.
-
-## Gate local
-
-```bash
-npm test
-npm run scan:assets
-npm run build:vscode-ext
-npm run release:pack-check
-npx oxe-cc doctor --release --write-manifest
-```
-
-O `doctor --release` deve bloquear a publicação quando encontrar:
-
-- árvore canónica `oxe/workflows/`, `oxe/workflows/references/` ou `commands/oxe/` ausente
-- `workflow-runtime-contracts.json` ausente ou inválido
-- drift de versão entre `package.json`, `packages/runtime/package.json`, `vscode-extension/package.json`, `README.md`, `CHANGELOG.md` e banner
-- topo do `CHANGELOG` ausente, sem data ou sem highlights
-- runtime não compilado em `lib/runtime/index.js`
-- wrappers dirty após `sync-runtime-metadata` e `sync:cursor`
-- drift semântico entre workflows canónicos e superfícies geradas
-- ausência ou falha dos relatórios obrigatórios da release
-- tarball npm contendo `.tgz`, `.vsix`, `.oxe/` ou sem arquivos obrigatórios do pacote
-
-## Relatórios obrigatórios
-
-Todos os artefatos abaixo devem existir em `.oxe/release/`:
-
-- `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` para versões `>=1.9.1`
-
-Na linha `>=1.10.0`, `runtime-real-report.json` deve cobrir cenários representativos além do happy path simples: multi-wave, multi-file, verify parcial, gate pendente e promoção bloqueada. O `multi-agent-real-report.json` deve provar merge com evidência, diff summary, arquivos aplicados e verify status por task; o release doctor valida esse conteúdo, não apenas a presença do arquivo.
-
-## Defaults estáveis desta publicação
-
-- `execute` e `verify`: `runtime-first`
-- `promotion`: somente `pr_draft`
-- `multi-agent`: GA apenas com `git_worktree`
-- `branch_push`: capability avançada, fora da superfície estável
-
-## CI
-
-O pipeline de CI e o pipeline de release devem rodar o mesmo gate:
-
-1. `npm test`
-2. `npm run scan:assets`
-3. `npm run release:pack-check`
-4. `npm run release:doctor`
-
-Se qualquer etapa falhar, a release não está pronta.
-
-## Observações operacionais
-
-- `status` e `status --full` distinguem agora `workspaceMode: product_package` de `workspaceMode: oxe_project`.
-- No repositório do pacote, readiness passa a ser de publicação; o CLI deixa de bloquear por ausência de `PLAN.md` executável quando não há ciclo ativo declarado.
+# Release Readiness — OXE
+
+Este é o contrato mínimo para publicar uma versão estável do OXE sem drift entre pacote, runtime, wrappers e operação enterprise.
+
+## Gate local
+
+```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:pack-check
+npx oxe-cc doctor --release --write-manifest
+npm run quality:report
+```
+
+`test:coverage` já executa `npm test` e aplica o ratchet global e dos módulos críticos. `test:packed-consumer` valida o pacote instalado em projeto temporário limpo. `test:vscode-ext` ativa a extensão num VS Code Extension Host real. `test:sdk-types` bloqueia drift do contrato TypeScript público. Lint e `format:check` são somente leitura.
+
+O `doctor --release` deve bloquear a publicação quando encontrar:
+
+- árvore canónica `oxe/workflows/`, `oxe/workflows/references/` ou `commands/oxe/` ausente
+- `workflow-runtime-contracts.json` ausente ou inválido
+- drift de versão entre `package.json`, `packages/runtime/package.json`, `vscode-extension/package.json`, `README.md`, `CHANGELOG.md` e banner
+- topo do `CHANGELOG` ausente, sem data ou sem highlights
+- runtime não compilado em `lib/runtime/index.js`
+- wrappers dirty após `sync-runtime-metadata` e `sync:cursor`
+- drift semântico entre workflows canónicos e superfícies geradas
+- ausência ou falha dos relatórios obrigatórios da release
+- tarball npm contendo `.tgz`, `.vsix`, `.oxe/` ou sem arquivos obrigatórios do pacote
+
+## Relatórios obrigatórios
+
+Todos os artefatos abaixo devem existir em `.oxe/release/`:
+
+- `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` para versões `>=1.9.1`
+
+Na linha `>=1.10.0`, `runtime-real-report.json` deve cobrir cenários representativos além do happy path simples: multi-wave, multi-file, verify parcial, gate pendente e promoção bloqueada. O `multi-agent-real-report.json` deve provar merge com evidência, diff summary, arquivos aplicados e verify status por task; o release doctor valida esse conteúdo, não apenas a presença do arquivo.
+
+O nome `runtime-real` indica que os cenários atravessam o runtime operacional verdadeiro, em vez de mocks do runtime. A suíte continua sendo local e determinística: não chama um modelo externo. A integração live com um provedor LLM é validada separadamente por `npm run test:runtime-llm`; esse teste é opt-in, exige configuração explícita de credenciais/provedor e não integra o gate determinístico de publicação.
+
+## Defaults estáveis desta publicação
+
+- `execute` e `verify`: `runtime-first`
+- `promotion`: somente `pr_draft`
+- `multi-agent`: GA apenas com `git_worktree`
+- `branch_push`: capability avançada, fora da superfície estável
+
+## CI
+
+O pipeline de CI e o pipeline de release devem rodar o mesmo gate:
+
+1. `npm run lint`
+2. `npm run format:check`
+3. `npm run test:sdk-types`
+4. `npm run test:coverage` (inclui `npm test`)
+5. `npm run test:packed-consumer`
+6. `npm run test:vscode-ext`
+7. `npm audit`
+8. `npm run scan:assets`
+9. `npm run build:vscode-ext`
+10. `npm run release:pack-check`
+11. `npm run release:manifest` (doctor de release com `--write-manifest`)
+12. `npm run quality:report`
+
+Se qualquer etapa falhar, a release não está pronta.
+
+O gate completo roda em Node 20. Um job de compatibilidade separado compila o runtime e executa os testes raiz em Node 18 e 22, cobrindo o `engines.node >=18` sem triplicar as suítes pesadas do runtime e da release.
+
+Em checkout limpo, um único `npm ci` na raiz instala as dependências da raiz, do runtime e da extensão por npm workspaces. Não mantenha lockfiles aninhados: o `package-lock.json` raiz é a fonte única de resolução.
+
+O workflow de release valida a tag, executa os gates, empacota o VSIX e cria a GitHub Release sem publicar no npm. A promoção ao registry é manual e posterior. As GitHub Actions ficam fixadas por SHA, e o Dependabot acompanha as revisões desses SHAs.
+
+## Observações operacionais
+
+- `status` e `status --full` distinguem agora `workspaceMode: product_package` de `workspaceMode: oxe_project`.
+- No repositório do pacote, readiness passa a ser de publicação; o CLI deixa de bloquear por ausência de `PLAN.md` executável quando não há ciclo ativo declarado.