@brunosps00/dev-workflow 1.7.1 → 2.1.0

package/scaffold/agents/rust/dw-rust-build-fixer.md

@@ -2,7 +2,6 @@
 name: dw-rust-build-fixer
 description: Fix Rust cargo check/test/clippy failures with minimal changes.
 tools: Read, Write, Edit, Bash, Grep, Glob
-model: sonnet
 mode: subagent
 ---
 

package/scaffold/agents/rust/dw-rust-reviewer.md

@@ -2,7 +2,6 @@
 name: dw-rust-reviewer
 description: Review Rust changes for ownership, error handling, concurrency, unsafe, and API design risks.
 tools: Read, Grep, Glob, Bash
-model: sonnet
 mode: subagent
 ---
 

package/scaffold/agents/security/dw-security-reviewer.md

@@ -2,7 +2,6 @@
 name: dw-security-reviewer
 description: Review auth, authorization, secrets, input handling, uploads, SQL, SSRF, XSS, and supply-chain risk.
 tools: Read, Grep, Glob, Bash
-model: sonnet
 mode: subagent
 ---
 

package/scaffold/agents/security/dw-silent-failure-hunter.md

@@ -2,7 +2,6 @@
 name: dw-silent-failure-hunter
 description: Find swallowed errors, dangerous fallbacks, lost stack traces, and missing error propagation.
 tools: Read, Grep, Glob, Bash
-model: sonnet
 mode: subagent
 ---
 

package/scaffold/agents/typescript/dw-typescript-build-fixer.md

@@ -2,7 +2,6 @@
 name: dw-typescript-build-fixer
 description: Fix TypeScript and JavaScript build/type errors with minimal changes.
 tools: Read, Write, Edit, Bash, Grep, Glob
-model: sonnet
 mode: subagent
 ---
 

package/scaffold/agents/typescript/dw-typescript-reviewer.md

@@ -2,7 +2,6 @@
 name: dw-typescript-reviewer
 description: Review TypeScript and JavaScript changes for type safety, async correctness, and web or Node risks.
 tools: Read, Grep, Glob, Bash
-model: sonnet
 mode: subagent
 ---
 

package/scaffold/config/routing.json

@@ -0,0 +1,60 @@
+{
+  "_note": "Dispatch routing for the CLI runners (/dw-claude-run, /dw-codex-run) via the dw-cli-run skill. Maps a task's Conventional-Commit type to a tier, and a tier to a concrete model + effort per brand. Seeded once on init and NEVER overwritten on update — model availability differs per account, so this file is yours to edit. Verify the model ids against `claude --help` / `codex --help` before trusting them; the shipped values are conservative defaults, not a guarantee that your account has access.",
+  "schema_version": "1.0",
+
+  "brands": {
+    "claude": { "detect": "claude --version" },
+    "codex": { "detect": "codex --version" }
+  },
+
+  "tiers": {
+    "light": {
+      "_use": "mechanical, low-ambiguity work; the answer is obvious and the diff is small",
+      "claude": { "model": "haiku", "effort": "low" },
+      "codex": { "model": "gpt-5.4-mini", "effort": "low" }
+    },
+    "standard": {
+      "_use": "normal feature and fix work",
+      "claude": { "model": "sonnet", "effort": "medium" },
+      "codex": { "model": "gpt-5.3-codex", "effort": "medium" }
+    },
+    "heavy": {
+      "_use": "architectural, security-sensitive, or wide-blast-radius work",
+      "claude": { "model": "opus", "effort": "high" },
+      "codex": { "model": "gpt-5.5", "effort": "high" }
+    }
+  },
+
+  "by_commit_type": {
+    "_note": "The task's type is already declared in tasks.md and in the atomic commit subject — no new inference needed.",
+    "chore": "light",
+    "docs": "light",
+    "style": "light",
+    "ci": "light",
+    "test": "standard",
+    "fix": "standard",
+    "feat": "standard",
+    "build": "standard",
+    "refactor": "standard",
+    "perf": "heavy"
+  },
+
+  "escalate_on_surface": {
+    "_note": "If the task's fence touches any of these, override the type-derived tier upward. Match against file paths and the task title.",
+    "tier": "heavy",
+    "patterns": ["auth", "session", "token", "credential", "migration", "payment", "billing", "invoice", "tenant", "crypto", "permission"]
+  },
+
+  "validation": {
+    "_note": "The worker never signs off on its own exam. Cross-brand is the default because a second vendor fails differently.",
+    "cross_brand": "preferred",
+    "degrade": "When only one brand is installed, validate in a SEPARATE dispatch at a different tier — never reuse the executing session.",
+    "acceptance_score": 9
+  },
+
+  "defaults": {
+    "_note": "Applied to every dispatch unless the prompt names a capability that needs otherwise.",
+    "no_mcp": true,
+    "read_only_skips_worktree": true
+  }
+}

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-claude-run.md

@@ -13,7 +13,11 @@ session**, score the delivery 0–10, escalate on failure, and **STOP for the ga
 |---|---|
 | `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`). |
+| `MODEL` | `--model <MODEL>` — `opus` · `sonnet` · `haiku` · `fable`, or a full id (`claude-opus-5`) |
+| `EFFORT` | `--effort <EFFORT>` — `low` · `medium` · `high` · `xhigh` · `max` |
+| `AUTO` | `--dangerously-skip-permissions` (headless auto-approve for a **WRITE** dispatch; justified because the worktree is isolated) |
+| `AUTO_READONLY` | `--permission-mode plan` (optionally `--allowedTools <list>`). Never combine with `AUTO`. |
+| `NO_MCP` | `--strict-mcp-config` with no `--mcp-config` → boots zero MCP servers |
 | `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. |

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

@@ -13,7 +13,11 @@ the delivery 0–10, escalate on failure, and **STOP for the gate**.
 |---|---|
 | `DISPATCH` | `cd <WORKTREE> && codex exec --skip-git-repo-check -m <MODEL> --config model_reasoning_effort="<EFFORT>" --dangerously-bypass-approvals-and-sandbox --json -o <AUDIT>/<slug>.last.md "$(cat <PROMPT>)" </dev/null > <AUDIT>/<slug>.log 2>&1` |
 | `STREAM` | `--json` (JSONL events) |
-| `AUTO` | `--dangerously-bypass-approvals-and-sandbox` (no sandbox + no approvals = full access **with network** so the CLI can run the gate; justified because the worktree is isolated). Edits without a network gate: `--sandbox workspace-write --full-auto`. Read-only/analysis: `--sandbox read-only` (drop `--full-auto`). |
+| `MODEL` | `-m <MODEL>` — `gpt-5.5` · `gpt-5.3-codex` · `gpt-5.4` · `gpt-5.3-codex-spark` · `gpt-5.4-mini` |
+| `EFFORT` | `--config model_reasoning_effort="<EFFORT>"` — `low` · `medium` · `high` · `xhigh` |
+| `AUTO` | `--dangerously-bypass-approvals-and-sandbox` (no sandbox + no approvals = full access **with network** so the CLI can run the gate; **WRITE** dispatch only, justified because the worktree is isolated). Edits without a network gate: `--sandbox workspace-write --full-auto`. |
+| `AUTO_READONLY` | `--sandbox read-only` (drop `--full-auto`). Never combine with `AUTO`. |
+| `NO_MCP` | `-c mcp_servers='{}'` → boots zero MCP servers, keeps auth and the rest of `config.toml`. Blunter alternative: `--ignore-user-config` (also drops model defaults — then `MODEL` + `EFFORT` are mandatory). |
 | `RESUME <id>` | `cd <WORKTREE> && codex exec resume <THREAD_ID> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox --json "$(cat <FOLLOWUP_PROMPT>)" </dev/null >> <AUDIT>/<slug>.log 2>&1` |
 | `RESUME_LAST` | `codex exec resume --last …` (filters by cwd = the worktree) |
 | `SESSION_ID` | Codex has **no flag to fix** the id → **capture** the thread id from the first run's stream: `grep -oE '"thread_id":"[^"]*"' <AUDIT>/<slug>.log \| head -1` (from the `thread.started` event) → write to `<AUDIT>/<slug>.session`. |

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

@@ -129,10 +129,12 @@ Each option lists final-image-size estimate, attack-surface notes, debug-ability
 
 Present the services detected in Phase 0.3 as a checklist. The user can:
 - **Accept** — include all detected services in `docker-compose.dev.yml`
-- **Add** — include additional services they want for dev (e.g., MailHog if SMTP is used in app code, Jaeger if OTel is used)
+- **Add** — include additional services they want for dev (e.g., Mailpit if SMTP is used in app code, Jaeger if OTel is used)
 - **Remove** — drop a detected service (e.g., they have managed Postgres in dev too)
 
-Always offer MailHog if any email-sending library is detected and no email service is already in dev.
+Always offer Mailpit if any email-sending library is detected and no email service is already in dev.
+
+If pgvector is detected in the project, there is no bundled recipe to reach for — it was removed because the image carried CVEs with no upstream fix. Keep whatever image the project already uses, and tell the user plainly that it needs its own review: a rebuilt image, or a managed Postgres with the `vector` extension enabled. Do not substitute an image on the user's behalf.
 
 #### 1.4 File tree preview
 
@@ -163,8 +165,11 @@ Without approval: write report (Phase 3 with `status: PLANNED`) and stop.
 **`docker-compose.dev.yml`**:
 - Compose service blocks from `.agents/skills/docker-compose-recipes/services/*.yml` per `references/compose-composition.md`.
 - Add app service(s) at the end: `build: { context: ., dockerfile: Dockerfile.dev }`, `volumes` for hot reload (bind mount source, anonymous volume for `node_modules`/`__pycache__`), `env_file: .env`, `depends_on` with `condition: service_healthy` per `references/healthcheck-patterns.md`.
+- Preserve each recipe's image tag (do NOT convert any of them to a digest — a digest freezes the base and never picks up a security rebuild), the required credential vars, and the `127.0.0.1` binds. The loopback ports intentionally keep the `apps on host` topology working.
 - Header comment: `# Generated by /dw-dockerize on YYYY-MM-DD`.
 
+**`.env.example`**: emit every credential var with no working value (the recipes use `${VAR:?}`, so Compose refuses to start without one). After copying to `.env`, require the user to set unique generated local values before running Compose. Application URLs use `localhost` when apps run on the host and service DNS when they run in Compose.
+
 **`Dockerfile.dev`** (multi-stage NOT required for dev — single stage is fine):
 
 | Stack | Shape |
@@ -176,7 +181,7 @@ Without approval: write report (Phase 3 with `status: PLANNED`) and stop.
 
 **`.dockerignore`** for dev: exclude `.git`, `node_modules`, `target`, `dist`, `.dw`, `.agents`, `*.md` (except README.md).
 
-**README.md "Local Dev" section** (appended): port table for selected services, default credentials from `.env.example`, the four `dev:*` script commands.
+**README.md "Local Dev" section** (appended): port table for selected services, credential requirements from `.env.example` without working passwords, the four `dev:*` script commands.
 
 #### 2.2 `--prod` artifacts
 
@@ -217,7 +222,8 @@ Key requirements (apply to every language):
 - `restart: always`.
 - Internal network. NO public ports except via reverse proxy.
 - Secrets via `secrets:` block or external manager.
-- Drop dev-only services (no MailHog, Mailpit, smtp4dev, LocalStack, MinIO unless explicitly needed in prod).
+- Drop dev-only services (no Mailpit, smtp4dev, LocalStack, MinIO unless explicitly needed in prod).
+- For vector search, use a separately reviewed image or a managed Postgres service with the `vector` extension; this project ships no vetted pgvector image.
 
 **`.dockerignore`** for prod: stricter than dev. Exclude tests, `tests/`, `.github/`, `.dw/`, `.agents/`, all markdown except license.
 
@@ -234,6 +240,7 @@ Read existing `Dockerfile` and compose files. Apply `security-review/infrastruct
 - Compose: missing healthchecks on services? (flag)
 - Compose: services missing `restart` policy? (flag)
 - Compose: bind mounts in prod compose? (flag CRITICAL if `prod` in filename)
+- Compose: any image pinned by digest, or a credential with a working default? (flag CRITICAL — both block base-image rebuilds or ship a usable credential)
 
 Apply `dw-review-rigor`: dedup repeated patterns, signal-over-volume on style nits.
 
@@ -257,7 +264,7 @@ mode: <dev|prod|both|audit|dry-run>
 languages: [...]
 frameworks: { web: '...', api: '...' }
 services_detected: [postgres, redis, ...]
-services_added: [mailhog, ...]
+services_added: [mailpit, ...]
 base_image_strategy: <conservative|balanced|bold>
 ---
 ```
@@ -272,7 +279,7 @@ Sections:
 6. **Files Created** — table with path + bytes + role.
 7. **Audit Findings** (only `--audit` mode) — table of issues with severity, file:line, recommendation.
 8. **Next Steps:**
-   - For `--dev`: `cp .env.example .env` (if missing), `docker compose -f docker-compose.dev.yml up -d`, then smoke test the app.
+   - For `--dev`: `cp .env.example .env` (if missing), set every required secret such as `POSTGRES_PASSWORD` to a unique local value, run `docker compose -f docker-compose.dev.yml up -d`, then smoke test the app.
    - For `--prod`: build the image locally first (`docker build -t <name>:dev .`), run `/dw-secure-audit` on the Dockerfile and compose, then push to registry.
    - For `--audit`: apply suggested fixes manually or run with `--mode=force-overwrite`.
    - Always: run `/dw-secure-audit --plan` against the project before promoting the image to production.
@@ -293,7 +300,7 @@ Sections:
 - <critical>Never silently overwrite. If `Dockerfile`/`docker-compose.*.yml`/`.dockerignore` exists, default to `--audit`.</critical>
 - <critical>Prod images NEVER include secrets, dev SDK tooling, source code that wasn't compiled, or test fixtures.</critical>
 - <critical>Prod images ALWAYS run as a non-root user.</critical>
-- <critical>Prod compose files NEVER include MailHog, Mailpit, smtp4dev, LocalStack, or development-only services.</critical>
+- <critical>Prod compose files NEVER include Mailpit, smtp4dev, LocalStack, or development-only services.</critical>
 - <critical>If `--audit` finds CRITICAL severity issues (secrets in ENV, root user, public ports on data tier), the report's Next Steps must list the fix as REQUIRED before deploy.</critical>
 - Do NOT use `:latest` tags anywhere.
 - Do NOT exec compose commands from this command — produce files, the user runs `docker compose up`.

package/scaffold/en/commands/dw-generate-pr.md

@@ -109,6 +109,19 @@ Build the body following the template below, filling in with collected informati
 
 3. **Instruct the user** to paste the body (Ctrl+V) in the description field
 
+### 6. Record the PR back into the spec
+
+The PR URL only exists after the user clicks "Create". Once it does, write it back — otherwise nothing on the `.dw/` side ever records which PR delivered the work, and the trail ends at the branch.
+
+```bash
+# Fast path: resolves once the PR exists. Needs the GitHub CLI; skip silently if absent.
+gh pr view --json url -q .url 2>/dev/null
+```
+
+- If a URL resolves, append it to the PRD's `## Related` section as `- PR: <url>`.
+- If `gh` is unavailable or the PR isn't created yet, print the exact line for the user to paste and move on. **Never block the command on this** — it is a record, not a gate.
+- For bugfix branches, append the same line to `.dw/bugfixes/<NNN-slug>/SUMMARY.md` under `## Related` instead.
+
 ## PR Template (copy to clipboard)
 
 ```markdown

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

@@ -79,10 +79,10 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
 
 #### Layer B — Infra (only ask what fits the shape)
 
-6. **Database**: Postgres / Postgres + pgvector / MySQL / SQLite (file, no service) / MongoDB (out of scope for compose recipes — note and skip if chosen) / none. For Postgres + pgvector, select an explicit supported recipe/version.
+6. **Database**: Postgres / MySQL / SQLite (file, no service) / MongoDB (out of scope for compose recipes — note and skip if chosen) / none. There is no bundled pgvector recipe: the image carried unfixed upstream CVEs and no bundled artifact could clear them. If the project needs vector search, note it and let the user pick a separately reviewed image or a managed Postgres with the extension enabled.
 7. **Cache**: Redis / Memcached / none
 8. **Queue / message broker**: pg-boss (Node + Postgres, no extra service), BullMQ (Node + Redis), Celery (Python only), RabbitMQ (any), LocalStack SQS (any), none. If chosen, also ask whether the project will have async workers.
-9. **Email — dev capture** (default: **Mailpit**, ask only if user wants to override): Mailpit / MailHog / smtp4dev / skip
+9. **Email — dev capture** (default: **Mailpit**, ask only if user wants to override): Mailpit / smtp4dev / skip
 10. **Email — prod target** (only ask if user wants email at all): SMTP relay / SendGrid / Resend / Postmark / SES / skip
 11. **Object storage**: S3 (real, no service in compose) / MinIO (dev) / GCS (no service) / none
 12. **Search**: Meilisearch / Typesense / Elasticsearch / none
@@ -112,7 +112,7 @@ Save all answers in memory for Phase 2.
 
 ### Phase 2 — One-Pager + Plan + Approval Gate
 
-1. Render `.dw/spec/projects/{{PROJECT_NAME}}.md` from `.dw/templates/project-onepager.md`. Fill every section: shape, languages, frameworks, services table (name + port + default credentials), architecture diagram (ASCII), generated-files list, open questions.
+1. Render `.dw/spec/projects/{{PROJECT_NAME}}.md` from `.dw/templates/project-onepager.md`. Fill every section: shape, languages, frameworks, services table (name + port + credential requirements, never a working password), architecture diagram (ASCII), generated-files list, open questions.
 2. Build a plan:
    - Commands to run (in order, with arguments)
    - Files to create (with paths under `{{TARGET_DIR}}`)
@@ -163,11 +163,12 @@ If fullstack:
    - Aggregate named volumes under `volumes:`.
    - Resolve port collisions if any.
    - For `everything in Compose`, add the app service(s) at the end (build context = `apps/<name>` or root, Dockerfile.dev, env_file, volumes, depends_on with `condition: service_healthy`). For `apps on host`, compose infrastructure only and use `localhost` endpoints in app-facing environment variables.
+   - Preserve each recipe's image tag (do NOT convert any of them to a digest — a digest freezes the base image and never picks up a security rebuild), the required credential vars, and the `127.0.0.1` port binds. Those loopback mappings intentionally support `apps on host`; do not remove them from local dev.
 3. Add a header comment: `# Generated by /dw-new-project on YYYY-MM-DD`.
 
 #### 3.4 Generate `.env.example`
 
-Consolidate every env var referenced by selected services (per `references/env-conventions.md`). Group by service. Always include the application-side derived URLs (`DATABASE_URL`, `REDIS_URL`, `AMQP_URL`, `SMTP_HOST`/`SMTP_PORT`, `AWS_ENDPOINT_URL`, etc.).
+Consolidate every env var referenced by selected services (per `references/env-conventions.md`). Group by service. Always include the application-side derived URLs (`DATABASE_URL`, `REDIS_URL`, `AMQP_URL`, `SMTP_HOST`/`SMTP_PORT`, `AWS_ENDPOINT_URL`, etc.). Every credential var is emitted empty in `.env.example` (the recipes use `${VAR:?}`, so Compose refuses to start without a real value). Require the user to set unique generated values in the gitignored `.env` before running Compose. Never emit a reusable password.
 
 #### 3.5 Generate scripts
 
@@ -217,7 +218,7 @@ Minimal scaffold:
 | Database | <db or n/a> |
 | Cache | <cache or n/a> |
 | Queue | <queue or n/a> |
-| Email (dev) | <mailpit|mailhog|smtp4dev|none> |
+| Email (dev) | <mailpit|smtp4dev|none> |
 | Search | <search or n/a> |
 | Observability | <observability or n/a> |
 | Reverse proxy | <traefik|none> |
@@ -228,7 +229,7 @@ Minimal scaffold:
 
 ## Services in docker-compose.dev.yml
 
-(table of selected services with ports and default credentials)
+(table of selected services with ports and credential requirements; never include a working password)
 
 ## Conventions
 
@@ -241,8 +242,8 @@ Minimal scaffold:
 
 Generate a starter README with:
 - Project name + 1-line purpose
-- Quick Start (`cp .env.example .env && pnpm install && pnpm dev:up`)
-- Local Dev (port table for selected services + UI URLs + default credentials)
+- Quick Start (`cp .env.example .env`, set every required secret to a unique local value, then `pnpm install && pnpm dev:up`)
+- Local Dev (port table for selected services + UI URLs + credential requirements; never publish a working password)
 - Architecture diagram (ASCII from the one-pager)
 - Project layout (tree of top-level dirs)
 - Dev-workflow integration (mentions `/dw-plan prd`, `/dw-run`, `/dw-qa`, `/dw-secure-audit --plan`, `/dw-secure-audit`)
@@ -276,7 +277,7 @@ date: YYYY-MM-DD
 shape: <frontend|backend|fullstack>
 languages: [typescript, python, ...]
 frameworks: { web: '...', api: '...' }
-services: [postgres-pgvector, mailpit, minio, ...]
+services: [postgres, mailpit, minio, ...]
 package_manager: <pnpm|npm|yarn|poetry|uv|cargo|dotnet>
 monorepo: <pnpm-workspaces|turborepo|nx|none>
 ---
@@ -299,10 +300,10 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 | ... | ... | ... |
 
 ## Services Composed
-<table of services with port + UI URL + default credentials, sourced from .agents/skills/docker-compose-recipes/>
+<table of services with port + UI URL + credential requirements, sourced from .agents/skills/docker-compose-recipes/>
 
 ## Next Steps
-1. `cp .env.example .env` and review credentials.
+1. `cp .env.example .env`, generate unique local secrets, and set every required value such as `POSTGRES_PASSWORD`.
 2. `pnpm install` (or your chosen package manager).
 3. `pnpm dev:up` to bring up all services. Wait for healthchecks.
 4. Open Mailpit UI at http://localhost:8025 to confirm email capture is wired.
@@ -323,10 +324,10 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 
 - <critical>NEVER bypass the Phase 2 approval gate. If invoked in a non-interactive context, abort with: "/dw-new-project requires an interactive approval; rerun with --dry-run to plan-only."</critical>
 - <critical>NEVER run `create-*` tools outside `{{TARGET_DIR}}`. Each command's CWD is the target dir.</critical>
-- <critical>If MailHog/Mailpit/smtp4dev was selected, NEVER also wire a real SMTP into dev. The dev compose ALWAYS captures.</critical>
+- <critical>If Mailpit/smtp4dev was selected, NEVER also wire a real SMTP into dev. The dev compose ALWAYS captures.</critical>
 - <critical>If a `create-*` tool fails, STOP execution. Do not skip ahead to compose generation — partial scaffolds confuse later commands.</critical>
 - Do NOT pin Node/Python/.NET/Rust SDK versions inside the project unless the user asks; rely on `package.json` engines / `pyproject.toml` / `global.json` / `rust-toolchain.toml` to express intent without forcing.
-- Do NOT bake secrets into any generated file. `.env.example` has dev defaults only; real values live in untracked `.env`.
+- Do NOT bake secrets into any generated file. `.env.example` has non-secret dev defaults and empty required secret keys; real values live in untracked `.env`.
 
 ## Error Handling
 

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`.
@@ -75,7 +76,7 @@ When available under `./.agents/skills/`, these skills are invoked per task:
    - Atomic commit message: `feat(<scope>): <task title> (#<task-id>)`.
    - Reference the FRs covered.
    - One task = one commit (unless the task explicitly has subtask milestones that earn separate commits).
-6. **Update tasks.md:** mark this task as `Done` with the commit SHA.
+6. **Update tasks.md:** set this task's `Status` to `Done` and write the short SHA (`git rev-parse --short HEAD`) into its `Commit` column. This is the only record linking a task to its diff — do not skip it.
 7. **Report:** what was done, what tests were added, what was validated.
 
 ### STOP CONDITIONS