oxe-cc 0.6.4 → 0.6.6

package/oxe/workflows/next.md

@@ -1,28 +1,31 @@
 # OXE — Workflow: next
 
 <objective>
-Inspecionar `.oxe/STATE.md` e a existência de `SPEC.md`, `PLAN.md`, `QUICK.md`, `VERIFY.md` e `.oxe/codebase/` para recomendar **exatamente um** próximo passo OXE e **uma** frase de justificativa — sem lista de alternativas equiparáveis.
+Inspecionar `.oxe/STATE.md` global, a sessão ativa quando existir, e a existência de `SPEC.md`, `PLAN.md`, `QUICK.md`, `VERIFY.md` e `.oxe/codebase/` para recomendar **exatamente um** próximo passo OXE e **uma** frase de justificativa — sem lista de alternativas equiparáveis.
 </objective>
 
-<context>
-- O usuário pode rodar **`npx oxe-cc status`** no terminal para a mesma lógica resumida. **`npx oxe-cc status --hints`** (ou **`--json --hints`**) acrescenta lembretes **paralelos** (idade do scan/compact por config) — **não** altera o único passo canónico que este workflow deve devolver.
-- Se houver empate aparente (ex.: poderia ser spec ou quick), preferir **spec** quando já existir mapa de codebase; preferir **quick** só se o usuário deixar explícito que é correção mínima.
-- **Blueprint plan-agent:** se **`.oxe/plan-agents.json`** tiver `lifecycle.status === "invalidated"`, o próximo passo **não** assume papéis desse JSON; continuar a raciocinar só com **PLAN.md** / **QUICK.md** / **VERIFY.md** e **STATE.md**. Se o utilizador quiser de novo agentes + mensagens, indicar **`/oxe-plan-agent`**.
-</context>
+<context>
+- O usuário pode rodar **`npx oxe-cc status`** no terminal para a mesma lógica resumida. **`npx oxe-cc status --hints`** (ou **`--json --hints`**) acrescenta lembretes **paralelos** (idade do scan/compact por config) — **não** altera o único passo canónico que este workflow deve devolver.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, preferir os artefatos da sessão antes de olhar a raiz legada.
+- Se houver empate aparente (ex.: poderia ser spec ou quick), preferir **spec** quando já existir mapa de codebase; preferir **quick** só se o usuário deixar explícito que é correção mínima.
+- **Blueprint plan-agent:** se **`.oxe/plan-agents.json`** tiver `lifecycle.status === "invalidated"`, o próximo passo **não** assume papéis desse JSON; continuar a raciocinar só com **PLAN.md** / **QUICK.md** / **VERIFY.md** e **STATE.md**. Se o utilizador quiser de novo agentes + mensagens, indicar **`/oxe-plan-agent`**.
+- Priorizar sempre o passo que **reduz incerteza primeiro**. Se o plano existente não for o melhor plano atual ou estiver abaixo do limiar de confiança, o próximo passo não pode ser `execute`.
+</context>
 
 <process>
 1. Se `.oxe/` ou `STATE.md` não existir → **único** passo: **scan** (ou `oxe-cc init-oxe` seguido de scan).
 2. Se não houver `.oxe/codebase/*.md` completos (sete mapas) e o trabalho **não** for só um quick isolado → **scan**.
-3. Se fase `quick_active` ou existir `QUICK.md` **sem** `PLAN.md`:
+3. Se fase `quick_active` ou existir `QUICK.md` no escopo resolvido **sem** `PLAN.md`:
    - Se `QUICK.md` contiver linha `Promover para spec/plan?: sim` → **spec** (promoção declarada pelo autor; ignorar demais heurísticas).
    - Se o `QUICK.md` tiver **mais de 10 passos**, ou o utilizador/descrição indicar **contrato público**, **segurança**, **dados pessoais**, ou **>8 ficheiros** tocados ou previstos → **spec** (promoção obrigatória).
    - Senão → **execute** (há passos curtos a implementar).
-4. Se não houver `SPEC.md` e não for quick intencional declarado → **spec** (passo único).
-5. Se houver SPEC mas não PLAN → se `.oxe/config.json` tiver `discuss_before_plan: true` e faltar **`.oxe/DISCUSS.md`** com decisões → **discuss**; senão → **plan**.
-6. Se PLAN existe, **VERIFY.md** ainda **não** existe ou está claramente antes da implementação atual → **execute** (onda atual).
-7. Se PLAN existe e VERIFY falta após implementação declarada → **verify**.
-8. Se VERIFY indica falha ou gaps não resolvidos → **plan** (replanejamento) como passo único, com referência a `SUMMARY.md`.
-9. Se VERIFY OK e estado coerente → **spec** ou **quick** para **próxima** entrega, ou mensagem “fluxo da feature atual concluído”.
+4. Se não houver `SPEC.md` no escopo resolvido e não for quick intencional declarado → **spec** (passo único).
+5. Se houver SPEC no escopo resolvido mas não PLAN → se `.oxe/config.json` tiver `discuss_before_plan: true` e faltar **`DISCUSS.md`** com decisões → **discuss**; senão → **plan**.
+6. Se PLAN existe mas a seção **Autoavaliação do Plano** disser `Melhor plano atual: não`, ou a `Confiança` estiver abaixo do limiar configurado (padrão 70%), o próximo passo deve ser **plan** (replanejar) ou **discuss/research** se a própria autoavaliação indicar isso.
+7. Se PLAN existe, **VERIFY.md** ainda **não** existe ou está claramente antes da implementação atual → **execute** (onda atual).
+8. Se PLAN existe e VERIFY falta após implementação declarada → **verify**.
+9. Se VERIFY indica falha ou gaps não resolvidos → **plan** (replanejamento) como passo único, com referência a `SUMMARY.md`.
+10. Se VERIFY OK e estado coerente → **spec** ou **quick** para **próxima** entrega, ou mensagem “fluxo da feature atual concluído”.
 
 **Saída obrigatória (só isto, nesta ordem):**
 

package/oxe/workflows/obs.md

@@ -8,16 +8,17 @@ Registrar uma **observação contextual** em **`.oxe/OBSERVATIONS.md`** durante
 Entrada: texto livre com a observação (restrição, descoberta técnica, preferência, risco, decisão).
 </objective>
 
-<context>
+<context>
 - Pode ser chamado **a qualquer momento**: antes, durante ou após qualquer passo da trilha OXE.
 - Não interrompe o fluxo em curso — a observação é armazenada e incorporada na próxima oportunidade.
-- Se chamado **durante execute** (fase `executing` no STATE) com impacto `execute` ou `all`: oferecer opção de aplicar agora (pausar onda atual) ou continuar e aplicar na próxima rodada.
-- Ler **`.oxe/STATE.md`** para capturar o contexto automático (fase atual, tarefa ativa, workstream ativo).
-- Usar `oxe/templates/OBSERVATIONS.template.md` para criar o arquivo se ainda não existir.
-</context>
+- Se chamado **durante execute** (fase `executing` no STATE) com impacto `execute` ou `all`: oferecer opção de aplicar agora (pausar onda atual) ou continuar e aplicar na próxima rodada.
+- Ler **`.oxe/STATE.md`** para capturar o contexto automático (fase atual, tarefa ativa, workstream ativo).
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `OBSERVATIONS.md` vive em `.oxe/<active_session>/execution/`; sem sessão ativa, manter `.oxe/`.
+- Usar `oxe/templates/OBSERVATIONS.template.md` para criar o arquivo se ainda não existir.
+</context>
 
 <format_observations_md>
-Arquivo: **`.oxe/OBSERVATIONS.md`**
+Arquivo: **`OBSERVATIONS.md`** no escopo resolvido da sessão
 
 ```markdown
 # Observações OXE
@@ -69,14 +70,14 @@ Se ambíguo, usar `all` (princípio de maior abrangência).
 
 <process>
 1. Ler **`.oxe/STATE.md`**: capturar `phase`, `last_task` ou tarefa ativa na onda, `active_workstream`.
-2. Determinar o **próximo ID** (OBS-NNN): contar entradas existentes em `.oxe/OBSERVATIONS.md` ou começar em OBS-001.
+2. Determinar o **próximo ID** (OBS-NNN): contar entradas existentes em `OBSERVATIONS.md` do escopo resolvido ou começar em OBS-001.
 3. Classificar o **impacto** automaticamente com base no texto; se ambíguo, usar `all`.
 3b. **Propagação automática de constraints:**
    - Se existir **`.oxe/SPEC.md`**: ler a tabela de requisitos (R-ID) e critérios (A*) e identificar quais são diretamente afetados pelo texto da observação. Registrar em `**Afeta (spec):**`.
    - Se existir **`.oxe/PLAN.md`**: ler as tarefas (Tn) e identificar quais podem precisar de ajuste no campo `Verificar` ou `Implementar`. Registrar em `**Afeta (plan):**`.
    - Se nenhum R-ID ou Tn identificável: registrar `**Afeta:** (a cruzar na próxima incorporação)`.
    - Esta propagação é automática e não requer input do usuário.
-4. Criar ou atualizar **`.oxe/OBSERVATIONS.md`**:
+4. Criar ou atualizar **`OBSERVATIONS.md`** no escopo resolvido:
    - Adicionar linha na tabela de índice.
    - Adicionar seção `### OBS-NNN` com contexto, impacto, status e texto.
 5. Avaliar **urgência**:

package/oxe/workflows/plan-agent.md

@@ -3,7 +3,7 @@
 <objective>
 Produzir **dois artefactos alinhados**:
 
-1. **`.oxe/PLAN.md`** — mesmo contrato que o workflow **`plan.md`** (tarefas `Tn`, **Onda**, **Depende de**, **Verificar**, **Aceite vinculado**), para **`/oxe-execute`**, **`/oxe-verify`** e gates OXE existentes.
+1. **`.oxe/PLAN.md`** — mesmo contrato que o workflow **`plan.md`** (tarefas `Tn`, **Onda**, **Depende de**, **Verificar**, **Aceite vinculado**, **Autoavaliação do Plano** com rubrica e confiança determinística), para **`/oxe-execute`**, **`/oxe-verify`** e gates OXE existentes.
 2. **`.oxe/plan-agents.json`** — **blueprint de execução**: objetivo, **agentes** (papéis, âmbito, entradas/saídas esperadas, dependências entre agentes), **estratégia em ondas** (`execution.waves`), **`runId`** e **`lifecycle`** (schema **2**).
 
 O plano **não** é só uma lista de tarefas: cada agente é um **pacote de contexto** (o que ler, o que produzir, que `Tn` cobre). A execução real continua a ser feita pelo utilizador ou por subagentes da IDE, guiados por este blueprint e pelo `PLAN.md`.
@@ -13,8 +13,10 @@ O plano **não** é só uma lista de tarefas: cada agente é um **pacote de cont
 Se o utilizador pedir **`--replan`**: aplicar a mesma lógica de replanejamento descrita em **`plan.md`** (VERIFY, SUMMARY, secção Replanejamento) e **atualizar ou recriar** `plan-agents.json` em coerência com o novo `PLAN.md`; gerar **novo** `runId` e repor `lifecycle.status` → `pending_execute`. Se ainda existir pasta **`.oxe/plan-agent-messages/`** cheia do **run** anterior e o utilizador não precisar dela na raiz, **arquivar** primeiro em **`.oxe/archive/plan-agent-runs/<runId-antigo>/`** (ver **`references/plan-agent-chat-protocol.md`**) ou pedir confirmação antes de sobrescrever; depois recriar **`.oxe/plan-agent-messages/README.md`** para o novo `runId`.
 </objective>
 
-<context>
-- **Pré-requisitos** iguais a **`plan.md`**: `.oxe/SPEC.md` obrigatória; `discuss_before_plan` + `DISCUSS.md` quando configurado; consumir **NOTES**, **UI-SPEC**, **DISCUSS**, **RESEARCH**, **CODEBASE-DELTA** / **RESUME**, **config.json** (`plan_max_tasks_per_wave`, `default_verify_command`) como em **`plan.md`**.
+<context>
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `PLAN.md`, `plan-agents.json` e `plan-agent-messages/` vivem em `.oxe/<active_session>/plan/`; sem sessão ativa, manter `.oxe/`.
+- O `plan-agent` herda integralmente o contrato `oxe/workflows/references/flow-robustness-contract.md`. Não pode emitir percentuais concorrentes por agente; a confiança final do plano é única e visível no `PLAN.md`.
+- **Pré-requisitos** iguais a **`plan.md`**: `.oxe/SPEC.md` obrigatória; `discuss_before_plan` + `DISCUSS.md` quando configurado; consumir **NOTES**, **UI-SPEC**, **DISCUSS**, **RESEARCH**, **CODEBASE-DELTA** / **RESUME**, **config.json** (`plan_max_tasks_per_wave`, `default_verify_command`) como em **`plan.md`**.
 - **Fonte de verdade das tarefas:** `PLAN.md`. O JSON referencia tarefas via **`taskIds`** em cada agente — **não** duplicar o texto de **Verificar** no JSON; copiar só paths/resumo curto em **`outputs`** quando útil para routing.
 - **Agentes ≠ ferramentas externas fixas:** `role` e `scope` descrevem o **comportamento esperado** de um contexto focado (ex.: “Backend Auth Specialist”), não um binário. Quem executa pode ser um único modelo com instruções diferentes por onda.
 - **Protocolo agente → agente:** **`oxe/workflows/references/plan-agent-chat-protocol.md`** — mensagens em **`.oxe/plan-agent-messages/`** (ficheiros `W{onda}-{seq}-{from}-to-{dest}.md` com frontmatter YAML). Criar a pasta e copiar o índice a partir de **`oxe/templates/plan-agent-messages-README.template.md`** → `.oxe/plan-agent-messages/README.md`.
@@ -125,7 +127,7 @@ Resumo obrigatório no chat: `Gate plan-agent: OK` ou `Gate plan-agent: corrigid
 3. Escrever **`.oxe/PLAN.md`** (cabeçalho YAML como em `oxe/templates/PLAN.template.md`; em **--replan**, secção Replanejamento).
 4. Gerar **`runId`** novo e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO agora>" }`.
 5. Escrever **`.oxe/plan-agents.json`** a partir de **`oxe/templates/plan-agents.template.json`**, com **`oxePlanAgentsSchema: 3`**, `goal`, `agents` (incluindo `model_hint` por agente conforme `<model_hints>`), `execution`, `runId`, `lifecycle`.
-6. Criar **`.oxe/plan-agent-messages/`** e **`.oxe/plan-agent-messages/README.md`** a partir de **`oxe/templates/plan-agent-messages-README.template.md`**.
+6. Criar `plan-agent-messages/` e `plan-agent-messages/README.md` no escopo resolvido a partir de **`oxe/templates/plan-agent-messages-README.template.md`**.
 7. Atualizar **`.oxe/STATE.md`**: fase `plan_ready`, próximo passo `oxe:execute`; preencher **Blueprint de agentes (sessão)** — `run_id` (= `runId`), `lifecycle_status` (= `pending_execute`), **última onda** — (ou `—`).
 8. Aplicar **`<plan_agent_quality_gate>`**; corrigir até passar.
 9. No chat: resumo do gate plan-agent, `runId`, número de agentes, ondas, tarefas, referência ao protocolo em **`references/plan-agent-chat-protocol.md`**.

package/oxe/workflows/plan.md

@@ -3,24 +3,26 @@
 <objective>
 Produzir **`.oxe/PLAN.md`**: tarefas **pequenas**, **ondas** (paralelizáveis vs sequenciais), e **cada tarefa com bloco de verificação** (comando de teste e/ou checklist manual).
 
-Base: `.oxe/SPEC.md` (critérios com IDs **A1**, **A2**, …) + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
+Base: `SPEC.md` do escopo resolvido da sessão (critérios com IDs **A1**, **A2**, …) + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
 
 Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_failed`):
-- Ler **`.oxe/VERIFY.md`** (gaps e falhas), **`.oxe/SUMMARY.md`** se existir, e o **PLAN.md** atual.
+- Ler `VERIFY.md` e `SUMMARY.md` do escopo resolvido, e o `PLAN.md` atual.
 - Preservar tarefas já concluídas ou renumerar com nota em **Replanejamento**; não apagar histórico útil — deslocar para a seção **Replanejamento** e reescrever **Tarefas** conforme necessário.
 - Se **SUMMARY.md** não existir, criar a partir de `oxe/templates/SUMMARY.template.md` para registrar o contexto do replan (ou dar append se já existir).
 </objective>
 
-<context>
-- Se existir **`.oxe/OBSERVATIONS.md`** com entradas `pendente` de impacto `plan` ou `all`, incorporar nas tarefas relevantes antes de finalizar o plano (ajustar implementação, verificação ou escopo de Tn) e marcar essas entradas como `incorporada → plan (data)`.
-- Se existir **`.oxe/LESSONS.md`**, ler entradas com `Aplicar em: /oxe-plan` e `Status: ativo`. Aplicar como restrições explícitas no planejamento: ajuste de complexidade de tarefas, padrões de verificação, escolha de modo solo vs agentes. Registrar aplicações como comentário no PLAN.md: `<!-- lição C-NN aplicada: ... -->`.
+<context>
+- Seguir `oxe/workflows/references/flow-robustness-contract.md` como contrato canónico de robustez. A ordem obrigatória é: ler artefatos, resolver sessão/paths, validar pré-condições, escrever o plano, autoavaliar o plano, registrar próximo passo único.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, o plano vive em `.oxe/<active_session>/plan/` e lê a spec em `.oxe/<active_session>/spec/`.
+- Se existir `OBSERVATIONS.md` do escopo resolvido com entradas `pendente` de impacto `plan` ou `all`, incorporar nas tarefas relevantes antes de finalizar o plano (ajustar implementação, verificação ou escopo de Tn) e marcar essas entradas como `incorporada → plan (data)`.
+- Se existir **`.oxe/global/LESSONS.md`**, ler entradas com `Aplicar em: /oxe-plan` e `Status: ativo`. Aplicar como restrições explícitas no planejamento: ajuste de complexidade de tarefas, padrões de verificação, escolha de modo solo vs agentes. Registrar aplicações como comentário no PLAN.md: `<!-- lição C-NN aplicada: ... -->`.
 - **LESSONS + OBS juntos:** se houver tanto LESSONS quanto OBS pendentes, LESSONS orientam o *como planejar* e OBS orientam o *o que incluir*. Não confundir os papéis.
 - Não inventar APIs inexistentes: cruzar com **STRUCTURE.md**, **INTEGRATIONS.md** e arquivos reais; respeitar **CONCERNS.md** (evitar agravar dívida conhecida sem tarefa explícita).
 - Se existir **`.oxe/NOTES.md`**, rever entradas em aberto: incorporar em tarefas (com **Aceite vinculado** quando aplicável) ou registar na secção **Replanejamento** / nota explícita *fora de âmbito desta trilha*.
-- Se existir **`.oxe/UI-SPEC.md`**, as tarefas de UI devem referenciar secções do UI-SPEC no texto de **Implementação** ou **Verificar**.
-- Se existir **`.oxe/DISCUSS.md`**, alinhar tarefas às decisões registradas. Referenciar IDs **D-NN** no campo **Decisão vinculada:** de cada tarefa impactada — se nenhuma decisão impactar a tarefa, omitir o campo. A rastreabilidade D-NN → Tn → verify é usada pela seção **Fidelidade de decisões** do verify.
-- Se existir **`.oxe/RESEARCH.md`** e notas em **`.oxe/research/*.md`**, ler o índice e as notas cujo **Tema** cruza o âmbito do plano (ou as mais recentes relevantes). Se o índice marcar **Estado** pendente em tópico bloqueante, pedir nova sessão **research** ou **discuss**, ou registar **suposição explícita** no PLAN antes de ondas que dependam dessa decisão.
-- Se existir **`.oxe/plan-agents.json`** (gerado por **`/oxe-plan-agent`**), um **--replan** ou renumerar tarefas deve **atualizar o JSON em conjunto** com o `PLAN.md` (cobertura `taskIds`, ondas e dependências entre agentes) — ver **`oxe/workflows/plan-agent.md`**. Preferir **`/oxe-plan-agent --replan`** para regerar **`runId`**, **`lifecycle`** (`pending_execute`) e alinhar **STATE.md**; se só **`/oxe-plan`** for usado, ou o JSON fica manualmente sincronizado, ou marcar no JSON `lifecycle.invalidatedBy: new_plan` até novo plan-agent.
+- Se existir `UI-SPEC.md` no escopo resolvido, as tarefas de UI devem referenciar secções do UI-SPEC no texto de **Implementação** ou **Verificar**.
+- Se existir `DISCUSS.md` no escopo resolvido, alinhar tarefas às decisões registradas. Referenciar IDs **D-NN** no campo **Decisão vinculada:** de cada tarefa impactada — se nenhuma decisão impactar a tarefa, omitir o campo. A rastreabilidade D-NN → Tn → verify é usada pela seção **Fidelidade de decisões** do verify.
+- Se existir `RESEARCH.md` e notas em `research/*.md` do escopo resolvido, ler o índice e as notas cujo **Tema** cruza o âmbito do plano (ou as mais recentes relevantes). Se o índice marcar **Estado** pendente em tópico bloqueante, pedir nova sessão **research** ou **discuss**, ou registar **suposição explícita** no PLAN antes de ondas que dependam dessa decisão.
+- Se existir `plan-agents.json` no escopo resolvido (gerado por **`/oxe-plan-agent`**), um **--replan** ou renumerar tarefas deve **atualizar o JSON em conjunto** com o `PLAN.md` (cobertura `taskIds`, ondas e dependências entre agentes) — ver **`oxe/workflows/plan-agent.md`**. Preferir **`/oxe-plan-agent --replan`** para regerar **`runId`**, **`lifecycle`** (`pending_execute`) e alinhar **STATE.md**; se só **`/oxe-plan`** for usado, ou o JSON fica manualmente sincronizado, ou marcar no JSON `lifecycle.invalidatedBy: new_plan` até novo plan-agent.
 - Se existirem **`.oxe/CODEBASE-DELTA.md`** e/ou **`.oxe/RESUME.md`** (tipicamente após **`/oxe-compact`**), ler **antes** de detalhar tarefas: o delta resume o que mudou nos mapas face ao código; o RESUME ancora fase e trilha OXE — **não** substituem SPEC nem os sete ficheiros em `codebase/`.
 - Se existir **`.oxe/config.json`** com `default_verify_command` não vazio, usar como fallback quando a SPEC não indicar comando.
 - Se existir **`plan_max_tasks_per_wave` > 0** na config, **não** colocar mais tarefas do que esse número na mesma **Onda**; dividir em mais ondas.
@@ -29,7 +31,7 @@ Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_fai
 </context>
 
 <format_plan>
-Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de Implementar** (test-first):
+Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de Implementar** (test-first):
 
 ```markdown
 ### Tn — título curto
@@ -44,10 +46,44 @@ Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de I
 - **Aceite vinculado:** A1, A2 (IDs exatos da tabela de critérios da SPEC)
 - **Decisão vinculada:** D-01, D-02 (IDs de `.oxe/DISCUSS.md` — omitir se não houver DISCUSS)
 <!-- oxe-task: {"id":"Tn","wave":1,"type":"feature","files":[],"done":false,"complexity":"S"} -->
-```
-
-**Escala de Complexidade:**
-| Valor | Esforço estimado | Sinal de alerta |
+```
+
+Depois do resumo e antes das tarefas, o `PLAN.md` deve conter também:
+
+```markdown
+## Autoavaliação do Plano
+- **Melhor plano atual:** sim | não
+- **Confiança:** 0–100%
+- **Base da confiança:**
+  - Completude dos requisitos: NN/25
+  - Dependências conhecidas: NN/15
+  - Risco técnico: NN/20
+  - Impacto no código existente: NN/15
+  - Clareza da validação / testes: NN/15
+  - Lacunas externas / decisões pendentes: NN/10
+- **Principais incertezas:** ...
+- **Alternativas descartadas:** ...
+- **Condição para replanejar:** ...
+```
+
+**Rubrica fixa de confiança (determinística):**
+| 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 |
+
+**Faixas semânticas obrigatórias:**
+- `85–100%` → pronto para executar
+- `70–84%` → executável com risco controlado
+- `50–69%` → precisa refino antes de execução
+- `<50%` → não executar
+
+**Escala de Complexidade:**
+| Valor | Esforço estimado | Sinal de alerta |
 |-------|-----------------|-----------------|
 | `S` | < 30 min, 1–2 arquivos | — |
 | `M` | < 2h, 2–5 arquivos | — |
@@ -66,31 +102,36 @@ Antes de finalizar a resposta ao utilizador, o agente **deve** percorrer este ga
 
 1. **Depende de:** em cada `### Tn`, apenas IDs `Tk` que existem no mesmo ficheiro, ou `—`.
 2. **Ciclos:** não há cadeia circular óbvia (ex.: T2→T3→T2); se houver, quebrar dependência ou onda.
-3. **Cobertura A*:** todos os IDs da tabela de critérios em `.oxe/SPEC.md` aparecem em **Aceite vinculado:** de alguma tarefa, ou há nota explícita de **gap** no PLAN (fora de âmbito / adiado) por ID.
+3. **Cobertura A*:** todos os IDs da tabela de critérios em `SPEC.md` do escopo resolvido aparecem em **Aceite vinculado:** de alguma tarefa, ou há nota explícita de **gap** no PLAN (fora de âmbito / adiado) por ID.
 4. **Ondas:** cada número de **Onda:** usado tem pelo menos uma tarefa; sem ondas vazias.
 5. **`plan_max_tasks_per_wave`:** se `.oxe/config.json` tiver valor **> 0**, contar tarefas por **Onda**; nenhuma onda excede o limite.
-6. **UI-SPEC:** se existir `.oxe/UI-SPEC.md`, toda tarefa cuja **Implementar** ou **Verificar** toque UI deve citar **secção § do UI-SPEC** ou path explícito.
-7. **Fidelidade de decisões:** se existir `.oxe/DISCUSS.md` com IDs **D-NN**, cada decisão com impacto técnico deve aparecer em **Decisão vinculada:** de alguma tarefa, ou ter nota explícita de gap. Sem cobertura para D-NN técnico = falha do gate.
-8. **Complexidade XL:** toda tarefa com `Complexidade: XL` deve ter sub-tarefas explícitas (ex.: T3.1, T3.2 — como bullets dentro da tarefa) **ou** justificativa na tarefa explicando por que não pode ser quebrada. Tarefa XL sem sub-tarefas e sem justificativa = falha do gate.
-9. **Test-first:** em toda tarefa, `Verificar` deve preceder `Implementar` no texto. Se a ordem estiver invertida, corrigir antes de finalizar.
-
-Se após correções estruturais persistir ambiguidade de produto: **uma** frase recomendando `oxe:discuss` ou `oxe:spec`.
-
-Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N problemas)`.
+6. **UI-SPEC:** se existir `UI-SPEC.md` no escopo resolvido, toda tarefa cuja **Implementar** ou **Verificar** toque UI deve citar **secção § do UI-SPEC** ou path explícito.
+7. **Fidelidade de decisões:** se existir `DISCUSS.md` com IDs **D-NN** no escopo resolvido, cada decisão com impacto técnico deve aparecer em **Decisão vinculada:** de alguma tarefa, ou ter nota explícita de gap. Sem cobertura para D-NN técnico = falha do gate.
+8. **Complexidade XL:** toda tarefa com `Complexidade: XL` deve ter sub-tarefas explícitas (ex.: T3.1, T3.2 — como bullets dentro da tarefa) **ou** justificativa na tarefa explicando por que não pode ser quebrada. Tarefa XL sem sub-tarefas e sem justificativa = falha do gate.
+9. **Test-first:** em toda tarefa, `Verificar` deve preceder `Implementar` no texto. Se a ordem estiver invertida, corrigir antes de finalizar.
+10. **Autoavaliação presente:** o `PLAN.md` contém `## Autoavaliação do Plano`, `Melhor plano atual`, `Confiança`, rubrica completa e `Condição para replanejar`.
+11. **Calibração de execução:** se `Melhor plano atual: não` ou `Confiança < limiar configurado`, o plano não pode recomendar execução direta; deve recomendar refino, discuss ou research.
+12. **Rastreabilidade de evidência:** cada tarefa deve ter entrada observável de origem na SPEC, no codebase, em DISCUSS, OBS, RESEARCH ou LESSONS; tarefa sem evidência de entrada explícita = falha do gate.
+13. **Mudanças de risco:** tarefas com risco relevante (migração, auth, schema, contrato público, segurança) devem incluir contenção, rollback, fallback ou verificação reforçada.
+
+Se após correções estruturais persistir ambiguidade de produto: **uma** frase recomendando `oxe:discuss` ou `oxe:spec`.
+
+Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N problemas)`.
 </plan_quality_gate>
 
 <process>
-1. Ler `.oxe/SPEC.md` (obrigatório). Se faltar, pedir **spec** primeiro.
-2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `.oxe/DISCUSS.md` com decisões fechadas, pedir **discuss** antes de planejar.
+1. Resolver `active_session` e ler `SPEC.md` do escopo correto (obrigatório). Se faltar, pedir **spec** primeiro.
+2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `DISCUSS.md` no escopo resolvido com decisões fechadas, pedir **discuss** antes de planejar.
 3. Se existir **`.oxe/NOTES.md`**, consumir ou explicitamente adiar cada bullet relevante (ver **context**).
 4. Ler `.oxe/codebase/*.md` (incl. CONVENTIONS / CONCERNS) e inspecionar pontos de entrada se a spec exigir.
-5. Escrever ou atualizar `.oxe/PLAN.md` usando `oxe/templates/PLAN.template.md` como cabeçalho; **preservar** YAML inicial (`oxe_doc: plan`, `status`, `inputs`) se já existir e **atualizar** `updated:` (ISO); em **--replan**, preencher a seção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
-6. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes; respeitar `plan_max_tasks_per_wave` se configurado.
-7. Aplicar integralmente o bloco **`<plan_quality_gate>`** acima ao `PLAN.md` em disco; corrigir o ficheiro até passar ou documentar gaps explícitos.
-8. Atualizar `.oxe/STATE.md`: fase `plan_ready`, próximo passo `oxe:execute` (implementar ondas) e depois `oxe:verify`.
-9. **Sugestão de agentes (inteligente):** após o gate passar, verificar se o plano tem 3+ domínios distintos (ex.: backend + frontend + DB, ou auth + notificações + UI). Se sim, sugerir proativamente: "Este plano tem N domínios distintos. Quer gerar um blueprint de agentes com `/oxe-plan --agents`?" — não executar automaticamente, apenas oferecer. Se o usuário incluiu `--agents` no input original, executar imediatamente a lógica de `oxe/workflows/plan-agent.md`.
-10. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
-</process>
+5. Escrever ou atualizar `PLAN.md` no escopo resolvido usando `oxe/templates/PLAN.template.md` como cabeçalho; **preservar** YAML inicial (`oxe_doc: plan`, `status`, `inputs`) se já existir e **atualizar** `updated:` (ISO); em **--replan**, preencher a seção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
+6. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes; respeitar `plan_max_tasks_per_wave` se configurado.
+7. Preencher `## Autoavaliação do Plano` com a rubrica fixa. A confiança é a soma ponderada das seis dimensões; não inventar percentagem sem justificar os pontos.
+8. Aplicar integralmente o bloco **`<plan_quality_gate>`** acima ao `PLAN.md` em disco; corrigir o ficheiro até passar ou documentar gaps explícitos.
+9. Atualizar `.oxe/STATE.md` global: fase `plan_ready`, próximo passo `oxe:execute` apenas se `Melhor plano atual: sim` e a confiança estiver no limiar executável; caso contrário, próximo passo deve reduzir incerteza (`oxe:discuss`, `oxe:research` ou replanejamento).
+10. **Sugestão de agentes (inteligente):** após o gate passar, verificar se o plano tem 3+ domínios distintos (ex.: backend + frontend + DB, ou auth + notificações + UI). Se sim, sugerir proativamente: "Este plano tem N domínios distintos. Quer gerar um blueprint de agentes com `/oxe-plan --agents`?" — não executar automaticamente, apenas oferecer. Se o usuário incluiu `--agents` no input original, executar imediatamente a lógica de `oxe/workflows/plan-agent.md`.
+11. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver, melhor-plano-atual e confiança.
+</process>
 
 <success_criteria>
 - [ ] Cada tarefa tem seção **Verificar** com comando ou checklist explícito.

package/oxe/workflows/project.md

@@ -14,7 +14,7 @@ Detecta a operação pelo primeiro token do input e delega ao workflow canônico
 - Este workflow é um **dispatcher**: lê o input, identifica a operação e executa o workflow correto.
 - Workflows canônicos: `oxe/workflows/milestone.md`, `oxe/workflows/workstream.md`, `oxe/workflows/checkpoint.md`.
 - Se o input for ambíguo, apresentar as 3 operações disponíveis e pedir escolha.
-- Sem input: mostrar o estado atual de milestones e workstreams ativos lendo `STATE.md`, `MILESTONES.md` e `CHECKPOINTS.md`.
+- Sem input: mostrar o estado atual de milestones e workstreams ativos lendo `STATE.md`, `.oxe/global/MILESTONES.md` e `CHECKPOINTS.md` do escopo atual da sessão.
 </context>
 
 <dispatch_table>

package/oxe/workflows/quick.md

@@ -8,8 +8,10 @@ Quando o trabalho envolve **2 ou mais domínios distintos** (ex.: backend + fron
 Usar quando: correção pontual, refactor local, feature pequena ou protótipo que **não** justifica critérios de aceite completos.
 </objective>
 
-<context>
-- Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
+<context>
+- Seguir `oxe/workflows/references/flow-robustness-contract.md`. Quick continua leve, mas não pode fingir que existe plano formal quando ele não existe.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `QUICK.md` e `quick-agents.json` vivem em `.oxe/<active_session>/plan/`; sem sessão ativa, manter `.oxe/`.
+- Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
 - Não apagar `SPEC.md` / `PLAN.md` se existirem; este fluxo é paralelo ou temporário.
 - **Blueprint plan-agent:** este fluxo **não** reutiliza papéis (`role` / `scope`) de **`.oxe/plan-agents.json`**. Se existir `plan-agents.json` com **`oxePlanAgentsSchema: 2`** e `lifecycle.status` **não** for já `invalidated`, **invalidar** o blueprint após criar/substituir **`QUICK.md`**: `lifecycle: { "status": "invalidated", "since": "<ISO>", "invalidatedBy": "quick", "invalidatedReason": "oxe-quick substitui trilha focada do blueprint" }`. Actualizar **`.oxe/STATE.md`** — secção **Blueprint de agentes (sessão)**: **lifecycle_status** → `invalidated`, nota "invalidado por quick". Não escrever novas mensagens em **`.oxe/plan-agent-messages/`** para o `runId` invalidado.
 - **Quick-agents anterior:** se existir **`.oxe/quick-agents.json`** com `status` diferente de `done` ou `invalidated`, invalidá-lo antes de criar o novo (`status: "invalidated", "since": "<ISO>", "reason": "novo quick iniciado"`).
@@ -119,7 +121,8 @@ Uso **sem** novo slash: é o mesmo `/oxe-quick` com redação mínima.
 - **Passos** — lista numerada, **máximo 10**; cada passo acionável numa linha.
 - **Verificar** — um comando de terminal **ou** checklist manual explícito.
 - **Agentes dinâmicos** — seção opcional quando PDDA estiver ativo (ver acima).
-- **Promover para spec/plan?** — preencher sempre; se qualquer gatilho abaixo for verdadeiro, resposta **sim** e parar de acumular trabalho no QUICK — passar a **`/oxe-spec`** (e depois discuss/plan conforme config).
+- **Promover para spec/plan?** — preencher sempre; se qualquer gatilho abaixo for verdadeiro, resposta **sim** e parar de acumular trabalho no QUICK — passar a **`/oxe-spec`** (e depois discuss/plan conforme config).
+- **Confiança formal do plano:** se ainda não houver `PLAN.md`, declarar explicitamente no QUICK que **não houve plano formal**; não inventar percentagem de confiança aqui.
 
 O perfil fast **não** é uma segunda trilha: continua sujeito à mesma promoção obrigatória quando o trabalho deixa de ser trivial.
 
@@ -140,16 +143,17 @@ No final de **`.oxe/QUICK.md`**, mantenha a linha:
 Se **sim**, o próximo passo recomendado no chat é **`/oxe-spec`** (depois discuss/plan conforme config).
 
 <process>
-1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir). Verificar **`.oxe/OBSERVATIONS.md`** — se houver entradas `pendente` com impacto `all`, registrar como restrições nos **Passos** ou no **Contexto** do QUICK.md antes de finalizar; marcar as OBS como `incorporada → quick (data)`.
+1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir). Verificar `OBSERVATIONS.md` do escopo resolvido — se houver entradas `pendente` com impacto `all`, registrar como restrições nos **Passos** ou no **Contexto** do QUICK.md antes de finalizar; marcar as OBS como `incorporada → quick (data)`.
 2. Avaliar se PDDA lean se aplica (ver `<plan_driven_dynamic_agents_lean>` — domínios distintos, 5+ passos, ou flag `--agents`).
-3. Criar ou substituir **`.oxe/QUICK.md`** com:
+3. Criar ou substituir **`QUICK.md`** no escopo resolvido com:
    - **Objetivo** — uma frase. *(Esta é a minispec: restringe o escopo de todos os agentes e passos.)*
    - **Contexto** — 2–5 bullets (arquivos/pastas já vistos).
    - **Passos** — lista numerada, **máximo 10** passos acionáveis; se PDDA ativo, anotar `<!-- agente: id -->` em cada passo.
    - **Agentes dinâmicos** *(somente se PDDA ativo)* — tabela com ID, papel, steps, persona.
    - **Verificar** — pelo menos um: comando de terminal (ex.: `npm test`) **ou** checklist manual explícito. *(Este é o critério de aceite da minispec.)*
-   - **Promover para spec/plan?** — conforme seção acima.
-4. Se PDDA ativo, criar **`.oxe/quick-agents.json`** usando `oxe/templates/quick-agents.template.json`:
+   - **Promover para spec/plan?** — conforme seção acima.
+   - **Plano formal existente?** — `não`; usar `sim` apenas se este quick estiver ancorado a um `PLAN.md` já aprovado no mesmo escopo.
+4. Se PDDA ativo, criar **`quick-agents.json`** no escopo resolvido usando `oxe/templates/quick-agents.template.json`:
    - Gerar `quickId` novo (`quick-<YYYY-MM-DD>-<6hex>`).
    - `status: "active"`, `since: "<ISO agora>"`.
    - Preencher `agents[]` derivando de cada grupo de passos do QUICK.md.

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

@@ -0,0 +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
+
+- `85–100%` → pronto para executar
+- `70–84%` → executável com risco controlado
+- `50–69%` → 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

@@ -0,0 +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>

package/oxe/workflows/research.md

@@ -1,15 +1,16 @@
 # OXE — Workflow: research
 
 <objective>
-Produzir **notas de pesquisa rastreáveis** em **`.oxe/research/YYYY-MM-DD-<slug>.md`** e manter **`.oxe/RESEARCH.md`** como **índice e histórico** (ligações, tipo, estado, resumo). Serve para qualquer incerteza antes de um plano pesado: spikes, comparação de tecnologias, due diligence, requisitos ambíguos, **e** — com profundidade quando pedido — compreensão de **sistemas grandes**, **engenharia reversa / brownfield** e **hipóteses de modernização** (sempre ligadas a evidência ou suposições explícitas).
+Produzir **notas de pesquisa rastreáveis** em `research/YYYY-MM-DD-<slug>.md` do escopo resolvido e manter `RESEARCH.md` correspondente como **índice e histórico** (ligações, tipo, estado, resumo). Serve para qualquer incerteza antes de um plano pesado: spikes, comparação de tecnologias, due diligence, requisitos ambíguos, **e** — com profundidade quando pedido — compreensão de **sistemas grandes**, **engenharia reversa / brownfield** e **hipóteses de modernização** (sempre ligadas a evidência ou suposições explícitas).
 
 Não substitui **SPEC** nem **PLAN**; alimenta decisões que depois entram na SPEC ou no PLAN.
 </objective>
 
 <context>
-- **Uma sessão = um ficheiro novo** em `.oxe/research/`; não sobrescrever notas antigas salvo correção explícita do utilizador.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, research vive em `.oxe/<active_session>/research/`; sem sessão ativa, usar `.oxe/research/`.
+- **Uma sessão = um ficheiro novo** em `research/`; não sobrescrever notas antigas salvo correção explícita do utilizador.
 - Nome do ficheiro: **`YYYY-MM-DD-<slug-kebab>.md`** (data ISO do dia acordado na mensagem ou data atual; slug único, curto, ASCII preferível).
-- **Índice:** `.oxe/RESEARCH.md` deve conter tabela **Histórico** (mais recente primeiro) com colunas: **Data** | **Ficheiro** (`research/...`) | **Tema / âmbito** | **Tipo** (ex.: spike, mapa-sistema, reversa, modernização, decisão) | **Estado** (decidido / pendente / parcial) | **Resumo** (uma linha). Opcional: bloco **Última sessão** no topo com link para a nota mais recente.
+- **Índice:** `RESEARCH.md` do mesmo escopo deve conter tabela **Histórico** (mais recente primeiro) com colunas: **Data** | **Ficheiro** (`research/...`) | **Tema / âmbito** | **Tipo** (ex.: spike, mapa-sistema, reversa, modernização, decisão) | **Estado** (decidido / pendente / parcial) | **Resumo** (uma linha). Opcional: bloco **Última sessão** no topo com link para a nota mais recente.
 - Preferir **`.oxe/SPEC.md`** existente; se o pedido for mapear/reverter **antes** de spec, criar a nota mesmo assim com **Contexto** a declarar ausência de SPEC e próximo passo `oxe:spec`.
 - **Progressive disclosure:** sistemas grandes → profundidade por área; várias sessões/notas datadas em vez de um único ficheiro enorme.
 - Template: **`oxe/templates/RESEARCH.template.md`**.
@@ -33,19 +34,19 @@ Anotar `thinking_depth: surface | standard | deep` no frontmatter da nota de pes
 </thinking_depth>
 
 <process>
-1. Garantir pastas `.oxe/` e `.oxe/research/`.
+1. Garantir pastas `.oxe/` e `research/` do escopo resolvido.
 2. Escolher `YYYY-MM-DD-<slug>.md` único; se colisão, acrescentar sufixo ao slug (ex. `-b`).
 3. Criar a nota a partir de `RESEARCH.template.md`: preencher secções **base**; preencher secções de **reforço** ou marcar **N/A** com justificação curta quando o âmbito for sistema grande, reversa ou modernização.
-4. Se **`.oxe/RESEARCH.md`** não existir, criá-lo com título `# OXE — Índice de pesquisa`, parágrafo introdutório, secção **Histórico** com cabeçalho de tabela e primeira linha.
-5. Se já existir, **atualizar** `RESEARCH.md`: nova linha no topo da tabela **Histórico** (mais recente primeiro); opcionalmente atualizar **Última sessão** com link para o ficheiro novo.
+4. Se `RESEARCH.md` do escopo resolvido não existir, criá-lo com título `# OXE — Índice de pesquisa`, parágrafo introdutório, secção **Histórico** com cabeçalho de tabela e primeira linha.
+5. Se já existir, **atualizar** `RESEARCH.md` do escopo resolvido: nova linha no topo da tabela **Histórico** (mais recente primeiro); opcionalmente atualizar **Última sessão** com link para o ficheiro novo.
 6. Ler **`.oxe/SPEC.md`**, **`.oxe/codebase/*`** e código alvo (Glob/Grep/Read) conforme âmbito.
 7. Atualizar **`.oxe/STATE.md`**: nota de fase / próximo passo típico `oxe:plan`, ou `oxe:spec` se faltar contrato, ou `oxe:ui-spec` se o foco for UI antes do plano.
 8. Responder no chat em 5–10 linhas: caminho da nota nova, confirmação de atualização do índice, próximo passo OXE.
 </process>
 
 <success_criteria>
-- [ ] Existe novo ficheiro em `.oxe/research/YYYY-MM-DD-<slug>.md` com secções base preenchidas de forma útil.
-- [ ] `.oxe/RESEARCH.md` existe e a tabela **Histórico** inclui a nova entrada.
+- [ ] Existe novo ficheiro em `research/YYYY-MM-DD-<slug>.md` no escopo correto com secções base preenchidas de forma útil.
+- [ ] `RESEARCH.md` do mesmo escopo existe e a tabela **Histórico** inclui a nova entrada.
 - [ ] Nenhuma nota anterior foi sobrescrita sem instrução explícita do utilizador.
 - [ ] `STATE.md` reflete o progresso e o próximo passo sugerido.
 </success_criteria>

package/oxe/workflows/security.md

@@ -8,8 +8,9 @@ Pode ser chamado standalone ou como Camada 5 do **`verify.md`** quando `config.j
 Não substitui ferramentas de análise estática (SAST) — identifica padrões de risco no código e na configuração a partir do contexto disponível no repositório.
 </objective>
 
-<context>
-- **Fonte de stack:** `.oxe/codebase/STACK.md` determina quais categorias OWASP são pertinentes (ex.: app sem DB descarta A03:Injection-SQL; API sem auth descarta A07:Authentication).
+<context>
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. O relatório de segurança segue a sessão ativa em `verification/`, mas continua a ler `codebase/` global.
+- **Fonte de stack:** `.oxe/codebase/STACK.md` determina quais categorias OWASP são pertinentes (ex.: app sem DB descarta A03:Injection-SQL; API sem auth descarta A07:Authentication).
 - **Fontes de código:** `.oxe/codebase/STRUCTURE.md`, `.oxe/codebase/CONCERNS.md`, `.oxe/codebase/INTEGRATIONS.md` orientam quais arquivos focar.
 - **Severidade:** P0 = crítico (exploração provável, impacto direto), P1 = alto (requer mitigação antes do próximo deploy), P2 = médio (risco aceitável com compensação documentada).
 - **Saída de tarefas:** recomendações vinculadas a `Tn` existentes no PLAN.md (se disponível) ou como sugestões de novas tarefas `T_new`.
@@ -45,14 +46,14 @@ Antes de auditar, determinar quais categorias se aplicam lendo `STACK.md` e `INT
    a. Identificar **arquivos críticos** (auth, input handlers, DB queries, configs, env, deps).
    b. Ler os arquivos relevantes (Glob, Grep, Read) procurando padrões de risco.
    c. Registrar achados com: localização (`path:linha`), padrão encontrado, severidade (P0/P1/P2), recomendação.
-4. Ler `.oxe/PLAN.md` se existir — vincular achados P0/P1 a tarefas `Tn` existentes quando possível, ou criar sugestão `T_new`.
-5. Escrever `.oxe/SECURITY.md` a partir de `oxe/templates/SECURITY.template.md`.
-6. Atualizar `.oxe/STATE.md`: nota de segurança (ex.: `security_audit: YYYY-MM-DD | P0:N | P1:N | P2:N`).
+4. Ler `PLAN.md` do escopo resolvido se existir — vincular achados P0/P1 a tarefas `Tn` existentes quando possível, ou criar sugestão `T_new`.
+5. Escrever `SECURITY.md` no escopo resolvido a partir de `oxe/templates/SECURITY.template.md`.
+6. Atualizar `.oxe/STATE.md`: nota de segurança (ex.: `security_audit: YYYY-MM-DD | P0:N | P1:N | P2:N`).
 7. Responder no chat: total de achados por severidade, arquivos mais críticos identificados, próximo passo (P0 presentes → bloquear deploy; apenas P2 → ação opcional).
 </process>
 
 <success_criteria>
-- [ ] `.oxe/SECURITY.md` existe com categorias OWASP selecionadas e justificativa de descarte.
+- [ ] `SECURITY.md` existe no escopo correto com categorias OWASP selecionadas e justificativa de descarte.
 - [ ] Cada achado tem: localização, padrão, severidade, recomendação.
 - [ ] Categorias sem achados registradas como "nenhum achado nesta categoria".
 - [ ] Achados P0/P1 vinculados a `Tn` existente ou sugestão `T_new`.