oxe-cc 1.11.0 → 1.14.0

package/oxe/workflows/agent-mode.md

@@ -0,0 +1,150 @@
+# OXE — Workflow: agent-mode (Agent Mode)
+
+<objective>
+Execução autônoma de objetivos de complexidade simples ou média por um único Conductor Agent.
+O Conductor age diretamente como implementador, adotando a persona primária selecionada pelo `conduct.md`, produzindo o resultado em uma sessão sem necessidade de equipe multi-agente.
+</objective>
+
+<context>
+- Invocado por `conduct.md` quando `intent_score` é simples ou médio.
+- Aplicar `oxe/workflows/references/reasoning-execution.md` durante a implementação.
+- Persona primária já foi selecionada e está disponível como parâmetro de entrada.
+- Gravar artefatos em `.oxe/agent/`.
+- Ao final, emitir eventos básicos para `OXE-EVENTS.ndjson` (RunStarted, WorkItemCompleted, RunCompleted).
+</context>
+
+---
+
+## Fase 1 — Inicialização da Sessão
+
+Criar `.oxe/agent/AGENT-SESSION.json` com:
+
+```json
+{
+  "session_id": "agent-<YYYYMMDD>-<seq>",
+  "started_at": "<ISO8601>",
+  "status": "running",
+  "objective": "<objetivo do usuário>",
+  "intent_score": "<simples|médio>",
+  "intent_tags": [],
+  "primary_persona": "<id>",
+  "memory_applied": false,
+  "tool_calls": [],
+  "work_items": [],
+  "reconciliation": null
+}
+```
+
+Registrar entrada em `.oxe/agent/INTENT-LOG.ndjson`:
+```json
+{"ts": "<ISO8601>", "objective": "<texto>", "score": "<score>", "tags": [], "persona": "<id>"}
+```
+
+---
+
+## Fase 2 — Discovery (reasoning-execution: "reconhecimento curto")
+
+Antes de mutar qualquer arquivo, executar um reconhecimento mínimo:
+
+1. Ler arquivos relevantes ao objetivo (usar Glob + Grep conforme intent_tags)
+2. Identificar:
+   - **Arquivos que serão modificados** (write_set)
+   - **Padrões existentes** a seguir (naming, estrutura, imports)
+   - **Riscos imediatos** (arquivo crítico? Arquivo compartilhado? Arquivo com testes?)
+3. Se o write_set for maior que o esperado para `intent_score=simples` (> 5 arquivos): **parar e elevar para Swarm Mode**
+
+Registrar discovery em `.oxe/agent/AGENT-SESSION.json` → campo `work_items`.
+
+---
+
+## Fase 3 — Execução (sob persona selecionada)
+
+Adotar os princípios da persona primária de `oxe/personas/<primary_persona>.md`:
+
+- **Write set mínimo** — tocar apenas os arquivos identificados no discovery
+- **Verificar antes de avançar** — executar verificação ao completar cada item
+- **Discoveries fora de escopo** → `.oxe/OBSERVATIONS.md` (não expandir silenciosamente)
+- **Segredos nunca em código**
+
+Para cada `work_item`:
+1. Implementar conforme objetivo
+2. Verificar (comando ou checklist)
+3. Atualizar `AGENT-SESSION.json` → `work_items[i].status = "done" | "failed"`
+4. Registrar em `INTENT-LOG.ndjson`: `{"ts": "...", "item": "...", "status": "...", "files_changed": []}`
+
+---
+
+## Fase 4 — Reconciliação
+
+Ao finalizar todos os `work_items`:
+
+1. Listar todos os arquivos modificados
+2. Confirmar que o objetivo foi satisfeito (sim/parcialmente/não)
+3. Listar discoveries relevantes registrados em OBSERVATIONS.md
+
+Atualizar `AGENT-SESSION.json`:
+```json
+{
+  "status": "completed | partial | failed",
+  "completed_at": "<ISO8601>",
+  "files_changed": ["lista de arquivos"],
+  "reconciliation": {
+    "objective_satisfied": true,
+    "observations_added": 0,
+    "next_suggested": "<próximo passo se houver>"
+  }
+}
+```
+
+Gravar `.oxe/agent/RECONCILIATION.md` com:
+```markdown
+## Reconciliação — <session_id>
+
+**Objetivo:** <texto>
+**Resultado:** satisfeito | parcial | falhou
+**Arquivos alterados:** <lista>
+**Observações adicionadas:** <N>
+**Próximo passo:** <texto ou "—">
+```
+
+---
+
+## Fase 5 — Eventos
+
+Emitir no final para `.oxe/OXE-EVENTS.ndjson` (append, uma linha NDJSON por evento):
+
+```json
+{"id": "<uuid>", "type": "RunStarted", "timestamp": "<ISO8601>", "session_id": "<id>", "run_id": "<session_id>", "payload": {"mode": "agent", "objective": "<texto>", "persona": "<id>"}}
+{"id": "<uuid>", "type": "WorkItemCompleted", "timestamp": "<ISO8601>", "session_id": "<id>", "run_id": "<session_id>", "payload": {"items_completed": N, "files_changed": []}}
+{"id": "<uuid>", "type": "RunCompleted", "timestamp": "<ISO8601>", "session_id": "<id>", "run_id": "<session_id>", "payload": {"status": "completed", "objective_satisfied": true}}
+```
+
+**Se `OXE-EVENTS.ndjson` não existir:** criar com o primeiro evento.
+
+---
+
+## Saída para o usuário
+
+Ao final, reportar:
+
+```
+Agent Mode — concluído
+Objetivo: <texto resumido>
+Persona: <id>
+Arquivos alterados: N
+Verificação: passou | falhou
+
+<lista de arquivos>
+
+Próximo passo: <recomendação ou "—">
+```
+
+<success_criteria>
+- [ ] AGENT-SESSION.json criado e atualizado ao longo da execução.
+- [ ] Persona primária adotada (princípios de operação aplicados).
+- [ ] Write set mínimo respeitado.
+- [ ] Verificação executada por work_item.
+- [ ] RECONCILIATION.md gerado.
+- [ ] OXE-EVENTS.ndjson atualizado (RunStarted + WorkItemCompleted + RunCompleted).
+- [ ] Discoveries fora de escopo → OBSERVATIONS.md, não expansão silenciosa.
+</success_criteria>

package/oxe/workflows/conduct.md

@@ -0,0 +1,149 @@
+# OXE — Workflow: conduct (Conductor Agent)
+
+<objective>
+Ponto de entrada para objetivos em linguagem natural que requerem execução autônoma.
+O Conductor classifica a complexidade do objetivo, recupera memória relevante, carrega as personas adequadas e decide se o trabalho será feito em **Agent Mode** (Conductor age sozinho) ou **Swarm Mode** (equipe de agentes especializados).
+
+Invocado automaticamente por `oxe.md` quando o input é um **objetivo ou tarefa de implementação** — não uma pergunta situacional, não um pedido de roteamento simples.
+</objective>
+
+<context>
+- Este workflow **gera artefatos**: `AGENT-SESSION.json` (Agent Mode) ou `SWARM-RUN.json` (Swarm Mode).
+- Aplicar `oxe/workflows/references/reasoning-planning.md` para a fase de decisão.
+- Aplicar `oxe/workflows/references/reasoning-execution.md` quando agir diretamente (Agent Mode).
+- Lê: `.oxe/STATE.md`, `.oxe/memory/REPO-MEMORY.md` (se existir), `.oxe/global/LESSONS.md`.
+- Nunca expande escopo além do objetivo declarado. Discoveries vão para OBSERVATIONS.md.
+</context>
+
+---
+
+## Fase 1 — Intent Classification
+
+Ler o objetivo do usuário e classificar em uma das três categorias:
+
+| Score | Critérios | Modo |
+|-------|-----------|------|
+| **simples** | 1 domínio, ≤ 3 arquivos esperados, mudança isolada (texto, config, estilo, bug local) | Agent Mode |
+| **médio** | 1–2 domínios, 3–8 arquivos, lógica nova mas contida (endpoint, componente, função) | Agent Mode |
+| **complexo** | 3+ domínios, 8+ arquivos, ou: nova feature com storage + backend + frontend + testes | Swarm Mode |
+
+**Sinais de complexidade que forçam Swarm Mode:**
+- Objetivo menciona: "módulo", "sistema", "fluxo completo", "histórico", "relatório", "pipeline"
+- Objetivo envolve: banco de dados + API + UI simultaneamente
+- Objetivo requer scaffold de múltiplos arquivos em diretórios diferentes
+- Estimativa de ondas > 2 no PLAN.md
+
+**Saída desta fase:**
+```
+intent_score: simples | médio | complexo
+intent_tags: [lista de domínios detectados: backend, frontend, storage, auth, infra, test, docs, config]
+objective_summary: resumo em 1 frase do que o usuário quer
+```
+
+---
+
+## Fase 2 — Memory Retrieval
+
+Ler as camadas de memória na ordem:
+
+1. `.oxe/STATE.md` — estado atual da trilha (fase, sessão ativa, run ativo)
+2. `.oxe/memory/REPO-MEMORY.md` — memória cross-session (decisões, pitfalls, preferências) — **se existir**
+3. `.oxe/global/LESSONS.md` — lições de ciclos anteriores com `Status: ativo` e `Impacto: alto` — **se existir**
+4. `.oxe/OBSERVATIONS.md` — observações pendentes com `Status: pendente` — **se existir**
+
+Para cada camada lida, extrair apenas o que é **relevante ao objetivo atual** (usar intent_tags como filtro).
+
+Gravar snapshot do contexto injetado:
+- Agent Mode → `.oxe/agent/MEMORY-INJECTIONS.md`
+- Swarm Mode → `.oxe/swarm/DECISIONS.md` (seção "Contexto de Memória")
+
+**Se `.oxe/memory/` não existir:** pular silenciosamente e continuar.
+
+---
+
+## Fase 3 — Skill Loading
+
+Com base nos `intent_tags`, selecionar as personas aplicáveis:
+
+| Tag | Persona primária | Persona secundária |
+|-----|------------------|--------------------|
+| backend | executor | architect |
+| frontend | ui-specialist | executor |
+| storage | db-specialist | architect |
+| auth | architect | executor |
+| infra | architect | — |
+| test | executor | verifier |
+| docs | executor | — |
+| config | executor | — |
+| research | researcher | — |
+| debug | debugger | — |
+
+Registrar personas selecionadas em:
+- Agent Mode → `.oxe/agent/SKILLS-LOADED.json`
+- Swarm Mode → informação vai para fase de atribuição de papéis
+
+**Resolução:** tentar `oxe/personas/<id>.md` (global) → `.oxe/skills/active/<id>.md` (projeto). Usar o primeiro encontrado.
+
+---
+
+## Fase 4 — Decisão de Modo
+
+Com base no `intent_score`:
+
+### Se simples ou médio → Agent Mode
+
+Executar `oxe/workflows/agent-mode.md` com:
+- `objective`: objetivo original do usuário
+- `intent_tags`: tags detectadas
+- `primary_persona`: persona primária selecionada
+- `memory_context`: contexto de memória extraído
+
+### Se complexo → Swarm Mode
+
+Executar `oxe/workflows/swarm-mode.md` com:
+- `objective`: objetivo original do usuário
+- `intent_tags`: tags detectadas
+- `memory_context`: contexto de memória extraído
+
+**Comunicar ao usuário antes de prosseguir:**
+
+Para Agent Mode:
+```
+Conductor: modo Agent (complexidade: [score])
+Persona: [primary_persona]
+Domínios: [intent_tags]
+Memória aplicada: [sim/não — N lições, M pitfalls]
+
+Executando...
+```
+
+Para Swarm Mode:
+```
+Conductor: modo Swarm (complexidade: complexo)
+Domínios: [intent_tags]
+Agentes: Scout + [N] Builders + Reviewer + Verifier
+Memória aplicada: [sim/não — N lições, M pitfalls]
+
+Iniciando Scout...
+```
+
+---
+
+## Artefatos gerados por este workflow
+
+| Artefato | Modo | Caminho |
+|----------|------|---------|
+| AGENT-SESSION.json | Agent | `.oxe/agent/AGENT-SESSION.json` |
+| SKILLS-LOADED.json | Agent | `.oxe/agent/SKILLS-LOADED.json` |
+| MEMORY-INJECTIONS.md | Agent | `.oxe/agent/MEMORY-INJECTIONS.md` |
+| SWARM-RUN.json | Swarm | `.oxe/swarm/SWARM-RUN.json` |
+| DECISIONS.md | Swarm | `.oxe/swarm/DECISIONS.md` |
+
+<success_criteria>
+- [ ] Intent score determinado (simples/médio/complexo).
+- [ ] Memória lida e filtrada por intent_tags.
+- [ ] Persona(s) selecionada(s) e registrada(s).
+- [ ] Usuário informado do modo escolhido antes da execução.
+- [ ] Delegação correta: agent-mode.md ou swarm-mode.md.
+- [ ] Nenhum artefato de SPEC/PLAN criado por este workflow.
+</success_criteria>

package/oxe/workflows/distill.md

@@ -0,0 +1,164 @@
+# OXE — Workflow: distill (Learning Kernel)
+
+<objective>
+Ao final de um Swarm Run (ou Agent Mode run), extrair padrões do que aconteceu,
+detectar lições reutilizáveis e candidatas a novas skills, atualizar LESSONS.md com dedup,
+e enfileirar na PROMOTION-QUEUE.md as skills candidatas para revisão humana.
+</objective>
+
+<context>
+- Invocado por `swarm-mode.md` Fase 8 (após Verifier) ou por `/oxe-verify` com `--retro`.
+- Reaproveitamento: LESSONS.md taxonomy e regras de dedup de `.oxe/global/LESSONS.md`.
+- Reaproveitamento: `LessonPromoted` event type de `packages/runtime/src/events/catalog.ts`.
+- Não modifica arquivos de código. Apenas lê run artifacts e grava em `.oxe/learning/` e `.oxe/global/`.
+- Parâmetros de entrada: `run_id`, `mode` (swarm|agent).
+</context>
+
+---
+
+## Fase 1 — Coleta de evidências do run
+
+Ler os seguintes artefatos do run (pular silenciosamente se não existirem):
+
+**Para Swarm Mode:**
+- `.oxe/swarm/SWARM-RUN.json` — status geral, agentes, waves
+- `.oxe/swarm/FINAL-INTEGRATION.md` — resultado da integração
+- `.oxe/swarm/BLOCKERS.ndjson` — bloqueios que ocorreram
+- `.oxe/swarm/reviews/*.md` — resultados das revisões
+- `.oxe/swarm/DECISIONS.md` — decisões tomadas pelo coordinator
+
+**Para Agent Mode:**
+- `.oxe/agent/AGENT-SESSION.json` — status, work_items, reconciliation
+- `.oxe/agent/RECONCILIATION.md` — resultado final
+
+**Sempre:**
+- `.oxe/OBSERVATIONS.md` — observações adicionadas durante o run
+- `.oxe/VERIFY.md` (se existir) — resultado de verificação
+
+---
+
+## Fase 2 — Detecção de padrões (candidatos)
+
+Para cada evidência coletada, identificar padrões nas categorias:
+
+| Categoria | Sinal de detecção |
+|-----------|------------------|
+| **blocker_pattern** | Mesmo tipo de bloqueio em 2+ tasks do mesmo run |
+| **success_pattern** | Approach que funcionou e pode ser replicado |
+| **anti_pattern** | Abordagem que causou revisão reprovada ou retrabalho |
+| **file_conflict_pattern** | Conflito de file ownership que exigiu serialização |
+| **integration_gap** | Falha na integração que não foi detectada nas tasks individuais |
+| **scope_expansion** | Observation de tipo `new_constraint` que alargou o escopo |
+
+Para cada padrão detectado, criar entrada em `.oxe/learning/CANDIDATES.ndjson`:
+```json
+{"id": "CAND-001", "type": "lesson|skill", "category": "blocker_pattern", "source_run": "swarm-YYYYMMDD-001", "pattern": "descrição do padrão detectado", "draft": "lição prescritiva em 1 frase: faça X ao invés de Y", "evidence": ["BLOCKERS.ndjson#T2", "reviews/T2-REVIEW.md"], "ts": "ISO8601"}
+```
+
+---
+
+## Fase 3 — Atualização de LESSONS.md
+
+Para cada candidato com `type = "lesson"`:
+
+1. Verificar se já existe lição com mesma raiz (mesma categoria + padrão similar) em `.oxe/global/LESSONS.md`
+2. **Se existe:** incrementar `Frequência` + atualizar `Última aplicação` (não duplicar)
+3. **Se não existe:** adicionar nova entrada `C-NN-L1` com:
+   - `Lição`: texto prescritivo (o que fazer, não o que aconteceu)
+   - `Raiz`: causa raiz identificada
+   - `Tipo`: spec | plan | execute | verify | process | agents
+   - `Aplicar em`: qual workflow consome esta lição
+   - `Status`: ativo
+   - `Frequência`: 1
+   - `Impacto`: alto | médio | baixo (baseado no severity do padrão)
+   - `Última aplicação`: data do run
+
+Atualizar índice (tabela de conteúdos) em LESSONS.md.
+
+---
+
+## Fase 4 — Atualização de lessons-metrics.json
+
+Se `.oxe/lessons-metrics.json` existir (ou criar a partir do template):
+
+Para cada lição atualizada ou criada:
+```json
+{
+  "id": "C-NN-L1",
+  "cycle": "C-NN",
+  "applied_cycles": ["swarm-YYYYMMDD-001"],
+  "outcomes": [{"run_id": "...", "result": "success|partial|failure", "ts": "..."}],
+  "success_rate": 1.0,
+  "status": "active",
+  "deprecation_threshold": 0.5
+}
+```
+
+**Regra de depreciação automática:** se `success_rate < 0.5` e `apply_count >= 3` → `status = deprecated`.
+
+---
+
+## Fase 5 — Candidatas a Skill
+
+Para candidatos com `type = "skill"` (padrões recorrentes que podem virar persona/capability):
+
+Verificar critérios de promoção:
+- Padrão apareceu em 2+ runs diferentes, OU
+- Padrão é um `success_pattern` com alta reprodutibilidade
+
+Adicionar à `.oxe/learning/PROMOTION-QUEUE.md`:
+```markdown
+## SKILL-001 — <nome sugerido>
+
+**Fonte:** <run_id>
+**Categoria:** <category>
+**Padrão:** <descrição>
+**Draft do skill:** <esboço do comportamento que o skill encapsularia>
+**Ação:** [ ] Revisar e promover com `/oxe-skill new <id>`
+```
+
+---
+
+## Fase 6 — Atualização de REPO-MEMORY.md
+
+Se o run gerou decisões arquiteturais ou pitfalls novos:
+
+Adicionar entradas em `.oxe/memory/REPO-MEMORY.md`:
+- Seção "Decisões Arquiteturais" para decisões tomadas pelo Coordinator
+- Seção "Pitfalls Conhecidos" para blockers que ocorreram
+- Seção "Padrões Validados" para success_patterns confirmados
+
+Se o arquivo não existir, criá-lo a partir de `.oxe/templates/REPO-MEMORY.template.md`.
+
+---
+
+## Fase 7 — Eventos
+
+Emitir para `.oxe/OXE-EVENTS.ndjson`:
+```json
+{"type": "RetroPublished", "payload": {"run_id": "...", "lessons_added": N, "lessons_updated": M}}
+{"type": "LessonPromoted", "payload": {"lesson_id": "C-NN-L1", "frequency": N, "impact": "alto"}}
+```
+
+---
+
+## Saída para o usuário (quando invocado explicitamente)
+
+```
+Learning Kernel — concluído
+Run: <run_id>
+Candidatos detectados: N
+Lições adicionadas: X | atualizadas: Y | depreciadas: Z
+Skills candidatas para revisão: M (ver .oxe/learning/PROMOTION-QUEUE.md)
+REPO-MEMORY atualizado: sim | não
+```
+
+<success_criteria>
+- [ ] CANDIDATES.ndjson populado com padrões detectados do run.
+- [ ] LESSONS.md atualizado com dedup correto (sem duplicatas, Frequência incrementada).
+- [ ] lessons-metrics.json atualizado com outcomes e success_rate.
+- [ ] PROMOTION-QUEUE.md com skills candidatas (se houver).
+- [ ] REPO-MEMORY.md atualizado com decisões e pitfalls.
+- [ ] Eventos LessonPromoted emitidos.
+- [ ] Nenhum arquivo de código do projeto modificado.
+</success_criteria>

package/oxe/workflows/help.md

@@ -217,6 +217,7 @@ Um pedido → **um** destino (sem gerar contrato). O agente aplica `route.md` ou
 
 | Se o utilizador disser (exemplos) | Comando / ação |
 |-----------------------------------|----------------|
+| **Objetivo de implementação** (“cria X”, “implementa Y”, “adiciona Z”, “corrige W”, “desenvolve N”) | `/oxe <objetivo>` → Conductor decide automaticamente Agent Mode (simples/médio) ou Swarm Mode (complexo) |
 | Não sei que passo OXE sou / “o que faço agora?” | `/oxe` ou `npx oxe-cc status` |
 | Quero entender rapidamente a situação real da trilha atual | `/oxe “pergunta”` |
 | Acabei de clonar / falta OXE no projeto | `npx oxe-cc@latest` (ou `oxe-cc`) na raiz do repo |

package/oxe/workflows/memory.md

@@ -0,0 +1,163 @@
+# OXE — Workflow: memory (Memory Kernel)
+
+<objective>
+Protocolo de recuperação de memória para o Conductor Agent.
+Lê as 4 camadas de memória do OXE na ordem correta, filtra por relevância ao objetivo atual
+e retorna um context pack para injeção antes de qualquer execução (Agent Mode ou Swarm Mode).
+</objective>
+
+<context>
+- Invocado por `conduct.md` Fase 2 (Memory Retrieval).
+- Não modifica artefatos de projeto. Apenas lê e grava em `.oxe/memory/retrieved/`.
+- Reaproveitamento: `buildMemoryLayers()` em `bin/lib/oxe-operational.cjs:2364` define a ordem das camadas.
+- Reaproveitamento: `extractSemanticFragment()` em `bin/lib/oxe-context-engine.cjs` para extração filtrada.
+- Parâmetros de entrada: `intent_tags`, `phase` (conduct|spec|plan|execute|verify), `objective`.
+</context>
+
+---
+
+## Camadas de memória (ordem de leitura)
+
+| # | Camada | Arquivo | Conteúdo |
+|---|--------|---------|----------|
+| 1 | runtime_state | `.oxe/STATE.md` | Fase atual, sessão ativa, run ativo |
+| 2 | session_memory | `.oxe/<session>/SESSION.md` | Contexto da sessão ativa (se existir) |
+| 3 | project_memory | `.oxe/memory/REPO-MEMORY.md` | Decisões cross-session, pitfalls, preferências |
+| 4 | lessons | `.oxe/global/LESSONS.md` | Lições de ciclos anteriores |
+| 5 | observations | `.oxe/OBSERVATIONS.md` | Observações pendentes |
+
+---
+
+## Fase 1 — Leitura das camadas
+
+Para cada camada, verificar se o arquivo existe. Se não existir, pular silenciosamente.
+
+**Filtro de relevância:** para cada camada, extrair apenas seções que contenham pelo menos uma das `intent_tags` no texto, ou que estejam marcadas com `Aplicar em` compatível com a `phase` atual.
+
+**Para LESSONS.md:** filtrar por:
+- `Status: ativo`
+- `Impacto: alto` (prioridade máxima) ou `Frequência >= 2` (lições recorrentes)
+- `Aplicar em` contém a `phase` atual
+
+**Para OBSERVATIONS.md:** filtrar por:
+- `Status: pendente`
+- `Impacto` inclui a `phase` atual ou `all`
+
+---
+
+## Fase 2 — Ranking por relevância
+
+Para cada fragmento extraído, atribuir score de relevância:
+
+| Critério | Score |
+|---------|-------|
+| Tag exata em intent_tags | +3 |
+| Impacto: alto | +2 |
+| Frequência >= 3 | +2 |
+| Phase match exato | +2 |
+| Frequência >= 2 | +1 |
+| Menção ao objetivo (palavras-chave) | +1 |
+
+Ordenar fragmentos por score decrescente. Manter top-10 para injeção (ou todos se < 10).
+
+---
+
+## Fase 3 — Geração do Context Pack
+
+Gerar arquivo de injeção baseado no mode:
+
+**Agent Mode** → `.oxe/agent/MEMORY-INJECTIONS.md`
+**Swarm Mode** → `.oxe/swarm/DECISIONS.md` (seção "Contexto de Memória")
+
+Formato do context pack:
+```markdown
+## Contexto de Memória — <phase> / <timestamp>
+
+**Objetivo:** <texto>
+**Intent Tags:** <lista>
+**Fontes:** <camadas lidas>
+
+### Lições aplicáveis
+<fragmentos de LESSONS.md ordenados por relevância>
+
+### Pitfalls conhecidos
+<fragmentos de REPO-MEMORY.md relevantes>
+
+### Observações pendentes
+<fragmentos de OBSERVATIONS.md com impacto na fase atual>
+
+### Estado atual
+<fragmento de STATE.md>
+```
+
+---
+
+## Fase 4 — Snapshot rastreável
+
+Gravar snapshot do contexto injetado em `.oxe/memory/retrieved/<phase>.md` para auditoria.
+
+Se o diretório `.oxe/memory/retrieved/` não existir, criar.
+
+---
+
+## Estrutura `.oxe/memory/REPO-MEMORY.md`
+
+Quando criado pela primeira vez (após primeiro swarm run completo), deve seguir:
+
+```markdown
+# Memória do Repositório
+
+> Memória cross-session. Atualizada automaticamente pelo Learning Kernel ao final de cada Swarm Run.
+> Contém decisões arquiteturais, pitfalls recorrentes e preferências do projeto.
+
+## Decisões Arquiteturais
+
+| ID | Decisão | Contexto | Data |
+|----|---------|----------|------|
+
+## Pitfalls Conhecidos
+
+| ID | Problema | Causa | Solução | Frequência |
+|----|---------|-------|---------|-----------|
+
+## Preferências do Projeto
+
+| Categoria | Preferência | Fonte |
+|-----------|------------|-------|
+
+## Padrões Validados
+
+| Padrão | Contexto | Data |
+|--------|---------|------|
+```
+
+---
+
+## Estrutura `.oxe/memory/MEMORY-INDEX.json`
+
+```json
+{
+  "updated_at": "ISO8601",
+  "entries": [
+    {
+      "id": "MEM-001",
+      "type": "lesson | pitfall | decision | preference | pattern",
+      "phase": ["spec", "plan", "execute", "verify", "conduct"],
+      "relevance_tags": ["backend", "auth"],
+      "source": ".oxe/global/LESSONS.md#C-01-L1",
+      "summary": "Uma frase resumindo o conteúdo",
+      "created_at": "ISO8601",
+      "last_applied": "ISO8601",
+      "apply_count": 2
+    }
+  ]
+}
+```
+
+<success_criteria>
+- [ ] Camadas lidas na ordem correta (runtime_state → session → project → lessons → observations).
+- [ ] Filtro de relevância aplicado por intent_tags e phase.
+- [ ] Context pack gerado no caminho correto (agent ou swarm).
+- [ ] Snapshot gravado em `.oxe/memory/retrieved/<phase>.md`.
+- [ ] Arquivos ausentes pular silenciosamente (sem erro).
+</success_criteria>

package/oxe/workflows/oxe.md

@@ -135,7 +135,8 @@ Não precisam ser decorados como comandos separados:
    - **Sem input ou "next / o que faço / status":** aplicar `<modo_status>`.
    - **"help / comandos / o que é OXE":** aplicar `<modo_help>`.
    - **Pergunta situacional** ("onde estou?", "qual o risco?", "o que está acontecendo?", "me contextualize"): aplicar `<modo_pergunta>`.
-   - **Input de ação/tarefa** (linguagem natural com contexto operacional): aplicar `<modo_route>` e, se o workflow for claro, carregar e executar diretamente o `oxe/workflows/<nome>.md` correspondente.
+   - **Objetivo de implementação** (linguagem natural descrevendo uma tarefa, feature ou mudança a executar — ex.: "cria X", "implementa Y", "adiciona Z", "corrige W"): carregar e executar diretamente `oxe/workflows/conduct.md`. O Conductor decide Agent Mode vs Swarm Mode automaticamente.
+   - **Input de roteamento simples** (pedido que mapeia diretamente a um comando OXE existente sem necessidade de execução): aplicar `<modo_route>` e, se o workflow for claro, carregar e executar diretamente o `oxe/workflows/<nome>.md` correspondente.
 2. Nunca produzir listas longas de alternativas. Um passo, um comando, uma frase.
 3. Se o workflow executado diretamente gerar artefatos, reportar no chat conforme esse workflow.
 </process>