@brunosps00/dev-workflow 2.0.0 → 2.1.0

package/.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "brunosps00-dev-workflow",
+  "description": "À-la-carte dev-workflow skills for focused agent work: minimalism, search-first research, verification, security review, and code quality.",
   "owner": {
     "name": "Bruno Santos"
   },

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": "2.0.0",
+  "version": "2.1.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,110 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > those versions were released, so they are summaries of what shipped, not
 > contemporaneous release notes. `git log` remains the authoritative record.
 
+## [2.1.0] — 2026-08-04
+
+Release driven by a skill-by-skill analysis of [mattpocock/skills](https://github.com/mattpocock/skills),
+whose philosophy is the opposite of this project's: small composable skills anchored
+to an issue tracker, against an opinionated pipeline with durable state in `.dw/`.
+What follows is the transferable technique, adapted — plus five defects of our own
+that the comparison exposed. What was deliberately **not** taken, and why, is
+recorded in [docs/skills-ecosystem-comparison.md](docs/skills-ecosystem-comparison.md).
+
+### Added
+
+- **`/dw-triage` — the intake boundary the pipeline never had.** External bug
+  reports, feature requests, and PRs previously had to be hand-converted into a
+  bugfix or a PRD before anything could touch them. One category (`bug` |
+  `enhancement`) and one state (`needs-triage` → `needs-info` | `ready-for-work` |
+  `needs-human` | `wontfix`), persisted in `.dw/triage/NNN-<slug>.md`, routing to
+  `/dw-bugfix`, `/dw-plan prd`, or `/dw-brainstorm --mode=grill`. Two mechanisms
+  carry the weight: **claims are verified before a brief is written** (bugs
+  reproduced from the reporter's steps, PR diffs checked against what they claim),
+  and `.dw/out-of-scope/<concept>.md` remembers rejections **by domain concept**
+  rather than by the request's wording, so a request refused in January is not
+  re-litigated in March. A `wontfix` for "already implemented" deliberately does
+  not write there — that store is memory of refusal, not of delivery.
+  It is local-first in the strict sense: `.dw/` is the source of truth and the
+  command works with no network and no `gh`. GitHub read via `gh` is optional
+  enrichment, and writing back is opt-in per write, never a side effect of triage.
+- **`### Decision Map` in the idea one-pager.** `dw-grilling` already instructed
+  the agent to record its decision tree so a session could resume — with nowhere
+  to record it, so the graph was rebuilt from scratch every time and what the last
+  session knew was still *undecided* was lost. Each node now carries a `State`
+  (`resolved` | `open-ready` | `open-blocked`), a `Depends on:` field reusing the
+  form `tasks.md` already uses, and an explicit `**Frontier:**` line so the next
+  session reads what is decidable now without recomputing the graph. `#### Decision
+  Fog` records what is known to be undecided but not yet sharp enough to phrase as
+  a decision. Grill resumes from the map instead of re-deriving it, never re-asks a
+  `resolved` node, and the alignment gate now also requires `Frontier: none`.
+  Schema stays at `1.1`: the section is optional, so existing one-pagers stay valid.
+- **`/dw-review --since <ref>`** — ad-hoc review against a verified comparison
+  point. Resolves the ref with `git rev-parse --verify`, aborts with an actionable
+  message if it does not resolve, aborts if the diff is empty rather than reviewing
+  nothing, and records the exact diff and commit commands in every report so the
+  review is reproducible. Three-dot, matching PR review semantics. The default
+  PRD/bugfix flow is unchanged.
+- **Test-first loop in `dw-testing-discipline`** (`references/tdd-loop.md`):
+  confirm the public seam with the user, one red test per vertical slice, run it
+  and **observe** the expected red, minimum green, next slice. Refactor is outside
+  the cycle. `/dw-run` uses it only on an explicit request — never by default.
+- **Red-capable feedback contract in `dw-debug-protocol`.** Reproduction was
+  specified as an outcome, not a procedure. A loop must now be single,
+  deterministic, fast, agent-runnable, and **proven red now** — "it should fail"
+  does not count — before any theorizing, with a repertoire of loop types and a
+  HITL template for when the loop needs credentials, hardware, or a human action.
+  `/dw-bugfix` records the loop command before and after the fix. Trivial bugs stay
+  exempt; the exemption ends when a first fix fails or the bug spans layers.
+- **Seam dependency categories and Design It Twice** in
+  `dw-simplification/references/deep-modules.md`. Classifying what a seam isolates
+  (in-process, local-substitutable, remote owned, true external) derives the test
+  strategy instead of reflexively mocking or running everything; interface findings
+  require three-plus proposals under distinct constraints before one is recommended.
+  Loaded from `/dw-refactor` only for interface/seam findings, so simple refactors
+  stay cheap.
+- **`AGENTS.md` and `CLAUDE.md`** at the repo root. A project whose product is
+  agent instructions had none for maintaining itself; the invariants existed only
+  as tests that fail after the mistake.
+
+### Fixed
+
+- **`git restore .` bypassed the git guardrails entirely.** `git checkout .` was
+  blocked while `git restore .`, `git restore -- .`, `git restore --staged
+  --worktree .` and `git restore --source=<ref> .` — which discard exactly the same
+  uncommitted work — passed through. The hook had **no test at all**, which is why
+  the hole survived. It now has one that invokes the script for real over stdin,
+  including a case that runs it from a directory whose name contains a space.
+- **`Depends on:` was parsed by the wave executor but existed in no template.**
+  `/dw-plan` told each task to declare its dependencies and
+  `dw-execute-phase/references/wave-coordination.md` built the parallel graph by
+  topological sort from that field — while `tasks-template.md` had no column for it
+  and `task-template.md` no field. The graph rested on data nothing produced. The
+  field now has a home in both, and `wave-coordination.md` uses the `1.0` task IDs
+  the pipeline actually writes instead of the `01` form its example carried.
+- **`/dw-brainstorm --research` wrote outside the repo.** Reports went to
+  `~/Documents/<Topic>_Research_<date>/`, so `/dw-plan` and `/dw-intel` could not
+  consume research the pipeline itself produced. They now land under the active
+  spec, or under `.dw/spec/research/` when standalone.
+- **The marketplace manifest had no description**, which `claude plugin validate`
+  warns about and `npm run validate` did not catch. The field was added to the
+  generator in `build-plugin.js`, not only to the checked-in JSON, so it survives
+  the next `npm run build:plugin`.
+- **The PT `/dw-refactor` searched for a section that did not exist.** It told the
+  agent to locate `Modo: refactor-audit (catalogo de code smells + deep-modules)`
+  while the heading in `dw-brainstorm` reads `catálogo`, accented. The lookup never
+  matched; the EN pair matches exactly and always worked. Surfaced by the
+  accentuation pass below.
+
+### Changed
+
+- **24 PT-BR scaffold files were written with no diacritics at all** ("Voce e a
+  entrada", "secao", "nao") while the other half of the scaffold was correctly
+  accented, making it impossible to tell a new mistake from old debt. All 24 are
+  now accented. Diacritics only, verified mechanically: both sides normalized
+  (Unicode NFKD, combining marks dropped) and compared byte for byte, so any
+  content change would have failed the check. Literal strings the commands search
+  for, code blocks, flags, paths, and English technical terms were left untouched.
+
 ## [2.0.0] — 2026-08-02
 
 First release after a full security audit of the compose recipes. Two options were

package/README.md

@@ -42,14 +42,15 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v2.0.0 ships **38 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v2.1.0 ships **39 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
-### Tier 1 — Gateway (3)
+### Tier 1 — Gateway (4)
 
 | Command | When |
 |---------|------|
 | **`/dw-autopilot "wish"`** | Default entry point in two invocations. First run completes PRD → TechSpec → Tasks and stops. Second run resumes from state, executes `/dw-goal --from-autopilot <slug>` for Run → Review → QA/Fix → Review, then Security Gate → Commit → PR. |
 | **`/dw-bugfix "description"`** | A bug report or pasted error. Triages bug-vs-feature-vs-scope, surgical fix or routes to a PRD. |
+| **`/dw-triage [item]`** | An external bug report, feature request, or PR. Checks whether it already exists and whether it was rejected before, verifies the claim, then routes to `/dw-bugfix`, `/dw-plan prd`, or `/dw-brainstorm --mode=grill`. Local-first in `.dw/triage/`; works with no network and no `gh`. |
 | **`/dw-help [keyword]`** | Discover commands. Pass a keyword for shortcuts; `--advanced` reveals internal commands. |
 
 ### Tier 2 — Pipeline granular (10)
@@ -62,19 +63,20 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-brainstorm "idea"`** | Refine a concrete idea before PRD. Flags: `--onepager` (durable artifact), `--council` (multi-advisor debate), `--research` (multi-source cited research). |
 | **`/dw-plan "feature"`** | PRD → TechSpec → Tasks sequentially with checkpoints. Stages: `prd`, `techspec`, `tasks`. Mandatory clarification questions, source-grounding, constitution gate, final consistency check. |
 | **`/dw-run [task-id]`** | Execute tasks. Default: all pending in dependency order with wave-based parallel dispatch. Single-task: pass an ID. `--resume` continues an interrupted plan. |
-| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`). |
+| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`), `--since <ref>` (ad-hoc review from a verified comparison point). |
 | **`/dw-qa`** | Mode-aware QA. Auto-detects UI vs API. Flags: `--fix` (iterative QA + fix-retest loop), `--api`, `--ai` (AI eval against reference dataset), `--uat` (human-in-the-loop walkthrough), `--bugfix <slug>` (QA a bugfix). |
 | **`/dw-pause`** | Consolidate the current session's mental state into `.dw/STATE.md` (Decisions, Blockers, Todos, Deferred, Lessons, Open Loops). Used before long breaks or context-window compactions. |
 | **`/dw-resume`** | Read `.dw/STATE.md`, present a TLDR of where work left off, and suggest the next `dw-*` command. Never auto-executes. |
 | **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
 | **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Tier 3 — Specialty (12)
+### Tier 3 — Specialty (13)
 
 | Command | What |
 |---------|------|
 | **`/dw-analyze-project`** | Scans the repo, writes `.dw/rules/` (per-module conventions, anti-patterns, naming). Step 8 offers `.dw/constitution.md`; Step 9 writes `.dw/rules/concerns.md`; Step 10 can synthesize a frontend `DESIGN.md` from existing tokens. Run once per project; refresh after major refactors. |
 | **`/dw-redesign-ui "target"`** | Audits a frontend page, runs the `dw-ui-discipline` 4-question grounding, proposes 2-3 design directions, ships the redesign. WCAG 2.2 AA accessibility floor is non-negotiable; UI diffs can also run the deterministic impeccable slop detector. |
+| **`/dw-open-design "brief"`** | Generates, iterates, or refactors headless Open Design HTML prototypes through the `od` CLI. Refines the brief before dispatch, runs with an explicit `--agent codex\|claude`, captures JSONL audit logs, and stops for a dual ≥9 visual gate. `--refactor` works from a live URL or from screenshots. |
 | **`/dw-refactor "target"`** | Audits a target for refactor opportunities using Fowler smells, `dw-simplification`, deep-modules analysis, and behavior-preserving test gates. This is the explicit route for code-health and tech-debt work. |
 | **`/dw-functional-doc`** | Maps screens + user flows into a functional doc, validated end-to-end with Playwright. Uses the WSL-resilient browser resolver and can capture guided functional video evidence. |
 | **`/dw-context-budget`** | Audits context overhead from commands, skills, agents, instruction files, and MCPs. |

package/lib/build-plugin.js

@@ -22,6 +22,8 @@ const { readSkillRegistry } = require('./skill-registry');
 
 const REPO_ROOT = path.join(__dirname, '..');
 const PLUGIN_DIR = path.join(REPO_ROOT, '.claude-plugin');
+const MARKETPLACE_DESCRIPTION =
+  'À-la-carte dev-workflow skills for focused agent work: minimalism, search-first research, verification, security review, and code quality.';
 
 function buildManifests() {
   const registry = readSkillRegistry();
@@ -46,6 +48,7 @@ function buildManifests() {
 
   const marketplace = {
     name: 'brunosps00-dev-workflow',
+    description: MARKETPLACE_DESCRIPTION,
     owner: author,
     plugins: [
       {
@@ -72,7 +75,7 @@ function run() {
   for (const name of exportable) console.log(`  - ${name}`);
 }
 
-module.exports = { buildManifests, run };
+module.exports = { buildManifests, run, MARKETPLACE_DESCRIPTION };
 
 if (require.main === module) {
   run();

package/lib/constants.js

@@ -30,13 +30,14 @@ const COMMANDS = {
     { name: 'dw-redesign-ui', description: 'Audits a frontend page, proposes design directions you choose from, then ships the redesign.' },
     { name: 'dw-refactor', description: 'Audits a target for refactor opportunities using the refactor-audit protocol, Fowler smells, deep-modules analysis, and behavior-preserving test gates.' },
     { name: 'dw-resume', description: 'Trigger when user says "resume work", "where did we stop?", or starts a session in a project with an existing .dw/STATE.md. Reads STATE.md, presents a TLDR, and suggests the next dw-* command.' },
-    { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug>.' },
+    { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
     { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block. Auto-invoked by /dw-review and /dw-generate-pr, explicit phase in /dw-autopilot, and runnable standalone.' },
     { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
     { name: 'dw-subtask-start', userInvoked: true, description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
+    { name: 'dw-triage', description: 'Local-first intake for external bug reports, feature requests, and PRs. Persists .dw/triage/ state, checks redundancy and prior rejections, verifies claims, then routes to /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, or no work.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
@@ -70,13 +71,14 @@ const COMMANDS = {
     { name: 'dw-redesign-ui', description: 'Audita uma pagina frontend, propoe direcoes de design que voce escolhe, e entrega o redesign.' },
     { name: 'dw-refactor', description: 'Audita um target por oportunidades de refactor usando o protocolo refactor-audit, smells Fowler, deep-modules e gates de teste preservando comportamento.' },
     { name: 'dw-resume', description: 'Trigger quando usuario diz "retoma", "onde paramos?" ou comeca sessao num projeto com .dw/STATE.md existente. Le STATE.md, apresenta TLDR e sugere proximo comando dw-*.' },
-    { name: 'dw-review', description: 'Trigger quando usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug>.' },
+    { name: 'dw-review', description: 'Trigger quando usuário pede pra revisar código, checar qualidade ou validar prontidão pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
     { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH bloqueiam. Auto-invocado por /dw-review e /dw-generate-pr, fase explicita no /dw-autopilot, e executavel standalone.' },
     { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
     { name: 'dw-subtask-start', userInvoked: true, description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
+    { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos. Persiste estado em .dw/triage/, checa redundância e rejeições anteriores, verifica alegações, e então roteia para /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, ou nenhum trabalho.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };

package/lib/validate.js

@@ -23,8 +23,10 @@ function run() {
 
   // Plugin manifest drift check.
   const { plugin, marketplace } = buildManifests();
+  checkMarketplaceDescription(marketplace, issues);
   checkManifestDrift('.claude-plugin/plugin.json', plugin, issues);
   checkManifestDrift('.claude-plugin/marketplace.json', marketplace, issues);
+  checkMarketplaceFileDescription('.claude-plugin/marketplace.json', issues);
 
   console.log('dev-workflow validate\n');
   if (warnings.length) {
@@ -55,6 +57,25 @@ function checkManifestDrift(relPath, expected, issues) {
   }
 }
 
+function checkMarketplaceDescription(marketplace, issues) {
+  if (!marketplace || typeof marketplace.description !== 'string' || !marketplace.description.trim()) {
+    issues.push('Generated marketplace manifest must include a root-level description.');
+  }
+}
+
+function checkMarketplaceFileDescription(relPath, issues) {
+  const file = path.join(__dirname, '..', relPath);
+  if (!fs.existsSync(file)) return;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (typeof manifest.description !== 'string' || !manifest.description.trim()) {
+      issues.push(`${relPath} must include a root-level description.`);
+    }
+  } catch {
+    issues.push(`${relPath} is not valid JSON.`);
+  }
+}
+
 module.exports = { run };
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "2.0.0",
+  "version": "2.1.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"

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

@@ -181,7 +181,7 @@ At the end, always leave the user in one of these situations:
 - With better questions to decide
 - With a next workspace command to follow
 - 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 research report at `.dw/spec/<prd-slug>/research/<topic-slug>-<YYYYMMDD>/research.md` when a PRD is active, `.dw/spec/ideas/<idea-slug>-research-<YYYYMMDD>/research.md` when an idea one-pager is active, or `.dw/spec/research/<topic-slug>-<YYYYMMDD>/research.md` for standalone research (if **research** mode fired)
 - With the refactor plan at `<target>/refactor-plan.md` (if **refactor-audit** 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)
@@ -237,7 +237,7 @@ Complementary skill **`dw-source-grounding`**: **ALWAYS** — apply Detect → F
 
 ### Output
 
-Saved to `~/Documents/<Topic>_Research_<YYYYMMDD>/`. Mandatory sections:
+Save `research.md` inside the repo: `.dw/spec/<prd-slug>/research/<topic-slug>-<YYYYMMDD>/research.md` when a PRD is active, `.dw/spec/ideas/<idea-slug>-research-<YYYYMMDD>/research.md` when an idea one-pager is active, or `.dw/spec/research/<topic-slug>-<YYYYMMDD>/research.md` for standalone research. Mandatory sections:
 1. Executive Summary (200-400 words)
 2. Introduction (scope, methodology, assumptions)
 3. Main Analysis (4-8 findings, 600-2000 words each, all cited)
@@ -364,9 +364,12 @@ When these signals appear during auto-dispatch, **recommend** Grill in one line
 
 ### The session (after authorization)
 
-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).
+1. **Resume or build the decision tree first.** Before the first question, read the active one-pager for an
+   existing **Decision Map**. If present, resume from its `Depends on:` graph, `State` values, explicit
+   **Frontier**, and `Decision Fog`; do not re-ask nodes already `resolved`. If no map exists, 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`).
@@ -403,9 +406,10 @@ 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**.
+Grill extends `.dw/spec/ideas/<slug>.md` to schema `1.1`, adding: **Decision Map** (nodes, `Depends on:`, `State`,
+explicit **Frontier**, and `Decision Fog` for unclear future nodes), **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

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

@@ -38,7 +38,7 @@
 
     When available in the project at `./.agents/skills/`, use these skills as contextual support without replacing this command:
 
-    - `dw-debug-protocol`: **ALWAYS** — runs the bug through the six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Stop-the-line discipline; root-cause over symptom; regression test committed in the same atomic commit. Non-reproducible bugs follow the instrument-first sub-protocol — no guess fixes without explicit acknowledgement.
+    - `dw-debug-protocol`: **ALWAYS** — runs the bug through the six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Stop-the-line discipline; root-cause over symptom; regression test committed in the same atomic commit. For non-trivial bugs, or after a first fix fails, Step 1 must establish a red-capable feedback loop before theorizing. Non-reproducible bugs follow the instrument-first sub-protocol — no guess fixes without explicit acknowledgement.
     - `dw-verify`: **ALWAYS** — in Direct mode, invoked before committing the fix. The VERIFICATION REPORT must show the original bug symptom no longer reproduces (not just that tests pass).
     - `vercel-react-best-practices`: use when the bug affects React/Next.js and there is suspicion of render, hydration, fetching, waterfall, bundle, or re-render issues
     - `dw-testing-discipline`: use when the fix requires a reproducible E2E/retest flow in a web app — `references/playwright-recipes.md` for recipes, core rules + 6 agent guardrails for any test the fix adds, flaky-discipline if the bug surfaces intermittently.
@@ -214,6 +214,7 @@
     - Stack traces
     - Recently modified files
     - If the bug is UI-related or depends on browser flow, supplement collection with `dw-testing-discipline` (playwright-recipes + three-workflow-patterns to pick the right verification mode)
+    - For non-trivial bugs, or when the first fix attempt failed, build the `dw-debug-protocol` red-capable feedback loop before proposing a cause: one loop command/artifact, deterministic enough, fast, agent-runnable, and observed red. If no agent-runnable loop is possible, record attempts and ask the user for the missing artifact/access with the HITL template from `references/six-step-triage.md`.
 
     ### 3. Clarification Questions (MANDATORY - EXACTLY 3)
 
@@ -384,7 +385,7 @@
     1. Discover the next `NNN` (see File Locations section).
     2. Create `.dw/bugfixes/NNN-<slug>/` if not yet created in step 5.0.
     3. Write `TASK.md` with the triage, clarifications, root cause, and the approved plan as executed (use `.dw/templates/bugfix-template.md` as the base structure).
-    4. Write `fix-report.md` with the verbatim `dw-verify` VERIFICATION REPORT plus the before/after reproduction trace.
+    4. Write `fix-report.md` with the verbatim `dw-verify` VERIFICATION REPORT plus the before/after reproduction trace. The report MUST include `Loop command before fix` and `Loop command after fix` (or the exact HITL blocker, attempts made, and artifact/access requested when no loop was possible).
     5. Write `SUMMARY.md` using `.dw/templates/bugfix-summary-template.md`. Fill in slug, date, status `Fixed`, severity, related_concerns (from step 1.5), Symptom (verbatim), Root Cause (one sentence), Resolution (2-4 bullets), Files Touched, Verification, Related, Followups.
     6. If the fix touched a concern listed in `.dw/rules/concerns.md`, append a line to that concern's row's `Last incident` column (or add a new row under Known Bug History) — preserve hand-written entries between `<!-- preserved:start -->` markers.
     7. Report paths of all three files in chat before the commit step.
@@ -494,6 +495,7 @@
     - [ ] **Maximum 5 affected files**
     - [ ] **No migrations**
     - [ ] **Test task included (correct project framework)**
+    - [ ] **Non-trivial bug loop recorded: command before fix + command after fix, or HITL blocker with attempts + requested artifact/access**
     - [ ] Awaiting approval before executing
     - [ ] **`.dw/bugfixes/NNN-<slug>/{TASK,fix-report,SUMMARY}.md` written after verify PASS**
 

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

@@ -69,7 +69,7 @@ Before Stage 1, check for an idea one-pager at `.dw/spec/ideas/<slug>.md` and th
 - `schema_version: "1.1"`;
 - `status: aligned`;
 - `alignment.confirmed_by_user: true`;
-- every dependency branch is resolved (no open decision node);
+- the **Decision Map** has every dependency branch resolved (no open decision node and `Frontier: none`);
 - 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>
@@ -167,7 +167,7 @@ Runs when default mode (after TechSpec approval) OR `plan tasks`.
 4. **Test placement (`dw-testing-discipline`):** every test-adding subtask names its invariant per the placement doctrine. Owning layer specified.
 5. **Constitution alignment:** every task lists `Constitution: respects P-NNN` or `Constitution: deviates P-NNN — ADR planned: <slug>` or `Constitution: n/a — reason: <one-liner>`.
 6. **LLM-eval subtask (when applicable):** if the PRD has an AI feature, one task must include an Eval Plan subtask (reference dataset path, oracle rungs, judge calibration, target metrics).
-7. **Dependency declaration:** each task explicitly lists which previous tasks it depends on. Validation rejects cycles.
+7. **Dependency declaration:** each task explicitly lists which previous tasks it depends on. Write the field as `Depends on: none` or `Depends on: 1.0, 2.0` in `tasks.md` and each `<N>_task.md`. Validation rejects cycles.
 8. **Output locations:**
    - Summary: `.dw/spec/prd-<feature-slug>/tasks.md`
    - Per-task files: `.dw/spec/prd-<feature-slug>/<N>_task.md`

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

@@ -29,6 +29,7 @@ You are the dev-workflow refactor audit entrypoint. This command restores an exp
    - Using Fowler smell taxonomy.
    - Loading `dw-review-rigor` and `dw-simplification` when available.
    - Applying Chesterton's Fence and deep-modules analysis before proposing a refactor.
+   - Loading the advanced deep-modules sections (`Dependency categories decide seam tests` and `Design It Twice for interface findings`) only when the surviving finding is a shallow interface, interface leak, or seam in the wrong place.
    - De-duplicating findings and severity-ordering P0-P3.
    - Saving the output to `<target>/refactor-plan.md`.
 5. If the target does not exist or is too broad, use the clarification questions to narrow it before scanning.

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

@@ -19,6 +19,7 @@ You are the review orchestrator. Runs both Level 2 (PRD compliance / coverage) a
 | `/dw-review --coverage-only` | Only Level 2 — maps every PRD requirement (or bugfix scope) to the code that delivers it. Skips code quality. |
 | `/dw-review --code-only` | Only Level 3 — code quality / convention / security checks. Skips PRD/scope mapping. |
 | `/dw-review --bugfix <NNN-slug>` | Targets a bugfix at `.dw/bugfixes/NNN-slug/` instead of a PRD. Level 2 maps the bugfix scope (TASK.md + fix-report.md + SUMMARY.md) to the code that delivers the fix; Level 3 checks the diff. Output: `.dw/bugfixes/NNN-slug/review/`. |
+| `/dw-review --since <ref>` | Ad-hoc review against a verified comparison point. Runs the normal selected levels, but the diff is computed from `<ref>` after the `--since` preflight below. |
 
 ## Inputs
 
@@ -26,7 +27,8 @@ You are the review orchestrator. Runs both Level 2 (PRD compliance / coverage) a
 |----------|-------------|---------|
 | `{{PRD_PATH}}` | Path to PRD directory (auto-detect from active branch if omitted; ignored when `--bugfix` is used) | `.dw/spec/prd-invoice-export` |
 | `{{BUGFIX_SLUG}}` | Bugfix slug when `--bugfix` flag is used | `001-login-not-working` |
-| `{{MODE}}` | `--coverage-only` / `--code-only` / `--bugfix <slug>` (optional; default = both, target = PRD) | — |
+| `{{SINCE_REF}}` | Git ref used when `--since <ref>` is passed | `v2.0.0`, `HEAD~3`, `main` |
+| `{{MODE}}` | `--coverage-only` / `--code-only` / `--bugfix <slug>` / `--since <ref>` (optional; default = both, target = PRD) | — |
 
 ## Target Resolution
 
@@ -38,6 +40,24 @@ The review runs against one of two target kinds. Compute `<target>` ONCE at the
 
 When the bugfix target is used, the Coverage mapping (Level 2) operates on the numbered tasks from `TASK.md` (not FR-N.M); a task is DELIVERED when (a) the files it claimed to touch are in the diff and (b) the regression test referenced in `fix-report.md` exists and runs. Orphan code in bugfix mode is anything in the diff that does not correspond to a numbered task — a strong signal the safety valve should have escalated to `/dw-plan`.
 
+## `--since <ref>` Preflight
+
+`--since` is opt-in. The default PRD/bugfix review keeps using the PRD branch creation point / base branch flow unchanged.
+
+When `--since <ref>` is passed, run this preflight before any Level 2 or Level 3 analysis:
+
+1. Resolve the fixed point:
+   - Run `git rev-parse --verify --quiet <ref>^{commit}`.
+   - If it fails, abort with: `REJECTED: --since ref '<ref>' does not resolve to a commit. Pass a valid commit, tag, or branch, then rerun /dw-review --since <ref>.`
+2. Build the review range:
+   - Diff command: `git diff <ref>...HEAD`.
+   - Commit command: `git log <ref>..HEAD --oneline`.
+   - Choice: three-dot diff is used so the reviewed patch is what `HEAD` changed since the merge-base with the verified ref, matching PR review semantics and avoiding changes that exist only on `<ref>`.
+3. Confirm the diff is not empty:
+   - Run `git diff --name-only <ref>...HEAD`.
+   - If it returns no paths, abort with: `APPROVED: no changes to review for git diff <ref>...HEAD. Pick an earlier --since ref or use the default PRD/base-branch review.`
+4. Record the resolved ref, the diff command, and the commit command in every generated review report so the review is reproducible.
+
 ## Complementary Skills
 
 When available under `./.agents/skills/`, these are invoked as analytical support:
@@ -107,6 +127,9 @@ Saved to `<target>/QA/review-coverage.md` (PRD target) or `<target>/review/revie
 ```markdown
 # Coverage Review
 
+**Diff command:** git diff <effective-base-or-ref>...HEAD
+**Commit range:** git log <effective-base-or-ref>..HEAD --oneline
+
 ## Status by Functional Requirement
 
 | FR | Description | Status | Evidence | Commit |
@@ -133,7 +156,7 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
 
 ### Behavior
 
-1. **Diff analysis:** identify what changed since the PRD branch was created (`git diff <base-branch>...HEAD`).
+1. **Diff analysis:** identify what changed since the PRD branch was created (`git diff <base-branch>...HEAD`). If `--since <ref>` is used, use the preflight diff command instead.
 
 2. **Rules conformance** (against `.dw/rules/`):
    - General patterns: no `any` types in TS, no `console.log` in prod, error handling, multi-tenancy.
@@ -176,6 +199,13 @@ Saved to `<target>/QA/dw-code-review.md` (PRD target) or `<target>/review/dw-cod
 - **APPROVED WITH CAVEATS** — green but findings worth fixing in follow-up (filed with severities).
 - **REJECTED** — at least one hard gate failed. Specify which.
 
+The report MUST include:
+
+```markdown
+**Diff command:** git diff <effective-base-or-ref>...HEAD
+**Commit range:** git log <effective-base-or-ref>..HEAD --oneline
+```
+
 ## Consolidated output (default mode)
 
 When both levels run, a consolidated report at `<target>/QA/review-consolidated.md` (PRD target) or `<target>/review/review-consolidated.md` (bugfix target):
@@ -188,6 +218,7 @@ When both levels run, a consolidated report at `<target>/QA/review-consolidated.
 **Verification Report:** PASS
 **Security Audit:** PASS (or REJECTED with reasons)
 **Constitution Compliance:** PASS (or violations listed)
+**Diff command:** git diff <effective-base-or-ref>...HEAD
 
 ## Overall Verdict
 <line>

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

@@ -34,6 +34,7 @@ When available under `./.agents/skills/`, these skills are invoked per task:
 - 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-testing-discipline` test-first mode: ONLY when the task text or user explicitly says `TDD`, `test first`, or `red-green-refactor`, execute that task through `references/tdd-loop.md` (confirm public seams with the user → write ONE red test → run and observe red → implement minimum green → run and observe green → next slice; refactor only after the loop via `dw-simplification`). This is not the default `/dw-run` mode.
 - `dw-ui-discipline`: when the task touches UI, the 4 grounding questions must be answered before any visual decision lands.
 - `dw-llm-eval`: when the task touches AI feature code paths, the reference dataset + oracle ladder rules apply.
 - `dw-minimalism`: **before writing new code** — climb the YAGNI decision ladder (need it? reuse? stdlib? native? installed dep? one line?) at the active intensity, then write the minimum. Hands new dependencies to `dw-search-first`.