@brunosps00/dev-workflow 1.7.1 → 2.1.0

package/scaffold/scripts/hooks/git-guardrails.mjs

@@ -14,13 +14,17 @@
  * error allows the command, so a hook bug never blocks the user.
  */
 
-const DANGEROUS = [
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DANGEROUS = [
   { re: /\bgit\s+push\b[^\n|&;]*(--force\b|--force-with-lease\b|\s-f\b)/, why: 'force push rewrites remote history' },
   { re: /\bgit\s+push\b[^\n|&;]*(--delete\b|\s-d\b|\s:\S)/, why: 'deletes a remote branch' },
   { re: /\bgit\s+reset\b[^\n|&;]*--hard\b/, why: 'hard reset discards uncommitted work and rewrites the branch' },
   { re: /\bgit\s+clean\b[^\n|&;]*-[a-z]*f/, why: 'git clean -f permanently deletes untracked files' },
   { re: /\bgit\s+branch\b[^\n|&;]*\s-D\b/, why: 'force-deletes a branch that may be unmerged' },
   { re: /\bgit\s+checkout\b[^\n|&;]*\s(--\s+\.|\.\s*$)/, why: 'discards all local changes in the working tree' },
+  { re: /\bgit\s+restore\b[^\n|&;]*\s(--\s+)?\.(?=\s*(?:$|[|&;]))/, why: 'discards all local changes in the working tree' },
 ];
 
 function readStdin() {
@@ -38,42 +42,55 @@ function allow() {
   process.exit(0);
 }
 
-function deny(reason) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'deny',
-        permissionDecisionReason: reason,
-      },
-    }) + '\n',
-  );
-  process.exit(0);
-}
-
-async function main() {
+export function evaluatePayload(input) {
   let payload;
   try {
-    payload = JSON.parse(await readStdin());
+    payload = JSON.parse(input);
   } catch {
-    return allow(); // fail open
+    return null; // fail open
   }
 
   const command = payload && payload.tool_input && typeof payload.tool_input.command === 'string'
     ? payload.tool_input.command
     : '';
-  if (!command) return allow();
+  if (!command) return null;
 
   for (const rule of DANGEROUS) {
     if (rule.re.test(command)) {
-      return deny(
-        `Blocked by dev-workflow git guardrails: ${rule.why}. ` +
-          `If this is intentional, run it yourself outside the agent, or adjust .claude/settings.json hooks.`,
-      );
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason:
+            `Blocked by dev-workflow git guardrails: ${rule.why}. ` +
+            `If this is intentional, run it yourself outside the agent, or adjust .claude/settings.json hooks.`,
+        },
+      };
     }
   }
 
-  return allow();
+  return null;
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }) + '\n',
+  );
+  process.exit(0);
+}
+
+async function main() {
+  const result = evaluatePayload(await readStdin());
+  if (!result) return allow();
+  return deny(result.hookSpecificOutput.permissionDecisionReason);
 }
 
-main().catch(() => allow());
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(() => allow());
+}

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docker-compose-recipes
-description: Use for docker-compose service blocks (postgres, pgvector, redis, mailpit, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
+description: Use for docker-compose service blocks (postgres, redis, mailpit, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
 allowed-tools:
   - Read
   - Write
@@ -49,14 +49,12 @@ Each row points to `services/<name>.yml`.
 | Service | Use | Default port(s) | Recipe |
 |---------|-----|-----------------|--------|
 | Postgres 16 (alpine) | Relational DB | `5432` | `services/postgres.yml` |
-| PostgreSQL 18 + pgvector 0.8.2 | Relational + vector DB | `5432` | `services/postgres-pgvector.yml` |
 | MySQL 8 | Relational DB | `3306` | `services/mysql.yml` |
 | Redis 7 (alpine) | Cache, pub/sub, BullMQ backend | `6379` | `services/redis.yml` |
 | Memcached 1.6 (alpine) | Cache | `11211` | `services/memcached.yml` |
 | RabbitMQ 3 (management-alpine) | Message broker + UI | `5672`, UI `15672` | `services/rabbitmq.yml` |
 | LocalStack | AWS-compatible local (S3, SQS, SNS, DynamoDB) | `4566` | `services/localstack.yml` |
 | Mailpit | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
-| MailHog | Legacy email capture alternative | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
 | smtp4dev | Windows-friendly SMTP capture | SMTP `2525`, UI `5000` | `services/smtp4dev.yml` |
 | MinIO | S3-compatible local | API `9000`, UI `9001` | `services/minio.yml` |
 | Meilisearch | Search engine (lightweight) | `7700` | `services/meilisearch.yml` |
@@ -82,7 +80,7 @@ Each row points to `services/<name>.yml`.
 
 ## Inspired by
 
-Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `pgvector/pgvector`, `redis`, `axllent/mailpit`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
+Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `axllent/mailpit`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
 
 ## Structured Return
 

package/scaffold/skills/docker-compose-recipes/references/compose-composition.md

@@ -4,7 +4,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 
 ## The merge algorithm
 
-1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres-pgvector, mailpit, minio]`.
+1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres, mailpit, minio]`.
 2. **Read each `services/<name>.yml`** as a standalone fragment. Each file declares ONE top-level service block (e.g., `postgres:`) plus comments at the bottom describing the volumes block to merge.
 3. **Concatenate under a single `services:` map.** Indent each block under `services:` in the final file. Order does not matter for compose, but for readability sort by tier: storage → cache/queue → search → email → observability → proxy.
 4. **Collect the volumes.** Each recipe's comments list the named volumes it needs. Aggregate them under a top-level `volumes:` block. Example:
@@ -42,7 +42,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 services:
   # --- storage tier ---
   postgres:
-    # ... contents from services/postgres-pgvector.yml
+    # ... contents from services/postgres.yml
 
   # --- cache tier ---
   redis:

package/scaffold/skills/docker-compose-recipes/references/env-conventions.md

@@ -1,12 +1,18 @@
 # Env var conventions
 
-All recipes reference env vars via `${VAR:-default}` so a project's `.env` (or `.env.example`) is the single source of truth.
+Recipes reference non-secret env vars via `${VAR:-default}` — ports, users, database names. **Every credential uses `${VAR:?error}` instead**, so Compose refuses to start when the value is missing rather than falling back to a value published in this repository. That applies to `postgres`, `mysql`, `elasticsearch`, `meilisearch`, `minio`, and `rabbitmq`; `test/compose-recipe-safety.test.js` enforces it across every recipe.
+
+Authenticated services also publish on `127.0.0.1:` only. Docker's `"HOST:CONTAINER"` short form binds every host interface, which turns a local dev credential into a network-reachable one.
+
+A project's `.env` is the local source of truth; `.env.example` documents required keys without supplying reusable credentials.
+
+[source: https://docs.docker.com/reference/compose-file/interpolation/, version: Compose Specification, retrieved: 2026-07-15]
 
 ## Naming pattern
 
 - **Service-scoped** vars use the upstream image's convention: `POSTGRES_USER`, `MYSQL_ROOT_PASSWORD`, `MEILI_MASTER_KEY`, etc. This avoids surprises when reading the image's documentation.
 - **Application-scoped** vars use a generic name that spans implementations: `DATABASE_URL`, `REDIS_URL`, `SMTP_HOST`, `AWS_ENDPOINT_URL`. The application reads these, not the service-specific ones.
-- **Port overrides** use `<SERVICE>_PORT` (or `<SERVICE>_<ROLE>_PORT` when there are several): `POSTGRES_PORT`, `MAILHOG_SMTP_PORT`, `MAILHOG_UI_PORT`, `RABBITMQ_PORT`, `RABBITMQ_UI_PORT`.
+- **Port overrides** use `<SERVICE>_PORT` (or `<SERVICE>_<ROLE>_PORT` when there are several): `POSTGRES_PORT`, `MAILPIT_SMTP_PORT`, `MAILPIT_UI_PORT`, `RABBITMQ_PORT`, `RABBITMQ_UI_PORT`.
 
 ## Mapping between service vars and app vars
 
@@ -15,21 +21,22 @@ When a project uses Postgres, the `.env.example` should declare BOTH the service
 ```dotenv
 # Postgres (consumed by the postgres service)
 POSTGRES_USER=app
-POSTGRES_PASSWORD=app
+# Required: generate a unique value in .env before running Compose.
+POSTGRES_PASSWORD=
 POSTGRES_DB=app
 POSTGRES_PORT=5432
 
-# Application-side connection string
-DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+# Application-side connection string for apps running on the host
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${POSTGRES_PORT}/${POSTGRES_DB}
 ```
 
 Compose performs variable substitution in `.env` references. When the application also runs in Compose, use service DNS such as `postgres`; when applications run on the host, the committed example must use `localhost` and the published host port instead.
 
-For the PostgreSQL + pgvector recipe, use the same connection variables. The image provides the extension binaries, but `CREATE EXTENSION IF NOT EXISTS vector` belongs in the application's reviewed migrations, not container startup scripts.
+If a project needs the `vector` extension, there is no bundled recipe for it — use a separately reviewed image or a managed Postgres, with the same connection variables above. `CREATE EXTENSION IF NOT EXISTS vector` belongs in the application's reviewed migrations, never in a container startup script.
 
 ## What goes in `.env.example` vs `.env`
 
-- `.env.example` — committed. Holds DEFAULTS that are safe for dev and template values for prod.
+- `.env.example` — committed. Holds non-secret defaults and empty required secret keys; it never contains a working database password.
 - `.env` — gitignored. Real values for the user's local machine.
 
 Never commit a `.env`. Always commit a `.env.example`.
@@ -43,11 +50,11 @@ Never commit a `.env`. Always commit a `.env.example`.
 | Redis URL | `REDIS_URL` | `REDIS_PASSWORD` (if set) |
 | RabbitMQ URL | `AMQP_URL` | `RABBITMQ_USER`, `RABBITMQ_PASSWORD` |
 | AWS-compatible | `AWS_ENDPOINT_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | LocalStack: `test`/`test`. MinIO: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` |
-| SMTP | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_SECURE` | Service hostname (`mailhog`/`mailpit`/`smtp4dev`) + recipe's SMTP port |
+| SMTP | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_SECURE` | Service hostname (`mailpit`/`smtp4dev`) + recipe's SMTP port |
 | OTel | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://jaeger:4318` |
 
 ## Reserved names
 
 The recipes use these env var names. Do NOT reuse them for unrelated config:
 
-`POSTGRES_*`, `MYSQL_*`, `MEILI_*`, `MINIO_*`, `RABBITMQ_*`, `MAILHOG_*`, `MAILPIT_*`, `SMTP4DEV_*`, `JAEGER_*`, `TRAEFIK_*`, `LOCALSTACK_*`, `ELASTIC_*`, `TYPESENSE_*`, `MEMCACHED_*`, `REDIS_*`.
+`POSTGRES_*`, `MYSQL_*`, `MEILI_*`, `MINIO_*`, `RABBITMQ_*`, `MAILPIT_*`, `SMTP4DEV_*`, `JAEGER_*`, `TRAEFIK_*`, `LOCALSTACK_*`, `ELASTIC_*`, `TYPESENSE_*`, `MEMCACHED_*`, `REDIS_*`.

package/scaffold/skills/docker-compose-recipes/references/healthcheck-patterns.md

@@ -12,7 +12,6 @@ Every recipe ships a healthcheck. App services that depend on infra MUST gate st
 | Memcached | `echo stats | nc -w 1 localhost 11211 \| grep -q uptime` | Memcached has no native ping; stats command is the cheapest readiness signal |
 | RabbitMQ | `rabbitmq-diagnostics ping` | Built-in; takes ~30s to be ready, hence `start_period: 30s` |
 | LocalStack | `curl -sf http://localhost:4566/_localstack/health \| grep -q running` | Internal endpoint reports per-service readiness |
-| MailHog | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
 | Mailpit | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
 | smtp4dev | `wget --spider http://localhost:80` | UI on internal port 80 |
 | MinIO | `curl -f http://localhost:9000/minio/health/live` | Documented liveness endpoint |

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/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-debug-protocol/SKILL.md

@@ -32,6 +32,8 @@ See `references/stop-the-line.md` for when this rule bends.
 
 Without a deterministic reproduction, you cannot know whether your "fix" worked. The reproduction is the hypothesis test. Even a flaky bug needs a *reproducible-enough* test (e.g., "fails 8/10 runs") before fixing.
 
+For non-trivial bugs, or after a first fix fails, Step 1 must establish the red-capable feedback loop contract in `references/six-step-triage.md` before theorizing: one loop, deterministic enough, fast, agent-runnable, and observed red. If the loop needs human action, use the HITL template there instead of continuing blind.
+
 If you cannot reproduce: see `references/non-reproducible-strategy.md`. Don't fix on guess.
 
 ### 3. Find the root cause, not the nearest cause