oxe-cc 0.6.2 → 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

@@ -1,50 +1,50 @@
-# OXE — Workflow: project (gestão de projeto)
-
-<objective>
-Ponto de entrada unificado para as três operações de gestão de projeto OXE:
-
-- **milestone** — marcos de entrega (M-NN): `new`, `complete`, `status`, `audit`
-- **workstream** — trilhas paralelas: `new <nome>`, `switch <nome>`, `list`, `close <nome>`
-- **checkpoint** — snapshot nomeado de sessão: `[slug]`
-
-Detecta a operação pelo primeiro token do input e delega ao workflow canônico correspondente.
-</objective>
-
-<context>
-- 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`.
-</context>
-
-<dispatch_table>
-| Input começa com | Delega para | Exemplos |
-|------------------|-------------|---------|
-| `milestone new ...` | `milestone.md` + subcomando `new` | `/oxe-project milestone new v1.0` |
-| `milestone complete` | `milestone.md` + subcomando `complete` | `/oxe-project milestone complete` |
-| `milestone status` | `milestone.md` + subcomando `status` | `/oxe-project milestone status` |
-| `milestone audit` | `milestone.md` + subcomando `audit` | `/oxe-project milestone audit` |
-| `workstream new <nome>` | `workstream.md` + subcomando `new` | `/oxe-project workstream new auth` |
-| `workstream switch <nome>` | `workstream.md` + subcomando `switch` | `/oxe-project workstream switch auth` |
-| `workstream list` | `workstream.md` + subcomando `list` | `/oxe-project workstream list` |
-| `workstream close <nome>` | `workstream.md` + subcomando `close` | `/oxe-project workstream close auth` |
-| `checkpoint [slug]` | `checkpoint.md` | `/oxe-project checkpoint pre-refactor` |
-| *(sem input)* | Status atual | `/oxe-project` |
-</dispatch_table>
-
-<process>
-1. Ler o input do usuário (texto após o comando).
-2. Identificar o primeiro token:
-   - `milestone` → carregar e executar `oxe/workflows/milestone.md` passando o restante como subcomando.
-   - `workstream` → carregar e executar `oxe/workflows/workstream.md` passando o restante como subcomando.
-   - `checkpoint` → carregar e executar `oxe/workflows/checkpoint.md` passando o slug (se houver).
-   - *(vazio)* → ler `STATE.md`, `MILESTONES.md` (se existir) e listar: milestone ativo (M-NN / nenhum), workstreams abertos, último checkpoint. Sugerir próxima operação.
-   - *(ambíguo)* → listar as 3 operações disponíveis com exemplos de uso.
-3. Executar o workflow delegado integralmente.
-</process>
-
-<success_criteria>
-- [ ] O workflow correto foi executado com base no input.
-- [ ] Sem input: STATUS atual de milestone ativo, workstreams e último checkpoint mostrado.
-- [ ] Input ambíguo: máximo 3 opções apresentadas com exemplos, não listas longas.
-</success_criteria>
+# OXE — Workflow: project (gestão de projeto)
+
+<objective>
+Ponto de entrada unificado para as três operações de gestão de projeto OXE:
+
+- **milestone** — marcos de entrega (M-NN): `new`, `complete`, `status`, `audit`
+- **workstream** — trilhas paralelas: `new <nome>`, `switch <nome>`, `list`, `close <nome>`
+- **checkpoint** — snapshot nomeado de sessão: `[slug]`
+
+Detecta a operação pelo primeiro token do input e delega ao workflow canônico correspondente.
+</objective>
+
+<context>
+- 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`, `.oxe/global/MILESTONES.md` e `CHECKPOINTS.md` do escopo atual da sessão.
+</context>
+
+<dispatch_table>
+| Input começa com | Delega para | Exemplos |
+|------------------|-------------|---------|
+| `milestone new ...` | `milestone.md` + subcomando `new` | `/oxe-project milestone new v1.0` |
+| `milestone complete` | `milestone.md` + subcomando `complete` | `/oxe-project milestone complete` |
+| `milestone status` | `milestone.md` + subcomando `status` | `/oxe-project milestone status` |
+| `milestone audit` | `milestone.md` + subcomando `audit` | `/oxe-project milestone audit` |
+| `workstream new <nome>` | `workstream.md` + subcomando `new` | `/oxe-project workstream new auth` |
+| `workstream switch <nome>` | `workstream.md` + subcomando `switch` | `/oxe-project workstream switch auth` |
+| `workstream list` | `workstream.md` + subcomando `list` | `/oxe-project workstream list` |
+| `workstream close <nome>` | `workstream.md` + subcomando `close` | `/oxe-project workstream close auth` |
+| `checkpoint [slug]` | `checkpoint.md` | `/oxe-project checkpoint pre-refactor` |
+| *(sem input)* | Status atual | `/oxe-project` |
+</dispatch_table>
+
+<process>
+1. Ler o input do usuário (texto após o comando).
+2. Identificar o primeiro token:
+   - `milestone` → carregar e executar `oxe/workflows/milestone.md` passando o restante como subcomando.
+   - `workstream` → carregar e executar `oxe/workflows/workstream.md` passando o restante como subcomando.
+   - `checkpoint` → carregar e executar `oxe/workflows/checkpoint.md` passando o slug (se houver).
+   - *(vazio)* → ler `STATE.md`, `MILESTONES.md` (se existir) e listar: milestone ativo (M-NN / nenhum), workstreams abertos, último checkpoint. Sugerir próxima operação.
+   - *(ambíguo)* → listar as 3 operações disponíveis com exemplos de uso.
+3. Executar o workflow delegado integralmente.
+</process>
+
+<success_criteria>
+- [ ] O workflow correto foi executado com base no input.
+- [ ] Sem input: STATUS atual de milestone ativo, workstreams e último checkpoint mostrado.
+- [ ] Input ambíguo: máximo 3 opções apresentadas com exemplos, não listas longas.
+</success_criteria>

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).
+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/retro.md

@@ -1,62 +1,62 @@
-# OXE — Workflow: retro (retrospectiva de ciclo)
-
-<objective>
-Sintetizar os aprendizados de um ciclo completo (spec → verify) em **`.oxe/LESSONS.md`** — um arquivo prescritivo e cumulativo que alimenta automaticamente ciclos futuros.
-
-**Princípio:** lições não são diário — são instruções para o próximo ciclo. Cada entrada diz COMO agir diferente, não apenas o que aconteceu.
-
-Pode ser chamado:
-- Após `/oxe-verify` (ciclo normal completo)
-- Após `/oxe-verify` com falha e replanejamento (ciclo com retrabalho)
-- A qualquer momento para capturar aprendizados antes que se percam
-</objective>
-
-<context>
-- **Pré-requisito preferível:** `.oxe/VERIFY.md` existente. Sem ele, a retro é baseada em STATE.md e relato do usuário.
-- **Artefato:** `.oxe/LESSONS.md` — append-only por padrão; nunca apagar entradas anteriores, apenas mudar `Status` para `resolvido`.
-- **Consumidores:** `/oxe-spec` (lições tipo `spec`), `/oxe-plan` (lições tipo `plan`), `/oxe-scan` (lições tipo `process`), `/oxe-execute` (lições tipo `execute`).
-- **Ciclo ID:** sequencial `C-01`, `C-02`, … (continuar do último em LESSONS.md).
-- Template: `oxe/templates/LESSONS.template.md`.
-</context>
-
-<taxonomy>
-## Taxonomia de tipos de lição
-
-| Tipo | Quando usar | Consumido por |
-|------|-------------|---------------|
-| `spec` | Problemas na definição de requisitos ou critérios A* | `/oxe-spec` Fase 1/3 |
-| `plan` | Problemas de granularidade, ondas, verificações | `/oxe-plan` |
-| `execute` | Padrões de falha na implementação, hipóteses erradas | `/oxe-execute` |
-| `verify` | Critérios vagos, evidências insuficientes, camadas puladas | `/oxe-verify` |
-| `process` | Escolha errada de workflow (quick vs spec, solo vs agents) | `/oxe-scan`, qualquer entry |
-| `agents` | Problemas de orquestração, runId, dependências de agente | `/oxe-plan-agent`, `/oxe-execute` |
-
-**Formato de lição (prescritivo, não descritivo):**
-- ❌ "A tarefa T4 demorou muito" (descritivo — não ajuda no próximo ciclo)
-- ✅ "Tarefas com integração de terceiros devem ter Complexidade L mínimo + Verificar com mock fallback" (prescritivo — o próximo plan pode aplicar)
-</taxonomy>
-
-<process>
-1. Ler **`.oxe/VERIFY.md`** se existir: identificar tarefas que falharam, critérios A* sem evidência, gaps documentados.
-2. Ler **`.oxe/FORENSICS.md`** se existir: capturar causa raiz de falhas de execução.
-3. Ler **`.oxe/SUMMARY.md`** se existir: capturar contexto de replans e decisões forçadas.
-4. Ler **`.oxe/STATE.md`**: capturar número de ondas, execute_mode usado, se houve loop, se houve escalação para forensics.
-5. Sintetizar **3–5 lições prescritivas** (não mais — qualidade sobre quantidade):
-   - Cada lição responde: "O que o próximo ciclo deve fazer diferente?"
-   - Formato: **Lição** (o que fazer) + **Raiz** (por que isso aconteceu) + **Tipo** + **Aplicar em**
-6. Determinar o próximo **ciclo ID** (C-NN) lendo `.oxe/LESSONS.md` existente ou começando em C-01.
-7. Criar ou atualizar **`.oxe/LESSONS.md`** usando `oxe/templates/LESSONS.template.md`:
-   - Adicionar linha na tabela de índice (mais recente primeiro).
-   - Adicionar seção `### C-NN` com as lições sintetizadas.
-   - **Nunca apagar** entradas anteriores — só mudar `Status: resolvido` se a lição foi superada.
-8. Atualizar **`.oxe/STATE.md`**: campo `last_retro: YYYY-MM-DD`.
-9. Responder no chat: ID do ciclo (C-NN), número de lições registradas, lição mais crítica em 1 frase, sugestão do próximo ciclo (`/oxe-scan` ou `/oxe-spec`).
-</process>
-
-<success_criteria>
-- [ ] `.oxe/LESSONS.md` existe com entrada C-NN na tabela e seção de detalhe.
-- [ ] Cada lição é prescritiva (diz o que fazer) não descritiva (não é só o que aconteceu).
-- [ ] 3–5 lições por ciclo — não um dump completo de eventos.
-- [ ] `STATE.md` tem `last_retro` atualizado.
-- [ ] Entradas anteriores preservadas; apenas `Status` pode mudar.
-</success_criteria>
+# OXE — Workflow: retro (retrospectiva de ciclo)
+
+<objective>
+Sintetizar os aprendizados de um ciclo completo (spec → verify) em **`.oxe/LESSONS.md`** — um arquivo prescritivo e cumulativo que alimenta automaticamente ciclos futuros.
+
+**Princípio:** lições não são diário — são instruções para o próximo ciclo. Cada entrada diz COMO agir diferente, não apenas o que aconteceu.
+
+Pode ser chamado:
+- Após `/oxe-verify` (ciclo normal completo)
+- Após `/oxe-verify` com falha e replanejamento (ciclo com retrabalho)
+- A qualquer momento para capturar aprendizados antes que se percam
+</objective>
+
+<context>
+- **Pré-requisito preferível:** `.oxe/VERIFY.md` existente. Sem ele, a retro é baseada em STATE.md e relato do usuário.
+- **Artefato:** `.oxe/LESSONS.md` — append-only por padrão; nunca apagar entradas anteriores, apenas mudar `Status` para `resolvido`.
+- **Consumidores:** `/oxe-spec` (lições tipo `spec`), `/oxe-plan` (lições tipo `plan`), `/oxe-scan` (lições tipo `process`), `/oxe-execute` (lições tipo `execute`).
+- **Ciclo ID:** sequencial `C-01`, `C-02`, … (continuar do último em LESSONS.md).
+- Template: `oxe/templates/LESSONS.template.md`.
+</context>
+
+<taxonomy>
+## Taxonomia de tipos de lição
+
+| Tipo | Quando usar | Consumido por |
+|------|-------------|---------------|
+| `spec` | Problemas na definição de requisitos ou critérios A* | `/oxe-spec` Fase 1/3 |
+| `plan` | Problemas de granularidade, ondas, verificações | `/oxe-plan` |
+| `execute` | Padrões de falha na implementação, hipóteses erradas | `/oxe-execute` |
+| `verify` | Critérios vagos, evidências insuficientes, camadas puladas | `/oxe-verify` |
+| `process` | Escolha errada de workflow (quick vs spec, solo vs agents) | `/oxe-scan`, qualquer entry |
+| `agents` | Problemas de orquestração, runId, dependências de agente | `/oxe-plan-agent`, `/oxe-execute` |
+
+**Formato de lição (prescritivo, não descritivo):**
+- ❌ "A tarefa T4 demorou muito" (descritivo — não ajuda no próximo ciclo)
+- ✅ "Tarefas com integração de terceiros devem ter Complexidade L mínimo + Verificar com mock fallback" (prescritivo — o próximo plan pode aplicar)
+</taxonomy>
+
+<process>
+1. Ler **`.oxe/VERIFY.md`** se existir: identificar tarefas que falharam, critérios A* sem evidência, gaps documentados.
+2. Ler **`.oxe/FORENSICS.md`** se existir: capturar causa raiz de falhas de execução.
+3. Ler **`.oxe/SUMMARY.md`** se existir: capturar contexto de replans e decisões forçadas.
+4. Ler **`.oxe/STATE.md`**: capturar número de ondas, execute_mode usado, se houve loop, se houve escalação para forensics.
+5. Sintetizar **3–5 lições prescritivas** (não mais — qualidade sobre quantidade):
+   - Cada lição responde: "O que o próximo ciclo deve fazer diferente?"
+   - Formato: **Lição** (o que fazer) + **Raiz** (por que isso aconteceu) + **Tipo** + **Aplicar em**
+6. Determinar o próximo **ciclo ID** (C-NN) lendo `.oxe/LESSONS.md` existente ou começando em C-01.
+7. Criar ou atualizar **`.oxe/LESSONS.md`** usando `oxe/templates/LESSONS.template.md`:
+   - Adicionar linha na tabela de índice (mais recente primeiro).
+   - Adicionar seção `### C-NN` com as lições sintetizadas.
+   - **Nunca apagar** entradas anteriores — só mudar `Status: resolvido` se a lição foi superada.
+8. Atualizar **`.oxe/STATE.md`**: campo `last_retro: YYYY-MM-DD`.
+9. Responder no chat: ID do ciclo (C-NN), número de lições registradas, lição mais crítica em 1 frase, sugestão do próximo ciclo (`/oxe-scan` ou `/oxe-spec`).
+</process>
+
+<success_criteria>
+- [ ] `.oxe/LESSONS.md` existe com entrada C-NN na tabela e seção de detalhe.
+- [ ] Cada lição é prescritiva (diz o que fazer) não descritiva (não é só o que aconteceu).
+- [ ] 3–5 lições por ciclo — não um dump completo de eventos.
+- [ ] `STATE.md` tem `last_retro` atualizado.
+- [ ] Entradas anteriores preservadas; apenas `Status` pode mudar.
+</success_criteria>

package/oxe/workflows/security.md

@@ -1,61 +1,62 @@
-# OXE — Workflow: security (auditoria de segurança)
-
-<objective>
-Produzir **`.oxe/SECURITY.md`**: auditoria de segurança do repositório focada nas categorias OWASP Top 10 **relevantes** ao stack do projeto. Complementa **`validate-gaps`** (cobertura de testes) com uma camada de segurança aplicativa.
-
-Pode ser chamado standalone ou como Camada 5 do **`verify.md`** quando `config.json` tiver `"security_in_verify": true`.
-
-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>
-
+# OXE — Workflow: security (auditoria de segurança)
+
+<objective>
+Produzir **`.oxe/SECURITY.md`**: auditoria de segurança do repositório focada nas categorias OWASP Top 10 **relevantes** ao stack do projeto. Complementa **`validate-gaps`** (cobertura de testes) com uma camada de segurança aplicativa.
+
+Pode ser chamado standalone ou como Camada 5 do **`verify.md`** quando `config.json` tiver `"security_in_verify": true`.
+
+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>
+- 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`.
-- **Integração com verify:** se `security_in_verify: true` em `.oxe/config.json`, o workflow `verify.md` inclui referência a este output como Camada 5. O `security.md` continua sendo o workflow canônico.
-- **Não alterar código:** apenas auditar e registrar achados. Nenhum arquivo de código é modificado.
-</context>
-
-<owasp_scope>
-## Mapeamento OWASP → Stack
-
-Antes de auditar, determinar quais categorias se aplicam lendo `STACK.md` e `INTEGRATIONS.md`:
-
-| Categoria OWASP | Aplicável quando |
-|-----------------|-----------------|
-| A01 — Broken Access Control | App com autenticação/autorização ou rotas protegidas |
-| A02 — Cryptographic Failures | Dados sensíveis em trânsito ou em repouso; senhas; tokens |
-| A03 — Injection | DB queries, shell commands, parsers de entrada, templates |
-| A04 — Insecure Design | Ausência de modelagem de ameaças; fluxos de negócio sem validação |
-| A05 — Security Misconfiguration | Config de servidor, CORS, headers HTTP, variáveis de ambiente |
-| A06 — Vulnerable Components | Dependências com CVEs conhecidos; versões sem suporte |
-| A07 — Authentication Failures | Login, sessão, JWT, OAuth, tokens de reset |
-| A08 — Software Integrity | Supply chain; checksums; CI/CD sem verificação |
-| A09 — Logging & Monitoring | Ausência de logs de eventos críticos; dados sensíveis em logs |
-| A10 — SSRF | Requisições a URLs controladas pelo usuário; fetch/proxy interno |
-
-**Selecionar apenas as categorias aplicáveis** ao stack identificado. Listar explicitamente as ignoradas e o motivo.
-</owasp_scope>
-
-<process>
-1. Ler `.oxe/codebase/STACK.md`, `.oxe/codebase/STRUCTURE.md`, `.oxe/codebase/INTEGRATIONS.md`, `.oxe/codebase/CONCERNS.md`.
-2. Selecionar categorias OWASP aplicáveis ao stack (ver `<owasp_scope>`); registrar as descartadas.
-3. Para cada categoria aplicável:
-   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`.
+- **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`.
+- **Integração com verify:** se `security_in_verify: true` em `.oxe/config.json`, o workflow `verify.md` inclui referência a este output como Camada 5. O `security.md` continua sendo o workflow canônico.
+- **Não alterar código:** apenas auditar e registrar achados. Nenhum arquivo de código é modificado.
+</context>
+
+<owasp_scope>
+## Mapeamento OWASP → Stack
+
+Antes de auditar, determinar quais categorias se aplicam lendo `STACK.md` e `INTEGRATIONS.md`:
+
+| Categoria OWASP | Aplicável quando |
+|-----------------|-----------------|
+| A01 — Broken Access Control | App com autenticação/autorização ou rotas protegidas |
+| A02 — Cryptographic Failures | Dados sensíveis em trânsito ou em repouso; senhas; tokens |
+| A03 — Injection | DB queries, shell commands, parsers de entrada, templates |
+| A04 — Insecure Design | Ausência de modelagem de ameaças; fluxos de negócio sem validação |
+| A05 — Security Misconfiguration | Config de servidor, CORS, headers HTTP, variáveis de ambiente |
+| A06 — Vulnerable Components | Dependências com CVEs conhecidos; versões sem suporte |
+| A07 — Authentication Failures | Login, sessão, JWT, OAuth, tokens de reset |
+| A08 — Software Integrity | Supply chain; checksums; CI/CD sem verificação |
+| A09 — Logging & Monitoring | Ausência de logs de eventos críticos; dados sensíveis em logs |
+| A10 — SSRF | Requisições a URLs controladas pelo usuário; fetch/proxy interno |
+
+**Selecionar apenas as categorias aplicáveis** ao stack identificado. Listar explicitamente as ignoradas e o motivo.
+</owasp_scope>
+
+<process>
+1. Ler `.oxe/codebase/STACK.md`, `.oxe/codebase/STRUCTURE.md`, `.oxe/codebase/INTEGRATIONS.md`, `.oxe/codebase/CONCERNS.md`.
+2. Selecionar categorias OWASP aplicáveis ao stack (ver `<owasp_scope>`); registrar as descartadas.
+3. Para cada categoria aplicável:
+   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 `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.
-- [ ] 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`.
-- [ ] Nenhum arquivo de código foi modificado.
-- [ ] STATE.md tem linha `security_audit` com data e contagem de achados.
-</success_criteria>
+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>
+- [ ] `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`.
+- [ ] Nenhum arquivo de código foi modificado.
+- [ ] STATE.md tem linha `security_audit` com data e contagem de achados.
+</success_criteria>