@brunosps00/dev-workflow 1.5.0 → 1.7.0

package/scaffold/pt-br/commands/dw-open-design.md

@@ -0,0 +1,323 @@
+<system_instructions>
+Voce e o **runner headless do Open Design (`od`)** para gerar e iterar prototipos HTML em uma pasta de projeto,
+sem abrir Electron e sem depender do estado da GUI do usuario. Use o daemon do `nexu-io/open-design` em
+`--headless`, importe a pasta alvo uma vez, rode briefs single ou batch em serie, verifique o arquivo produzido,
+rode gate visual Playwright/Firefox e **PARE para o gate do dono** antes de qualquer commit.
+
+<critical>NUNCA use o estado da GUI do usuario. Sempre rode com `OD_DATA_DIR` isolado por projeto, por exemplo `.dw/.open-design/data/`.</critical>
+<critical>NUNCA commite prototipo reprovado. O gate e dual >=9: gate automatico + avaliacao visual propria >=9, depois gate do dono.</critical>
+<critical>O agente (`codex` ou `claude`) deve ser sempre explicito em `od run start --agent <agent>`. Se o usuario nao passar, resolva de config/estado do projeto; fallback `codex`.</critical>
+<critical>NUNCA despache o pedido cru do usuario para o `od`. O valor deste comando e refinar o prompt primeiro: ancore no codigo real, estruture o brief, qualifique estados/temas/a11y/deep-link, persista o brief revisavel e so entao anexe o apendice headless.</critical>
+
+## Inputs
+
+| Flag/argumento | Default | Descricao |
+|---|---:|---|
+| `--target <dir>` | `open-design/` | Pasta importada como projeto externo e onde os HTMLs serao escritos. |
+| `--brief <file>` | nenhum | Um brief markdown para uma run single. |
+| `--brief-glob <glob>` | nenhum | Batch em serie. Expanda para lista estavel e rode um prompt por vez. |
+| `--output <file>` | obrigatorio no brief/apendice | HTML esperado; verifique no filesystem depois da run. |
+| `--agent <codex|claude>` | estado/config -> `codex` | Agente repassado ao `od run start --agent`. |
+| `--platform <text>` | `Web responsivo desktop-first e mobile-safe` | Resposta pre-preenchida para o discovery da skill `web-prototype`. |
+| `--deep-link-id <id>` | nenhum | Valor usado no gate comportamental `?aberto=<id>` + Esc. |
+| `--refactor` | falso | Modo redesign/refactor de tela existente; captura prints atuais e ancora o brief no estado visivel + codigo real. |
+| `--url <url>` | nenhum | URL de app rodando para capturar prints atuais via Playwright Firefox. |
+| `--viewports <lista>` | `1440x900,375x812` | Viewports separados por virgula para `--refactor --url`; expanda conforme a dor (ex.: `1920x1080` para tabela larga). |
+| `--screenshot <path>` | repetivel | Print atual ja capturado quando nao houver `--url`; copie para `_refs/<slug>/`. |
+
+## 0. Refinar o brief
+
+Antes de qualquer pre-flight de daemon ou chamada ao `od`, transforme a intencao do usuario em um brief qualificado.
+Nao envie a frase crua do usuario para o runner.
+
+Contrato obrigatorio:
+
+| Etapa | Exigencia |
+|---|---|
+| Ancorar na realidade | Se a tela existe, leia o codigo real dela: colunas, enums, acoes, estados, permissoes, contracts e dominio. Leia tambem design system, prototipos irmaos e guias de design do projeto. E proibido inventar campo, status ou acao. |
+| Estruturar | Reescreva o pedido no esqueleto padrao abaixo, preenchendo paths reais e arquivo de saida exato. |
+| Qualificar | Cubra loading/skeleton, empty/vazio, erro/falha, light + dark, a11y, limites do design system local (ex.: <=6 cards/filtros), responsividade e deep-link. |
+| Persistir | Salve o brief refinado dentro do projeto, por exemplo `<target>/PROMPT-<slug>.md`. Ele e entregavel revisavel pelo dono, nao arquivo descartavel. |
+| Revisar se ja vier pronto | Se o usuario trouxer um brief ja qualificado, faca uma revisao rapida por checklist, ajuste apenas lacunas e persista a versao final. |
+
+Esqueleto padrao do brief refinado:
+
+```markdown
+# <titulo da tela/prototipo>
+
+Cole este brief no Open Design. Arquivo de saida exato: `<OUTPUT_FILE>`.
+
+## 1. Por que
+<dor real do usuario/produto; problema observavel que este prototipo precisa resolver>
+
+## 2. Decisao de interacao
+<padrao de navegacao, abertura, selecao, filtros, ordenacao, edicao e confirmacoes>
+
+## 3. Layout/lista
+Tabela/lista baseada apenas em colunas REAIS:
+
+| Coluna real | Origem/contract | Como aparece | Estado/limite |
+|---|---|---|---|
+| <nome> | <arquivo/API/schema> | <texto, badge, acao> | <truncate, vazio, erro> |
+
+## 4. Detalhe/acoes
+<drawer/modal/pagina de detalhe; acoes contextuais permitidas por estado/permissao real>
+
+## 5. Fidelidade de dominio
+Para o mock nao mentir: usar enums/status reais, dados de exemplo realistas no idioma do projeto e incluir estados raros/quebrados que existem no dominio.
+
+## 6. Direcao visual
+<tokens, componentes, densidade, referencias herdadas, prototipos irmaos e limites do design system>
+
+## Entregar
+- `<OUTPUT_FILE>`
+- `<OUTPUT_FILE>.artifact.json` se houver sidecar
+```
+
+So depois de persistir esse arquivo anexe o apendice headless em `.dw/.open-design/runs/` e despache a run.
+
+### 0R. Modo refactor/redesign
+
+Quando `--refactor` estiver presente, a fase 0 continua obrigatoria. Prints complementam a ancoragem no codigo; eles
+nao substituem leitura de contracts, enums, permissoes, estados, design system e prototipos irmaos.
+
+Capture ou copie os prints atuais para dentro da pasta importada, em `_refs/<slug>/`, antes de persistir o brief:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --url "<url>" \
+  --viewports "1440x900,375x812"
+```
+
+Sem URL de app rodando, aceite prints prontos repetindo `--screenshot`:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --screenshot "./antes-1440-light.png" \
+  --screenshot "./antes-375-dark.png"
+```
+
+Regras de captura:
+
+| Caso | Exigencia |
+|---|---|
+| Viewports | Default sensato: desktop `1440x900` + mobile `375x812`. O agente escolhe/expande conforme a dor: bug mobile inclui `375x812`; tabela larga inclui `1920x1080`; tablet/console inclui `768x1024`. |
+| Temas | Capture light e dark quando aplicavel. O helper usa `light,dark` por default e grava nomes como `_refs/<slug>/atual-1440-light.png` e `_refs/<slug>/atual-375-dark.png`. |
+| Caminho robusto | O agente do `od` le imagens do filesystem do projeto. Referencie caminhos relativos dentro do target; nao dependa de flag de imagem no `run start`. |
+| Higiene | `_refs/` e material de referencia nao devem virar prototipo. Se o projeto-alvo versiona prototipos finais, documente limpeza ou adicione `<target>/_refs/` ao `.gitignore` conforme a convencao local. |
+
+O brief refinado do modo refactor deve adicionar este bloco:
+
+```markdown
+## Referencias da tela atual
+Abra e ANALISE os prints antes de escrever:
+- `_refs/<slug>/atual-1440-light.png`
+- `_refs/<slug>/atual-375-dark.png`
+
+## O que esta errado hoje
+<dor apontando elementos visiveis nos prints: densidade, hierarquia, tabela, filtros, estados, contraste, mobile, etc.>
+
+## A ideia da mudanca
+<o que muda e por que; decisao de interacao/visual proposta pelo usuario ou pelo agente apos ler codigo e prints>
+
+## Preservar
+<fluxos, campos, permissoes, estados, copys, affordances e integracoes que nao podem mudar>
+```
+
+## Pre-flight
+
+| Checagem | Acao |
+|---|---|
+| Resolver `od` | `OD_CLI_DIR` vence. Senao use `~/.dw/vendor/open-design`. Se `apps/daemon/bin/od.mjs` nao existir, pare e mande rodar `dev-workflow install-deps`. |
+| Prerequisitos | O checkout do Open Design exige Node `~24` e pnpm `>=10.33`. Se faltarem, pare com instrucoes objetivas. |
+| Estado isolado | Crie `.dw/.open-design/`, `.dw/.open-design/data/`, `.dw/.open-design/runs/` e `.dw/.open-design/state.json`. |
+| Porta | Escolha porta livre em `127.0.0.1`; persista `daemonUrl` e `port` no state. |
+| Daemon vivo | Se `od daemon status --daemon-url <url> --json` retornar `ok: true`, reuse. Senao inicie novo daemon. |
+
+Comando base do daemon:
+
+```bash
+OD_DATA_DIR="$PWD/.dw/.open-design/data" \
+OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000 \
+node "$OD_DIR/apps/daemon/bin/od.mjs" daemon start \
+  --headless \
+  --host 127.0.0.1 \
+  --port "$PORT"
+```
+
+Ruido conhecido: `codex_core::shell_snapshot` pode logar `ERROR` de sintaxe. Isso e benigno; nao aborte se a run
+continua e o arquivo alvo e criado.
+
+## Import idempotente
+
+Use `project import-folder` na pasta alvo resolvida absoluta. Default: `<repo>/open-design/`.
+
+Persistir em `.dw/.open-design/state.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "targetDir": "/abs/repo/open-design",
+  "projectId": "<project.id>",
+  "conversationId": "<conversationId>",
+  "daemonUrl": "http://127.0.0.1:<port>",
+  "port": 17556,
+  "agent": "codex"
+}
+```
+
+Se `projectId` existe no state e `od project info <id> --daemon-url <url> --json` funciona para o mesmo
+`targetDir`, reuse. Caso contrario, reimporte:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" project import-folder "$TARGET_DIR" \
+  --daemon-url "$OD_URL" \
+  --name "$(basename "$TARGET_DIR")" \
+  --skill web-prototype \
+  --design-system default \
+  --json
+```
+
+Capture `project.id` e `conversationId`; nao dependa de estado global do app.
+
+## Apendice headless obrigatorio
+
+Anexe este bloco ao final de cada brief em um arquivo temporario dentro de `.dw/.open-design/runs/`.
+Preencha `<PLATFORM>`, `<OUTPUT_FILE>` e referencias irma se houver.
+
+```markdown
+---
+
+## Apendice headless para Open Design
+
+Plataforma-alvo: <PLATFORM>.
+
+Nao faca discovery e nao faca perguntas. Nao emita `<question-form>`. Siga este brief com as respostas acima e
+entregue arquivo primeiro.
+
+Arquivo de saida obrigatorio: `<OUTPUT_FILE>`.
+
+Contrato file-first:
+- Escreva o HTML diretamente no filesystem do projeto, exatamente em `<OUTPUT_FILE>`.
+- Nao altere arquivos existentes, exceto quando este prompt for explicitamente uma iteracao cirurgica sobre um arquivo alvo.
+- Se precisar criar sidecar, mantenha `<OUTPUT_FILE>.artifact.json` coerente.
+- Nao responda apenas com bloco `<artifact>` textual; run `succeeded` sem arquivo e falha.
+
+Para evitar timeout headless:
+- Escreva arquivos grandes em partes, com edicoes de aproximadamente 150 linhas por chamada.
+- Mantenha progresso visivel ate finalizar o HTML.
+
+Contexto de consistencia:
+- Leia prototipos irmaos em `prototipos/` ou na pasta indicada no brief antes de definir padroes visuais.
+- Preserve o sistema visual local quando houver referencia proxima.
+
+Deep-link obrigatorio:
+- Implemente `?aberto=<id>` para abrir o drawer/modal do item correto.
+- Ao fechar com Esc ou acao de fechar, limpe o parametro com `history.replaceState`.
+- O drawer/modal deve usar `role="dialog"` e atributos ARIA adequados.
+- Inclua estados skeleton/loading, empty/vazio e erro/falha.
+```
+
+## Run single
+
+Sempre passe `--agent` explicitamente:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file "$PROMPT_WITH_APPENDIX" \
+  --follow \
+  --json | tee ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+Depois da run, confira o arquivo. **Nao aceite apenas status `succeeded`:**
+
+```bash
+test -s "$TARGET_DIR/<OUTPUT_FILE>"
+```
+
+Registre no JSONL ou em sidecar de auditoria: brief, prompt com apendice, agente, daemonUrl, projectId,
+conversationId, output esperado, status final e resultado da verificacao do arquivo.
+
+## Batch
+
+Para `--brief-glob`, expanda os briefs, ordene por nome e rode em serie. Pare no primeiro caso em que:
+
+| Condicao | Resultado |
+|---|---|
+| run falha | `BLOCKED` com log JSONL |
+| run diz sucesso mas arquivo nao existe ou esta vazio | `FINDINGS` e follow-up cirurgico ou `BLOCKED` |
+| gate visual <9 | `FINDINGS`; iterar antes de continuar |
+
+Nao rode prompts em paralelo no mesmo projeto `od`; preserve auditabilidade e contexto.
+
+## Iteracao cirurgica
+
+Use follow-up run no mesmo `projectId`/`conversationId`, com prompt curto e arquivo alvo explicito:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file ".dw/.open-design/runs/<slug>.followup.md" \
+  --follow \
+  --json | tee -a ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+O follow-up deve dizer: arquivo unico, mudanca exata, nao tocar prototipos irmaos, manter deep-link e estados.
+
+## Gate visual obrigatorio
+
+Execute o gate automatico:
+
+```bash
+node .dw/scripts/open-design/gate-prototype.mjs \
+  --file "$TARGET_DIR/<OUTPUT_FILE>" \
+  --deep-link-id "<id-real>" \
+  --expected-text "<texto-do-item>" \
+  --out ".dw/.open-design/gate/<slug>"
+```
+
+O gate cobre:
+
+| Camada | Exigencia |
+|---|---|
+| Estrutural | `<title>`, `aberto`, `replaceState`, `role=dialog`/ARIA, skeleton/loading, empty/vazio, erro/falha. |
+| Screenshot | Firefox headless em light e dark, com `colorScheme` e `data-theme`. |
+| Comportamental | `?aberto=<id>` abre o item certo; Esc fecha e limpa o parametro. |
+| Avaliacao | Automatico PASS + sua nota visual >=9. Se abaixo de 9, faca follow-up cirurgico. |
+
+Depois de passar, **pare para o gate do dono**. Nao commite ate o dono aprovar.
+
+## Armadilhas validadas
+
+| Armadilha | Sintoma | Contorno obrigatorio |
+|---|---|---|
+| Discovery da `web-prototype` | Abre com `<question-form>` e encerra o turno; headless nao gera GenUI (`od ui list` vazio). | Anexar o apendice headless respondendo plataforma e proibindo perguntas/discovery. |
+| Timeout de inatividade | HTML grande fica silencioso e o run morre perto de 10min. | `OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000` no daemon + instruir escrita em partes de ~150 linhas. |
+| `codex_core::shell_snapshot` | Loga `ERROR` de sintaxe no stream. | Tratar como ruido se a run prossegue e o arquivo final existe. |
+| Estado da GUI | Config/agente/projetos vazam do app do usuario. | `OD_DATA_DIR` isolado sempre; `--agent`, `--skill` e `--design-system` explicitos. |
+
+## Structured Return
+
+**Status:** `PASS` | `FINDINGS` | `BLOCKED` | `NOT_APPLICABLE`  
+**Scope:** pasta alvo, briefs executados, agente usado, projectId/conversationId.  
+**Evidence:** logs JSONL, arquivo(s) HTML verificados, gate JSON, screenshots light/dark.  
+**Artifacts:** paths dos prototipos e sidecars.  
+**Decisions:** defaults/overrides aplicados (`agent`, `target`, plataforma, porta).  
+**Risks:** qualquer gate abaixo de 9, arquivo nao gerado apesar de run succeeded, dependencia ausente.  
+**Next Step:** gate do dono, follow-up cirurgico necessario, ou comando de resume exato.
+</system_instructions>

package/scaffold/pt-br/commands/dw-plan.md

@@ -55,7 +55,36 @@ Claude Code e OpenCode podem usar agentes nativos. Codex e Copilot usam `.agents
 
 <critical>Quando uma ferramenta estruturada de entrevista/input do usuario estiver disponivel, `/dw-plan` DEVE usa-la para as perguntas de clarificacao de PRD e TechSpec. Nao rebaixe para chat comum por conveniencia. Se nenhuma ferramenta desse tipo existir no runtime, faca as mesmas perguntas no chat e registre explicitamente: `Ferramenta de entrevista estruturada indisponivel; usando fallback em chat.`</critical>
 
-A ferramenta e obrigatoria no planejamento porque preserva escolhas explicitas do usuario e impede o agent de responder as proprias perguntas. Cada estagio mantem sua propria cota: PRD exige 7+ perguntas de produto; TechSpec exige 7+ perguntas tecnicas.
+A ferramenta e obrigatoria no planejamento porque preserva escolhas explicitas do usuario e impede o agent de responder as proprias perguntas.
+
+## Entrevista dirigida por cobertura (sem cotas fixas de perguntas)
+
+<critical>`/dw-plan` NÃO faz um número fixo de perguntas. Cada estágio monta uma **coverage matrix** sobre suas dimensões obrigatórias, descobre fatos do repo/rules/intel/artefatos de domínio, **credita evidência já resolvida num handoff de Grill alinhado**, e então pergunta — uma decisão por vez — SOMENTE as dimensões que continuam descobertas. Nunca re-pergunte uma decisão de produto que o usuário já resolveu no Grill.</critical>
+
+### Handoff alinhado (do grill do `/dw-brainstorm`)
+
+Antes do Stage 1, verifique se há um one-pager de ideia em `.dw/spec/ideas/<slug>.md` e o vocabulário canônico em `.dw/domain/**`.
+
+<critical>Valide o handoff e FALHE FECHADO. Credite um handoff alinhado — i.e. suprima as perguntas de produto que suas decisões cobrem — SOMENTE quando TODAS valem:
+- `schema_version: "1.1"`;
+- `status: aligned`;
+- `alignment.confirmed_by_user: true`;
+- toda branch de dependência resolvida (nenhum nó de decisão aberto);
+- contradições glossário/código fechadas;
+- nenhuma entrada **bloqueante** resta em Remaining Decisions.
+Se QUALQUER check falha — ou o arquivo está malformado, internamente inconsistente, `draft` ou `paused` — o one-pager é **input, não handoff confiável**: leia para contexto, mas trate todas as suas decisões como **descobertas** e pergunte normalmente. Nunca suprima uma pergunta de produto só pela força do `status: aligned`; `alignment.confirmed_by_user: true` e uma árvore resolvida, não-bloqueante e sem contradições também são exigidos.</critical>
+
+Quando (e só quando) o handoff é totalmente válido:
+- Carregue suas **Resolved Decisions**, **Evidence** e links de **Canonical Vocabulary**.
+- Marque toda dimensão de PRD que essas decisões cobrem como **já coberta** (cite o one-pager como evidência) — NÃO re-pergunte.
+- Só dimensões descobertas viram perguntas, uma por vez.
+
+### Coverage matrices
+
+- **Dimensões do PRD:** objetivos, usuários-alvo, limites de escopo, métricas de sucesso, estratégia de rollout, pontos de integração, edge cases.
+- **Dimensões do TechSpec:** domain placement, data flow, dependências, core interfaces, estratégia de testes, reuse-vs-build, integração multi-projeto (quando aplicável).
+
+Para cada estágio: monte a matriz, marque cada dimensão `coberta` (fato descoberto ou evidência alinhada creditada) ou `descoberta`, e pergunte só as `descobertas` — uma decisão por turn, cada uma com resposta recomendada. **Decisões técnicas que um Grill de produto não cobriu ainda podem ser perguntadas durante o TechSpec** — Grill alinha vocabulário e decisões de produto, não o design técnico completo.
 
 ## Constitution Gate
 
@@ -78,11 +107,11 @@ Roda em modo padrão OU `plan prd`.
 
 ### Pré-requisitos
 - Ideia ou tópico do usuário.
-- (Opcional) one-pager de brainstorm em `.dw/spec/ideas/<slug>.md` via `/dw-brainstorm --onepager`.
+- (Opcional) um one-pager de ideia do `/dw-brainstorm` em `.dw/spec/ideas/<slug>.md`. Se estiver `status: aligned` (schema `1.1`, de uma sessão de Grill), consuma como handoff — suas Resolved Decisions são creditadas, não re-perguntadas (ver Entrevista dirigida por cobertura).
 
 ### Comportamento obrigatório
 
-1. **Perguntas de clarificação (MÍNIMO 7).** Antes de escrever qualquer coisa, use a ferramenta de entrevista estruturada quando disponivel para fazer 7+ perguntas cobrindo: objetivos, usuários-alvo, limites de escopo, métricas de sucesso, estratégia de rollout, pontos de integração, edge cases. Se a ferramenta estiver indisponivel, use fallback em chat e registre o fallback.
+1. **Coverage matrix sobre as dimensões do PRD** (objetivos, usuários-alvo, limites de escopo, métricas de sucesso, estratégia de rollout, pontos de integração, edge cases). Monte a matriz, credite evidência de handoff alinhado e fatos descobertos do repo, e pergunte SOMENTE as dimensões descobertas — uma decisão por vez, cada uma com resposta recomendada — usando a ferramenta de entrevista estruturada quando disponível (registre o fallback em chat caso contrário). Sem contagem fixa de perguntas; nunca re-pergunte uma decisão resolvida num one-pager alinhado.
 2. **Web search MÍNIMO 3 queries** para padrões de mercado, contexto regulatório, abordagens de competidores quando relevante.
 3. **Constitution alignment.** Cada requisito funcional (FR-N.M) inclui linha `Constitution Alignment: respects P-NNN, P-MMM` OU `no applicable principle: <motivo>`.
 4. **Awareness multi-projeto.** Se feature cruza projetos do workspace, consulte `.dw/rules/integrations.md` e documente escopo na seção "Projetos Impactados".
@@ -106,7 +135,7 @@ Roda em modo padrão (após aprovação do PRD) OU `plan techspec` OU `plan --fr
 ### Comportamento obrigatório
 
 1. **Hard gate: open questions do PRD.** Se `.dw/spec/prd-<feature>/prd.md` tem seção "Open Questions" com itens não resolvidos, PARE e peça pra usuário resolver primeiro.
-2. **Perguntas de clarificação (MÍNIMO 7).** Use a ferramenta de entrevista estruturada quando disponivel para fazer perguntas tecnicas cobrindo: domain placement, data flow, dependências, core interfaces, estratégia de testes, reuse-vs-build, integração multi-projeto se aplicável. Se a ferramenta estiver indisponivel, use fallback em chat e registre o fallback.
+2. **Coverage matrix sobre as dimensões do TechSpec** (domain placement, data flow, dependências, core interfaces, estratégia de testes, reuse-vs-build, integração multi-projeto quando aplicável). Credite evidência de handoff alinhado e fatos descobertos, e pergunte SOMENTE as dimensões descobertas — uma decisão por vez — usando a ferramenta de entrevista estruturada quando disponível (registre o fallback em chat caso contrário). Decisões técnicas não cobertas por um Grill de produto ainda podem ser perguntadas aqui. Sem contagem fixa de perguntas.
 3. **Web search MÍNIMO 3 queries** + Context7 MCP para framework/library specifics.
 4. **Source grounding (`dw-source-grounding`).** Toda decisão de framework/library carrega `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`.
 5. **Constitution gate.** Cada decisão arquitetural lista `Respects: P-NNN` ou `Deviates: P-NNN — justification: <slug ADR ou racional>`. Desvios de princípios `severity: high/critical` sem ADR → PARE.
@@ -187,7 +216,7 @@ Após plan completo, o diretório do PRD contém:
 
 ## Diretrizes finais
 
-- Cada estágio tem sua própria cota de perguntas de clarificação — não recicle. Estágios diferentes precisam de framing diferente. Use a ferramenta de entrevista estruturada sempre que disponivel.
+- Cada estágio roda uma coverage matrix sobre suas próprias dimensões — sem cota fixa de perguntas. Credite evidência de handoff alinhado e fatos descobertos; pergunte só decisões descobertas, uma por vez. Estágios diferentes precisam de framing diferente. Use a ferramenta de entrevista estruturada sempre que disponivel.
 - Web search é obrigatório; Context7 MCP para libraries. Sem pular pra "acho que sei a versão mais recente."
 - Constitution gate roda na entrada de cada estágio; defaults são auto-instalados quando ausente (nunca bloqueia).
 - Os três estágios produzem Markdown commitado — esses são os artefatos canônicos de planejamento. Eles evoluem com a feature.

package/scaffold/pt-br/templates/adr-template.md

@@ -3,8 +3,9 @@ id: NNN
 status: Proposed
 title: [Título imperativo curto da decisão]
 date: YYYY-MM-DD
-prd: [slug do PRD, ex: prd-user-auth]
-schema_version: "1.0"
+scope: repo | prd
+prd: [slug do PRD para scope=prd, ex: prd-user-auth; "n/a" para scope=repo]
+schema_version: "1.1"
 supersedes: null
 superseded_by: null
 ---
@@ -46,8 +47,11 @@ Proposed | Accepted | Deprecated | Superseded by ADR-XXX
 
 ## Related
 
-- PRD: `.dw/spec/[prd-slug]/prd.md`
-- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (se aplicável)
+<!-- scope=prd: linke o PRD/TechSpec dono. scope=repo: sem PRD dono — omita as linhas de PRD/TechSpec
+     (ou escreva "n/a") e linke `.dw/constitution.md` / `.dw/rules/` só quando genuinamente aplicáveis. -->
+
+- PRD: `.dw/spec/[prd-slug]/prd.md` (só scope=prd; "n/a" para scope=repo)
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (se aplicável; só scope=prd)
 - Tasks afetadas: [lista de tasks, se aplicável]
 - ADRs relacionadas: [lista, se aplicável]
 

package/scaffold/pt-br/templates/idea-onepager.md

@@ -1,11 +1,19 @@
 ---
 type: idea-onepager
-schema_version: "1.0"
-status: draft
+schema_version: "1.1"
+status: draft | paused | aligned
 date: YYYY-MM-DD
 classification: improves | consolidates | new
+alignment:
+  confirmed_by_user: false   # true SOMENTE quando o usuário confirma explicitamente o shared understanding
+  confirmed_on: null         # data ISO dessa confirmação
 ---
 
+> **Schema 1.1.** O bloco `## Grill Alignment` abaixo é preenchido por uma sessão de grill do `/dw-brainstorm`. Sem
+> Grill, deixe esse bloco vazio e mantenha `status: draft`. `status: aligned` é permitido SOMENTE quando cada branch
+> de dependência está resolvida, contradições glossário/código estão fechadas, nenhuma decisão bloqueante resta, e o
+> usuário confirmou explicitamente o shared understanding — senão use `draft` ou `paused`.
+
 # Ideia: [Título curto e imperativo]
 
 ## Problem Statement
@@ -81,6 +89,40 @@ Idealmente 2-4 stories. Se são mais de 5, provavelmente não é MVP.]
 - [Pergunta 1 que afeta escopo]
 - [Pergunta 2 que afeta prioridade]
 
+## Grill Alignment
+
+_(schema 1.1 — preenchido por uma sessão de grill do `/dw-brainstorm`; consumido pelo `/dw-plan`, que NÃO re-pergunta decisões resolvidas. Deixe vazio para um one-pager sem grill.)_
+
+### Resolved Decisions
+
+| Decisão | Recomendado | Escolhido | Alternativa rejeitada | Evidência |
+|---------|-------------|-----------|-----------------------|-----------|
+| [a decisão] | [o que o Grill recomendou] | [o que o usuário escolheu] | [a opção rejeitada + seu trade-off] | [fonte no one-pager/repo] |
+
+### Evidence
+
+[Fatos descobertos durante o Grill no repo/rules/intel/docs — cada um com sua fonte (`path:line`, doc, ou query de intel) — usados em vez de perguntar ao usuário.]
+
+- **[fato]** — fonte: `[path:line ou doc]`
+
+### Canonical Vocabulary
+
+[Links para `.dw/domain/**` dos termos de que esta ideia depende. Não repita definições aqui — aponte para o glossário.]
+
+- **[Termo]** → `.dw/domain/glossary.md#termo` (ou `.dw/domain/contexts/<slug>.md#termo` num projeto multi-contexto)
+
+### Remaining Decisions
+
+[Decisões não-bloqueantes ainda abertas após o alinhamento, com seu dono. Uma decisão bloqueante significa que o one-pager NÃO está `aligned`.]
+
+- **[decisão aberta]** — dono: [quem] — bloqueante? [não]
+
+### Alignment State
+
+- **State:** `draft` | `paused` | `aligned`
+- **Shared understanding confirmado pelo usuário:** [sim/não — `aligned` exige um sim explícito]
+- **Por que não alinhado (se draft/paused):** [o nó bloqueante ou contradição não fechada que parou o alinhamento]
+
 ## Next Step
 
 Escolha UM:

package/scaffold/scripts/open-design/capture-current.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+function parseArgs(argv) {
+  const result = { screenshot: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (inlineValue !== undefined) {
+      if (key === "screenshot") result.screenshot.push(inlineValue);
+      else result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      if (key === "screenshot") {
+        throw new Error("Missing value for --screenshot <path>.");
+      }
+      result[key] = true;
+      continue;
+    }
+    if (key === "screenshot") result.screenshot.push(next);
+    else result[key] = next;
+    index += 1;
+  }
+  return result;
+}
+
+async function importFirefox() {
+  try {
+    return (await import("@playwright/test")).firefox;
+  } catch {
+    try {
+      return (await import("playwright")).firefox;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function slugify(value) {
+  return (
+    String(value)
+      .toLowerCase()
+      .replace(/^https?:\/\//, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 70) || "screen"
+  );
+}
+
+function parseViewports(value) {
+  return String(value || "1440x900,375x812")
+    .split(",")
+    .map((entry) => {
+      const match = entry.trim().match(/^(\d{2,5})x(\d{2,5})$/);
+      if (!match) return null;
+      return { width: Number(match[1]), height: Number(match[2]) };
+    })
+    .filter(Boolean);
+}
+
+function parseThemes(value) {
+  return String(value || "light,dark")
+    .split(",")
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry === "light" || entry === "dark");
+}
+
+function inferProvidedName(source, index) {
+  const base = path.basename(source, path.extname(source)).toLowerCase();
+  const width = base.match(/(?:^|[^0-9])(\d{3,5})(?:x\d{3,5})?(?:[^0-9]|$)/)?.[1];
+  const theme = base.includes("dark") ? "dark" : base.includes("light") ? "light" : "";
+  if (width && theme) return `atual-${width}-${theme}.png`;
+  if (width) return `atual-${width}-${String(index + 1).padStart(2, "0")}.png`;
+  return `atual-ref-${String(index + 1).padStart(2, "0")}.png`;
+}
+
+async function captureFromUrl(args, outDir) {
+  if (!args.url) return [];
+  const firefox = await importFirefox();
+  if (!firefox) {
+    throw new Error("Playwright is not installed. Run: npm i -D @playwright/test && npx playwright install firefox");
+  }
+
+  const viewports = parseViewports(args.viewports);
+  if (viewports.length === 0) {
+    throw new Error("No valid --viewports entries. Use comma-separated WIDTHxHEIGHT values, for example 1440x900,375x812.");
+  }
+  const themes = parseThemes(args.themes);
+  if (themes.length === 0) {
+    throw new Error("No valid --themes entries. Use light,dark or one of them.");
+  }
+
+  const browser = await firefox.launch({ headless: true });
+  const shots = [];
+  try {
+    for (const viewport of viewports) {
+      for (const theme of themes) {
+        const context = await browser.newContext({
+          colorScheme: theme,
+          viewport,
+        });
+        const page = await context.newPage();
+        await page.goto(String(args.url), { waitUntil: "networkidle" }).catch(() => page.goto(String(args.url)));
+        await page.evaluate((value) => {
+          document.documentElement.setAttribute("data-theme", value);
+        }, theme);
+        await page.waitForTimeout(300);
+        const target = path.join(outDir, `atual-${viewport.width}-${theme}.png`);
+        await page.screenshot({ path: target, fullPage: true });
+        shots.push({ source: String(args.url), viewport, theme, path: target });
+        await context.close();
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return shots;
+}
+
+function copyProvidedScreenshots(args, outDir) {
+  return args.screenshot.map((source, index) => {
+    const resolved = path.resolve(String(source));
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Screenshot not found: ${resolved}`);
+    }
+    const target = path.join(outDir, inferProvidedName(resolved, index));
+    fs.copyFileSync(resolved, target);
+    return { source: resolved, path: target };
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.url && args.screenshot.length === 0) {
+    throw new Error("Pass --url <app-url> or one or more --screenshot <path> values.");
+  }
+
+  const targetDir = path.resolve(String(args.target || "open-design"));
+  const slug = slugify(args.slug || args.url || "screen");
+  const outDir = path.resolve(String(args.out || path.join(targetDir, "_refs", slug)));
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const copied = copyProvidedScreenshots(args, outDir);
+  const captured = await captureFromUrl(args, outDir);
+  const shots = [...copied, ...captured];
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        targetDir,
+        refsDir: outDir,
+        relativeRefs: shots.map((shot) => path.relative(targetDir, shot.path).split(path.sep).join("/")),
+        shots,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`capture-current: ${error.message}\n`);
+  process.exit(1);
+});