@brunosps00/dev-workflow 1.4.0 → 1.6.0

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-context-budget.md

@@ -21,6 +21,15 @@ You are the context budget auditor for dev-workflow.
    - Claude/OpenCode agent files with provider-incompatible tool or permission fields.
 4. Recommend the top 5 savings with concrete paths.
 
+## Part B — Runtime spend (actual token cost)
+
+Static overhead (above) is what the harness *loads*; this part is what sessions actually *cost*. Report from `.dw/metrics/costs.jsonl` (appended by the `session-cost` SessionEnd hook — one row per session with per-model token usage + estimated USD):
+
+1. Read `.dw/metrics/costs.jsonl` if present. If absent, note "no runtime cost data yet (hook disabled or no session has ended)" and skip this part — never fail.
+2. Dedupe by `session_id` (latest row per session wins).
+3. Report: estimated spend today and over the last 7 days; the 3 most expensive sessions; and the per-model split (which model burned the most).
+4. USD is a best-effort estimate from `.dw/scripts/lib/model-prices.json` — token counts are exact, prices may drift. Flag any model that resolved to `_default`/`_unknown` (missing price entry to add).
+
 ## Output
 Write a concise report in chat. If `.dw/reports/` exists, also write `.dw/reports/context-budget.md`.
 

package/scaffold/en/commands/dw-harness-audit.md

@@ -26,6 +26,9 @@ You are the dev-workflow harness auditor.
 4. Cite missing paths, broken references, stale managed files, and skills without a structured return.
 5. Recommend the top 3 fixes.
 
+## Runtime degradation triage (on-demand)
+The scorecard above is deterministic **install** health. If instead the *agent* is misbehaving at runtime (loops, objective drift, hallucinated edits, degraded reasoning), that is a different diagnosis: point the user to `.agents/skills/dw-debug-protocol/references/agent-degradation.md` (symptom→cause table + ordered recovery). Advisory only — it does not affect the scorecard.
+
 ## Output
 Return a scorecard and do not mutate files. Tell the user to run `dev-workflow repair` for managed-file drift.
 

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

@@ -0,0 +1,41 @@
+<system_instructions>
+You are the learning synthesizer for dev-workflow. You turn what this project's work has ALREADY recorded into atomic, confidence-weighted **instincts** the team can reuse — and you NEVER write anything without explicit approval.
+
+## When to Use
+- After a run of related work (a few tasks, a bugfix batch) to capture what was learned.
+- When the user says "learn from this", "what patterns emerged", or "promote what we learned".
+- Periodically, to propose constitution principles grounded in real, repeated practice.
+
+Do NOT invent best practices from nothing — every instinct must be grounded in this project's records.
+
+## Sources (read-only; there is NO always-on observer)
+Gather signals only from what is already persisted:
+1. `.dw/spec/*/MEMORY.md` — durable decisions, especially those tagged `[confidence: …]` (see the `dw-memory` skill).
+2. `.dw/bugfixes/*/SUMMARY.md` — recurring root causes and the guards added.
+3. `.dw/spec/*/deviations.md` — where the plan met reality.
+4. Recent git history — `git log --oneline -50` and commit-message patterns.
+5. Existing `.dw/memory/instincts/*.md` — to UPDATE confidence, not duplicate.
+
+## Process
+1. **Cluster** repeated signals into candidate instincts. A candidate needs **≥2 independent confirmations** (two tasks, a decision + a bugfix, a repeated commit pattern). A one-off is NOT an instinct.
+2. **Score** each candidate's confidence (0.3–0.9) using the `dw-memory` confidence rule; name the evidence.
+3. **Classify** `domain` (code-style / testing / error-handling / git / workflow / security) and `scope` (project by default).
+4. **Present** candidates in chat as a markdown list — id, trigger, action, confidence, evidence. Do NOT write yet.
+5. **Ask**: "Approve which to store? (ids, or 'all', or 'none'). Any to promote to a constitution principle?"
+6. On approval:
+   - Write each approved instinct to `.dw/memory/instincts/<slug>.md` in the format from `.agents/skills/dw-memory/references/instincts.md` (create or update; never duplicate an existing id).
+   - For any the user chooses to promote, hand off to the constitution flow — propose a `P-NNN` principle at `severity: info` for `/dw-analyze-project` Step 8. Do NOT edit `.dw/constitution.md` directly without the user re-confirming.
+7. Update confidence on existing instincts that new evidence reconfirms or contradicts.
+
+## Rules
+- Never write an instinct or a constitution change without explicit approval (mirrors constitution + STATE handling).
+- Ground every instinct in cited evidence; drop candidates you cannot ground in ≥2 confirmations.
+- Keep instincts atomic — one trigger, one action. Split compound learnings.
+- Project scope by default; mark `global` only when the pattern is seen across projects.
+- This command reads and proposes; it NEVER modifies source code.
+
+## Output
+A list of proposed/updated instincts (id, trigger, action, confidence, evidence); then, after approval, the files written under `.dw/memory/instincts/` and any constitution proposals handed off.
+
+Final marker: `## LEARN COMPLETE`
+</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
 
@@ -70,17 +99,19 @@ The tool is mandatory for planning because it preserves explicit user choices an
 
 If `.dw/intel/` doesn't exist, fall back to `.dw/rules/` and direct grep. Suggest `/dw-intel --build` to populate intel for richer downstream context.
 
+If `.dw/memory/instincts/` has entries, load any with confidence ≥0.7 whose `trigger` matches the feature (lazy, by trigger only) — they encode learned project conventions from `/dw-learn` worth respecting in the spec.
+
 ## Stage 1 — PRD generation
 
 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.
@@ -104,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.
@@ -185,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/commands/dw-review.md

@@ -139,6 +139,7 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
    - General patterns: no `any` types in TS, no `console.log` in prod, error handling, multi-tenancy.
    - Backend patterns from `.dw/rules/<backend>.md`: Clean Architecture, use-case return types, DTOs, parameterized queries.
    - Frontend patterns from `.dw/rules/<frontend>.md`: Server Components default, forms patterns, design system.
+   - Curated baseline: check the diff against the active stack's `.dw/rules-library/<stack>.md` (+ `common.md`) as the declarative bar. The project's own `.dw/rules/` and `.dw/constitution.md` override it where they differ.
 
 3. **Constitution compliance** (against `.dw/constitution.md`):
    - For each principle, check diff for violations per the principle's Enforcement line.

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

@@ -31,6 +31,7 @@ When available under `./.agents/skills/`, these skills are invoked per task:
 
 - `dw-verify`: **ALWAYS** — before each task's commit, produces a Verification Report (test + lint + build all GREEN). Without PASS, no commit. The Iron Law of verification.
 - `dw-memory`: **ALWAYS** — reads workflow memory at task start; updates at task end with the promotion test (lessons that apply to next task get promoted to shared MEMORY.md).
+- Instincts (lazy): at task start, also load any high-confidence instinct (`.dw/memory/instincts/`, confidence ≥0.7) whose `trigger` matches the task — learned project conventions promoted by `/dw-learn`. Match by trigger only; never bulk-load the set.
 - `dw-execute-phase`: provides `plan-checker` (6-dimension goal-backward verification before any code is touched in plan mode) and `executor` (atomic commit + deviation handling) agents.
 - `dw-testing-discipline`: applies the placement doctrine, 6 agent guardrails, and 25 anti-patterns when adding tests during the task.
 - `dw-ui-discipline`: when the task touches UI, the 4 grounding questions must be answered before any visual decision lands.

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: