@brunosps00/dev-workflow 1.5.0 → 1.7.0

package/scaffold/scripts/open-design/gate-prototype.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+function parseArgs(argv) {
+  const result = {};
+  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) {
+      result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+      continue;
+    }
+    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(/\.html?$/, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 70) || "prototype"
+  );
+}
+
+function addResult(results, name, pass, details = "") {
+  results.push({ name, pass: Boolean(pass), details });
+}
+
+async function structuralChecks(page, html, results) {
+  const data = await page.evaluate(() => {
+    const visibleText = document.body ? document.body.innerText : "";
+    const hasDialogRole = Boolean(document.querySelector('[role="dialog"], [aria-modal="true"], [aria-labelledby]'));
+    const title = document.title.trim();
+    return { visibleText, hasDialogRole, title };
+  });
+
+  addResult(results, "title", data.title.length > 0, data.title || "missing document title");
+  addResult(results, "aberto-param", /\baberto\b/.test(html), "source contains aberto");
+  addResult(results, "replace-state", /replaceState/.test(html), "source contains replaceState");
+  addResult(results, "dialog-aria", data.hasDialogRole, "role=dialog, aria-modal, or aria-labelledby present");
+  addResult(results, "skeleton-state", /skeleton|carregando|loading/i.test(html + "\n" + data.visibleText));
+  addResult(results, "empty-state", /empty|vazio|sem\s+(resultado|dados|itens|registros)/i.test(html + "\n" + data.visibleText));
+  addResult(results, "error-state", /error|erro|falha|failed|retry|tentar novamente/i.test(html + "\n" + data.visibleText));
+}
+
+async function visibleDialog(page, selector) {
+  const selected = selector ? page.locator(selector).first() : page.locator('[role="dialog"], [aria-modal="true"]').first();
+  try {
+    return (await selected.count()) > 0 && (await selected.isVisible());
+  } catch {
+    return false;
+  }
+}
+
+async function clickFirstOpenable(page, rowSelector) {
+  const selector =
+    rowSelector ||
+    '[data-open], [data-id], tbody tr, [role="row"], [role="button"], article, li button, li, button';
+  const candidates = page.locator(selector);
+  const count = Math.min(await candidates.count(), 20);
+  for (let index = 0; index < count; index += 1) {
+    const candidate = candidates.nth(index);
+    try {
+      if (!(await candidate.isVisible())) continue;
+      await candidate.click({ timeout: 1500 });
+      return true;
+    } catch {
+      // Try the next plausible opener.
+    }
+  }
+  return false;
+}
+
+async function behavioralChecks(page, baseUrl, args, results) {
+  const dialogSelector = args.dialogSelector ? String(args.dialogSelector) : "";
+  if (!(await visibleDialog(page, dialogSelector))) {
+    const clicked = await clickFirstOpenable(page, args.rowSelector ? String(args.rowSelector) : "");
+    await page.waitForTimeout(300);
+    addResult(results, "open-drawer-click", clicked && (await visibleDialog(page, dialogSelector)), "first row/openable opens dialog or drawer");
+  } else {
+    addResult(results, "open-drawer-click", true, "dialog already visible");
+  }
+
+  const deepLinkId = args.deepLinkId ? String(args.deepLinkId) : "";
+  if (!deepLinkId) {
+    addResult(results, "deep-link-opens", false, "missing --deep-link-id");
+    addResult(results, "esc-clears-param", false, "missing --deep-link-id");
+    return;
+  }
+
+  const url = new URL(baseUrl);
+  url.searchParams.set("aberto", deepLinkId);
+  await page.goto(url.toString(), { waitUntil: "load" });
+  await page.waitForTimeout(500);
+
+  const expectedText = String(args.expectedText || deepLinkId);
+  const deepLinkData = await page.evaluate((text) => {
+    const bodyText = document.body ? document.body.innerText : "";
+    const hasDialog = Boolean(document.querySelector('[role="dialog"], [aria-modal="true"]'));
+    return {
+      hasDialog,
+      hasText: bodyText.toLowerCase().includes(text.toLowerCase()),
+      search: window.location.search,
+    };
+  }, expectedText);
+  addResult(
+    results,
+    "deep-link-opens",
+    deepLinkData.search.includes(`aberto=${encodeURIComponent(deepLinkId)}`) && deepLinkData.hasDialog && deepLinkData.hasText,
+    `expected visible text: ${expectedText}`,
+  );
+
+  await page.keyboard.press("Escape");
+  await page.waitForTimeout(500);
+  const searchAfterEsc = await page.evaluate(() => window.location.search);
+  addResult(results, "esc-clears-param", !new URLSearchParams(searchAfterEsc).has("aberto"), searchAfterEsc || "empty search");
+}
+
+async function captureScreenshots(browser, fileUrl, outDir, slug) {
+  const shots = [];
+  for (const scheme of ["light", "dark"]) {
+    const context = await browser.newContext({
+      colorScheme: scheme,
+      viewport: { width: 1440, height: 1000 },
+    });
+    const page = await context.newPage();
+    await page.goto(fileUrl, { waitUntil: "load" });
+    await page.evaluate((theme) => {
+      document.documentElement.setAttribute("data-theme", theme);
+    }, scheme);
+    await page.waitForTimeout(300);
+    const shotPath = path.join(outDir, `${slug}-${scheme}.png`);
+    await page.screenshot({ path: shotPath, fullPage: true });
+    shots.push({ colorScheme: scheme, path: shotPath });
+    await context.close();
+  }
+  return shots;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.file) {
+    throw new Error("Missing required argument: --file <prototype.html>");
+  }
+
+  const filePath = path.resolve(String(args.file));
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Prototype file not found: ${filePath}`);
+  }
+
+  const firefox = await importFirefox();
+  if (!firefox) {
+    throw new Error("Playwright is not installed. Run: npm i -D @playwright/test && npx playwright install firefox");
+  }
+
+  const html = fs.readFileSync(filePath, "utf8");
+  const outDir = path.resolve(String(args.out || path.join(".dw", ".open-design", "gate", slugify(path.basename(filePath)))));
+  fs.mkdirSync(outDir, { recursive: true });
+  const baseUrl = pathToFileURL(filePath).toString();
+  const slug = slugify(path.basename(filePath));
+
+  const browser = await firefox.launch({ headless: true });
+  const results = [];
+  let screenshots = [];
+  try {
+    const context = await browser.newContext({ colorScheme: "light", viewport: { width: 1440, height: 1000 } });
+    const page = await context.newPage();
+    await page.goto(baseUrl, { waitUntil: "load" });
+    await structuralChecks(page, html, results);
+    await behavioralChecks(page, baseUrl, args, results);
+    await context.close();
+    screenshots = await captureScreenshots(browser, baseUrl, outDir, slug);
+  } finally {
+    await browser.close();
+  }
+
+  const failed = results.filter((result) => !result.pass);
+  const summary = {
+    file: filePath,
+    score: Number(((results.length - failed.length) / results.length * 10).toFixed(1)),
+    pass: failed.length === 0,
+    results,
+    screenshots,
+  };
+  fs.writeFileSync(path.join(outDir, `${slug}-gate.json`), JSON.stringify(summary, null, 2) + "\n", "utf8");
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`gate-prototype: ${error.message}\n`);
+  process.exit(1);
+});

package/scaffold/skill-registry.json

@@ -35,7 +35,7 @@
       "trigger": "Fire an AI CLI (Codex/Claude/Copilot) in a dedicated git worktree to implement a prepared prompt; resumable per-task session; STOP for the gate",
       "expected_output": "Audit-logged run with a 0-10 dual evaluation, a resumable session-id sidecar, and a STOP-for-gate Structured Return.",
       "load_policy": "lazy-references",
-      "context_limit": 18000,
+      "context_limit": 19000,
       "bundled": true
     },
     {
@@ -60,6 +60,30 @@
       "context_limit": 12000,
       "bundled": true
     },
+    {
+      "name": "dw-domain-modeling",
+      "kind": "protocol",
+      "tier": "specialty",
+      "owner": "dw-brainstorm,dw-analyze-project",
+      "trigger": "Native Grill domain vocabulary: challenge fuzzy/overloaded terms, cross-check against code, persist a canonical glossary to .dw/domain",
+      "expected_output": "Canonical terms with discouraged synonyms persisted lazily to .dw/domain (single or multi-context), or fuzzy-term findings.",
+      "load_policy": "lazy-references",
+      "context_limit": 12000,
+      "exportable": false,
+      "bundled": true
+    },
+    {
+      "name": "dw-grilling",
+      "kind": "protocol",
+      "tier": "specialty",
+      "owner": "dw-brainstorm,dw-plan",
+      "trigger": "Native Grill decision-tree interview: sharpen a plan/PRD to shared understanding, exactly one decision per turn with a recommended answer",
+      "expected_output": "A dependency-ordered decision tree, resolved decisions with recommendations, and an explicit shared-understanding gate.",
+      "load_policy": "lazy-references",
+      "context_limit": 12000,
+      "exportable": false,
+      "bundled": true
+    },
     {
       "name": "dw-debug-protocol",
       "kind": "protocol",

package/scaffold/skills/dw-cli-run/SKILL.md

@@ -129,19 +129,21 @@ without reaching 9. Always show the score + a short per-criterion rationale —
 ceiling, **cite the specific gap** (the failing test, the file left out of fence), not just a label. Same
 evidence discipline as the five-axis rubric in `dw-review-rigor/references/self-eval-rubric.md`.
 
-## Dual evaluation: the CLI auto-gates (MAX effort) → Claude re-gates (compares scores)
+## Dual evaluation: the CLI auto-gates (max effort) → the parent re-gates (compares scores)
 The CLI **can't grade its own exam alone** — hence two layers. The CLI auto-gates cheaply (close to the work) and
-**Claude audits independently** and **compares the scores** (catches an inflated self-score).
+**the parent/orchestrator audits independently** and **compares the scores** (catches an inflated self-score). The
+parent is the dispatching session — possibly Claude itself; the re-gate is provider-neutral.
 1. **CLI auto-gate (loop, MAX effort).** The prompt MUST instruct: after implementing, **run the SAME gate** and
    give a **self-score 0–10**; **fix and re-run while the self-score <9 or the gate isn't green**, at max effort.
    Stop at self-score ≥9 + green gate (or report `blockers`). The final report carries the self-score + per
    criterion.
-2. **Claude re-gate (independent).** When the CLI declares pass, the parent **re-runs the SAME gate** (fan-out,
-   prefer Workflow → `/workflows`) and gives its **own 0–10** — without trusting the self-score.
-3. **Compare + decide.** Claude ≥9 and small gap → **PASS** (ready for the owner's merge decision). Claude <9 OR a
+2. **Parent re-gate (independent).** When the CLI declares pass, the parent/orchestrator **re-runs the SAME gate**
+   (fan-out, prefer Workflow → `/workflows`) and gives its **own 0–10** — without trusting the self-score (a worker
+   never signs off on its own exam, even when that worker is Claude).
+3. **Compare + decide.** Parent ≥9 and small gap → **PASS** (ready for the owner's merge decision). Parent <9 OR a
    large gap (CLI overestimated) → re-execute: hand the gaps back via **session resume** (step 5, max effort) and
-   repeat 1→2→3 until it converges. **The score that counts for acceptance is Claude's**; the self-score is signal
-   + an inflation detector. Always record both scores + the gap in the Structured Return.
+   repeat 1→2→3 until it converges. **The score that counts for acceptance is the parent's**; the self-score is
+   signal + an inflation detector. Always record both scores + the gap in the Structured Return.
 
 ## Graded escalation on failure
 If the score is low / the gate failed / the CLI didn't finish, **re-run the SAME task one notch up** — gradual, no
@@ -199,7 +201,7 @@ The stream ends with the adapter's `USAGE` block (token counts). Extract it from
   right worktree, ready for the gate; `FINDINGS` = ran, score 6–8 or caveats (uncommitted/out-of-fence/partial);
   `BLOCKED` = missing CLI/credential/worktree/prompt/adapter table, or escalation exhausted without reaching 9;
   `NOT_APPLICABLE` = no worktree+prompt → still planning.
-- **Score:** **Claude's score** (0–10 — counts for acceptance, bar ≥9) + the **CLI self-score** + the **gap**;
+- **Score:** **the parent's score** (0–10 — counts for acceptance, bar ≥9) + the **CLI self-score** + the **gap**;
   per-criterion rationale (conformance/gate/completeness/hygiene/quality). Large gap = inflated self-score.
 - **Scope:** worktree + branch + prompt used; CLI + model + effort + sandbox/auto mode; escalation notches taken.
 - **Evidence:** path of the durable audit log + final-message file; stream JSONL excerpt; `git status`/diff of the

package/scaffold/skills/dw-domain-modeling/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: dw-domain-modeling
+description: "Internal domain-vocabulary protocol for the native Grill flow. Loaded by /dw-brainstorm (grill mode) and referenced by /dw-analyze-project to keep canonical vocabulary: challenge fuzzy or overloaded terms, propose precise canonical names, stress-test with concrete edge-case scenarios, cross-check terms against the code, and persist resolved terms safely and lazily into .dw/domain (glossary for a single context, context-map plus per-context files for many). Rare ADR policy. Pipeline-internal, never exported, never implements code."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+---
+
+# dw-domain-modeling — canonical vocabulary, kept in .dw/domain
+
+The vocabulary layer of the native Grill flow. It keeps the language of the domain sharp: one canonical term per
+concept, fuzzy language challenged, overloaded terms split, every term cross-checked against the code. Resolved
+terms persist to `.dw/domain/**` — **never** to root `CONTEXT.md` and **never** into the auto-generated
+`.dw/rules/` module files (those describe what the code IS; the glossary is human-curated vocabulary).
+
+> **Internal protocol.** Loaded by `/dw-brainstorm --mode=grill`; read and linked (never regenerated) by
+> `/dw-analyze-project`. Not standalone, not exported to the à-la-carte plugin.
+
+## The disciplines
+
+1. **Canonical vocabulary — one term per concept.** When several words compete for the same idea, pick the best
+   and record the rest as discouraged synonyms. The glossary's job is to end the debate, not catalogue it.
+2. **Challenge fuzzy / overloaded terms.** When the user says "the user thing" or uses one word for two
+   concepts (`User` the account vs `User` the person), stop and propose precise names. Don't pretend to
+   understand — push back until the term is sharp.
+3. **Stress-test with concrete scenarios.** Force precision with edge cases: *"A guest checks out without an
+   account — is that a Customer or a Visitor?"* Vague answers become the next grill question.
+4. **Cross-check against the code.** Before recording a term, confirm it against the codebase. Surface
+   contradictions with the file and line: *"You call it `Subscription`, but `src/billing/plan.ts:12` models it
+   as `Plan`. Which is canonical?"* Don't argue from generalities.
+5. **Persist safely, lazily, and only when authorized.** Create a `.dw/domain/**` file only **after** a term is
+   resolved AND the Grill flow has write authorization. No speculative files; no writing an unresolved term.
+6. **Route single vs multi context.** One bounded context → one flat `.dw/domain/glossary.md`. Multiple contexts
+   (the same word means different things in billing vs shipping) → `.dw/domain/context-map.md` plus one
+   `.dw/domain/contexts/<slug>.md` per context. Full routing + format: `references/glossary-format.md`.
+7. **ADR rarely, and only on approval.** Vocabulary decisions are not ADRs. Reach for an ADR only on the
+   three-criterion test, and only with separate explicit user approval — see `references/adr-policy.md`.
+
+## Native artifacts
+
+| Path | When |
+|---|---|
+| `.dw/domain/glossary.md` | Single bounded context — the default. |
+| `.dw/domain/context-map.md` | Two or more contexts — names the contexts and the terms that cross or clash. |
+| `.dw/domain/contexts/<slug>.md` | Per-context glossary, one file per context. |
+
+All created **lazily**: the directory and file appear only when the first term in that context is resolved and
+authorization exists. `/dw-analyze-project` **reads and links** these when present and must **preserve** them —
+never regenerate or overwrite `.dw/domain/**`.
+
+## What a glossary entry is (and is not)
+
+A definition is **one or two sentences** that say what the domain term **is**, plus a short list of discouraged
+synonyms. It **excludes** implementation details (classes, files, tables), requirements ("must load in 200ms"),
+scratch notes, and general programming concepts (timeouts, retries, DTOs) — even when the project uses them
+heavily. The test: *is this concept unique to this domain, or general programming?* Only the former belongs.
+Format and examples: `references/glossary-format.md`.
+
+## Anti-patterns
+
+- Writing vocabulary into `.dw/rules/<module>.md` or a root `CONTEXT.md` instead of `.dw/domain/**`.
+- Creating a glossary file for a term that is not yet resolved, or before write authorization exists.
+- Definitions that describe the code ("a `Repository` class in `src/`") instead of the concept.
+- Listing every synonym as equal — pick one canonical term, discourage the rest.
+- Splitting into multiple contexts prematurely — a single flat glossary is right until a word genuinely clashes
+  across contexts.
+- Regenerating or overwriting `.dw/domain/**` from `/dw-analyze-project`.
+
+## Structured Return
+
+- **Status:** `PASS` · `FINDINGS` · `BLOCKED` · `NOT_APPLICABLE` — `PASS` when the terms in scope are resolved,
+  cross-checked against the code, and (when authorized) persisted to the correct `.dw/domain/**` path; `FINDINGS`
+  when terms remain fuzzy, a code contradiction is open, or authorization is missing so nothing was written;
+  `BLOCKED` when the caller supplied no vocabulary to resolve or the code cross-check cannot run;
+  `NOT_APPLICABLE` when there is no domain vocabulary at stake.
+- **Scope:** the terms examined, single- vs multi-context routing, and the target `.dw/domain/**` path(s).
+- **Evidence:** the code cross-checks (file:line) and scenarios used to sharpen each term.
+- **Artifacts:** the glossary / context-map / per-context files written or proposed, with paths.
+- **Decisions:** each canonical term chosen, the discouraged synonyms, and the routing decision.
+- **Risks:** unresolved fuzziness, open code contradictions, or vocabulary written without authorization.
+- **Next Step:** resolve the remaining terms, request write authorization, or hand the canonical vocabulary back
+  to the grill / one-pager.

package/scaffold/skills/dw-domain-modeling/references/adr-policy.md

@@ -0,0 +1,48 @@
+# ADR policy — rare, three-criterion, approval-gated
+
+Most decisions surfaced during a grill are **not** ADRs. Vocabulary choices, scope calls, and reversible
+decisions belong in the glossary or the one-pager, not the ADR log. An ADR is for the rare decision that is
+expensive to unwind and non-obvious to a future reader.
+
+## The three-criterion test (all must hold)
+
+| Criterion | Test |
+|---|---|
+| **Hard to reverse** | If we change this in 6 months, does it cost meaningfully more than a day — a migration, a re-architecture, a contract change? |
+| **Surprising without context** | Would a competent new contributor reasonably reach a *different* decision, absent this record? |
+| **Genuine trade-off** | Was there a real alternative we considered and chose against — a rejection worth remembering? |
+
+If any criterion fails, **do not** write an ADR. Record the decision where it belongs (glossary, one-pager, PRD)
+and move on. ADR-ing every casual decision turns the log into noise.
+
+## Approval is always separate
+
+Even when all three criteria hold, **creating an ADR needs a separate, explicit user approval.** A resolved grill
+decision authorizes the glossary/alignment update — it does **not** authorize an ADR. Offer the ADR, state which
+criteria it meets, and wait for the user to approve before anything is written.
+
+## Routing — repo vs prd scope
+
+ADRs are created via `/dw-adr`, which routes by `--scope`:
+
+- **`--scope=repo`** → `.dw/adrs/adr-NNN.md`. Repo-wide decisions, and any decision made **before a PRD exists**
+  (a greenfield grill naturally produces repo-scoped ADRs).
+- **`--scope=prd`** → `.dw/spec/<prd>/adrs/adr-NNN.md`. Decisions bound to a specific active PRD.
+
+Default resolution when scope is unspecified (`--scope=` is always authoritative): the uniquely **active** PRD →
+`prd`; no active PRD → `repo`; several active PRDs (ambiguous) → **ask**, don't guess. `NNN` is sequential within
+the chosen scope's ADR directory.
+
+**Active vs historical PRD** — deterministic and conservative, reading only evidence the repo already records
+(never guessing): a PRD directory is a candidate only when it is **not terminal** (its `prd.md` status is not
+shipped/merged/delivered/done/archived/superseded/cancelled). Choose the active one by precedence — an **explicit
+target** (named PRD or `PRD_PATH`) → the **active session** (`.dw/STATE.md`) → the **current `feat/prd-<slug>`
+branch**. If more than one non-terminal PRD survives with no disambiguating signal, **ask**. The authoritative
+rule lives in the `/dw-adr` "Active PRD" section.
+
+## What qualifies
+
+Architectural shape, integration patterns between components, high-lock-in technology choices, bounded-context
+boundaries, deliberate deviations from convention, non-visible constraints, and non-obvious rejected
+alternatives. A vocabulary decision — "we call it `Tenant`, not `Org`" — does **not** qualify; it is a glossary
+entry.

package/scaffold/skills/dw-domain-modeling/references/glossary-format.md

@@ -0,0 +1,66 @@
+# Glossary format and context routing
+
+Where domain vocabulary lives, what an entry looks like, and how to decide between a single flat glossary and a
+multi-context map.
+
+## Paths (created lazily)
+
+| Path | Purpose |
+|---|---|
+| `.dw/domain/glossary.md` | The single-context default. One flat glossary for the whole project. |
+| `.dw/domain/context-map.md` | Multi-context index: names each bounded context and the terms that cross or clash between them. |
+| `.dw/domain/contexts/<slug>.md` | One glossary per bounded context (`<slug>` = kebab-case context name). |
+
+Never write vocabulary to root `CONTEXT.md` or to `.dw/rules/<module>.md`. The `.dw/rules/` files are
+auto-generated analysis of what the code IS; the glossary is human-curated vocabulary and must survive
+`/dw-analyze-project` runs untouched.
+
+Create files only when a term is **resolved** and the Grill flow has **write authorization**. Do not scaffold
+empty files or write an unresolved term.
+
+## Entry format
+
+Each term is a short entry:
+
+```markdown
+### Order
+A customer's committed request to buy one or more items, in one of: pending, paid, shipped, delivered, refunded.
+
+_Avoid:_ Purchase, Cart, Transaction
+```
+
+Rules for an entry:
+
+- **One or two sentences.** Define what the term **is**, not what a class does. If it needs a paragraph, the
+  concept is probably two concepts — split it.
+- **`_Avoid:_` line** lists the discouraged synonyms. Pick one canonical term; every competing word goes here so
+  the debate does not reopen.
+- **Exclude** implementation detail (files, classes, tables, endpoints), requirements/NFRs, scratch notes, and
+  general programming concepts (timeout, retry, DTO, cache) even if heavily used.
+- **Inclusion test:** *is this concept unique to this domain, or is it general programming?* Only the former is a
+  glossary term. `Order`, `Tenant`, `Dunning` — yes. `Timeout`, `Repository`, `Idempotency key` — no.
+
+Group entries under `##` subheadings when natural clusters emerge; a flat list of `###` terms is fine for a small
+glossary.
+
+## Single vs multi context — how to route
+
+Start with **one flat `.dw/domain/glossary.md`**. It is the right default and stays right until a word genuinely
+means different things in different parts of the system.
+
+Split to multi-context only when a term **clashes across bounded contexts** — e.g. `Account` means a login in
+Identity but a ledger in Billing. Then:
+
+1. Create `.dw/domain/context-map.md`. List each context (Identity, Billing, Shipping…), a one-line description,
+   and the **shared or clashing terms** with the context each meaning belongs to.
+2. Move each context's terms into `.dw/domain/contexts/<slug>.md` (e.g. `contexts/billing.md`).
+3. In the context map, note translations: "Billing `Account` ≈ Identity `Organization`, not Identity `Account`."
+
+Do not split pre-emptively. A single clean glossary beats three thin ones. When in doubt, stay single-context and
+record the tension as a grill decision rather than forking files.
+
+## Interaction with /dw-analyze-project
+
+`/dw-analyze-project` must, when `.dw/domain/**` exists: read it, link it from `.dw/rules/index.md` (so
+downstream commands find the canonical vocabulary), and **preserve it verbatim** — never regenerate, merge, or
+overwrite. The analyzer owns `.dw/rules/**`; the Grill flow owns `.dw/domain/**`.

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

@@ -0,0 +1,98 @@
+---
+name: dw-grilling
+description: "Internal decision-tree interview protocol for the native Grill flow. Loaded by /dw-brainstorm (grill mode) and /dw-plan to stress-test a plan or PRD to shared understanding: build a dependency-ordered decision tree, ask exactly ONE unresolved decision per turn with a recommended answer plus rationale and a real alternative, discover facts from the repo/docs instead of asking, leave decisions to the user, and gate alignment on explicit confirmation. Pipeline-internal, never exported, never implements code."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# dw-grilling — interview to shared understanding, one decision at a time
+
+A relentless-but-disciplined interview that sharpens a plan/PRD until author and reviewer reach a
+**shared understanding** — the alignment layer of the native Grill flow. It walks the design tree branch by
+branch, resolving dependencies one at a time. It does not brainstorm options and it does not implement; it
+converges decisions. Persistence (glossary, one-pager, PRD) is delegated — see `dw-domain-modeling` for
+vocabulary and the calling command for the idea one-pager / PRD.
+
+> **Internal protocol.** Loaded by `/dw-brainstorm --mode=grill` and by `/dw-plan` when it consumes an aligned
+> handoff. Not a standalone skill, not exported to the à-la-carte plugin. If no calling command supplied the
+> Grill context (target artifact + write authorization state), return `NOT_APPLICABLE`.
+
+## Hard rules (non-negotiable)
+
+1. **Exactly one unresolved decision per turn, then wait.** Never dump a list of questions — a batch is
+   bewildering and lets the reviewer skim instead of decide. Ask, wait, integrate the answer, ask the next.
+2. **Every question carries a recommendation.** Structure: *evidence (when available) → the decision →
+   recommended answer → one-line rationale → a meaningful alternative and its trade-off.* A question with no
+   recommended answer is not ready to ask. See `references/interview-loop.md`.
+3. **Facts are discovered, decisions are asked.** If the answer can be found in the codebase, rules, intel,
+   or docs, look it up and state it — do not ask the user a question the repo already answers. Only genuine
+   **decisions** (choices with no single correct answer) go to the user.
+4. **Decisions belong to the user.** Recommend, argue, push back on vague language — but the user chooses.
+   Never answer your own decision question and move on.
+5. **No implementation, ever.** Grill never edits source code. It produces alignment, not commits.
+6. **Alignment is gated on explicit confirmation.** Do not declare shared understanding (or `status: aligned`)
+   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
+
+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`.
+
+## The loop
+
+For each unresolved node, in dependency order:
+
+1. **Discover** every fact the node needs (repo/docs). State the facts and their source.
+2. **Frame the decision** and give the recommended answer + rationale + one real alternative/trade-off.
+3. **Ask** — one decision, then wait.
+4. **Integrate** the answer. A resolved answer authorizes the matching glossary/alignment update (delegated to
+   `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.
+
+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`.
+
+## Allowed writes (only when the caller authorized them)
+
+Grill is read-first. The only stateful writes the flow may make, and only after the corresponding decision is
+resolved and write authorization exists, are: `.dw/domain/**` (via `dw-domain-modeling`), the active
+`.dw/spec/ideas/<slug>.md`, an explicitly active PRD/TechSpec **after showing the proposed change**, and routed
+ADR paths (after separate approval). Never source code. If authorization is absent, keep interviewing and report
+what you *would* persist.
+
+## Anti-patterns
+
+- Asking two or more decisions in one turn — the batch defeats the protocol.
+- Asking a question the codebase already answers — that is a fact, look it up.
+- Recommending nothing ("what do you want to do about X?") — always bring a recommended answer.
+- Declaring alignment without the user's explicit confirmation.
+- Writing any artifact before its decision is resolved and authorization exists.
+- Generating an option matrix here — that is `option-matrix`, a separate and mutually exclusive phase.
+
+## Structured Return
+
+- **Status:** `PASS` · `FINDINGS` · `BLOCKED` · `NOT_APPLICABLE` — `PASS` when the tree is fully resolved,
+  contradictions closed, and the user explicitly confirmed shared understanding (session `aligned`); `FINDINGS`
+  when decisions were resolved but blocking questions, unclosed contradictions, or a pending confirmation remain
+  (draft/paused); `BLOCKED` when the caller supplied no target artifact or write-authorization state, or the
+  interview cannot proceed; `NOT_APPLICABLE` when invoked without Grill context (no plan/PRD to sharpen).
+- **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).
+- **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
+  to /dw-plan" — never implement here.

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

@@ -0,0 +1,56 @@
+# Decision tree — build, order, gate, resume
+
+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)
+
+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
+   decision the artifact leaves open. Fold in vocabulary tension from `dw-domain-modeling` — an overloaded or
+   fuzzy term is a decision node.
+2. **Separate facts from decisions.** Discard anything the repo already answers (those are facts to state, not
+   ask). What remains is the decision set.
+3. **Draw dependencies.** For each decision, mark which other decisions must be settled first. "Is refund a
+   state or a flag?" blocks "which events transition into it?". A node that constrains others is a **parent**.
+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.
+
+## 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 shared-understanding gate
+
+Declare alignment (and let the caller set the one-pager to `status: aligned`) only when **all** hold:
+
+- Every dependency branch is resolved — no open decision node remains.
+- Every glossary/code contradiction surfaced during the grill is closed (a canonical term chosen, or the code
+  discrepancy explained).
+- No blocking open decision remains (a non-blocking "revisit later" may be recorded as a remaining decision).
+- The user has **explicitly confirmed** shared understanding — not "sounds good", but an explicit yes to the
+  summary of resolved decisions and canonical vocabulary.
+
+Present a shared-understanding summary before asking for confirmation: the resolved decisions, the canonical
+terms, and the remaining (non-blocking) decisions with their owners.
+
+## Paused / draft state
+
+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).
+- Return `FINDINGS` with the open nodes as the Next Step, so the next turn resumes the same tree.
+
+## Handoff to /dw-plan
+
+An `aligned` session is a handoff contract: the resolved product decisions, their evidence, and the canonical
+vocabulary links. `/dw-plan` consumes this **without re-asking** the resolved decisions — it credits the aligned
+evidence in its coverage matrices and asks only decisions the Grill did not cover (technical decisions may still
+surface during TechSpec). Never re-litigate a decision the user already settled in the grill.