ma-agents 3.4.9 → 3.5.0

package/_bmad-output/implementation-artifacts/epic-15-adversarial-fixes.md

@@ -0,0 +1,287 @@
+# Epic 15: Adversarial Review — Fix Specification
+
+**Source:** Epic 15 adversarial review (2026-03-28)
+**Scope:** 9 actionable fixes across test infrastructure, migration safety, code hygiene
+**Priority:** Fixes are ordered by importance — complete them in sequence
+
+---
+
+## Fix 1: Add missing test file to npm test script
+
+**Finding:** `test/story-15-5-workflow-skills.test.js` (157 tests covering all 25 SRE/DevOps/Cyber/extension workflow conversions) is not listed in the `npm test` script in `package.json`. These tests never run in CI.
+
+**What to do:**
+1. Open `package.json`
+2. Find the `"test"` script in the `"scripts"` section
+3. Add `node test/story-15-5-workflow-skills.test.js` to the test chain, positioned after the other Epic 15 test files (after `convert-agents-to-skills.test.js` or `migration.test.js`)
+4. Run `npm test` to confirm all tests pass including the newly added file
+
+**Acceptance criteria:**
+- `npm test` executes `story-15-5-workflow-skills.test.js` and all 157 tests pass
+- No other test files are removed or reordered
+
+---
+
+## Fix 2: Fix 3 stale test assertions
+
+**Finding:** Epic 15 changed the module structure but left pre-existing test assertions pointing at the old structure. These are documented as discrepancies D2, D3, D4 in `_bmad-output/implementation-artifacts/15-8-validation-report.md`.
+
+### Fix 2a: `test/bmad-extension.test.js` — stale module.yaml name assertion (D2)
+
+1. Open `test/bmad-extension.test.js`
+2. Find the assertion that checks the `name` field of `lib/bmad-extension/module.yaml`
+3. The old expected value will reference the pre-6.2.1 module name
+4. Update it to match the current value in `lib/bmad-extension/module.yaml`, which is: `"MA-Agents Skills & Agents"`
+5. Run this test file to confirm it passes
+
+### Fix 2b: `test/extension-module-restructure.test.js` — stale agents/ directory assertions (D3)
+
+1. Open `test/extension-module-restructure.test.js`
+2. Find assertions that expect `lib/bmad-extension/agents/` directory to exist or contain files
+3. This directory was deleted in Story 15.6. Remove or update these assertions:
+   - If the assertion checks that `agents/` exists → remove it
+   - If it counts files in `agents/` → remove it
+   - If it checks that specific `.customize.yaml` files exist in `agents/` → remove those specific checks
+4. Do NOT remove assertions about `skills/` or other directories that still exist
+5. Run this test file to confirm it passes
+
+### Fix 2c: `test/yes-flag.test.js` — environment-dependent flakiness (D4)
+
+1. Open `test/yes-flag.test.js`
+2. Identify the flaky test (it will be environment-dependent — likely depends on npm/node version, temp directory availability, or network access)
+3. If the test relies on external state (network, specific paths), make it self-contained by:
+   - Mocking the external dependency, OR
+   - Adding a guard that skips the test with a clear message when the prerequisite is unavailable
+4. Run the test file 3 times to confirm it passes consistently
+
+**Acceptance criteria:**
+- All three test files pass cleanly
+- No unrelated assertions were modified
+- `npm test` passes end-to-end
+
+---
+
+## Fix 3: Retain migration backup directory until next successful install
+
+**Finding:** `cleanupLegacyArtifacts()` in `lib/bmad.js` deletes `.backup-pre-migration/` immediately after `mergeUserCustomizations()` runs. If the merge produced corrupt output (e.g., invalid YAML from user content with special characters), the backup is permanently destroyed. The rollback safety net (NFR29) only covers the update step, not a botched merge.
+
+**What to do:**
+1. Open `lib/bmad.js`
+2. Find `cleanupLegacyArtifacts()` — it has three cleanup targets: old XML agents, legacy workflow YAML, and the backup directory
+3. **Remove the backup directory cleanup from `cleanupLegacyArtifacts()`** — specifically, remove or comment out the section that deletes `.backup-pre-migration/`
+4. Instead, move backup directory cleanup to the **beginning** of `backupCustomizations()` — so the old backup is only deleted when a NEW backup is about to be created (i.e., on the next migration/install run)
+5. Add a console log message when deleting a previous backup: `chalk.dim('Removing previous migration backup...')`
+
+**Implementation detail:**
+```
+In backupCustomizations():
+  1. Check if .backup-pre-migration/ already exists
+  2. If yes: log message, delete it
+  3. Proceed with creating new backup as before
+
+In cleanupLegacyArtifacts():
+  1. Keep old XML cleanup
+  2. Keep legacy YAML cleanup
+  3. REMOVE backup directory cleanup
+```
+
+6. Update `test/migration.test.js`:
+   - Add a test: after `cleanupLegacyArtifacts()` runs, `.backup-pre-migration/` directory still exists
+   - Add a test: `backupCustomizations()` removes a pre-existing `.backup-pre-migration/` before creating a new one
+   - Update any existing test that asserts `.backup-pre-migration/` is deleted by cleanup
+
+**Acceptance criteria:**
+- After a migration, `.backup-pre-migration/` is preserved on disk
+- On the NEXT migration run, the old backup is replaced with a fresh one
+- All migration tests pass
+
+---
+
+## Fix 4: Add output validation to mergeUserCustomizations()
+
+**Finding:** After merging user memories, custom critical_actions, and persona overrides into post-migration customize files, the function never validates that the resulting file is still parseable. A user persona containing YAML special characters (`:`, `#`, `{`, `>`, `|`) could produce corrupt output.
+
+**What to do:**
+1. Open `lib/bmad.js`, find `mergeUserCustomizations()`
+2. After writing each merged customize file, add a validation step:
+   - Re-read the file that was just written
+   - Run it through `parseCustomizeYaml()` (the same parser used to read it)
+   - If parsing fails or returns unexpected structure, log a warning and restore the pre-merge version from backup
+3. The validation logic should be:
+   ```
+   const merged = fs.readFileSync(targetPath, 'utf8');
+   const parsed = parseCustomizeYaml(merged);
+   if (!parsed || !parsed.criticalActions || parsed.criticalActions.length === 0) {
+     console.warn(chalk.yellow(`  ⚠ Merge produced invalid output for ${file}, restoring backup`));
+     fs.copyFileSync(backupPath, targetPath);
+     skipped.push(file);
+     continue;
+   }
+   ```
+4. Update `test/migration.test.js`:
+   - Add a test: merge with user content containing YAML special characters (`memories:\n  - "key: value with colons"`) produces valid output
+   - Add a test: if merge produces unparseable output, the backup copy is restored and the file is added to `skipped`
+
+**Acceptance criteria:**
+- `mergeUserCustomizations()` validates each merged file before moving on
+- Corrupt merges are caught and the backup is restored for that specific file
+- Migration continues for other files (doesn't abort entirely)
+- New tests cover the happy path and the corrupt-merge path
+
+---
+
+## Fix 5: Flag dead menu items in agent SKILL.md files
+
+**Finding:** Four agent menu items reference skills that were never implemented: `sre-health-check`, `sre-performance-opt`, `devops-optimize-pipelines`, `cyber-threat-modeling`. These are dead links that will confuse users.
+
+**What to do:**
+1. Edit `lib/bmad-extension/skills/bmad-ma-agent-sre/SKILL.md`:
+   - Find the menu table rows for "Health Check" (referencing `sre-health-check`) and "Performance Optimization" (referencing `sre-performance-opt`)
+   - Append ` *(not yet implemented)*` to the description column of each
+
+2. Edit `lib/bmad-extension/skills/bmad-ma-agent-devops/SKILL.md`:
+   - Find the menu table row for "Optimize Pipelines" (referencing `devops-optimize-pipelines`)
+   - Append ` *(not yet implemented)*` to the description column
+
+3. Edit `lib/bmad-extension/skills/bmad-ma-agent-cyber/SKILL.md`:
+   - Find the menu table row for "Threat Modeling" (referencing `cyber-threat-modeling`)
+   - Append ` *(not yet implemented)*` to the description column
+
+4. Update `test/migration-validation.test.js` if it has assertions that check these exact description strings — adjust expected values to include the new suffix
+
+**Acceptance criteria:**
+- All 4 dead menu items are visibly marked as not yet implemented
+- Agents still render menus correctly (no broken markdown)
+- Tests pass
+
+---
+
+## Fix 6: Remove redundant agent source files from lib/bmad-customizations/
+
+**Finding:** `lib/bmad-customizations/` still contains the original source files for all 4 migrated agents (`bmm-sre.customize.yaml`, `bmm-cyber.customize.yaml`, `bmm-devops.customize.yaml`, `bmm-mil498.customize.yaml`, plus `sre.md`, `cyber.md`, `devops.md`, `mil498.md`). These are superseded by the skill folders in `lib/bmad-extension/skills/bmad-ma-agent-*/`. No code reads from these paths for the migrated agents.
+
+**What to do:**
+1. First, **verify** that no code references these files:
+   - Search all `.js` files for `bmad-customizations/bmm-sre`, `bmad-customizations/bmm-cyber`, `bmad-customizations/bmm-devops`, `bmad-customizations/bmm-mil498`
+   - Search all `.js` files for `bmad-customizations/sre.md`, `bmad-customizations/cyber.md`, `bmad-customizations/devops.md`, `bmad-customizations/mil498.md`
+   - If ANY code still references these files, do NOT delete them — instead add a comment at the top of each: `# DEPRECATED: Canonical source is now lib/bmad-extension/skills/bmad-ma-agent-{name}/SKILL.md`
+
+2. If no code references them, delete these 8 files:
+   - `lib/bmad-customizations/bmm-sre.customize.yaml`
+   - `lib/bmad-customizations/bmm-cyber.customize.yaml`
+   - `lib/bmad-customizations/bmm-devops.customize.yaml`
+   - `lib/bmad-customizations/bmm-mil498.customize.yaml`
+   - `lib/bmad-customizations/sre.md`
+   - `lib/bmad-customizations/cyber.md`
+   - `lib/bmad-customizations/devops.md`
+   - `lib/bmad-customizations/mil498.md`
+
+3. Do NOT delete the other files in `lib/bmad-customizations/` (the platform-specific customize files like `claude-code.customize.yaml`, `cursor.customize.yaml`, etc.) — those serve a different purpose
+
+4. Update any test that asserts the existence or count of files in `lib/bmad-customizations/`
+
+**Acceptance criteria:**
+- No code references the deleted files
+- The 8 agent-specific files are removed (or deprecated if still referenced)
+- Platform-specific customize files are untouched
+- All tests pass
+
+---
+
+## Fix 7: Update story artifact statuses to match sprint status
+
+**Finding:** Stories 15.1 through 15.5 have `status: review` in their implementation artifact `.md` files, while the sprint status YAML says the entire epic is `done`. This inconsistency creates confusion about which source of truth to trust.
+
+**What to do:**
+1. Update the `status:` field in each of these files to `done`:
+   - `_bmad-output/implementation-artifacts/15-1-bump-bmad-method-to-6-2-1.md`
+   - `_bmad-output/implementation-artifacts/15-2-restructure-extension-module.md`
+   - `_bmad-output/implementation-artifacts/15-3-convert-custom-agents-to-skill-folders.md`
+   - `_bmad-output/implementation-artifacts/15-4-convert-mil498-workflows-to-skill-md.md`
+   - `_bmad-output/implementation-artifacts/15-5-convert-sre-devops-cyber-workflows.md`
+
+2. Look for a `status:` key in the YAML frontmatter or a `**Status:**` line in the markdown body — update whichever format the file uses
+
+**Acceptance criteria:**
+- All 8 story artifacts show status `done`
+- Sprint status YAML and individual story statuses agree
+
+---
+
+## Fix 8: Document compareVersions() limitations
+
+**Finding:** `compareVersions()` in `lib/bmad.js` only handles simple `X.Y.Z` numeric semver. It will mishandle pre-release versions, 4+ segments, leading zeros, and non-numeric segments. Since it gates whether migrations run, failures here are silent and consequential.
+
+**What to do:**
+1. Open `lib/bmad.js`, find `compareVersions()`
+2. Add a JSDoc comment above the function documenting its constraints:
+   ```javascript
+   /**
+    * Compare two semver version strings (X.Y.Z format only).
+    * Limitations: Does not support pre-release suffixes (e.g., 6.2.1-beta.1),
+    * versions with more than 3 segments, or non-numeric segments.
+    * Returns: -1 if a < b, 0 if equal, 1 if a > b.
+    */
+   ```
+3. Add a guard at the top of the function that logs a warning if either version doesn't match `/^\d+\.\d+\.\d+$/`:
+   ```javascript
+   const semverPattern = /^\d+\.\d+\.\d+$/;
+   if (!semverPattern.test(a) || !semverPattern.test(b)) {
+     console.warn(chalk.yellow(`Warning: Non-standard version format detected (${a} vs ${b}), comparison may be unreliable`));
+   }
+   ```
+4. Add a test in `test/migration.test.js`:
+   - `compareVersions('6.2.1-beta.1', '6.2.1')` — verify it doesn't crash (behavior can be undefined, but it must not throw)
+   - `compareVersions('6.2', '6.2.1')` — same, no crash
+
+**Acceptance criteria:**
+- Function has clear documentation of its limitations
+- Non-standard version inputs produce a warning, not a crash
+- Existing version comparisons continue to work identically
+
+---
+
+## Fix 9: Add basic merge integration test with adversarial YAML content
+
+**Finding:** No test feeds realistic/adversarial user content through the merge pipeline. The regex-based YAML parsing in `parseCustomizeYaml()` and the merge logic in `mergeUserCustomizations()` are untested against content containing colons, hashes, multi-line strings, and other YAML special characters.
+
+**What to do:**
+1. Open `test/migration.test.js`
+2. Add a new test section: `// Adversarial YAML content tests`
+3. Create a mock project where the backed-up customize file contains:
+   ```yaml
+   critical_actions:
+     - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+     - "Custom action: deploy to prod #important"
+   memories:
+     - "User prefers dark mode: always"
+     - "Last deploy was 2026-03-15 at 14:30"
+     - "Note: this has a colon in it"
+   persona:
+     role: "Senior SRE: Platform Team"
+     identity: "Expert in k8s | helm | terraform"
+   ```
+4. Run `mergeUserCustomizations()` against it
+5. Assert:
+   - The custom critical action (`"Custom action: deploy to prod #important"`) appears in the merged output
+   - All 3 memories appear in the merged output
+   - The persona with colons and pipes is preserved
+   - The merged file can be re-parsed by `parseCustomizeYaml()` without error
+6. Add a second test with a truly broken input (e.g., unbalanced quotes, bare `{` characters) to verify the function doesn't crash and handles it gracefully
+
+**Acceptance criteria:**
+- Adversarial YAML content survives the merge round-trip
+- Broken input is handled without crashing
+- All existing migration tests still pass
+
+---
+
+## Execution Notes
+
+- **Run `npm test` after each fix** to catch regressions early
+- Fixes 1-2 are pure test maintenance — no production code changes
+- Fixes 3-4 modify `lib/bmad.js` — be careful with the migration pipeline; don't break the happy path
+- Fix 5 modifies SKILL.md content files — verify markdown rendering
+- Fix 6 deletes files — the grep verification step is mandatory before deletion
+- Fixes 7-8 are documentation/metadata — lowest risk
+- Fix 9 is test-only — adds coverage without production code changes

package/_bmad-output/implementation-artifacts/epic-16-adversarial-review.md

@@ -0,0 +1,49 @@
+# Epic 16: Multi-Repository Project Layout -- Adversarial Review
+
+**Review Date:** 2026-03-28
+**Scope:** Stories 16.1, 16.2, 16.3, 16.4
+**Verdict:** Significant issues found -- not ready for dev without corrections
+
+---
+
+## Findings
+
+### Story 16.1: Repository Layout Wizard
+
+1. **Wrong prompt library referenced throughout the story.** The Dev Notes, code sample, and Key Implementation Constraint #1 all reference `inquirer` as the prompt library. The actual codebase uses `prompts` (the `prompts` npm package), not `inquirer`. See `bin/cli.js` line 3: `const prompts = require('prompts');` and `lib/installer.js` line 4. The `inquirer` package is never imported anywhere. The code sample uses `prompt({ type: 'list', ... })` which is `inquirer` syntax; `prompts` uses `type: 'select'` with `choices` as `{ title, value }` objects, not `{ name, value }`. The entire code pattern reference is wrong.
+
+2. **Story says to modify `cli.js` (root of project) but the actual file is at `bin/cli.js`.** The Dev Notes state "Primary file to modify: `cli.js` (root of project)" and the code sample says "In cli.js -- new wizard section after agent selection." The file is actually `bin/cli.js`. There is no `cli.js` at the project root. A developer would spend time looking for a file that does not exist at the stated location.
+
+3. **No git URL validation whatsoever.** AC #3 and Task 3.1 accept any string as a git URL. There is no validation that the URL is a plausible git remote. There is also no protection against command injection -- the URL is interpolated directly into an `execSync()` shell command. A malicious or mistyped URL containing shell metacharacters (e.g., `; rm -rf /`) would execute arbitrary commands. This is a **security vulnerability**. At minimum, the URL and path should be validated and shell-escaped, not merely quoted.
+
+4. **AC #5 (Local path) allows confirming a non-existent path, but consequences are undefined.** Task 2.3-2.4 say if the user confirms a non-existent path, store it anyway. But Story 16.2 will write this path into config.yaml, Story 16.3 stamps it into project-context.md, and Story 16.4 expects BMAD workflows to read from it. What happens when every downstream consumer tries to use a path that does not exist? There is no acceptance criterion for how the system should behave when a configured path is invalid at runtime.
+
+5. **No acceptance criterion or task for handling git authentication failures.** Task 3.7 says "Handle clone failure gracefully -- catch error, display message, ask user to retry or skip." But "skip" is undefined. If the user skips a failed clone, what is the state of the layout object? Is the mode still `remote` with no valid local path? Is it silently downgraded to `same`? The skip behavior is not specified and would leave the layout object in an inconsistent state.
+
+### Story 16.2: Config Storage and Cross-Reference File
+
+6. **Story 16.2 writes to `_bmad/core/config.yaml`, but BMAD workflows read from `_bmad/bmm/config.yaml`.** Every single workflow.yaml in the codebase uses `config_source: "{project-root}/_bmad/bmm/config.yaml"`, and SKILL.md extension files also instruct agents to "Load and read `{project-root}/_bmad/bmm/config.yaml`." The story writes `knowledgebase_path` and `sprint_management_path` to `_bmad/core/config.yaml`, but no workflow or agent reads from that file for operational config. Unless BMAD workflows are modified to also read `_bmad/core/config.yaml` (not specified anywhere in these four stories), the paths written will be invisible to consumers. This is a **fundamental architectural disconnect**.
+
+7. **Stale `project-layout.yaml` problem is unaddressed.** Task 3.2 explicitly says "leave it in place (do not delete -- user may switch back)." This means if a user switches from multi-repo to single-repo, a stale `project-layout.yaml` with old paths remains. Agents reading that file (per Story 16.4 AC #4) would use outdated paths. There is no mechanism to mark the file as inactive, no version or validity check, and no AC addressing how consumers should handle the stale-file scenario.
+
+8. **String manipulation for YAML merge is fragile and underspecified.** Task 1.5 says "Preserve existing config.yaml content -- append/merge, do not overwrite" and Task 1.6 says use "string manipulation or regex." But there is no specification for what happens when `knowledgebase_path` already exists in the file from a previous run. Append would create duplicates. Find/replace needs a defined regex. The story does not specify whether existing values should be updated in place or appended, nor does it provide the regex pattern.
+
+### Story 16.3: Project-Context Multi-Repo Section
+
+9. **Contradiction between AC #3 (idempotency) and existing codebase behavior.** AC #3 says "When project-context.md already exists, the file is NOT modified." But the existing codebase in `installer.js` already DOES modify an existing `project-context.md` via `updateProjectContextManifestPaths()` which replaces content between marker comments. The story's blanket "do NOT modify" rule contradicts the established pattern and means users who install multi-repo on an existing project will NEVER get the Repository Layout section unless they manually edit it or regenerate from scratch (losing customizations).
+
+10. **Template location uncertainty and missing test updates.** Dev Notes say "Generator function: in `installer.js` or related module (find via Epic 13 implementation)" -- the hedge "or related module" suggests the author was not sure. More critically, Task 3.2 modifies the public API signature of `generateProjectContext()` (an exported function). There is no mention of updating tests in `test/generate-project-context.test.js` or checking for other callers of this function.
+
+### Story 16.4: Validate Cross-Repo Path Resolution
+
+11. **Story is built on an unverified assumption with no definition of done if it fails.** The Expected Outcome says "Most likely outcome: BMAD workflow path resolution is driven by `config.yaml` values that ma-agents sets." But workflows use `output_folder: "{config_source}:output_folder"` which reads from `_bmad/bmm/config.yaml` -- a completely different key name and config file. There are zero references to `knowledgebase_path` or `sprint_management_path` anywhere in workflow files. This story is framed as "validation" but the gap it will inevitably discover should have been scoped as implementation work, not punted to a validation story that might produce a "gap analysis document" with no timeline for resolution.
+
+12. **No acceptance criteria for what constitutes a passing validation.** The ACs describe expected behaviors, but Task 4 says "If BMAD workflows don't natively support configurable output paths, document changes needed." So the story passes even if nothing works? There is no AC that defines the minimum passing bar. A validation story without a pass/fail criterion is a research spike wearing a validation costume.
+
+### Cross-Story Issues
+
+13. **Three sources of truth, no precedence specification.** Story 16.2 stores paths in `config.yaml`. Story 16.3 stamps paths into `project-context.md`. Story 16.4 says agents discover paths from `project-layout.yaml` OR `config.yaml`. There are now three sources of truth for the same information, and no specification for which takes precedence when they disagree.
+
+14. **No CI/CD path for multi-repo configuration.** AC #7 of Story 16.1 says `--yes` mode defaults to single-repo, and Dev Notes say "multi-repo is interactive-only configuration." This means there is no way to configure multi-repo in an automated pipeline -- ever. For a feature targeting DevOps engineers (Story 16.2's persona), making it impossible to automate is a significant gap. There should be environment variables or CLI arguments for headless multi-repo setup.
+
+15. **Zero automated test coverage across all four stories.** Stories 16.1-16.3 introduce new functions and modify an existing exported function. There is an existing test file that will break when the function signature changes. None of the three implementation stories include any task for writing or updating unit tests. Story 16.4's tasks are all manual audits. The epic ships with zero automated regression coverage.

package/_bmad-output/implementation-artifacts/epic-16-edge-case-review.md

@@ -0,0 +1,230 @@
+# Edge Case Hunter Review: Epic 16 — Multi-Repository Project Layout
+
+**Scope:** Stories 16.1, 16.2, 16.3, 16.4
+**Date:** 2026-03-28
+**Method:** Exhaustive path enumeration across all branching paths and boundary conditions
+
+## Findings
+
+```json
+[
+  {
+    "location": "16.1:AC#3/Task3.1",
+    "trigger_condition": "User enters empty string or whitespace-only git URL",
+    "guard_snippet": "if (!gitUrl || !gitUrl.trim()) { console.log(chalk.red('Git URL cannot be empty')); /* re-prompt */ }",
+    "potential_consequence": "execSync runs git clone with empty quoted arg, cryptic git error"
+  },
+  {
+    "location": "16.1:AC#3/Task3.2",
+    "trigger_condition": "User enters empty string or whitespace-only destination path",
+    "guard_snippet": "if (!destPath || !destPath.trim()) { console.log(chalk.red('Destination path cannot be empty')); /* re-prompt */ }",
+    "potential_consequence": "git clone writes into current directory unexpectedly"
+  },
+  {
+    "location": "16.1:AC#3/Task3.4",
+    "trigger_condition": "Git URL contains shell metacharacters like $() or backticks",
+    "guard_snippet": "Use execFileSync('git', ['clone', gitUrl, destPath]) instead of execSync with string interpolation",
+    "potential_consequence": "Arbitrary command injection via crafted git URL string"
+  },
+  {
+    "location": "16.1:AC#5/Task2.2",
+    "trigger_condition": "User provides relative path like '../kb' from different CWDs",
+    "guard_snippet": "const resolved = path.resolve(process.cwd(), localPath); // resolve relative to install CWD, store absolute",
+    "potential_consequence": "Stored relative path resolves differently when agents run later"
+  },
+  {
+    "location": "16.1:AC#5/Task2.4",
+    "trigger_condition": "User confirms non-existent local path without correction",
+    "guard_snippet": "If user confirms non-existent path, log warning that path will need to exist before agents run",
+    "potential_consequence": "Config stores path that does not exist; agents fail at runtime"
+  },
+  {
+    "location": "16.1:AC#3/Task3.3",
+    "trigger_condition": "Destination exists but is a file, not a directory",
+    "guard_snippet": "if (fs.existsSync(destPath) && !fs.statSync(destPath).isDirectory()) { /* warn and re-prompt */ }",
+    "potential_consequence": "Summary display crashes or git clone fails overwriting a file"
+  },
+  {
+    "location": "16.1:AC#3/Task3.7",
+    "trigger_condition": "Clone fails and user selects 'skip'; no fallback path stored",
+    "guard_snippet": "If skip chosen after clone failure, set mode to 'same' or require valid local path before proceeding",
+    "potential_consequence": "Layout object has remote mode but no cloned repo; downstream steps fail"
+  },
+  {
+    "location": "16.1:AC#3/Task3.4",
+    "trigger_condition": "Git is not installed or not on PATH",
+    "guard_snippet": "try { execSync('git --version') } catch { chalk.red('git not found on PATH'); process.exit(1) }",
+    "potential_consequence": "Unhelpful ENOENT error from execSync instead of clear message"
+  },
+  {
+    "location": "16.1:AC#7/Task1.6",
+    "trigger_condition": "User passes --yes with env vars for custom repo paths",
+    "guard_snippet": "Document or support env vars (MA_KB_PATH, MA_SPRINT_PATH) that override defaults in --yes mode",
+    "potential_consequence": "CI/CD pipelines cannot configure multi-repo without interactive prompts"
+  },
+  {
+    "location": "16.1:AC#3/Task3.5",
+    "trigger_condition": "Clone hangs due to SSH key prompt or large repo on slow network",
+    "guard_snippet": "execSync('git clone ...', { timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })",
+    "potential_consequence": "Installer hangs indefinitely waiting for git credential or transfer"
+  },
+  {
+    "location": "16.2:AC#1/Task1.5",
+    "trigger_condition": "config.yaml has no trailing newline or unusual YAML formatting",
+    "guard_snippet": "Ensure content ends with newline before appending; use regex anchored to line start for find/replace",
+    "potential_consequence": "Appended fields merge into last line, producing invalid YAML"
+  },
+  {
+    "location": "16.2:AC#1/Task1.6",
+    "trigger_condition": "config.yaml contains duplicate knowledgebase_path keys after multiple installs",
+    "guard_snippet": "Regex replace existing key if found: content.replace(/^knowledgebase_path:.*$/m, newLine) || append",
+    "potential_consequence": "YAML has duplicate keys; parsers may use first or last unpredictably"
+  },
+  {
+    "location": "16.2:AC#1/Task1.4",
+    "trigger_condition": "Absolute path contains YAML-special characters like colons (C:\\path or C:/path)",
+    "guard_snippet": "Quote path values in YAML: knowledgebase_path: \"C:/Code/kb-repo\"",
+    "potential_consequence": "Unquoted colon in Windows path produces invalid YAML"
+  },
+  {
+    "location": "16.2:AC#2/Task2.4",
+    "trigger_condition": "Path contains characters needing YAML escaping (#, %, {, })",
+    "guard_snippet": "Always wrap path values in double quotes in project-layout.yaml template strings",
+    "potential_consequence": "YAML comment or anchor syntax triggered by special chars in path"
+  },
+  {
+    "location": "16.2:AC#4/Task2.4",
+    "trigger_condition": "Path separator normalization differs between runs on same OS",
+    "guard_snippet": "Always normalize with .replace(/\\\\/g, '/') before writing, even on Unix (idempotency)",
+    "potential_consequence": "Determinism check fails; file diff shows path separator changes"
+  },
+  {
+    "location": "16.2:AC#1/Task1.2",
+    "trigger_condition": "config.yaml does not exist yet (first install before bmad-method completes)",
+    "guard_snippet": "if (!fs.existsSync(configPath)) { fs.mkdirSync(path.dirname(configPath), {recursive:true}); fs.writeFileSync(configPath, '') }",
+    "potential_consequence": "Read of non-existent file throws ENOENT, installer crashes"
+  },
+  {
+    "location": "16.2:AC#3/Task3.2",
+    "trigger_condition": "Previous multi-repo project-layout.yaml is stale but not deleted on mode change",
+    "guard_snippet": "Log warning: 'Existing project-layout.yaml found but current config is single-repo — file may be stale'",
+    "potential_consequence": "Agents read stale project-layout.yaml and use wrong paths silently"
+  },
+  {
+    "location": "16.3:AC#3/Task4.3",
+    "trigger_condition": "project-context.md exists AND single-repo mode configured",
+    "guard_snippet": "Only log 'add Repository Layout manually' message when multi-repo is configured AND file exists",
+    "potential_consequence": "Confusing log message shown to single-repo users who need no action"
+  },
+  {
+    "location": "16.3:AC#2/Task3.4",
+    "trigger_condition": "Template placeholder replaced with empty string leaves double blank lines",
+    "guard_snippet": "Replace '{{REPO_LAYOUT_SECTION}}\\n\\n' (placeholder plus surrounding blank lines) as a unit",
+    "potential_consequence": "Generated project-context.md has extra blank lines in single-repo mode"
+  },
+  {
+    "location": "16.3:AC#1/Task2.4",
+    "trigger_condition": "Mixed config: knowledgebase is external but sprint is same-repo",
+    "guard_snippet": "Section generator should list each concern independently, showing '.' or 'current repository' for same-mode items",
+    "potential_consequence": "Section omits same-repo concern or shows incomplete path info to agents"
+  },
+  {
+    "location": "16.3:AC#1/Task2.2",
+    "trigger_condition": "Layout config object is undefined or missing fields when generator is called",
+    "guard_snippet": "if (!layout?.knowledgebase || !layout?.sprintManagement) { return ''; }",
+    "potential_consequence": "TypeError accessing .mode on undefined; installer crash during generation"
+  },
+  {
+    "location": "16.4:AC#1/Task1.3",
+    "trigger_condition": "BMAD workflows use hardcoded _bmad-output/ instead of config-driven path",
+    "guard_snippet": "Audit must check for literal '_bmad-output/' strings in workflow files; document each as requiring change",
+    "potential_consequence": "Multi-repo config is stored but never used; artifacts always go to code repo"
+  },
+  {
+    "location": "16.4:AC#4/Task3.1",
+    "trigger_condition": "Both project-layout.yaml and config.yaml exist with conflicting paths",
+    "guard_snippet": "Define precedence: config.yaml is source of truth; project-layout.yaml is informational. Document this.",
+    "potential_consequence": "Agents read different files and resolve to different paths non-deterministically"
+  },
+  {
+    "location": "16.4:AC#1/Task2.2",
+    "trigger_condition": "Knowledgebase path points to repo that lacks _bmad-output/planning-artifacts/",
+    "guard_snippet": "Workflows should check if target directory exists before read/write; create or error clearly",
+    "potential_consequence": "Agent crashes or silently creates artifacts in wrong location"
+  },
+  {
+    "location": "16.1:AC#5/Task2.2",
+    "trigger_condition": "Path exists but is a file, not a directory",
+    "guard_snippet": "if (fs.existsSync(p) && !fs.statSync(p).isDirectory()) { chalk.yellow('Path exists but is not a directory') }",
+    "potential_consequence": "Validation passes but subsequent file operations in that 'directory' fail"
+  },
+  {
+    "location": "16.2:AC#2/Task2.5",
+    "trigger_condition": "_bmad-output/ directory does not exist in fresh code repo",
+    "guard_snippet": "fs.mkdirSync('_bmad-output', { recursive: true }) before writing project-layout.yaml",
+    "potential_consequence": "ENOENT error writing project-layout.yaml in brand-new repository"
+  },
+  {
+    "location": "16.1:AC#3/Task3.3",
+    "trigger_condition": "Destination directory exists but is empty (not a git repo)",
+    "guard_snippet": "Distinguish empty dir from populated dir/git repo in summary; offer to clone into it vs. use as-is",
+    "potential_consequence": "User confirms empty directory; agents later find no artifacts and fail"
+  },
+  {
+    "location": "16.2:AC#1/Task1.5",
+    "trigger_condition": "config.yaml is read-only or locked by another process",
+    "guard_snippet": "try { fs.writeFileSync(configPath, content) } catch(e) { chalk.red('Cannot write config.yaml: ' + e.message) }",
+    "potential_consequence": "Unhandled EACCES or EPERM crashes installer with stack trace"
+  },
+  {
+    "location": "16.1:AC#4/Task3.4",
+    "trigger_condition": "Destination path is inside the current repository (e.g., ./external/kb)",
+    "guard_snippet": "Warn if destPath resolves to a subdirectory of process.cwd(); nested repos cause git confusion",
+    "potential_consequence": "Nested git repo causes submodule-like issues; commits mix repos"
+  },
+  {
+    "location": "16.3:AC#4/Task1.2",
+    "trigger_condition": "Template file does not contain {{REPO_LAYOUT_SECTION}} after manual edit",
+    "guard_snippet": "if (!template.includes('{{REPO_LAYOUT_SECTION}}')) { log warning; append section at end if multi-repo }",
+    "potential_consequence": "Multi-repo section silently dropped; agents have no path information"
+  },
+  {
+    "location": "16.4:AC#4/Task3.3",
+    "trigger_condition": "Knowledgebase repo path is valid but user has no read permission",
+    "guard_snippet": "Validation should test fs.accessSync(kbPath, fs.constants.R_OK) and report permission error",
+    "potential_consequence": "Agent discovers path but cannot read PRD; opaque permission denied error"
+  },
+  {
+    "location": "16.2:AC#2/Task2.3",
+    "trigger_condition": "Mode is 'local' but original source was cloned; no gitUrl stored",
+    "guard_snippet": "Only check mode === 'remote' for gitUrl inclusion; 'local' mode must never have gitUrl even if path is a git repo",
+    "potential_consequence": "Missing gitUrl for local-mode git repos may confuse future pull/sync features"
+  },
+  {
+    "location": "16.1:AC#1/Task1.4",
+    "trigger_condition": "User selects different modes for KB and sprint pointing to same external path",
+    "guard_snippet": "if (kb.path === sprint.path && kb.path !== '.') { log info: 'Both concerns point to same external repo' }",
+    "potential_consequence": "No issue per se but user may not realize both share one repo; worth confirming"
+  },
+  {
+    "location": "16.2:AC#4/Task4.4",
+    "trigger_condition": "Second install changes mode from remote to local for same concern",
+    "guard_snippet": "When overwriting config.yaml paths, also check if project-layout.yaml needs regeneration with new mode",
+    "potential_consequence": "config.yaml updated but project-layout.yaml still shows old remote mode and gitUrl"
+  },
+  {
+    "location": "16.1:AC#3/Task3.4",
+    "trigger_condition": "Disk is full during git clone; partial clone left on filesystem",
+    "guard_snippet": "In catch block after clone failure: if destPath was created by clone, rimraf/remove it before retry prompt",
+    "potential_consequence": "Partial clone directory passes exists-check on retry; corrupt repo used"
+  },
+  {
+    "location": "16.3:AC#1/Task2.2",
+    "trigger_condition": "Configured path contains backslashes that break markdown rendering",
+    "guard_snippet": "Normalize all paths with .replace(/\\\\/g, '/') before injecting into markdown section",
+    "potential_consequence": "Markdown renders backslashes as escape chars; agents see mangled paths"
+  }
+]
+```
+
+**Total findings: 35**

package/_bmad-output/implementation-artifacts/epic-17-adversarial-review.md

@@ -0,0 +1,37 @@
+# Epic 17: Sprint Planning Overhaul -- Adversarial Review
+
+**Review Date:** 2026-03-28
+**Scope:** Story 17.1 (Sprint Entity Model)
+**Verdict:** Multiple specification conflicts and gaps -- needs corrections before dev
+
+---
+
+## Findings
+
+1. **Schema mismatch between AC #1 and Task 2.5: `created_date` and `last_modified` are phantom fields.** AC #1 specifies exactly seven fields in the YAML schema: `id`, `name`, `status`, `capacity`, `start`, `end`, `items`. Task 2.5 adds two more fields (`created_date` and `last_modified`) that appear nowhere in the acceptance criteria. Task 6.2 then says "Verify new schema fields match AC #1 exactly" -- which they cannot, because Task 2.5's template has nine fields. A developer literally cannot satisfy both Task 2.5 and Task 6.2 simultaneously. Either the AC needs updating or the task needs to drop the extra fields.
+
+2. **The story ignores the SKILL.md file entirely.** Epic 15 already converted `add-sprint` into a skill package. The file `lib/bmad-extension/skills/add-sprint/SKILL.md` exists and contains an identical copy of the workflow. The story's "Files to modify" list mentions only `lib/bmad-extension/workflows/add-sprint/workflow.md`. The `module-help.csv` entry already points to `skill:add-sprint`, which resolves to the SKILL.md, not the workflow.md. If the developer only modifies `workflow.md`, the actual invoked skill will remain unchanged and still emit the old format. This is a **showstopper omission**. The `bmad-skill-manifest.yaml` file may also need updating.
+
+3. **No date validation specified.** Task 2.3 says dates must be ISO format `YYYY-MM-DD`, but there is no acceptance criterion, validation step, or error-handling behavior defined for invalid dates. What happens if the user enters `2026-13-45`, `next Tuesday`, or an empty string? The old workflow allowed freeform or empty values. The new schema implies strict ISO dates, but the story specifies no validation logic, no error message, and no retry loop. Compare to the capacity field (Task 2.2), which has explicit validation with an error message and a `goto` loop. Dates get nothing.
+
+4. **Start and end dates: required or optional?** The old workflow explicitly made `start_context` and `end_context` optional ("press Enter to skip"). The new schema shows `start` and `end` as always populated. No AC or task states whether dates are required or optional. If optional, what value goes in the YAML -- empty string, `null`, omitted key? If required, the story needs to say so explicitly. Downstream story 17.8 (Sprint Status Display) will need to render these fields, so the contract matters.
+
+5. **AC #2 is untestable within this story's scope.** AC #2 says "`items` contains an ordered list of story/bug IDs" and "the count of items never exceeds `capacity`." But the Critical Guardrails state "`items` array MUST be initialized as empty `[]` -- never pre-populated during sprint creation," and the story explicitly forbids touching `add-to-sprint` or `modify-sprint` (the only workflows that would populate `items`). Within this story, `items` will always be `[]`, and the capacity constraint can never be exercised. This AC is testing behavior that is physically impossible to trigger until Story 17.4. It should be moved to 17.4 or clearly marked as a contract specification, not an acceptance criterion for this story.
+
+6. **AC #3 is also largely untestable within this story's scope.** AC #3 describes the transition from `planning` to `active`, but Task 3.4 says "activation is a separate action (via modify-sprint or a future activate-sprint step)" and the guardrails say "Do NOT rework modify-sprint." There is no mechanism in this story's add-sprint workflow to set a sprint to `active`, so the single-active-sprint validation (Task 3.1-3.3) cannot be triggered by anything this story delivers. The validation code would be dead code with no way to invoke it.
+
+7. **The `name` field has no uniqueness constraint or validation.** Two sprints can have different IDs but identical names. The ID has overwrite protection (Task 2.6), but the name is free text with a default template that could easily collide. If 17.8 (Sprint Status Display) shows sprints by name, this will cause confusion. No AC addresses name uniqueness or name format validation.
+
+8. **FR132 specifies "start/end context" but the story silently narrows to strict ISO dates.** The PRD requirement FR132 reads: "each sprint has an iteration identifier, capacity, assigned item list, start/end context, and status." The word "context" implies the old freeform model. This story silently narrows the semantics from freeform context to strict ISO dates without documenting this as a deliberate deviation from FR132 or proposing a PRD amendment.
+
+9. **Sprint status transition rules are incomplete.** AC #3 only covers `planning -> active`. The Dev Notes say the state machine is `planning -> active -> closed`. But the story never explicitly forbids: `closed -> active` (reopening), `closed -> planning`, `active -> planning` (deactivation without closing), or creating a sprint directly in `active` or `closed` status. The guardrails document update (Task 5.3) should contain the full transition matrix, but the story only says "Add Sprint Status Transitions section" -- that is a one-line description, not a specification.
+
+10. **The `module-help.csv` output-location column is stale.** The current entry's output-location says `_bmad-output/implementation-artifacts` -- but sprint files now go to `_bmad-output/implementation-artifacts/sprints/`. Task 4.2 says "Update description if changed" but does not identify that the output-location is also wrong. The description references "optional start/end context" which no longer applies either.
+
+11. **No guidance on sprint ID numbering conflicts or sequencing.** The ID format is `sprint-{number}`, but nothing prevents creating `sprint-5` when only `sprint-1` exists, or creating `sprint-1` after `sprint-3`. There is no auto-increment, no next-available-number suggestion, and no validation that numbers are sequential. Downstream stories that glob and sort by ID will behave unpredictably with non-sequential numbering.
+
+12. **The guardrails document name is misleading after this update.** The file is called `epic-11-12-shared-guardrails.md`, but after Task 5 it will contain Epic 17 content (Sprint Status Transitions, new paths, new globs). The filename no longer reflects its scope. No renaming is proposed.
+
+13. **Interim breakage of existing workflows has no mitigation.** The story states that after 17.1, the existing `add-to-sprint`, `modify-sprint`, and `sprint-status-view` workflows will be **broken** because they still reference `sprint-plan-*.yaml` paths. The story calls this "expected and acceptable." But there is no feature flag, no deprecation warning, no stub that returns a useful error message, and no documented workaround. A Scrum Master running `/add-to-sprint` after 17.1 lands will get a silent failure or cryptic "no sprint plans found" error with no explanation.
+
+14. **The `items` array example in AC #2 uses inconsistent ID formats without defining the contract.** The example shows `["5-5-explicit-parameter-passing", "5-6-fix-space-in-path-bug", "BUG-path-spaces"]`. Story IDs use `{epic}-{story}-{slug}` format but bug IDs use `BUG-{slug}`. This is the only place that defines the item ID format, and it is buried in an example rather than stated as a rule. Story 17.4 will need to write to this array and must know the exact format. The contract should be explicit.