bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/modules/bmm/testarch/knowledge/recurse.md

@@ -0,0 +1,296 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Polling with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // Use assertions instead of boolean returns
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // If assertions pass, predicate succeeds
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Key Points**:
+
+- Predicate can use `expect()` assertions
+- If assertions throw, polling continues
+- If assertions pass, polling succeeds
+- More expressive than boolean returns
+
+### Example 3: Custom Error Messages
+
+**Context**: Provide context-specific error messages for timeout failures.
+
+**Implementation**:
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `error` option provides custom message
+- Replaces default "Timed out after X ms"
+- Include debugging hints in error message
+- Helps diagnose failures faster
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## Enhanced Error Types
+
+The utility categorizes errors for easier debugging:
+
+```typescript
+// TimeoutError - Predicate never returned true
+Error: Polling timed out after 30000ms: Job never completed
+
+// CommandError - Command function threw
+Error: Command failed: Request failed with status 500
+
+// PredicateError - Predicate function threw (not from assertions)
+Error: Predicate failed: Cannot read property 'status' of undefined
+```
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- ✅ Background job completion
+- ✅ Webhook/event processing
+- ✅ Database eventual consistency
+- ✅ Cache propagation
+- ✅ State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+
+## Anti-Patterns
+
+**❌ Using hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**✅ Poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**❌ Polling too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**✅ Reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```

package/src/modules/bmm/testarch/tea-index.csv

@@ -20,3 +20,14 @@ test-priorities,Test Priorities Matrix,"P0–P3 criteria, coverage targets, exec
 test-healing-patterns,Test Healing Patterns,"Common failure patterns and automated fixes","healing,debugging,patterns",knowledge/test-healing-patterns.md
 selector-resilience,Selector Resilience,"Robust selector strategies and debugging techniques","selectors,locators,debugging",knowledge/selector-resilience.md
 timing-debugging,Timing Debugging,"Race condition identification and deterministic wait fixes","timing,async,debugging",knowledge/timing-debugging.md
+overview,Playwright Utils Overview,"Installation, design principles, fixture patterns","playwright-utils,fixtures",knowledge/overview.md
+api-request,API Request,"Typed HTTP client, schema validation","api,playwright-utils",knowledge/api-request.md
+network-recorder,Network Recorder,"HAR record/playback, CRUD detection","network,playwright-utils",knowledge/network-recorder.md
+auth-session,Auth Session,"Token persistence, multi-user","auth,playwright-utils",knowledge/auth-session.md
+intercept-network-call,Intercept Network Call,"Network spy/stub, JSON parsing","network,playwright-utils",knowledge/intercept-network-call.md
+recurse,Recurse Polling,"Async polling, condition waiting","polling,playwright-utils",knowledge/recurse.md
+log,Log Utility,"Report logging, structured output","logging,playwright-utils",knowledge/log.md
+file-utils,File Utilities,"CSV/XLSX/PDF/ZIP validation","files,playwright-utils",knowledge/file-utils.md
+burn-in,Burn-in Runner,"Smart test selection, git diff","ci,playwright-utils",knowledge/burn-in.md
+network-error-monitor,Network Error Monitor,"HTTP 4xx/5xx detection","monitoring,playwright-utils",knowledge/network-error-monitor.md
+fixtures-composition,Fixtures Composition,"mergeTests composition patterns","fixtures,playwright-utils",knowledge/fixtures-composition.md

package/src/modules/bmm/workflows/1-analysis/create-product-brief/product-brief.template.md

@@ -0,0 +1,10 @@
+---
+stepsCompleted: []
+inputDocuments: []
+date: { system-date }
+author: { user }
+---
+
+# Product Brief: {{project_name}}
+
+<!-- Content will be appended sequentially through collaborative workflow steps -->

package/src/modules/bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md

@@ -0,0 +1,192 @@
+---
+name: 'step-01-init'
+description: 'Initialize the product brief workflow by detecting continuation state and setting up the document'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-vision.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
+
+# Template References
+productBriefTemplate: '{workflow_path}/product-brief.template.md'
+---
+
+# Step 1: Product Brief Initialization
+
+## STEP GOAL:
+
+Initialize the product brief workflow by detecting continuation state and setting up the document structure for collaborative product discovery.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused Business Analyst facilitator
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+- ✅ Maintain collaborative discovery tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on initialization and setup - no content generation yet
+- 🚫 FORBIDDEN to look ahead to future steps or assume knowledge from them
+- 💬 Approach: Systematic setup with clear reporting to user
+- 📋 Detect existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking any action
+- 💾 Initialize document structure and update frontmatter appropriately
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until user selects 'C' (Continue)
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Variables from workflow.md are available in memory
+- Focus: Workflow initialization and document setup only
+- Limits: Don't assume knowledge from other steps or create content yet
+- Dependencies: Configuration loaded from workflow.md initialization
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Check for Existing Workflow State
+
+First, check if the output document already exists:
+
+**Workflow State Detection:**
+
+- Look for file at `{output_folder}/analysis/*product-brief*.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+**Continuation Protocol:**
+
+- **STOP immediately** and load `{workflow_path}/steps/step-01b-continue.md`
+- Do not proceed with any initialization tasks
+- Let step-01b handle all continuation logic
+- This is an auto-proceed situation - no user choice needed
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery:
+
+**Research Documents (Priority: Sharded → Whole):**
+
+1. Check for sharded research folder: `{output_folder}/analysis/research/**/*.md`
+2. If folder exists: Load EVERY file in that folder completely
+3. If no folder exists: Try whole file: `{output_folder}/analysis/research/*research*.md`
+4. Add discovered files to `inputDocuments` frontmatter
+
+**Brainstorming Documents (Priority: Sharded → Whole):**
+
+1. Check for sharded brainstorming folder: `{output_folder}/analysis/*brainstorm*/**/*.md`
+2. If folder exists: Load useful brainstorming files completely
+3. If no folder exists: Try whole file: `{output_folder}/analysis/*brainstorm*.md`
+4. Add discovered files to `inputDocuments` frontmatter
+
+**Project Documentation (Existing Projects):**
+
+1. Look for index file: `{output_folder}/**/index.md`
+2. Load index.md to understand what project files are available
+3. Read available files from index to understand existing project context
+4. Add discovered files to `inputDocuments` frontmatter
+
+#### B. Create Initial Document
+
+**Document Setup:**
+
+- Copy the template from `{productBriefTemplate}` to `{outputFile}`
+- Initialize frontmatter with proper structure:
+
+```yaml
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'product-brief'
+lastStep: 0
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+---
+```
+
+#### C. Present Initialization Results
+
+**Setup Report to User:**
+"Welcome {{user_name}}! I've set up your product brief workspace for {{project_name}}.
+
+**Document Setup:**
+
+- Created: `{outputFile}` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+
+- Research: {number of research files loaded or "None found"}
+- Brainstorming: {number of brainstorming files loaded or "None found"}
+- Project docs: {number of project files loaded or "None found"}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Do you have any other documents you'd like me to include, or shall we continue to the next step?"
+
+### 4. Present MENU OPTIONS
+
+Display: "**Proceeding to product vision discovery...**"
+
+#### Menu Handling Logic:
+
+- After setup report is presented, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an initialization step with auto-proceed after setup completion
+- Proceed directly to next step after document setup and reporting
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then load and read fully `{nextStepFile}` to execute and begin product vision discovery.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Existing workflow detected and properly handed off to step-01b
+- Fresh workflow initialized with template and proper frontmatter
+- Input documents discovered and loaded using sharded-first logic
+- All discovered files tracked in frontmatter `inputDocuments`
+- Menu presented and user input handled correctly
+- Frontmatter updated with `stepsCompleted: [1]` before proceeding
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not updating frontmatter with discovered input documents
+- Creating document without proper template structure
+- Not checking sharded folders first before whole files
+- Not reporting discovered documents to user clearly
+- Proceeding without user selecting 'C' (Continue)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/modules/bmm/workflows/1-analysis/create-product-brief/steps/step-01b-continue.md

@@ -0,0 +1,165 @@
+---
+name: 'step-01b-continue'
+description: 'Resume the product brief workflow from where it was left off, ensuring smooth continuation'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
+---
+
+# Step 1B: Product Brief Continuation
+
+## STEP GOAL:
+
+Resume the product brief workflow from where it was left off, ensuring smooth continuation with full context restoration.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused Business Analyst facilitator
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+- ✅ Maintain collaborative continuation tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on understanding where we left off and continuing appropriately
+- 🚫 FORBIDDEN to modify content completed in previous steps
+- 💬 Approach: Systematic state analysis with clear progress reporting
+- 📋 Resume workflow from exact point where it was interrupted
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking any action
+- 💾 Keep existing frontmatter `stepsCompleted` values
+- 📖 Only load documents that were already tracked in `inputDocuments`
+- 🚫 FORBIDDEN to discover new input documents during continuation
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Current document and frontmatter are already loaded
+- Focus: Workflow state analysis and continuation logic only
+- Limits: Don't assume knowledge beyond what's in the document
+- Dependencies: Existing workflow state from previous session
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Analyze Current State
+
+**State Assessment:**
+Review the frontmatter to understand:
+
+- `stepsCompleted`: Which steps are already done
+- `lastStep`: The most recently completed step number
+- `inputDocuments`: What context was already loaded
+- All other frontmatter variables
+
+### 2. Restore Context Documents
+
+**Context Reloading:**
+
+- For each document in `inputDocuments`, load the complete file
+- This ensures you have full context for continuation
+- Don't discover new documents - only reload what was previously processed
+- Maintain the same context as when workflow was interrupted
+
+### 3. Present Current Progress
+
+**Progress Report to User:**
+"Welcome back {{user_name}}! I'm resuming our product brief collaboration for {{project_name}}.
+
+**Current Progress:**
+
+- Steps completed: {stepsCompleted}
+- Last worked on: Step {lastStep}
+- Context documents available: {len(inputDocuments)} files
+
+**Document Status:**
+
+- Current product brief is ready with all completed sections
+- Ready to continue from where we left off
+
+Does this look right, or do you want to make any adjustments before we proceed?"
+
+### 4. Determine Continuation Path
+
+**Next Step Logic:**
+Based on `lastStep` value, determine which step to load next:
+
+- If `lastStep = 1` → Load `./step-02-vision.md`
+- If `lastStep = 2` → Load `./step-03-users.md`
+- If `lastStep = 3` → Load `./step-04-metrics.md`
+- Continue this pattern for all steps
+- If `lastStep = 6` → Workflow already complete
+
+### 5. Handle Workflow Completion
+
+**If workflow already complete (`lastStep = 6`):**
+"Great news! It looks like we've already completed the product brief workflow for {{project_name}}.
+
+The final document is ready at `{outputFile}` with all sections completed through step 6.
+
+Would you like me to:
+
+- Review the completed product brief with you
+- Suggest next workflow steps (like PRD creation)
+- Start a new product brief revision
+
+What would be most helpful?"
+
+### 6. Present MENU OPTIONS
+
+**If workflow not complete:**
+Display: "Ready to continue with Step {nextStepNumber}: {nextStepTitle}?
+
+**Select an Option:** [C] Continue to Step {nextStepNumber}"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute the appropriate next step file based on `lastStep`
+- IF Any other comments or queries: respond and redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions about current progress
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [current state confirmed], will you then load and read fully the appropriate next step file to resume the workflow.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All previous input documents successfully reloaded
+- Current workflow state accurately analyzed and presented
+- User confirms understanding of progress before continuation
+- Correct next step identified and prepared for loading
+- Proper continuation path determined based on `lastStep`
+
+### ❌ SYSTEM FAILURE:
+
+- Discovering new input documents instead of reloading existing ones
+- Modifying content from already completed steps
+- Loading wrong next step based on `lastStep` value
+- Proceeding without user confirmation of current state
+- Not maintaining context consistency from previous session
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.