ma-agents 3.6.2 → 3.8.0

package/_bmad-output/implementation-artifacts/done/16-4-validate-cross-repo-path-resolution.md

@@ -1,137 +0,0 @@
-# Story 16.4: Validate Cross-Repo Path Resolution
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want to verify that BMAD workflows correctly resolve artifact paths from the configured repo layout,
-So that planning and sprint artifacts are read from and written to the correct repositories.
-
-## Acceptance Criteria
-
-1. An audit of all BMAD workflows identifies which use config-driven path resolution and which hardcode `_bmad-output/` — documented in a gap analysis table
-2. When multi-repo is configured, at least ONE planning workflow reads planning artifacts from `{knowledgebase_path}/_bmad-output/planning-artifacts/` (FR119). If none do natively, the gap is documented with a concrete remediation task
-3. When multi-repo is configured, at least ONE sprint workflow reads/writes sprint artifacts from `{sprint_management_path}/_bmad-output/implementation-artifacts/` (FR120). If none do natively, the gap is documented with a concrete remediation task
-4. When single-repo is configured, all workflows behave identically to pre-Epic-16 behavior — verified by running a workflow in both modes and diffing output structure (NFR34)
-5. Source-of-truth precedence is documented: `_bmad/bmm/config.yaml` is PRIMARY (runtime), `project-layout.yaml` is INFORMATIONAL (agent discovery), `project-context.md` is INSTRUCTIONAL (agent rules)
-6. If workflows DO support config-driven paths: at least 3 end-to-end tests pass (planning read, sprint write, single-repo unchanged)
-7. If workflows do NOT support config-driven paths: a backlog item is created with specific workflow files, line numbers, and required changes — NOT just a "gap analysis document"
-8. External repo paths are validated for accessibility: directory exists and is readable (`fs.accessSync` with `R_OK`)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Audit BMAD workflow path resolution (AC: #1)
-  - [x] 1.1-1.5 Scanned all 21 workflows — 185 config-driven references, 0 hardcoded. Gap analysis table in validation report.
-
-- [x] Task 2: Test config-driven path resolution (AC: #2, #3, #6)
-  - [x] 2.1-2.6 Confirmed: workflows use `planning_artifacts` and `implementation_artifacts` from config. Updated `writeRepoLayoutConfig()` to derive these from layout paths.
-
-- [x] Task 3: Verify single-repo backward compatibility (AC: #4)
-  - [x] 3.1-3.4 Single-repo writes default `_bmad-output/planning-artifacts` and `_bmad-output/implementation-artifacts` — identical to pre-Epic-16 behavior.
-
-- [x] Task 4: Verify agent discovery paths (AC: #5, #8)
-  - [x] 4.1-4.5 Documented source-of-truth precedence (config.yaml PRIMARY). Path accessibility validated via fs.accessSync.
-
-- [x] Task 5: Create remediation or confirmation artifacts (AC: #1-#8)
-  - [x] 5.1 Created `_bmad-output/implementation-artifacts/16-4-validation-report.md` — PASS, no gaps.
-  - [x] 5.2-5.4 No backlog items needed — all workflows already config-driven.
-
-## Dev Notes
-
-### This Is a Validation Story WITH Defined Pass/Fail Criteria
-
-Unlike a pure research spike, this story has concrete pass/fail acceptance criteria:
-
-- **PASS**: Workflows resolve paths from config → end-to-end tests confirm → validation report created
-- **PARTIAL PASS**: Workflows don't resolve from config → gaps documented with specific file/line remediation tasks added to backlog
-- **FAIL**: Unable to determine how workflows resolve paths → should not happen given Task 1's audit approach
-
-### Known Config Resolution Pattern
-
-BMAD workflow.yaml files use this pattern:
-```yaml
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-planning_artifacts: "{config_source}:planning_artifacts"
-implementation_artifacts: "{config_source}:implementation_artifacts"
-```
-
-The `{config_source}:field_name` syntax reads the value of `field_name` from the config file. If `_bmad/bmm/config.yaml` contains `planning_artifacts: "_bmad-output/planning-artifacts"`, workflows use that value.
-
-**The key question**: Can we add `knowledgebase_path` and `sprint_management_path` to config.yaml and have workflows use them? This depends on whether workflows can be modified to derive `planning_artifacts` from `knowledgebase_path` — or if we need to change `planning_artifacts` itself to point to the external path.
-
-**Most likely resolution**: Story 16.2 writes `planning_artifacts: "{knowledgebase_path}/_bmad-output/planning-artifacts"` and `implementation_artifacts: "{sprint_management_path}/_bmad-output/implementation-artifacts"` directly into `_bmad/bmm/config.yaml`. This means the existing `{config_source}:planning_artifacts` pattern in workflows "just works" without workflow modifications. **This approach should be validated in Task 2.**
-
-### Source of Truth Precedence (Cross-Story)
-
-| File | Role | Authority | When to Use |
-|------|------|-----------|-------------|
-| `_bmad/bmm/config.yaml` | Runtime config | PRIMARY | Workflows and agents resolving paths at execution time |
-| `_bmad-output/project-layout.yaml` | Agent discovery | INFORMATIONAL | Agents in code repo that need to find external repos without loading BMAD config |
-| `_bmad-output/project-context.md` | Agent rules | INSTRUCTIONAL | Agent constitutional doc — stamps paths as operating rules |
-
-If these disagree, `_bmad/bmm/config.yaml` wins. Story 16.2 writes to config.yaml; Stories 16.2 and 16.3 write the other two files from the same source data.
-
-### What to Do When Gaps Are Found
-
-Do NOT just write a "gap analysis document" and close the story. Instead:
-1. Create specific, actionable backlog stories
-2. Add them to sprint-status.yaml
-3. Include file paths, line numbers, and the exact change needed
-4. Estimate scope: is this a 1-line config change or a multi-file workflow refactor?
-
-### NFR Compliance
-
-| NFR | How This Story Verifies It |
-|-----|---------------------------|
-| NFR34 | Single-repo mode: all workflows behave identically to pre-Epic-16 behavior |
-| NFR37 | Audit verifies no workflow hardcodes `_bmad-output/` — all use config values |
-| NFR9 | Path resolution verified on Windows (forward slash normalization) |
-
-### Dependencies
-
-- **Stories 16.1, 16.2, 16.3** must be complete — this story validates their output
-- **BMAD workflows** — understanding how they resolve `config_source` variables is the core of this story
-
-### Project Structure Notes
-
-- Workflow configs: `_bmad/bmm/workflows/*/workflow.yaml` — check `config_source` and path variables
-- BMAD config: `_bmad/bmm/config.yaml` (confirmed: this is where workflows read from)
-- Cross-reference: `_bmad-output/project-layout.yaml`
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, path resolution section, lines 873-901]
-- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.4, lines 2087-2117]
-- [Source: _bmad-output/planning-artifacts/prd.md — FR119-FR122, lines 584-587]
-- [Source: _bmad-output/planning-artifacts/prd.md — NFR34, NFR37, lines 657-660]
-- [Source: _bmad/bmm/workflows/4-implementation/create-story/workflow.yaml — config_source pattern]
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-None.
-
-### Completion Notes List
-- Audited all 21 BMAD workflows: 185 config-driven path references, 0 hardcoded `_bmad-output/`
-- Identified gap: workflows read `planning_artifacts`/`implementation_artifacts` but Story 16.2 only wrote `knowledgebase_path`/`sprint_management_path`. Fixed `writeRepoLayoutConfig()` to also derive and write the artifact path fields
-- Single-repo backward compatibility confirmed: default artifact paths match pre-Epic-16 behavior
-- Source-of-truth precedence documented in validation report
-- Created validation report at `_bmad-output/implementation-artifacts/16-4-validation-report.md`
-- 7 validation tests in `test/cross-repo-validation.test.js`, all pass
-
-### Change Log
-- 2026-03-28: Validated story 16.4 — all workflows config-driven, no gaps found. Fixed config write to include derived artifact paths.
-
-### File List
-- bin/cli.js (modified — writeRepoLayoutConfig now also writes planning_artifacts and implementation_artifacts)
-- test/cross-repo-validation.test.js (new — 7 validation tests)
-- _bmad-output/implementation-artifacts/16-4-validation-report.md (new — validation report)
-- package.json (modified — added test to script)
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified)
-- _bmad-output/implementation-artifacts/16-4-validate-cross-repo-path-resolution.md (modified)

package/_bmad-output/implementation-artifacts/done/16-4-validation-report.md

@@ -1,79 +0,0 @@
-# Story 16.4 Validation Report: Cross-Repo Path Resolution
-
-Generated: 2026-03-28
-
-## Audit Summary
-
-**Result: PASS** - All BMAD workflows are 100% config-driven. No hardcoded `_bmad-output/` paths found.
-
-## Gap Analysis Table
-
-| Workflow | Phase | Path Source | Hardcoded? | Config Key Used | Change Needed |
-|----------|-------|-----------|-----------|----------------|---------------|
-| bmad-product-brief | 1-Analysis | config.yaml | No | planning_artifacts | None |
-| bmad-domain-research | 1-Analysis | config.yaml | No | planning_artifacts | None |
-| bmad-market-research | 1-Analysis | config.yaml | No | planning_artifacts | None |
-| bmad-technical-research | 1-Analysis | config.yaml | No | planning_artifacts | None |
-| bmad-create-prd | 2-Planning | config.yaml | No | planning_artifacts | None |
-| bmad-create-ux-design | 2-Planning | config.yaml | No | planning_artifacts | None |
-| bmad-validate-prd | 2-Planning | config.yaml | No | planning_artifacts | None |
-| bmad-edit-prd | 2-Planning | config.yaml | No | planning_artifacts | None |
-| bmad-create-architecture | 3-Solutioning | config.yaml | No | planning_artifacts | None |
-| bmad-create-epics-and-stories | 3-Solutioning | config.yaml | No | planning_artifacts | None |
-| bmad-check-implementation-readiness | 3-Solutioning | config.yaml | No | planning_artifacts | None |
-| bmad-generate-project-context | 3-Solutioning | config.yaml | No | planning_artifacts | None |
-| bmad-sprint-planning | 4-Implementation | config.yaml | No | implementation_artifacts, planning_artifacts | None |
-| bmad-sprint-status | 4-Implementation | config.yaml | No | implementation_artifacts | None |
-| bmad-create-story | 4-Implementation | config.yaml | No | implementation_artifacts, planning_artifacts | None |
-| bmad-dev-story | 4-Implementation | config.yaml | No | implementation_artifacts | None |
-| bmad-retrospective | 4-Implementation | config.yaml | No | implementation_artifacts | None |
-| bmad-code-review | 4-Implementation | config.yaml | No | planning_artifacts, implementation_artifacts | None |
-| bmad-correct-course | 4-Implementation | config.yaml | No | implementation_artifacts | None |
-| bmad-quick-dev | 4-Implementation | config.yaml | No | implementation_artifacts, planning_artifacts | None |
-| bmad-qa-generate-e2e-tests | 4-Implementation | config.yaml | No | implementation_artifacts | None |
-
-## Config Resolution Chain
-
-All workflows follow this identical pattern:
-1. Load config from `{project-root}/_bmad/bmm/config.yaml`
-2. Resolve `planning_artifacts` and `implementation_artifacts` from config values
-3. Use `{planning_artifacts}/...` and `{implementation_artifacts}/...` for all path references
-
-**Multi-repo resolution:**
-- `planning_artifacts` = `{knowledgebase_path}/_bmad-output/planning-artifacts`
-- `implementation_artifacts` = `{sprint_management_path}/_bmad-output/implementation-artifacts`
-
-**Single-repo resolution (backward compatible):**
-- `planning_artifacts` = `_bmad-output/planning-artifacts`
-- `implementation_artifacts` = `_bmad-output/implementation-artifacts`
-
-## Source-of-Truth Precedence
-
-| File | Role | Authority |
-|------|------|-----------|
-| `_bmad/bmm/config.yaml` | Runtime source of truth | PRIMARY |
-| `_bmad-output/project-layout.yaml` | Agent discovery file | INFORMATIONAL |
-| `_bmad-output/project-context.md` | Agent constitutional doc | INSTRUCTIONAL |
-
-If these disagree, `_bmad/bmm/config.yaml` wins.
-
-## Backward Compatibility (NFR34)
-
-Single-repo mode writes:
-- `knowledgebase_path: "."` and `sprint_management_path: "."`
-- `planning_artifacts: "_bmad-output/planning-artifacts"`
-- `implementation_artifacts: "_bmad-output/implementation-artifacts"`
-
-These values are identical to the pre-Epic-16 default behavior. No workflow changes needed.
-
-## Path Accessibility
-
-Story 16.1 validates external paths at wizard time:
-- `fs.existsSync()` checks for local paths
-- `fs.statSync().isDirectory()` confirms it's a directory
-- Git clone validates remote paths
-- Non-existent paths generate warnings
-
-## Conclusion
-
-**No backlog items needed.** All 21 BMAD workflows already support config-driven path resolution through the `planning_artifacts` and `implementation_artifacts` config keys. Story 16.2's config write (updated during 16.4 validation) now also writes these derived fields, completing the end-to-end resolution chain.

package/_bmad-output/implementation-artifacts/done/16-5-fix-config-lost-on-update.md

@@ -1,110 +0,0 @@
-# Story 16.5: Fix Config Lost on Update (Bug)
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **user with a multi-repo layout configured**,
-I want my repo layout configuration to be preserved when I update ma-agents,
-So that I don't silently lose my multi-repo paths every time I add a skill or update agents.
-
-## Bug Description
-
-`collectRepoLayout()` is called unconditionally at [cli.js:595](bin/cli.js#L595) during every install/update run. Unlike skill and agent selections — which are pre-populated during updates — the repo layout prompt starts blank every time. If the user accepts defaults (or runs `--yes` without env vars), the existing multi-repo config in `config.yaml` and `project-layout.yaml` is overwritten with single-repo defaults.
-
-**Reproduction steps:**
-1. Run `npx ma-agents` and configure multi-repo layout (e.g., knowledgebase at `/ext/kb`)
-2. Run `npx ma-agents` again to add a new skill
-3. At the repo layout prompt, accept defaults (or press Enter)
-4. Config.yaml now has `knowledgebase_path: "."` — previous config lost
-
-**Root cause:** No `readExistingLayout()` function exists. The update path never reads the current `project-layout.yaml` or `config.yaml` to pre-populate the prompts.
-
-## Acceptance Criteria
-
-1. **Given** an existing installation with multi-repo layout configured in `_bmad-output/project-layout.yaml`, **When** the user runs `ma-agents` again and selects "Update", **Then** the repo layout prompts are pre-populated with the existing configuration (mode, path, gitUrl)
-2. **Given** an existing installation with single-repo layout (no `project-layout.yaml`), **When** the user runs `ma-agents` again, **Then** the repo layout defaults to single-repo as before (no behavioral change)
-3. **Given** an update with `--yes` flag and no env vars, **When** `project-layout.yaml` exists with multi-repo paths, **Then** the existing layout is preserved (read from file) instead of defaulting to single-repo
-4. **Given** an update with `--yes` flag and env vars set, **When** `project-layout.yaml` also exists, **Then** the env vars take precedence over the file (explicit override wins)
-5. **Given** a fresh install (no existing `project-layout.yaml`), **When** the wizard runs, **Then** behavior is identical to current implementation (no regression)
-6. **Given** an existing multi-repo layout, **When** the user explicitly changes layout during update (selects different mode/path), **Then** the new configuration replaces the old one as expected
-
-## Tasks / Subtasks
-
-- [x] Task 1: Implement `readExistingLayout()` function in `bin/cli.js`
-  - [x] 1.1 Read `_bmad-output/project-layout.yaml` if it exists; parse YAML fields (mode, path, gitUrl for each concern)
-  - [x] 1.2 If file doesn't exist, check `_bmad/bmm/config.yaml` for `knowledgebase_path` and `sprint_management_path` fields as fallback
-  - [x] 1.3 Return layout object matching `collectRepoLayout()` return shape, or `null` if no existing config found
-  - [x] 1.4 Handle parse errors gracefully — return `null` on corruption (don't crash the installer)
-
-- [x] Task 2: Modify `collectRepoLayout()` to accept and use existing layout
-  - [x] 2.1 Add `existingLayout` parameter: `collectRepoLayout(flags, existingLayout = null)`
-  - [x] 2.2 In `--yes` mode: if env vars not set AND `existingLayout` is not null, return `existingLayout` (preserve existing config)
-  - [x] 2.3 In `--yes` mode: env vars still take precedence over existing layout (AC #4)
-  - [x] 2.4 In interactive mode: use `existingLayout` to set `initial` values on prompts — pre-select the current mode for each concern
-  - [x] 2.5 When user selects same mode as existing, pre-fill path/URL from existing config
-
-- [x] Task 3: Wire into `installWizard()`
-  - [x] 3.1 Before calling `collectRepoLayout()`, call `readExistingLayout()` when `isUpdate` is true
-  - [x] 3.2 Pass existing layout to `collectRepoLayout(flags, existingLayout)`
-
-- [x] Task 4: Write unit tests
-  - [x] 4.1 Test `readExistingLayout()` with valid `project-layout.yaml` returns correct layout object
-  - [x] 4.2 Test `readExistingLayout()` with missing file returns null
-  - [x] 4.3 Test `readExistingLayout()` with corrupt YAML returns null (no crash)
-  - [x] 4.4 Test `--yes` mode preserves existing layout when no env vars set
-  - [x] 4.5 Test `--yes` mode with env vars overrides existing layout
-  - [x] 4.6 Test fresh install (no existing layout) behaves identically to current code
-
-## Dev Notes
-
-### Key Files
-
-- `bin/cli.js` — `collectRepoLayout()` (~line 370), `installWizard()` (~line 595)
-- `_bmad-output/project-layout.yaml` — existing config file written by Story 16.2
-
-### YAML Parsing
-
-The project does not use a YAML library. `project-layout.yaml` is simple flat/nested YAML generated by `writeProjectLayoutYaml()`. Parse with regex or line-by-line — match the existing pattern in `writeConfigField()`. Do NOT add a YAML dependency for this.
-
-### Backward Compatibility
-
-- Fresh installs must behave identically (no existing layout = current behavior)
-- `readExistingLayout()` returning `null` means "no existing config" — fall through to current flow
-- Export `readExistingLayout` for testability
-
-### References
-
-- [Source: bin/cli.js — collectRepoLayout() at line 370]
-- [Source: bin/cli.js — installWizard() at line 595]
-- [Source: Adversarial Review Finding #1 — config destroyed on update]
-
-## Dev Agent Record
-
-### Implementation Plan
-- Added `readExistingLayout()` before `collectRepoLayout()` in the update path
-- `readExistingLayout()` reads `project-layout.yaml` first (authoritative), falls back to `config.yaml` path fields
-- Modified `collectRepoLayout()` to accept `existingLayout` parameter for pre-population
-- `--yes` mode: env vars > existing layout > defaults (priority chain)
-- Interactive mode: pre-selects existing mode in prompts via `initial` index
-
-### Completion Notes
-- All 4 tasks implemented and verified with 13 dedicated tests
-- Full regression suite passes (all existing tests unaffected)
-- `readExistingLayout()` exported for testability
-- No new dependencies added — regex-based YAML parsing matches existing project pattern
-- Round-trip test confirms `writeProjectLayoutYaml()` → `readExistingLayout()` works correctly
-- Backward compatibility verified: fresh installs with no existing layout behave identically
-
-## File List
-
-- `bin/cli.js` — Added `readExistingLayout()`, modified `collectRepoLayout()` signature and `--yes` logic, updated interactive prompt pre-selection, wired into `installWizard()`, updated exports
-- `test/config-lost-on-update.test.js` — New: 13 unit tests covering readExistingLayout, collectRepoLayout with existingLayout, round-trip
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Updated 16-5 status: ready-for-dev → in-progress → review
-- `_bmad-output/implementation-artifacts/16-5-fix-config-lost-on-update.md` — Updated task checkboxes, status, dev agent record
-
-## Change Log
-
-- 2026-03-28: Implemented bug fix for config lost on update — `readExistingLayout()` reads existing multi-repo layout from `project-layout.yaml` / `config.yaml` and pre-populates `collectRepoLayout()` during updates. 13 tests added.

package/_bmad-output/implementation-artifacts/done/16-6-repo-sync-check-skill.md

@@ -1,116 +0,0 @@
-# Story 16.6: Repository Sync Check Skill
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **developer using multi-repo layout**,
-I want a skill or workflow that checks whether my external repos are in sync and properly scaffolded,
-So that I catch stale clones and missing directory structures before agents fail at runtime.
-
-## Problem Context
-
-Epic 16 stories 16.1-16.4 let users point to external repos for knowledgebase and sprint management, but:
-- **No scaffolding:** The external repo is never checked for the expected `_bmad-output/planning-artifacts/` and `_bmad-output/implementation-artifacts/` directory structure. A freshly created empty repo will cause every workflow to fail.
-- **No sync:** Remote repos are cloned once during installation. After that, there is no pull, fetch, or freshness check. Local clones go stale silently.
-
-This skill provides a pre-flight check that agents or users can run to validate external repo readiness.
-
-## Acceptance Criteria
-
-1. **Given** a multi-repo layout is configured, **When** the user runs the repo-sync-check skill (or an agent runs it as pre-flight), **Then** it reads `_bmad/bmm/config.yaml` to discover the `knowledgebase_path` and `sprint_management_path`
-2. **Given** an external knowledgebase path, **When** the path does not exist on disk, **Then** the skill reports an error: "Knowledgebase path does not exist: {path}" and advises the user to re-run the installer or create the directory
-3. **Given** an external path that exists, **When** `_bmad-output/planning-artifacts/` is missing inside it, **Then** the skill reports a warning: "Missing directory structure — run scaffolding" and offers to create the expected directories
-4. **Given** an external path that is a git repo, **When** the local branch is behind the remote tracking branch, **Then** the skill reports: "Local clone is {N} commits behind remote — consider running git pull" with the specific count
-5. **Given** an external path that is a git repo, **When** there are uncommitted local changes, **Then** the skill reports: "Local clone has uncommitted changes — commit or stash before pulling"
-6. **Given** an external path that is a git repo with no remote configured, **Then** the skill reports info: "No remote tracking branch — sync check skipped (local-only repo)"
-7. **Given** a single-repo layout (both paths are `.`), **When** the skill runs, **Then** it reports: "Single-repo layout — no external repos to check" and exits cleanly
-8. **Given** the skill detects missing scaffolding, **When** the user confirms, **Then** the skill creates the missing directories: `_bmad-output/planning-artifacts/` and/or `_bmad-output/implementation-artifacts/` with a `.gitkeep` file in each
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create the skill definition file
-  - [x] 1.1 Create `.claude/skills/repo-sync-check/SKILL.md` (following existing skill pattern)
-  - [x] 1.2 Define skill metadata: name, description, trigger conditions
-  - [x] 1.3 The skill should be invocable via `/repo-sync-check` command
-
-- [x] Task 2: Implement config reading
-  - [x] 2.1 Read `_bmad/bmm/config.yaml` for `knowledgebase_path` and `sprint_management_path`
-  - [x] 2.2 If both are `.` (same), report single-repo and exit
-  - [x] 2.3 Also read `_bmad-output/project-layout.yaml` for gitUrl information (needed for remote checks)
-
-- [x] Task 3: Implement path existence and scaffolding checks
-  - [x] 3.1 For each external path: verify the directory exists
-  - [x] 3.2 Check for `_bmad-output/planning-artifacts/` inside knowledgebase path
-  - [x] 3.3 Check for `_bmad-output/implementation-artifacts/` inside sprint management path
-  - [x] 3.4 Offer to create missing directories with `.gitkeep` files
-
-- [x] Task 4: Implement git sync checks
-  - [x] 4.1 For each external path that contains `.git`: run `git fetch` (non-destructive) to update remote refs
-  - [x] 4.2 Compare local HEAD with remote tracking branch using `git rev-list --count HEAD..@{u}`
-  - [x] 4.3 Check for uncommitted changes via `git status --porcelain`
-  - [x] 4.4 Handle repos with no remote gracefully
-
-- [x] Task 5: Produce advisory report
-  - [x] 5.1 Output a structured markdown report with: status per concern (OK / WARNING / ERROR), specific advice for each issue found
-  - [x] 5.2 Exit cleanly — this is advisory, not blocking
-
-- [x] Task 6: Register skill in MANIFEST
-  - [x] 6.1 Add entry to `.claude/skills/MANIFEST.yaml`
-  - [x] 6.2 Set `applies_when` to multi-repo layout scenarios
-  - [x] 6.3 Not `always_load` — only relevant when multi-repo is configured
-
-## Dev Notes
-
-### Skill vs Workflow Decision
-
-This should be a **skill** (not a workflow) because:
-- It's a short, self-contained check — no multi-step workflow needed
-- It should be easy to invoke manually (`/repo-sync-check`) or as a pre-flight step
-- It reads config and runs git commands — matches skill pattern
-
-### Git Commands (Safe, Read-Only)
-
-All git operations are read-only except `git fetch` which only updates remote refs:
-```bash
-git fetch                           # update remote refs (safe)
-git rev-list --count HEAD..@{u}     # commits behind remote
-git status --porcelain              # uncommitted changes
-git remote -v                       # check if remote exists
-```
-
-### Config Reading Pattern
-
-Match the existing LLM-instruction pattern: the skill tells Claude to read config.yaml and extract paths. No need for a JS parser — this is an agent skill, not installer code.
-
-### References
-
-- [Source: Adversarial Review Findings #3 (no scaffolding) and #4 (no sync)]
-- [Source: bin/cli.js — writeRepoLayoutConfig() for config format]
-- [Source: bin/cli.js — writeProjectLayoutYaml() for layout file format]
-
-## Dev Agent Record
-
-### Implementation Plan
-- Created SKILL.md as an LLM-instruction skill (not installer code) — agents read config and run git commands
-- Skill provides step-by-step procedure: read config, check paths, check scaffolding, check git sync, produce report
-- Registered in MANIFEST.yaml with `applies_when` triggers for multi-repo scenarios
-
-### Completion Notes
-- Skill created at `.claude/skills/repo-sync-check/SKILL.md` with YAML frontmatter
-- Registered in MANIFEST.yaml — not `always_load` (only relevant for multi-repo)
-- No unit tests needed — this is an agent-instruction skill (markdown), not executable code
-- Skill covers all 8 ACs: config reading, path existence, scaffolding, git sync (fetch/rev-list/status), no-remote handling, single-repo exit, scaffolding creation
-
-## File List
-
-- `.claude/skills/repo-sync-check/SKILL.md` — New: repo sync check skill definition
-- `.claude/skills/MANIFEST.yaml` — Added repo-sync-check entry
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Updated 16-6 status
-- `_bmad-output/implementation-artifacts/16-6-repo-sync-check-skill.md` — Story file updated
-
-## Change Log
-
-- 2026-03-28: Created repo-sync-check skill for multi-repo layout validation — path checks, scaffolding, git sync.

package/_bmad-output/implementation-artifacts/done/16-7-portable-path-storage.md

@@ -1,109 +0,0 @@
-# Story 16.7: Portable Path Storage
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **team member cloning a project with multi-repo layout**,
-I want stored paths to be portable across machines,
-So that `project-layout.yaml` and `config.yaml` don't contain absolute paths that only work on the original developer's machine.
-
-## Problem Context
-
-`writeProjectLayoutYaml()` at [cli.js:329-368](bin/cli.js#L329-L368) writes absolute resolved paths like `d:/Code/kb-repo` into `_bmad-output/project-layout.yaml`. This file lives inside `_bmad-output/` which is typically committed to git. When another developer clones the repo, those absolute paths are wrong for their machine.
-
-Similarly, `writeRepoLayoutConfig()` writes absolute paths into `_bmad/bmm/config.yaml`.
-
-## Acceptance Criteria
-
-1. **Given** a local multi-repo path that is a sibling or relative to the project root, **When** the config is written, **Then** the path is stored as a relative path from the project root (e.g., `../kb-repo` instead of `d:/Code/kb-repo`)
-2. **Given** a local path that cannot be expressed as a simple relative path (different drive on Windows, no common ancestor), **When** the config is written, **Then** the absolute path is stored but a comment warns: `# PORTABILITY: absolute path — other developers may need to reconfigure`
-3. **Given** a remote repo with a gitUrl, **When** the config is written, **Then** the gitUrl is always stored (it's inherently portable), and the local clone path is stored as relative if possible
-4. **Given** stored relative paths, **When** `readExistingLayout()` (Story 16.5) reads them back, **Then** it resolves them to absolute paths using `path.resolve(projectRoot, storedPath)` for runtime use
-5. **Given** a `project-layout.yaml` with relative paths, **When** agents read the file, **Then** the paths work correctly because agents operate from the project root
-6. **Given** a `config.yaml` with artifact paths derived from relative base paths, **When** the derived `planning_artifacts` and `implementation_artifacts` are written, **Then** they are also relative (e.g., `../kb-repo/_bmad-output/planning-artifacts`)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Add relative path computation utility
-  - [x] 1.1 Create `toPortablePath(absolutePath, projectRoot)` function in `bin/cli.js`
-  - [x] 1.2 Use `path.relative(projectRoot, absolutePath)` to compute relative path
-  - [x] 1.3 If the relative path starts with more than 3 levels of `..` or crosses drive boundaries (Windows), fall back to absolute with portability comment
-  - [x] 1.4 Normalize to forward slashes (existing `normalizePath()`)
-
-- [x] Task 2: Update `writeProjectLayoutYaml()` to use relative paths
-  - [x] 2.1 Convert each concern's path through `toPortablePath()` before writing
-  - [x] 2.2 Add portability warning comment for absolute paths that couldn't be made relative
-
-- [x] Task 3: Update `writeRepoLayoutConfig()` to use relative paths
-  - [x] 3.1 Convert `knowledgebase_path` and `sprint_management_path` through `toPortablePath()`
-  - [x] 3.2 Derive `planning_artifacts` and `implementation_artifacts` from the portable paths
-
-- [x] Task 4: Update `readExistingLayout()` (Story 16.5 dependency) to resolve relative paths
-  - [x] 4.1 When reading paths from files, resolve them via `path.resolve(projectRoot, storedPath)`
-  - [x] 4.2 Handle both relative and absolute paths (backward compatibility with existing configs)
-
-- [x] Task 5: Write unit tests
-  - [x] 5.1 Test sibling path is stored as relative: `d:/Code/kb` from `d:/Code/agents` becomes `../kb`
-  - [x] 5.2 Test deeply nested relative still works: `../../other/kb`
-  - [x] 5.3 Test cross-drive path falls back to absolute with warning (Windows)
-  - [x] 5.4 Test round-trip: write relative, read back, resolve to absolute matches original
-  - [x] 5.5 Test `.` path (same repo) remains unchanged
-  - [x] 5.6 Test derived artifact paths are relative when base path is relative
-
-## Dev Notes
-
-### Dependencies
-
-- Story 16.5 (`readExistingLayout`) should be implemented first — Task 4 extends it
-- Can be developed in parallel if the `readExistingLayout` interface is agreed upon
-
-### Path Resolution Strategy
-
-```
-Project root: d:/Code/agents
-External KB:  d:/Code/kb-repo
-
-Relative:     ../kb-repo
-Stored:       path: "../kb-repo"
-Derived:      planning_artifacts: "../kb-repo/_bmad-output/planning-artifacts"
-```
-
-### Backward Compatibility
-
-Existing configs with absolute paths must still work. `readExistingLayout()` should handle both forms: if the path is already absolute, use it directly. If relative, resolve from project root.
-
-### References
-
-- [Source: bin/cli.js — writeProjectLayoutYaml() at line 329]
-- [Source: bin/cli.js — writeRepoLayoutConfig() at line 304]
-- [Source: Adversarial Review Finding #7 — absolute paths break portability]
-
-## Dev Agent Record
-
-### Implementation Plan
-- Added `toPortablePath(absolutePath, projectRoot)` — converts absolute paths to relative using `path.relative()`, with fallback to absolute for cross-drive or deeply nested (>3 levels) paths
-- Added `resolveStoredPath(storedPath, projectRoot)` — resolves relative paths back to absolute at read time, passes absolute paths through unchanged
-- Updated `writeProjectLayoutYaml()` and `writeRepoLayoutConfig()` to convert paths through `toPortablePath()` before writing
-- Updated `readExistingLayout()` to resolve stored relative paths via `resolveStoredPath()`
-- Portability warning comment added for non-portable absolute paths
-
-### Completion Notes
-- All 5 tasks implemented with 20 dedicated tests
-- Full regression suite passes (all existing tests unaffected, including 16-5 tests)
-- Backward compatible: existing absolute paths in config files still work correctly
-- Round-trip verified: write relative -> read back -> resolve = original absolute path
-- No new dependencies added
-
-## File List
-
-- `bin/cli.js` — Added `toPortablePath()`, `resolveStoredPath()`, updated `writeProjectLayoutYaml()`, `writeRepoLayoutConfig()`, `readExistingLayout()`, updated exports
-- `test/portable-paths.test.js` — New: 20 unit tests covering toPortablePath, resolveStoredPath, write functions with portability, round-trip, backward compat
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Updated 16-7 status
-- `_bmad-output/implementation-artifacts/16-7-portable-path-storage.md` — Story file updated
-
-## Change Log
-
-- 2026-03-28: Implemented portable path storage — paths stored as relative when possible, resolved at read time. 20 tests added.

package/_bmad-output/implementation-artifacts/done/16-8-cicd-remote-mode.md

@@ -1,97 +0,0 @@
-# Story 16.8: CI/CD Remote Repository Mode
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **CI/CD pipeline operator**,
-I want to configure remote git repositories for knowledgebase and sprint management in headless mode,
-So that automated pipelines can set up multi-repo layouts without interactive prompts.
-
-## Problem Context
-
-The `collectRepoLayout()` function with `flags.yes` at [cli.js:372-383](bin/cli.js#L372-L383) only supports `mode: 'local'` (via env var) or `mode: 'same'` (default). There is no env var for git URLs, no automated clone step, and no `mode: 'remote'` handling. A CI pipeline cannot set up a remote multi-repo layout. It silently degrades to local-path-or-default with no warning that remote mode is unavailable in automation.
-
-## Acceptance Criteria
-
-1. **Given** `--yes` flag and `MA_KNOWLEDGEBASE_GIT_URL` env var set, **When** `collectRepoLayout()` runs, **Then** it clones the repo to the path specified by `MA_KNOWLEDGEBASE_PATH` (required when git URL is set) and returns `mode: 'remote'` with the gitUrl stored
-2. **Given** `--yes` flag and `MA_SPRINT_GIT_URL` env var set, **When** `collectRepoLayout()` runs, **Then** it clones the sprint repo to `MA_SPRINT_PATH` and returns `mode: 'remote'`
-3. **Given** git URL env var set but corresponding path env var missing, **When** `collectRepoLayout()` runs, **Then** it exits with a clear error: "MA_KNOWLEDGEBASE_GIT_URL requires MA_KNOWLEDGEBASE_PATH to be set (clone destination)"
-4. **Given** the clone destination already exists and contains a `.git` directory, **When** the clone is attempted, **Then** it skips cloning and uses the existing directory (idempotent for re-runs)
-5. **Given** the clone destination already exists but is NOT a git repo, **When** the clone is attempted, **Then** it exits with error: "Destination exists but is not a git repo — remove it or use a different path"
-6. **Given** a clone failure in CI mode, **When** the clone fails, **Then** it exits with non-zero status and a clear error message (no fallback to same mode — CI should fail loudly)
-7. **Given** only `MA_KNOWLEDGEBASE_PATH` set (no git URL), **When** `collectRepoLayout()` runs, **Then** behavior is unchanged: `mode: 'local'` with the resolved path (backward compatible)
-8. **Given** both git URL and path env vars for both concerns point to the same repo, **Then** only one clone is performed
-
-## Tasks / Subtasks
-
-- [x] Task 1: Add new env var support to `collectRepoLayout()`
-  - [x] 1.1 Check `MA_KNOWLEDGEBASE_GIT_URL` and `MA_SPRINT_GIT_URL` env vars
-  - [x] 1.2 Validate that when git URL is set, corresponding PATH var is also set — exit with clear error if not
-  - [x] 1.3 When both are set: mode is `'remote'`, path is resolved PATH, gitUrl is the URL
-
-- [x] Task 2: Implement CI-mode clone logic
-  - [x] 2.1 If destination exists with `.git/`: skip clone, log info "Using existing clone at {path}"
-  - [x] 2.2 If destination exists without `.git/`: exit with error (ambiguous state)
-  - [x] 2.3 If destination doesn't exist: clone using same `execFileSync` pattern as interactive mode
-  - [x] 2.4 On clone failure: exit with non-zero code (no fallback — CI must fail explicitly)
-  - [x] 2.5 If both concerns have same git URL + path: clone once, reference for both
-
-- [x] Task 3: Write unit tests
-  - [x] 3.1 Test `--yes` + git URL + path env vars returns remote mode with correct fields
-  - [x] 3.2 Test `--yes` + git URL without path env var exits with error
-  - [x] 3.3 Test existing git repo at destination skips clone
-  - [x] 3.4 Test existing non-git directory at destination errors
-  - [x] 3.5 Test backward compatibility: PATH without URL still returns local mode
-
-## Dev Notes
-
-### Env Var Summary (After This Story)
-
-| Env Var | Purpose | Required With |
-|---------|---------|---------------|
-| `MA_KNOWLEDGEBASE_PATH` | Local path for knowledgebase | Standalone or with GIT_URL |
-| `MA_SPRINT_PATH` | Local path for sprint management | Standalone or with GIT_URL |
-| `MA_KNOWLEDGEBASE_GIT_URL` | Git URL for knowledgebase repo | Requires MA_KNOWLEDGEBASE_PATH |
-| `MA_SPRINT_GIT_URL` | Git URL for sprint management repo | Requires MA_SPRINT_PATH |
-
-### CI Behavior: Fail Loudly
-
-Interactive mode falls back to `same` on clone failure. CI mode must NOT do this — a failed clone in CI means the pipeline is broken and should exit non-zero. Use `process.exit(1)` with a clear error, not a silent fallback.
-
-### Idempotency
-
-CI pipelines re-run frequently. If the clone destination already exists and is a valid git repo, skip the clone. This makes the step idempotent without needing `rm -rf` in pipeline scripts.
-
-### References
-
-- [Source: bin/cli.js — collectRepoLayout() --yes mode at line 372]
-- [Source: Adversarial Review Finding #8 — CI/CD can't do remote mode]
-
-## Dev Agent Record
-
-### Implementation Plan
-- Added `ciCloneIfNeeded(destPath, gitUrl, clonedRepos)` — handles clone-or-skip logic with dedup tracking
-- Extended `collectRepoLayout()` --yes mode to check `MA_KNOWLEDGEBASE_GIT_URL` / `MA_SPRINT_GIT_URL` env vars
-- Validation: git URL without corresponding PATH exits with clear error
-- Clone idempotency: existing `.git/` = skip; existing non-git = error; missing = clone
-- Deduplication: same URL+path tracked via Map to avoid double clones
-
-### Completion Notes
-- All 3 tasks implemented with 9 dedicated tests
-- Full regression suite passes
-- CI behavior: fail loudly with `process.exit(1)` on errors — no silent fallback
-- Backward compatible: PATH without URL still returns local mode
-
-## File List
-
-- `bin/cli.js` — Added `ciCloneIfNeeded()`, extended `collectRepoLayout()` --yes mode with git URL env vars, updated exports
-- `test/cicd-remote-mode.test.js` — New: 9 tests covering remote mode, validation errors, clone logic, backward compat
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Updated 16-8 status
-- `_bmad-output/implementation-artifacts/16-8-cicd-remote-mode.md` — Story file updated
-
-## Change Log
-
-- 2026-03-28: Implemented CI/CD remote mode — `MA_KNOWLEDGEBASE_GIT_URL` / `MA_SPRINT_GIT_URL` env vars enable remote repo cloning in --yes mode. 9 tests added.