--- --- # Step 3: Implement ## RULES - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` - No push. No remote ops. - Sequential execution only. - Content inside `` in `{spec_file}` is read-only. Do not modify. ## PRECONDITION Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding. ## INSTRUCTIONS ### Pre-Implementation Check **CRITICAL: Calculate structural blast radius and obtain human approval before ANY code modification. NEVER skip this check.** 1. **Identify targets**: Extract the symbols and files being modified from `{spec_file}` — the `## Code Map` section lists target files and their roles. 2. **Calculate blast radius with built-in summarization and freshness check**: For each target symbol, call the memtrace-adapter: `node _bmad/scripts/memtrace/memtrace-adapter.mjs --target --query get_impact --check-freshness --summarize`. The adapter verifies index freshness (via `--check-freshness`) before the blast radius query — no separate `list_repos` call needed. Process targets SEQUENTIALLY using `for...of` — NEVER use `Promise.all`. On exit code 0: parse STDOUT JSON; use `summarized.critical_dependents`, `summarized.module_impact`, `summarized.total_affected`, and `summarized.token_estimate` for the Confidence Report (guaranteed ≤2000 tokens). Extract `affected_symbols` (raw) for qa-memtrace.mjs. On exit code 1: check STDERR for `[FRESHNESS]` (stale/missing index) vs `MEMTRACE_MCP_ERROR_TIMEOUT` (MCP unreachable) → HALT. 4. **Token budget already satisfied**: The adapter's `--summarize` flag guarantees the `summarized` field is under 2000 tokens. No manual summarization needed. Use `summarized.token_estimate` to confirm compliance. 5. **Present Blast Radius Confidence Report**: ``` ## Blast Radius Confidence Report **Target:** [symbol/file] **Risk Level:** [Low/Medium/High/Critical] **Affected Symbols:** N downstream dependents across M files ### Critical Dependents (Depth 1-2) - `symbol` in `file` — relationship ### Module Impact Summary - module: N symbols (High/Med/Low risk) ### Recommended Pre-Flight Checks - Review test coverage for: top modules - Pay special attention to: bridge/central symbols touched --- **Decision Required:** Modify [target]? [A] Approve / [R] Reject ``` 5a. **Generate Test Coverage Justification**: Before halting for user approval, map each affected module from the blast radius report to test files covering the impacted symbols: - Discover test files using conventions: `test/`, `__tests__/`, `*.test.*`, `*.spec.*` patterns — search/grep for affected symbol names in test files - Assign a coverage status per module: `Yes` (all covered), `Partial:N` (N of M covered), or `None` (no tests found) - Append the justification using this format after the "---" separator in the Confidence Report: ``` ### Test Coverage Justification | Module | Affected Symbols | Test Files | Coverage | |--------|-----------------|------------|----------| | `path/to/module` | N symbols | `test/module.test.ts` | Yes | | `path/to/other` | M symbols | — | **None** | **Coverage Summary:** - **Covered:** X/Y modules (Z affected symbols) - **Uncovered:** A/Y modules (B affected symbols — needs tests) - **Partial:** C/Y modules (D/N symbols covered) **Justification Notes:** - `module-A`: Covered by existing tests in `test/module-a.test.ts` - `module-B`: No test coverage found — requires new test file - `module-C`: Partial coverage — `test/module-c.test.ts` covers 3 of 5 impacted functions ``` - If the blast radius has zero affected modules, skip the justification and note "No affected modules to map" - Enforce combined token budget (blast radius + justification ≤ 2000 tokens). Prioritize: uncovered modules, then high-risk, then covered - Ask the user for a coverage threshold percentage (0 = never block, 100 = block if any uncovered); default to flag-only mode if declined - Write the full Test Coverage Justification into `{spec_file}`'s completion notes section before proceeding 5b. **Execute Mathematical Quality Gate (Phase 2)**: If the blast radius has zero affected modules (empty result from get_impact), skip this step and note "Mathematical Quality Gate: SKIPPED (empty blast radius)." Otherwise: - Serialize the blast radius data and test coverage data to temporary JSON files in the system temp directory - Use the user-provided coverage threshold (default 100 if none given) - Run: `node _bmad/scripts/memtrace/qa-memtrace.mjs --blast-radius --test-coverage --threshold ` - Read the script's STDOUT and capture its exit code - **If exit 0**: log the output to `{spec_file}` completion notes under "Mathematical Quality Gate Output" and continue - **If exit 1**: persist the output to `{spec_file}` completion notes, present the uncovered nodes, then HALT: "Mathematical quality gate failed. N of M required nodes are not covered by tests. Agent must write/update tests for the listed uncovered nodes before proceeding. Do NOT proceed until the quality gate passes." - The qa-memtrace.mjs exit code is the FINAL authority. Exit 1 is a HARD BLOCK on implementation. 5c. **Dead Code Pitfall Validation**: If the story involves dead-code removal (find_dead_code usage in context or tasks): - Call the memtrace-adapter: `node _bmad/scripts/memtrace/memtrace-adapter.mjs --target --query find_dead_code [--repo ]`. Process sequentially — NEVER use `Promise.all`. Parse the adapter's STDOUT JSON for the `symbols` array. - Serialize candidates to a temp JSON file. - Run: `node _bmad/scripts/memtrace/validate-dead-code.mjs --candidates ` - If exit 0: log output to `{spec_file}` completion notes as "Dead Code Pitfall Validation Report". Present SUSPECT entries for manual review. FALSE_POS and GHOST are ignored. - If exit 1: log error to completion notes and proceed without pitfall validation (error is logged, not a hard block). - Clean up temp files. - If story does NOT involve dead-code removal, skip this step entirely. 6. **HALT for decision**: Ask the user: "Decision: Proceed with modification? [A] Approve — proceed to implementation | [R] Reject — halt execution" - If **Approve**: Continue to the Baseline step below - If **Reject**: HALT — "Blast radius verification rejected. Execution halted. Please provide guidance." --- ### Baseline Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. ### Implement Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`. If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context. Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly. **Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case. ### Self-Check Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding. ## NEXT Read fully and follow `./step-04-review.md`