refactor: centralize qa paths in core-config.yaml and update agent activation flows

2025-08-16 19:56:34 -05:00
parent ed539432fb
commit c58a4f3b59
19 changed files with 219 additions and 56 deletions
--- a/bmad-core/tasks/apply-qa-fixes.md
+++ b/bmad-core/tasks/apply-qa-fixes.md
@@ -0,0 +1,148 @@
+# apply-qa-fixes
+
+Implement fixes based on QA results (gate and assessments) for a specific story. This task is for the Dev agent to systematically consume QA outputs and apply code/test changes while only updating allowed sections in the story file.
+
+## Purpose
+
+- Read QA outputs for a story (gate YAML + assessment markdowns)
+- Create a prioritized, deterministic fix plan
+- Apply code and test changes to close gaps and address issues
+- Update only the allowed story sections for the Dev agent
+
+## Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}' # e.g., "2.2"
+  - qa_root: from `bmad-core/core-config.yaml` key `qa.qaLocation` (e.g., `docs/project/qa`)
+  - story_root: from `bmad-core/core-config.yaml` key `devStoryLocation` (e.g., `docs/project/stories`)
+
+optional:
+  - story_title: '{title}' # derive from story H1 if missing
+  - story_slug: '{slug}' # derive from title (lowercase, hyphenated) if missing
+```
+
+## QA Sources to Read
+
+- Gate (YAML): `{qa_root}/gates/{epic}.{story}-*.yml`
+  - If multiple, use the most recent by modified time
+- Assessments (Markdown):
+  - Test Design: `{qa_root}/assessments/{epic}.{story}-test-design-*.md`
+  - Traceability: `{qa_root}/assessments/{epic}.{story}-trace-*.md`
+  - Risk Profile: `{qa_root}/assessments/{epic}.{story}-risk-*.md`
+  - NFR Assessment: `{qa_root}/assessments/{epic}.{story}-nfr-*.md`
+
+## Prerequisites
+
+- Repository builds and tests run locally (Deno 2)
+- Lint and test commands available:
+  - `deno lint`
+  - `deno test -A`
+
+## Process (Do not skip steps)
+
+### 0) Load Core Config & Locate Story
+
+- Read `bmad-core/core-config.yaml` and resolve `qa_root` and `story_root`
+- Locate story file in `{story_root}/{epic}.{story}.*.md`
+  - HALT if missing and ask for correct story id/path
+
+### 1) Collect QA Findings
+
+- Parse the latest gate YAML:
+  - `gate` (PASS|CONCERNS|FAIL|WAIVED)
+  - `top_issues[]` with `id`, `severity`, `finding`, `suggested_action`
+  - `nfr_validation.*.status` and notes
+  - `trace` coverage summary/gaps
+  - `test_design.coverage_gaps[]`
+  - `risk_summary.recommendations.must_fix[]` (if present)
+- Read any present assessment markdowns and extract explicit gaps/recommendations
+
+### 2) Build Deterministic Fix Plan (Priority Order)
+
+Apply in order, highest priority first:
+
+1. High severity items in `top_issues` (security/perf/reliability/maintainability)
+2. NFR statuses: all FAIL must be fixed → then CONCERNS
+3. Test Design `coverage_gaps` (prioritize P0 scenarios if specified)
+4. Trace uncovered requirements (AC-level)
+5. Risk `must_fix` recommendations
+6. Medium severity issues, then low
+
+Guidance:
+
+- Prefer tests closing coverage gaps before/with code changes
+- Keep changes minimal and targeted; follow project architecture and TS/Deno rules
+
+### 3) Apply Changes
+
+- Implement code fixes per plan
+- Add missing tests to close coverage gaps (unit first; integration where required by AC)
+- Keep imports centralized via `deps.ts` (see `docs/project/typescript-rules.md`)
+- Follow DI boundaries in `src/core/di.ts` and existing patterns
+
+### 4) Validate
+
+- Run `deno lint` and fix issues
+- Run `deno test -A` until all tests pass
+- Iterate until clean
+
+### 5) Update Story (Allowed Sections ONLY)
+
+CRITICAL: Dev agent is ONLY authorized to update these sections of the story file. Do not modify any other sections (e.g., QA Results, Story, Acceptance Criteria, Dev Notes, Testing):
+
+- Tasks / Subtasks Checkboxes (mark any fix subtask you added as done)
+- Dev Agent Record →
+  - Agent Model Used (if changed)
+  - Debug Log References (commands/results, e.g., lint/tests)
+  - Completion Notes List (what changed, why, how)
+  - File List (all added/modified/deleted files)
+- Change Log (new dated entry describing applied fixes)
+- Status (see Rule below)
+
+Status Rule:
+
+- If gate was PASS and all identified gaps are closed → set `Status: Ready for Done`
+- Otherwise → set `Status: Ready for Review` and notify QA to re-run the review
+
+### 6) Do NOT Edit Gate Files
+
+- Dev does not modify gate YAML. If fixes address issues, request QA to re-run `review-story` to update the gate
+
+## Blocking Conditions
+
+- Missing `bmad-core/core-config.yaml`
+- Story file not found for `story_id`
+- No QA artifacts found (neither gate nor assessments)
+  - HALT and request QA to generate at least a gate file (or proceed only with clear developer-provided fix list)
+
+## Completion Checklist
+
+- deno lint: 0 problems
+- deno test -A: all tests pass
+- All high severity `top_issues` addressed
+- NFR FAIL → resolved; CONCERNS minimized or documented
+- Coverage gaps closed or explicitly documented with rationale
+- Story updated (allowed sections only) including File List and Change Log
+- Status set according to Status Rule
+
+## Example: Story 2.2
+
+Given gate `docs/project/qa/gates/2.2-*.yml` shows
+
+- `coverage_gaps`: Back action behavior untested (AC2)
+- `coverage_gaps`: Centralized dependencies enforcement untested (AC4)
+
+Fix plan:
+
+- Add a test ensuring the Toolkit Menu "Back" action returns to Main Menu
+- Add a static test verifying imports for service/view go through `deps.ts`
+- Re-run lint/tests and update Dev Agent Record + File List accordingly
+
+## Key Principles
+
+- Deterministic, risk-first prioritization
+- Minimal, maintainable changes
+- Tests validate behavior and close gaps
+- Strict adherence to allowed story update areas
+- Gate ownership remains with QA; Dev signals readiness via Status
--- a/bmad-core/tasks/nfr-assess.md
+++ b/bmad-core/tasks/nfr-assess.md
@@ -7,11 +7,11 @@ Quick NFR validation focused on the core four: security, performance, reliabilit
 ```yaml
 required:
  - story_id: '{epic}.{story}' # e.g., "1.3"
-  - story_path: 'docs/stories/{epic}.{story}.*.md'
+  - story_path: `bmad-core/core-config.yaml` for the `devStoryLocation`

 optional:
-  - architecture_refs: 'docs/architecture/*.md'
-  - technical_preferences: 'docs/technical-preferences.md'
+  - architecture_refs: `bmad-core/core-config.yaml` for the `architecture.architectureFile`
+  - technical_preferences: `bmad-core/core-config.yaml` for the `technicalPreferences`
  - acceptance_criteria: From story file
 ```

@@ -20,7 +20,7 @@ optional:
 Assess non-functional requirements for a story and generate:

 1. YAML block for the gate file's `nfr_validation` section
-2. Brief markdown assessment saved to `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`
+2. Brief markdown assessment saved to `qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`

 ## Process

@@ -123,7 +123,7 @@ If `technical-preferences.md` defines custom weights, use those instead.

 ## Output 2: Brief Assessment Report

-**ALWAYS save to:** `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`
+**ALWAYS save to:** `qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`

 ```markdown
 # NFR Assessment: {epic}.{story}
@@ -162,7 +162,7 @@ Reviewer: Quinn
 **End with this line for the review task to quote:**

 ```
-NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
+NFR assessment: qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
 ```

 ## Output 4: Gate Integration Line
@@ -170,7 +170,7 @@ NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
 **Always print at the end:**

 ```
-Gate NFR block ready → paste into docs/qa/gates/{epic}.{story}-{slug}.yml under nfr_validation
+Gate NFR block ready → paste into qa.qaLocation/gates/{epic}.{story}-{slug}.yml under nfr_validation
 ```

 ## Assessment Criteria
--- a/bmad-core/tasks/qa-gate.md
+++ b/bmad-core/tasks/qa-gate.md
@@ -14,7 +14,7 @@ Generate a standalone quality gate file that provides a clear pass/fail decision

 ## Gate File Location

-**ALWAYS** create file at: `docs/qa/gates/{epic}.{story}-{slug}.yml`
+**ALWAYS** check the `bmad-core/core-config.yaml` for the `qa.qaLocation/gates`

 Slug rules:

@@ -124,11 +124,13 @@ waiver:

 ## Output Requirements

-1. **ALWAYS** create gate file at: `docs/qa/gates/{epic}.{story}-{slug}.yml`
+1. **ALWAYS** create gate file at: `qa.qaLocation/gates` from `bmad-core/core-config.yaml`
 2. **ALWAYS** append this exact format to story's QA Results section:
+
+   ```text
+   Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
   ```
-   Gate: {STATUS} → docs/qa/gates/{epic}.{story}-{slug}.yml
-   ```
+
 3. Keep status_reason to 1-2 sentences maximum
 4. Use severity values exactly: `low`, `medium`, or `high`

@@ -147,7 +149,7 @@ After creating gate file, append to story's QA Results section:

 ### Gate Status

-Gate: CONCERNS → docs/qa/gates/1.3-user-auth-login.yml
+Gate: CONCERNS → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
 ```

 ## Key Principles
--- a/bmad-core/tasks/review-story.md
+++ b/bmad-core/tasks/review-story.md
@@ -167,9 +167,9 @@ After review and any refactoring, append your results to the story file in the Q

 ### Gate Status

-Gate: {STATUS} → docs/qa/gates/{epic}.{story}-{slug}.yml
-Risk profile: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
-NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
+Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
+Risk profile: qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+NFR assessment: qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md

 # Note: Paths should reference core-config.yaml for custom configurations

@@ -183,9 +183,9 @@ NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md

 **Template and Directory:**

- Render from `templates/qa-gate-tmpl.yaml`
- Create `docs/qa/gates/` directory if missing (or configure in core-config.yaml)
- Save to: `docs/qa/gates/{epic}.{story}-{slug}.yml`
+- Render from `../templates/qa-gate-tmpl.yaml`
+- Create directory defined in `qa.qaLocation/gates` (see `bmad-core/core-config.yaml`) if missing
+- Save to: `qa.qaLocation/gates/{epic}.{story}-{slug}.yml`

 Gate file structure:

@@ -308,7 +308,7 @@ Stop the review and request clarification if:
 After review:

 1. Update the QA Results section in the story file
-2. Create the gate file in `docs/qa/gates/`
+2. Create the gate file in directory from `qa.qaLocation/gates`
 3. Recommend status: "Ready for Done" or "Changes Required" (owner decides)
 4. If files were modified, list them in QA Results and ask Dev to update File List
 5. Always provide constructive feedback and actionable recommendations
--- a/bmad-core/tasks/risk-profile.md
+++ b/bmad-core/tasks/risk-profile.md
@@ -105,7 +105,7 @@ Evaluate each risk using probability × impact:
 - `Medium (2)`: Moderate consequences (degraded performance, minor data issues)
 - `Low (1)`: Minor consequences (cosmetic issues, slight inconvenience)

-**Risk Score = Probability × Impact**
+### Risk Score = Probability × Impact

 - 9: Critical Risk (Red)
 - 6: High Risk (Orange)
@@ -182,7 +182,7 @@ risk_summary:

 ### Output 2: Markdown Report

-**Save to:** `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`

 ```markdown
 # Risk Profile: Story {epic}.{story}
@@ -290,7 +290,7 @@ Review and update risk profile when:

 Calculate overall story risk score:

-```
+```text
 Base Score = 100
 For each risk:
  - Critical (9): Deduct 20 points
@@ -339,8 +339,8 @@ Based on risk profile, recommend:

 **Print this line for review task to quote:**

-```
-Risk profile: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+```text
+Risk profile: qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
 ```

 ## Key Principles
--- a/bmad-core/tasks/test-design.md
+++ b/bmad-core/tasks/test-design.md
@@ -84,7 +84,7 @@ Ensure:

 ### Output 1: Test Design Document

-**Save to:** `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`

 ```markdown
 # Test Design: Story {epic}.{story}
@@ -150,7 +150,7 @@ test_design:
 Print for use by trace-requirements task:

 ```text
-Test design matrix: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
+Test design matrix: qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
 P0 tests identified: {count}
 ```

--- a/bmad-core/tasks/trace-requirements.md
+++ b/bmad-core/tasks/trace-requirements.md
@@ -95,16 +95,16 @@ trace:
    full: Y
    partial: Z
    none: W
-  planning_ref: 'docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md'
+  planning_ref: 'qa.qaLocation/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'
+  notes: 'See qa.qaLocation/assessments/{epic}.{story}-trace-{YYYYMMDD}.md'
 ```

 ### Output 2: Traceability Report

-**Save to:** `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`

 Create a traceability report with:

@@ -250,7 +250,7 @@ This traceability feeds into quality gates:
 **Print this line for review task to quote:**

 ```text
-Trace matrix: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
+Trace matrix: qa.qaLocation/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
 ```

 - Full coverage → PASS contribution