@brunosps00/dev-workflow 2.0.0 → 2.1.0

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.