bmad-method 4.37.0-beta.6 → 5.0.0-beta.1

package/bmad-core/tasks/trace-requirements.md

@@ -0,0 +1,264 @@
+# trace-requirements
+
+Map story requirements to test cases using Given-When-Then patterns for comprehensive traceability.
+
+## Purpose
+
+Create a requirements traceability matrix that ensures every acceptance criterion has corresponding test coverage. This task helps identify gaps in testing and ensures all requirements are validated.
+
+**IMPORTANT**: Given-When-Then is used here for documenting the mapping between requirements and tests, NOT for writing the actual test code. Tests should follow your project's testing standards (no BDD syntax in test code).
+
+## Prerequisites
+
+- Story file with clear acceptance criteria
+- Access to test files or test specifications
+- Understanding of the implementation
+
+## Traceability Process
+
+### 1. Extract Requirements
+
+Identify all testable requirements from:
+
+- Acceptance Criteria (primary source)
+- User story statement
+- Tasks/subtasks with specific behaviors
+- Non-functional requirements mentioned
+- Edge cases documented
+
+### 2. Map to Test Cases
+
+For each requirement, document which tests validate it. Use Given-When-Then to describe what the test validates (not how it's written):
+
+```yaml
+requirement: "AC1: User can login with valid credentials"
+test_mappings:
+  - test_file: "auth/login.test.ts"
+    test_case: "should successfully login with valid email and password"
+    # Given-When-Then describes WHAT the test validates, not HOW it's coded
+    given: "A registered user with valid credentials"
+    when: "They submit the login form"
+    then: "They are redirected to dashboard and session is created"
+    coverage: full
+
+  - test_file: "e2e/auth-flow.test.ts"
+    test_case: "complete login flow"
+    given: "User on login page"
+    when: "Entering valid credentials and submitting"
+    then: "Dashboard loads with user data"
+    coverage: integration
+```
+
+### 3. Coverage Analysis
+
+Evaluate coverage for each requirement:
+
+**Coverage Levels:**
+
+- `full`: Requirement completely tested
+- `partial`: Some aspects tested, gaps exist
+- `none`: No test coverage found
+- `integration`: Covered in integration/e2e tests only
+- `unit`: Covered in unit tests only
+
+### 4. Gap Identification
+
+Document any gaps found:
+
+```yaml
+coverage_gaps:
+  - requirement: "AC3: Password reset email sent within 60 seconds"
+    gap: "No test for email delivery timing"
+    severity: medium
+    suggested_test:
+      type: integration
+      description: "Test email service SLA compliance"
+
+  - requirement: "AC5: Support 1000 concurrent users"
+    gap: "No load testing implemented"
+    severity: high
+    suggested_test:
+      type: performance
+      description: "Load test with 1000 concurrent connections"
+```
+
+## Outputs
+
+### Output 1: Gate YAML Block
+
+**Generate for pasting into gate file under `trace`:**
+
+```yaml
+trace:
+  totals:
+    requirements: X
+    full: Y
+    partial: Z
+    none: W
+  planning_ref: "docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md"
+  uncovered:
+    - ac: "AC3"
+      reason: "No test found for password reset timing"
+  notes: "See docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md"
+```
+
+### Output 2: Traceability Report
+
+**Save to:** `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`
+
+Create a traceability report with:
+
+```markdown
+# Requirements Traceability Matrix
+
+## Story: {epic}.{story} - {title}
+
+### Coverage Summary
+
+- Total Requirements: X
+- Fully Covered: Y (Z%)
+- Partially Covered: A (B%)
+- Not Covered: C (D%)
+
+### Requirement Mappings
+
+#### AC1: {Acceptance Criterion 1}
+
+**Coverage: FULL**
+
+Given-When-Then Mappings:
+
+- **Unit Test**: `auth.service.test.ts::validateCredentials`
+  - Given: Valid user credentials
+  - When: Validation method called
+  - Then: Returns true with user object
+
+- **Integration Test**: `auth.integration.test.ts::loginFlow`
+  - Given: User with valid account
+  - When: Login API called
+  - Then: JWT token returned and session created
+
+#### AC2: {Acceptance Criterion 2}
+
+**Coverage: PARTIAL**
+
+[Continue for all ACs...]
+
+### Critical Gaps
+
+1. **Performance Requirements**
+   - Gap: No load testing for concurrent users
+   - Risk: High - Could fail under production load
+   - Action: Implement load tests using k6 or similar
+
+2. **Security Requirements**
+   - Gap: Rate limiting not tested
+   - Risk: Medium - Potential DoS vulnerability
+   - Action: Add rate limit tests to integration suite
+
+### Test Design Recommendations
+
+Based on gaps identified, recommend:
+
+1. Additional test scenarios needed
+2. Test types to implement (unit/integration/e2e/performance)
+3. Test data requirements
+4. Mock/stub strategies
+
+### Risk Assessment
+
+- **High Risk**: Requirements with no coverage
+- **Medium Risk**: Requirements with only partial coverage
+- **Low Risk**: Requirements with full unit + integration coverage
+```
+
+## Traceability Best Practices
+
+### Given-When-Then for Mapping (Not Test Code)
+
+Use Given-When-Then to document what each test validates:
+
+**Given**: The initial context the test sets up
+
+- What state/data the test prepares
+- User context being simulated
+- System preconditions
+
+**When**: The action the test performs
+
+- What the test executes
+- API calls or user actions tested
+- Events triggered
+
+**Then**: What the test asserts
+
+- Expected outcomes verified
+- State changes checked
+- Values validated
+
+**Note**: This is for documentation only. Actual test code follows your project's standards (e.g., describe/it blocks, no BDD syntax).
+
+### Coverage Priority
+
+Prioritize coverage based on:
+
+1. Critical business flows
+2. Security-related requirements
+3. Data integrity requirements
+4. User-facing features
+5. Performance SLAs
+
+### Test Granularity
+
+Map at appropriate levels:
+
+- Unit tests for business logic
+- Integration tests for component interaction
+- E2E tests for user journeys
+- Performance tests for NFRs
+
+## Quality Indicators
+
+Good traceability shows:
+
+- Every AC has at least one test
+- Critical paths have multiple test levels
+- Edge cases are explicitly covered
+- NFRs have appropriate test types
+- Clear Given-When-Then for each test
+
+## Red Flags
+
+Watch for:
+
+- ACs with no test coverage
+- Tests that don't map to requirements
+- Vague test descriptions
+- Missing edge case coverage
+- NFRs without specific tests
+
+## Integration with Gates
+
+This traceability feeds into quality gates:
+
+- Critical gaps → FAIL
+- Minor gaps → CONCERNS
+- Missing P0 tests from test-design → CONCERNS
+
+### Output 3: Story Hook Line
+
+**Print this line for review task to quote:**
+
+```text
+Trace matrix: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
+```
+
+- Full coverage → PASS contribution
+
+## Key Principles
+
+- Every requirement must be testable
+- Use Given-When-Then for clarity
+- Identify both presence and absence
+- Prioritize based on risk
+- Make recommendations actionable

package/bmad-core/templates/qa-gate-tmpl.yaml

@@ -0,0 +1,102 @@
+template:
+  id: qa-gate-template-v1
+  name: Quality Gate Decision
+  version: 1.0
+  output:
+    format: yaml
+    filename: docs/qa/gates/{{epic_num}}.{{story_num}}-{{story_slug}}.yml
+    title: "Quality Gate: {{epic_num}}.{{story_num}}"
+
+# Required fields (keep these first)
+schema: 1
+story: "{{epic_num}}.{{story_num}}"
+story_title: "{{story_title}}"
+gate: "{{gate_status}}"  # PASS|CONCERNS|FAIL|WAIVED
+status_reason: "{{status_reason}}"  # 1-2 sentence summary of why this gate decision
+reviewer: "Quinn (Test Architect)"
+updated: "{{iso_timestamp}}"
+
+# Always present but only active when WAIVED
+waiver: { active: false }
+
+# Issues (if any) - Use fixed severity: low | medium | high
+top_issues: []
+
+# Risk summary (from risk-profile task if run)
+risk_summary:
+  totals: { critical: 0, high: 0, medium: 0, low: 0 }
+  recommendations:
+    must_fix: []
+    monitor: []
+
+# Examples section using block scalars for clarity
+examples:
+  with_issues: |
+    top_issues:
+      - id: "SEC-001"
+        severity: high  # ONLY: low|medium|high
+        finding: "No rate limiting on login endpoint"
+        suggested_action: "Add rate limiting middleware before production"
+      - id: "TEST-001"  
+        severity: medium
+        finding: "Missing integration tests for auth flow"
+        suggested_action: "Add test coverage for critical paths"
+  
+  when_waived: |
+    waiver:
+      active: true
+      reason: "Accepted for MVP release - will address in next sprint"
+      approved_by: "Product Owner"
+
+# ============ Optional Extended Fields ============
+# Uncomment and use if your team wants more detail
+
+optional_fields_examples:
+  quality_and_expiry: |
+    quality_score: 75  # 0-100 (optional scoring)
+    expires: "2025-01-26T00:00:00Z"  # Optional gate freshness window
+  
+  evidence: |
+    evidence:
+      tests_reviewed: 15
+      risks_identified: 3
+      trace:
+        ac_covered: [1, 2, 3]  # AC numbers with test coverage
+        ac_gaps: [4]  # AC numbers lacking coverage
+  
+  nfr_validation: |
+    nfr_validation:
+      security: { status: CONCERNS, notes: "Rate limiting missing" }
+      performance: { status: PASS, notes: "" }
+      reliability: { status: PASS, notes: "" }
+      maintainability: { status: PASS, notes: "" }
+  
+  history: |
+    history:  # Append-only audit trail
+      - at: "2025-01-12T10:00:00Z"
+        gate: FAIL
+        note: "Initial review - missing tests"
+      - at: "2025-01-12T15:00:00Z"  
+        gate: CONCERNS
+        note: "Tests added but rate limiting still missing"
+  
+  risk_summary: |
+    risk_summary:  # From risk-profile task
+      totals:
+        critical: 0
+        high: 0
+        medium: 0
+        low: 0
+      # 'highest' is emitted only when risks exist
+      recommendations:
+        must_fix: []
+        monitor: []
+  
+  recommendations: |
+    recommendations:
+      immediate:  # Must fix before production
+        - action: "Add rate limiting to auth endpoints"
+          refs: ["api/auth/login.ts:42-68"]
+      future:  # Can be addressed later
+        - action: "Consider caching for better performance"
+          refs: ["services/data.service.ts"]

package/common/tasks/execute-checklist.md

@@ -9,7 +9,6 @@ If the user asks or does not specify a specific checklist, list the checklists a
 ## Instructions
 
 1. **Initial Assessment**
-
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
@@ -22,14 +21,12 @@ If the user asks or does not specify a specific checklist, list the checklists a
      - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
 
 2. **Document and Artifact Gathering**
-
    - Each checklist will specify its required documents/artifacts at the beginning
    - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
 
 3. **Checklist Processing**
 
    If in interactive mode:
-
    - Work through each section of the checklist one at a time
    - For each section:
      - Review all items in the section following instructions for that section embedded in the checklist
@@ -38,7 +35,6 @@ If the user asks or does not specify a specific checklist, list the checklists a
      - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
 
    If in YOLO mode:
-
    - Process all sections at once
    - Create a comprehensive report of all findings
    - Present the complete analysis to the user
@@ -46,7 +42,6 @@ If the user asks or does not specify a specific checklist, list the checklists a
 4. **Validation Approach**
 
    For each checklist item:
-
    - Read and understand the requirement
    - Look for evidence in the documentation that satisfies the requirement
    - Consider both explicit mentions and implicit coverage
@@ -60,7 +55,6 @@ If the user asks or does not specify a specific checklist, list the checklists a
 5. **Section Analysis**
 
    For each section:
-
    - think step by step to calculate pass rate
    - Identify common themes in failed items
    - Provide specific recommendations for improvement
@@ -70,7 +64,6 @@ If the user asks or does not specify a specific checklist, list the checklists a
 6. **Final Report**
 
    Prepare a summary that includes:
-
    - Overall checklist completion status
    - Pass rates by section
    - List of failed items with context

package/dist/agents/analyst.txt

@@ -149,7 +149,7 @@ If user selects Option 1, present numbered list of techniques from the brainstor
 1. Apply selected technique according to data file description
 2. Keep engaging with technique until user indicates they want to:
    - Choose a different technique
-   - Apply current ideas to a new technique  
+   - Apply current ideas to a new technique
    - Move to convergent phase
    - End session
 
@@ -266,63 +266,54 @@ CRITICAL: First, help the user select the most appropriate research focus based
 Present these numbered options to the user:
 
 1. **Product Validation Research**
-
    - Validate product hypotheses and market fit
    - Test assumptions about user needs and solutions
    - Assess technical and business feasibility
    - Identify risks and mitigation strategies
 
 2. **Market Opportunity Research**
-
    - Analyze market size and growth potential
    - Identify market segments and dynamics
    - Assess market entry strategies
    - Evaluate timing and market readiness
 
 3. **User & Customer Research**
-
    - Deep dive into user personas and behaviors
    - Understand jobs-to-be-done and pain points
    - Map customer journeys and touchpoints
    - Analyze willingness to pay and value perception
 
 4. **Competitive Intelligence Research**
-
    - Detailed competitor analysis and positioning
    - Feature and capability comparisons
    - Business model and strategy analysis
    - Identify competitive advantages and gaps
 
 5. **Technology & Innovation Research**
-
    - Assess technology trends and possibilities
    - Evaluate technical approaches and architectures
    - Identify emerging technologies and disruptions
    - Analyze build vs. buy vs. partner options
 
 6. **Industry & Ecosystem Research**
-
    - Map industry value chains and dynamics
    - Identify key players and relationships
    - Analyze regulatory and compliance factors
    - Understand partnership opportunities
 
 7. **Strategic Options Research**
-
    - Evaluate different strategic directions
    - Assess business model alternatives
    - Analyze go-to-market strategies
    - Consider expansion and scaling paths
 
 8. **Risk & Feasibility Research**
-
    - Identify and assess various risk factors
    - Evaluate implementation challenges
    - Analyze resource requirements
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
@@ -491,13 +482,11 @@ CRITICAL: collaborate with the user to develop specific, actionable research que
 ### 5. Review and Refinement
 
 1. **Present Complete Prompt**
-
    - Show the full research prompt
    - Explain key elements and rationale
    - Highlight any assumptions made
 
 2. **Gather Feedback**
-
    - Are the objectives clear and correct?
    - Do the questions address all concerns?
    - Is the scope appropriate?
@@ -872,9 +861,9 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 
 ### Change Log
 
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
+| Date   | Version | Description                 | Author    |
+| ------ | ------- | --------------------------- | --------- |
+| [Date] | 1.0     | Initial brownfield analysis | [Analyst] |
 
 ## Quick Reference - Key Files and Entry Points
 
@@ -897,11 +886,11 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 
 ### Actual Tech Stack (from package.json/requirements.txt)
 
-| Category | Technology | Version | Notes |
-|----------|------------|---------|--------|
-| Runtime | Node.js | 16.x | [Any constraints] |
-| Framework | Express | 4.18.2 | [Custom middleware?] |
-| Database | PostgreSQL | 13 | [Connection pooling setup] |
+| Category  | Technology | Version | Notes                      |
+| --------- | ---------- | ------- | -------------------------- |
+| Runtime   | Node.js    | 16.x    | [Any constraints]          |
+| Framework | Express    | 4.18.2  | [Custom middleware?]       |
+| Database  | PostgreSQL | 13      | [Connection pooling setup] |
 
 etc...
 
@@ -940,6 +929,7 @@ project-root/
 ### Data Models
 
 Instead of duplicating, reference actual model files:
+
 - **User Model**: See `src/models/User.js`
 - **Order Model**: See `src/models/Order.js`
 - **Related Types**: TypeScript definitions in `src/types/`
@@ -969,10 +959,10 @@ Instead of duplicating, reference actual model files:
 
 ### External Services
 
-| Service | Purpose | Integration Type | Key Files |
-|---------|---------|------------------|-----------|
-| Stripe | Payments | REST API | `src/integrations/stripe/` |
-| SendGrid | Emails | SDK | `src/services/emailService.js` |
+| Service  | Purpose  | Integration Type | Key Files                      |
+| -------- | -------- | ---------------- | ------------------------------ |
+| Stripe   | Payments | REST API         | `src/integrations/stripe/`     |
+| SendGrid | Emails   | SDK              | `src/services/emailService.js` |
 
 etc...
 
@@ -1017,6 +1007,7 @@ npm run test:integration  # Runs integration tests (requires local DB)
 ### Files That Will Need Modification
 
 Based on the enhancement requirements, these files will be affected:
+
 - `src/services/userService.js` - Add new user fields
 - `src/models/User.js` - Update schema
 - `src/routes/userRoutes.js` - New endpoints
@@ -2581,7 +2572,7 @@ Each status change requires user verification and approval before proceeding.
 #### Greenfield Development
 
 - Business analysis and market research
-- Product requirements and feature definition  
+- Product requirements and feature definition
 - System architecture and design
 - Development execution
 - Testing and deployment
@@ -2690,8 +2681,11 @@ Templates with Level 2 headings (`##`) can be automatically sharded:
 
 ```markdown
 ## Goals and Background Context
-## Requirements  
+
+## Requirements
+
 ## User Interface Design Goals
+
 ## Success Metrics
 ```