@anhth2/spec-driven-dev-plugin 0.6.0 → 0.8.0

package/commands/generate-tests.tmpl

@@ -3,55 +3,451 @@
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID or class path. Find files to test: controllers with `@trace.implements={UC-ID}`, service/facade implementations, and the `.feature` file at `{paths.specs_dir}/{domain}/{UC-ID}.feature`.*
+*Note: For this command, the target in Step 1 is a UC-ID or `.feature` file path. Find the feature file at `{paths.specs_dir}/{domain}/{UC-ID}-*.feature` (glob match — filename includes slug suffix) and the implementation files tagged `@trace.implements={UC-ID}`.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
+## Service Detection
+
+Read `@trace.service` and `@trace.module` from the feature file header.
+
+| Condition | Action |
+|---|---|
+| `@trace.module` present | Use as `active_module` |
+| `@trace.module` absent | Use `tech_stack.module` from project-context.yaml |
+| `@trace.service` present | Store as `active_service` |
+| `@trace.service` absent | Use `{UC-ID}` domain as fallback |
+
+**Platform type classification:**
+
+| Platform | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+---
+
 ## CHECKPOINT — Test Plan
+
+Before generating, scan the feature file for scenarios and the implementation files for classes/functions. Display:
+
 ```
-Test Plan — {UC-ID}:
-Unit Tests:
-  - {Service}ImplTest: {method} — {scenario} → {expected}
-Integration Tests:
-  - {Controller}Test: {endpoint} — {scenario} → HTTP {status}
-Total: {N} classes, ~{M} test cases. Proceed? (Y/N)
+Test Plan — {UC-ID} ({active_module})
+──────────────────────────────────────
+Platform   : {backend | web-frontend | mobile}
+Scenarios  : {N} scenarios from .feature file
+Impl files : {list of files tagged @trace.implements={UC-ID}}
+
+Tests to generate:
+  {platform-specific list — see templates below}
+
+Proceed? (Y/N)
 ```
 
+Wait for explicit "Y" before generating.
+
+---
+
 ## Generate
 
-### Unit Test Template
-```
+### If `platform_type = backend`
+
+#### java-spring
+
+```java
 // @trace.verifies={UC-ID}
+// @trace.service={active_service}
 // @trace.test_type=unit
 class {Resource}ServiceImplTest {
-  // Mock dependencies
-  // Test: methodName_whenValid_shouldReturnExpected()
-  //   Given — set up mocks | When — call method | Then — assert
-  // Test: methodName_whenNotFound_shouldThrowException()
-  //   Given — mock returns empty | When & Then — assert exception
+    @Mock {Repository} {repository};
+    @InjectMocks {Resource}ServiceImpl service;
+
+    // methodName_whenValid_shouldReturnExpected()
+    //   Given — mock repository returns data
+    //   When  — call service method
+    //   Then  — assert result matches expected
+
+    // methodName_whenNotFound_shouldThrowException()
+    //   Given — mock returns Optional.empty()
+    //   When & Then — assertThrows({NotFoundException}.class, ...)
+}
+
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=integration
+@WebMvcTest({Resource}Controller.class)
+class {Resource}ControllerTest {
+    @MockBean {Facade | Service} facade;
+
+    // endpoint_shouldReturn200WhenValid()
+    // endpoint_shouldReturn400WhenInvalid()
+    // endpoint_shouldReturn404WhenNotFound()
+    // endpoint_shouldReturn401WhenUnauthenticated()
 }
 ```
 
-### Integration Test Template (HTTP layer)
+Rules:
+- Unit tests: mock at Repository layer, test Service logic
+- Integration tests: mock at Facade/Service layer, test HTTP contract only
+- Never mock the class under test
+- Follow naming: `methodName_whenCondition_shouldOutcome` (from CLAUDE.md §6)
+
+#### golang
+
+```go
+// @trace.verifies={UC-ID}
+// Unit: table-driven tests for service layer
+func Test{Resource}Service_{Method}(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   {InputType}
+        want    {OutputType}
+        wantErr bool
+    }{
+        {"valid input", ..., ..., false},
+        {"not found", ..., nil, true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) { ... })
+    }
+}
+
+// @trace.verifies={UC-ID}
+// Integration: HTTP handler tests using httptest
+func Test{Resource}Handler_{Endpoint}(t *testing.T) {
+    // setup router, mock service, fire request
+    // assert status code and response body
+}
 ```
+
+#### dotnet
+
+```csharp
+// @trace.verifies={UC-ID}
+// Unit: xUnit + Moq
+public class {Resource}ServiceTests {
+    private readonly Mock<I{Repository}> _repoMock = new();
+    private readonly {Resource}Service _sut;
+
+    [Fact]
+    public async Task {Method}_WhenValid_Returns{Expected}() { }
+
+    [Fact]
+    public async Task {Method}_WhenNotFound_ThrowsNotFoundException() { }
+}
+
+// @trace.verifies={UC-ID}
+// Integration: WebApplicationFactory
+public class {Resource}ControllerTests : IClassFixture<WebApplicationFactory<Program>> {
+    [Fact]
+    public async Task {Endpoint}_Returns200_WhenValid() { }
+
+    [Fact]
+    public async Task {Endpoint}_Returns400_WhenInvalid() { }
+}
+```
+
+#### php-laravel
+
+```php
+// @trace.verifies={UC-ID}
+// Unit: PHPUnit
+class {Resource}ServiceTest extends TestCase {
+    public function test_{method}_when_valid_should_return_expected(): void { }
+    public function test_{method}_when_not_found_should_throw(): void { }
+}
+
+// @trace.verifies={UC-ID}
+// Feature: Laravel HTTP tests
+class {Resource}ControllerTest extends TestCase {
+    use RefreshDatabase;
+    public function test_{endpoint}_returns_200_when_valid(): void {
+        $response = $this->getJson('/api/{resource}');
+        $response->assertStatus(200)->assertJsonStructure([...]);
+    }
+}
+```
+
+#### context-engineering
+
+Check `tech_stack.language` from project-context.yaml to select the correct test syntax:
+
+**If language = Python** (default):
+
+```python
+# @trace.verifies={UC-ID}
+# @trace.test_type=unit
+# Unit: test prompt orchestration functions
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+class Test{Resource}Prompt:
+    # test_{function}_when_valid_input_should_return_expected_output()
+    #   Given — mock LLM client returns controlled response
+    #   When  — call prompt function with valid input
+    #   Then  — assert output matches expected structure/content
+
+    # test_{function}_when_llm_unavailable_should_raise()
+    #   Given — mock LLM client raises connection error
+    #   When & Then — assert specific exception is raised
+
+    # test_{function}_trace_assertions()
+    #   Given — run function with trace capture enabled
+    #   Then  — assert @trace.implements tag present in function definition
+    #           assert output conforms to expected schema
+
+    def test_{function}_when_valid_should_return_expected(self, mock_llm):
+        # Arrange
+        mock_llm.complete.return_value = "{expected response}"
+        # Act
+        result = {function}(input={test_input})
+        # Assert
+        assert result == {expected_output}
+        mock_llm.complete.assert_called_once_with(...)
+
+    def test_{function}_when_invalid_input_should_raise(self):
+        with pytest.raises({ExpectedError}):
+            {function}(input=None)
+```
+
+**If language = TypeScript / JavaScript** (Node.js LangChain.js, etc.):
+
+```typescript
+// @trace.verifies={UC-ID}
+// @trace.test_type=unit
+import { jest } from '@jest/globals'
+
+describe('{Resource}Prompt', () => {
+  const mockLlm = { complete: jest.fn() }
+
+  it('{scenario description}', async () => {
+    mockLlm.complete.mockResolvedValue('{expected response}')
+    const result = await {function}({ input: '{test_input}', llm: mockLlm })
+    expect(result).toEqual({expected_output})
+    expect(mockLlm.complete).toHaveBeenCalledWith(expect.objectContaining({ ... }))
+  })
+
+  it('throws when input is invalid', async () => {
+    await expect({function}({ input: null, llm: mockLlm })).rejects.toThrow('{ExpectedError}')
+  })
+})
+```
+
+**If language = Java** (LangChain4j, etc.): use JUnit 5 + Mockito, same patterns as java-spring unit tests above — mock the `ChatLanguageModel` interface.
+
+Rules:
+- Mock the LLM client at the boundary — never call real LLM in unit tests
+- Validate input schema and output schema separately
+- Each scenario in `.feature` maps to one test function
+- Use parameterized tests for multiple input variants
+
+---
+
+### If `platform_type = web-frontend`
+
+#### react / nextjs / vue / nuxt / angular
+
+```typescript
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=component
+
+// Component tests (Vitest + Testing Library)
+describe('{ComponentName}', () => {
+  it('renders correctly when data is loaded', () => {
+    render(<{ComponentName} {...props} />)
+    expect(screen.getByText('...')).toBeInTheDocument()
+  })
+
+  it('shows loading state while fetching', () => { })
+
+  it('shows error message on API failure', () => { })
+
+  it('calls handler when user interacts', async () => {
+    await userEvent.click(screen.getByRole('button', { name: '...' }))
+    expect(mockHandler).toHaveBeenCalledWith(...)
+  })
+})
+
+// @trace.verifies={UC-ID}
+// @trace.test_type=e2e
+
+// E2E tests (Playwright or Cypress — use whichever is in project)
+test('{scenario from .feature}', async ({ page }) => {
+  await page.goto('/{route}')
+  await page.getByRole('button', { name: '...' }).click()
+  await expect(page.getByText('...')).toBeVisible()
+})
+```
+
+Rules:
+- One component test file per component involved in the UC
+- One E2E test file per UC covering happy path + key error scenarios
+- Mock API calls at the network layer (MSW or cy.intercept), not at component props
+- Use accessible queries (`getByRole`, `getByLabelText`) — avoid `getByTestId` unless necessary
+- Each test maps to exactly one scenario in the `.feature` file
+
+---
+
+### If `platform_type = mobile`
+
+#### flutter
+
+```dart
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=widget
+
+// Widget tests
+group('{FeatureName} widget tests', () {
+  testWidgets('renders correctly when state is loaded', (tester) async {
+    await tester.pumpWidget(MaterialApp(home: {Widget}()));
+    await tester.pumpAndSettle();
+    expect(find.text('...'), findsOneWidget);
+  });
+
+  testWidgets('shows loading indicator while fetching', (tester) async { });
+  testWidgets('shows error widget on failure', (tester) async { });
+  testWidgets('calls handler on tap', (tester) async {
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pumpAndSettle();
+    verify(() => mockBloc.add({Event}())).called(1);
+  });
+});
+
 // @trace.verifies={UC-ID}
 // @trace.test_type=integration
-class {Resource}ControllerTest {
-  // Mock Facade/Service
-  // Test: filter_shouldReturn200()
-  // Test: create_shouldReturn201()
-  // Test: create_shouldReturn400WhenInvalid()
+// Integration test (flutter_test / integration_test package)
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+  testWidgets('{scenario from .feature}', (tester) async {
+    app.main();
+    await tester.pumpAndSettle();
+    // Navigate, interact, assert
+  });
+}
+```
+
+#### react-native
+
+```typescript
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=component
+
+// Jest + React Native Testing Library
+describe('{ComponentName}', () => {
+  it('{scenario description}', () => {
+    const { getByText, getByRole } = render(<{ComponentName} {...props} />)
+    expect(getByText('...')).toBeTruthy()
+  })
+
+  it('calls navigation on button press', () => {
+    const mockNavigate = jest.fn()
+    const { getByRole } = render(<{ComponentName} navigation={{ navigate: mockNavigate }} />)
+    fireEvent.press(getByRole('button'))
+    expect(mockNavigate).toHaveBeenCalledWith('...')
+  })
+})
+```
+
+#### ios-swiftui
+
+```swift
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=unit
+
+// XCTest — ViewModel unit tests
+@MainActor
+final class {Feature}ViewModelTests: XCTestCase {
+    var sut: {Feature}ViewModel!
+    var mockRepo: Mock{Repository}!
+
+    override func setUp() async throws {
+        mockRepo = Mock{Repository}()
+        sut = {Feature}ViewModel(repository: mockRepo)
+    }
+
+    func test_{method}_whenValid_shouldUpdate{State}() async throws {
+        // Given
+        mockRepo.stub{Method}Result = {expected}
+        // When
+        await sut.{method}()
+        // Then
+        XCTAssertEqual(sut.{state}, {expected})
+    }
+
+    func test_{method}_whenError_shouldSetErrorState() async throws { }
+}
+```
+
+#### android-compose
+
+```kotlin
+// @trace.verifies={UC-ID}
+// @trace.service={active_service}
+// @trace.test_type=unit
+
+// Unit test — ViewModel
+class {Feature}ViewModelTest {
+    @get:Rule val mainDispatcherRule = MainDispatcherRule()
+    private val mockRepo: {Repository} = mockk()
+    private lateinit var sut: {Feature}ViewModel
+
+    @Before fun setup() { sut = {Feature}ViewModel(mockRepo) }
+
+    @Test fun `{method} when valid should emit success state`() = runTest {
+        coEvery { mockRepo.{method}(any()) } returns Result.success({data})
+        sut.{method}({input})
+        assertEquals(UiState.Success({data}), sut.uiState.value)
+    }
+}
+
+// @trace.verifies={UC-ID}
+// @trace.test_type=ui
+
+// UI test — Compose
+@HiltAndroidTest
+class {Feature}ScreenTest {
+    @get:Rule(order = 0) val hiltRule = HiltAndroidRule(this)
+    @get:Rule(order = 1) val composeRule = createAndroidComposeRule<MainActivity>()
+
+    @Test fun {scenario}_displaysExpectedUi() {
+        composeRule.onNodeWithText("...").assertIsDisplayed()
+        composeRule.onNodeWithContentDescription("...").performClick()
+        composeRule.onNodeWithText("...").assertIsDisplayed()
+    }
 }
 ```
 
+---
+
 ## Checklist
-- [ ] `@trace.verifies` on every test class
-- [ ] Every .feature scenario has a test
-- [ ] Correct layer mocked (no repo mocks in controller tests)
-- [ ] Test names follow pattern from CLAUDE.md §6 (e.g., `methodName_whenCondition_shouldOutcome`)
+
+**All platforms:**
+- [ ] `@trace.verifies` on every test class / test group
+- [ ] `@trace.service` on every test class / test group
+- [ ] Every scenario in `.feature` file has ≥ 1 corresponding test
+- [ ] Happy path covered
+- [ ] Key error / edge case scenarios covered
+
+**Backend only:**
+- [ ] Correct layer mocked (Repository in unit tests, Facade/Service in controller tests)
+- [ ] No real DB calls in unit tests
+- [ ] Test naming follows `methodName_whenCondition_shouldOutcome` (CLAUDE.md §6)
+
+**Frontend / Mobile only:**
+- [ ] No hardcoded delays (`sleep`, `setTimeout`) in tests — use `waitFor` / `pumpAndSettle`
+- [ ] Accessible queries used (role, label) not implementation-specific selectors
+- [ ] API calls mocked at network layer, not at component level
+
+---
 
 ## Write Trace State
 
@@ -59,22 +455,22 @@ After generating all test files, update `{paths.trace_dir}/{UC-ID}.tsv` — for
 
 | Column | Value |
 |--------|-------|
-| `test_count` | number of test methods covering this SC across all generated test classes |
-| `test_classes` | comma-separated list of test class names (e.g., `OrderServiceImplTest,OrderControllerTest`) |
+| `test_count` | number of test methods covering this SC |
+| `test_classes` | comma-separated test class / describe-block names |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Count `test_count` by scanning generated test files for methods that correspond to this SC (methods whose name or comment references the SC-ID, or all methods in a test class dedicated to this UC).
-
 Leave all other columns unchanged.
 
+---
+
 ## Output
 
 {{include:steps/report-footer.md}}
 
 ```
-/generate-tests Complete — {UC-ID}
-  ✅ {Service}Test ({M} tests)
-  ✅ {Controller}Test ({M} tests)
-Trace: {paths.trace_dir}/{UC-ID}.tsv updated (test_count, test_classes)
+/generate-tests Complete — {UC-ID} ({active_module})
+  ✅ {TestClass1} ({N} tests)
+  ✅ {TestClass2} ({N} tests)
+Trace: {paths.trace_dir}/{UC-ID}.tsv updated
 Next: /run-tests {UC-ID}
 ```

package/commands/refine-prd.md

@@ -31,7 +31,7 @@ Display and wait for response:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Recommended  : claude-opus-4 (or latest Opus model)
   Why needed   : Spec analysis, architecture review, code generation
                  require deep reasoning. Smaller models miss edge cases.
 
@@ -131,6 +131,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -140,13 +141,46 @@ If `paths` section is absent, use these defaults:
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -217,6 +251,26 @@ If the file does not exist → skip silently.
 
 ---
 
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -227,10 +281,12 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -324,21 +380,23 @@ Suggest the logical next command based on workflow phase:
 
 | Current command         | Suggest next                                  |
 |-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
 | /generate-tests         | `/run-tests {UC-ID}`                          |
 | /run-tests (passing)    | `/review-code {UC-ID}`                        |
 | /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
 | /review-code            | `/smoke-test {UC-ID}` or create PR            |
 | /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 
@@ -355,7 +413,9 @@ Next   : {suggested command with example arguments}
 /refine-prd Complete — {PRD name}
 Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
 Review: {paths.refinement_dir}/{prd-slug}-findings.yaml
-Next: Open in Review Board (right-click file) → Update PRD → /generate-bdd
+Next: Open in Review Board (right-click file) → Update PRD
+      → /review-context {prd-file}   ← verify PRD quality before generating BDD
+      → /generate-bdd {prd-file}
 ```
 
 ---
@@ -374,9 +434,16 @@ Next: Open in Review Board (right-click file) → Update PRD → /generate-bdd
 
 For each accepted finding, in order of severity (critical → major → minor):
 - Navigate to the PRD section indicated by `finding.section`.
-- Apply `finding.suggestion` (or the note from `modified` status if applicable).
+- Apply `finding.suggestion`. For `status: "modified"` findings, the human has already edited `finding.suggestion` in the Review Board — that edited value IS the fix to apply.
 - Do not alter any sections not referenced by an accepted finding.
 
+### Phase 2.5 — Update findings file
+
+For each finding that was applied (status was `accepted` or `modified`):
+- Set `status: "applied"` in `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+
+Update `summary.status: "applied"` in the findings file.
+
 ### Phase 3 — Bump version & write changelog entry
 
 1. Read current `| **Version** |` value from PRD metadata table.
@@ -404,5 +471,6 @@ Changes  :
   - {change 2}
 
 ⚠️  BDD may be outdated. Run:
-    /generate-bdd {prd-file}
+    /review-context {prd-file}   ← verify PRD quality first
+    → /generate-bdd {prd-file}
 ```