@brunosps00/dev-workflow 1.5.0 → 1.7.0

package/scaffold/en/commands/dw-claude-run.md

@@ -11,18 +11,19 @@ session**, score the delivery 0–10, escalate on failure, and **STOP for the ga
 
 | Slot | Claude value |
 |---|---|
-| `DISPATCH` | `UUID=$(cat /proc/sys/kernel/random/uuid); cd <WORKTREE> && claude -p --session-id "$UUID" --model <MODEL> --output-format stream-json --include-partial-messages --verbose --dangerously-skip-permissions "$(cat <PROMPT>)" </dev/null > <AUDIT>/<slug>.log 2>&1` |
+| `DISPATCH` | `UUID=$(cat /proc/sys/kernel/random/uuid); cd <WORKTREE> && claude -p --session-id "$UUID" --model <MODEL> --effort <EFFORT> --output-format stream-json --include-partial-messages --verbose --dangerously-skip-permissions "$(cat <PROMPT>)" </dev/null > <AUDIT>/<slug>.log 2>&1` |
 | `STREAM` | `--output-format stream-json --include-partial-messages --verbose` (`--verbose` is **required** with `stream-json` in `-p` mode) |
 | `AUTO` | `--dangerously-skip-permissions` (headless auto-approve; justified because the worktree is isolated). Read-only/analysis: drop it and pass `--permission-mode plan` (or restrict `--allowedTools`). |
-| `RESUME <id>` | `cd <WORKTREE> && claude --resume "$UUID" -p --output-format stream-json --include-partial-messages --verbose --dangerously-skip-permissions "$(cat <FOLLOWUP_PROMPT>)" </dev/null >> <AUDIT>/<slug>.log 2>&1` |
+| `RESUME <id>` | `cd <WORKTREE> && claude --resume "$UUID" -p --effort <EFFORT> --output-format stream-json --include-partial-messages --verbose --dangerously-skip-permissions "$(cat <FOLLOWUP_PROMPT>)" </dev/null >> <AUDIT>/<slug>.log 2>&1` |
 | `RESUME_LAST` | `claude -c -p …` (continue the most recent conversation in this cwd) |
 | `SESSION_ID` | **FIXED by you** — you pass `--session-id "$UUID"` on the first run, so the id is known up front. Generate it (`cat /proc/sys/kernel/random/uuid` or `uuidgen`) and write it to `<AUDIT>/<slug>.session` BEFORE/at dispatch. No stream-scraping needed — Claude is the easy case. |
 | `DONE_SIGNAL` | the final `{"type":"result"}` message in the stream (carries `subtype`, `usage`, `total_cost_usd`, `num_turns`) |
 | `USAGE` | the `result` message `usage` → `input_tokens` / `cache_read_input_tokens` / `cache_creation_input_tokens` / `output_tokens`, plus `total_cost_usd`. Extract: `grep -oE '"usage":\{[^}]*\}' <AUDIT>/<slug>.log \| tail -1` |
 
-**Model + effort:** `--model` selects the tier (`opus` · `sonnet` · `haiku`, or a full id). Claude has no numeric
-effort flag; map "escalation" to model tier (and, when needed, ask for extended thinking in the prompt). Start one
-tier below the ceiling; escalate per `dw-cli-run`.
+**Model + effort:** `--model` selects the tier (`opus` · `sonnet` · `haiku`, or a full id). `--effort` selects the
+reasoning budget: `low` · `medium` · `high` · `xhigh` · `max` (supported by the Claude CLI ≥ 2.1.206). Escalate per
+`dw-cli-run`: raise `--effort` first (low→medium→high→xhigh→max), then bump `--model` one tier and reset effort.
+Start one notch below the ceiling.
 
 ## Session resume (the heart)
 Because you pass `--session-id "$UUID"`, the id is **fixed and known** at dispatch — write it to
@@ -38,6 +39,8 @@ Because you pass `--session-id "$UUID"`, the id is **fixed and known** at dispat
 | `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
 | `<slug>` | task key for audit/session files | `prd-billing-integrador` |
 | `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |
+| `<MODEL>` | Claude tier or full model id | `opus` / `sonnet` / `haiku` |
+| `<EFFORT>` | reasoning budget (Claude CLI ≥ 2.1.206) | `low` / `medium` / `high` / `xhigh` / `max` |
 
 Return via the `dw-cli-run` **Structured Return** (Status/Score/Scope/Evidence/Artifacts/Decisions/Risks/Telemetry/
 Next Step), including the fixed `session-id` (UUID), its sidecar path, and the exact `RESUME` command to continue.

package/scaffold/en/commands/dw-help.md

@@ -38,12 +38,13 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-commit` | Atomic Conventional Commits for pending work. |
 | `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-## Tier 3 — Specialty (11)
+## Tier 3 — Specialty (12)
 
 | Command | What |
 |---------|------|
 | `/dw-analyze-project` | Scan the repo, write `.dw/rules/`, offer `.dw/constitution.md`, generate `.dw/rules/concerns.md`, and synthesize frontend `DESIGN.md` when tokens exist. |
 | `/dw-redesign-ui "target"` | Audit, propose 2-3 design directions, ship. Enforces UI grounding + WCAG; can run the deterministic impeccable slop detector. |
+| `/dw-open-design --brief <file>` | Generate, iterate, or `--refactor` headless Open Design HTML prototypes via `od`; refines briefs first, can capture current screenshots with `--url --viewports` or `--screenshot`, then verifies file + visual gate. |
 | `/dw-refactor "target"` | Audit code-health and tech debt with Fowler smells, deep-modules analysis, and behavior-preserving test gates. |
 | `/dw-functional-doc` | Map screens + flows into a functional doc validated with Playwright; uses WSL-resilient browser resolution. |
 | `/dw-context-budget` | Audit context overhead from commands, skills, agents, instructions, and MCPs. |
@@ -112,6 +113,7 @@ Match the keyword and suggest:
 | `research`, `compare`, `state of the art` | `/dw-brainstorm --research` |
 | `refactor`, `smell`, `code health`, `tech debt` | `/dw-refactor` |
 | `ui`, `design`, `redesign` | `/dw-redesign-ui` |
+| `open design`, `prototype`, `prototipo`, `od cli`, `html prototype` | `/dw-open-design --brief <file>`, `/dw-open-design --brief-glob "<glob>" --agent claude`, or `/dw-open-design --refactor --url <url> --viewports "1440x900,375x812"` |
 | `intel`, `where is`, `what uses` | `/dw-intel` (or `--build` to (re)create the index) |
 | `context`, `tokens`, `slow agent` | `/dw-context-budget` |
 | `harness`, `install`, `wrappers`, `agents` | `/dw-harness-audit` |

package/scaffold/en/commands/dw-open-design.md

@@ -0,0 +1,324 @@
+<system_instructions>
+You are the **headless Open Design (`od`) runner** for generating and iterating HTML prototypes in a project
+folder, without Electron and without depending on the user's GUI state. Start the `nexu-io/open-design` daemon in
+`--headless`, import the target folder once, run single briefs or serial batches, verify the output file, run the
+Playwright/Firefox visual gate, and **STOP for the owner's gate** before any commit.
+
+<critical>NEVER use the user's GUI state. Always run with an isolated per-project `OD_DATA_DIR`, for example `.dw/.open-design/data/`.</critical>
+<critical>NEVER commit a rejected prototype. The gate is dual >=9: automated gate + your own visual score >=9, then owner gate.</critical>
+<critical>The agent (`codex` or `claude`) must always be explicit in `od run start --agent <agent>`. If the user does not pass one, resolve from project config/state; fallback `codex`.</critical>
+<critical>NEVER dispatch the user's raw request to `od`. This command's value is refining the prompt first: ground it in real code, structure the brief, qualify states/themes/a11y/deep-link, persist the reviewable brief, and only then append the headless appendix.</critical>
+
+## Inputs
+
+| Flag/argument | Default | Description |
+|---|---:|---|
+| `--target <dir>` | `open-design/` | Folder imported as the external project and where HTML files are written. |
+| `--brief <file>` | none | One markdown brief for a single run. |
+| `--brief-glob <glob>` | none | Serial batch. Expand to a stable list and run one prompt at a time. |
+| `--output <file>` | required in the brief/appendix | Expected HTML file; verify it on disk after the run. |
+| `--agent <codex|claude>` | state/config -> `codex` | Agent forwarded to `od run start --agent`. |
+| `--platform <text>` | `Responsive web, desktop-first and mobile-safe` | Pre-filled discovery answer for the `web-prototype` skill. |
+| `--deep-link-id <id>` | none | Value used by the behavioral gate for `?aberto=<id>` + Esc. |
+| `--refactor` | false | Existing-screen redesign/refactor mode; captures current screenshots and grounds the brief in visible state + real code. |
+| `--url <url>` | none | Running app URL for current screenshot capture via Playwright Firefox. |
+| `--viewports <list>` | `1440x900,375x812` | Comma-separated viewports for `--refactor --url`; expand as the pain requires (for example `1920x1080` for a wide table). |
+| `--screenshot <path>` | repeatable | Already-captured current screenshot when there is no `--url`; copy it into `_refs/<slug>/`. |
+
+## 0. Refine The Brief
+
+Before any daemon pre-flight or `od` call, turn the user's intent into a qualified brief. Do not send the user's raw
+sentence to the runner.
+
+Required contract:
+
+| Step | Requirement |
+|---|---|
+| Ground in reality | If the screen exists, read its real code: columns, enums, actions, states, permissions, contracts, and domain. Also read the project's design system, sibling prototypes, and design guides. Inventing a field, status, or action is forbidden. |
+| Structure | Rewrite the request into the standard skeleton below, filling real paths and the exact output file. |
+| Qualify | Cover loading/skeleton, empty, error/failure, light + dark, a11y, local design-system limits (for example <=6 cards/filters), responsiveness, and deep-link. |
+| Persist | Save the refined brief inside the project, for example `<target>/PROMPT-<slug>.md`. It is a reviewable owner deliverable, not a disposable scratch file. |
+| Review if already ready | If the user already provides a qualified brief, do a quick checklist review, patch only gaps, and persist the final version. |
+
+Standard refined brief skeleton:
+
+```markdown
+# <screen/prototype title>
+
+Paste this brief into Open Design. Exact output file: `<OUTPUT_FILE>`.
+
+## 1. Why
+<real user/product pain; observable problem this prototype must solve>
+
+## 2. Interaction Decision
+<navigation, opening, selection, filters, sorting, editing, and confirmation pattern>
+
+## 3. Layout/List
+Table/list based only on REAL columns:
+
+| Real column | Source/contract | Presentation | State/limit |
+|---|---|---|---|
+| <name> | <file/API/schema> | <text, badge, action> | <truncate, empty, error> |
+
+## 4. Detail/Actions
+<drawer/modal/detail page; contextual actions allowed by real state/permission>
+
+## 5. Domain Fidelity
+So the mock does not lie: use real enums/statuses, realistic sample data in the project's language, and include rare/broken states that exist in the domain.
+
+## 6. Visual Direction
+<tokens, components, density, inherited references, sibling prototypes, and design-system limits>
+
+## Deliver
+- `<OUTPUT_FILE>`
+- `<OUTPUT_FILE>.artifact.json` when there is a sidecar
+```
+
+Only after persisting this file should you append the headless appendix under `.dw/.open-design/runs/` and dispatch
+the run.
+
+### 0R. Refactor/Redesign Mode
+
+When `--refactor` is present, phase 0 remains mandatory. Screenshots complement grounding in code; they do not
+replace reading contracts, enums, permissions, states, the design system, and sibling prototypes.
+
+Capture or copy current screenshots into the imported folder, under `_refs/<slug>/`, before persisting the brief:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --url "<url>" \
+  --viewports "1440x900,375x812"
+```
+
+Without a running app URL, accept existing screenshots by repeating `--screenshot`:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --screenshot "./before-1440-light.png" \
+  --screenshot "./before-375-dark.png"
+```
+
+Capture rules:
+
+| Case | Requirement |
+|---|---|
+| Viewports | Sensible default: desktop `1440x900` + mobile `375x812`. The agent chooses/expands as the pain requires: mobile bug includes `375x812`; wide table includes `1920x1080`; tablet/console includes `768x1024`. |
+| Themes | Capture light and dark when applicable. The helper uses `light,dark` by default and writes names like `_refs/<slug>/atual-1440-light.png` and `_refs/<slug>/atual-375-dark.png`. |
+| Robust path | The `od` agent reads images from the project filesystem. Reference relative paths inside the target; do not depend on an image flag in `run start`. |
+| Hygiene | `_refs/` and reference material must not become prototypes. If the target project tracks final prototypes, document cleanup or add `<target>/_refs/` to `.gitignore` according to local convention. |
+
+The refined refactor brief must add this block:
+
+```markdown
+## Current Screen References
+Open and ANALYZE the screenshots before writing:
+- `_refs/<slug>/atual-1440-light.png`
+- `_refs/<slug>/atual-375-dark.png`
+
+## What Is Wrong Today
+<pain pointing to visible elements in the screenshots: density, hierarchy, table, filters, states, contrast, mobile, etc.>
+
+## The Change Idea
+<what changes and why; interaction/visual decision proposed by the user or by the agent after reading code and screenshots>
+
+## Preserve
+<flows, fields, permissions, states, copy, affordances, and integrations that must not change>
+```
+
+## Pre-flight
+
+| Check | Action |
+|---|---|
+| Resolve `od` | `OD_CLI_DIR` wins. Otherwise use `~/.dw/vendor/open-design`. If `apps/daemon/bin/od.mjs` is missing, stop and tell the user to run `dev-workflow install-deps`. |
+| Prerequisites | The Open Design checkout requires Node `~24` and pnpm `>=10.33`. If missing, stop with concrete instructions. |
+| Isolated state | Create `.dw/.open-design/`, `.dw/.open-design/data/`, `.dw/.open-design/runs/`, and `.dw/.open-design/state.json`. |
+| Port | Pick a free port on `127.0.0.1`; persist `daemonUrl` and `port` in state. |
+| Live daemon | If `od daemon status --daemon-url <url> --json` returns `ok: true`, reuse it. Otherwise start a new daemon. |
+
+Daemon command shape:
+
+```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"
+```
+
+Known noise: `codex_core::shell_snapshot` may log a syntax `ERROR`. Treat it as benign when the run continues and
+the target file is created.
+
+## Idempotent Import
+
+Use `project import-folder` on the resolved absolute target folder. Default: `<repo>/open-design/`.
+
+Persist in `.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"
+}
+```
+
+If `projectId` exists in state and `od project info <id> --daemon-url <url> --json` works for the same `targetDir`,
+reuse it. Otherwise, reimport:
+
+```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` and `conversationId`; do not depend on global app state.
+
+## Required Headless Appendix
+
+Append this block to every brief in a temporary file under `.dw/.open-design/runs/`.
+Fill `<PLATFORM>`, `<OUTPUT_FILE>`, and sibling references when applicable.
+
+```markdown
+---
+
+## Headless appendix for Open Design
+
+Target platform: <PLATFORM>.
+
+Do not run discovery and do not ask questions. Do not emit `<question-form>`. Follow this brief with the answers
+above and deliver file-first.
+
+Required output file: `<OUTPUT_FILE>`.
+
+File-first contract:
+- Write the HTML directly to the project filesystem, exactly at `<OUTPUT_FILE>`.
+- Do not alter existing files, except when this prompt is explicitly a surgical iteration on a target file.
+- If you need to create a sidecar, keep `<OUTPUT_FILE>.artifact.json` coherent.
+- Do not answer only with a textual `<artifact>` block; run `succeeded` without the file is a failure.
+
+To avoid headless timeout:
+- Write large files in parts, with edits of about 150 lines per call.
+- Keep visible progress until the HTML is complete.
+
+Consistency context:
+- Read sibling prototypes in `prototipos/` or the folder named by the brief before defining visual patterns.
+- Preserve the local visual system when a nearby reference exists.
+
+Required deep link:
+- Implement `?aberto=<id>` to open the correct item's drawer/modal.
+- On Esc or close action, clear the parameter with `history.replaceState`.
+- The drawer/modal must use `role="dialog"` and appropriate ARIA attributes.
+- Include skeleton/loading, empty, and error states.
+```
+
+## Single Run
+
+Always pass `--agent` explicitly:
+
+```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"
+```
+
+After the run, check the file. **Do not accept only `succeeded`:**
+
+```bash
+test -s "$TARGET_DIR/<OUTPUT_FILE>"
+```
+
+Record in JSONL or an audit sidecar: brief, prompt with appendix, agent, daemonUrl, projectId, conversationId,
+expected output, final status, and file verification result.
+
+## Batch
+
+For `--brief-glob`, expand the briefs, sort by name, and run serially. Stop at the first case where:
+
+| Condition | Result |
+|---|---|
+| run fails | `BLOCKED` with JSONL log |
+| run says success but file is missing or empty | `FINDINGS` and surgical follow-up or `BLOCKED` |
+| visual gate <9 | `FINDINGS`; iterate before continuing |
+
+Do not run prompts in parallel in the same `od` project; preserve auditability and context.
+
+## Surgical Iteration
+
+Use a follow-up run on the same `projectId`/`conversationId`, with a short prompt and explicit target file:
+
+```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"
+```
+
+The follow-up must say: single file, exact change, do not touch sibling prototypes, preserve deep-link and states.
+
+## Required Visual Gate
+
+Run the automated gate:
+
+```bash
+node .dw/scripts/open-design/gate-prototype.mjs \
+  --file "$TARGET_DIR/<OUTPUT_FILE>" \
+  --deep-link-id "<real-id>" \
+  --expected-text "<item-text>" \
+  --out ".dw/.open-design/gate/<slug>"
+```
+
+The gate covers:
+
+| Layer | Requirement |
+|---|---|
+| Structural | `<title>`, `aberto`, `replaceState`, `role=dialog`/ARIA, skeleton/loading, empty, error. |
+| Screenshot | Headless Firefox in light and dark, with `colorScheme` and `data-theme`. |
+| Behavioral | `?aberto=<id>` opens the correct item; Esc closes and clears the parameter. |
+| Evaluation | Automated PASS + your visual score >=9. If below 9, run a surgical follow-up. |
+
+After it passes, **stop for the owner's gate**. Do not commit until the owner approves.
+
+## Validated Pitfalls
+
+| Pitfall | Symptom | Required workaround |
+|---|---|---|
+| `web-prototype` discovery | Opens with `<question-form>` and ends the turn; headless does not create GenUI (`od ui list` empty). | Append the headless appendix answering platform and forbidding questions/discovery. |
+| Inactivity timeout | Large HTML goes silent and the run dies near 10 minutes. | `OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000` on the daemon + instruct ~150-line chunked writes. |
+| `codex_core::shell_snapshot` | Logs a syntax `ERROR` in the stream. | Treat as noise if the run continues and the final file exists. |
+| GUI state | App config/agent/projects leak from the user's GUI. | Isolated `OD_DATA_DIR` always; explicit `--agent`, `--skill`, and `--design-system`. |
+
+## Structured Return
+
+**Status:** `PASS` | `FINDINGS` | `BLOCKED` | `NOT_APPLICABLE`  
+**Scope:** target folder, briefs run, agent used, projectId/conversationId.  
+**Evidence:** JSONL logs, verified HTML file(s), gate JSON, light/dark screenshots.  
+**Artifacts:** prototype and sidecar paths.  
+**Decisions:** defaults/overrides applied (`agent`, `target`, platform, port).  
+**Risks:** any gate below 9, missing file despite run succeeded, missing dependency.  
+**Next Step:** owner gate, required surgical follow-up, or exact resume command.
+</system_instructions>

package/scaffold/en/commands/dw-plan.md

@@ -55,7 +55,36 @@ Claude Code and OpenCode can use native project agents. Codex and Copilot use `.
 
 <critical>When a structured interview/user-input tool is available, `/dw-plan` MUST use it for PRD and TechSpec clarification questions. Do not downgrade to plain chat merely for convenience. If no such tool exists in the runtime, ask the same questions in chat and explicitly record: `Structured interview tool unavailable; using chat fallback.`</critical>
 
-The tool is mandatory for planning because it preserves explicit user choices and prevents the agent from answering its own questions. Each stage keeps its own quota: PRD requires 7+ product questions; TechSpec requires 7+ technical questions.
+The tool is mandatory for planning because it preserves explicit user choices and prevents the agent from answering its own questions.
+
+## Coverage-driven interview (no fixed question quotas)
+
+<critical>`/dw-plan` does NOT ask a fixed number of questions. Each stage builds a **coverage matrix** over its required dimensions, discovers facts from the repo/rules/intel/domain artifacts, **credits evidence already resolved in an aligned Grill handoff**, and then asks — one decision at a time — ONLY the dimensions that remain uncovered. Never re-ask a product decision the user already resolved during Grill.</critical>
+
+### Aligned handoff (from `/dw-brainstorm` grill)
+
+Before Stage 1, check for an idea one-pager at `.dw/spec/ideas/<slug>.md` and the canonical vocabulary in `.dw/domain/**`.
+
+<critical>Validate the handoff and FAIL CLOSED. Credit an aligned handoff — i.e. suppress the product questions its decisions cover — ONLY when EVERY one of these holds:
+- `schema_version: "1.1"`;
+- `status: aligned`;
+- `alignment.confirmed_by_user: true`;
+- every dependency branch is resolved (no open decision node);
+- glossary/code contradictions are closed;
+- no **blocking** entry remains under Remaining Decisions.
+If ANY check fails — or the file is malformed, internally inconsistent, `draft`, or `paused` — the one-pager is **input, not a trusted handoff**: read it for context, but treat all its decisions as **uncovered** and ask them normally. Never suppress a product question on the strength of `status: aligned` alone; `alignment.confirmed_by_user: true` and a resolved, non-blocking, contradiction-free tree are required too.</critical>
+
+When (and only when) the handoff is fully valid:
+- Load its **Resolved Decisions**, **Evidence**, and **Canonical Vocabulary** links.
+- Mark every PRD dimension those decisions cover as **already covered** (cite the one-pager as the evidence) — do NOT re-ask them.
+- Only uncovered dimensions become questions, asked one at a time.
+
+### Coverage matrices
+
+- **PRD dimensions:** goals, target users, scope boundaries, success metrics, rollout strategy, integration points, edge cases.
+- **TechSpec dimensions:** domain placement, data flow, dependencies, core interfaces, test strategy, reuse-vs-build, multi-project integration (when applicable).
+
+For each stage: build the matrix, mark each dimension `covered` (fact discovered or aligned evidence credited) or `uncovered`, then ask only the `uncovered` ones — one decision per turn, each with a recommended answer. **Technical decisions a product Grill did not cover may still be asked during TechSpec** — Grill aligns product vocabulary and product decisions, not the full technical design.
 
 ## Constitution Gate
 
@@ -78,11 +107,11 @@ Runs when default mode OR `plan prd`.
 
 ### Prerequisites for this stage
 - Idea or topic from the user.
-- (Optional) brainstorm one-pager from `/dw-brainstorm --onepager` at `.dw/spec/ideas/<slug>.md`.
+- (Optional) an idea one-pager from `/dw-brainstorm` at `.dw/spec/ideas/<slug>.md`. If it is `status: aligned` (schema `1.1`, from a Grill session), consume it as a handoff — its Resolved Decisions are credited, not re-asked (see Coverage-driven interview).
 
 ### Required behavior
 
-1. **Clarification questions (MINIMUM 7).** Before writing anything, use the structured interview tool when available to ask 7+ focused questions covering: goals, target users, scope boundaries, success metrics, rollout strategy, integration points, edge cases. If the tool is unavailable, use chat fallback and record that fallback.
+1. **Coverage matrix over the PRD dimensions** (goals, target users, scope boundaries, success metrics, rollout strategy, integration points, edge cases). Build the matrix, credit any aligned-handoff evidence and facts discovered from the repo, then ask ONLY the uncovered dimensions — one decision at a time, each with a recommended answer — using the structured interview tool when available (record the chat fallback otherwise). No fixed question count; never re-ask a decision resolved in an aligned one-pager.
 2. **Web search MINIMUM 3 queries** for market patterns, regulatory context, competitor approaches when relevant.
 3. **Constitution alignment.** Each functional requirement (FR-N.M) includes a `Constitution Alignment: respects P-NNN, P-MMM` line OR `no applicable principle: <reason>`.
 4. **Multi-project awareness.** If the feature spans multiple projects in the workspace, consult `.dw/rules/integrations.md` and document scope in the PRD's "Impacted Projects" section.
@@ -106,7 +135,7 @@ Runs when default mode (after PRD approval) OR `plan techspec` OR `plan --from t
 ### Required behavior
 
 1. **Hard gate: PRD open questions.** If `.dw/spec/prd-<feature>/prd.md` has an "Open Questions" section with unresolved items, STOP and ask the user to resolve them first.
-2. **Clarification questions (MINIMUM 7).** Use the structured interview tool when available to ask technical questions covering: domain placement, data flow, dependencies, core interfaces, test strategy, reuse-vs-build, multi-project integration if applicable. If the tool is unavailable, use chat fallback and record that fallback.
+2. **Coverage matrix over the TechSpec dimensions** (domain placement, data flow, dependencies, core interfaces, test strategy, reuse-vs-build, multi-project integration when applicable). Credit aligned-handoff evidence and discovered facts, then ask ONLY uncovered dimensions — one decision at a time — using the structured interview tool when available (record the chat fallback otherwise). Technical decisions not covered by a product Grill may still be asked here. No fixed question count.
 3. **Web search MINIMUM 3 queries** for technical patterns + Context7 MCP for framework/library specifics.
 4. **Source grounding (`dw-source-grounding`).** Every framework/library decision ships with `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`.
 5. **Constitution gate.** Each architectural decision lists `Respects: P-NNN` or `Deviates: P-NNN — justification: <ADR slug or rationale>`. Deviations from `severity: high/critical` principles without ADR → STOP.
@@ -187,7 +216,7 @@ After full plan run, the PRD directory contains:
 
 ## Final Guidelines
 
-- Each stage has its own clarification question quota — don't recycle. Different stages need different framing. Use the structured interview tool whenever available.
+- Each stage runs a coverage matrix over its own dimensions — no fixed question quota. Credit aligned-handoff evidence and discovered facts; ask only uncovered decisions, one at a time. Different stages need different framing. Use the structured interview tool whenever available.
 - Web search is mandatory; Context7 MCP for libraries. No skipping for "I think I know the latest version."
 - Constitution gate runs at every stage entry; defaults are auto-installed when missing (never blocks).
 - All three stages produce committed Markdown — these are the canonical planning artifacts. They evolve with the feature.

package/scaffold/en/templates/adr-template.md

@@ -3,8 +3,9 @@ id: NNN
 status: Proposed
 title: [Short imperative title of the decision]
 date: YYYY-MM-DD
-prd: [PRD slug, e.g. prd-user-auth]
-schema_version: "1.0"
+scope: repo | prd
+prd: [PRD slug for scope=prd, e.g. prd-user-auth; "n/a" for 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` (if applicable)
+<!-- scope=prd: link the owning PRD/TechSpec. scope=repo: no owning PRD — omit the PRD/TechSpec lines
+     (or write "n/a") and link `.dw/constitution.md` / `.dw/rules/` only when they genuinely apply. -->
+
+- PRD: `.dw/spec/[prd-slug]/prd.md` (scope=prd only; "n/a" for scope=repo)
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (if applicable; scope=prd only)
 - Affected tasks: [task list, if applicable]
 - Related ADRs: [list, if applicable]
 

package/scaffold/en/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   # set true ONLY when the user explicitly confirms shared understanding
+  confirmed_on: null         # ISO date of that confirmation
 ---
 
+> **Schema 1.1.** The `## Grill Alignment` block below is populated by a `/dw-brainstorm` grill session. Without a
+> Grill, leave that block empty and keep `status: draft`. `status: aligned` is allowed ONLY when every dependency
+> branch is resolved, glossary/code contradictions are closed, no blocking decision remains, and the user has
+> explicitly confirmed shared understanding — otherwise use `draft` or `paused`.
+
 # Idea: [Short, imperative title]
 
 ## Problem Statement
@@ -81,6 +89,40 @@ Ideally 2-4 stories. If it's more than 5, it's probably not MVP.]
 - [Question 1 affecting scope]
 - [Question 2 affecting priority]
 
+## Grill Alignment
+
+_(schema 1.1 — filled by a `/dw-brainstorm` grill session; consumed by `/dw-plan`, which does NOT re-ask resolved decisions. Leave empty for a non-grilled one-pager.)_
+
+### Resolved Decisions
+
+| Decision | Recommended | Chosen | Alternative rejected | Evidence |
+|----------|-------------|--------|----------------------|----------|
+| [the decision] | [what Grill recommended] | [what the user chose] | [the rejected option + its trade-off] | [one-pager/repo source] |
+
+### Evidence
+
+[Facts discovered during Grill from the repo/rules/intel/docs — each with its source (`path:line`, doc, or intel query) — that were used instead of asking the user.]
+
+- **[fact]** — source: `[path:line or doc]`
+
+### Canonical Vocabulary
+
+[Links into `.dw/domain/**` for the terms this idea depends on. Do not restate definitions here — point to the glossary.]
+
+- **[Term]** → `.dw/domain/glossary.md#term` (or `.dw/domain/contexts/<slug>.md#term` for a multi-context project)
+
+### Remaining Decisions
+
+[Non-blocking decisions still open after alignment, with their owner. A blocking decision means the one-pager is NOT `aligned`.]
+
+- **[open decision]** — owner: [who] — blocking? [no]
+
+### Alignment State
+
+- **State:** `draft` | `paused` | `aligned`
+- **Shared understanding confirmed by user:** [yes/no — `aligned` requires an explicit yes]
+- **Why not aligned (if draft/paused):** [the blocking node or unclosed contradiction that stopped alignment]
+
 ## Next Step
 
 Pick ONE: