ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/done/16-1-repository-layout-wizard.md

@@ -1,223 +0,0 @@
-# Story 16.1: Repository Layout Wizard
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want the installer to ask where the knowledgebase and sprint management are managed during installation,
-So that the project layout is configured correctly for multi-repo environments.
-
-## Acceptance Criteria
-
-1. When the user runs `npx ma-agents install`, the wizard asks "Where is your knowledgebase managed?" with options: Current repository (default), Local path, Remote git repository (FR111)
-2. The wizard asks "Where is your sprint management managed?" with the same options (FR112)
-3. When the user selects "Remote git repository", the wizard asks for the git URL and local destination path for cloning. If the destination already exists and is a directory, it displays its contents summary and asks the user to confirm. If it exists but is a file, it warns and re-prompts (FR113)
-4. When the user selects "Remote git repository" and the destination does not exist, it clones the repository to that path using `execFileSync` (not `execSync`) to prevent command injection (FR114)
-5. When the user selects "Local path", the wizard validates the path exists and is a directory. If it does not exist, it alerts the user and asks to confirm or correct. If confirmed, logs a warning that the path must exist before agents run (FR115)
-6. When the user selects "Current repository" for both concerns, no additional configuration is needed — single-repo mode preserved (FR116)
-7. In `--yes` flag (CI/CD mode), the wizard checks env vars `MA_KNOWLEDGEBASE_PATH` and `MA_SPRINT_PATH`. If set, uses those paths (mode=local). If not set, defaults to "Current repository" (mode=same). Multi-repo is configurable headlessly via env vars (FR127 integration)
-8. Git clone uses `execFileSync('git', ['clone', gitUrl, destPath])` with `{ timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } }` for space-safety, injection prevention, and hang protection
-9. Empty/whitespace-only inputs for git URL or destination path are rejected with re-prompt
-10. If a clone fails, any partially-created destination directory is cleaned up before offering retry. If user skips, the concern falls back to `same` mode with a warning logged
-
-## Tasks / Subtasks
-
-- [x] Task 1: Add `collectRepoLayout()` function to `bin/cli.js` (AC: #1, #2, #6, #7)
-  - [x] 1.1 Create `collectRepoLayout(flags)` async function in `bin/cli.js`
-  - [x] 1.2 Implement the knowledgebase prompt using `prompts` library (type: `'select'`, choices as `{ title, value }` objects — matching existing wizard patterns)
-  - [x] 1.3 Implement the sprint management prompt with same choices
-  - [x] 1.4 Return layout object: `{ knowledgebase: { mode, path, gitUrl? }, sprintManagement: { mode, path, gitUrl? } }`
-  - [x] 1.5 When mode is `same`, set `path: '.'`
-  - [x] 1.6 In `--yes` mode: check `process.env.MA_KNOWLEDGEBASE_PATH` and `process.env.MA_SPRINT_PATH`. If set, use `{ mode: 'local', path: path.resolve(envValue) }`. If not set, use `{ mode: 'same', path: '.' }`
-  - [x] 1.7 If both concerns resolve to the same external path, log info: "Both concerns point to same external repository"
-
-- [x] Task 2: Implement "Local path" flow (AC: #5, #9)
-  - [x] 2.1 Prompt user for local path string; reject empty/whitespace-only input with re-prompt
-  - [x] 2.2 Resolve to absolute path via `path.resolve(process.cwd(), localPath)`
-  - [x] 2.3 Check `fs.existsSync(resolved)`: if exists, verify `fs.statSync(resolved).isDirectory()` — if it's a file, warn and re-prompt
-  - [x] 2.4 If path does not exist: display warning with `chalk.yellow()`, ask user to confirm or provide corrected path
-  - [x] 2.5 If confirmed non-existent: store resolved path, log warning that path must exist before agents run
-  - [x] 2.6 If not confirmed, re-prompt for the path (loop)
-  - [x] 2.7 Warn if resolved path is inside the current repo (`resolved.startsWith(process.cwd())`) — nested repos cause git confusion
-
-- [x] Task 3: Implement "Remote git repository" flow (AC: #3, #4, #8, #9, #10)
-  - [x] 3.1 Prompt user for git URL string; reject empty/whitespace-only input with re-prompt
-  - [x] 3.2 Prompt user for local destination path; reject empty/whitespace-only input with re-prompt
-  - [x] 3.3 Resolve destination to absolute path via `path.resolve()`
-  - [x] 3.4 If destination exists and is a file (not directory): warn with `chalk.red()` and re-prompt
-  - [x] 3.5 If destination exists and is a directory: display summary with `chalk.blue()` (file count, whether it's a git repo), ask user to confirm using existing directory
-  - [x] 3.6 If destination does not exist: run `execFileSync('git', ['clone', gitUrl, destPath], { timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })` — prevents injection, hangs, and SSH key prompts
-  - [x] 3.7 On clone failure: if `destPath` was created by the failed clone (didn't exist before), remove it (`fs.rmSync(destPath, { recursive: true, force: true })`). Then offer retry or skip
-  - [x] 3.8 If user skips after failure: fall back to `{ mode: 'same', path: '.' }`, log warning with `chalk.yellow('Falling back to current repository for {concern}')`
-  - [x] 3.9 Warn if destination resolves inside current repo
-
-- [x] Task 4: Integrate into wizard flow (AC: #1-#10)
-  - [x] 4.1 Call `collectRepoLayout(flags)` in `installWizard()` AFTER agent selection (after ~line 333) and BEFORE scope selection (~line 336)
-  - [x] 4.2 Pass the returned layout object forward to the installation pipeline context
-  - [x] 4.3 Store layout in the installation context so subsequent steps (config write, project-context) can access it
-  - [x] 4.4 Verify `--yes` mode without env vars bypasses all repo layout prompts (defaults to same)
-  - [x] 4.5 Verify `--yes` mode with env vars creates local-mode layout without prompts
-
-- [x] Task 5: Write unit tests (AC: #1-#10)
-  - [x] 5.1 Test `collectRepoLayout()` with `--yes` flag returns both as `same` mode
-  - [x] 5.2 Test `collectRepoLayout()` with `--yes` + env vars returns local mode with resolved paths
-  - [x] 5.3 Test local path validation: existing dir accepted, existing file rejected, non-existent warned
-  - [x] 5.4 Test remote flow: `execFileSync` called with correct args array (not string interpolation)
-  - [x] 5.5 Test clone failure: partial directory cleanup, skip fallback to same mode
-  - [x] 5.6 Test empty/whitespace input rejection for URL and path
-  - [x] 5.7 Test nested-repo warning when path is inside cwd
-
-## Dev Notes
-
-### Architecture Decision P2-10
-
-This story implements the installation wizard portion of architecture decision P2-10 (Multi-Repository Project Layout). The wizard goes in `bin/cli.js` as a new section AFTER the agent selection prompts.
-
-### CRITICAL: Correct Prompt Library
-
-The codebase uses the `prompts` npm package, NOT `inquirer`. See `bin/cli.js` line 3: `const prompts = require('prompts');`. Key syntax differences:
-- List/select prompts use `type: 'select'` (not `'list'`)
-- Choices use `{ title: 'Display text', value: 'value' }` (not `{ name, value }`)
-- Import: `const prompts = require('prompts');`
-
-### Code Pattern Reference (Corrected)
-
-```javascript
-// In bin/cli.js — new wizard section after agent selection
-async function collectRepoLayout(flags) {
-  // CI/CD mode: check env vars first, then default
-  if (flags.yes) {
-    const kbPath = process.env.MA_KNOWLEDGEBASE_PATH;
-    const sprintPath = process.env.MA_SPRINT_PATH;
-    return {
-      knowledgebase: kbPath
-        ? { mode: 'local', path: path.resolve(kbPath) }
-        : { mode: 'same', path: '.' },
-      sprintManagement: sprintPath
-        ? { mode: 'local', path: path.resolve(sprintPath) }
-        : { mode: 'same', path: '.' },
-    };
-  }
-
-  const layout = { knowledgebase: null, sprintManagement: null };
-  for (const concern of ['knowledgebase', 'sprintManagement']) {
-    const { mode } = await prompts({
-      type: 'select',
-      name: 'mode',
-      message: `Where is your ${concern} managed?`,
-      choices: [
-        { title: 'Current repository (default)', value: 'same' },
-        { title: 'Local path', value: 'local' },
-        { title: 'Remote git repository', value: 'remote' },
-      ]
-    });
-    // ... mode-specific handling
-  }
-  return layout;
-}
-```
-
-### SECURITY: Command Injection Prevention
-
-**NEVER** use `execSync()` with string interpolation for git clone. The git URL is user-provided and could contain shell metacharacters. Use `execFileSync` which passes arguments as an array, bypassing shell interpretation:
-
-```javascript
-// WRONG — command injection via URL
-execSync(`git clone "${gitUrl}" "${destPath}"`);
-
-// CORRECT — arguments passed as array, no shell
-const { execFileSync } = require('child_process');
-execFileSync('git', ['clone', gitUrl, destPath], {
-  timeout: 120000,
-  env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-  stdio: 'inherit'
-});
-```
-
-### Clone Failure Cleanup
-
-If a clone fails partway through, the destination directory may contain a partial/corrupt clone. Before offering retry, check if the directory was created by the clone attempt and remove it:
-
-```javascript
-const existedBefore = fs.existsSync(destPath);
-try {
-  execFileSync('git', ['clone', gitUrl, destPath], { ... });
-} catch (err) {
-  if (!existedBefore && fs.existsSync(destPath)) {
-    fs.rmSync(destPath, { recursive: true, force: true });
-  }
-  // offer retry or skip
-}
-```
-
-### Key Implementation Constraints
-
-1. **`prompts` library** (NOT `inquirer`): Use `type: 'select'` with `{ title, value }` choices — match existing `bin/cli.js` patterns
-2. **File location**: `bin/cli.js` (NOT `cli.js` at project root — there is no such file)
-3. **`execFileSync` for git clone**: Array args, no shell, prevents injection
-4. **Clone timeout**: 120 seconds, matching existing `GIT_TERMINAL_PROMPT: '0'` pattern in `lib/bmad.js`
-5. **Cross-platform paths**: `path.resolve()` for normalization — do NOT use hardcoded separators
-6. **No new dependencies**: Use `fs`, `path`, `child_process` (already available), `chalk` (already imported), `prompts` (already imported)
-7. **CI/CD env vars**: `MA_KNOWLEDGEBASE_PATH` and `MA_SPRINT_PATH` enable headless multi-repo setup
-
-### NFR Compliance
-
-| NFR | How This Story Addresses It |
-|-----|----------------------------|
-| NFR34 | Default "Current repository" preserves single-repo behavior — no change for existing users |
-| NFR35 | Git clone uses user-provided URL — works with internal GitLab, local network repos |
-| NFR9 | `path.resolve()` for cross-platform path handling |
-
-### Story Scope Boundary
-
-This story ONLY implements the wizard collection. It does NOT write to config.yaml or create `project-layout.yaml` — that is Story 16.2. This story returns the layout object to the caller.
-
-### Project Structure Notes
-
-- Primary file to modify: `bin/cli.js`
-- Wizard section placement: after agent selection (~line 333), before scope selection (~line 336)
-- The layout object is passed forward through the installation pipeline
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, lines 792-901]
-- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.1, lines 1972-2008]
-- [Source: _bmad-output/planning-artifacts/prd.md — FR111-FR116, FR127, lines 574-598]
-- [Source: _bmad-output/planning-artifacts/prd.md — NFR34-NFR37, lines 655-660]
-- [Source: bin/cli.js — installWizard(), prompts library usage]
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-None — implementation proceeded without errors.
-
-### Completion Notes List
-
-- Implemented `collectRepoLayout(flags)` function with full CI/CD (--yes) and interactive support
-- Implemented `collectLocalPath(concern)` helper for local path validation with re-prompt loops, directory/file checks, non-existent path warnings, and nested-repo detection
-- Implemented `collectRemotePath(concern)` helper for remote git clone flow with `execFileSync` (injection-safe), clone failure cleanup, retry/skip fallback, and nested-repo detection
-- Integrated `collectRepoLayout()` into `installWizard()` flow after agent selection, before scope selection
-- Created 13 unit tests in `test/repo-layout.test.js` covering: --yes defaults, env var resolution, structural code checks (execFileSync array args, clone cleanup, empty input rejection, nested-repo warning), and integration test
-- All 13 new tests pass, all existing tests pass (no regressions)
-- Added `repo-layout.test.js` to `package.json` test script
-- Exported `collectRepoLayout` from `bin/cli.js` for testability
-
-### Change Log
-
-- 2026-03-28: Implemented story 16.1 — repository layout wizard with all 5 tasks complete
-
-### File List
-
-- bin/cli.js (modified — added collectRepoLayout, collectLocalPath, collectRemotePath functions + integration)
-- test/repo-layout.test.js (new — 13 unit/integration tests)
-- package.json (modified — added repo-layout.test.js to test script)
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified — story status)
-- _bmad-output/implementation-artifacts/16-1-repository-layout-wizard.md (modified — task checkboxes, dev record)

package/_bmad-output/implementation-artifacts/done/16-2-config-storage-and-cross-reference.md

@@ -1,180 +0,0 @@
-# Story 16.2: Config Storage and Cross-Reference File
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **DevOps engineer**,
-I want the configured repo paths stored persistently and a cross-reference file created in the code repo,
-So that agents and BMAD workflows can discover the correct paths without re-running installation.
-
-## Acceptance Criteria
-
-1. When knowledgebase is configured at `d:/Code/kb-repo` and sprint management at `d:/Code/sprint-repo`, `_bmad/bmm/config.yaml` contains `knowledgebase_path` and `sprint_management_path` fields with those values (FR117)
-2. When multi-repo mode is configured, `_bmad-output/project-layout.yaml` is created in the CODE repository with `generated`, `knowledgebase` (mode, path, gitUrl), and `sprint_management` (mode, path) sections (FR122)
-3. When single-repo mode is configured (both set to "current repository"), config.yaml contains `knowledgebase_path: "."` and `sprint_management_path: "."` — and NO `project-layout.yaml` is created (NFR34)
-4. Running the installer multiple times with the same multi-repo configuration produces an identical `project-layout.yaml` except for the `generated` date field (NFR36 deterministic)
-5. `project-layout.yaml` is generated by ma-agents installer, not by bmad-method — it lives in `_bmad-output/` which is version-controlled (per F3)
-6. Path values in both YAML files are always double-quoted and use forward slashes (cross-platform safe)
-7. If config.yaml already contains `knowledgebase_path`/`sprint_management_path` from a previous run, the values are updated in place (not duplicated)
-8. When switching from multi-repo to single-repo, a stale `project-layout.yaml` is deleted (not left behind with outdated paths)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Write repo layout to `_bmad/bmm/config.yaml` (AC: #1, #3, #6, #7)
-  - [x] 1.1 After `collectRepoLayout()` returns (Story 16.1), extract knowledgebase and sprint management paths
-  - [x] 1.2 Read existing `_bmad/bmm/config.yaml` content as string. If file does not exist, log error and skip (bmad-method should have created it)
-  - [x] 1.3 Normalize paths: `resolvedPath.replace(/\\/g, '/')` before writing
-  - [x] 1.4 For each field (`knowledgebase_path`, `sprint_management_path`): regex replace or append
-  - [x] 1.5 Always double-quote path values in YAML
-  - [x] 1.6 Wrap write in try/catch — non-fatal on permission errors
-  - [x] 1.7 For `same` mode, write `"."` as the path value
-
-- [x] Task 2: Generate `project-layout.yaml` for multi-repo mode (AC: #2, #4, #5, #6)
-  - [x] 2.1 Check if either concern is NOT `same` mode — if both are `same`, skip
-  - [x] 2.2 Ensure `_bmad-output/` directory exists
-  - [x] 2.3 Generate `_bmad-output/project-layout.yaml` using template string
-  - [x] 2.4 Only include `gitUrl` field when mode is `remote`
-  - [x] 2.5 Normalize all paths before writing
-  - [x] 2.6 Always double-quote path and gitUrl values
-
-- [x] Task 3: Handle single-repo mode and stale files (AC: #3, #8)
-  - [x] 3.1 When both concerns are `same` mode, do NOT create `project-layout.yaml`
-  - [x] 3.2 Delete stale `project-layout.yaml` when switching to single-repo
-  - [x] 3.3 Config.yaml still gets `"."` paths written
-
-- [x] Task 4: Handle mode changes on reinstall (AC: #7, #8)
-  - [x] 4.1 Update existing fields in-place via regex
-  - [x] 4.2 Mode changes regenerate project-layout.yaml
-  - [x] 4.3 Mode changes to both-same delete project-layout.yaml
-
-- [x] Task 5: Integrate into installation pipeline (AC: #1-#8)
-  - [x] 5.1 Place config write AFTER bmad-method installation completes
-  - [x] 5.2 Place project-layout.yaml generation after config write
-  - [x] 5.3 Log what was written
-  - [x] 5.4 Verify idempotency
-
-- [x] Task 6: Write unit tests (AC: #1-#8)
-  - [x] 6.1 Test config write: both-same writes `"."`, multi-repo writes absolute paths
-  - [x] 6.2 Test config idempotency
-  - [x] 6.3 Test config update: existing fields replaced in place, no duplicates
-  - [x] 6.4 Test project-layout.yaml: created for multi-repo, skipped for single-repo
-  - [x] 6.5 Test stale cleanup: switching to single-repo deletes existing project-layout.yaml
-  - [x] 6.6 Test path normalization: backslashes converted to forward slashes
-  - [x] 6.7 Test YAML quoting: double-quoted paths
-  - [x] 6.8 Test file permissions error: non-fatal, logged gracefully
-
-## Dev Notes
-
-### CRITICAL: Correct Config File Location
-
-**BMAD workflows read config from `_bmad/bmm/config.yaml`**, NOT `_bmad/core/config.yaml`. Every workflow.yaml in the codebase uses:
-```yaml
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-```
-
-The architecture doc references `_bmad/core/config.yaml`, but the actual codebase uses `_bmad/bmm/config.yaml` for operational config that workflows consume. Write path fields to `_bmad/bmm/config.yaml` so workflows can resolve them at runtime.
-
-### Source of Truth Precedence
-
-Three files can contain repo layout information. Their roles and precedence:
-
-| File | Role | Authority |
-|------|------|-----------|
-| `_bmad/bmm/config.yaml` | **Runtime source of truth** — workflows read this at execution time | PRIMARY |
-| `_bmad-output/project-layout.yaml` | **Agent discovery file** — agents in code repo discover cross-repo paths without loading BMAD config | INFORMATIONAL |
-| `_bmad-output/project-context.md` | **Agent constitutional doc** — stamps paths into agent operating rules | INSTRUCTIONAL |
-
-If these ever disagree, `_bmad/bmm/config.yaml` wins.
-
-### Idempotent YAML Write Pattern
-
-The codebase avoids `js-yaml` as a dependency. Use regex-based find/replace for idempotent config writes:
-
-```javascript
-function writeConfigField(content, fieldName, value) {
-  const regex = new RegExp(`^${fieldName}:.*$`, 'm');
-  const newLine = `${fieldName}: "${value}"`;
-  if (regex.test(content)) {
-    return content.replace(regex, newLine); // update in place
-  }
-  // append (ensure trailing newline)
-  return content.trimEnd() + '\n' + newLine + '\n';
-}
-```
-
-### Stale File Cleanup
-
-When switching from multi-repo to single-repo, the `project-layout.yaml` must be deleted — not left behind. Agents reading a stale file would use outdated paths silently. This is a deliberate departure from the "leave it" approach in the original architecture, based on the adversarial review finding that stale files cause silent path misdirection.
-
-### Key Implementation Constraints
-
-1. **Write to `_bmad/bmm/config.yaml`**: This is where workflows actually read from — verified by checking `config_source` in all workflow.yaml files
-2. **No js-yaml dependency**: Use string templates and regex for YAML operations
-3. **Always double-quote path values**: Handles Windows drive letters (`C:`), spaces, and YAML-special chars (`#`, `%`, `{`, `}`)
-4. **Always normalize separators**: `.replace(/\\/g, '/')` on all paths before writing
-5. **Idempotent writes**: Regex replace existing fields, append only if missing — never duplicate
-6. **Delete stale files**: Remove `project-layout.yaml` when switching to single-repo
-7. **project-layout.yaml in `_bmad-output/`**: version-controlled per Epic 10 policy
-8. **Generated date**: `YYYY-MM-DD` format matching sprint-status.yaml convention
-
-### NFR Compliance
-
-| NFR | How This Story Addresses It |
-|-----|----------------------------|
-| NFR34 | Single-repo: write `"."` paths, delete any stale project-layout.yaml |
-| NFR36 | Deterministic: template string, only `generated` date varies |
-| NFR9 | Path normalization with forward slashes in YAML output |
-
-### Dependencies
-
-- **Story 16.1** must be complete — provides the `layout` object with mode/path/gitUrl for each concern
-- **bmad-method installation** must complete first — creates `_bmad/bmm/config.yaml`
-
-### Project Structure Notes
-
-- Config write target: `_bmad/bmm/config.yaml` (verified: all workflows use this as config_source)
-- Project-layout.yaml target: `_bmad-output/project-layout.yaml`
-- Integration point: after `bmad.installBmad()` completes in the installation pipeline
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, config storage section, lines 844-870]
-- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.2, lines 2010-2052]
-- [Source: _bmad-output/planning-artifacts/prd.md — FR117, FR122, lines 582-587]
-- [Source: _bmad-output/planning-artifacts/prd.md — NFR34, NFR36, lines 657-659]
-- [Source: _bmad/bmm/workflows/4-implementation/create-story/workflow.yaml — config_source: _bmad/bmm/config.yaml]
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-None — clean implementation.
-
-### Completion Notes List
-
-- Implemented `normalizePath()` utility for backslash-to-forward-slash conversion
-- Implemented `writeConfigField()` for idempotent regex-based YAML field writes (replace or append)
-- Implemented `writeRepoLayoutConfig()` to write `knowledgebase_path` and `sprint_management_path` to `_bmad/bmm/config.yaml`
-- Implemented `writeProjectLayoutYaml()` to generate `_bmad-output/project-layout.yaml` for multi-repo or delete stale file for single-repo
-- Integrated both into `installWizard()` as Step 3.6 after BMAD installation
-- 16 unit tests covering normalization, config writes, idempotency, stale cleanup, multi-repo/single-repo modes
-- All tests pass, no regressions
-
-### Change Log
-
-- 2026-03-28: Implemented story 16.2 — config storage and project-layout.yaml generation
-
-### File List
-
-- bin/cli.js (modified — added writeRepoLayoutConfig, writeProjectLayoutYaml, writeConfigField, normalizePath + integration)
-- test/config-storage.test.js (new — 16 tests)
-- package.json (modified — added test to script)
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified)
-- _bmad-output/implementation-artifacts/16-2-config-storage-and-cross-reference.md (modified)

package/_bmad-output/implementation-artifacts/done/16-3-project-context-multi-repo-section.md

@@ -1,136 +0,0 @@
-# Story 16.3: Project-Context Multi-Repo Section
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As an **AI agent**,
-I want project-context.md to include the configured repository paths,
-So that I know where to read and write planning and sprint artifacts.
-
-## Acceptance Criteria
-
-1. When multi-repo is configured with knowledgebase at `/path/to/kb` and sprint at `/path/to/sprint`, the generated project-context.md includes a "Repository Layout" section with both paths and usage instructions (FR118)
-2. When single-repo mode is configured, the "Repository Layout" section is omitted entirely from project-context.md — no empty headers, no leftover blank lines (NFR34 backward compatibility)
-3. When project-context.md already exists, the installer uses the **marker-based update pattern** (like the existing `ma-agents:manifest-paths` pattern) to insert or update the Repository Layout section between `<!-- ma-agents:repo-layout-start -->` and `<!-- ma-agents:repo-layout-end -->` markers. If markers don't exist yet, append the section with markers at the end of the "AI Agent Mandatory Rules" block. The file is NOT regenerated from scratch (preserves user customizations)
-4. The `project-context.template.md` template is updated with a `{{REPO_LAYOUT_SECTION}}` placeholder that resolves to the section content (with markers) or empty string
-5. When the layout config object is undefined or missing fields, the generator returns empty string (no crash)
-6. All paths in the generated section use forward slashes (backslashes normalized before markdown insertion)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Update project-context template (AC: #1, #2, #4)
-  - [x] 1.1-1.5 Added `{{REPO_LAYOUT_SECTION}}` placeholder; clean removal for single-repo
-
-- [x] Task 2: Implement Repository Layout section generator (AC: #1, #2, #5, #6)
-  - [x] 2.1-2.7 `generateRepoLayoutSection(layout)` with guards, markers, mixed config, path normalization
-
-- [x] Task 3: Integrate with project-context generator (AC: #1, #2, #4, #5)
-  - [x] 3.1-3.5 Added `layout` parameter to `generateProjectContext()`, backward-compatible
-
-- [x] Task 4: Implement marker-based update for existing files (AC: #3)
-  - [x] 4.1-4.7 `updateProjectContextRepoLayout()` with marker update/insert, integrated into installWizard
-
-- [x] Task 5: Write/update unit tests (AC: #1-#6)
-  - [x] 5.1-5.7 12 new tests added to generate-project-context.test.js (27 total, all pass)
-
-## Dev Notes
-
-### CRITICAL: Marker-Based Update Pattern (Not "Never Modify")
-
-The adversarial review correctly identified that the original AC ("never modify existing project-context.md") contradicts the codebase's established pattern. The existing `updateProjectContextManifestPaths()` function in `lib/installer.js` already modifies existing files using HTML comment markers:
-
-```markdown
-<!-- ma-agents:manifest-paths-start -->
-  content here
-<!-- ma-agents:manifest-paths-end -->
-```
-
-This story uses the SAME pattern with `<!-- ma-agents:repo-layout-start -->` / `<!-- ma-agents:repo-layout-end -->` markers. This allows:
-- Fresh generation: placeholder replaced in template
-- Existing files: content between markers updated in place
-- User customizations outside markers: preserved
-
-### Generator Function Location (Confirmed)
-
-The generator function is `generateProjectContext()` in `lib/installer.js` (lines 143-200). It is an exported function with existing tests in `test/generate-project-context.test.js`. Adding the `layout` parameter changes the public API — tests MUST be updated.
-
-### Template Section Format
-
-```markdown
-<!-- ma-agents:repo-layout-start -->
-### Repository Layout
-- **Knowledgebase:** {{KNOWLEDGEBASE_PATH}}
-- **Sprint Management:** {{SPRINT_MANAGEMENT_PATH}}
-- When creating or reading planning artifacts, use the knowledgebase path
-- When creating or reading sprint/story artifacts, use the sprint management path
-<!-- ma-agents:repo-layout-end -->
-```
-
-### Key Implementation Constraints
-
-1. **Marker-based updates**: Use `<!-- ma-agents:repo-layout-start/end -->` markers — same pattern as manifest paths
-2. **Clean omission**: When single-repo, no markers, no section, no blank lines — truly omitted
-3. **Backward-compatible API**: `generateProjectContext(root, agents, layout)` — `layout` defaults to `null`, existing callers unaffected
-4. **Normalize backslashes**: All paths get `.replace(/\\/g, '/')` before markdown insertion — backslashes break markdown rendering
-5. **No new dependencies**: String template replacement, consistent with existing approach
-6. **Template file**: `lib/templates/project-context.template.md` (confirmed)
-7. **Existing test file**: `test/generate-project-context.test.js` — MUST be updated
-
-### NFR Compliance
-
-| NFR | How This Story Addresses It |
-|-----|----------------------------|
-| NFR34 | Single-repo: section omitted entirely — no visible change to existing project-context.md |
-| NFR37 | Agents get explicit path instructions — no hardcoded `_bmad-output/` assumptions |
-
-### Dependencies
-
-- **Story 16.2** provides the config values that determine whether multi-repo is active
-- **Epic 13** (project-context auto-generation) provides the template and generator function this story modifies
-
-### Project Structure Notes
-
-- Template file: `lib/templates/project-context.template.md`
-- Generator function: `generateProjectContext()` in `lib/installer.js` (lines 143-200)
-- Update function: `updateProjectContextManifestPaths()` in `lib/installer.js` — use as pattern reference
-- Existing tests: `test/generate-project-context.test.js`
-- Output: `_bmad-output/project-context.md`
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, project-context integration, lines 884-895]
-- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.3, lines 2054-2085]
-- [Source: _bmad-output/planning-artifacts/prd.md — FR118, line 583]
-- [Source: _bmad-output/planning-artifacts/prd.md — NFR34, NFR37, lines 657-660]
-- [Source: lib/installer.js — generateProjectContext(), updateProjectContextManifestPaths()]
-- [Source: test/generate-project-context.test.js — existing tests to update]
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-None.
-
-### Completion Notes List
-- Added `{{REPO_LAYOUT_SECTION}}` placeholder to `lib/templates/project-context.template.md`
-- Implemented `generateRepoLayoutSection(layout)` in `lib/installer.js` — generates markdown with markers for multi-repo, empty string for single-repo
-- Updated `generateProjectContext()` to accept optional `layout` parameter (backward-compatible)
-- Implemented `updateProjectContextRepoLayout()` for marker-based updates to existing project-context.md
-- Integrated into `installWizard()` — calls `updateProjectContextRepoLayout()` after skill installation
-- 12 new tests added to `test/generate-project-context.test.js`, all 27 pass
-
-### Change Log
-- 2026-03-28: Implemented story 16.3 — project-context multi-repo section
-
-### File List
-- lib/installer.js (modified — generateRepoLayoutSection, updateProjectContextRepoLayout, generateProjectContext layout param)
-- lib/templates/project-context.template.md (modified — added REPO_LAYOUT_SECTION placeholder)
-- bin/cli.js (modified — import updateProjectContextRepoLayout, call after skill install)
-- test/generate-project-context.test.js (modified — 12 new tests)
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified)
-- _bmad-output/implementation-artifacts/16-3-project-context-multi-repo-section.md (modified)