@dewtech/dare-cli 2.15.0 → 2.17.0

package/templates/DARE-dag-example.yaml

@@ -0,0 +1,280 @@
+# Exemplo completo de dare-dag.yaml para o DARE CLI
+#
+# Este arquivo ilustra como estruturar um grafo de tasks (DAG) para o método DARE.
+# Copie e customize para seu projeto.
+#
+# Campos:
+#   - name: nome do projeto
+#   - version: semântica (versionamento do projeto)
+#   - created_at: timestamp
+#   - tasks: dicionário de tasks
+#
+# Cada task tem:
+#   - name (obrigatório): nome legível da tarefa
+#   - complexity (obrigatório): LOW | MEDIUM | HIGH
+#   - rank (opcional): ordem no DAG, calculado automaticamente se omitido
+#   - depends_on (opcional): lista de task IDs que DEVE completar antes
+#   - status (opcional): PENDING | RUNNING | DONE | FAILED
+#   - subtask_prompt (opcional): descrição detalhada para o agente executar
+#   - blueprint_section (opcional): link para seção em BLUEPRINT.md
+
+name: "API de Autenticação com JWT"
+version: "1.0"
+created_at: "2026-05-14T10:30:00Z"
+
+# Metadados opcionais
+metadata:
+  project_url: "https://github.com/seu-org/seu-projeto"
+  team: "Backend Team"
+  deadline: "2026-06-30"
+
+# ============================
+# TAREFAS (TASKS)
+# ============================
+
+tasks:
+  # ─────────────────────────────────────────────────────────────
+  # RANK 1 — Fundação (sem dependências)
+  # Estas tarefas podem rodar em paralelo — nenhuma depende uma da outra
+  # ─────────────────────────────────────────────────────────────
+
+  task-001:
+    name: "Setup Boilerplate"
+    complexity: "LOW"
+    # rank será calculado como 1 automaticamente (sem deps)
+    depends_on: []
+    status: "DONE"  # ✅ Já completada
+    subtask_prompt: |
+      Crie estrutura básica Node.js + NestJS:
+      - package.json com deps (typescript, express, dotenv)
+      - tsconfig.json
+      - .gitignore, .env.example
+      - scripts: dev, build, test, lint
+    blueprint_section: "1. Foundation"
+
+  task-002:
+    name: "Setup Database Schema"
+    complexity: "MEDIUM"
+    depends_on: []
+    status: "DONE"  # ✅ Completada
+    subtask_prompt: |
+      Defina schema no banco de dados:
+      - Tabela `users` (id, email, password_hash, created_at, updated_at)
+      - Tabela `refresh_tokens` (id, user_id, token_hash, expires_at, revoked_at)
+      - Índices em email e token
+      - Migrations com Prisma / TypeORM / Knex
+    blueprint_section: "1. Foundation"
+
+  # ─────────────────────────────────────────────────────────────
+  # RANK 2 — Core (depende de Rank 1)
+  # task-003 depende de task-001 (boilerplate)
+  # task-004 depende de task-002 (schema)
+  # Podem rodar em paralelo uma com a outra
+  # ─────────────────────────────────────────────────────────────
+
+  task-003:
+    name: "Implement JWT Auth Middleware"
+    complexity: "HIGH"
+    depends_on:
+      - "task-001"  # Precisa do boilerplate
+    status: "RUNNING"  # ⚙️ Em andamento
+    subtask_prompt: |
+      Crie middleware de autenticação:
+      - Gere JWT (HS256 ou RS256) com payload (user_id, iat, exp)
+      - Middleware que valida JWT em cada request
+      - Extraia user_id do token e injete em req.user
+      - Trate expiração, inválido, ausente
+      - Logs de tentativas falhadas
+    blueprint_section: "2. Authentication Core"
+
+  task-004:
+    name: "Implement Refresh Token Flow"
+    complexity: "MEDIUM"
+    depends_on:
+      - "task-001",  # Precisa do boilerplate
+      - "task-002"   # Precisa do schema
+    status: "PENDING"  # ⏳ Não iniciada
+    subtask_prompt: |
+      Implemente rotação de refresh tokens:
+      - Endpoint POST /auth/refresh que aceita refresh_token
+      - Valide refresh_token contra banco de dados
+      - Gere novo access_token + refresh_token
+      - Revogue token antigo no banco
+      - Implemente segurança: limite rate, valide origin
+    blueprint_section: "2. Authentication Core"
+
+  # ─────────────────────────────────────────────────────────────
+  # RANK 3 — Integração & Testes (depende de Rank 2)
+  # task-005 depende de task-003 (middleware)
+  # task-006 depende de task-003 e task-004 (ambos cores)
+  # ─────────────────────────────────────────────────────────────
+
+  task-005:
+    name: "Add Login & Logout Endpoints"
+    complexity: "LOW"
+    depends_on:
+      - "task-003"  # Precisa do middleware JWT
+    status: "PENDING"  # ⏳ Não iniciada
+    subtask_prompt: |
+      Crie endpoints de autenticação:
+      - POST /auth/login (email, password) → access_token, refresh_token
+      - POST /auth/logout (revoga refresh_token)
+      - Validação de entrada (email válido, password não vazio)
+      - Hash de password com bcrypt/argon2
+      - Testes unitários para sucesso e erro
+    blueprint_section: "3. API Endpoints"
+
+  task-006:
+    name: "Implement Tests & Security Hardening"
+    complexity: "HIGH"
+    depends_on:
+      - "task-003",  # Precisa do middleware
+      - "task-004"   # Precisa do refresh flow
+    status: "PENDING"  # ⏳ Não iniciada
+    subtask_prompt: |
+      Teste segurança e implemente proteções:
+      - Testes end-to-end: login → refresh → logout
+      - Testes de segurança: expiração, inválido, reuso de token
+      - CORS policy (origem permitida)
+      - Helmet.js para headers de segurança
+      - Rate limiting no /auth/refresh
+      - CSP (Content Security Policy)
+      - Logs de auditoria (tentativas falhadas)
+    blueprint_section: "4. Security & Testing"
+
+  # ─────────────────────────────────────────────────────────────
+  # RANK 4 — Documentação & Deploy (depende de tudo)
+  # task-007 depende de toda core (task-005, task-006)
+  # ─────────────────────────────────────────────────────────────
+
+  task-007:
+    name: "Document API & Prepare Deploy"
+    complexity: "LOW"
+    depends_on:
+      - "task-005",  # Precisa endpoints prontos
+      - "task-006"   # Precisa testes passando
+    status: "PENDING"  # ⏳ Não iniciada
+    subtask_prompt: |
+      Documente e prepare deployment:
+      - OpenAPI/Swagger documentation
+      - README com exemplos de uso (curl/Postman)
+      - Environment variables documentation
+      - Docker setup (Dockerfile, docker-compose)
+      - CI/CD pipeline (GitHub Actions / GitLab CI)
+      - Health check endpoint
+    blueprint_section: "5. Documentation & Deploy"
+
+# ============================
+# EXPLICAÇÃO DO GRAFO
+# ============================
+
+# Visualização (Rank = camada):
+#
+# Rank 1 (Fundação — paralelo)
+# ├── task-001 [LOW] ✅
+# └── task-002 [MEDIUM] ✅
+#
+# Rank 2 (Core — paralelo)
+# ├── task-003 [HIGH] ⚙️ (depende: 001)
+# └── task-004 [MEDIUM] ⏳ (depende: 001, 002)
+#
+# Rank 3 (Integração — paralelo)
+# ├── task-005 [LOW] ⏳ (depende: 003)
+# └── task-006 [HIGH] ⏳ (depende: 003, 004)
+#
+# Rank 4 (Documentação)
+# └── task-007 [LOW] ⏳ (depende: 005, 006)
+
+# ============================
+# COMO USAR ESTE ARQUIVO
+# ============================
+
+# 1. Copie para seu projeto:
+#    cp packages/cli/templates/DARE-dag-example.yaml DARE/dare-dag.yaml
+
+# 2. Customize:
+#    - Substitua nomes das tasks pelo seu projeto
+#    - Ajuste complexidade (LOW/MEDIUM/HIGH)
+#    - Defina dependências corretas
+#    - Atualize blueprint_section se tiver um BLUEPRINT.md
+
+# 3. Valide:
+#    dare dag validate
+
+# 4. Visualize:
+#    /dare-dag-viz
+#    → Abre em https://excalidraw.com com cores por complexidade
+
+# 5. Atualize status conforme avança:
+#    task-003:
+#      status: "DONE"  # Após completar
+
+# ============================
+# CONVENÇÕES
+# ============================
+
+# Task ID:
+#   Formato: task-NNN-slug
+#   - NNN = número sequencial (001, 002, ...)
+#   - slug = nome legível em kebab-case
+#   Exemplos: task-001-setup-boilerplate, task-003-jwt-middleware
+
+# Complexidade:
+#   - LOW: < 30 min, padrão bem definido
+#   - MEDIUM: 2-8 horas, múltiplas decisões
+#   - HIGH: 1+ dias, design crítico, risco alto
+
+# Status:
+#   - PENDING: não iniciada, aguardando
+#   - RUNNING: em execução neste momento
+#   - DONE: completada com sucesso
+#   - FAILED: falhou, requer ajuste
+
+# Depends_on:
+#   Lista outras tasks que devem completar ANTES desta
+#   Sem ciclos permitidos (A→B→A é inválido)
+
+# Rank (automático):
+#   Calculado como: 1 + max(rank das dependências)
+#   Rank 1 = nenhuma dependência
+#   Rank N = executa após Rank N-1
+
+# ============================
+# INTEGRAÇÃO COM DARE WORKFLOW
+# ============================
+
+# Phase 1: DESIGN (você define requisitos)
+#   → Cria DARE/DESIGN.md
+#
+# Phase 2: ARCHITECT (Claude Code/Cursor propõe arquitetura)
+#   → Cria DARE/BLUEPRINT.md
+#   → Você aprova / ajusta
+#
+# Phase 3: REVIEW (Claude Code propõe tasks)
+#   → Cria DARE/dare-dag.yaml (este arquivo!)
+#   → Você aprova structure
+#
+# Phase 4: EXECUTE (Claude Code implementa)
+#   → Roda dare execute --ralph-loop
+#   → Testes automáticos (build, test, lint)
+#   → Abre PR / commit automático
+
+# ============================
+# REFERÊNCIAS
+# ============================
+
+# DARE Methodology: https://github.com/dewtech-technologies/dare-method
+# Design Tokens (cores, fonts): docs/DESIGN-TOKENS-EXCALIDRAW.md
+# Visualization: /dare-dag-viz (gera dag-graph.excalidraw)
+# Excalidraw app: https://excalidraw.com
+
+# ============================
+# LICENÇA
+# ============================
+
+# Este arquivo e o método DARE são AGPL v3.
+# Você é livre para usar, modificar, compartilhar.
+# Contribuições voltam ao projeto.
+#
+# Créditos: Wanderson Leandro (Dewtech Technologies)
+# Inspirações: Ralph Loop (termo original), Excalidraw (ferramenta)

package/templates/UPDATE-MANIFEST.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "releases": {
+    "2.16.0": {
+      "releasedAt": "2026-05-10",
+      "summary": "Excalidraw DAG visualization",
+      "changelog": "Adiciona renderer Excalidraw para visualizar o DAG (tasks + dependências) em diagrama interativo.",
+      "changes": []
+    },
+    "2.17.0": {
+      "releasedAt": "2026-05-16",
+      "summary": "dare update + dare review + dare refine + Anti-Stub Contract",
+      "changelog": "Release grande, três frentes complementares que resolvem três problemas reais:\n\n## 1. `dare update` — sincronizar projeto com CLI\n\nDev atualiza o CLI globalmente (npm install -g @dewtech/dare-cli@latest) e roda `dare update` em cada projeto pra puxar templates / skills / commands novos — sem mexer em DESIGN, BLUEPRINT, TASKS, dare-dag.yaml. UPDATE-MANIFEST.json declarativo lista changes + migrations por release. Backup automático em `.dare/backup-<version>/`. Detecção de customizações por hash SHA-256 (keep / replace / force). Filtro por IDE configurado.\n\nFlags: `--dry-run`, `--yes`, `--force`, `--target <version>`.\n\n## 2. `dare review` + `dare refine` — Anti-stub gates\n\nProblema: tasks marcadas como DONE com código mockado, stubs, esqueletos de função, TODOs pendentes.\n\n`dare review <task-id>`:\n- Camada estática (regex): TODO/FIXME/XXX/HACK, throw new Error('not implemented'), unimplemented!(), todo!(), NotImplementedError, funções vazias, retorno-fantasma (return null como única statement), mocks fora de testes (jest.fn, vi.mock, sinon.stub, MagicMock), placeholders\n- Camada semântica (opt-in via `--from-agent <verdict.json>`): IDE agent valida critério-a-critério se implementação satisfaz spec\n- Skills `dare-review` (Claude Code), `review-task` (Cursor), `dare-review` (Antigravity) produzem o verdito semântico\n- Gate opt-in no Ralph Loop: `review.onComplete: true` no dare.config.json bloqueia `dare execute --complete` quando review falha\n\n`dare refine <task-id>`:\n- Heurística determinística de complexidade: # arquivos, # funções/endpoints, # testes, # deps, keywords pesadas (refactor/migrate/integrate)\n- Buckets LOW (0-5) / MED (6-12) / HIGH (13-20) / CRITICAL (21+); thresholds configuráveis em `refine.thresholds`\n- `--split` propõe quebra em sub-tasks agrupadas por diretório\n- Skills `dare-refine` (todas IDEs) produzem split semântico (por camada, por endpoint, por feature, refactor-then-feature, migration-then-code)\n\n## 3. Anti-Stub Contract nos prompts de geração\n\nBlueprint e Tasks agora forçam especificação executável: para cada endpoint, função pública, evento ou job — assinatura completa, request/response shape por status code, validações enumeradas, edge cases, side effects, exemplos concretos. TASK-SPEC-template ganha seção 'PADRÕES PROIBIDOS' explícita e Definition of Done anti-mock obrigatório.\n\n## 4. Mudanças de schema em `dare.config.json`\n\n- Campo `version` agora rastreia a release do DARE (antes era placeholder zombie `0.1.0`).\n- Novo objeto `review`: `{ onComplete: false, strict: false }` (opt-in pra projetos legados, on para novos).\n- Novo objeto `refine`: `{ thresholds: { low: 5, med: 12, high: 20 } }`.\n\nMigrações `unify-version-field` e `add-review-refine-defaults` cuidam de projetos pré-2.17 automaticamente.",
+      "changes": [
+        {
+          "type": "modified",
+          "path": "dare.config.json#version",
+          "description": "Campo `version` agora rastreia a release do DARE (antes era placeholder `0.1.0` zombie)",
+          "appliesTo": ["*"]
+        },
+        {
+          "type": "added",
+          "path": "dare.config.json#review",
+          "description": "Adiciona objeto `review` ({ onComplete, strict }) em dare.config.json — gate opt-in pré-DONE no Ralph Loop",
+          "appliesTo": ["*"]
+        },
+        {
+          "type": "added",
+          "path": "dare.config.json#refine",
+          "description": "Adiciona objeto `refine.thresholds` em dare.config.json para customizar buckets de complexidade",
+          "appliesTo": ["*"]
+        }
+      ],
+      "migrations": [
+        {
+          "id": "unify-version-field",
+          "description": "Migra `dareVersion` → `version` e substitui o placeholder legacy `0.1.0` por `2.16.0` quando necessário",
+          "optional": false
+        },
+        {
+          "id": "add-review-refine-defaults",
+          "description": "Adiciona `review: { onComplete: false, strict: false }` e `refine: { thresholds: ... }` em projetos pré-2.17 (opt-in — não ativa o gate automaticamente)",
+          "optional": false
+        }
+      ]
+    }
+  }
+}

package/templates/ide/antigravity/.agents/skills/dare-blueprint/SKILL.md

@@ -122,34 +122,90 @@ Crie um documento `DARE/BLUEPRINT.md` com a seguinte estrutura:
 
 ## Estrutura de Diretórios
 
+> Mantenha esta seção **stack-agnóstica**. Liste os agrupamentos lógicos
+> (domínio, infraestrutura, interfaces, testes, migrations) e use a
+> nomenclatura **idiomática da stack escolhida** no `dare init`. Os exemplos
+> abaixo cobrem as 5 stacks suportadas — use **apenas o bloco da stack do
+> projeto**, não os 5 juntos.
+
+<details>
+<summary>Exemplo — Node.js / NestJS</summary>
+
+```
+projeto/
+├── src/
+│   ├── auth/
+│   │   ├── auth.controller.ts
+│   │   ├── auth.service.ts
+│   │   ├── auth.module.ts
+│   │   └── dto/{register,login}.dto.ts
+│   ├── users/{users.entity.ts,users.service.ts}
+│   └── main.ts
+├── migrations/{001_users.ts,002_refresh_tokens.ts}
+└── test/auth.e2e-spec.ts
+```
+</details>
+
+<details>
+<summary>Exemplo — Rust / Axum</summary>
+
+```
+projeto/
+├── src/
+│   ├── domain/{user.rs,refresh_token.rs}
+│   ├── handlers/{register.rs,login.rs,refresh.rs,logout.rs}
+│   ├── middleware/jwt.rs
+│   └── main.rs
+├── migrations/{001_users.sql,002_refresh_tokens.sql}
+└── tests/auth_integration.rs
+```
+</details>
+
+<details>
+<summary>Exemplo — Python / FastAPI</summary>
+
 ```
 projeto/
 ├── app/
-│   ├── Models/
-│   │   ├── User.php
-│   │   └── RefreshToken.php
-│   ├── Http/
-│   │   ├── Controllers/
-│   │   │   └── AuthController.php
-│   │   ├── Requests/
-│   │   │   ├── RegisterRequest.php
-│   │   │   └── LoginRequest.php
-│   │   └── Resources/
-│   │       └── UserResource.php
-│   ├── Services/
-│   │   └── AuthService.php
-│   └── Exceptions/
-│       └── AuthException.php
-├── database/
-│   └── migrations/
-│       ├── create_users_table.php
-│       └── create_refresh_tokens_table.php
-├── routes/
-│   └── api.php
-└── tests/
-    └── Feature/
-        └── AuthTest.php
+│   ├── routers/auth.py
+│   ├── models/{user.py,refresh_token.py}
+│   ├── schemas/{register.py,login.py}
+│   ├── services/auth.py
+│   └── main.py
+├── alembic/versions/{001_users.py,002_refresh_tokens.py}
+└── tests/test_auth.py
 ```
+</details>
+
+<details>
+<summary>Exemplo — PHP / Laravel</summary>
+
+```
+projeto/
+├── app/Http/Controllers/AuthController.php
+├── app/Http/Requests/{RegisterRequest,LoginRequest}.php
+├── app/Models/{User,RefreshToken}.php
+├── app/Services/AuthService.php
+├── database/migrations/{create_users,create_refresh_tokens}_table.php
+├── routes/api.php
+└── tests/Feature/AuthTest.php
+```
+</details>
+
+<details>
+<summary>Exemplo — Go / Gin</summary>
+
+```
+projeto/
+├── cmd/server/main.go
+├── internal/
+│   ├── handlers/{register,login,refresh,logout}.go
+│   ├── models/{user,refresh_token}.go
+│   └── middleware/jwt.go
+├── migrations/{001_users.sql,002_refresh_tokens.sql}
+└── handlers_test.go
+```
+</details>
 
 ## Plano de Execução
 
@@ -175,26 +231,71 @@ projeto/
 
 ## Comandos de Setup
 
+> Liste **somente os comandos da stack do projeto** (definida em
+> `dare init` / `dare.config.json#backend`). Não inclua todos os blocos
+> abaixo — use o que casa com a stack escolhida.
+
+<details>
+<summary>Node.js / NestJS</summary>
+
 ```bash
-# Instalar dependências
-composer install
+npm install
+cp .env.example .env
+npm run migration:run
+npm test
+npm run start:dev
+```
+</details>
+
+<details>
+<summary>Rust / Axum</summary>
 
-# Criar arquivo .env
+```bash
+cargo build
 cp .env.example .env
-php artisan key:generate
+sqlx migrate run
+cargo test
+cargo run
+```
+</details>
 
-# Rodar migrations
-php artisan migrate
+<details>
+<summary>Python / FastAPI</summary>
 
-# Gerar JWT secret
-php artisan jwt:secret
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+alembic upgrade head
+pytest
+uvicorn app.main:app --reload
+```
+</details>
 
-# Rodar testes
-php artisan test
+<details>
+<summary>PHP / Laravel</summary>
 
-# Iniciar servidor
+```bash
+composer install
+cp .env.example .env
+php artisan key:generate
+php artisan migrate
+php artisan test
 php artisan serve
 ```
+</details>
+
+<details>
+<summary>Go / Gin</summary>
+
+```bash
+go mod download
+cp .env.example .env
+migrate -path ./migrations -database "$DATABASE_URL" up
+go test ./...
+go run ./cmd/server
+```
+</details>
 
 ## Próximas Etapas
 1. Revisar e aprovar este Blueprint
@@ -202,7 +303,50 @@ php artisan serve
 3. Continuar com o Método DARE
 ```
 
-### Passo 5: Pedir Aprovação
+### Passo 5: Aplicar ANTI-STUB CONTRACT (regra inegociável)
+
+> **Por que existe esta regra:** a skill `dare-tasks` que vem depois usa este Blueprint como **única fonte de verdade**. Se um endpoint, função ou regra ficar genérico aqui, o agente que implementar a task **será forçado a inventar** — e vai produzir mocks, stubs e esqueletos para "preencher o vazio". Detalhe agora.
+>
+> Tasks que produzem mock/stub/skeleton **falham** no `dare review` (v2.17+) e bloqueiam o `dare execute --complete`.
+
+Para **cada** endpoint, função pública, evento ou job declarado no Blueprint, especifique de forma **executável**:
+
+**Endpoints HTTP/RPC:**
+- Assinatura completa (método, path, headers obrigatórios, content-type)
+- Request schema (todos os campos com tipo, restrições, opcionalidade)
+- Response schema **por status code** (2xx, 4xx, 5xx — não só "200 OK")
+- Validações server-side (lista exaustiva: `email único`, `senha ≥ 8 chars + maiúscula + dígito`)
+- Edge cases enumerados (input vazio, duplicado, expirado, sem permissão)
+- Side effects (tabelas/filas/caches/emails tocados, em ordem)
+- Exemplo concreto (payload real, response real — não placeholder)
+
+**Funções de domínio / services:**
+- Assinatura tipada (`fn name(args: Types) -> ReturnType`)
+- Pré-condições e pós-condições verificáveis
+- Estados de erro com tipo de exceção/Result esperado
+- Comportamento em concorrência (idempotência, locking, retry)
+
+**Jobs / event handlers / workers:**
+- Trigger (evento/cron/fila — nome canônico)
+- Payload schema tipado
+- Retry policy (backoff, max attempts, DLQ)
+- Idempotência (chave + estratégia)
+
+**Modelos de dados:**
+- Cada campo com tipo, nullable, default, constraints (unique, fk, check), índices
+- Triggers ou hooks (soft-delete, audit, encryption-at-rest)
+
+**Critério "Blueprint detalhado o suficiente"** (auto-validação antes de salvar):
+
+- [ ] Para cada endpoint, um humano não-familiarizado consegue escrever request/response sem perguntar nada?
+- [ ] Para cada função pública, está claro **o que retorna** em todos os caminhos (sucesso + erros enumerados)?
+- [ ] Edge cases foram **enumerados** ou só listados como "tratar edge cases"?
+- [ ] Cada validação tem uma regra concreta (não só "validar email")?
+- [ ] Cada decisão arquitetural tem **justificativa** (não só "escolhemos X")?
+
+**Anti-padrão a evitar:** seções como _"implementar autenticação"_ ou _"validar dados"_ — isso vira stub. Especifique algoritmo, campos, regras.
+
+### Passo 6: Pedir Aprovação
 Após gerar o Blueprint, peça ao usuário:
 - Revisar a arquitetura
 - Aprovar endpoints e modelos

package/templates/ide/antigravity/.agents/skills/dare-refine/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: dare-refine
+description: Analisa complexidade de uma task DARE e, quando alta, quebra em sub-tasks menores. Use após gerar o DAG (para tasks HIGH/CRITICAL), quando o dev pedir refinamento manual, ou quando o escopo mudou e uma task ficou grande. Combina heurística determinística (CLI) com decisão semântica do agente.
+---
+
+# DARE Refine Skill
+
+Você é o refinador de tasks do método DARE. Seu papel é garantir que cada task caiba em uma conversa única do agente — sem ficar tão grande que o agente "invente" stubs/mocks pra completar.
+
+## Quando usar
+
+- Após `dare-tasks` gerar o DAG, para cada task com complexity HIGH no `dare-dag.yaml`
+- Quando o dev pede: "refine task-034"
+- Quando o BLUEPRINT mudou e uma task ficou grande demais
+
+## Camada determinística vs semântica
+
+O CLI `dare refine <id>` já mede sinais objetivos: # arquivos, # funções, # testes, # dependências, keywords pesadas. Esta skill faz a camada semântica — você lê o conteúdo da spec e decide se faz sentido quebrar.
+
+## Como executar
+
+### Passo 1: Rodar a heurística determinística
+
+```bash
+dare refine <task-id> --split --format json > .dare/refine-<task-id>.json
+```
+
+JSON traz:
+- `report.score`, `report.level`
+- `report.signals` — explica a pontuação
+- `report.recommendsSplit` — true se HIGH/CRITICAL
+- `proposal.subtasks` — quebra inicial coarse
+
+### Passo 2: Decidir se quebra
+
+**Quebrar quando:**
+- `recommendsSplit: true` (HIGH/CRITICAL)
+- Mais de 6 arquivos
+- Mistura responsabilidades (modelo + controller + teste + migration)
+- Inclui refactor + feature juntos
+- Keyword "pesada" + score MED+
+
+**Manter inteira quando:**
+- LOW ou MED baixo
+- Mesmo módulo
+- Cabe em uma conversa (15–60 min)
+
+### Passo 3: Eixos de split
+
+| Eixo | Quando |
+|---|---|
+| **Por camada** | Modelo / Controller / Service / Test separados |
+| **Por endpoint** | 4 endpoints → 4 sub-tasks |
+| **Por feature** | Auth = register + login → split por verbo |
+| **Refactor + feature** | "1. refactor" + "2. feature em cima" |
+| **Migration + código** | "1. migration" + "2. código novo" |
+
+Cada sub-task:
+- `subtask_prompt` auto-suficiente (Anti-Stub Contract!)
+- Spec própria em `DARE/EXECUTION/<sub-id>.md`
+- `depends_on` mínimo mas correto
+- Complexity honesta — se sub ainda for HIGH, quebrar de novo
+
+### Passo 4: Verdito
+
+`.dare/refine-verdict-<task-id>.json`:
+
+```json
+{
+  "manageable": false,
+  "reasons": ["Score 18 (HIGH) — 7 endpoints + migration", "Mistura refactor com features novas"],
+  "proposedSubtasks": [
+    {
+      "id": "task-034a",
+      "title": "Refactor UserService",
+      "files": ["src/services/UserService.ts", "tests/services/UserService.test.ts"],
+      "rationale": "Refactor isolado antes da feature",
+      "estimatedLevel": "MED"
+    }
+  ]
+}
+```
+
+Manuseável:
+
+```json
+{
+  "manageable": true,
+  "reasons": ["Score 7 (MED), 4 arquivos mesmo módulo"]
+}
+```
+
+### Passo 5: Aplicar o split
+
+1. Editar `DARE/dare-dag.yaml` substituindo a task pelas sub-tasks
+2. Criar specs em `DARE/EXECUTION/<sub-id>.md` (template + Anti-Stub Contract)
+3. Atualizar `DARE/TASKS.md` (visão humana)
+4. Regenerar Mermaid: `dare dag viz -o DARE/dag-graph.mmd`
+5. Marcar task original como SPLIT (preservar histórico)
+
+### Passo 6: Mensagem
+
+Manuseável:
+> ✅ Task bem-dimensionada (score X, level Y). Sem split.
+
+Quebrada:
+> 🪓 Task quebrada em N sub-tasks: [lista]. Revise com `dare validate` e `dare dag viz`.
+
+## Regras inegociáveis
+
+- Não quebrar tasks LOW
+- Não inventar dependências falsas
+- Cada sub-task testável independentemente
+- Anti-Stub Contract aplica em cada sub-task