oxe-cc 0.7.1 → 0.9.0

package/.github/prompts/oxe-validate-gaps.prompt.md

@@ -1,12 +1,45 @@
----
-name: oxe-validate-gaps
-agent: agent
-description: OXE — Gaps de cobertura pós-verify (VALIDATION-GAPS.md)
-argument-hint: "[opcional: foco Tn ou A*]"
----
-
-Executa o workflow **OXE validate-gaps** no repositório atual. Lê e aplica **integralmente**:
-
-`oxe/workflows/validate-gaps.md`
-
-Requer `VERIFY.md` e `PLAN.md` já existentes. Texto adicional: foco opcional em tarefa **Tn** ou critério **A***.
+---
+name: oxe-validate-gaps
+agent: agent
+description: OXE — Gaps de cobertura pós-verify (VALIDATION-GAPS.md)
+argument-hint: "[opcional: foco Tn ou A*]"
+oxe_workflow_slug: validate-gaps
+oxe_reasoning_mode: review
+oxe_question_policy: none
+oxe_output_contract: findings
+oxe_tool_profile: review_heavy
+oxe_confidence_policy: explicit
+oxe_context_tier: standard
+oxe_contract_version: 2.0.0
+oxe_semantics_hash: 27d51ac144da4c1c
+---
+
+<!-- oxe-reasoning-contract:start -->
+
+**Contrato de raciocínio OXE deste comando**
+- **Workflow:** validate-gaps
+- **Modo:** revisão
+- **Perguntas:** nenhuma
+- **Saída esperada:** achados
+- **Perfil de ferramentas:** revisão intensa
+- **Política de confiança:** explícita
+- **Tier de contexto padrão:** padrão
+- **Versão do contrato:** 2.0.0
+- **Checksum semântico:** `27d51ac144da4c1c`
+- **Entrada de contexto prioritária:** `.oxe/context/packs/validate-gaps.md` e `.oxe/context/packs/validate-gaps.json`
+- **Regra pack-first:** ler o context pack primeiro; se estiver stale, incompleto ou ausente, cair para leitura direta com fallback explícito.
+- **Inspeção estruturada:** `oxe-cc context inspect --workflow validate-gaps --json`
+- Apresentar findings primeiro, ordenados por severidade e evidência.
+- Separar bug, risco, regressão e lacuna de teste.
+- Se não houver findings, declarar isso explicitamente e listar riscos residuais.
+- **Seções esperadas:** Findings · Perguntas abertas · Riscos residuais · Resumo
+- **Bloqueios formais:** missing:state
+- **Referência canónica:** `oxe/workflows/references/reasoning-review.md`
+
+<!-- oxe-reasoning-contract:end -->
+
+Executa o workflow **OXE validate-gaps** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/validate-gaps.md`
+
+Requer `VERIFY.md` e `PLAN.md` já existentes. Texto adicional: foco opcional em tarefa **Tn** ou critério **A***.

package/.github/prompts/oxe-verify.prompt.md

@@ -1,12 +1,45 @@
----
-name: oxe-verify
-agent: agent
-description: OXE — Valida implementação (.oxe/VERIFY.md)
-argument-hint: "[opcional: Tn]"
----
-
-Executa o workflow **OXE verify**. Lê e aplica **integralmente**:
-
-`oxe/workflows/verify.md` (na raiz do repositório em contexto)
-
-Se o utilizador indicar uma tarefa `Tn`, restringe a verificação a essa tarefa.
+---
+name: oxe-verify
+agent: agent
+description: OXE — Valida implementação (.oxe/VERIFY.md)
+argument-hint: "[opcional: Tn]"
+oxe_workflow_slug: verify
+oxe_reasoning_mode: review
+oxe_question_policy: none
+oxe_output_contract: findings
+oxe_tool_profile: review_heavy
+oxe_confidence_policy: explicit
+oxe_context_tier: standard
+oxe_contract_version: 2.0.0
+oxe_semantics_hash: 442bb4594208d058
+---
+
+<!-- oxe-reasoning-contract:start -->
+
+**Contrato de raciocínio OXE deste comando**
+- **Workflow:** verify
+- **Modo:** revisão
+- **Perguntas:** nenhuma
+- **Saída esperada:** achados
+- **Perfil de ferramentas:** revisão intensa
+- **Política de confiança:** explícita
+- **Tier de contexto padrão:** padrão
+- **Versão do contrato:** 2.0.0
+- **Checksum semântico:** `442bb4594208d058`
+- **Entrada de contexto prioritária:** `.oxe/context/packs/verify.md` e `.oxe/context/packs/verify.json`
+- **Regra pack-first:** ler o context pack primeiro; se estiver stale, incompleto ou ausente, cair para leitura direta com fallback explícito.
+- **Inspeção estruturada:** `oxe-cc context inspect --workflow verify --json`
+- Apresentar findings primeiro, ordenados por severidade e evidência.
+- Separar bug, risco, regressão e lacuna de teste.
+- Se não houver findings, declarar isso explicitamente e listar riscos residuais.
+- **Seções esperadas:** Findings · Perguntas abertas · Riscos residuais · Resumo
+- **Bloqueios formais:** missing:state
+- **Referência canónica:** `oxe/workflows/references/reasoning-review.md`
+
+<!-- oxe-reasoning-contract:end -->
+
+Executa o workflow **OXE verify**. Lê e aplica **integralmente**:
+
+`oxe/workflows/verify.md` (na raiz do repositório em contexto)
+
+Se o utilizador indicar uma tarefa `Tn`, restringe a verificação a essa tarefa.

package/.github/prompts/oxe-workstream.prompt.md

@@ -1,12 +1,45 @@
----
-name: oxe-workstream
-agent: agent
-description: "OXE — Trilhas paralelas: list, new <nome>, switch <nome>, status, close <nome> — cada trilha tem artefatos independentes em .oxe/workstreams/<nome>/"
-argument-hint: "list | new <nome> | switch <nome> | status | close <nome>"
----
-
-Executa o workflow **OXE workstream** no repositório atual. Lê e aplica **integralmente** o ficheiro no workspace:
-
-`oxe/workflows/workstream.md`
-
-Usa o texto adicional desta mensagem como subcomando e contexto.
+---
+name: oxe-workstream
+agent: agent
+description: "OXE — Trilhas paralelas: list, new <nome>, switch <nome>, status, close <nome> — cada trilha tem artefatos independentes em .oxe/workstreams/<nome>/"
+argument-hint: "list | new <nome> | switch <nome> | status | close <nome>"
+oxe_workflow_slug: workstream
+oxe_reasoning_mode: execution
+oxe_question_policy: ask_high_impact_only
+oxe_output_contract: execution
+oxe_tool_profile: write_bounded
+oxe_confidence_policy: explicit
+oxe_context_tier: standard
+oxe_contract_version: 2.0.0
+oxe_semantics_hash: 82d171363381cc0d
+---
+
+<!-- oxe-reasoning-contract:start -->
+
+**Contrato de raciocínio OXE deste comando**
+- **Workflow:** workstream
+- **Modo:** execução
+- **Perguntas:** perguntar só alto impacto
+- **Saída esperada:** execução
+- **Perfil de ferramentas:** mutação limitada
+- **Política de confiança:** explícita
+- **Tier de contexto padrão:** padrão
+- **Versão do contrato:** 2.0.0
+- **Checksum semântico:** `82d171363381cc0d`
+- **Entrada de contexto prioritária:** `.oxe/context/packs/workstream.md` e `.oxe/context/packs/workstream.json`
+- **Regra pack-first:** ler o context pack primeiro; se estiver stale, incompleto ou ausente, cair para leitura direta com fallback explícito.
+- **Inspeção estruturada:** `oxe-cc context inspect --workflow workstream --json`
+- Fazer reconhecimento curto antes de editar ou executar mutações.
+- Trabalhar no menor write set viável e validar após cada fatia relevante.
+- Parar e explicitar o bloqueio quando houver hipótese crítica não verificada.
+- **Seções esperadas:** Contexto lido · Alvo da mudança · Validação executada · Resultado · Próximo passo
+- **Bloqueios formais:** missing:state · missing:plan
+- **Referência canónica:** `oxe/workflows/references/reasoning-execution.md`
+
+<!-- oxe-reasoning-contract:end -->
+
+Executa o workflow **OXE workstream** no repositório atual. Lê e aplica **integralmente** o ficheiro no workspace:
+
+`oxe/workflows/workstream.md`
+
+Usa o texto adicional desta mensagem como subcomando e contexto.

package/.github/prompts/oxe.prompt.md

@@ -1,12 +1,45 @@
----
-name: oxe
-agent: agent
-description: OXE — Entrada universal: próximo passo / roteamento / help dos 8 comandos essenciais
-argument-hint: "[contexto em linguagem natural | 'help' | vazio para próximo passo]"
----
-
-Executa o workflow **OXE** (entrada universal) no repositório atual. Lê e aplica **integralmente**:
-
-`oxe/workflows/oxe.md`
-
-`$ARGUMENTS`: vazio → próximo passo; texto → roteamento; "help" → 8 comandos essenciais.
+---
+name: oxe
+agent: agent
+description: OXE — Entrada universal: próximo passo / roteamento / help dos 8 comandos essenciais
+argument-hint: "[contexto em linguagem natural | 'help' | vazio para próximo passo]"
+oxe_workflow_slug: oxe
+oxe_reasoning_mode: status
+oxe_question_policy: none
+oxe_output_contract: routing
+oxe_tool_profile: read_heavy
+oxe_confidence_policy: explicit
+oxe_context_tier: standard
+oxe_contract_version: 2.0.0
+oxe_semantics_hash: d7f65cd3f77b0abc
+---
+
+<!-- oxe-reasoning-contract:start -->
+
+**Contrato de raciocínio OXE deste comando**
+- **Workflow:** oxe
+- **Modo:** estado / roteamento
+- **Perguntas:** nenhuma
+- **Saída esperada:** roteamento
+- **Perfil de ferramentas:** leitura intensa
+- **Política de confiança:** explícita
+- **Tier de contexto padrão:** padrão
+- **Versão do contrato:** 2.0.0
+- **Checksum semântico:** `d7f65cd3f77b0abc`
+- **Entrada de contexto prioritária:** `.oxe/context/packs/oxe.md` e `.oxe/context/packs/oxe.json`
+- **Regra pack-first:** ler o context pack primeiro; se estiver stale, incompleto ou ausente, cair para leitura direta com fallback explícito.
+- **Inspeção estruturada:** `oxe-cc context inspect --workflow oxe --json`
+- Responder com leitura curta e orientada a decisão.
+- Dar uma recomendação única e justificar o motivo.
+- Explicitar a confiança quando o estado estiver incompleto ou ambíguo.
+- **Seções esperadas:** Leitura atual · Recomendação · Motivo · Confiança
+- **Bloqueios formais:** missing:state
+- **Referência canónica:** `oxe/workflows/references/reasoning-status.md`
+
+<!-- oxe-reasoning-contract:end -->
+
+Executa o workflow **OXE** (entrada universal) no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/oxe.md`
+
+`$ARGUMENTS`: vazio → próximo passo; texto → roteamento; "help" → 8 comandos essenciais.

package/AGENTS.md

@@ -72,10 +72,12 @@ Blueprints em `.oxe/plan-agents.json` (schema 3). Protocolo inter-agente: `oxe/w
 ## Integrações IDE
 
 - **Cursor:** slash commands em `~/.cursor/commands/` (gerados por `npm run sync:cursor`)
-- **GitHub Copilot (VS Code):** prompt files em `~/.copilot/prompts/` + `copilot-instructions.md`
+- **GitHub Copilot (VS Code):** prompt files em `.github/prompts/` + `.github/copilot-instructions.md`
 - **Claude Code:** commands em `~/.claude/commands/`
 - **OpenCode / Gemini / Codex / Windsurf / Antigravity:** via `oxe-cc --all-agents`
 
-## Instruções para agentes de IA
-
-Quando o utilizador pedir uma etapa OXE por linguagem natural, seguir o ficheiro `oxe/workflows/<passo>.md` correspondente **sem atalhar passos**. Ler os artefatos em `.oxe/` antes de qualquer ação — nunca partir de suposições sobre o estado do projeto.
+## Instruções para agentes de IA
+
+Quando o utilizador pedir uma etapa OXE por linguagem natural, seguir o ficheiro `oxe/workflows/<passo>.md` correspondente **sem atalhar passos**. Ler os artefatos em `.oxe/` antes de qualquer ação — nunca partir de suposições sobre o estado do projeto.
+
+Os wrappers por runtime podem carregar metadata cognitiva (`oxe_reasoning_mode`, `oxe_question_policy`, `oxe_output_contract`, `oxe_tool_profile`, `oxe_confidence_policy`), mas o comportamento canónico continua no workflow. Use essa metadata para adaptar a postura do agente sem bifurcar a lógica do OXE por ferramenta.

package/CHANGELOG.md

@@ -4,6 +4,51 @@ Todas as versões seguem [Semantic Versioning](https://semver.org/). As mudança
 
 ---
 
+## [0.8.0] — 2026-04-14
+
+### Adicionado
+
+**Session forking + revert**
+- `session fork [nome]` — bifurca a sessão ativa, copiando todos os artefatos para uma nova sessão; rastreia `forked_from` na SESSION.md
+- `session revert <checkpoint-slug>` — restaura STATE.md ao snapshot de um checkpoint, sem apagar artefatos atuais
+
+**Skill system**
+- `/oxe-skill` — workflow para descobrir, invocar e gerenciar skills (unificação de personas e capabilities)
+- `@<skill-id>` no chat resolve persona OU capability OU composite como ponto de entrada único
+- Template `SKILL.template.md` para criação de skills de projeto em `.oxe/skills/`
+- Resolução em 3 camadas: project → capabilities → global (personas do pacote)
+
+**Sistema de permissões com wildcard**
+- `permissions[]` em `.oxe/config.json` — regras glob+ação que controlam acesso a arquivos durante execute e apply
+- Ações: `allow`, `deny`, `ask` — avaliação first-match wins
+- Scopes: `execute`, `apply`, `all`
+- Gate automático no workflow execute antes de cada onda
+
+**Config hierárquico (system → user → project)**
+- `loadOxeConfigMerged()` agora lê 3 níveis: system (`OXE_SYSTEM_CONFIG` ou path OS-default) < user (`~/.oxe/config.json`) < project (`.oxe/config.json`)
+- `status --full` exibe fontes de cada nível de configuração
+- Campo `sources` no retorno do SDK
+
+**Event sourcing com replay**
+- `replayEvents()` no SDK — reconstrói timeline de `OXE-EVENTS.ndjson` com deltas, filtros por run/wave/event
+- `oxe-cc runtime replay [--run <id>] [--from <event-id>] [--wave <n>] [--write]` — visualização de timeline no terminal ou `REPLAY-SESSION.md` em disco
+- Integração com `/oxe-forensics` — replay como ferramenta de investigação
+
+**Plugin system com carregamento remoto**
+- `plugins[]` em `config.json` aceita `{ source: "npm:<pkg>" }` e `{ source: "path:./file.cjs" }`
+- `oxe-cc plugins list` — lista plugins carregados (local + externos)
+- `oxe-cc plugins install npm:<pkg>` — instala plugin npm em `.oxe/plugins/_npm/`
+- `resolvePluginSources()` e `installNpmPlugin()` expostos no SDK
+
+### Tipos TypeScript
+- `OxePermissionRule`, `PermissionCheckResult`, `ReplayReport`, `PluginSource` adicionados
+- `security.checkFilePermission`, `security.checkPermissions`, `security.globToRegex` declarados
+- `operational.replayEvents` declarado
+- `plugins.resolvePluginSources`, `plugins.installNpmPlugin` declarados
+- `health.loadOxeConfigMerged` retorna `sources: { system, user, project }`
+
+---
+
 ## [0.7.0] — 2026-04-13
 
 ### Adicionado

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:** `0.6.4` · [package.json](package.json)
+**Versão:** `0.8.0` · [package.json](package.json)
 
 **Framework OXE — Orchestrated eXperience Engineering**
 
@@ -31,11 +31,26 @@ Ele se apoia em três princípios:
 - **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.
 
 O resultado: **menos requisições**, **mais coerência**, e uma experiência de engenharia orquestrada que funciona do mesmo jeito em qualquer IDE.
 
 ---
 
+## Semântica de raciocínio do OXE
+
+O OXE agora distingue cinco famílias de raciocínio:
+
+- `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
+
+Essas regras vivem no núcleo canónico em `oxe/workflows/references/reasoning-*.md`, sobem para os workflows em `oxe/workflows/` e são renderizadas para cada runtime em `.github/prompts/`, `.cursor/commands/`, `commands/oxe/`, `.codex/prompts/` e skills multiagente.
+
+---
+
 ## Modos de uso
 
 Escolha a complexidade certa para sua tarefa. Você sempre começa simples e adiciona estrutura quando precisar.
@@ -175,6 +190,7 @@ Cada passo lê o anterior como contexto e escreve seu artefato no escopo correto
 | `/oxe-session` | Cria, alterna, retoma, fecha e migra sessões OXE sem misturar artefatos de ciclos diferentes. |
 | `/oxe-ask` | Lê `STATE`, resolve a sessão ativa e responde perguntas situacionais com base nos artefatos reais. |
 | `/oxe-capabilities` | Gera e mantém o catálogo nativo de capabilities do projeto em `.oxe/CAPABILITIES.md` e `.oxe/capabilities/`, com política, side effects e evidência esperada. |
+| `/oxe-skill` | Descobrir, invocar e gerenciar skills OXE — unificação de personas e capabilities via `@<skill-id>`. Subcomandos: `list`, `explain <id>`, `new <id>`, invocação `@<id>` inline. |
 | `oxe-cc azure` | Provider Azure nativo via Azure CLI: autenticação corporativa com MFA, inventário via Resource Graph e operações guiadas para Service Bus, Event Grid e Azure SQL, sempre com evidência em `.oxe/cloud/azure/`. |
 | `/oxe-dashboard` | Consolida `STATE`, `PLAN`, `ACTIVE-RUN`, trace log, runtime, checkpoints e verify numa visão visual de ciclo, artefatos, ondas, handoffs e aprovação antes do execute. |
 
@@ -198,12 +214,16 @@ Estes não precisam ser decorados — aparecem quando o contexto pede ou quando
 
 | Comando | Quando usar |
 |---------|-------------|
+| `/oxe-debug` | Diagnóstico técnico inline durante execute — stack trace, teste vermelho, flake |
 | `/oxe-research` | Spike, mapa de sistema, engenharia reversa — antes de spec ou plano |
 | `/oxe-forensics` | Falha persistente após múltiplas tentativas — diagnóstico profundo |
+| `/oxe-validate-gaps` | Gaps de cobertura pós-verify (Nyquist-lite) |
+| `/oxe-security` | Auditoria OWASP P0/P1/P2 vinculada ao stack |
 | `/oxe-ui-spec` | Contrato UI/UX derivado da SPEC (quando UI é domínio crítico) |
 | `/oxe-ui-review` | Auditoria da implementação UI contra o contrato |
 | `/oxe-review-pr` | Revisão de PR ou diff de branches |
 | `/oxe-checkpoint` | Snapshot nomeado do estado da sessão |
+| `/oxe-loop` | Iteração automática até verify passar (integrado ao Modo B do execute) |
 
 ---
 
@@ -388,7 +408,8 @@ npx oxe-cc@latest
 
 | Flag | Efeito |
 |------|--------|
-| `--cursor` / `--copilot` | Só uma das stacks |
+| `--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) |
@@ -400,6 +421,8 @@ npx oxe-cc@latest
 
 </details>
 
+GitHub Copilot no VS Code é **workspace-first**: o OXE instala prompt files em `.github/prompts/*.prompt.md` e mescla instruções em `.github/copilot-instructions.md`. `~/.copilot/` fica reservado ao legado detectável e ao runtime do Copilot CLI.
+
 <details>
 <summary><strong>Atualizar e desinstalar</strong></summary>
 
@@ -430,15 +453,19 @@ node bin/oxe-cc.js --help
 | Comando | O que faz |
 |---------|-----------|
 | `oxe-cc` / `oxe-cc install` | Instala workflows e integrações |
-| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, config, bootstrap `.oxe/`, sessão ativa, autoavaliação do plano e saúde lógica (`healthy` \| `warning` \| `broken`) |
+| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, config, bootstrap `.oxe/`, sessão ativa, autoavaliação do plano, saúde lógica (`healthy` \| `warning` \| `broken`), drift semântico multi-runtime e workflows sem contrato no registry |
 | `oxe-cc status` | Próximo passo sugerido + saúde lógica do fluxo |
 | `oxe-cc status --full` | Coverage matrix + readiness gate + active run no terminal (ANSI) |
-| `oxe-cc status --json` | Mesmo, em JSON, com `healthStatus`, `activeSession` e `planSelfEvaluation` |
+| `oxe-cc status --json` | Mesmo, em JSON (schema v3), com `healthStatus`, `activeSession`, `planSelfEvaluation`, `contextPacks`, `contextQuality` e `semanticsDrift` |
+| `oxe-cc context build [--workflow <slug>] [--tier <minimal\|standard\|full>]` | Gera context pack(s) em `.oxe/context/packs/` — seleção determinística de artefatos por contrato de workflow |
+| `oxe-cc context inspect [--workflow <slug>]` | Inspeciona um context pack existente ou resolve sob demanda (sem escrita); útil para diagnóstico antes de iniciar um passo |
 | `oxe-cc update` | Atualiza workflows para a versão mais recente |
-| `oxe-cc init-oxe` | Bootstrap do `.oxe/` (STATE, config, codebase/) |
-| `oxe-cc dashboard` | Interface web local para revisão, comentários e aprovação do plano |
+| `oxe-cc init-oxe` | Bootstrap do `.oxe/` (STATE, config, codebase/, context/, install/) |
+| `oxe-cc dashboard` | Interface web local para revisão, comentários e aprovação do plano (inclui aba Context com quality score e drift semântico) |
 | `oxe-cc runtime <status\|start\|pause\|resume\|replay>` | Controla o run ativo, cursor, replay e tracing operacional |
+| `oxe-cc runtime replay [--run <id>] [--from <event-id>] [--wave <n>] [--write]` | Timeline de eventos com deltas; `--write` gera `REPLAY-SESSION.md` |
 | `oxe-cc capabilities <list\|install\|remove\|update>` | Mantém o catálogo nativo de capabilities em `.oxe/` |
+| `oxe-cc plugins <list\|install\|remove>` | Gerencia plugins de lifecycle; `install npm:<pkg>` instala em `.oxe/plugins/_npm/` |
 | `oxe-cc uninstall` | Remove integrações OXE do HOME e do repo |
 | `oxe-cc uninstall --global-cli` | Também remove o pacote npm global do PATH |
 
@@ -458,7 +485,8 @@ Arquivo `.oxe/config.json`. Principais opções:
 | `scale_adaptive` | `true` | Scan sugere o profile pelo tamanho do projeto |
 | `scan_max_age_days` | `0` | Doctor avisa quando o scan estiver velho |
 | `lessons_max_age_days` | `0` | Doctor avisa quando a última retro estiver velho |
-| `plugins` | `[]` | Hooks de lifecycle em `.oxe/plugins/*.cjs` |
+| `plugins` | `[]` | Hooks de lifecycle em `.oxe/plugins/*.cjs`; aceita `{ source: "npm:<pkg>" }` e `{ source: "path:./file.cjs" }` |
+| `permissions` | `[]` | Regras glob+ação para gate de arquivos em execute/apply — `{ pattern, action: allow\|deny\|ask, scope?: execute\|apply\|all }` |
 
 ---
 
@@ -485,7 +513,9 @@ TypeScript: [`lib/sdk/index.d.ts`](lib/sdk/index.d.ts) · Docs: [`lib/sdk/README
 | 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 `~/.copilot/prompts/` |
+| `/oxe-*` não aparecem no Copilot | Ative `"chat.promptFiles": true`; confirme `.github/prompts/` e `.github/copilot-instructions.md`; se existir legado em `~/.copilot/`, rode `npx oxe-cc uninstall --copilot-legacy-clean` |
+| Copilot responde fora do workflow OXE | Rode `npx oxe-cc doctor`; confirme que o prompt veio de `.github/prompts/` e não do legado em `~/.copilot/`; se houver blocos mistos de outros frameworks no global, limpe o legado |
+| Um runtime responde sem a nova disciplina de raciocínio | Verifique drift entre `oxe/workflows/`, `.github/prompts/`, `commands/oxe/` e os prompts instalados; rode `npm run sync:runtime-metadata` e `npm run sync:cursor` no repo do pacote |
 | Arquivos não atualizam | Reinstale com `--force` |
 | `ETARGET` / versão não encontrada | `npm cache clean --force` |
 | Erro no WSL sobre Node | Use Node instalado dentro do WSL |

package/bin/lib/oxe-agent-install.cjs

@@ -8,9 +8,10 @@
  * Com `--ide-local`, destinos equivalentes sob a raiz do projeto (ex.: ./.opencode/commands).
  */
 
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const runtimeSemantics = require('./oxe-runtime-semantics.cjs');
 
 const OXE_MANAGED_HTML = '<!-- oxe-cc managed -->';
 const OXE_MANAGED_TOML = '# oxe-cc managed';
@@ -75,47 +76,55 @@ function adjustWorkflowPathsForNestedLayout(content) {
 
 /**
  * @param {string} text
- * @returns {{ description: string, body: string }}
- */
-function parseCursorCommandFrontmatter(text) {
-  const normalized = text.replace(/\r\n/g, '\n');
-  if (!normalized.startsWith('---\n')) {
-    return { description: '', body: normalized.trim() };
-  }
-  const end = normalized.indexOf('\n---\n', 4);
-  if (end === -1) {
-    return { description: '', body: normalized.trim() };
-  }
-  const yamlBlock = normalized.slice(4, end);
-  let description = '';
-  for (const line of yamlBlock.split('\n')) {
-    const m = line.match(/^description:\s*(.+)$/);
-    if (m) {
-      description = m[1].trim().replace(/^["']|["']$/g, '');
-      break;
-    }
-  }
-  const body = normalized.slice(end + 5).trim();
-  return { description, body };
-}
+ * @returns {{ description: string, body: string, frontmatter: Record<string, string> }}
+ */
+function parseCursorCommandFrontmatter(text) {
+  const normalized = text.replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) {
+    return { description: '', body: normalized.trim(), frontmatter: {} };
+  }
+  const end = normalized.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return { description: '', body: normalized.trim(), frontmatter: {} };
+  }
+  const yamlBlock = normalized.slice(4, end);
+  const frontmatter = {};
+  let description = '';
+  for (const line of yamlBlock.split('\n')) {
+    const m = line.match(/^description:\s*(.+)$/);
+    if (m) {
+      description = m[1].trim().replace(/^["']|["']$/g, '');
+    }
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
+    if (kv) frontmatter[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  const body = normalized.slice(end + 5).trim();
+  return { description, body, frontmatter };
+}
 
 /**
  * @param {string} skillName
  * @param {string} description
- * @param {string} body
- */
-function buildAgentSkillMarkdown(skillName, description, body) {
-  const desc = description.trim() || `Comando OXE — ${skillName}`;
-  return (
-    `---\n` +
-    `name: ${skillName}\n` +
-    `description: ${JSON.stringify(desc)}\n` +
-    `user-invocable: true\n` +
-    `---\n\n` +
-    `${OXE_MANAGED_HTML}\n\n` +
-    `${body}\n`
-  );
-}
+ * @param {string} body
+ * @param {Record<string, string>} [metadata]
+ */
+function buildAgentSkillMarkdown(skillName, description, body, metadata) {
+  const desc = description.trim() || `Comando OXE — ${skillName}`;
+  const meta = metadata ? runtimeSemantics.pickRuntimeMetadata(metadata) : {};
+  const metaLines = Object.keys(meta).length
+    ? `${runtimeSemantics.renderRuntimeMetadataLines(meta).join('\n')}\n`
+    : '';
+  return (
+    `---\n` +
+    `name: ${skillName}\n` +
+    `description: ${JSON.stringify(desc)}\n` +
+    `user-invocable: true\n` +
+    metaLines +
+    `---\n\n` +
+    `${OXE_MANAGED_HTML}\n\n` +
+    `${body}\n`
+  );
+}
 
 /**
  * @returns {string[]}
@@ -181,9 +190,9 @@ function installSkillTreeFromCursorCommands(cCmdSrc, skillsRoot, opts, pathRewri
   const writeOne = (skillName, srcPath, descSuffix) => {
     let raw = fs.readFileSync(srcPath, 'utf8');
     if (pathRewriteNested) raw = adjustWorkflowPathsForNestedLayout(raw);
-    const { description, body } = parseCursorCommandFrontmatter(raw);
-    const desc = descSuffix ? `${description.trim()} ${descSuffix}`.trim() : description.trim();
-    const md = buildAgentSkillMarkdown(skillName, desc, body);
+    const { description, body, frontmatter } = parseCursorCommandFrontmatter(raw);
+    const desc = descSuffix ? `${description.trim()} ${descSuffix}`.trim() : description.trim();
+    const md = buildAgentSkillMarkdown(skillName, desc, body, frontmatter);
     const destDir = path.join(skillsRoot, skillName);
     const dest = path.join(destDir, 'SKILL.md');
     if (opts.dryRun) {
@@ -248,8 +257,8 @@ function installGeminiTomlCommands(cCmdSrc, paths, opts, pathRewriteNested, logO
   const writeToml = (relPath, srcPath, descSuffix) => {
     let raw = fs.readFileSync(srcPath, 'utf8');
     if (pathRewriteNested) raw = adjustWorkflowPathsForNestedLayout(raw);
-    const { description, body } = parseCursorCommandFrontmatter(raw);
-    const desc = descSuffix ? `${description} ${descSuffix}`.trim() : description;
+    const { description, body } = parseCursorCommandFrontmatter(raw);
+    const desc = descSuffix ? `${description} ${descSuffix}`.trim() : description;
     const toml = buildGeminiToml(desc, body);
     const dest = path.join(base, relPath);
     if (opts.dryRun) {
@@ -298,8 +307,8 @@ function installWindsurfGlobalWorkflows(cCmdSrc, paths, opts, pathRewriteNested,
     }
     let raw = fs.readFileSync(src, 'utf8');
     if (pathRewriteNested) raw = adjustWorkflowPathsForNestedLayout(raw);
-    const { description, body } = parseCursorCommandFrontmatter(raw);
-    const title = description || name.replace(/\.md$/i, '');
+    const { description, body } = parseCursorCommandFrontmatter(raw);
+    const title = description || name.replace(/\.md$/i, '');
     const out =
       `---\n` +
       `description: ${JSON.stringify(title)}\n` +
@@ -353,14 +362,19 @@ function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido
     }
     let raw = fs.readFileSync(src, 'utf8');
     if (pathRewriteNested) raw = adjustWorkflowPathsForNestedLayout(raw);
-    const { description, body } = parseCursorCommandFrontmatter(raw);
-    const out =
-      `---\n` +
-      `description: ${JSON.stringify(description || 'OXE')}\n` +
-      `argument-hint: [texto livre opcional]\n` +
-      `---\n\n` +
-      `${OXE_MANAGED_HTML}\n\n` +
-      `${body}\n`;
+    const { description, body, frontmatter } = parseCursorCommandFrontmatter(raw);
+    const meta = runtimeSemantics.pickRuntimeMetadata(frontmatter);
+    const metaLines = Object.keys(meta).length
+      ? `${runtimeSemantics.renderRuntimeMetadataLines(meta).join('\n')}\n`
+      : '';
+    const out =
+      `---\n` +
+      `description: ${JSON.stringify(description || 'OXE')}\n` +
+      `argument-hint: [texto livre opcional]\n` +
+      metaLines +
+      `---\n\n` +
+      `${OXE_MANAGED_HTML}\n\n` +
+      `${body}\n`;
     fs.mkdirSync(destDir, { recursive: true });
     fs.writeFileSync(dest, out, 'utf8');
   }