oxe-cc 0.6.4 → 0.6.5

package/oxe/workflows/plan.md

@@ -3,24 +3,25 @@
 <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>
+- 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.
@@ -66,11 +67,11 @@ 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.
+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.
 
@@ -80,14 +81,14 @@ Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N
 </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).
+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. 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`.
+8. Atualizar `.oxe/STATE.md` global: 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>

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,9 @@ 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>
+- 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"`).
@@ -140,16 +141,16 @@ 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`:
+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/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`.

package/oxe/workflows/session.md

@@ -0,0 +1,153 @@
+# OXE — Workflow: session
+
+<objective>
+Gerenciar **sessões OXE** em `.oxe/sessions/` para isolar artefatos por ciclo de trabalho, mantendo **`.oxe/STATE.md`** como índice global e preservando o **modo legado** quando não houver sessão ativa.
+
+Subcomandos:
+- `new <nome>`
+- `list`
+- `switch <id-ou-nome>`
+- `resume <id-ou-nome>`
+- `status`
+- `close`
+- `migrate <nome>`
+</objective>
+
+<context>
+- Fonte de regra de path: `oxe/workflows/references/session-path-resolution.md`
+- Template da sessão: `oxe/templates/SESSION.template.md`
+- Índice global: `.oxe/SESSIONS.md`
+- Sessão ativa fica sempre em `.oxe/STATE.md`, campo `active_session`, com path relativo completo: `sessions/sNNN-slug`
+- Sem sessão ativa, os workflows continuam a operar na raiz `.oxe/`
+- Esta entrega é **workflows only**: `oxe-cc status` / `doctor` continuam legados e isso deve ser assumido nesta versão
+</context>
+
+<index_format>
+## Formato fixo de `.oxe/SESSIONS.md`
+
+```markdown
+# OXE — Índice de sessões
+
+| ID | Nome | Status | Criada | Última atividade | Resumo | Path |
+|----|------|--------|--------|------------------|--------|------|
+| s001 | auth-redesign | active | 2026-04-07 | 2026-04-07 | Sessão criada por migrate | `sessions/s001-auth-redesign` |
+```
+
+- Linha mais recente no topo
+- `switch` e `resume` atualizam **Última atividade**
+- `close` atualiza **Status** para `archived`
+</index_format>
+
+<process_new>
+## `new <nome>`
+
+1. Garantir `.oxe/`, `.oxe/sessions/` e `.oxe/global/`.
+2. Normalizar o nome para slug ASCII em kebab-case.
+3. Ler `.oxe/SESSIONS.md` se existir; calcular o próximo ID `sNNN`.
+4. Criar `.oxe/sessions/sNNN-slug/` com:
+   - `spec/`
+   - `plan/`
+   - `execution/`
+   - `verification/`
+   - `checkpoints/`
+   - `research/`
+   - `artifacts/`
+   - `workstreams/`
+5. Criar `SESSION.md` a partir de `SESSION.template.md`.
+6. Criar ou atualizar `.oxe/SESSIONS.md` com a nova linha no topo.
+7. Atualizar `.oxe/STATE.md`:
+   - `active_session: sessions/sNNN-slug`
+   - `session_id: sNNN`
+   - fase resumida e próximo passo coerentes com a sessão nova
+8. Responder no chat com ID, path da sessão e próximo passo sugerido.
+</process_new>
+
+<process_list>
+## `list`
+
+1. Ler `.oxe/SESSIONS.md`.
+2. Se o ficheiro não existir, responder que não há sessões registadas.
+3. Exibir a tabela do índice; se o utilizador pedir filtro, aceitar `--status active|archived`.
+</process_list>
+
+<process_switch>
+## `switch <id-ou-nome>`
+
+1. Ler `.oxe/SESSIONS.md`.
+2. Resolver a sessão por `sNNN`, slug ou nome exibido na tabela.
+3. Atualizar `.oxe/STATE.md` global:
+   - `active_session`
+   - `session_id`
+   - `Última atividade` dessa sessão em `.oxe/SESSIONS.md`
+4. Não mover artefatos; apenas mudar o contexto ativo.
+</process_switch>
+
+<process_resume>
+## `resume <id-ou-nome>`
+
+- Mesmo comportamento de `switch`
+- Usar wording de retomada no chat, mas sem lógica diferente
+</process_resume>
+
+<process_status>
+## `status`
+
+1. Ler `.oxe/STATE.md` global.
+2. Se houver `active_session`, abrir `SESSION.md` da sessão ativa e resumir:
+   - metadados
+   - índice de artefatos
+   - tags
+   - último evento do histórico
+3. Se não houver sessão ativa, responder com a tabela de `.oxe/SESSIONS.md` (equivalente funcional a `list`).
+</process_status>
+
+<process_close>
+## `close`
+
+1. Ler `.oxe/STATE.md`; se não houver sessão ativa, pausar e informar.
+2. Abrir `SESSION.md` da sessão ativa e marcar `Status: archived`.
+3. Atualizar `.oxe/SESSIONS.md` com `Status = archived` e `Última atividade = hoje`.
+4. Limpar de `.oxe/STATE.md`:
+   - `active_session`
+   - `session_id`
+5. Responder com a sessão encerrada e lembrar que sessões arquivadas continuam legíveis.
+</process_close>
+
+<process_migrate>
+## `migrate <nome>`
+
+1. Executar logicamente `new <nome>` para abrir uma nova sessão.
+2. Mover apenas artefatos session-scoped existentes da raiz `.oxe/`:
+   - `SPEC.md`, `ROADMAP.md`, `DISCUSS.md`, `UI-SPEC.md` → `spec/`
+   - `PLAN.md`, `QUICK.md`, `plan-agents.json`, `quick-agents.json`, `plan-agent-messages/` → `plan/`
+   - `OBSERVATIONS.md`, `DEBUG.md`, `FORENSICS.md`, `SUMMARY.md` → `execution/`
+   - `VERIFY.md`, `VALIDATION-GAPS.md`, `SECURITY.md`, `UI-REVIEW.md` → `verification/`
+   - `checkpoints/`, `CHECKPOINTS.md` → `checkpoints/`
+   - `research/`, `RESEARCH.md` → `research/`
+   - `workstreams/` → `workstreams/`
+3. Não mover:
+   - `.oxe/STATE.md`
+   - `.oxe/config.json`
+   - `.oxe/codebase/`
+   - `.oxe/SESSIONS.md`
+   - `.oxe/global/`
+4. No chat, listar:
+   - movidos
+   - mantidos globais
+   - ignorados por inexistência
+</process_migrate>
+
+<process_default>
+## Sem subcomando
+
+- Se houver sessão ativa: executar `status`
+- Se não houver sessão ativa: executar `list`
+</process_default>
+
+<success_criteria>
+- [ ] `.oxe/sessions/sNNN-slug/` é o path da sessão criado/consultado.
+- [ ] `active_session` guarda o path relativo completo no `STATE.md` global.
+- [ ] `.oxe/SESSIONS.md` usa as colunas mínimas `ID | Nome | Status | Criada | Última atividade | Resumo | Path`.
+- [ ] `close` arquiva sem apagar artefatos.
+- [ ] `migrate` move só artefatos session-scoped e preserva os globais.
+</success_criteria>

package/oxe/workflows/spec.md

@@ -13,14 +13,20 @@ Para trabalho **muito pequeno** que não justifica spec completa: redirecionar p
 Se **`.oxe/config.json`** tiver `discuss_before_plan: true`: mencionar no final da Fase 5 que o próximo passo é **`oxe:discuss`** antes do plano.
 </objective>
 
-<context>
-**Pré-requisito preferível:** scan executado. Se não existir, mencionar na spec que o mapa está pendente.
-
-Ler no início:
-- `.oxe/STATE.md` — fase atual, decisões, workstream ativo
-- `.oxe/codebase/OVERVIEW.md` e `STACK.md` se existirem — não contradizer o repo
-- **`.oxe/OBSERVATIONS.md`** — se houver entradas `pendente` com impacto `spec` ou `all`, incorporá-las na Fase 3 (Requisitos) e marcá-las `incorporada → spec (data)` após uso
-- **`.oxe/LESSONS.md`** — se existir, ler entradas com `Aplicar em: spec` e status `ativo`. Usar como restrições explícitas ou alertas durante a Fase 1 (perguntas) e Fase 3 (requisitos). Exemplo: se uma lição diz "perguntar explicitamente sobre integração com X", adicionar essa pergunta no Bloco B da Fase 1.
+<context>
+**Pré-requisito preferível:** scan executado. Se não existir, mencionar na spec que o mapa está pendente.
+
+**Resolução de sessão:** antes de ler ou escrever artefatos desta trilha, resolver `active_session` em `.oxe/STATE.md` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa:
+- `SPEC.md`, `ROADMAP.md` e `DISCUSS.md` vivem em `.oxe/<active_session>/spec/`
+- `OBSERVATIONS.md`, `RESEARCH.md` e `research/` seguem o escopo da sessão
+- `LESSONS.md` continua global em `.oxe/global/LESSONS.md`
+- sem sessão ativa, manter o modo legado na raiz `.oxe/`
+
+Ler no início:
+- `.oxe/STATE.md` — fase atual, decisões, workstream ativo
+- `.oxe/codebase/OVERVIEW.md` e `STACK.md` se existirem — não contradizer o repo
+- **OBS do escopo ativo** — se houver entradas `pendente` com impacto `spec` ou `all`, incorporá-las na Fase 3 (Requisitos) e marcá-las `incorporada → spec (data)` após uso
+- **`.oxe/global/LESSONS.md`** — se existir, ler entradas com `Aplicar em: spec` e status `ativo`. Usar como restrições explícitas ou alertas durante a Fase 1 (perguntas) e Fase 3 (requisitos). Exemplo: se uma lição diz "perguntar explicitamente sobre integração com X", adicionar essa pergunta no Bloco B da Fase 1.
 
 **Brownfield (COBOL, JCL, copybooks, VB6, SP):** quando o objetivo for documentar ou planear migração, ver **`oxe/workflows/references/legacy-brownfield.md`** — épicos por trilha, critérios A* verificáveis por Grep/leitura/checklist.
 
@@ -69,8 +75,8 @@ Usar templates: **`oxe/templates/SPEC.template.md`** e **`oxe/templates/ROADMAP.
 - "Há 3 áreas com incerteza técnica: autenticação JWT, integração com Stripe, e deploy em edge. Quer investigar alguma antes de avançar para requisitos?"
 
 **Se aprovado:**
-- Criar notas de pesquisa datadas em `.oxe/research/YYYY-MM-DD-<slug>.md` (usar fluxo de `research.md`)
-- Atualizar `.oxe/RESEARCH.md` com índice
+- Criar notas de pesquisa datadas em `research/YYYY-MM-DD-<slug>.md` no escopo ativo (usar fluxo de `research.md`)
+- Atualizar `RESEARCH.md` no mesmo escopo
 - Consolidar descobertas relevantes antes de avançar para Fase 3
 
 **Se pulado:** registrar em `SPEC.md` as áreas de incerteza como suposições explícitas.
@@ -105,7 +111,7 @@ Usar templates: **`oxe/templates/SPEC.template.md`** e **`oxe/templates/ROADMAP.
 <fase_4_roteiro>
 ## Fase 4 — Roteiro
 
-**Objetivo:** criar fases de entrega mapeadas aos requisitos v1 e escrever `.oxe/ROADMAP.md`.
+**Objetivo:** criar fases de entrega mapeadas aos requisitos v1 e escrever `ROADMAP.md` no escopo ativo da sessão.
 
 **Lógica de agrupamento:**
 - Agrupar requisitos v1 em fases por **dependência técnica** e **valor entregável**
@@ -113,14 +119,14 @@ Usar templates: **`oxe/templates/SPEC.template.md`** e **`oxe/templates/ROADMAP.
 - Fase 1 = o que `/oxe-plan` implementará no próximo ciclo
 - Fases 2+ = ciclos futuros de spec→plan→execute→verify
 
-**Escrever `.oxe/ROADMAP.md`** usando `oxe/templates/ROADMAP.template.md`:
+**Escrever `ROADMAP.md`** usando `oxe/templates/ROADMAP.template.md` no escopo ativo:
 
 ```markdown
 ---
 oxe_doc: roadmap
 status: draft
 updated: <data>
-spec_ref: .oxe/SPEC.md
+spec_ref: SPEC.md
 ---
 
 ## Fase 1 — [Nome]
@@ -192,24 +198,24 @@ O resultado desta reflexão é **invisível ao usuário** — é trabalho intern
 </fase_5_aprovacao>
 
 <process>
-1. Ler `.oxe/STATE.md`, `OVERVIEW.md`, `STACK.md` e `.oxe/OBSERVATIONS.md` (verificar pendentes).
+1. Ler `.oxe/STATE.md`, `OVERVIEW.md`, `STACK.md` e `OBSERVATIONS.md` do escopo ativo (verificar pendentes).
 2. **Fase 1 — Perguntas:** enviar bloco coeso de 3-5 perguntas; máx 3 rodadas; confirmar entendimento.
 3. **Fase 2 — Pesquisa:** propor áreas de investigação; aguardar aprovação; executar se aprovado.
 4. **Fase 3 — Requisitos:** extrair tabela R-ID com v1/v2/fora e critérios A*; incorporar OBS pendentes; apresentar para validação.
-5. **Fase 4 — Roteiro:** agrupar requisitos v1 em fases; escrever `.oxe/ROADMAP.md`.
-6. Escrever **`.oxe/SPEC.md`** usando `oxe/templates/SPEC.template.md`:
+5. **Fase 4 — Roteiro:** agrupar requisitos v1 em fases; escrever `ROADMAP.md` no escopo ativo.
+6. Escrever **`SPEC.md`** usando `oxe/templates/SPEC.template.md` no escopo ativo:
    - Frontmatter YAML (`oxe_doc: spec`, `status`, `updated`, `inputs`)
    - Objetivo, Escopo (dentro/fora), Critérios de aceite (tabela A*), Suposições e riscos, Referências
    - Preservar chaves existentes se SPEC.md já existir; atualizar `updated:`
 6b. **Auto-reflexão:** executar integralmente o bloco `<auto_reflexao>` antes de avançar. Corrigir a spec conforme necessário. Não apresentar a lista de verificação ao usuário — apenas a spec corrigida.
 7. **Fase 5 — Aprovação:** apresentar resumo, aguardar aprovação do roteiro, redirecionar.
-8. Atualizar **`.oxe/STATE.md`**: `phase: spec_ready`, próximo passo.
-9. Marcar OBS incorporadas em `.oxe/OBSERVATIONS.md` se houver pendentes de impacto `spec`.
+8. Atualizar **`.oxe/STATE.md`** global: `phase: spec_ready`, próximo passo e referência curta à sessão ativa quando existir.
+9. Marcar OBS incorporadas em `OBSERVATIONS.md` do escopo ativo se houver pendentes de impacto `spec`.
 </process>
 
 <success_criteria>
-- [ ] `.oxe/SPEC.md` existe com critérios A* e coluna Como verificar; `STATE.md` atualizado.
-- [ ] `.oxe/ROADMAP.md` existe com fases mapeadas a R-IDs e A*, status `approved` (ou `draft` se usuário não confirmou).
+- [ ] `SPEC.md` existe no escopo correto (`spec/` da sessão ou `.oxe/` legado) com critérios A* e coluna Como verificar; `STATE.md` global atualizado.
+- [ ] `ROADMAP.md` existe no mesmo escopo com fases mapeadas a R-IDs e A*, status `approved` (ou `draft` se usuário não confirmou).
 - [ ] Tabela de requisitos R-ID foi apresentada e validada (v1/v2/fora) antes do roteiro.
 - [ ] Usuário foi consultado no gate da Fase 5 e escolheu o próximo passo.
 - [ ] OBS pendentes com impacto `spec` foram incorporadas e marcadas `incorporada`.

package/oxe/workflows/ui-review.md

@@ -13,9 +13,9 @@ Não substitui **`verify`**: cruza contrato UI; o verify global continua a amarr
 </context>
 
 <process>
-1. Ler `.oxe/UI-SPEC.md`, `.oxe/SPEC.md` e inspecionar ficheiros de UI relevantes (paths do PLAN ou indicados pelo utilizador).
-2. Escrever **`.oxe/UI-REVIEW.md`** com: **Data**, **Âmbito revisto**, **Checklist** (passou / falhou / N/A), **Bloqueios**, **Sugestões**.
-3. Atualizar **`.oxe/STATE.md`** se útil (referência a UI-REVIEW pendente de verify).
+1. Resolver `active_session` conforme `session-path-resolution.md`; ler `UI-SPEC.md` e `SPEC.md` do escopo resolvido e inspecionar ficheiros de UI relevantes (paths do PLAN ou indicados pelo utilizador).
+2. Escrever **`UI-REVIEW.md`** no escopo de `verification/` da sessão ativa (ou `.oxe/` legado) com: **Data**, **Âmbito revisto**, **Checklist** (passou / falhou / N/A), **Bloqueios**, **Sugestões**.
+3. Atualizar **`.oxe/STATE.md`** global se útil (referência a UI-REVIEW pendente de verify).
 4. Indicar no chat: se há P0 → próximo passo típico **`/oxe-execute`** (correções); senão **`/oxe-verify`** para fecho global.
 </process>
 

package/oxe/workflows/ui-spec.md

@@ -13,9 +13,9 @@ Produzir **`.oxe/UI-SPEC.md`**: contrato de UI/UX derivado de **`.oxe/SPEC.md`**
 </context>
 
 <process>
-1. Ler `.oxe/SPEC.md` e, se existirem, `OVERVIEW.md` / `CONVENTIONS.md` em `.oxe/codebase/`.
-2. Criar ou atualizar **`.oxe/UI-SPEC.md`** com as secções acima preenchidas de forma verificável (checklist ou critérios numerados **U1**, **U2**… opcionais).
-3. Atualizar **`.oxe/STATE.md`**: nota de fase ou próximo passo `oxe:plan` (se ainda não há PLAN) ou manter `oxe:execute` se o plano já referencia UI.
+1. Resolver `active_session` conforme `session-path-resolution.md`; ler `SPEC.md` do escopo resolvido e, se existirem, `OVERVIEW.md` / `CONVENTIONS.md` em `.oxe/codebase/`.
+2. Criar ou atualizar **`UI-SPEC.md`** em `.oxe/<active_session>/spec/` (ou `.oxe/` legado) com as secções acima preenchidas de forma verificável (checklist ou critérios numerados **U1**, **U2**… opcionais).
+3. Atualizar **`.oxe/STATE.md`** global: nota de fase ou próximo passo `oxe:plan` (se ainda não há PLAN) ou manter `oxe:execute` se o plano já referencia UI.
 4. Resumo no chat: o que ficou no UI-SPEC e como o **`/oxe-plan`** deve citar as secções (ex.: “cumprir UI-SPEC §2”).
 </process>
 

package/oxe/workflows/validate-gaps.md

@@ -6,20 +6,21 @@ Após **`verify`**, produzir ou atualizar **`.oxe/VALIDATION-GAPS.md`**: auditor
 Não substitui **`verify`**: não reescreve a evidência em `VERIFY.md`; adiciona uma camada de “gaps” e melhorias para a próxima ronda ou replan.
 </objective>
 
-<context>
-- **Pré-requisitos:** `.oxe/VERIFY.md` e `.oxe/PLAN.md` existem. `.oxe/SPEC.md` altamente recomendado para cruzar IDs **A***.
+<context>
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `VERIFY.md`, `PLAN.md`, `SPEC.md` e `VALIDATION-GAPS.md` vivem no escopo da sessão; sem sessão ativa, manter `.oxe/`.
+- **Pré-requisitos:** `VERIFY.md` e `PLAN.md` existem no escopo resolvido. `SPEC.md` altamente recomendado para cruzar IDs **A***.
 - **Quando usar:** equipas que querem fechar dívida de testes, evidência fraca ou desalinhamento após um verify (passou ou falhou).
 - **Edição do PLAN:** só se o utilizador pedir explicitamente incorporar as sugestões no plano.
 </context>
 
 <process>
-1. Ler `.oxe/PLAN.md` (cada `### Tn`, **Verificar**, **Aceite vinculado:**), `.oxe/VERIFY.md` (tabelas de tarefas e de critérios SPEC), e `.oxe/SPEC.md` se existir.
+1. Ler `PLAN.md` (cada `### Tn`, **Verificar**, **Aceite vinculado:**), `VERIFY.md` (tabelas de tarefas e de critérios SPEC), e `SPEC.md` do escopo resolvido se existir.
 2. Aplicar checklist de deteção (marcar cada achado nos **Gaps**):
    - **A*** na SPEC sem linha clara na tabela de critérios do VERIFY, ou com evidência inexistente/vaga.
    - **Tn** com `Comando: —` ou **Manual** vago quando o critério associado pede rigor reprodutível.
    - VERIFY indica sucesso mas a coluna de evidência é só genérica (sem path, comando ou trecho identificável).
    - Tarefa no PLAN sem linha correspondente na tabela de tarefas do VERIFY (verify focado em subset — documentar como gap de escopo).
-3. Escrever ou atualizar **`.oxe/VALIDATION-GAPS.md`** com secções fixas:
+3. Escrever ou atualizar **`VALIDATION-GAPS.md`** no escopo resolvido com secções fixas:
    - **Data** (ISO) e **Contexto** (verify passou / falhou; ambiente se relevante).
    - **Gaps** — tabela: **ID ou Tn** | **Tipo de gap** | **Severidade sugerida** (P0/P1/P2) | **Nota**.
    - **Sugestões de tarefas** — rascunhos `T_new` ou bullets para incorporar no próximo `oxe:plan --replan`; **apenas texto**.