@brunosps00/dev-workflow 1.5.0 → 1.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "author": {
     "name": "Bruno Santos"
   },

package/README.md

@@ -42,7 +42,7 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v1.5.0 ships **37 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.6.0 ships **37 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 
@@ -377,7 +377,7 @@ Optional Azure integration (v1.0.3). The `/dw-install-azure-skills` command and
 
 Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex) formalized in `CLAUDE.md`/`AGENTS.md` above the Trigger Map; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
 
-Four patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding new commands or skills** — instead they fold into the existing surface as internal modes and inline guidance: (1) **grill-with-docs** → `/dw-brainstorm` `grill` mode (interview discipline that stress-tests plan vocabulary against `.dw/rules/`); (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same release also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
+Patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding any new public command** (the public command count is unchanged): (1) **grill** — a native, stateful alignment session reimplemented (clean-room, no upstream prose copied) from [`skills/engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md), [`skills/productivity/grilling`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md), and [`skills/engineering/domain-modeling`](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md). It is the `/dw-brainstorm` `grill` mode, backed by two **internal, non-exported** bundled skills — `dw-grilling` (dependency-ordered decision-tree interview, one decision per turn with a recommended answer, facts looked up rather than asked, shared-understanding gate) and `dw-domain-modeling` (canonical glossary, fuzzy/overloaded-term challenge, rare ADRs). Intentional `.dw/` differences: the curated glossary lives in **`.dw/domain/**`** (not upstream's root `CONTEXT.md`, and not our auto-generated `.dw/rules/`); Grill requires **one explicit authorization** before it writes and is mutually exclusive with the option matrix; alignment emits an idea one-pager at **schema `1.1`** consumed by `/dw-plan` without re-asking; and ADR creation is gated on the 3-criteria test and routed via `/dw-adr --scope=repo|prd`. (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same line of work also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
 
 Opportunity discovery and the explicit `/dw-refactor` surface were inspired by patterns observed in [`pedronauck/skills`](https://github.com/pedronauck/skills), especially `game-changing-features` (10x opportunity framing) and `refactoring-analysis` (Fowler-smell prioritization). dev-workflow does not install or depend on that repository at runtime, and the command text here is a clean-room adaptation of the workflow shape rather than copied skill content.
 

package/lib/constants.js

@@ -1,9 +1,9 @@
 const COMMANDS = {
   en: [
-    { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost.' },
+    { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost. --scope=repo writes .dw/adrs/ (works before any PRD); --scope=prd writes under the active PRD. Gated on hard-to-reverse + surprising + genuine trade-off.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
     { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. First invocation plans and stops; second invocation resumes via dw-goal, then commit and PR.' },
-    { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Modes: ideation, --research, --onepager, --council. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
+    { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Auto-dispatches internal modes via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill is a native stateful alignment session (a direct grill-me phrase or --mode=grill) that writes canonical vocabulary to .dw/domain/. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
     { name: 'dw-claude-run', userInvoked: true, description: 'Trigger when user asks to run/fire Claude (claude -p headless) in a dedicated worktree to implement a prepared prompt/spec. Claude adapter over the dw-cli-run protocol: durable audit log, resumable session via --session-id, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
     { name: 'dw-codex-run', userInvoked: true, description: 'Trigger when user asks to run/fire Codex (codex exec) in a dedicated worktree to implement a prepared prompt/spec. Codex adapter over the dw-cli-run protocol: durable audit log, resumable per-task session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
@@ -39,10 +39,10 @@ const COMMANDS = {
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
-    { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam.' },
+    { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam. --scope=repo escreve em .dw/adrs/ (funciona antes de qualquer PRD); --scope=prd escreve sob o PRD ativo. Gated em dificil-de-reverter + surpreendente + trade-off real.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
     { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Primeira invocacao planeja e para; segunda retoma via dw-goal, depois commit e PR.' },
-    { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Modos: ideacao, --research, --onepager, --council. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
+    { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Auto-dispatch de modos internos via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill e uma sessao nativa de alinhamento com estado (frase direta tipo me-questione ou --mode=grill) que escreve vocabulario canonico em .dw/domain/. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
     { name: 'dw-claude-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Claude (claude -p headless) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Claude sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel via --session-id, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
     { name: 'dw-codex-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Codex (codex exec) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Codex sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel por tarefa, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"
   },
   "scripts": {
+    "test": "node --test test/*.test.js",
     "validate": "node lib/validate.js",
-    "build:plugin": "node lib/build-plugin.js"
+    "build:plugin": "node lib/build-plugin.js",
+    "pack:check": "npm pack --dry-run"
   },
   "files": [
     "bin/",

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

@@ -1,36 +1,71 @@
 <system_instructions>
-You are an architectural-decision recorder. Your job is to create an **Architecture Decision Record (ADR)** documenting an important technical decision made during the current PRD phase.
+You are an architectural-decision recorder. Your job is to create an **Architecture Decision Record (ADR)** documenting an important technical decision — either repo-wide (`--scope=repo`, valid even before any PRD exists) or bound to an active PRD (`--scope=prd`).
 
 ## When to Use
 - Use when an architectural or design decision has been made and needs to be recorded for future reference (library choice, communication pattern, performance tradeoff, compliance-imposed constraint, etc.)
 - Use during `/dw-plan techspec` or `/dw-run` when the rationale for the decision does not fit in the techspec or the task file
+- Use **before any PRD exists** to record a repo-wide decision — pass `--scope=repo` (writes to `.dw/adrs/`).
 - Do NOT use for trivial or cheaply-reversible decisions (variable names, import order)
 - Do NOT use to record bugs or incidents (use `/dw-bugfix` or operational notes)
 
+<critical>Offer or create an ADR ONLY when all three criteria hold: (1) **hard to reverse**, (2) **surprising without context**, and (3) a **genuine trade-off** (a real alternative was considered and chosen against). If any one is missing, skip the ADR — do not turn the ADR log into noise. Creation ALWAYS needs explicit user approval, even when all three hold.</critical>
+
 ## Pipeline Position
-**Predecessor:** any point in the pipeline after `/dw-plan prd` | **Successor:** continue the previous flow (techspec, task, review)
+**Predecessor:** any point (repo-scoped ADRs work even before `/dw-plan prd`) | **Successor:** continue the previous flow (techspec, task, review)
 
 The ADR is **additive**: it does not replace any pipeline stage. Any existing command can invoke `/dw-adr` when a non-trivial decision needs a permanent record.
 
+## Scope (`--scope=repo|prd`)
+
+| Scope | Directory | When |
+|-------|-----------|------|
+| `repo` | `.dw/adrs/adr-NNN.md` | Repo-wide decision, and any decision made **before a PRD exists**. |
+| `prd` | `{{PRD_PATH}}/adrs/adr-NNN.md` | Decision bound to a specific active PRD. |
+
+**Default resolution** when `--scope` is not given (`--scope=` is always authoritative and overrides this):
+
+1. Determine the **candidate active PRDs** (see "Active PRD" below) — PRD directories in `.dw/spec/prd-*/` that are NOT terminal/historical.
+2. Exactly one candidate → default to `prd` (that PRD).
+3. Zero candidates (no PRD exists, or every PRD is terminal) → default to `repo`.
+4. Two or more candidates with no disambiguating signal → **ask** which PRD (or `repo`); never guess.
+
+### Active PRD (operational definition)
+
+Distinguish an **active** PRD from a **historical/terminal** one deterministically and conservatively, using evidence already in the repo — in this precedence:
+
+1. **Explicit target** — a PRD named in the request or passed as `{{PRD_PATH}}`. Wins outright.
+2. **Active session** — the PRD referenced by `.dw/STATE.md` (the current working spec), when present.
+3. **Current branch** — a `feat/prd-<slug>` checkout points at `prd-<slug>`.
+
+A PRD directory is **terminal/historical** (excluded from candidates) when its `prd.md` frontmatter/status marks it shipped, merged, delivered, done, archived, superseded, or cancelled. When none of signals 1–3 disambiguate and more than one non-terminal PRD remains, **ask** — do not guess. This reads only what the repo already records; it never invents state, a status field, or a migration.
+
+Numbering (`NNN`) is sequential **within the chosen scope's** ADR directory — repo ADRs and per-PRD ADRs have independent counters.
+
 ## Input Variables
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to the active PRD folder | `.dw/spec/prd-my-feature` |
+| `{{SCOPE}}` | `repo` or `prd` (optional; resolved by default rules above) | `repo` |
+| `{{PRD_PATH}}` | Path to the active PRD folder (only for `scope=prd`) | `.dw/spec/prd-my-feature` |
 | `{{TITLE}}` | Short imperative title of the decision | "Use PostgreSQL instead of MongoDB" |
 
-If `{{PRD_PATH}}` is not provided, ask the user which PRD is active (read `.dw/spec/` and list). If `{{TITLE}}` is not provided, ask.
+If `{{SCOPE}}` is not provided, resolve it per the Scope section (unique PRD → `prd`; no PRD → `repo`; multiple PRDs → ask). For `scope=prd`, if `{{PRD_PATH}}` is not provided, ask the user which PRD is active (read `.dw/spec/` and list). If `{{TITLE}}` is not provided, ask.
 
 ## File Locations
 
-- ADR directory: `{{PRD_PATH}}/adrs/`
-- New file: `{{PRD_PATH}}/adrs/adr-NNN.md` (NNN zero-padded to 3 digits)
+- **`scope=repo`** → directory `.dw/adrs/`, new file `.dw/adrs/adr-NNN.md`.
+- **`scope=prd`** → directory `{{PRD_PATH}}/adrs/`, new file `{{PRD_PATH}}/adrs/adr-NNN.md`.
+- NNN zero-padded to 3 digits, sequential within the chosen scope's directory.
 - Template: `.dw/templates/adr-template.md`
 
 ## Workflow
 
+### 0. Resolve scope
+- Determine `scope` from `--scope=` or the default resolution (unique active PRD → `prd`; no PRD → `repo`; ambiguous multiple PRDs → ask). Set the target ADR directory accordingly (`.dw/adrs/` for repo, `{{PRD_PATH}}/adrs/` for prd).
+- Confirm the three-criterion gate holds (hard to reverse + surprising + genuine trade-off) and get explicit user approval before writing.
+
 ### 1. Discover the next number
-- List files in `{{PRD_PATH}}/adrs/` (create the directory if missing)
+- List files in the target ADR directory (create it if missing)
 - Next number is `max(existing) + 1`, or `1` if empty
 
 ### 2. Gather context (minimum questions)
@@ -52,8 +87,9 @@ id: NNN
 status: Proposed | Accepted | Deprecated | Superseded
 title: [ADR title]
 date: YYYY-MM-DD
-prd: [PRD slug]
-schema_version: "1.0"
+scope: repo | prd
+prd: [PRD slug for scope=prd, or "n/a" for scope=repo]
+schema_version: "1.1"
 ---
 
 # ADR-NNN: [Title]
@@ -86,11 +122,13 @@ schema_version: "1.0"
 
 ### 4. Update cross-references
 
-If the ADR is created **during** a PRD execution, add a line to the "Related ADRs" section of related artifacts:
+If the ADR is created with **`scope=prd`** (during a PRD execution), add a line to the "Related ADRs" section of related artifacts:
 - `prd.md`, `techspec.md`, or `[N]_task.md`, matching the decision's scope
 
 If the "Related ADRs" section does not exist in the file, add it at the end.
 
+For **`scope=repo`** ADRs there is no owning PRD — set `prd: n/a` in the frontmatter and link related artifacts only when they genuinely apply (e.g. `.dw/constitution.md`, `.dw/rules/`). Repo ADRs are the natural home for decisions taken during a greenfield Grill session before any PRD exists.
+
 ### 5. Report
 
 Present to the user:
@@ -110,7 +148,7 @@ This command is inspired by the ADR pattern in `/tmp/compozy/.agents/skills/cy-c
 
 - Paths are `.dw/spec/<prd>/adrs/` instead of `.compozy/tasks/<name>/adrs/`
 - 4 minimum questions instead of Compozy's longer interactive flow (aligned with the concise style of other dw-* commands)
-- Explicit integration with `schema_version` of v1.0 templates
+- Explicit integration with `schema_version` v1.1 templates (adds `scope`; the PRD link is conditional so repo-scoped ADRs are coherent)
 
 Credit: Compozy project.
 

package/scaffold/en/commands/dw-analyze-project.md

@@ -32,6 +32,7 @@ The rules generated by this command are consumed by:
 <critical>This command ONLY generates documentation. Do NOT modify any project source code.</critical>
 <critical>Read actual source files to verify patterns — do not guess from file names alone.</critical>
 <critical>Include real code examples from the project in the generated rules.</critical>
+<critical>PRESERVE the Grill flow's domain artifacts. `.dw/domain/**` (glossary / context-map / per-context files) is human-curated canonical vocabulary owned by `/dw-brainstorm` grill — this command must NEVER regenerate, merge, or overwrite it. When `.dw/domain/**` exists, READ it and LINK it from `.dw/rules/index.md`; do not copy its terms into the auto-generated `.dw/rules/` files. This command owns `.dw/rules/**`; the Grill flow owns `.dw/domain/**`.</critical>
 
 ## Objective
 
@@ -498,8 +499,11 @@ workspace-root/
 
 - See [{module}]({module}.md) for detailed rules per module
 - See [integrations.md](integrations.md) for inter-project communication (if monorepo)
+- See [domain glossary](../domain/glossary.md) — or [context map](../domain/context-map.md) — for canonical vocabulary (only when `.dw/domain/` exists; owned by Grill, read-only here, never regenerated)
 ```
 
+> When `.dw/domain/**` exists, add the Domain Vocabulary link(s) above to the generated `index.md` and leave the domain files untouched. When it does not exist, omit the link — this command never creates `.dw/domain/**` (only `/dw-brainstorm` grill does, after explicit authorization).
+
 #### 7.2 `.dw/rules/{module}.md` (per module)
 
 ```markdown
@@ -877,6 +881,7 @@ Before declaring the analysis complete, verify:
 - [ ] Step 9 (concerns map) presented candidates, awaited approval, wrote `.dw/rules/concerns.md` (or noted no signals)
 - [ ] Step 10 (design authority) ran for frontend projects: existing authority respected, or `DESIGN.md` generated from real tokens, or curated-defaults bootstrap recommended
 - [ ] Preserved-marker blocks in concerns.md kept verbatim on refresh
+- [ ] `.dw/domain/**` (glossary / context-map) preserved verbatim and linked from index.md when present — never regenerated or overwritten
 - [ ] Topology analysis completed (god nodes, coupling metrics, dependency graph)
 - [ ] Critical nodes table generated with Ca, Ce, instability
 - [ ] Circular dependencies identified and documented

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

@@ -20,8 +20,8 @@ Internal modes (the dispatcher picks 1+):
 
 | Mode | Auto-fires when |
 |------|-----------------|
-| **option-matrix** (always-on default) | Default surface: 3-7 options (conservative / balanced / bold) with `[IMPROVES] / [CONSOLIDATES] / [NEW]` tags. Always runs unless a hard override says otherwise. |
-| **grill** | Vocabulary feels unsettled — user terms differ from `.dw/rules/` / `.dw/constitution.md`, or two synonyms compete in the same conversation, or a contributor proposes a name that clashes with the glossary. |
+| **option-matrix** (default surface) | 3-7 options (conservative / balanced / bold) with `[IMPROVES] / [CONSOLIDATES] / [NEW]` tags. Runs by default **except when Grill is the active phase** — `grill` and `option-matrix` are mutually exclusive in a turn (a hard override or an authorized Grill also skips it). |
+| **grill** (native, stateful — needs explicit authorization) | The plan/PRD or its vocabulary feels unsettled. Signal Reading may **recommend** Grill, but it is a stateful alignment session that writes to `.dw/domain/**` and the one-pager; it starts only on **explicit intent** — `--mode=grill`, a direct phrase like "grill me" / "me questione", or a **yes** to the one-time offer. Mutually exclusive with `option-matrix`. |
 | **prototype** | User asks "is this state model right?" / "what should this look like?" with no clear answer; or the next sensible step is to RUN code, not write words. |
 | **council** | Two or more competing approaches surface with no obvious winner; or consensus forms too quickly (false-consensus signal). |
 | **research** | The question depends on external state-of-the-art ("what's the current best practice for X", multi-source comparisons, regulatory or framework landscape). |
@@ -68,6 +68,8 @@ When available in the project under `./.agents/skills/`, use these skills to enr
 - `dw-ui-discipline`: use when brainstorming involves frontend or UI direction — its hard-gate (scene sentence, surface job) is a generative forcing function during ideation, not just a review check. Also picked up by the **prototype** mode's UI branch.
 - `vercel-react-best-practices`: use when brainstorming React/Next.js architecture or performance trade-offs.
 - `security-review`: use when brainstorming touches auth, data handling, or security-sensitive features.
+- `dw-grilling`: the interview engine of the **grill** mode — a dependency-ordered decision tree, exactly one decision per turn, each with a recommended answer. Internal, loaded by path; never exported.
+- `dw-domain-modeling`: the vocabulary engine of the **grill** mode — canonical glossary in `.dw/domain/**`, fuzzy/overloaded-term challenge, code cross-checks, and the rare-ADR policy. Internal, loaded by path; never exported.
 
 ## Template Reference
 
@@ -92,9 +94,9 @@ Before producing any output, **read the situation**:
 1. Inspect `.dw/spec/prd-*/`, `.dw/rules/`, `.dw/constitution.md`, `.dw/intel/` if they exist. Note the project's current vocabulary and recent PRDs.
 2. Inspect recent git activity (`git log --oneline -20`) to detect ongoing work.
 3. Re-read the user's request against the Auto-Dispatch table at the top of this file. Match signals to modes.
-4. Decide the dispatch: **option-matrix** always runs unless an explicit mode override skips it. Other modes (grill, prototype, council, research, refactor-audit, onepager) fire **additively** when their signals are present.
-5. State the dispatch decision to the user in one short line: e.g., "Dispatching: option-matrix + onepager (PRD is one step away)" or "Dispatching: grill (vocabulary unsettled in current PRD)". Do not bury this — surface it before running.
-6. Then proceed with the modes in this order (when chained): grill → research → option-matrix → council → refactor-audit → prototype → onepager. Skip modes not in the dispatch.
+4. Decide the dispatch: **option-matrix** runs by default unless an explicit mode override skips it OR Grill is the active phase (the two are mutually exclusive). **grill** is never auto-started — if its signals appear, **recommend** it and request one explicit authorization before starting the stateful session or writing any file (a normal brainstorm must not write Grill artifacts just because vocabulary looks unstable). The other modes (prototype, council, research, refactor-audit, onepager) fire **additively** when their signals are present.
+5. State the dispatch decision to the user in one short line: e.g., "Dispatching: option-matrix + onepager (PRD is one step away)" or, for grill, a recommendation needing consent: "Recommending: grill (vocabulary unsettled) — authorize to start the stateful session?". Do not bury this — surface it before running.
+6. Then proceed with the modes in this order (when chained): grill (only if authorized) → research → option-matrix → council → refactor-audit → prototype → onepager. Because grill and option-matrix are mutually exclusive, an authorized Grill runs to alignment first and only **offers** option-matrix as a separate, explicitly announced later phase. Skip modes not in the dispatch.
 
 ### Standard flow (option-matrix mode)
 
@@ -181,7 +183,7 @@ At the end, always leave the user in one of these situations:
 - With the one-pager at `.dw/spec/ideas/<slug>.md` (if **onepager** mode fired)
 - With the research report at `~/Documents/<Topic>_Research_<date>/` (if **research** mode fired)
 - With the refactor plan at `<target>/refactor-plan.md` (if **refactor-audit** mode fired)
-- With sharpened glossary entries in `.dw/rules/` (if **grill** mode fired)
+- With canonical glossary entries in `.dw/domain/**` and an aligned idea one-pager (if **grill** ran with authorization)
 - With a runnable throwaway prototype + verdict template (if **prototype** mode fired)
 
 ## Mode: research (multi-source research)
@@ -331,57 +333,114 @@ Saved to `<target>/refactor-plan.md`:
 - Proposing refactors that aren't tested or testable → high risk, won't ship.
 - Ignoring documented architectural decisions in `.dw/rules/` → flagging intentional design as smell.
 
-## Mode: grill (domain-grilling)
+## Mode: grill (native stateful alignment)
 
-Fires when vocabulary feels unsettled — user terms differ from `.dw/rules/` / `.dw/constitution.md`, two synonyms compete in the same conversation, or a contributor proposes a name that clashes with the glossary. Override: `--mode=grill`. Replaces the option-generation default with an **interview-style stress-test** of the plan/PRD against the project's domain vocabulary. Each round of questions sharpens one piece. Updates `.dw/rules/` (or `.dw/constitution.md`) inline as terms crystallize — never deferred to "after the conversation."
+Grill is a **stateful alignment session** that interviews the plan/PRD to *shared understanding* and persists
+canonical vocabulary to `.dw/domain/**`. It is **not** a normal brainstorm turn: it holds a decision tree across
+turns and it writes files. Because it is stateful and mutating, it starts **only on explicit intent**.
 
-<critical>Ask ONE question at a time. Wait for the answer. Don't dump a list of 5 questions and hope for the best.</critical>
+<critical>Explicit intent to Grill = `--mode=grill`, a direct phrase like "grill me" / "grill this plan", OR a **yes** to the one-time offer below. Automatic Signal Reading may **recommend** Grill, but it MUST request one explicit authorization before starting the session or writing ANY file. A normal brainstorm never writes Grill artifacts just because the vocabulary looks unstable.</critical>
 
-### When to use grill mode
+<critical>`grill` and `option-matrix` are **mutually exclusive** in a turn. Grill converges decisions; it does NOT generate an option matrix or a single final option-matrix verdict — but **every interview question still carries a recommended answer** (with rationale and an alternative/trade-off). "No recommendation" refers only to the option-matrix verdict, never to the per-question recommendation. After alignment, Grill may **offer** option-matrix as a separate, explicitly announced later phase.</critical>
 
-- Before `/dw-plan prd` when the domain feels unsettled or the team uses competing terms.
+<critical>Ask exactly ONE unresolved decision per interaction, then wait. Never dump a list of questions.</critical>
+
+Grill is powered by two internal skills (loaded by path from `./.agents/skills/`, never exported):
+- **`dw-grilling`** — the decision-tree interview engine (dependency ordering, one decision per turn, a
+  recommended answer for every question, facts discovered rather than asked, the shared-understanding gate).
+- **`dw-domain-modeling`** — the vocabulary engine (canonical terms, fuzzy/overloaded-term challenge, code
+  cross-checks, and safe lazy persistence to `.dw/domain/**`).
+
+### When Grill is the right move
+
+- Before `/dw-plan prd` when the domain or the plan feels unsettled or the team uses competing terms.
 - After `/dw-plan prd` when reviewers flag ambiguous language in the PRD.
-- During architectural discussion when "module", "service", "component" are being used interchangeably and you need to pin the canonical term.
-- When a contributor proposes a name that doesn't match the project's existing glossary.
+- When "module", "service", "component" (or two synonyms) are used interchangeably and the canonical term must be pinned.
+- When a proposed name clashes with the existing glossary, or a plan hides unresolved decisions.
+
+When these signals appear during auto-dispatch, **recommend** Grill in one line and offer to start it — e.g.
+*"The plan leaves 4 product decisions open and `Account` is overloaded. Start a Grill session (stateful, writes to
+`.dw/domain/**` and the one-pager)? [yes/no]"*. Start only on an explicit yes.
+
+### The session (after authorization)
 
-### During-session disciplines
+1. **Build the decision tree first.** Before the first question, inspect project facts — current PRDs/TechSpecs,
+   `.dw/rules/`, `.dw/intel/` (via `/dw-intel`), `.dw/constitution.md`, `.dw/domain/**`, and recent git activity —
+   and build a decision tree **ordered by dependencies** (never ask a downstream decision before its blocker).
+2. **Ask exactly one unresolved decision per interaction and wait.** Each question includes: evidence when
+   available (with source), the recommended answer, a short rationale, and a meaningful alternative/trade-off.
+   Follow `dw-grilling` (`references/interview-loop.md`, `references/decision-tree.md`).
+3. **Facts are discovered, decisions are asked.** Look facts up in the repo/rules/intel/docs; put only genuine
+   decisions to the user, and leave the choice to the user.
+4. **Sharpen vocabulary with `dw-domain-modeling`.** Challenge fuzzy/overloaded terms, stress-test with concrete
+   edge-case scenarios, and cross-check each term against the code (surface `file:line` contradictions).
+5. **A resolved answer authorizes the matching update.** Once a decision is resolved, you may persist the
+   corresponding glossary/alignment change (see allowlist). ADR creation still requires a **separate explicit
+   approval** — never auto-create one.
 
-1. **Challenge against the glossary.** Read `.dw/rules/index.md` + per-module `.dw/rules/<module>.md` + `.dw/constitution.md`. Flag terminology conflicts the instant the user uses a term that differs from (or contradicts) what's already documented.
+### Allowed stateful writes (only after authorization + the relevant decision is resolved)
 
-2. **Sharpen fuzzy language.** When the user says "the user thing" or "the order stuff", propose a precise canonical term. Don't pretend you understood — push back.
+- `.dw/domain/**` — the canonical glossary / context-map (via `dw-domain-modeling`).
+- The active `.dw/spec/ideas/<slug>.md` one-pager (extended to schema `1.1`, below).
+- An **explicitly active** PRD/TechSpec — only **after showing the proposed change** and getting agreement.
+- Routed ADR paths via `/dw-adr --scope=repo|prd` (after separate ADR approval).
 
-3. **Discuss concrete scenarios.** Force precision via specific edge cases: "What happens to the Order in state X when event Y arrives during retry Z?" Vague answers go back as further questions.
+**Never edit source code during Grill.** If authorization is absent, keep interviewing and report what you *would*
+persist.
 
-4. **Cross-reference code.** When the user states a behavior, glance at the codebase to confirm it. Surface contradictions: "You said the API returns `OrderId` but `src/api/orders.ts:42` returns `{ order_id, status }`." Don't argue from generalities.
+### Native domain artifacts (not `.dw/rules/`, not root `CONTEXT.md`)
 
-5. **Update `.dw/rules/` inline.** When a term crystallizes, write it into the appropriate rules file in the same conversation turn. Lazy file creation: if the file doesn't exist, create it. Format follows the glossary discipline established by the project (see `.dw/rules/index.md` for shape).
+Canonical vocabulary lives in `.dw/domain/**`, created **lazily** only after a term is resolved and write
+authorization exists:
 
-6. **Skip implementation details in the glossary.** `.dw/rules/` and `.dw/constitution.md` describe vocabulary and principles — not implementation. "Order: a customer's request to purchase one or more items, in one of these states: pending, paid, shipped, delivered, refunded" is fine. "Order: a TypeScript class in `src/orders/`" is implementation leak.
+- Single context → `.dw/domain/glossary.md`.
+- Multiple contexts → `.dw/domain/context-map.md` + `.dw/domain/contexts/<slug>.md`.
+
+A glossary definition is one or two sentences that say what the domain term **is**, lists discouraged synonyms
+(`_Avoid:_`), and excludes implementation details, requirements, scratch notes, and general programming concepts.
+Do **not** store human-curated vocabulary in the auto-generated `.dw/rules/` module files. `/dw-analyze-project`
+reads and links `.dw/domain/**` and must preserve it, never regenerate it.
+
+### Aligned handoff — the idea one-pager (schema `1.1`)
+
+Grill extends `.dw/spec/ideas/<slug>.md` to schema `1.1`, adding: **Resolved Decisions** (each with the recommended
+answer, the user's choice, and the alternative rejected), **Evidence** (facts discovered with sources),
+**Canonical Vocabulary** (links into `.dw/domain/**`), **Remaining Decisions**, and **Alignment State**.
+
+Set `status: aligned` **only when all** of these hold: every dependency branch is resolved, glossary/code
+contradictions are closed, no blocking open decision remains, AND the user **explicitly confirms** shared
+understanding. Otherwise persist a `draft`/`paused` state (with the decision tree and open nodes) and **stop**.
+`/dw-plan` consumes an aligned handoff without re-asking the resolved product decisions.
 
 ### ADR creation discipline
 
-Only propose an ADR via `/dw-adr` when **all three** hold:
+Only offer an ADR (via `/dw-adr --scope=repo|prd`) when **all three** hold — and creation always needs a separate
+explicit user approval (`dw-domain-modeling/references/adr-policy.md`):
 
 | Criterion | Test |
 |-----------|------|
-| **Hard to reverse** | If we change this in 6 months, does it cost >1 week of work? |
+| **Hard to reverse** | If we change this in 6 months, does it cost meaningfully more than a day? |
 | **Surprising without context** | Would a new contributor reasonably reach a different decision? |
 | **Genuine trade-off** | Was there a real alternative we considered and chose against? |
 
-If any is missing, skip the ADR. Don't ADR every casual decision — that turns the ADR folder into noise.
+Scope routing: `repo` → `.dw/adrs/adr-NNN.md` (works before any PRD); `prd` → `.dw/spec/<prd>/adrs/adr-NNN.md`.
+If any criterion is missing, skip the ADR — don't turn the ADR log into noise.
 
 ### Output
 
 grill mode produces:
-- **Updated `.dw/rules/<module>.md`** or `.dw/constitution.md` with crystallized terms.
-- **Updated PRD / TechSpec** if grilling happens mid-plan (terms in the artifact are aligned with the glossary).
-- **Optional `.dw/spec/<prd>/adrs/adr-NNN.md`** if criteria above hold.
-- **NO** option matrix or recommendation (that's option-matrix mode; grill is purely about sharpening). If the dispatcher chained grill+option-matrix, the option matrix runs in a separate phase.
+- **Canonical vocabulary in `.dw/domain/**`** (glossary, or context-map + per-context files) for resolved terms.
+- **An extended one-pager** at `.dw/spec/ideas/<slug>.md` (schema `1.1`) — `aligned` only after explicit confirmation, otherwise `draft`/`paused`.
+- **Updated PRD / TechSpec** only if explicitly active and the change was shown first.
+- **Optional routed ADR** via `/dw-adr --scope=…` if the three criteria hold and the user approves.
+- **NO** option matrix and no single final option-matrix verdict — but every interview question still carries a recommended answer (option-matrix is a separate later phase if offered and accepted).
 
 ### When the discipline bends
 
-- **Greenfield project with no `.dw/rules/`**: grill anyway; the conversation produces the FIRST entries in `.dw/rules/index.md`. That's the value.
-- **Cosmetic terminology disagreements** ("should we call it `userId` or `user_id`?"): skip grill mode; use a coding-conventions ADR or `.dw/rules/index.md` Naming section.
+- **Greenfield project with no `.dw/domain/`**: grill anyway (once authorized); the session produces the FIRST
+  entries in `.dw/domain/glossary.md`. That's the value. ADRs before any PRD route to `--scope=repo`.
+- **Cosmetic terminology disagreements** ("should we call it `userId` or `user_id`?"): skip grill; use a
+  coding-conventions note in `.dw/rules/index.md` Naming — a naming style is not a domain term.
 
 ## Mode: prototype (throwaway prototype)
 
@@ -445,8 +504,20 @@ The codebase-grounded idea refinement pattern is inspired by [`addyosmani/agent-
 - Output at `.dw/spec/ideas/<slug>.md` (sibling of `prd-<slug>/`) instead of `docs/ideas/` — preserves dev-workflow path conventions.
 - Integration with the existing pipeline: `/dw-plan prd` accepts the one-pager as input, reducing clarification questions.
 
-The **grill** and **prototype** modes are adapted from [`mattpocock/skills/grill-with-docs`](https://github.com/mattpocock/skills/tree/main/grill-with-docs) and [`mattpocock/skills/prototype`](https://github.com/mattpocock/skills/tree/main/prototype) (Matt Pocock, MIT). dev-workflow adaptation: integrated as INTERNAL auto-dispatched modes rather than separate skills, paths rebased on `.dw/rules/` + `.dw/spec/<prd>/`, ADR creation gated on the 3-criteria test (hard-to-reverse + surprising + genuine trade-off).
-
-Credit: Addy Osmani (idea-refine) and Matt Pocock (grill-with-docs, prototype).
+The **grill** mode is a native reimplementation of Matt Pocock's grilling discipline (MIT), drawing on three
+upstream skills: [`skills/engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md)
+(interview that produces docs as it goes), [`skills/productivity/grilling`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md)
+(one-decision-at-a-time interview with a recommended answer, facts looked up not asked, shared-understanding gate),
+and [`skills/engineering/domain-modeling`](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md)
+(canonical glossary, fuzzy-term challenge, rare ADRs). dev-workflow adaptations: behavior is reimplemented in this
+repo's voice (no upstream prose copied) and extracted into two **internal, non-exported** skills — `dw-grilling`
+and `dw-domain-modeling` — invoked by this mode; the glossary lives in **`.dw/domain/**`** (not upstream's root
+`CONTEXT.md` and not our auto-generated `.dw/rules/`); Grill is a **stateful session that requires one explicit
+authorization** before writing; alignment produces an idea one-pager at schema `1.1` consumed by `/dw-plan`; and
+ADR creation is gated on the 3-criteria test and routed via `/dw-adr --scope=repo|prd`. The **prototype** mode is
+adapted from [`mattpocock/skills/prototype`](https://github.com/mattpocock/skills) (MIT) as an internal
+auto-dispatched mode.
+
+Credit: Addy Osmani (idea-refine) and Matt Pocock (grill-with-docs, grilling, domain-modeling, prototype).
 
 </system_instructions>

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-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]