@brunosps00/dev-workflow 2.0.0 → 2.1.0

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

@@ -4,51 +4,51 @@ last_paused: ""
 last_resumed: ""
 ---
 
-# Estado da Sessao
+# Estado da Sessão
 
-Memoria de trabalho entre sessoes. Indice leve do que esta em andamento, do que foi decidido, do que ficou parado. Atualizado por `/dw-pause` (consolida) e lido por `/dw-resume` (orienta).
+Memória de trabalho entre sessões. Índice leve do que está em andamento, do que foi decidido, do que ficou parado. Atualizado por `/dw-pause` (consolida) e lido por `/dw-resume` (orienta).
 
-Diferente do `MEMORY.md` por-PRD (memoria de workflow para uma feature) ou dos ADRs (decisoes arquiteturais duraveis), este arquivo vive no nivel do projeto e sobrevive entre PRDs, branches e sessoes. Edite livremente entre pausas.
+Diferente do `MEMORY.md` por-PRD (memória de workflow para uma feature) ou dos ADRs (decisões arquiteturais duráveis), este arquivo vive no nível do projeto e sobrevive entre PRDs, branches e sessões. Edite livremente entre pausas.
 
 ## Open Loops (Pontas Soltas)
 
-O que esta em andamento — trabalho comecado mas nao terminado. Cada entrada: label curto + path/alvo + proxima acao concreta.
+O que está em andamento — trabalho começado mas não terminado. Cada entrada: label curto + path/alvo + próxima ação concreta.
 
 - _nenhum_
 
-## Decisoes
+## Decisões
 
-Decisoes transversais que ainda nao viraram ADR (porque nao justificam um, ou porque a formalizacao foi adiada). Formato: `YYYY-MM-DD — decisao — contexto (1 linha)`.
+Decisões transversais que ainda não viraram ADR (porque não justificam um, ou porque a formalização foi adiada). Formato: `YYYY-MM-DD — decisao — contexto (1 linha)`.
 
 - _nenhuma_
 
 ## Bloqueios
 
-O que esta impedindo o avanco. Externo (esperando alguem), interno (lacuna de conhecimento) ou tecnico (tooling quebrado). Cada entrada: label curto + o que esta bloqueado + dono / condicao de desbloqueio.
+O que está impedindo o avanço. Externo (esperando alguém), interno (lacuna de conhecimento) ou técnico (tooling quebrado). Cada entrada: label curto + o que está bloqueado + dono / condição de desbloqueio.
 
 - _nenhum_
 
 ## Todos
 
-Pequenos follow-ups que nao justificam um PRD ou task. Uma linha cada. Limpe conforme forem feitos ou migrados para um PRD.
+Pequenos follow-ups que não justificam um PRD ou task. Uma linha cada. Limpe conforme forem feitos ou migrados para um PRD.
 
 - _nenhum_
 
 ## Ideias Adiadas
 
-Ideias consideradas mas parqueadas. Capture para nao perder; revisite quando o escopo mudar. Cada entrada: ideia + motivo do park + trigger de revisita (se conhecido).
+Ideias consideradas mas parqueadas. Capture para não perder; revisite quando o escopo mudar. Cada entrada: ideia + motivo do park + trigger de revisita (se conhecido).
 
 - _nenhuma_
 
-## Licoes
+## Lições
 
-Pequenas licoes aprendidas no trabalho recente — padroes que funcionaram, pegadinhas, "da proxima vez eu...". Nao sao arquiteturais (essas vao para ADRs); sao operacionais.
+Pequenas lições aprendidas no trabalho recente — padrões que funcionaram, pegadinhas, "da próxima vez eu...". Não são arquiteturais (essas vão para ADRs); são operacionais.
 
 - _nenhuma_
 
-## Preferencias
+## Preferências
 
-Convencoes acordadas durante o trabalho que afetam como o agent deve se comportar dali em diante. Exemplos: "sempre rodar `pnpm typecheck` antes do commit", "preferir named exports a default exports em utils".
+Convenções acordadas durante o trabalho que afetam como o agent deve se comportar dali em diante. Exemplos: "sempre rodar `pnpm typecheck` antes do commit", "preferir named exports a default exports em utils".
 
 - _nenhuma_
 

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

@@ -13,6 +13,7 @@ status: pending
 [Breve descrição da tarefa]
 
 **Requisitos Funcionais cobertos**: RF-X.Y, RF-X.Z (máximo 2 por task)
+Depends on: none
 
 <requirements>
 [Lista de requisitos obrigatórios]

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

@@ -19,19 +19,20 @@ feat/prd-[nome-funcionalidade]
 
 ## Tarefas
 
-| Task | Descrição | RFs | Status | Commit |
-|------|-----------|-----|--------|--------|
-| 1.0 | [Título] | RF-1.1, RF-1.2 | Pendente | — |
-| 2.0 | [Título] | RF-2.1 | Pendente | — |
-| 3.0 | [Título] | RF-3.1, RF-3.2 | Pendente | — |
+| Task | Descrição | Depends on | RFs | Status | Commit |
+|------|-----------|------------|-----|--------|--------|
+| 1.0 | [Título] | none | RF-1.1, RF-1.2 | Pendente | — |
+| 2.0 | [Título] | 1.0 | RF-2.1 | Pendente | — |
+| 3.0 | [Título] | 1.0, 2.0 | RF-3.1, RF-3.2 | Pendente | — |
 
 `Commit` guarda o SHA curto escrito de volta pelo `/dw-run` quando a task fecha (passo 6). É o que torna o diff da task localizável depois — deixe `—` até a task commitar.
+`Depends on` é o grafo de dependência consumido pelo `/dw-run`; escreva `none` quando uma task não tiver dependência.
 
 ## Progresso
 
-- [ ] 1.0 Título da Tarefa Principal
-- [ ] 2.0 Título da Tarefa Principal
-- [ ] 3.0 Título da Tarefa Principal
+- [ ] 1.0 Título da Tarefa Principal        Depends on: none
+- [ ] 2.0 Título da Tarefa Principal        Depends on: 1.0
+- [ ] 3.0 Título da Tarefa Principal        Depends on: 1.0, 2.0
 
 ## Workflow
 

package/scaffold/pt-br/templates/triage-needs-info-template.md

@@ -0,0 +1,23 @@
+# Needs Info: <título>
+
+## Perguntas Bloqueantes
+
+- [ ] <pergunta 1>
+- [ ] <pergunta 2>
+- [ ] <pergunta 3>
+
+## Por Que Isto Bloqueia a Triagem
+
+<Explique por que a informação ausente impede confiança na categoria/estado ou na verificação.>
+
+## Resposta do Autor
+
+<Cole ou resuma a resposta do autor. Quando o autor responder, mova o estado de triagem de `needs-info` para `needs-triage` e rode novamente a etapa de recomendação.>
+
+## Evidência Solicitada
+
+- Passos de reprodução:
+- Comportamento esperado vs atual:
+- Ambiente ou massa de teste:
+- PR diff ou branch/ref:
+- Screenshots/logs/traces:

package/scaffold/pt-br/templates/triage-out-of-scope-template.md

@@ -0,0 +1,36 @@
+---
+type: out-of-scope
+schema_version: "1.0"
+concept: "<concept-slug>"
+created_at: "YYYY-MM-DD"
+updated_at: "YYYY-MM-DD"
+---
+
+# Fora de Escopo: <Nome do Conceito>
+
+## Decisão
+
+Rejeitado em YYYY-MM-DD.
+
+## Motivo
+
+<Registre o motivo durável. Não escreva apenas "wontfix"; explique a fronteira de produto, técnica, operacional ou de política.>
+
+## Aplica-se A
+
+- <Formulação de domínio dos pedidos que esta decisão cobre>
+- <Redações alternativas conhecidas que mapeiam para o mesmo conceito>
+
+## Evidência
+
+- Registro de triagem: `.dw/triage/NNN-<slug>.md`
+- Busca no codebase:
+- Decisões anteriores:
+
+## Condições de Reabertura
+
+<O que precisaria mudar para este conceito ser reconsiderado?>
+
+## Histórico
+
+- YYYY-MM-DD — rejected — <actor> — <reason>

package/scaffold/pt-br/templates/triage-record-template.md

@@ -0,0 +1,88 @@
+---
+type: triage-record
+schema_version: "1.0"
+id: "NNN-<slug>"
+category: "bug | enhancement"
+state: "needs-triage | needs-info | ready-for-work | needs-human | wontfix"
+created_at: "YYYY-MM-DD"
+updated_at: "YYYY-MM-DD"
+---
+
+# Triagem: <título>
+
+## Fonte
+
+| Campo | Valor |
+|-------|-------|
+| Tipo de Fonte | paste / file / github-issue / github-pr / other |
+| Referência da Fonte | <caminho, URL, número de issue, número de PR, ou marcador de sessão colada> |
+| Autor | <nome ou desconhecido> |
+| Reportado em | <data ou desconhecida> |
+| Recuperado por | local / gh / pasted / owner-provided |
+
+## Resumo de Intake
+
+<Resumo curto do pedido em linguagem de domínio.>
+
+## Classificação
+
+| Campo | Valor |
+|-------|-------|
+| Categoria | bug / enhancement |
+| Estado | needs-triage / needs-info / ready-for-work / needs-human / wontfix |
+| Conceito de Domínio | <slug do conceito e nome humano> |
+| Motivo do Desfecho | <por que este estado foi escolhido> |
+
+## Checks do Codebase
+
+### Busca de Redundância
+
+| Área Pesquisada | Query / Conceito | Resultado |
+|-----------------|------------------|-----------|
+| `.dw/domain/**` | <concept> | <match / no match / missing> |
+| `.dw/spec/**` | <concept> | <match / no match / missing> |
+| `.dw/bugfixes/**` | <concept> | <match / no match / missing> |
+| `.dw/rules/**` | <concept> | <match / no match / missing> |
+| Código / testes / docs | <concept> | <match / no match> |
+
+### Busca de Rejeição Anterior
+
+| Registro | Similaridade | Decisão |
+|----------|--------------|---------|
+| `.dw/out-of-scope/<concept>.md` | <por que é similar> | aplica / não aplica / reaberta |
+
+## Verificação
+
+| Campo | Valor |
+|-------|-------|
+| Status da Verificação | confirmed / failed-to-reproduce / insufficient-detail |
+| Método de Verificação | passos de reprodução / revisão do diff do PR / testes relevantes / check de inventário de produto |
+| Comandos Rodados | <comandos ou n/a> |
+| Arquivos Inspecionados | <caminhos> |
+| Evidência | <o que foi observado> |
+
+## Needs Info
+
+<!-- Se o estado for needs-info, cole aqui o corpo de triage-needs-info-template.md. Caso contrário, escreva "n/a". -->
+
+n/a
+
+## Roteamento
+
+| Condição | Rota |
+|----------|------|
+| ready-for-work + bug | `/dw-bugfix` |
+| ready-for-work + enhancement | `/dw-plan prd` |
+| pedido malformado | `/dw-brainstorm --mode=grill` |
+| needs-human | ação do dono |
+| wontfix | sem trabalho downstream |
+
+Rota selecionada: <rota ou n/a>
+
+## Link Out-of-Scope
+
+<Se rejeitado, linke `.dw/out-of-scope/<concept>.md`. Se já implementado, linke a implementação e declare que nenhum registro out-of-scope foi escrito.>
+
+## Histórico
+
+- YYYY-MM-DD — needs-triage -> <state> — <actor> — <reason>

package/scaffold/scripts/hooks/git-guardrails.mjs

@@ -14,13 +14,17 @@
  * error allows the command, so a hook bug never blocks the user.
  */
 
-const DANGEROUS = [
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DANGEROUS = [
   { re: /\bgit\s+push\b[^\n|&;]*(--force\b|--force-with-lease\b|\s-f\b)/, why: 'force push rewrites remote history' },
   { re: /\bgit\s+push\b[^\n|&;]*(--delete\b|\s-d\b|\s:\S)/, why: 'deletes a remote branch' },
   { re: /\bgit\s+reset\b[^\n|&;]*--hard\b/, why: 'hard reset discards uncommitted work and rewrites the branch' },
   { re: /\bgit\s+clean\b[^\n|&;]*-[a-z]*f/, why: 'git clean -f permanently deletes untracked files' },
   { re: /\bgit\s+branch\b[^\n|&;]*\s-D\b/, why: 'force-deletes a branch that may be unmerged' },
   { re: /\bgit\s+checkout\b[^\n|&;]*\s(--\s+\.|\.\s*$)/, why: 'discards all local changes in the working tree' },
+  { re: /\bgit\s+restore\b[^\n|&;]*\s(--\s+)?\.(?=\s*(?:$|[|&;]))/, why: 'discards all local changes in the working tree' },
 ];
 
 function readStdin() {
@@ -38,42 +42,55 @@ function allow() {
   process.exit(0);
 }
 
-function deny(reason) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'deny',
-        permissionDecisionReason: reason,
-      },
-    }) + '\n',
-  );
-  process.exit(0);
-}
-
-async function main() {
+export function evaluatePayload(input) {
   let payload;
   try {
-    payload = JSON.parse(await readStdin());
+    payload = JSON.parse(input);
   } catch {
-    return allow(); // fail open
+    return null; // fail open
   }
 
   const command = payload && payload.tool_input && typeof payload.tool_input.command === 'string'
     ? payload.tool_input.command
     : '';
-  if (!command) return allow();
+  if (!command) return null;
 
   for (const rule of DANGEROUS) {
     if (rule.re.test(command)) {
-      return deny(
-        `Blocked by dev-workflow git guardrails: ${rule.why}. ` +
-          `If this is intentional, run it yourself outside the agent, or adjust .claude/settings.json hooks.`,
-      );
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason:
+            `Blocked by dev-workflow git guardrails: ${rule.why}. ` +
+            `If this is intentional, run it yourself outside the agent, or adjust .claude/settings.json hooks.`,
+        },
+      };
     }
   }
 
-  return allow();
+  return null;
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }) + '\n',
+  );
+  process.exit(0);
+}
+
+async function main() {
+  const result = evaluatePayload(await readStdin());
+  if (!result) return allow();
+  return deny(result.hookSpecificOutput.permissionDecisionReason);
 }
 
-main().catch(() => allow());
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(() => allow());
+}

package/scaffold/skills/dw-debug-protocol/SKILL.md

@@ -32,6 +32,8 @@ See `references/stop-the-line.md` for when this rule bends.
 
 Without a deterministic reproduction, you cannot know whether your "fix" worked. The reproduction is the hypothesis test. Even a flaky bug needs a *reproducible-enough* test (e.g., "fails 8/10 runs") before fixing.
 
+For non-trivial bugs, or after a first fix fails, Step 1 must establish the red-capable feedback loop contract in `references/six-step-triage.md` before theorizing: one loop, deterministic enough, fast, agent-runnable, and observed red. If the loop needs human action, use the HITL template there instead of continuing blind.
+
 If you cannot reproduce: see `references/non-reproducible-strategy.md`. Don't fix on guess.
 
 ### 3. Find the root cause, not the nearest cause

package/scaffold/skills/dw-debug-protocol/references/six-step-triage.md

@@ -14,12 +14,71 @@ Six discrete steps. Each has a specific output. Don't move to the next without f
 - From a log line → find the surrounding context (request ID, user ID, timestamp); reconstruct the scenario.
 - Write a failing test FIRST when the bug is in pure logic. The test commits the bug to record before you fix it.
 
+### Feedback loop contract
+
+For a non-trivial bug, or whenever the first attempted fix did not work, do not theorize before you have a feedback loop. A good loop is:
+
+- **Single:** one command or one executable artifact, not a hand-managed sequence.
+- **Deterministic:** produces the same result often enough to trust the signal.
+- **Fast:** runs quickly enough that you can use it repeatedly while narrowing the cause.
+- **Agent-runnable:** executable by the agent without hidden credentials, private hardware, or unrecorded manual state.
+- **Red-capable:** proven to fail now, with the failure already observed and saved. "It should fail" is not enough.
+
+Small obvious bugs are exempt from the full checklist when the reproduction is already a single clear command or click path and the fix is truly surgical. The exemption ends immediately if the first fix fails or the bug touches multiple layers.
+
+### Loop repertoire
+
+Pick the smallest loop that can show the bug:
+
+| Loop type | Use when |
+|-----------|----------|
+| Focused test | The bug fits an existing unit, integration, contract, or E2E suite |
+| `curl` / HTTP client | The bug is an API request/response behavior |
+| CLI command | The symptom is triggered by a command-line entry point |
+| Headless browser | The bug depends on browser rendering, routing, storage, or user events |
+| Trace replay | You have a captured request/session/fixture that can be replayed |
+| Dedicated harness | The production entry point is too slow or noisy, but a public seam can be exercised directly |
+| Fuzz or repeat runner | The bug is input-sensitive or low-frequency but locally amplifiable |
+| `git bisect` | A known-good revision exists and the regression window matters |
+| Differential test | A new path should match an old implementation, another service, or a reference output |
+
+### HITL loop template
+
+Use this when the loop cannot be run by the agent because it needs credentials, private data, hardware, or a human click. Do not continue in the dark; ask for the missing artifact or access.
+
+```
+## Human-in-the-loop reproduction needed
+
+I cannot run the feedback loop myself because: <credential / hardware / private data / manual action>.
+
+Please provide one of:
+- A single command I can run locally or in CI.
+- A sanitized fixture, trace, screenshot sequence, or log bundle.
+- Temporary access or exact manual steps you will run.
+
+What I already tried:
+- <attempt 1 + result>
+- <attempt 2 + result>
+
+Once provided, I will first confirm the loop is red-capable before proposing the fix.
+```
+
+### After the loop is red-capable
+
+Only after the failing loop is observed:
+
+1. Minimize the case by removing one variable at a time.
+2. List 3-5 falsifiable hypotheses and rank them before testing any one.
+3. Instrument one variable at a time, with removable log prefixes such as `[DW-DEBUG:<slug>]`, so cleanup is mechanical.
+4. Keep the regression test on the right public seam; do not lock the test to internals.
+5. Remove temporary instrumentation before final verification.
+
 **Common pitfall:** "It happens sometimes." This is not a reproduction. Either:
 - Find a deterministic trigger (often there's a state precondition you missed), OR
 - Quantify the rate (8/10 runs) and treat the test as flaky-but-progress.
 - See `non-reproducible-strategy.md` for state/timing/env-dependent cases.
 
-**Done when:** You have a one-line command (or a series of clicks) that produces the bug ≥80% of the time.
+**Done when:** You have a one-line command, executable script, or short click path for a trivial UI bug that produces the bug ≥80% of the time. For non-trivial bugs, the loop also satisfies the feedback loop contract above, or the HITL blocker is recorded with explicit artifact/access requested from the user.
 
 ## Step 2 — Localize
 

package/scaffold/skills/dw-execute-phase/references/wave-coordination.md

@@ -4,7 +4,7 @@ Tasks within a phase have dependencies. Some can run in parallel; others must wa
 
 ## Wave computation
 
-Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task numbers).
+Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task IDs).
 
 Algorithm: topological sort.
 
@@ -13,25 +13,25 @@ Algorithm: topological sort.
 3. Wave assignment:
    - Wave 1 = tasks with zero dependencies
    - Wave N = tasks whose all dependencies are in waves 1..N-1
-4. Output: ordered list of waves, each wave a list of task numbers.
+4. Output: ordered list of waves, each wave a list of task IDs.
 
 ## Example
 
 ```
 tasks.md:
-- 01 Create user schema       Depends on: none
-- 02 Create user model        Depends on: 01
-- 03 Create order schema      Depends on: none
-- 04 Wire auth middleware     Depends on: 02
-- 05 Add login endpoint       Depends on: 04
-- 06 Add order endpoint       Depends on: 02, 03
-- 07 Wire validation rules    Depends on: 04, 06
+- 1.0 Create user schema       Depends on: none
+- 2.0 Create user model        Depends on: 1.0
+- 3.0 Create order schema      Depends on: none
+- 4.0 Wire auth middleware     Depends on: 2.0
+- 5.0 Add login endpoint       Depends on: 4.0
+- 6.0 Add order endpoint       Depends on: 2.0, 3.0
+- 7.0 Wire validation rules    Depends on: 4.0, 6.0
 
 Computed waves:
-Wave 1: [01, 03]            (no deps; can run in parallel)
-Wave 2: [02]                (depends on 01)
-Wave 3: [04, 06]            (depend on wave 2)
-Wave 4: [05, 07]            (depend on wave 3)
+Wave 1: [1.0, 3.0]          (no deps; can run in parallel)
+Wave 2: [2.0]               (depends on 1.0)
+Wave 3: [4.0, 6.0]          (depend on wave 2)
+Wave 4: [5.0, 7.0]          (depend on wave 3)
 ```
 
 ## Parallel execution within a wave
@@ -73,7 +73,7 @@ Each wave is a checkpoint:
 
 ## Order within a wave
 
-Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task number (01 commit before 02 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
+Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task ID (1.0 commit before 2.0 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
 
 This means: subagents return their changes (files written, but NOT committed). The executor commits them in numeric order.
 

package/scaffold/skills/dw-grilling/SKILL.md

@@ -36,17 +36,23 @@ vocabulary and the calling command for the idea one-pager / PRD.
    until every dependency branch is resolved, glossary/code contradictions are closed, no blocking decision
    remains, AND the user explicitly confirms. Otherwise persist a draft/paused state and stop.
 
-## Before the first question — build the decision tree
+## Before the first question — resume or build the decision tree
 
-Inspect project facts and open questions, then order them by dependency (never ask a downstream decision before
-its blocker is resolved):
+Inspect the active one-pager/PRD first. If it already has a `### Decision Map`, read it before reconstructing:
+load its nodes, `Depends on:` fields, states, explicit **Frontier**, and `#### Decision Fog`; do not re-ask a
+node already marked `resolved`. Continue from the Frontier when it exists. Only rebuild from scratch when no
+durable map exists or the map is malformed.
+
+When no resumable map exists, inspect project facts and open questions, then order them by dependency (never ask
+a downstream decision before its blocker is resolved):
 
 1. Read what already exists: `.dw/rules/`, `.dw/intel/` (via `/dw-intel` when present), `.dw/constitution.md`,
    `.dw/domain/**` (glossary / context-map), current PRDs/TechSpecs, recent git activity.
 2. Extract the open decisions the plan/PRD implies. Fold in vocabulary tension surfaced by `dw-domain-modeling`
    (fuzzy or overloaded terms are decisions too).
-3. Order them into a **dependency tree**: a node that constrains others comes first. Record it so a later turn
-   (or `/dw-plan`) can resume. Full method + the shared-understanding gate: `references/decision-tree.md`.
+3. Order them into a **dependency tree**: a node that constrains others comes first. Record it in `### Decision
+   Map` so a later turn (or `/dw-plan`) can resume. Full method + the shared-understanding gate:
+   `references/decision-tree.md`.
 
 ## The loop
 
@@ -59,6 +65,9 @@ For each unresolved node, in dependency order:
    `dw-domain-modeling`; the caller persists to the one-pager/PRD). ADR creation still needs a separate explicit
    approval — never auto-create one.
 5. **Re-walk** the tree: the answer may unlock or reshape downstream nodes.
+6. **Persist the map** after each resolved answer when writes are authorized: update node state, `Depends on:`,
+   explicit **Frontier**, and `Decision Fog` without duplicating the decision outcome already recorded in
+   **Resolved Decisions**.
 
 When the tree is exhausted and contradictions are closed, present the shared-understanding summary and ask the
 user to confirm. Only then is the session `aligned`.
@@ -90,8 +99,9 @@ what you *would* persist.
 - **Scope:** the artifact under grill (one-pager / PRD / TechSpec), the decision tree size, and how many nodes
   are resolved vs open.
 - **Evidence:** the facts discovered from repo/rules/intel/docs (with sources) that were used instead of asking.
-- **Artifacts:** decision tree, resolved decisions with the recommended answer and the user's choice, and any
-  authorized `.dw/domain/**` / one-pager / PRD updates (with paths).
+- **Artifacts:** Decision Map (nodes, `Depends on:`, state, Frontier, Decision Fog), resolved decisions with the
+  recommended answer and the user's choice, and any authorized `.dw/domain/**` / one-pager / PRD updates (with
+  paths).
 - **Decisions:** each resolved decision, the alternative rejected, and why.
 - **Risks:** open decisions, unclosed glossary/code contradictions, and any decision made without full evidence.
 - **Next Step:** either "user to confirm shared understanding" (with the remaining nodes) or "aligned — hand off

package/scaffold/skills/dw-grilling/references/decision-tree.md

@@ -3,7 +3,13 @@
 Grill is not a flat questionnaire. It is a walk down a **dependency-ordered decision tree**, so an upstream
 decision is never asked after the downstream decision it constrains.
 
-## Build the tree (before the first question)
+## Resume or build the tree (before the first question)
+
+Before rebuilding a tree, read the active one-pager/PRD for an existing `### Decision Map`. If present and
+well-formed, resume from it instead of deriving the same tree again. Load the node IDs, `Depends on:` fields,
+states, explicit **Frontier**, and `#### Decision Fog`; do not re-ask a node already marked `resolved`.
+
+If there is no durable map yet:
 
 1. **Gather open decisions.** Read the plan/PRD and the project's durable facts (`.dw/rules/`, `.dw/intel/` via
    `/dw-intel`, `.dw/constitution.md`, `.dw/domain/**`, current PRDs/TechSpecs, recent git activity). List every
@@ -16,14 +22,31 @@ decision is never asked after the downstream decision it constrains.
 4. **Topologically order.** Ask parents before children. Independent branches can be walked in any order, but
    within a branch always resolve the blocker first.
 
-Record the tree (nodes, dependencies, resolved/open) so the session — or a later `/dw-plan` handoff — can resume
-exactly where it stopped.
+Record the tree in the active artifact's `### Decision Map` so this session, a later Grill session, or a later
+`/dw-plan` handoff can resume exactly where it stopped.
+
+## Durable Decision Map contract
+
+- Keep one row per decision node with a stable ID (`D1`, `D2`, ...), a short node label, `State`, `Depends on:`,
+  `Frontier?`, and structural notes.
+- Use the same dependency field shape as task plans: `Depends on: none` or `Depends on: D1, D2`. This keeps
+  dependency parsing consistent across durable artifacts.
+- Allowed `State` values are `resolved`, `open-ready`, and `open-blocked`.
+- Maintain an explicit `**Frontier:**` line listing all `open-ready` node IDs, or `none`. The next session reads
+  this line directly; it must not need to manually recompute the graph to know what can be asked next.
+- Keep `#### Decision Fog` for known unresolved areas that are not yet crisp enough to phrase as a decision
+  node. Each item is one line and graduates into a real node once it becomes decidable.
+
+Do not duplicate the content of `### Resolved Decisions` in the map. The map records structure and resume state;
+`Resolved Decisions` records the recommended answer, user's choice, rejected alternative, and evidence.
 
 ## Walk the tree
 
 Resolve nodes in dependency order using the per-turn contract (`interview-loop.md`). After each answer, **re-walk
-the tree**: a resolved parent may add, remove, or reshape child nodes. New tension discovered mid-walk becomes a
-new node, inserted in dependency order — not asked immediately if a blocker is still open.
+the tree** and persist the updated map when writes are authorized: a resolved parent may add, remove, or reshape
+child nodes. New tension discovered mid-walk becomes a new node, inserted in dependency order — not asked
+immediately if a blocker is still open. If a newly discovered uncertainty is real but still too vague to phrase
+as a decision, add it to `Decision Fog` instead of pretending the tree is complete.
 
 ## The shared-understanding gate
 
@@ -44,8 +67,8 @@ terms, and the remaining (non-blocking) decisions with their owners.
 If the gate is not met — blocking decision open, contradiction unclosed, or the user not yet confirming — **do
 not** declare alignment. Persist a draft/paused state:
 
-- Keep the one-pager (or PRD) at its draft/paused status with the decision tree, resolved decisions, and the
-  remaining open nodes recorded (the caller performs the write, only if authorized).
+- Keep the one-pager (or PRD) at its draft/paused status with `### Decision Map`, resolved decisions, the
+  explicit Frontier, and remaining open nodes recorded (the caller performs the write, only if authorized).
 - Return `FINDINGS` with the open nodes as the Next Step, so the next turn resumes the same tree.
 
 ## Handoff to /dw-plan