@brunosps00/dev-workflow 1.7.0 → 2.0.0

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-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

@@ -1,17 +1,17 @@
 <system_instructions>
-You are a workspace bootstrap lead for the dev-workflow ecosystem. Your job is to take an empty (or near-empty) directory, run a Socratic stack interview, and produce a working monorepo or single-app project with: (1) the right framework scaffolds via official `create-*` tools, (2) a `docker-compose.dev.yml` covering every selected dev dependency (db, cache, queue, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, and (4) a seeded `.dw/rules/index.md`.
+You are a workspace bootstrap lead for the dev-workflow ecosystem. Your job is to take an empty, near-empty, or docs-first directory (documentation without application code), run a Socratic stack interview, and produce a working monorepo or single-app project with: (1) the right framework scaffolds via official `create-*` tools, (2) a `docker-compose.dev.yml` covering every selected dev dependency (db, cache, queue, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, and (4) a seeded `.dw/rules/index.md`.
 
 <critical>This command MUST run AFTER `npx dev-workflow init` has populated `.dw/`. If `.dw/commands/` does not exist in the target directory, abort with: "Run `npx @brunosps00/dev-workflow init` first, then re-invoke /dw-new-project."</critical>
 <critical>NEVER touch files outside the new project's directory. The interview captures `{{TARGET_DIR}}`; all writes are scoped under it.</critical>
 <critical>Phase 3 (execution) runs ONLY after the user explicitly approves the plan presented in Phase 2. No flag bypass.</critical>
-<critical>MailHog is the DEFAULT for email-in-dev. The user must explicitly opt out before any other SMTP target is wired into dev.</critical>
+<critical>Mailpit is the DEFAULT for email-in-dev. The user must explicitly opt out before any other SMTP target is wired into dev.</critical>
 
 ## When to Use
 
-- Starting a new project from an empty directory and you want the dev-workflow conventions, containerized infra, and CI scaffolding from day one
+- Starting a new project from an empty or docs-first directory and you want the dev-workflow conventions, containerized infra, and CI scaffolding from day one
 - Replacing manual `pnpm create next-app && create vite ...` ceremony with a guided interview that captures the full dev environment
 - Spinning up a learning sandbox where you want a realistic stack (db + cache + email + observability) without 30 minutes of YAML
-- NOT for adding services to an existing project — use `/dw-dockerize --audit` for that
+- NOT for adding services to a project that already has manifests or application code — use `/dw-dockerize --audit`
 - NOT for adding a new app inside an existing monorepo — that needs a different command (planned for a future release)
 - NOT a replacement for `/dw-plan prd` — this generates the workspace, not the product spec
 
@@ -52,7 +52,7 @@ Execute phases in order. Phase 3 runs ONLY after user approval at the end of Pha
 1. Verify `.dw/commands/` exists in `{{TARGET_DIR}}`. If not, abort with the message above.
 2. Verify Docker is available: run `docker --version` and `docker compose version` (or `docker-compose --version`). If either fails, warn the user and point to `npx @brunosps00/dev-workflow install-deps`. Do NOT abort — the user may want a `--dry-run` plan even without Docker.
 3. Capture `{{PROJECT_NAME}}` (default: kebab-case of CWD basename) and confirm `{{TARGET_DIR}}`.
-4. Confirm the target directory is empty or contains only `.dw/`, `.git/`, `.agents/`, `.claude/`, `.opencode/`. If other files exist, list them and ask whether to proceed (anything else risks clobbering user code).
+4. Classify the target directory as `empty`, `workflow-only`, `docs-first`, or `existing-app`. A docs-first directory may contain documentation, prototypes, assets, and README files, but no application manifests or source directories. List every path that will be preserved and ask for confirmation. If it is an existing app, abort and point to `/dw-dockerize --audit`; never overwrite existing code.
 
 Emit a VERIFICATION REPORT for Phase 0 (Docker version captured, target dir state).
 
@@ -68,21 +68,21 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
 2. **Language(s)**: TypeScript/JavaScript, Python, C#, Rust (per app)
 3. **Framework per layer** (curated list — refuse anything outside):
    - **Frontend**: Next.js (app router), Vite + React (TS template)
-   - **Backend**: FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust), Fastify (Node TS)
-   - **Fullstack** (single bundle): T3 stack (Next.js + tRPC + Prisma + NextAuth), or Next.js front + FastAPI back (separate apps in monorepo)
+   - **Backend**: NestJS or Fastify (Node TS), FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust)
+   - **Fullstack**: T3 stack (single bundle), Next.js + NestJS, or Next.js + FastAPI (separate apps in a monorepo)
 4. **Package manager** (NO default — ask explicitly):
    - For Node: npm / pnpm / yarn
    - For Python: poetry / uv / pip + venv
    - For .NET: dotnet (built-in)
    - For Rust: cargo (built-in)
-5. **If fullstack** — monorepo orchestrator (NO default — ask explicitly): pnpm workspaces, npm workspaces, Turborepo, Nx
+5. **If fullstack** — workspace + task runner (NO default — ask explicitly): package-manager workspaces with native scripts, Turborepo, or Nx. Record combinations such as `pnpm workspaces + Turborepo`.
 
 #### Layer B — Infra (only ask what fits the shape)
 
-6. **Database**: Postgres / MySQL / SQLite (file, no service) / MongoDB (out of scope for compose recipes — note and skip if chosen) / none
+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**: BullMQ (Node only), 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: **MailHog**, ask only if user wants to override): MailHog / Mailpit / smtp4dev / skip
+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 / 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
@@ -93,7 +93,8 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
 #### Layer C — Tooling
 
 16. **Auth** (only ask if applicable to chosen stack):
-    - Next.js: NextAuth / Lucia / Clerk / custom JWT / none
+    - Next.js: Auth.js / generic OIDC / Clerk / custom JWT / none
+    - NestJS: generic OIDC / Passport JWT / custom auth / none
     - FastAPI: fastapi-users / authlib / custom JWT / none
     - ASP.NET: built-in Identity / IdentityServer / custom JWT / none
     - Axum: tower-cookies + jsonwebtoken / custom / none
@@ -102,7 +103,8 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
     - Python: Ruff + Black / Ruff only
     - C#: dotnet format
     - Rust: rustfmt + clippy (default)
-18. **CI**: GitHub Actions (always seed; user can opt out)
+18. **Dev topology**: apps on host + infrastructure in Compose / everything in Compose. For Node monorepos, recommend apps on host when fast hot reload is the priority.
+19. **CI**: GitHub Actions (always seed; user can opt out)
 
 Save all answers in memory for Phase 2.
 
@@ -110,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}}`)
@@ -133,6 +135,7 @@ Run in this order. Each step emits its own mini-VERIFICATION block.
 | Next.js | `pnpm create next-app@latest <dir> --ts --tailwind --eslint --app --import-alias '@/*' --use-pnpm --no-git` |
 | Vite + React | `pnpm create vite@latest <dir> --template react-ts` |
 | T3 | `pnpm dlx create-t3-app@latest <dir> --noGit --CI --tailwind --trpc --prisma --nextAuth --appRouter` |
+| NestJS | `pnpm dlx @nestjs/cli@latest new <dir> --package-manager pnpm --skip-git --strict` |
 | Fastify | `pnpm create fastify@latest <dir>` then trim interactive prompts; if no non-interactive flag works, generate the structure inline (`src/server.ts` + `src/routes/` + `package.json`) |
 | FastAPI | NO official `create-*`. Generate inline: `pyproject.toml` (with chosen package manager), `app/{routers,models,schemas,deps}/`, `app/main.py`, `tests/` skeleton |
 | ASP.NET Core | `dotnet new webapi -n <name> --use-minimal-apis --auth None` (use `--auth Individual` if Identity was chosen) |
@@ -142,12 +145,12 @@ Adjust the package manager flag per the user's choice (e.g., `--use-npm`, `--use
 
 For **fullstack-T3**: that's it for app code (T3 ships everything in one tree).
 
-For **fullstack-NextJS+FastAPI**: run two scaffolds, then move them into `apps/web/` and `apps/api/`.
+For **fullstack-NextJS+NestJS** or **fullstack-NextJS+FastAPI**: scaffold directly into `apps/web/` and `apps/api/` without moving or deleting pre-existing documentation.
 
 #### 3.2 Compose monorepo (fullstack only)
 
 If fullstack:
-1. Move scaffolded apps under `apps/<name>/`.
+1. If an app was scaffolded outside its final workspace path, move it under `apps/<name>/`. Apps scaffolded directly into `apps/web/` or `apps/api/` are already in place and must not be moved again.
 2. Create `pnpm-workspace.yaml` (or equivalent), root `package.json` with workspace scripts, root `tsconfig.base.json` if shared TS config.
 3. If user picked Turborepo: add `turbo.json` with `dev`, `build`, `lint`, `test` pipelines.
 4. If user picked Nx: run `pnpm dlx nx@latest init` after the apps are in place; integrate them as Nx projects.
@@ -159,12 +162,13 @@ If fullstack:
    - Concatenate selected service blocks under `services:`.
    - Aggregate named volumes under `volumes:`.
    - Resolve port collisions if any.
-   - 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` per `references/healthcheck-patterns.md`).
+   - 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
 
@@ -214,7 +218,7 @@ Minimal scaffold:
 | Database | <db or n/a> |
 | Cache | <cache or n/a> |
 | Queue | <queue or n/a> |
-| Email (dev) | <mailhog|mailpit|smtp4dev|none> |
+| Email (dev) | <mailpit|smtp4dev|none> |
 | Search | <search or n/a> |
 | Observability | <observability or n/a> |
 | Reverse proxy | <traefik|none> |
@@ -225,12 +229,12 @@ 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
 
 - See `.dw/rules/<module>.md` after `/dw-analyze-project` runs.
-- Email-in-dev uses MailHog by default; the app NEVER sends real mail in dev.
+- Email-in-dev uses Mailpit by default; the app NEVER sends real mail in dev.
 - All env vars live in `.env` (gitignored); `.env.example` is the template.
 ```
 
@@ -238,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`)
@@ -273,7 +277,7 @@ date: YYYY-MM-DD
 shape: <frontend|backend|fullstack>
 languages: [typescript, python, ...]
 frameworks: { web: '...', api: '...' }
-services: [postgres, redis, mailhog, ...]
+services: [postgres, mailpit, minio, ...]
 package_manager: <pnpm|npm|yarn|poetry|uv|cargo|dotnet>
 monorepo: <pnpm-workspaces|turborepo|nx|none>
 ---
@@ -296,13 +300,13 @@ 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 MailHog UI at http://localhost:8025 to confirm email capture is wired.
+4. Open Mailpit UI at http://localhost:8025 to confirm email capture is wired.
 5. `/dw-plan prd` to draft the first feature.
 6. After your first substantial commit, run `/dw-analyze-project` to enrich `.dw/rules/`.
 ```
@@ -320,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
 
@@ -332,7 +336,7 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 - User picks MongoDB → note "MongoDB recipe not bundled in v0.8.0; we'll add app dependencies but you'll need to wire the service manually". Continue.
 - User picks Caddy → same: note as not in bundled recipes; continue without compose service.
 - Port already bound on host → suggest the override env var and continue; do not pick a different port silently.
-- Working tree contains files other than the allowed set → list them and ask explicitly before proceeding.
+- Docs-first working tree → preserve every listed path and write only to approved new paths. Existing app → abort and point to `/dw-dockerize --audit`.
 
 ## Integration With Other dw-* Commands
 

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

@@ -75,7 +75,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

package/scaffold/en/templates/project-onepager.md

@@ -23,33 +23,35 @@ services: []
 |-------|--------|-----------|
 | Shape | frontend / backend / fullstack | [why this shape — single product surface, API for partners, etc.] |
 | Frontend | Next.js / Vite+React / n/a | [why this framework — SSR needs, SPA simplicity, etc.] |
-| Backend | FastAPI / ASP.NET Core minimal / Axum / Fastify / n/a | [why this framework — team expertise, ecosystem, latency targets] |
-| Database | Postgres / MySQL / SQLite / MongoDB / none | [why this DB — relational needs, JSON-heavy, transactional, etc.] |
+| Backend | NestJS / Fastify / FastAPI / ASP.NET Core minimal / Axum / n/a | [why this framework — team expertise, ecosystem, latency targets] |
+| Database | Postgres / MySQL / SQLite / MongoDB / none | [why this DB — relational, transactional needs, etc. Vector search has no bundled recipe; name the reviewed image or managed service if the project needs it] |
 | Cache | Redis / Memcached / none | [why or why not] |
-| Queue | BullMQ / Celery / RabbitMQ / LocalStack SQS / none | [why or why not + sync vs async workers] |
-| Email — dev | MailHog (default) / Mailpit / smtp4dev / none | [usually MailHog — capture only, never sends real mail] |
+| Queue | pg-boss / BullMQ / Celery / RabbitMQ / LocalStack SQS / none | [why or why not + sync vs async workers] |
+| Email — dev | Mailpit (default) / smtp4dev / none | [usually Mailpit — capture only, never sends real mail] |
 | Email — prod | SMTP / SendGrid / Resend / Postmark / SES / none | [why this provider — volume, deliverability, cost] |
 | Object storage | S3 / MinIO (dev) / GCS / none | [why or why not] |
 | Search | Meilisearch / Typesense / Elasticsearch / none | [why this engine — features, scale, simplicity] |
 | Observability | Sentry / OTel + Jaeger / none | [why this approach — error tracking only, full tracing, etc.] |
 | Reverse proxy | Traefik / Caddy / none | [usually only needed for multi-host dev or prod] |
-| Auth | NextAuth / Lucia / Clerk / fastapi-users / dotnet Identity / custom JWT / none | [why this approach — social login needs, B2B, etc.] |
+| Auth | Auth.js / generic OIDC / Clerk / fastapi-users / dotnet Identity / custom JWT / none | [why this approach — social login needs, B2B, etc.] |
 | Linter / formatter | Biome / ESLint+Prettier / Ruff+Black / dotnet format / cargo fmt+clippy | [team preference] |
 | Package manager | pnpm / npm / yarn / poetry / uv / cargo / dotnet | [team preference] |
-| Monorepo orchestrator | pnpm workspaces / npm workspaces / Turborepo / Nx / n/a | [only for fullstack — caching/build needs] |
+| Workspace + task runner | pnpm workspaces + Turborepo / npm workspaces / Nx / n/a | [only for fullstack — caching/build needs] |
+| Dev topology | apps on host / everything in Compose | [hot reload versus environment parity] |
 | CI | GitHub Actions / none | [usually GitHub Actions; opt out only for non-public repos] |
 
 ## Services & Infra
 
 [Generated services from the docker-compose-recipes skill. Filled by /dw-new-project.]
 
-| Service | Port (host) | UI | Default credentials |
-|---------|-------------|----|--------------------|
-| postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
+| Service | Port (host) | UI | Credentials |
+|---------|-------------|----|-------------|
+| postgres | 127.0.0.1:5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD required in `.env` (no default), POSTGRES_DB=app |
 | redis | 6379 | — | (no auth in dev) |
-| mailhog | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (no auth) |
+| mailpit | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (no auth) |
 | ... | ... | ... | ... |
 
+
 ## Architecture Diagram
 
 ```
@@ -59,12 +61,12 @@ services: []
 [ Browser ] -> [ Next.js (apps/web) ]
 
 # Fullstack
-[ Browser ] -> [ Next.js (apps/web) ] -> [ FastAPI (apps/api) ] -> [ Postgres ]
+[ Browser ] -> [ Next.js (apps/web) ] -> [ NestJS (apps/api) ] -> [ Postgres ]
                                                                 |-> [ Redis ]
-                                                                |-> [ MailHog ]
+                                                                |-> [ Mailpit ]
 
 # With observability
-... -> [ FastAPI ] -> { OTLP } -> [ Jaeger ]
+... -> [ NestJS ] -> { OTLP } -> [ Jaeger ]
 ```
 
 ## Generated Files
@@ -75,7 +77,7 @@ services: []
 {{TARGET_DIR}}/
 ├── apps/
 │   ├── web/                      (created by `pnpm create next-app`)
-│   └── api/                      (inline scaffold — FastAPI)
+│   └── api/                      (created by `pnpm dlx @nestjs/cli` or selected scaffold)
 ├── packages/
 │   └── shared/                   (created by /dw-new-project)
 ├── docker-compose.dev.yml        (composed from .agents/skills/docker-compose-recipes/)

package/scaffold/en/templates/task-template.md

@@ -12,7 +12,7 @@ status: pending
 
 [Brief task description]
 
-**Functional Requirements covered**: FR[X.Y], FR[X.Z] (maximum 2 per task)
+**Functional Requirements covered**: FR-X.Y, FR-X.Z (maximum 2 per task)
 
 <requirements>
 [List of mandatory requirements]

package/scaffold/en/templates/tasks-template.md

@@ -19,11 +19,13 @@ feat/prd-[feature-name]
 
 ## Tasks
 
-| Task | Description | FRs | Status |
-|------|-------------|-----|--------|
-| 1.0 | [Title] | FR1.1, FR1.2 | Pending |
-| 2.0 | [Title] | FR2.1 | Pending |
-| 3.0 | [Title] | FR3.1, FR3.2 | Pending |
+| Task | Description | FRs | Status | Commit |
+|------|-------------|-----|--------|--------|
+| 1.0 | [Title] | FR-1.1, FR-1.2 | Pending | — |
+| 2.0 | [Title] | FR-2.1 | Pending | — |
+| 3.0 | [Title] | FR-3.1, FR-3.2 | Pending | — |
+
+`Commit` holds the short SHA written back by `/dw-run` when the task closes (step 6). It is what makes a task's diff findable later — leave `—` until the task commits.
 
 ## Progress
 

package/scaffold/pt-br/commands/dw-claude-run.md

@@ -13,7 +13,11 @@ para implementar um prompt/spec ja preparado, captura a execucao inteira num log
 |---|---|
 | `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` e **obrigatorio** com `stream-json` no modo `-p`) |
-| `AUTO` | `--dangerously-skip-permissions` (auto-aprovacao headless; justificavel porque a worktree e isolada). Somente leitura/analise: tire-o e use `--permission-mode plan` (ou restrinja `--allowedTools`). |
+| `MODEL` | `--model <MODEL>` — `opus` · `sonnet` · `haiku` · `fable`, ou um id completo (`claude-opus-5`) |
+| `EFFORT` | `--effort <EFFORT>` — `low` · `medium` · `high` · `xhigh` · `max` |
+| `AUTO` | `--dangerously-skip-permissions` (auto-aprovacao headless para dispatch **WRITE**; justificavel porque a worktree e isolada) |
+| `AUTO_READONLY` | `--permission-mode plan` (opcionalmente `--allowedTools <lista>`). Nunca combine com `AUTO`. |
+| `NO_MCP` | `--strict-mcp-config` sem nenhum `--mcp-config` → sobe 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 …` (continua a conversa mais recente nesta cwd) |
 | `SESSION_ID` | **FIXADO por voce** — voce passa `--session-id "$UUID"` na 1a run, entao o id e conhecido de antemao. Gere-o (`cat /proc/sys/kernel/random/uuid` ou `uuidgen`) e grave em `<AUDIT>/<slug>.session` ANTES/no dispatch. Sem scraping do stream — o Claude e o caso facil. |

package/scaffold/pt-br/commands/dw-codex-run.md

@@ -13,7 +13,11 @@ implementar um prompt/spec ja preparado, captura a execucao inteira num log de a
 |---|---|
 | `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` (eventos JSONL) |
-| `AUTO` | `--dangerously-bypass-approvals-and-sandbox` (sem sandbox + sem approvals = full access **com rede**, p/ o CLI rodar o gate; justificavel porque a worktree e isolada). Edicao sem gate de rede: `--sandbox workspace-write --full-auto`. Somente leitura/analise: `--sandbox read-only` (sem `--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` (sem sandbox + sem approvals = full access **com rede**, p/ o CLI rodar o gate; **somente dispatch WRITE**, justificavel porque a worktree e isolada). Edicao sem gate de rede: `--sandbox workspace-write --full-auto`. |
+| `AUTO_READONLY` | `--sandbox read-only` (sem `--full-auto`). Nunca combine com `AUTO`. |
+| `NO_MCP` | `-c mcp_servers='{}'` → sobe zero MCP servers, preserva auth e o resto do `config.toml`. Alternativa mais bruta: `--ignore-user-config` (tambem derruba os defaults de modelo — ai `MODEL` + `EFFORT` viram obrigatorios). |
 | `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 …` (filtra por cwd = a worktree) |
 | `SESSION_ID` | Codex **nao tem flag pra fixar** o id → **capture** o thread id do stream da 1a run: `grep -oE '"thread_id":"[^"]*"' <AUDIT>/<slug>.log \| head -1` (do evento `thread.started`) → grave em `<AUDIT>/<slug>.session`. |