oxe-cc 0.3.9 → 0.6.0

package/oxe/templates/MEMORY.template.md

@@ -0,0 +1,49 @@
+---
+oxe_memory: true
+persona: (executor | planner | verifier | researcher | debugger | architect | ui-specialist | db-specialist | custom)
+session: YYYY-MM-DD
+project: (nome do projeto ou — )
+---
+
+# OXE — Memory Sidecar
+
+> Memória persistente de sessão para agente OXE.
+> Criado automaticamente pelo workflow que gerou esta sessão.
+> Referenciado no STATE.md sob **Memory (sidecars de sessão)**.
+
+## Contexto da sessão
+
+- **Data:** YYYY-MM-DD
+- **Persona:** (nome da persona)
+- **Escopo:** (o que foi trabalhado nesta sessão)
+- **Fase OXE:** scan_complete | spec_ready | discuss_complete | plan_ready | executing | verify_complete
+
+## Aprendizados
+
+_(O que foi descoberto que não estava no codebase ou na SPEC)_
+
+- …
+
+## Decisões tomadas
+
+_(Decisões D-NN relevantes para sessões futuras)_
+
+- D-NN: …
+
+## Padrões observados
+
+_(Padrões de código, arquitetura ou comportamento identificados)_
+
+- …
+
+## Avisos para sessões futuras
+
+_(Armadilhas, fragilidades, ou contexto que o próximo agente precisa saber)_
+
+- …
+
+## Arquivos chave acessados
+
+_(Paths mais importantes lidos/modificados nesta sessão)_
+
+- `…`

package/oxe/templates/MILESTONES.template.md

@@ -0,0 +1,17 @@
+# OXE — Milestones
+
+> Índice de marcos de entrega do projeto. Cada milestone é uma versão com artefatos arquivados em `.oxe/milestones/M-NN/`.
+
+## M-01 — (nome) (ativo)
+
+- **Status:** ativo | entregue | cancelado
+- **Iniciado:** YYYY-MM-DD
+- **Encerrado:** — (preencher ao completar)
+- **SPEC:** `.oxe/SPEC.md` | `.oxe/milestones/M-01/SPEC.md` (após arquivamento)
+- **Critérios:** A1, A2, … (IDs da SPEC)
+- **Entregável:** (descrever o que este milestone entrega)
+- **Notas:** (opcional)
+
+---
+
+_(Adicione M-02, M-03, … conforme `/oxe-milestone new`.)_

package/oxe/templates/OBSERVATIONS.template.md

@@ -0,0 +1,18 @@
+# Observações OXE
+
+<!-- Registradas via /oxe-obs. Incorporadas automaticamente em /oxe-spec, /oxe-plan,
+     /oxe-discuss e /oxe-execute quando há entradas com status: pendente.
+     Após incorporação: status muda para "incorporada → <workflow> (YYYY-MM-DD)". -->
+
+| ID | Data | Contexto | Impacto | Status |
+|----|------|----------|---------|--------|
+| OBS-001 | YYYY-MM-DD | [fase/tarefa] | spec, plan, execute ou all | pendente |
+
+---
+
+### OBS-001 — YYYY-MM-DD | [contexto: fase atual / tarefa ativa]
+
+**Impacto:** spec | plan | execute | all
+**Status:** pendente
+
+[Texto da observação — restrição, descoberta técnica, preferência, risco ou decisão]

package/oxe/templates/PLUGINS.md

@@ -0,0 +1,101 @@
+# OXE — Plugin System
+
+Plugins OXE são módulos CJS colocados em **`.oxe/plugins/`** que se executam em resposta a eventos do ciclo de vida dos workflows.
+
+## Instalação
+
+Crie um arquivo `.cjs` em `.oxe/plugins/`:
+
+```js
+// .oxe/plugins/meu-plugin.cjs
+module.exports = {
+  name: 'meu-plugin',
+  version: '1.0.0',
+  hooks: {
+    async onAfterVerify({ projectRoot, result }) {
+      if (result === 'verify_complete') {
+        console.log('[meu-plugin] Entrega verificada com sucesso!');
+      }
+    },
+  },
+};
+```
+
+## Hooks disponíveis
+
+| Hook | Quando dispara | Contexto (`ctx`) |
+|------|---------------|------------------|
+| `onBeforeScan` | Antes do scan iniciar | `{ projectRoot }` |
+| `onAfterScan` | Após os 7 mapas serem gerados | `{ projectRoot, maps: string[] }` |
+| `onBeforeSpec` | Antes do workflow spec | `{ projectRoot }` |
+| `onAfterSpec` | Após SPEC.md ser gerado | `{ projectRoot, specPath: string }` |
+| `onBeforePlan` | Antes do workflow plan | `{ projectRoot }` |
+| `onAfterPlan` | Após PLAN.md ser gerado | `{ projectRoot, planPath: string }` |
+| `onPlanGenerated` | Alias de `onAfterPlan` | `{ projectRoot, planPath: string }` |
+| `onBeforeExecute` | Antes de iniciar uma onda | `{ projectRoot, wave: number }` |
+| `onAfterExecute` | Após onda concluída | `{ projectRoot, wave: number, tasks: string[] }` |
+| `onBeforeVerify` | Antes do workflow verify | `{ projectRoot }` |
+| `onAfterVerify` | Após VERIFY.md ser gerado | `{ projectRoot, result: 'verify_complete'\|'verify_failed' }` |
+| `onVerifyComplete` | Quando verify_complete | `{ projectRoot, verifyPath: string }` |
+| `onVerifyFailed` | Quando verify_failed | `{ projectRoot, verifyPath: string, gaps: string[] }` |
+| `onMilestoneNew` | Novo milestone criado | `{ projectRoot, milestoneId: string, name: string }` |
+| `onMilestoneComplete` | Milestone encerrado | `{ projectRoot, milestoneId: string, archivePath: string }` |
+| `onWorkstreamNew` | Novo workstream criado | `{ projectRoot, workstream: string }` |
+
+## Exemplos de uso
+
+### Notificação Slack
+
+```js
+// .oxe/plugins/slack-notify.cjs
+const https = require('https');
+
+module.exports = {
+  name: 'slack-notify',
+  version: '1.0.0',
+  hooks: {
+    async onVerifyComplete({ projectRoot }) {
+      const webhookUrl = process.env.SLACK_WEBHOOK_OXE;
+      if (!webhookUrl) return;
+      // enviar notificação...
+    },
+  },
+};
+```
+
+### Geração de changelog
+
+```js
+// .oxe/plugins/changelog.cjs
+const fs = require('fs');
+const path = require('path');
+
+module.exports = {
+  name: 'changelog',
+  version: '1.0.0',
+  hooks: {
+    async onMilestoneComplete({ projectRoot, milestoneId }) {
+      const entry = `## ${milestoneId} — ${new Date().toISOString().split('T')[0]}\n\n`;
+      const changelogPath = path.join(projectRoot, 'CHANGELOG.md');
+      const existing = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+      fs.writeFileSync(changelogPath, entry + existing, 'utf8');
+    },
+  },
+};
+```
+
+## Erros em plugins
+
+Erros em hooks individuais são capturados e logados como warnings — não interrompem o workflow. Use `oxe-cc doctor` para validar plugins:
+
+```bash
+oxe-cc doctor --plugins
+```
+
+## Regras
+
+1. Plugins devem ter extensão `.cjs`.
+2. Plugins devem exportar `name` (string) e `hooks` (objeto).
+3. Hooks são assíncronos por padrão mas podem ser síncronos.
+4. Plugins não devem alterar artefatos OXE diretamente (STATE.md, PLAN.md, etc.) — use os outputs do contexto.
+5. Máximo recomendado: 20 plugins por projeto.

package/oxe/templates/ROADMAP.template.md

@@ -0,0 +1,44 @@
+---
+oxe_doc: roadmap
+status: draft
+updated: YYYY-MM-DD
+spec_ref: .oxe/SPEC.md
+---
+
+# Roteiro de Entrega
+
+<!-- Produzido pelo /oxe-spec (Fase 4). Cada fase mapeia requisitos R-ID → critérios A* da SPEC.
+     Fase 1 é o alvo do próximo /oxe-plan ou /oxe-plan-agent.
+     Fases seguintes entram em ciclos futuros de spec → plan → execute → verify. -->
+
+## Fase 1 — [Nome curto da fase]
+
+**Requisitos:** R1, R2
+**Critérios de aceite:** A1, A2, A3
+**Escopo:** o que será construído nesta fase (1–3 frases)
+
+## Fase 2 — [Nome curto da fase]
+
+**Requisitos:** R3, R4
+**Critérios de aceite:** A4, A5
+**Escopo:** o que será construído nesta fase (1–3 frases)
+
+<!-- Adicionar mais fases conforme necessário -->
+
+---
+
+## Fora do escopo (v2+)
+
+| Requisito | Motivo do adiamento |
+|-----------|---------------------|
+| R5: [descrição] | Complexidade técnica — reservado para v2 |
+| R6: [descrição] | Depende de R3 estar estável |
+
+---
+
+## Histórico de aprovação
+
+| Versão | Data | Comentário |
+|--------|------|------------|
+| v1 draft | YYYY-MM-DD | Gerado pelo /oxe-spec |
+| v1 aprovado | YYYY-MM-DD | Aprovado pelo usuário — seguir para /oxe-plan Fase 1 |

package/oxe/templates/SECURITY.template.md

@@ -0,0 +1,72 @@
+---
+oxe_doc: security
+status: draft
+updated: YYYY-MM-DD
+stack_ref: .oxe/codebase/STACK.md
+plan_ref: .oxe/PLAN.md
+---
+
+# Auditoria de Segurança OXE
+
+## Stack e escopo
+
+**Stack identificado:** [linguagem, framework, DB, auth]
+**Categorias OWASP avaliadas:** A01, A02, A03, ...
+**Categorias descartadas:** A04 (motivo), A08 (motivo), ...
+
+---
+
+## Achados
+
+### P0 — Crítico (requer ação imediata)
+
+| ID | Categoria | Arquivo:linha | Padrão encontrado | Recomendação | Tarefa |
+|----|-----------|--------------|-------------------|--------------|--------|
+| S-01 | A07 — Auth | `src/auth/login.ts:42` | Senha comparada sem hash | Usar bcrypt/argon2 | T_new |
+
+### P1 — Alto (antes do próximo deploy)
+
+| ID | Categoria | Arquivo:linha | Padrão encontrado | Recomendação | Tarefa |
+|----|-----------|--------------|-------------------|--------------|--------|
+| S-02 | A05 — Config | `.env.example:8` | JWT_SECRET sem rotação documentada | Documentar política de rotação | T3 |
+
+### P2 — Médio (ação recomendada, compensação aceitável)
+
+| ID | Categoria | Arquivo:linha | Padrão encontrado | Recomendação | Tarefa |
+|----|-----------|--------------|-------------------|--------------|--------|
+| S-03 | A09 — Logging | `src/api/handler.ts:15` | Erro logado com stack trace completo em produção | Filtrar dados sensíveis em prod | T_new |
+
+---
+
+## Resultado por categoria
+
+| Categoria OWASP | Status | Achados |
+|-----------------|--------|---------|
+| A01 — Broken Access Control | ✅ Sem achados | — |
+| A02 — Cryptographic Failures | ⚠️ P1 | S-02 |
+| A03 — Injection | ✅ Sem achados | — |
+| A05 — Security Misconfiguration | ⚠️ P1 | S-02 |
+| A07 — Authentication Failures | ❌ P0 | S-01 |
+| A09 — Logging & Monitoring | ⚠️ P2 | S-03 |
+
+---
+
+## Sugestões de tarefas novas
+
+```
+T_new-S01: Implementar hash de senha com bcrypt (custo ≥ 12)
+  Verificar: login falha com senha errada; hash visível no DB.
+  Aceite vinculado: [A* de segurança se existir na SPEC]
+
+T_new-S03: Filtrar stack traces em logs de produção
+  Verificar: log em NODE_ENV=production não expõe stacktrace.
+  Aceite vinculado: —
+```
+
+---
+
+## Próximo passo
+
+- **P0 presente:** ação obrigatória antes de qualquer deploy — criar tarefas e adicionar ao PLAN via `/oxe-plan --replan`.
+- **Apenas P1/P2:** priorizar P1 na próxima onda; P2 pode ir para backlog v2.
+- **Sem achados:** registrar como "auditoria limpa em YYYY-MM-DD" e prosseguir.

package/oxe/templates/STATE.md

@@ -12,7 +12,7 @@
 ## Último compact (codebase + RESUME) (opcional)
 
 - **Data:** (**YYYY-MM-DD** — preenchido por **`/oxe-compact`**: refresh incremental dos mapas em `.oxe/codebase/` + `CODEBASE-DELTA.md` + `RESUME.md`)
-- **Notas:** (opcional; ex.: “só STRUCTURE e TESTING”)
+- **Notas:** (opcional; ex.: "só STRUCTURE e TESTING")
 
 ## Contexto do plano / quick (opcional)
 
@@ -37,9 +37,36 @@ _(O agente pode preencher após cada onda.)_
 - [ ] Onda N — implementação concluída
 - [ ] Onda N — **Verificar** executado ou agendado
 
+## Milestone ativo (opcional — `/oxe-milestone`)
+
+- **ID:** (ex.: M-01 — ou — se não houver milestone ativo)
+- **Nome:** (ex.: v1.0 — autenticação básica)
+- **Iniciado:** (YYYY-MM-DD)
+- **Progresso:** (N/M critérios verificados)
+
+## Último milestone encerrado (opcional)
+
+- **ID:** —
+- **Data de encerramento:** —
+- **Artefatos:** `.oxe/milestones/M-NN/`
+
+## Workstreams ativos (opcional — `/oxe-workstream`)
+
+- (nenhum ou lista de nomes: ex.: `feature-billing`, `bugfix-auth`)
+
+## Workstream ativo (contexto atual)
+
+- (nome do workstream ativo — ou — para pipeline principal)
+
+## Memory (sidecars de sessão) (opcional — `/oxe-memory`)
+
+Sidecars de memória persistente por agente/sessão. Armazenados em `.oxe/memory/`.
+
+- (nenhum ou lista: ex.: `architect-2025-01-15.md`, `researcher-auth-2025-01-14.md`)
+
 ## Decisões persistentes
 
-- (bullet: decisão → data)
+- (bullet: D-NN: decisão → data)
 
 ## Próximo passo sugerido
 

package/oxe/templates/config.template.json

@@ -1,10 +1,15 @@
 {
+  "_comment": "OXE config — copie para .oxe/config.json no seu projeto. Remova esta linha.",
+  "profile": "balanced",
   "discuss_before_plan": false,
+  "verification_depth": "standard",
   "after_verify_suggest_pr": true,
   "after_verify_draft_commit": true,
+  "after_verify_suggest_uat": false,
   "default_verify_command": "",
   "scan_max_age_days": 0,
   "compact_max_age_days": 0,
+  "scale_adaptive": true,
   "scan_focus_globs": [],
   "scan_ignore_globs": [],
   "spec_required_sections": [],

package/oxe/templates/plan-agents.template.json

@@ -1,5 +1,5 @@
 {
-  "oxePlanAgentsSchema": 2,
+  "oxePlanAgentsSchema": 3,
   "runId": "oxe-YYYY-MM-DD-substituir-por-id-opaco",
   "lifecycle": {
     "status": "pending_execute",
@@ -18,7 +18,8 @@
       "taskIds": ["T1"],
       "dependencies": [],
       "inputs": [".oxe/STATE.md", ".oxe/SPEC.md"],
-      "outputs": ["src/example.ts"]
+      "outputs": ["src/example.ts"],
+      "model_hint": "balanced"
     }
   ],
   "execution": {

package/oxe/templates/quick-agents.template.json

@@ -0,0 +1,24 @@
+{
+  "oxeQuickAgentsSchema": 1,
+  "quickId": "quick-YYYY-MM-DD-substituir-por-6hex",
+  "quickRef": ".oxe/QUICK.md",
+  "status": "active",
+  "since": "YYYY-MM-DDTHH:mm:ssZ",
+  "_comment": "Agentes derivados dos passos do QUICK.md. Plan-Driven Dynamic Agents (lean): criados para esta demanda, invalidados ao promover para spec/plan ou iniciar novo quick.",
+  "agents": [
+    {
+      "id": "agent-dominio-a",
+      "role": "Papel específico para ESTA demanda (não genérico)",
+      "persona": "executor",
+      "steps": [1, 2, 3],
+      "focus": "Uma frase sobre o foco deste agente nos steps atribuídos"
+    },
+    {
+      "id": "agent-dominio-b",
+      "role": "Papel específico para ESTA demanda (não genérico)",
+      "persona": "executor",
+      "steps": [4, 5],
+      "focus": "Uma frase sobre o foco deste agente nos steps atribuídos"
+    }
+  ]
+}

package/oxe/workflows/discuss.md

@@ -8,10 +8,22 @@ Usar quando: SPEC existe mas há ambiguidade, risco técnico, ou `discuss_before
 
 <context>
 - Ler `.oxe/SPEC.md`, `.oxe/STATE.md` e trechos relevantes de `.oxe/codebase/OVERVIEW.md` / `STACK.md`.
+- Se existir **`.oxe/OBSERVATIONS.md`** com entradas `pendente` de impacto `spec`, `plan` ou `all`, carregá-las como contexto adicional para as perguntas e decisões; marcá-las `incorporada → discuss (data)` após uso.
 - Se existir **`.oxe/NOTES.md`**, rever bullets em aberto: promover para perguntas/decisões em `DISCUSS.md` ou marcar como *descartado* / *adiado* com uma linha de justificativa.
 - Se `.oxe/config.json` existir e `discuss_before_plan` for `true`, tratar este passo como **recomendado** antes de `oxe:plan`.
 </context>
 
+<decision_ids>
+Toda decisão fechada em `DISCUSS.md` recebe um **ID estável** com prefixo `D-` e número sequencial: **D-01**, **D-02**, …
+
+Regras:
+1. O ID é atribuído **quando a decisão é registrada** (não quando a pergunta é feita).
+2. IDs não são reutilizados — se uma decisão for revertida, registrar a reversão com novo ID (`D-05: Revertendo D-02 — novo comportamento X`) e marcar D-02 como `*(revertida por D-05)*`.
+3. `PLAN.md` deve referenciar os IDs nas tarefas (campo **Decisão vinculada:** `D-01, D-03`).
+4. `VERIFY.md` deve cruzar os IDs na seção **Fidelidade de decisões**.
+5. O ID é o vínculo de rastreabilidade discuss → plan → verify.
+</decision_ids>
+
 <process>
 1. Se não existir `.oxe/SPEC.md`, pedir **spec** primeiro (ou **quick** se for trabalho trivial).
 2. Se existir **`.oxe/NOTES.md`**, rever bullets em aberto e decidir o que entra em **Perguntas** ou **Decisões** (ou marcar *descartado* / *adiado* com justificativa curta).
@@ -19,16 +31,47 @@ Usar quando: SPEC existe mas há ambiguidade, risco técnico, ou `discuss_before
 4. Criar ou atualizar **`.oxe/DISCUSS.md`** com estrutura fixa:
    - **Contexto** — 2–4 bullets do que já se sabe da SPEC.
    - **Perguntas** — numeradas; para cada uma: resposta (se o usuário já respondeu na mensagem) ou `_(pendente)_`.
-   - **Decisões** — bullets com decisão + data (só as já fechadas).
-   - **Implicações para o plano** — bullets (ex.: “migrations necessárias”, “feature flag”).
+   - **Decisões** — tabela com colunas **ID** / **Decisão** / **Data** / **Impacto no plano** (só as já fechadas). Atribuir IDs **D-01**, **D-02**, … em sequência.
+   - **Implicações para o plano** — bullets (ex.: "migrations necessárias", "feature flag").
 5. Se ainda houver perguntas **pendentes** críticas, listá-las no chat (máx. 7) e parar até resposta; depois atualizar DISCUSS.md.
-6. Atualizar **`.oxe/STATE.md`**: fase `discuss_complete`, próximo passo `oxe:plan`.
-7. Resumo no chat em ≤8 linhas.
+6. Atualizar **`.oxe/STATE.md`**: fase `discuss_complete`, próximo passo `oxe:plan`. Registrar os IDs de decisão na seção **Decisões persistentes** do STATE (ex.: `D-01: escolheu JWT — 2025-01-15`).
+7. Resumo no chat em ≤8 linhas, listando decisões com seus IDs.
 </process>
 
+<discuss_md_format>
+```markdown
+---
+oxe_doc: discuss
+status: (open | closed)
+updated: YYYY-MM-DD
+---
+
+# OXE — Discuss
+
+## Contexto
+- …
+
+## Perguntas
+
+1. **[pergunta]**
+   - Resposta: … / _(pendente)_
+
+## Decisões
+
+| ID   | Decisão                          | Data       | Impacto no plano                      |
+|------|----------------------------------|------------|---------------------------------------|
+| D-01 | (decisão clara e acionável)      | YYYY-MM-DD | (como afeta tarefas / arquivos)       |
+| D-02 | …                                | …          | …                                     |
+
+## Implicações para o plano
+- …
+```
+</discuss_md_format>
+
 <success_criteria>
 - [ ] `.oxe/DISCUSS.md` existe com perguntas e decisões alinhadas à SPEC.
+- [ ] Cada decisão fechada tem ID único **D-NN** na tabela de Decisões.
 - [ ] Se existir `.oxe/NOTES.md`, as entradas relevantes foram tratadas (promovidas, descartadas ou adiadas com nota).
 - [ ] Nenhuma ambiguidade crítica ficou sem registro (como pendente ou suposição explícita na SPEC).
-- [ ] `STATE.md` indica próximo passo **plan**.
+- [ ] `STATE.md` indica próximo passo **plan** e lista IDs de decisão em **Decisões persistentes**.
 </success_criteria>