@brunosps00/dev-workflow 1.7.1 → 2.1.0

package/scaffold/skills/dw-debug-protocol/references/six-step-triage.md

@@ -14,12 +14,71 @@ Six discrete steps. Each has a specific output. Don't move to the next without f
 - From a log line → find the surrounding context (request ID, user ID, timestamp); reconstruct the scenario.
 - Write a failing test FIRST when the bug is in pure logic. The test commits the bug to record before you fix it.
 
+### Feedback loop contract
+
+For a non-trivial bug, or whenever the first attempted fix did not work, do not theorize before you have a feedback loop. A good loop is:
+
+- **Single:** one command or one executable artifact, not a hand-managed sequence.
+- **Deterministic:** produces the same result often enough to trust the signal.
+- **Fast:** runs quickly enough that you can use it repeatedly while narrowing the cause.
+- **Agent-runnable:** executable by the agent without hidden credentials, private hardware, or unrecorded manual state.
+- **Red-capable:** proven to fail now, with the failure already observed and saved. "It should fail" is not enough.
+
+Small obvious bugs are exempt from the full checklist when the reproduction is already a single clear command or click path and the fix is truly surgical. The exemption ends immediately if the first fix fails or the bug touches multiple layers.
+
+### Loop repertoire
+
+Pick the smallest loop that can show the bug:
+
+| Loop type | Use when |
+|-----------|----------|
+| Focused test | The bug fits an existing unit, integration, contract, or E2E suite |
+| `curl` / HTTP client | The bug is an API request/response behavior |
+| CLI command | The symptom is triggered by a command-line entry point |
+| Headless browser | The bug depends on browser rendering, routing, storage, or user events |
+| Trace replay | You have a captured request/session/fixture that can be replayed |
+| Dedicated harness | The production entry point is too slow or noisy, but a public seam can be exercised directly |
+| Fuzz or repeat runner | The bug is input-sensitive or low-frequency but locally amplifiable |
+| `git bisect` | A known-good revision exists and the regression window matters |
+| Differential test | A new path should match an old implementation, another service, or a reference output |
+
+### HITL loop template
+
+Use this when the loop cannot be run by the agent because it needs credentials, private data, hardware, or a human click. Do not continue in the dark; ask for the missing artifact or access.
+
+```
+## Human-in-the-loop reproduction needed
+
+I cannot run the feedback loop myself because: <credential / hardware / private data / manual action>.
+
+Please provide one of:
+- A single command I can run locally or in CI.
+- A sanitized fixture, trace, screenshot sequence, or log bundle.
+- Temporary access or exact manual steps you will run.
+
+What I already tried:
+- <attempt 1 + result>
+- <attempt 2 + result>
+
+Once provided, I will first confirm the loop is red-capable before proposing the fix.
+```
+
+### After the loop is red-capable
+
+Only after the failing loop is observed:
+
+1. Minimize the case by removing one variable at a time.
+2. List 3-5 falsifiable hypotheses and rank them before testing any one.
+3. Instrument one variable at a time, with removable log prefixes such as `[DW-DEBUG:<slug>]`, so cleanup is mechanical.
+4. Keep the regression test on the right public seam; do not lock the test to internals.
+5. Remove temporary instrumentation before final verification.
+
 **Common pitfall:** "It happens sometimes." This is not a reproduction. Either:
 - Find a deterministic trigger (often there's a state precondition you missed), OR
 - Quantify the rate (8/10 runs) and treat the test as flaky-but-progress.
 - See `non-reproducible-strategy.md` for state/timing/env-dependent cases.
 
-**Done when:** You have a one-line command (or a series of clicks) that produces the bug ≥80% of the time.
+**Done when:** You have a one-line command, executable script, or short click path for a trivial UI bug that produces the bug ≥80% of the time. For non-trivial bugs, the loop also satisfies the feedback loop contract above, or the HITL blocker is recorded with explicit artifact/access requested from the user.
 
 ## Step 2 — Localize
 

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/dw-execute-phase/references/wave-coordination.md

@@ -4,7 +4,7 @@ Tasks within a phase have dependencies. Some can run in parallel; others must wa
 
 ## Wave computation
 
-Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task numbers).
+Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task IDs).
 
 Algorithm: topological sort.
 
@@ -13,25 +13,25 @@ Algorithm: topological sort.
 3. Wave assignment:
    - Wave 1 = tasks with zero dependencies
    - Wave N = tasks whose all dependencies are in waves 1..N-1
-4. Output: ordered list of waves, each wave a list of task numbers.
+4. Output: ordered list of waves, each wave a list of task IDs.
 
 ## Example
 
 ```
 tasks.md:
-- 01 Create user schema       Depends on: none
-- 02 Create user model        Depends on: 01
-- 03 Create order schema      Depends on: none
-- 04 Wire auth middleware     Depends on: 02
-- 05 Add login endpoint       Depends on: 04
-- 06 Add order endpoint       Depends on: 02, 03
-- 07 Wire validation rules    Depends on: 04, 06
+- 1.0 Create user schema       Depends on: none
+- 2.0 Create user model        Depends on: 1.0
+- 3.0 Create order schema      Depends on: none
+- 4.0 Wire auth middleware     Depends on: 2.0
+- 5.0 Add login endpoint       Depends on: 4.0
+- 6.0 Add order endpoint       Depends on: 2.0, 3.0
+- 7.0 Wire validation rules    Depends on: 4.0, 6.0
 
 Computed waves:
-Wave 1: [01, 03]            (no deps; can run in parallel)
-Wave 2: [02]                (depends on 01)
-Wave 3: [04, 06]            (depend on wave 2)
-Wave 4: [05, 07]            (depend on wave 3)
+Wave 1: [1.0, 3.0]          (no deps; can run in parallel)
+Wave 2: [2.0]               (depends on 1.0)
+Wave 3: [4.0, 6.0]          (depend on wave 2)
+Wave 4: [5.0, 7.0]          (depend on wave 3)
 ```
 
 ## Parallel execution within a wave
@@ -73,7 +73,7 @@ Each wave is a checkpoint:
 
 ## Order within a wave
 
-Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task number (01 commit before 02 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
+Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task ID (1.0 commit before 2.0 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
 
 This means: subagents return their changes (files written, but NOT committed). The executor commits them in numeric order.
 

package/scaffold/skills/dw-grilling/SKILL.md

@@ -36,17 +36,23 @@ vocabulary and the calling command for the idea one-pager / PRD.
    until every dependency branch is resolved, glossary/code contradictions are closed, no blocking decision
    remains, AND the user explicitly confirms. Otherwise persist a draft/paused state and stop.
 
-## Before the first question — build the decision tree
+## Before the first question — resume or build the decision tree
 
-Inspect project facts and open questions, then order them by dependency (never ask a downstream decision before
-its blocker is resolved):
+Inspect the active one-pager/PRD first. If it already has a `### Decision Map`, read it before reconstructing:
+load its nodes, `Depends on:` fields, states, explicit **Frontier**, and `#### Decision Fog`; do not re-ask a
+node already marked `resolved`. Continue from the Frontier when it exists. Only rebuild from scratch when no
+durable map exists or the map is malformed.
+
+When no resumable map exists, inspect project facts and open questions, then order them by dependency (never ask
+a downstream decision before its blocker is resolved):
 
 1. Read what already exists: `.dw/rules/`, `.dw/intel/` (via `/dw-intel` when present), `.dw/constitution.md`,
    `.dw/domain/**` (glossary / context-map), current PRDs/TechSpecs, recent git activity.
 2. Extract the open decisions the plan/PRD implies. Fold in vocabulary tension surfaced by `dw-domain-modeling`
    (fuzzy or overloaded terms are decisions too).
-3. Order them into a **dependency tree**: a node that constrains others comes first. Record it so a later turn
-   (or `/dw-plan`) can resume. Full method + the shared-understanding gate: `references/decision-tree.md`.
+3. Order them into a **dependency tree**: a node that constrains others comes first. Record it in `### Decision
+   Map` so a later turn (or `/dw-plan`) can resume. Full method + the shared-understanding gate:
+   `references/decision-tree.md`.
 
 ## The loop
 
@@ -59,6 +65,9 @@ For each unresolved node, in dependency order:
    `dw-domain-modeling`; the caller persists to the one-pager/PRD). ADR creation still needs a separate explicit
    approval — never auto-create one.
 5. **Re-walk** the tree: the answer may unlock or reshape downstream nodes.
+6. **Persist the map** after each resolved answer when writes are authorized: update node state, `Depends on:`,
+   explicit **Frontier**, and `Decision Fog` without duplicating the decision outcome already recorded in
+   **Resolved Decisions**.
 
 When the tree is exhausted and contradictions are closed, present the shared-understanding summary and ask the
 user to confirm. Only then is the session `aligned`.
@@ -90,8 +99,9 @@ what you *would* persist.
 - **Scope:** the artifact under grill (one-pager / PRD / TechSpec), the decision tree size, and how many nodes
   are resolved vs open.
 - **Evidence:** the facts discovered from repo/rules/intel/docs (with sources) that were used instead of asking.
-- **Artifacts:** decision tree, resolved decisions with the recommended answer and the user's choice, and any
-  authorized `.dw/domain/**` / one-pager / PRD updates (with paths).
+- **Artifacts:** Decision Map (nodes, `Depends on:`, state, Frontier, Decision Fog), resolved decisions with the
+  recommended answer and the user's choice, and any authorized `.dw/domain/**` / one-pager / PRD updates (with
+  paths).
 - **Decisions:** each resolved decision, the alternative rejected, and why.
 - **Risks:** open decisions, unclosed glossary/code contradictions, and any decision made without full evidence.
 - **Next Step:** either "user to confirm shared understanding" (with the remaining nodes) or "aligned — hand off

package/scaffold/skills/dw-grilling/references/decision-tree.md

@@ -3,7 +3,13 @@
 Grill is not a flat questionnaire. It is a walk down a **dependency-ordered decision tree**, so an upstream
 decision is never asked after the downstream decision it constrains.
 
-## Build the tree (before the first question)
+## Resume or build the tree (before the first question)
+
+Before rebuilding a tree, read the active one-pager/PRD for an existing `### Decision Map`. If present and
+well-formed, resume from it instead of deriving the same tree again. Load the node IDs, `Depends on:` fields,
+states, explicit **Frontier**, and `#### Decision Fog`; do not re-ask a node already marked `resolved`.
+
+If there is no durable map yet:
 
 1. **Gather open decisions.** Read the plan/PRD and the project's durable facts (`.dw/rules/`, `.dw/intel/` via
    `/dw-intel`, `.dw/constitution.md`, `.dw/domain/**`, current PRDs/TechSpecs, recent git activity). List every
@@ -16,14 +22,31 @@ decision is never asked after the downstream decision it constrains.
 4. **Topologically order.** Ask parents before children. Independent branches can be walked in any order, but
    within a branch always resolve the blocker first.
 
-Record the tree (nodes, dependencies, resolved/open) so the session — or a later `/dw-plan` handoff — can resume
-exactly where it stopped.
+Record the tree in the active artifact's `### Decision Map` so this session, a later Grill session, or a later
+`/dw-plan` handoff can resume exactly where it stopped.
+
+## Durable Decision Map contract
+
+- Keep one row per decision node with a stable ID (`D1`, `D2`, ...), a short node label, `State`, `Depends on:`,
+  `Frontier?`, and structural notes.
+- Use the same dependency field shape as task plans: `Depends on: none` or `Depends on: D1, D2`. This keeps
+  dependency parsing consistent across durable artifacts.
+- Allowed `State` values are `resolved`, `open-ready`, and `open-blocked`.
+- Maintain an explicit `**Frontier:**` line listing all `open-ready` node IDs, or `none`. The next session reads
+  this line directly; it must not need to manually recompute the graph to know what can be asked next.
+- Keep `#### Decision Fog` for known unresolved areas that are not yet crisp enough to phrase as a decision
+  node. Each item is one line and graduates into a real node once it becomes decidable.
+
+Do not duplicate the content of `### Resolved Decisions` in the map. The map records structure and resume state;
+`Resolved Decisions` records the recommended answer, user's choice, rejected alternative, and evidence.
 
 ## Walk the tree
 
 Resolve nodes in dependency order using the per-turn contract (`interview-loop.md`). After each answer, **re-walk
-the tree**: a resolved parent may add, remove, or reshape child nodes. New tension discovered mid-walk becomes a
-new node, inserted in dependency order — not asked immediately if a blocker is still open.
+the tree** and persist the updated map when writes are authorized: a resolved parent may add, remove, or reshape
+child nodes. New tension discovered mid-walk becomes a new node, inserted in dependency order — not asked
+immediately if a blocker is still open. If a newly discovered uncertainty is real but still too vague to phrase
+as a decision, add it to `Decision Fog` instead of pretending the tree is complete.
 
 ## The shared-understanding gate
 
@@ -44,8 +67,8 @@ terms, and the remaining (non-blocking) decisions with their owners.
 If the gate is not met — blocking decision open, contradiction unclosed, or the user not yet confirming — **do
 not** declare alignment. Persist a draft/paused state:
 
-- Keep the one-pager (or PRD) at its draft/paused status with the decision tree, resolved decisions, and the
-  remaining open nodes recorded (the caller performs the write, only if authorized).
+- Keep the one-pager (or PRD) at its draft/paused status with `### Decision Map`, resolved decisions, the
+  explicit Frontier, and remaining open nodes recorded (the caller performs the write, only if authorized).
 - Return `FINDINGS` with the open nodes as the Next Step, so the next turn resumes the same tree.
 
 ## Handoff to /dw-plan

package/scaffold/skills/dw-simplification/references/deep-modules.md

@@ -91,6 +91,56 @@ The combined verdict:
 
 A flat "this is too long, extract method" recommendation is shallow analysis. Combining Fowler + deep-modules surfaces when the smell is actually a feature.
 
+## Dependency categories decide seam tests
+
+When a finding is about a seam, classify the dependency that seam isolates before choosing the test strategy. The category drives the test plan; do not reflexively mock everything or run every dependency for every test.
+
+This follows `dw-testing-discipline`: tests should sit at the lowest layer that can expose the defect, mocks isolate boundaries, and real systems validate before merge. If this section appears to conflict with `dw-testing-discipline`, prefer `dw-testing-discipline`.
+
+| Category | What it means | Test strategy |
+|----------|---------------|---------------|
+| **In-process** | Same process and memory space: pure functions, formatters, policy objects, parser modules, local caches. | Prefer unit or characterization tests with real collaborators. Mocking here usually tests the mock or hides a shallow interface. |
+| **Local-substitutable** | Real dependency can run locally with equivalent behavior: database, queue, object store emulator, search index, containerized service. | Use integration tests against the real local substitute for the merge gate. Unit tests may fake it for branch coverage, but at least one path must prove the real wiring. |
+| **Remote owned** | A service the team/company owns across the network. | Use adapter unit tests for failure mapping, consumer/producer contract tests for the API shape, and staging/sandbox smoke checks for real network behavior before merge. |
+| **True external** | Third-party service the team does not control: payments, email, identity provider, vendor API. | Keep a narrow adapter seam. Unit-test mapping and error policy with fixtures/fakes; validate contracts against provider sandbox or recorded contract fixtures where available. Do not make routine CI depend on a third-party public site being reachable. |
+
+The output for a seam-related finding adds:
+
+```markdown
+**Dependency category:** <in-process | local-substitutable | remote owned | true external>
+**Seam test strategy:** <lowest layer that catches the defect + real-system gate, if applicable>
+```
+
+## Design It Twice for interface findings
+
+When the surviving finding is **shallow interface**, **interface leak**, or **seam in the wrong place**, do not accept the first interface that works. Generate at least three radically different public-interface proposals for the same module before recommending one.
+
+Each proposal must have a distinct constraint, for example:
+
+- **Caller-minimal:** expose the fewest concepts to the caller, even if implementation grows.
+- **Domain-language-first:** public methods use product/domain vocabulary and hide vendor or storage terms.
+- **Test-boundary-first:** interface places the seam at the dependency category boundary and makes the real-system gate practical.
+- **Migration-first:** supports incremental caller migration without a broad flag day.
+
+Compare each proposal on:
+
+- **Depth:** how much implementation complexity it hides per public concept exposed.
+- **Locality:** whether inputs and outputs are explicit, with no hidden globals or ambient state.
+- **Seam placement:** whether the boundary lands at the dependency category boundary, not halfway through a workflow.
+- **Test cost:** which tests prove behavior without relying on mocks that can drift.
+
+Use a local loop inside this analysis, not `dw-council`, by default. `dw-council` is for high-stakes product or architecture trade-offs with multiple stakeholder priorities; an interface-depth comparison is usually a scoped refactor design exercise. Escalate to `dw-council` only when the interface choice also changes product behavior, ownership boundaries, security posture, or a hard-to-reverse architecture decision.
+
+The output for an interface finding adds:
+
+```markdown
+**Interface alternatives considered:**
+1. <proposal + constraint + depth/locality/seam/test notes>
+2. <proposal + constraint + depth/locality/seam/test notes>
+3. <proposal + constraint + depth/locality/seam/test notes>
+**Recommended interface:** <choice and why>
+```
+
 ## Output for refactor-audit findings
 
 When the audit flags a module as a shallow-wrapper or god-module candidate, the finding entry adds a `Deep-modules: <verdict>` line:

package/scaffold/skills/dw-testing-discipline/SKILL.md

@@ -34,6 +34,7 @@ Each rule has nuance read `references/core-rules.md` for the long version with e
 - Reviewing a PR diff under test paths.
 - Debugging a flaky test (or considering retry-as-fix — read `references/flaky-discipline.md` first).
 - Generating tests via an AI agent → invokes `references/agent-guardrails.md` automatically.
+- Explicit test-first requests ("TDD", "test first", "red-green-refactor") → use `references/tdd-loop.md` as an on-demand operating mode, not the default workflow.
 - Browser-based E2E with Playwright → recipes in `references/playwright-recipes.md`.
 - Verifying browser-side trust boundaries (auth, CSRF, headers) → `references/security-boundary.md`.
 - Picking which test workflow applies (UI / network / perf) → `references/three-workflow-patterns.md`.
@@ -61,6 +62,7 @@ Do not assume `npm test`. The package manager and the test runner are different
 |------------|------|
 | Placing a new test (which layer?) | `references/core-rules.md` (Rule 2 deep-dive) |
 | Writing new tests | `references/patterns.md` |
+| Explicit test-first / TDD loop | `references/tdd-loop.md` |
 | Reviewing tests / spotting smells | `references/anti-patterns.md` |
 | Agent-generated tests | `references/agent-guardrails.md` + `references/anti-patterns.md` |
 | Flaky tests | `references/flaky-discipline.md` |
@@ -180,7 +182,7 @@ Any of these in a PR is enough to REJECT a verdict:
 ## Integration with dev-workflow commands
 
 - `/dw-plan tasks` applies the placement doctrine — each test-adding task names the invariant.
-- `/dw-run` runs the 6 agent guardrails when generating tests during implementation.
+- `/dw-run` runs the 6 agent guardrails when generating tests during implementation. When the task or user explicitly requests test-first work, `/dw-run` switches to `references/tdd-loop.md` for that task only.
 - `/dw-review --code-only` runs the anti-pattern checks on diff hunks under test paths.
 - `/dw-qa --fix` applies the flaky-discipline taxonomy in retest cycles.
 - `/dw-qa` (UI mode) references `playwright-recipes.md` for concrete recipes.

package/scaffold/skills/dw-testing-discipline/references/tdd-loop.md

@@ -0,0 +1,83 @@
+# Test-first red-green loop
+
+Use this procedure only when the user or task explicitly asks for test-first work: "TDD", "test first", "red-green-refactor", or equivalent wording. It operates inside the six core rules from `dw-testing-discipline`; it does not replace or weaken them.
+
+## 0. Confirm the public seam
+
+Before writing the first test, identify the public boundary that should own the behavior:
+
+- API route, CLI command, exported function, component behavior, contract test, browser flow, or other public seam.
+- The invariant the user cares about, in one sentence.
+- The lowest layer that can detect the defect or missing behavior.
+
+Ask the user to confirm the seam before writing any code:
+
+```
+I plan to test this at `<public seam>` because it is the lowest public boundary that proves `<invariant>`.
+Confirm this seam, or point me at the boundary you want covered.
+```
+
+If the user rejects the seam, revise it and ask again. Do not test private helpers or internals just to make the first test easier.
+
+## 1. Write one red test
+
+Write exactly one test for the next vertical slice of behavior.
+
+- The test must assert observable behavior through the confirmed public seam.
+- The test must not be tautological: removing or breaking the production behavior should make it fail.
+- The test must not couple to implementation details, private methods, internal call order, or mock shape.
+- Mocks are allowed only at system boundaries you do not control.
+
+Do not write a batch of future tests before the first implementation. A vertical slice is one failing test, one minimal implementation, one green run.
+
+## 2. Run and observe red
+
+Run the narrowest test command that exercises the new test and capture the actual failure.
+
+The red state is valid only when the observed failure is the expected failure:
+
+- The test fails because the behavior is missing or wrong.
+- The test does not fail because of syntax, import, fixture, selector, clock, network, or mock setup problems.
+- The failure message points at the invariant under test.
+
+If the failure is not the expected red, fix the test setup or seam choice before touching production code.
+
+## 3. Implement the minimum green
+
+Change production code only as much as needed to satisfy the one failing test while preserving existing behavior.
+
+- Prefer the existing codebase patterns.
+- Do not add test-only branches, flags, exports, or helper methods to production.
+- Do not broaden the solution for future slices that do not yet have a red test.
+
+## 4. Run and observe green
+
+Run the same narrow command first. If it passes, run the relevant broader project test command before moving to the next slice.
+
+Record the command and outcome. A presumed green is not enough.
+
+## 5. Continue vertically
+
+Only after the current slice is green:
+
+1. Choose the next behavior slice.
+2. Write one new red test.
+3. Run and observe red.
+4. Implement the minimum green.
+5. Run and observe green.
+
+Stop when the requested behavior is covered at the public seam and the relevant project gate is green.
+
+## Refactor happens after the loop
+
+Refactoring is not part of the red-green cycle. After the behavior slices are green, run a separate review pass. If simplification is warranted, delegate that pass to `dw-simplification` and keep the tests green throughout.
+
+## Hard stops
+
+Stop and ask for clarification when:
+
+- No public seam is identifiable.
+- The user will not confirm the seam.
+- The only test you can write is tautological or coupled to internals.
+- The required mock would replace behavior owned by this codebase.
+- The next slice is unclear enough that the invariant cannot be stated in one sentence.

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.