@brunosps00/dev-workflow 1.7.0 → 2.0.0

package/scaffold/skills/docker-compose-recipes/references/prod-vs-dev.md

@@ -16,6 +16,10 @@ The recipes default to **dev**. When `/dw-dockerize --prod` (or `--both`) emits
 | Logging | Default driver | `json-file` with rotation, or ship to a log aggregator (Loki, CloudWatch) |
 | Resource limits | None (machine has plenty) | `mem_limit`, `cpus` set per service to prevent runaway containers |
 
+Every recipe tracks a tag rather than a digest on purpose: a digest freezes the base image and accrues CVEs with no upgrade path, since only a rebuild clears them. Tracking a tag is not a production approval either — a dev recipe still needs its own review before any non-local environment.
+
+Every credential-bearing dev recipe binds its host port to `127.0.0.1` so apps on the same workstation can connect without publishing the service on every host interface. [source: https://docs.docker.com/reference/compose-file/services/#ports, version: Compose Specification, retrieved: 2026-07-15]
+
 ## Per-service prod transforms
 
 ### Postgres / MySQL / Redis (data tier)
@@ -42,7 +46,7 @@ The recipes default to **dev**. When `/dw-dockerize --prod` (or `--both`) emits
 - **Remove entirely from prod compose.** LocalStack is dev-only.
 - Replace with the real AWS endpoints; `AWS_ENDPOINT_URL` becomes unset (default to AWS).
 
-### MailHog / Mailpit / smtp4dev
+### Mailpit / smtp4dev
 
 - **Remove entirely from prod compose.** Email-in-dev tools are dev-only.
 - Replace with a real provider via `SMTP_*` or API client (SendGrid, Resend, Postmark, SES).
@@ -80,6 +84,7 @@ The recipes default to **dev**. When `/dw-dockerize --prod` (or `--both`) emits
 - Ship secrets in committed files.
 - Use `:latest` tags.
 - Expose data-tier ports publicly.
-- Include MailHog / Mailpit / smtp4dev / LocalStack.
+- Pin any image by digest (it blocks the base-image security rebuilds prod depends on).
+- Include Mailpit / smtp4dev / LocalStack.
 - Skip healthchecks.
 - Forget to set non-root `USER` in the application Dockerfile.

package/scaffold/skills/docker-compose-recipes/services/elasticsearch.yml

@@ -8,14 +8,14 @@ elasticsearch:
   environment:
     discovery.type: single-node
     xpack.security.enabled: "true"
-    ELASTIC_PASSWORD: ${ELASTIC_PASSWORD:-elastic}
+    ELASTIC_PASSWORD: ${ELASTIC_PASSWORD:?Set ELASTIC_PASSWORD in .env}
     ES_JAVA_OPTS: "-Xms512m -Xmx512m"
   ports:
-    - "${ELASTICSEARCH_PORT:-9200}:9200"
+    - "127.0.0.1:${ELASTICSEARCH_PORT:-9200}:9200"
   volumes:
     - elasticsearch_data:/usr/share/elasticsearch/data
   healthcheck:
-    test: ["CMD-SHELL", "curl -fsu elastic:${ELASTIC_PASSWORD:-elastic} http://localhost:9200/_cluster/health | grep -E 'green|yellow'"]
+    test: ["CMD-SHELL", "curl -fsu elastic:${ELASTIC_PASSWORD} http://localhost:9200/_cluster/health | grep -E 'green|yellow'"]
     interval: 10s
     timeout: 5s
     retries: 10

package/scaffold/skills/docker-compose-recipes/services/mailpit.yml

@@ -1,9 +1,9 @@
-# Mailpit — modern alternative to MailHog (active maintenance, full-text search, REST API)
+# Mailpit — maintained email capture for local development
 # Env vars: MAILPIT_SMTP_PORT (default 1025), MAILPIT_UI_PORT (default 8025)
-# Application-side SMTP config: same as MailHog (drop-in replacement)
+# Application-side SMTP config: SMTP_HOST=mailpit; SMTP_PORT=1025
 
 mailpit:
-  image: axllent/mailpit:latest
+  image: axllent/mailpit:v1.30
   restart: unless-stopped
   ports:
     - "${MAILPIT_SMTP_PORT:-1025}:1025"
@@ -24,4 +24,4 @@ mailpit:
 #   mailpit_data: {}
 #
 # Prod notes:
-# - DEV ONLY. Do not ship to prod. See mailhog.yml notes for prod email guidance.
+# - DEV ONLY. Do not ship to prod; replace it with a real SMTP relay or transactional email API.

package/scaffold/skills/docker-compose-recipes/services/meilisearch.yml

@@ -6,11 +6,11 @@ meilisearch:
   image: getmeili/meilisearch:v1.10
   restart: unless-stopped
   environment:
-    MEILI_MASTER_KEY: ${MEILI_MASTER_KEY:-meili-dev-key-change-me}
+    MEILI_MASTER_KEY: ${MEILI_MASTER_KEY:?Set MEILI_MASTER_KEY in .env}
     MEILI_ENV: ${MEILI_ENV:-development}
     MEILI_NO_ANALYTICS: "true"
   ports:
-    - "${MEILISEARCH_PORT:-7700}:7700"
+    - "127.0.0.1:${MEILISEARCH_PORT:-7700}:7700"
   volumes:
     - meilisearch_data:/meili_data
   healthcheck:

package/scaffold/skills/docker-compose-recipes/services/minio.yml

@@ -1,17 +1,21 @@
 # MinIO — S3-compatible object storage (dev replacement for AWS S3)
+# Pinned, not `latest`: a floating tag makes a scan result describe what was pulled
+# that day rather than what the next user runs. This is the newest release published
+# to Docker Hub (2025-09-07); MinIO stopped pushing there afterwards, so `latest`
+# currently resolves to the same image — the pin buys reproducibility, not fewer CVEs.
 # Env vars: MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, MINIO_API_PORT (default 9000), MINIO_UI_PORT (default 9001)
 # Application-side: AWS_ENDPOINT_URL=http://minio:9000; AWS_ACCESS_KEY_ID=${MINIO_ROOT_USER}; AWS_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}
 
 minio:
-  image: minio/minio:latest
+  image: minio/minio:RELEASE.2025-09-07T16-13-09Z
   restart: unless-stopped
   command: server /data --console-address ":9001"
   environment:
     MINIO_ROOT_USER: ${MINIO_ROOT_USER:-minio}
-    MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-minio12345}
+    MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?Set MINIO_ROOT_PASSWORD in .env}
   ports:
-    - "${MINIO_API_PORT:-9000}:9000"
-    - "${MINIO_UI_PORT:-9001}:9001"
+    - "127.0.0.1:${MINIO_API_PORT:-9000}:9000"
+    - "127.0.0.1:${MINIO_UI_PORT:-9001}:9001"
   volumes:
     - minio_data:/data
   healthcheck:

package/scaffold/skills/docker-compose-recipes/services/mysql.yml

@@ -7,16 +7,16 @@ mysql:
   restart: unless-stopped
   command: --default-authentication-plugin=mysql_native_password
   environment:
-    MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root}
+    MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?Set MYSQL_ROOT_PASSWORD in .env}
     MYSQL_USER: ${MYSQL_USER:-app}
-    MYSQL_PASSWORD: ${MYSQL_PASSWORD:-app}
+    MYSQL_PASSWORD: ${MYSQL_PASSWORD:?Set MYSQL_PASSWORD in .env}
     MYSQL_DATABASE: ${MYSQL_DATABASE:-app}
   ports:
-    - "${MYSQL_PORT:-3306}:3306"
+    - "127.0.0.1:${MYSQL_PORT:-3306}:3306"
   volumes:
     - mysql_data:/var/lib/mysql
   healthcheck:
-    test: ["CMD-SHELL", "mysqladmin ping -h localhost -u${MYSQL_USER:-app} -p${MYSQL_PASSWORD:-app}"]
+    test: ["CMD-SHELL", "mysqladmin ping -h localhost -u${MYSQL_USER:-app} -p${MYSQL_PASSWORD}"]
     interval: 5s
     timeout: 3s
     retries: 10

package/scaffold/skills/docker-compose-recipes/services/postgres.yml

@@ -7,10 +7,10 @@ postgres:
   restart: unless-stopped
   environment:
     POSTGRES_USER: ${POSTGRES_USER:-app}
-    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
     POSTGRES_DB: ${POSTGRES_DB:-app}
   ports:
-    - "${POSTGRES_PORT:-5432}:5432"
+    - "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
   volumes:
     - postgres_data:/var/lib/postgresql/data
   healthcheck:

package/scaffold/skills/docker-compose-recipes/services/rabbitmq.yml

@@ -7,10 +7,10 @@ rabbitmq:
   restart: unless-stopped
   environment:
     RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-app}
-    RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:-app}
+    RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:?Set RABBITMQ_PASSWORD in .env}
   ports:
-    - "${RABBITMQ_PORT:-5672}:5672"
-    - "${RABBITMQ_UI_PORT:-15672}:15672"
+    - "127.0.0.1:${RABBITMQ_PORT:-5672}:5672"
+    - "127.0.0.1:${RABBITMQ_UI_PORT:-15672}:15672"
   volumes:
     - rabbitmq_data:/var/lib/rabbitmq
   healthcheck:

package/scaffold/skills/docker-compose-recipes/services/typesense.yml

@@ -3,11 +3,11 @@
 # Application-side: TYPESENSE_HOST=typesense; TYPESENSE_PORT=8108; TYPESENSE_API_KEY=${TYPESENSE_API_KEY}
 
 typesense:
-  image: typesense/typesense:0.27.1
+  image: typesense/typesense:30.2
   restart: unless-stopped
-  command: --data-dir /data --api-key=${TYPESENSE_API_KEY:-typesense-dev-key} --enable-cors
+  command: --data-dir /data --api-key=${TYPESENSE_API_KEY:?Set TYPESENSE_API_KEY in .env} --enable-cors
   ports:
-    - "${TYPESENSE_PORT:-8108}:8108"
+    - "127.0.0.1:${TYPESENSE_PORT:-8108}:8108"
   volumes:
     - typesense_data:/data
   healthcheck:

package/scaffold/skills/dw-cli-run/SKILL.md

@@ -27,7 +27,11 @@ with these slots. Substitute them into the steps below — everything else is id
 |---|---|
 | `DISPATCH` | first-run command (background, streaming → audit log, `</dev/null`) |
 | `STREAM` | flag(s) that make it emit parseable streaming events (JSON/JSONL) |
-| `AUTO` | auto-approve / non-interactive flag (justified by the isolated worktree) |
+| `MODEL` | flag that selects the model tier for this dispatch |
+| `EFFORT` | flag that selects the reasoning budget for this dispatch |
+| `AUTO` | auto-approve / non-interactive flag for a **WRITE** dispatch (justified by the isolated worktree) |
+| `AUTO_READONLY` | plan/sandbox flag for a **READ-ONLY** dispatch (makes edits impossible; no worktree needed) |
+| `NO_MCP` | flag that starts the CLI with no MCP servers (cold-start trim) |
 | `RESUME <id>` | re-run command that **continues the SAME session/context** by id |
 | `RESUME_LAST` | "resume the last session of this cwd" fallback |
 | `SESSION_ID` | how to obtain/fix the session-id (from the stream, a sidecar, or a flag) |
@@ -36,20 +40,30 @@ with these slots. Substitute them into the steps below — everything else is id
 
 If the command did not supply an adapter table, return `BLOCKED` — this skill is not invoked standalone.
 
-## RULE (hard) — never the main thread / main checkout
-Run **only** inside a **dedicated git worktree** (off main). **NEVER** fire the CLI in the repo's **main checkout**
-(the root tree on the primary branch, e.g. `~/code/<project>` on `main`) — the CLI edits autonomously and that
-would corrupt the owner's active tree. If the target is the main checkout, **ABORT** (`BLOCKED`) and instruct:
-create/use a worktree first (`git worktree add ../<project>-<slug> -b <branch> main`). Mandatory check before
-running: `git worktree list` → the target is a secondary worktree (not the one flagged as main) **AND** the CLI's
-`cwd` is that worktree.
+## Dispatch modes — WRITE and READ-ONLY
+
+Every dispatch declares its mode up front; it decides isolation, permission flags, and gate. **WRITE** edits and
+commits → worktree mandatory, `AUTO`, one per worktree, full 0–10 gate. **READ-ONLY** reads/reviews/reports → no
+worktree, `AUTO_READONLY`, freely parallel, score the report without a re-run gate. Per-mode detail:
+`references/dispatch-tuning.md`.
+
+<critical>RULE (hard) — a WRITE dispatch runs **only** inside a **dedicated git worktree** (off main). **NEVER** fire a WRITE dispatch in the repo's **main checkout** (the root tree on the primary branch, e.g. `~/code/<project>` on `main`) — the CLI edits autonomously and that would corrupt the owner's active tree. If the target is the main checkout, **ABORT** (`BLOCKED`) and instruct: create/use a worktree first (`git worktree add ../<project>-<slug> -b <branch> main`). Mandatory check before running: `git worktree list` → the target is a secondary worktree (not the one flagged as main) **AND** the CLI's `cwd` is that worktree.</critical>
+
+<critical>A READ-ONLY dispatch MAY run in the main checkout, because the read-only flags make autonomous edits impossible — that is the entire reason the worktree rule exists. This is NOT a relaxation of the WRITE rule: if the dispatch can write, it is a WRITE dispatch and the worktree is mandatory. When in doubt, treat it as WRITE. Never pass an auto-approve flag on a dispatch declared READ-ONLY.</critical>
 
 ## Pre-flight (fail early > run in the wrong place)
 1. `<cli> --version` answers (CLI + credentials present). Missing → `BLOCKED`.
-2. `git worktree list` — confirm the target worktree and that it is **not** the main checkout.
-3. A **prompt/spec** exists (what the CLI receives). Common conventions: `.dw/spec/<slug>/codex-prompt.md`
+2. **Declare the mode** (WRITE or READ-ONLY) and pick the matching `AUTO`/`AUTO_READONLY` slot.
+3. WRITE only: `git worktree list` — confirm the target worktree and that it is **not** the main checkout.
+4. A **prompt/spec** exists (what the CLI receives). Common conventions: `.dw/spec/<slug>/codex-prompt.md`
    (dev-workflow), `PROMPT.md`, `TASK.md`, or a path the owner names. **Read it** — it is the scope/fence/gate.
 
+## Cold-start cost
+A spawned CLI does not share the parent session's prompt cache and boots every configured MCP server first — on a
+small task that startup can outweigh the task. **Default: pass the adapter's `NO_MCP` slot on every dispatch whose
+prompt does not name an MCP capability.** Tool restriction, config trimming, and how to bind
+`.dw/config/routing.json` are in `references/dispatch-tuning.md` — read it when a dispatch feels overpriced.
+
 ## Where to run — pick the VEHICLE (the main thread NEVER runs inline)
 The main thread **orchestrates**; execution goes to one of these:
 - **Workflow (PREFERRED)** — when there is a pipeline (CLI implements → evaluate 0–10 → **gate fan-out**). One
@@ -66,11 +80,12 @@ The main thread **orchestrates**; execution goes to one of these:
 ## Protocol
 1. **Resolve target.** Worktree + prompt path (from the user or inferred). Derive a `<slug>` (the spec slug or
    worktree tag) — it keys the durable audit log and the session sidecar.
-2. **Model + effort — the parent SIZES the complexity and proposes.** Read the prompt and size it; **propose**
-   model+effort with a one-line rationale (CLI-specific names live in the adapter table); the owner confirms or
-   overrides; if told "you pick", decide by heuristic. Signals: number of tasks; fence breadth; sensitive surface
-   (auth/security/tenant/migration/financial); "foundation/redesign/architectural" vs "mechanical fix/typo/docs";
-   E2E/secure-audit in the gate. Start **one notch below the ceiling** and escalate on failure (see Escalation).
+2. **Model + effort — routing table first, size only what it misses.** `.dw/config/routing.json` is the default
+   source: commit type → tier (`by_commit_type`), raised if the fence matches `escalate_on_surface`, then tier →
+   `MODEL`/`EFFORT` for the brand. Costs no reasoning, reproducible. Absent, or no declared type? Size it: propose
+   with a one-line rationale (signals: task count, fence breadth, sensitive surface, architectural vs mechanical,
+   E2E/secure-audit in the gate); the owner confirms or overrides. Either way start **one notch below the
+   ceiling**. A tier that keeps escalating is a routing bug — name the entry that mis-sized it.
 3. **Set up the durable audit dir (OUTSIDE the worktree).** `<AUDIT>=<main-repo-or-home>/.dw/cli-run/` — it MUST
    survive `git worktree remove` (the worktree's `QA/` is wiped on merge). Files: `<AUDIT>/<slug>.log` (stream),
    `<AUDIT>/<slug>.session` (session-id sidecar), optionally `<AUDIT>/<slug>.last.md` (final message).
@@ -129,32 +144,21 @@ without reaching 9. Always show the score + a short per-criterion rationale —
 ceiling, **cite the specific gap** (the failing test, the file left out of fence), not just a label. Same
 evidence discipline as the five-axis rubric in `dw-review-rigor/references/self-eval-rubric.md`.
 
-## Dual evaluation: the CLI auto-gates (max effort) → the parent re-gates (compares scores)
-The CLI **can't grade its own exam alone** — hence two layers. The CLI auto-gates cheaply (close to the work) and
-**the parent/orchestrator audits independently** and **compares the scores** (catches an inflated self-score). The
-parent is the dispatching session — possibly Claude itself; the re-gate is provider-neutral.
-1. **CLI auto-gate (loop, MAX effort).** The prompt MUST instruct: after implementing, **run the SAME gate** and
-   give a **self-score 0–10**; **fix and re-run while the self-score <9 or the gate isn't green**, at max effort.
-   Stop at self-score ≥9 + green gate (or report `blockers`). The final report carries the self-score + per
-   criterion.
-2. **Parent re-gate (independent).** When the CLI declares pass, the parent/orchestrator **re-runs the SAME gate**
-   (fan-out, prefer Workflow → `/workflows`) and gives its **own 0–10** — without trusting the self-score (a worker
-   never signs off on its own exam, even when that worker is Claude).
-3. **Compare + decide.** Parent ≥9 and small gap → **PASS** (ready for the owner's merge decision). Parent <9 OR a
-   large gap (CLI overestimated) → re-execute: hand the gaps back via **session resume** (step 5, max effort) and
-   repeat 1→2→3 until it converges. **The score that counts for acceptance is the parent's**; the self-score is
-   signal + an inflation detector. Always record both scores + the gap in the Structured Return.
+## Dual evaluation: the worker auto-gates → the parent re-gates
+A worker **can't grade its own exam alone** — hence two layers. (1) The worker loops at max effort until its own
+score is ≥9 with a green gate. (2) The parent independently re-runs the SAME gate and scores it, without trusting
+the self-score — **a worker never signs off on its own exam, even when that worker is Claude**. (3) The parent's
+score is what counts; a large gap means the worker overestimated → hand the gaps back via session resume and
+repeat. Record both scores and the gap. Prefer a **different brand** for the re-gate when one is installed; with
+only one, re-gate in a separate dispatch at a different tier — never reuse the executing session. Full protocol:
+`references/dispatch-tuning.md`.
 
 ## Graded escalation on failure
 If the score is low / the gate failed / the CLI didn't finish, **re-run the SAME task one notch up** — gradual, no
-giving up on the first stumble, no jumping to the top.
-- **Ladder (one at a time):** first **effort** low→medium→high→xhigh (adapter names them); exhausted, bump the
-  **model** one tier and reset effort to high. Re-run and **re-score**.
-- **Continue vs restart:** coherent partial edits → **resume the session** (step 5, keeps context). Broken/dirty
-  worktree → **reset first** (`git -C <worktree> reset --hard && git clean -fd`) and run fresh at the higher notch
-  — don't stack error on error.
-- **Stop:** at **score ≥9** (ready for the gate) OR when **exhausted** (strongest model + max effort still below)
-  → `BLOCKED` with evidence. Announce each notch; with autonomy, escalate to the ceiling yourself.
+giving up on the first stumble, no jumping to the top. **Ladder:** effort first (`low`→`max`), then bump the model
+one tier and reset effort. **Stop** at score ≥9, or `BLOCKED` with evidence when the ceiling is exhausted.
+Announce each notch. Full ladder, continue-vs-restart rules, and how to read escalation as a routing-table signal:
+`references/dispatch-tuning.md`.
 
 ## Detailed output → direct the next step
 The delivery must be **detailed enough for the parent to decide the next step** — not an opaque "done". When it

package/scaffold/skills/dw-cli-run/references/dispatch-tuning.md

@@ -0,0 +1,85 @@
+# Dispatch tuning — trim the cold start, bind the routing table
+
+Read this when a dispatch feels disproportionately expensive for the size of the task, or when wiring
+`.dw/config/routing.json` for the first time. The protocol in `SKILL.md` works without it.
+
+## Cold-start cost
+
+A spawned CLI does not share the parent session's prompt cache and boots every configured MCP server before doing
+any work. On a small task that startup can cost more than the task itself. This is the one real advantage an
+in-session subagent keeps over a spawned CLI — so trim the spawn until the gap stops mattering.
+
+| | Claude | Codex |
+|---|---|---|
+| No MCP servers | `--strict-mcp-config` (with no `--mcp-config`) | `-c mcp_servers='{}'` |
+| Drop all user config | — | `--ignore-user-config` (blunt: also drops model defaults, so `MODEL` + `EFFORT` become mandatory) |
+| Restrict tools | `--tools ""` disables all; `--allowedTools <list>` for a subset | `--sandbox read-only` |
+
+**Default:** pass the MCP kill switch on every dispatch whose prompt does not name an MCP capability. If the
+prompt needs docs lookup (`context7`) or browser automation (`playwright`), keep them and say so in the dispatch
+rationale.
+
+Verified against `claude` 2.1.220 and `codex-cli` 0.144.4. Re-check with `claude --help` / `codex exec --help`
+after a CLI upgrade — these flags are not covered by either project's stability guarantees.
+
+## Binding `.dw/config/routing.json`
+
+Resolution order for a dispatch:
+
+1. Read the task's Conventional-Commit type (already in `tasks.md` and in the atomic commit subject).
+2. `by_commit_type[<type>]` → tier name.
+3. If the fence or the task title matches any `escalate_on_surface.patterns`, override the tier upward.
+4. `tiers[<tier>][<brand>]` → concrete `MODEL` + `EFFORT`.
+5. Substitute into the adapter's `MODEL`/`EFFORT` slots.
+
+If the file is absent, or the task has no declared type, fall back to the sizing heuristic in `SKILL.md` step 2.
+
+`routing.json` is seeded once on init and never reconciled on update, because model availability differs per
+account. Treat the shipped model ids as defaults to verify, not as a guarantee of access — a dispatch that fails
+with an unknown-model error is a routing-table edit, not a protocol bug.
+
+## Dual evaluation in full
+
+The CLI auto-gates cheaply (close to the work); the parent/orchestrator audits independently and compares the
+scores, which is what catches an inflated self-score. The parent is the dispatching session — possibly Claude
+itself; the re-gate is provider-neutral.
+
+1. **Worker auto-gate (loop, MAX effort).** The prompt MUST instruct: after implementing, **run the SAME gate**
+   and give a **self-score 0–10**; **fix and re-run while the self-score <9 or the gate isn't green**, at max
+   effort. Stop at self-score ≥9 + green gate (or report `blockers`). The final report carries the self-score plus
+   a per-criterion breakdown.
+2. **Parent re-gate (independent).** When the worker declares pass, the parent **re-runs the SAME gate** (fan-out,
+   prefer Workflow → `/workflows`) and gives its **own 0–10**, without trusting the self-score. Prefer a different
+   brand for this step when both are installed — a second vendor fails differently, which is the whole point of
+   the second layer. With one brand installed, re-gate in a separate dispatch at a different tier.
+3. **Compare + decide.** Parent ≥9 and small gap → **PASS** (ready for the owner's merge decision). Parent <9 OR a
+   large gap (worker overestimated) → re-execute: hand the gaps back via **session resume** at max effort and
+   repeat 1→2→3 until it converges. **The score that counts for acceptance is the parent's**; the self-score is
+   signal plus an inflation detector. Always record both scores and the gap in the Structured Return.
+
+## The escalation ladder in full
+
+If the score is low, the gate failed, or the CLI didn't finish, re-run the SAME task one notch up — gradual, no
+giving up on the first stumble, no jumping to the top.
+
+- **Ladder (one at a time):** first **effort** `low`→`medium`→`high`→`xhigh`(→`max` on Claude; the adapter names
+  the levels it supports); once exhausted, bump the **model** one tier and reset effort to `high`. Re-run and
+  **re-score**.
+- **Continue vs restart:** coherent partial edits → **resume the session** (keeps its context and the files it
+  already touched). Broken or dirty worktree → **reset first**
+  (`git -C <worktree> reset --hard && git clean -fd`) and run fresh at the higher notch. Don't stack error on
+  error.
+- **Stop:** at **score ≥9** (ready for the owner's gate), OR when **exhausted** (strongest model at max effort
+  still below the bar) → `BLOCKED` with evidence. Announce each notch; with autonomy, escalate to the ceiling
+  yourself rather than asking at every step.
+
+## Reading escalation as a routing signal
+
+A task that routinely needs two or more notches above what the table assigned is telling you the table is wrong
+for that commit type. Report which
+entry mis-sized it in the Structured Return, so the next edit to `routing.json` is grounded in a real run rather
+than a guess.
+
+The reverse also matters and is easier to miss: a tier that never escalates may be over-provisioned. If `feat`
+work consistently lands at score ≥9 on the first try, try the tier below it before assuming the current one is
+load-bearing.

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -80,7 +80,7 @@ Detail in `references/atomic-commits.md` (deviation entry format) and `reference
 Every task ends with exactly one git commit:
 
 ```
-feat(<scope>): <task title> (RF-XX)
+feat(<scope>): <task title> (#<task-id>)
 
 <one-line summary of what this commit delivers>
 
@@ -89,9 +89,11 @@ feat(<scope>): <task title> (RF-XX)
 - Tests added/updated: <list>
 - Deviations: <link to deviations.md entry, if any>
 
-Closes RF-XX (partial — see tasks.md).
+Closes <REQ-ID> (partial — see tasks.md).
 ```
 
+`<REQ-ID>` is copied verbatim from `tasks.md` — `FR-N.M` in English projects, `RF-N.M` in Portuguese ones. This skill is shared by both; never hardcode a prefix.
+
 The commit message format is consistent across waves so `/dw-generate-pr` can build a clean PR body. See `references/atomic-commits.md`.
 
 ## De-Sloppify Pass (optional cleanup task)

package/scaffold/skills/dw-execute-phase/agents/executor.md

@@ -88,7 +88,7 @@ For each wave:
 Format (per `references/atomic-commits.md`):
 
 ```
-<type>(<scope>): <task title> (RF-XX)
+<type>(<scope>): <task title> (#<task-id>)
 
 <one-line summary>
 
@@ -97,9 +97,11 @@ Format (per `references/atomic-commits.md`):
 - Tests added/updated: <list>
 - Deviations: <link or "none">
 
-Closes RF-XX (partial — full close on tasks.md completion).
+Closes <REQ-ID> (partial — full close on tasks.md completion).
 ```
 
+`<REQ-ID>` is copied verbatim from `tasks.md` (`FR-N.M` in English projects, `RF-N.M` in Portuguese ones) — never assume a prefix.
+
 Type from Conventional Commits (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`). Scope from task domain. Run `git add -A && git commit` once.
 
 ### Step 5: Deviation handling (when implementation diverges from plan)

package/scaffold/skills/dw-execute-phase/agents/plan-checker.md

@@ -50,7 +50,7 @@ Then verify each level against the actual plan files.
 
 - `prd_path` (from spawn prompt): `.dw/spec/prd-<slug>/`
 - Reads:
-  - `<prd_path>/prd.md` — the goal, requirements (RF-XX), acceptance criteria
+  - `<prd_path>/prd.md` — the goal, requirements (`<REQ-ID>`, see Dimension 1), acceptance criteria
   - `<prd_path>/techspec.md` — architecture decisions
   - `<prd_path>/tasks.md` — the plan to verify
   - `<prd_path>/<NN>_task.md` — per-task detail
@@ -62,15 +62,17 @@ Then verify each level against the actual plan files.
 
 ### Dimension 1: Requirement Coverage
 
-**Question:** Does every PRD requirement (RF-XX) have at least one task addressing it?
+<critical>Requirement IDs are language-dependent. English projects number them `FR-N.M`; Portuguese projects `RF-N.M`. This skill is shared by both — NEVER hardcode a prefix. Read the IDs verbatim from `prd.md` and match those exact strings in `tasks.md`. `<REQ-ID>` below stands for whichever form the project uses.</critical>
+
+**Question:** Does every PRD requirement have at least one task addressing it?
 
 **Process:**
-1. Extract every numbered requirement from `prd.md`
-2. For each RF-XX, search `tasks.md` for tasks tagged with that RF
+1. Extract every numbered requirement ID from `prd.md` verbatim (`FR-1.1`, `RF-1.1`, …)
+2. For each `<REQ-ID>`, search `tasks.md` for tasks tagged with that exact ID
 3. List uncovered requirements
 
-**Pass:** every RF has at least one task.
-**Revise:** ≥1 RF has no task; the planner missed it.
+**Pass:** every requirement has at least one task.
+**Revise:** ≥1 requirement has no task; the planner missed it.
 **Block:** the PRD has no requirements at all (plan can't verify).
 
 ### Dimension 2: Task Completeness
@@ -174,7 +176,7 @@ After running all 6 dimensions:
 
 ### REVISE — Dimension 1: Requirement Coverage
 
-- **RF-04** ("user can reset password via email link") has no task. Suggested: add task between 05 and 06.
+- **FR-4.1** ("user can reset password via email link") has no task. Suggested: add task between 05 and 06.
 
 ### REVISE — Dimension 2: Task Completeness
 

package/scaffold/skills/dw-execute-phase/references/atomic-commits.md

@@ -7,7 +7,7 @@ Every task in a phase commits exactly once. This drives traceability (a task's d
 Strict format. No deviations.
 
 ```
-<type>(<scope>): <task title> (RF-XX)
+<type>(<scope>): <task title> (#<task-id>)
 
 <one-line summary>
 
@@ -16,9 +16,11 @@ Strict format. No deviations.
 - Tests added/updated: <comma-separated list, or "none">
 - Deviations: <link to deviations.md entry, or "none">
 
-Closes RF-XX (partial — full close on tasks.md completion).
+Closes <REQ-ID> (partial — full close on tasks.md completion).
 ```
 
+<critical>`<REQ-ID>` is the requirement ID exactly as `prd.md` and `tasks.md` write it. English projects use `FR-N.M`; Portuguese projects use `RF-N.M`. This skill is shared by both — copy the ID verbatim, never assume a prefix.</critical>
+
 ### Field rules
 
 **`<type>`** — Conventional Commits:
@@ -36,7 +38,7 @@ Closes RF-XX (partial — full close on tasks.md completion).
 
 **`<task title>`** — copy from `tasks.md` task line. Imperative, concise. "Add login endpoint", not "Added login endpoint" or "Adding login endpoint".
 
-**`(RF-XX)`** — the requirement this task closes. If the task contributes to multiple, list the primary; mention the others in the body.
+**`(#<task-id>)`** — the task ID from `tasks.md` (`#1.0`, `#2.3`). This is what makes the commit findable from the task index — `/dw-run` writes the resulting SHA back into the `tasks.md` Commit column.
 
 **`<one-line summary>`** — one sentence answering "what does this commit deliver?". Different from the title (which is the task title); this is the OUTCOME.
 
@@ -44,12 +46,14 @@ Closes RF-XX (partial — full close on tasks.md completion).
 
 **Deviations link** — `.dw/spec/prd-<slug>/deviations.md#deviation-03-1` if the task triggered a Rule 1 or 2 deviation.
 
-**Closes line** — `Closes RF-XX (partial — full close on tasks.md completion)` because one task usually doesn't fully close a requirement; the whole phase does. Final task in the phase changes "(partial — ...)" to "(full)".
+**Closes line** — `Closes <REQ-ID> (partial — full close on tasks.md completion)` because one task usually doesn't fully close a requirement; the whole phase does. Final task in the phase changes "(partial — ...)" to "(full)". If the task closes more than one requirement, list them comma-separated.
 
 ## Examples
 
+Both examples come from an English project (`FR-`); a Portuguese project writes `RF-` in the same slots.
+
 ```
-feat(auth): wire JWT middleware to all /api/* routes (RF-04)
+feat(auth): wire JWT middleware to all /api/* routes (#4.0)
 
 Authenticated routes now reject requests without valid Bearer tokens.
 
@@ -58,11 +62,11 @@ Authenticated routes now reject requests without valid Bearer tokens.
 - Tests added/updated: src/middleware/auth.test.ts (12 cases — happy path, expired, malformed, missing)
 - Deviations: none
 
-Closes RF-04 (partial — full close on tasks.md completion).
+Closes FR-4.1 (partial — full close on tasks.md completion).
 ```
 
 ```
-test(orders): add integration tests for order creation flow (RF-07)
+test(orders): add integration tests for order creation flow (#7.0)
 
 Covers happy path, payment failure, inventory mismatch.
 
@@ -71,7 +75,7 @@ Covers happy path, payment failure, inventory mismatch.
 - Tests added/updated: tests/integration/orders.test.ts (8 cases)
 - Deviations: .dw/spec/prd-checkout-v2/deviations.md#deviation-08-1
 
-Closes RF-07 (partial — full close on tasks.md completion).
+Closes FR-7.2 (partial — full close on tasks.md completion).
 ```
 
 ## Verification before commit

package/scaffold/skills/dw-execute-phase/references/plan-verification.md

@@ -10,12 +10,14 @@ Mid-execution discovery of plan flaws is expensive: context burned, partial comm
 
 ### 1. Requirement Coverage
 
-**Goal:** every PRD requirement (RF-XX) has at least one task addressing it.
+**Goal:** every PRD requirement (`<REQ-ID>`) has at least one task addressing it.
+
+<critical>`<REQ-ID>` is language-dependent: `FR-N.M` in English projects, `RF-N.M` in Portuguese ones. This skill is shared by both — extract the IDs verbatim from `prd.md` and match those exact strings downstream; never hardcode a prefix.</critical>
 
 **Steps:**
-1. Extract numbered requirements from `prd.md`. Pattern: `### RF-NN` or `**RF-NN:**` or numbered list under "Functional Requirements".
-2. Build `Set<RF>` of expected requirements.
-3. Scan `tasks.md` and `<NN>_task.md` files for `Closes RF-XX` / `RF: RF-XX` / `Requirement: RF-XX` markers.
+1. Extract numbered requirements from `prd.md`. Pattern: `### <REQ-ID>` or `**<REQ-ID>:**` or numbered list under "Functional Requirements" / "Requisitos Funcionais".
+2. Build `Set<REQ-ID>` of expected requirements.
+3. Scan `tasks.md` and `<NN>_task.md` files for `Closes <REQ-ID>` / the `FRs`/`RFs` table column / `Requirement: <REQ-ID>` markers.
 4. Compute `uncovered = expected - addressed`.
 
 **Pass:** `uncovered` is empty.

package/scaffold/skills/docker-compose-recipes/services/mailhog.yml

@@ -1,23 +0,0 @@
-# MailHog — DEV-ONLY email capture (NEVER sends real mail)
-# This is the dev-workflow DEFAULT for email-in-dev so the project cannot accidentally email real users.
-# Env vars: MAILHOG_SMTP_PORT (default 1025), MAILHOG_UI_PORT (default 8025)
-# Application-side SMTP config:
-#   SMTP_HOST=mailhog ; SMTP_PORT=1025 ; SMTP_USER= ; SMTP_PASSWORD= ; SMTP_SECURE=false
-
-mailhog:
-  image: mailhog/mailhog:latest
-  restart: unless-stopped
-  ports:
-    - "${MAILHOG_SMTP_PORT:-1025}:1025"
-    - "${MAILHOG_UI_PORT:-8025}:8025"
-  healthcheck:
-    test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:8025"]
-    interval: 10s
-    timeout: 3s
-    retries: 5
-    start_period: 5s
-
-# Prod notes:
-# - MailHog must NEVER ship to prod. Replace with a real SMTP relay or transactional email API
-#   (SendGrid, Resend, Postmark, SES) when promoting docker-compose.dev.yml to prod.
-# - Open the UI at http://localhost:8025 to inspect captured mail; nothing leaves the host.