oxe-cc 1.5.1 → 1.7.0

package/oxe/workflows/references/adaptive-discovery.md

@@ -1,27 +1,27 @@
-# OXE — Descoberta Adaptativa
-
-<objective>
-Reduzir ambiguidade antes da escrita de `SPEC.md` e melhorar a qualidade do plano. Esta referência orienta `spec` e `ask`.
-</objective>
-
-## Regras
-
-- Classificar a demanda o mais cedo possível: `feature`, `bugfix`, `refactor`, `research`, `ops`, `mixed`.
-- Modular as perguntas pelo tipo de demanda e pelo risco.
-- Limitar rodadas; consolidar entendimento antes de escrever artefatos.
-- Registrar incertezas estruturadas, não apenas em texto solto.
-
-## Blocos mínimos
-
-- **Objetivo final**
-- **Impacto / público**
-- **Restrições técnicas**
-- **Riscos e casos extremos**
-- **Evidência faltante**
-
-## Saída esperada
-
-- resumo de entendimento;
-- demanda classificada;
-- incertezas remanescentes;
-- recomendação de próximo passo compatível com o risco.
+# OXE — Descoberta Adaptativa
+
+<objective>
+Reduzir ambiguidade antes da escrita de `SPEC.md` e melhorar a qualidade do plano. Esta referência orienta `spec` e `ask`.
+</objective>
+
+## Regras
+
+- Classificar a demanda o mais cedo possível: `feature`, `bugfix`, `refactor`, `research`, `ops`, `mixed`.
+- Modular as perguntas pelo tipo de demanda e pelo risco.
+- Limitar rodadas; consolidar entendimento antes de escrever artefatos.
+- Registrar incertezas estruturadas, não apenas em texto solto.
+
+## Blocos mínimos
+
+- **Objetivo final**
+- **Impacto / público**
+- **Restrições técnicas**
+- **Riscos e casos extremos**
+- **Evidência faltante**
+
+## Saída esperada
+
+- resumo de entendimento;
+- demanda classificada;
+- incertezas remanescentes;
+- recomendação de próximo passo compatível com o risco.

package/oxe/workflows/references/flow-robustness-contract.md

@@ -1,80 +1,80 @@
-# OXE — Contrato de Robustez do Fluxo
-
-<objective>
-Definir um contrato canónico para reduzir alucinação estrutural no OXE. Este ficheiro é consumido por `spec`, `plan`, `quick`, `execute`, `verify`, `next`, `status` e `doctor`.
-</objective>
-
-## Ordem determinística do fluxo
-
-Todo passo OXE deve seguir esta ordem, sem saltar etapas:
-
-1. Ler os artefatos obrigatórios do estado atual.
-2. Resolver `active_session` e os paths do escopo.
-3. Validar pré-condições mínimas antes de prosseguir.
-4. Produzir a saída principal do passo.
-5. Executar autoavaliação ou gate de qualidade do próprio passo.
-6. Registrar um próximo passo único.
-
-## Invariantes mínimos
-
-Todo workflow deve declarar com clareza:
-
-- quais artefatos lê;
-- quais artefatos escreve;
-- quais invariantes valida antes de operar;
-- qual fallback legado é permitido quando não há sessão ativa.
-
-## Proibição de saltos sem evidência
-
-- `plan` não deve avançar sem `SPEC.md` válido.
-- `execute` não deve avançar sem `PLAN.md` ou `QUICK.md` válido no escopo resolvido.
-- `verify` não deve avançar sem evidência mínima de execução ou de artefatos resultantes.
-- `next` não deve sugerir um passo que viole os gates acima.
-
-## Contrato de autoavaliação do plano
-
-Todo `PLAN.md` deve conter uma seção visível `## Autoavaliação do Plano` com:
-
-- `Melhor plano atual:` `sim` ou `não`
-- `Confiança:` `0–100%`
-- `Base da confiança:` rubrica fixa, não narrativa livre
-- `Principais incertezas:` lista curta
-- `Alternativas descartadas:` resumo curto
-- `Condição para replanejar:` critério objetivo
-
-### Rubrica obrigatória
-
-| Dimensão | Peso |
-|----------|------|
-| Completude dos requisitos | 25 |
-| Dependências conhecidas | 15 |
-| Risco técnico | 20 |
-| Impacto no código existente | 15 |
-| Clareza da validação / testes | 15 |
-| Lacunas externas / decisões pendentes | 10 |
-
-**Total:** 100 pontos
-
-### Faixas semânticas
-
-- `91–100%` → pronto para executar
-- `80–90%` → plano racional, mas ainda não executável
-- `50–79%` → precisa refino antes de execução
-- `<50%` → não executar
-
-## Calibração pós-execução
-
-`verify` deve comparar o resultado real com a autoavaliação do plano:
-
-- confiança alta + falha precoce = erro de calibração do plano;
-- confiança baixa + falha em risco previsto = autoavaliação aderente;
-- confiança alta + sucesso consistente = plano calibrado;
-- confiança baixa + sucesso amplo = plano conservador demais.
-
-## Uso por `status` e `doctor`
-
-`status` e `doctor` devem refletir a saúde lógica do fluxo com categorias determinísticas:
-
-- `healthy` — sem bloqueio lógico conhecido;
-- `warning` — fluxo operável, mas com gaps ou drift relevante;
-- `broken` — artefato crítico ausente, incoerência severa ou gate indispensável falhado.
+# OXE — Contrato de Robustez do Fluxo
+
+<objective>
+Definir um contrato canónico para reduzir alucinação estrutural no OXE. Este ficheiro é consumido por `spec`, `plan`, `quick`, `execute`, `verify`, `next`, `status` e `doctor`.
+</objective>
+
+## Ordem determinística do fluxo
+
+Todo passo OXE deve seguir esta ordem, sem saltar etapas:
+
+1. Ler os artefatos obrigatórios do estado atual.
+2. Resolver `active_session` e os paths do escopo.
+3. Validar pré-condições mínimas antes de prosseguir.
+4. Produzir a saída principal do passo.
+5. Executar autoavaliação ou gate de qualidade do próprio passo.
+6. Registrar um próximo passo único.
+
+## Invariantes mínimos
+
+Todo workflow deve declarar com clareza:
+
+- quais artefatos lê;
+- quais artefatos escreve;
+- quais invariantes valida antes de operar;
+- qual fallback legado é permitido quando não há sessão ativa.
+
+## Proibição de saltos sem evidência
+
+- `plan` não deve avançar sem `SPEC.md` válido.
+- `execute` não deve avançar sem `PLAN.md` ou `QUICK.md` válido no escopo resolvido.
+- `verify` não deve avançar sem evidência mínima de execução ou de artefatos resultantes.
+- `next` não deve sugerir um passo que viole os gates acima.
+
+## Contrato de autoavaliação do plano
+
+Todo `PLAN.md` deve conter uma seção visível `## Autoavaliação do Plano` com:
+
+- `Melhor plano atual:` `sim` ou `não`
+- `Confiança:` `0–100%`
+- `Base da confiança:` rubrica fixa, não narrativa livre
+- `Principais incertezas:` lista curta
+- `Alternativas descartadas:` resumo curto
+- `Condição para replanejar:` critério objetivo
+
+### Rubrica obrigatória
+
+| Dimensão | Peso |
+|----------|------|
+| Completude dos requisitos | 25 |
+| Dependências conhecidas | 15 |
+| Risco técnico | 20 |
+| Impacto no código existente | 15 |
+| Clareza da validação / testes | 15 |
+| Lacunas externas / decisões pendentes | 10 |
+
+**Total:** 100 pontos
+
+### Faixas semânticas
+
+- `91–100%` → pronto para executar
+- `80–90%` → plano racional, mas ainda não executável
+- `50–79%` → precisa refino antes de execução
+- `<50%` → não executar
+
+## Calibração pós-execução
+
+`verify` deve comparar o resultado real com a autoavaliação do plano:
+
+- confiança alta + falha precoce = erro de calibração do plano;
+- confiança baixa + falha em risco previsto = autoavaliação aderente;
+- confiança alta + sucesso consistente = plano calibrado;
+- confiança baixa + sucesso amplo = plano conservador demais.
+
+## Uso por `status` e `doctor`
+
+`status` e `doctor` devem refletir a saúde lógica do fluxo com categorias determinísticas:
+
+- `healthy` — sem bloqueio lógico conhecido;
+- `warning` — fluxo operável, mas com gaps ou drift relevante;
+- `broken` — artefato crítico ausente, incoerência severa ou gate indispensável falhado.

package/oxe/workflows/references/session-path-resolution.md

@@ -1,71 +1,71 @@
-# OXE — Referência: Session Path Resolution
-
-<objective>
-Padronizar a resolução de caminhos quando o projeto usa **sessões OXE** em `.oxe/sessions/`, preservando o modo legado quando **`.oxe/STATE.md`** não tiver `active_session`.
-</objective>
-
-<resolution_rule>
-## Regra de resolução
-
-1. Ler **`.oxe/STATE.md`** global.
-2. Procurar o campo **`active_session`** na secção **Sessão ativa**.
-3. Se existir e tiver valor diferente de `—`, usar:
-   - `session_path = .oxe/<active_session>/`
-   - `active_session` deve guardar sempre o path relativo completo, por exemplo: `sessions/s001-auth-redesign`
-4. Se não existir:
-   - `session_path = .oxe/`
-   - O workflow opera em **modo legado**
-
-## Convenções auxiliares
-
-- **global_state_path** = `.oxe/STATE.md`
-- **global_config_path** = `.oxe/config.json`
-- **global_codebase_path** = `.oxe/codebase/`
-- **global_sessions_index_path** = `.oxe/SESSIONS.md`
-- **global_lessons_path** = `.oxe/global/LESSONS.md`
-- **global_milestones_index_path** = `.oxe/global/MILESTONES.md`
-- **global_milestones_dir** = `.oxe/global/milestones/`
-</resolution_rule>
-
-<artifact_matrix>
-## Matriz de artefatos
-
-| Tipo | Escopo | Caminho com sessão ativa | Caminho legado |
-|------|--------|--------------------------|----------------|
-| STATE global | global | `.oxe/STATE.md` | `.oxe/STATE.md` |
-| Config | global | `.oxe/config.json` | `.oxe/config.json` |
-| Codebase | global | `.oxe/codebase/*` | `.oxe/codebase/*` |
-| SESSIONS | global | `.oxe/SESSIONS.md` | `.oxe/SESSIONS.md` |
-| LESSONS | global | `.oxe/global/LESSONS.md` | `.oxe/LESSONS.md` |
-| MILESTONES | global | `.oxe/global/MILESTONES.md` | `.oxe/MILESTONES.md` |
-| SPEC / ROADMAP / DISCUSS / UI-SPEC | sessão | `.oxe/<active_session>/spec/` | `.oxe/` |
-| PLAN / QUICK / plan-agents / quick-agents | sessão | `.oxe/<active_session>/plan/` | `.oxe/` |
-| STATE local / OBS / DEBUG / FORENSICS | sessão | `.oxe/<active_session>/execution/` | `.oxe/` |
-| VERIFY / VALIDATION-GAPS / SECURITY / UI-REVIEW | sessão | `.oxe/<active_session>/verification/` | `.oxe/` |
-| CHECKPOINTS | sessão | `.oxe/<active_session>/checkpoints/` | `.oxe/checkpoints/` |
-| RESEARCH | sessão | `.oxe/<active_session>/research/` | `.oxe/research/` |
-| WORKSTREAMS | sessão | `.oxe/<active_session>/workstreams/` | `.oxe/workstreams/` |
-</artifact_matrix>
-
-<reading_rule>
-## Regra de leitura
-
-- Quando um workflow ler um artefato da sua trilha, deve tentar primeiro o caminho da sessão ativa.
-- Se não houver sessão ativa, usar o caminho legado.
-- Se houver sessão ativa mas o artefato ainda não existir, o workflow pode:
-  - criar no caminho da sessão, se for writer da fase
-  - ou fazer fallback de leitura para o legado, quando isso preservar retrocompatibilidade e ajudar numa migração
-
-Exemplos:
-- `plan` lê `spec/SPEC.md` da sessão antes de cair para `.oxe/SPEC.md`
-- `verify` lê `plan/PLAN.md` e `spec/SPEC.md` da sessão antes do legado
-- `execute` lê sempre `.oxe/STATE.md` global **antes** de tudo, só para resolver `active_session`
-</reading_rule>
-
-<cross_session_refs>
-## Referências cruzadas
-
-- Em `SESSION.md`, referências a outras sessões usam o formato **`@sNNN`**
-- O texto pode complementar com o path, por exemplo: `@s003 ver sessions/s003-auth-hardening/SESSION.md`
-- Não existe sessão múltipla ativa: o formato `@sNNN` é apenas referência documental
-</cross_session_refs>
+# OXE — Referência: Session Path Resolution
+
+<objective>
+Padronizar a resolução de caminhos quando o projeto usa **sessões OXE** em `.oxe/sessions/`, preservando o modo legado quando **`.oxe/STATE.md`** não tiver `active_session`.
+</objective>
+
+<resolution_rule>
+## Regra de resolução
+
+1. Ler **`.oxe/STATE.md`** global.
+2. Procurar o campo **`active_session`** na secção **Sessão ativa**.
+3. Se existir e tiver valor diferente de `—`, usar:
+   - `session_path = .oxe/<active_session>/`
+   - `active_session` deve guardar sempre o path relativo completo, por exemplo: `sessions/s001-auth-redesign`
+4. Se não existir:
+   - `session_path = .oxe/`
+   - O workflow opera em **modo legado**
+
+## Convenções auxiliares
+
+- **global_state_path** = `.oxe/STATE.md`
+- **global_config_path** = `.oxe/config.json`
+- **global_codebase_path** = `.oxe/codebase/`
+- **global_sessions_index_path** = `.oxe/SESSIONS.md`
+- **global_lessons_path** = `.oxe/global/LESSONS.md`
+- **global_milestones_index_path** = `.oxe/global/MILESTONES.md`
+- **global_milestones_dir** = `.oxe/global/milestones/`
+</resolution_rule>
+
+<artifact_matrix>
+## Matriz de artefatos
+
+| Tipo | Escopo | Caminho com sessão ativa | Caminho legado |
+|------|--------|--------------------------|----------------|
+| STATE global | global | `.oxe/STATE.md` | `.oxe/STATE.md` |
+| Config | global | `.oxe/config.json` | `.oxe/config.json` |
+| Codebase | global | `.oxe/codebase/*` | `.oxe/codebase/*` |
+| SESSIONS | global | `.oxe/SESSIONS.md` | `.oxe/SESSIONS.md` |
+| LESSONS | global | `.oxe/global/LESSONS.md` | `.oxe/LESSONS.md` |
+| MILESTONES | global | `.oxe/global/MILESTONES.md` | `.oxe/MILESTONES.md` |
+| SPEC / ROADMAP / DISCUSS / UI-SPEC | sessão | `.oxe/<active_session>/spec/` | `.oxe/` |
+| PLAN / QUICK / plan-agents / quick-agents | sessão | `.oxe/<active_session>/plan/` | `.oxe/` |
+| STATE local / OBS / DEBUG / FORENSICS | sessão | `.oxe/<active_session>/execution/` | `.oxe/` |
+| VERIFY / VALIDATION-GAPS / SECURITY / UI-REVIEW | sessão | `.oxe/<active_session>/verification/` | `.oxe/` |
+| CHECKPOINTS | sessão | `.oxe/<active_session>/checkpoints/` | `.oxe/checkpoints/` |
+| RESEARCH | sessão | `.oxe/<active_session>/research/` | `.oxe/research/` |
+| WORKSTREAMS | sessão | `.oxe/<active_session>/workstreams/` | `.oxe/workstreams/` |
+</artifact_matrix>
+
+<reading_rule>
+## Regra de leitura
+
+- Quando um workflow ler um artefato da sua trilha, deve tentar primeiro o caminho da sessão ativa.
+- Se não houver sessão ativa, usar o caminho legado.
+- Se houver sessão ativa mas o artefato ainda não existir, o workflow pode:
+  - criar no caminho da sessão, se for writer da fase
+  - ou fazer fallback de leitura para o legado, quando isso preservar retrocompatibilidade e ajudar numa migração
+
+Exemplos:
+- `plan` lê `spec/SPEC.md` da sessão antes de cair para `.oxe/SPEC.md`
+- `verify` lê `plan/PLAN.md` e `spec/SPEC.md` da sessão antes do legado
+- `execute` lê sempre `.oxe/STATE.md` global **antes** de tudo, só para resolver `active_session`
+</reading_rule>
+
+<cross_session_refs>
+## Referências cruzadas
+
+- Em `SESSION.md`, referências a outras sessões usam o formato **`@sNNN`**
+- O texto pode complementar com o path, por exemplo: `@s003 ver sessions/s003-auth-hardening/SESSION.md`
+- Não existe sessão múltipla ativa: o formato `@sNNN` é apenas referência documental
+</cross_session_refs>

package/oxe/workflows/references/workflow-runtime-contracts.json

@@ -254,25 +254,25 @@
       ],
       "extraction_intent": "status_read"
     },
-    "dashboard": {
-      "reasoning_mode": "status",
-      "output_contract": "situational",
-      "required_artifacts": [
-        "state",
-        "phase_summary",
-        "project_summary"
-      ],
-      "optional_artifacts": [
-        "session_summary",
-        "plan",
-        "implementation_pack_json",
-        "reference_anchors",
-        "fixture_pack_json",
-        "runtime",
-        "verify",
-        "active_run",
-        "events",
-        "context_pack_dashboard"
+    "dashboard": {
+      "reasoning_mode": "status",
+      "output_contract": "situational",
+      "required_artifacts": [
+        "state",
+        "phase_summary",
+        "project_summary"
+      ],
+      "optional_artifacts": [
+        "session_summary",
+        "plan",
+        "implementation_pack_json",
+        "reference_anchors",
+        "fixture_pack_json",
+        "runtime",
+        "verify",
+        "active_run",
+        "events",
+        "context_pack_dashboard"
       ],
       "extraction_intent": "critical_check"
     },
@@ -322,72 +322,72 @@
         "canonical_state"
       ],
       "runtime_fallback_note": "Se o runtime não estiver compilado ou falhar por indisponibilidade do pacote, declarar fallback explícito para o fluxo legado antes de mutar.",
-      "required_artifacts": [
-        "state",
-        "runtime",
-        "checkpoints",
-        "implementation_pack_json",
-        "reference_anchors",
-        "fixture_pack_json"
-      ],
-      "optional_artifacts": [
-        "plan",
-        "quick",
-        "implementation_pack_md",
-        "fixture_pack_md",
-        "active_run",
-        "events",
-        "verify",
-        "summary",
-        "session_summary",
+      "required_artifacts": [
+        "state",
+        "runtime",
+        "checkpoints",
+        "implementation_pack_json",
+        "reference_anchors",
+        "fixture_pack_json"
+      ],
+      "optional_artifacts": [
+        "plan",
+        "quick",
+        "implementation_pack_md",
+        "fixture_pack_md",
+        "active_run",
+        "events",
+        "verify",
+        "summary",
+        "session_summary",
         "phase_summary",
         "project_summary",
         "capabilities_index",
         "azure_inventory"
       ],
-      "context_tiers": {
-        "minimal": [
-          "state",
-          "runtime",
-          "checkpoints",
-          "plan",
-          "implementation_pack_json",
-          "reference_anchors",
-          "fixture_pack_json",
-          "quick",
-          "phase_summary"
-        ],
-        "standard": [
-          "state",
-          "runtime",
-          "checkpoints",
-          "plan",
-          "implementation_pack_json",
-          "reference_anchors",
-          "fixture_pack_json",
-          "quick",
-          "phase_summary",
-          "session_summary",
-          "active_run",
-          "events",
+      "context_tiers": {
+        "minimal": [
+          "state",
+          "runtime",
+          "checkpoints",
+          "plan",
+          "implementation_pack_json",
+          "reference_anchors",
+          "fixture_pack_json",
+          "quick",
+          "phase_summary"
+        ],
+        "standard": [
+          "state",
+          "runtime",
+          "checkpoints",
+          "plan",
+          "implementation_pack_json",
+          "reference_anchors",
+          "fixture_pack_json",
+          "quick",
+          "phase_summary",
+          "session_summary",
+          "active_run",
+          "events",
           "verify",
           "summary"
         ],
         "full": [
-          "state",
-          "runtime",
-          "checkpoints",
-          "plan",
-          "implementation_pack_md",
-          "implementation_pack_json",
-          "reference_anchors",
-          "fixture_pack_md",
-          "fixture_pack_json",
-          "quick",
-          "active_run",
-          "events",
-          "verify",
-          "summary",
+          "state",
+          "runtime",
+          "checkpoints",
+          "plan",
+          "implementation_pack_md",
+          "implementation_pack_json",
+          "reference_anchors",
+          "fixture_pack_md",
+          "fixture_pack_json",
+          "quick",
+          "active_run",
+          "events",
+          "verify",
+          "summary",
           "session_summary",
           "phase_summary",
           "project_summary",
@@ -530,65 +530,65 @@
         "state",
         "spec"
       ],
-      "optional_artifacts": [
-        "discuss",
-        "investigations_index",
-        "project_summary",
-        "session_summary",
-        "phase_summary",
-        "global_lessons",
-        "capabilities_index",
-        "azure_inventory",
-        "checkpoints",
-        "calibration",
-        "implementation_pack_md",
-        "implementation_pack_json",
-        "reference_anchors",
-        "fixture_pack_md",
-        "fixture_pack_json"
-      ],
-      "context_tiers": {
-        "minimal": [
-          "state",
-          "spec",
+      "optional_artifacts": [
+        "discuss",
+        "investigations_index",
+        "project_summary",
+        "session_summary",
+        "phase_summary",
+        "global_lessons",
+        "capabilities_index",
+        "azure_inventory",
+        "checkpoints",
+        "calibration",
+        "implementation_pack_md",
+        "implementation_pack_json",
+        "reference_anchors",
+        "fixture_pack_md",
+        "fixture_pack_json"
+      ],
+      "context_tiers": {
+        "minimal": [
+          "state",
+          "spec",
           "session_summary",
           "phase_summary"
         ],
         "standard": [
-          "state",
-          "spec",
-          "session_summary",
-          "phase_summary",
-          "discuss",
-          "investigations_index",
-          "project_summary",
-          "global_lessons",
-          "capabilities_index",
-          "checkpoints",
-          "implementation_pack_json",
-          "reference_anchors",
-          "fixture_pack_json"
-        ],
-        "full": [
-          "state",
-          "spec",
-          "discuss",
+          "state",
+          "spec",
+          "session_summary",
+          "phase_summary",
+          "discuss",
+          "investigations_index",
+          "project_summary",
+          "global_lessons",
+          "capabilities_index",
+          "checkpoints",
+          "implementation_pack_json",
+          "reference_anchors",
+          "fixture_pack_json"
+        ],
+        "full": [
+          "state",
+          "spec",
+          "discuss",
           "investigations_index",
           "project_summary",
           "session_summary",
           "phase_summary",
-          "global_lessons",
-          "capabilities_index",
-          "azure_inventory",
-          "checkpoints",
-          "calibration",
-          "implementation_pack_md",
-          "implementation_pack_json",
-          "reference_anchors",
-          "fixture_pack_md",
-          "fixture_pack_json"
-        ]
-      },
+          "global_lessons",
+          "capabilities_index",
+          "azure_inventory",
+          "checkpoints",
+          "calibration",
+          "implementation_pack_md",
+          "implementation_pack_json",
+          "reference_anchors",
+          "fixture_pack_md",
+          "fixture_pack_json"
+        ]
+      },
       "extraction_intent": "planning_input"
     },
     "project": {