# Story 10.2: Document _bmad-output Policy in README and Installation Guidance

Status: done

depends-on: 10-1-ensure-bmad-output-not-gitignored

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

As a **Chief Architect**,
I want the _bmad-output folder policy documented in the README and installation guidance,
So that developers understand why _bmad-output is version-controlled and do not add it back to .gitignore.

## Acceptance Criteria

1. **Given** the project README, **When** a developer reads it, **Then** it contains a dedicated section explaining that `_bmad-output/` is intentionally tracked in version control as project knowledge, **And** the section explains what the folder contains (planning artifacts: PRDs, architecture, epics, stories, sprint plans), **And** the section explains why it is tracked (team alignment, AI context continuity, project history).
2. **Given** the installation or getting-started documentation, **When** a developer sets up the tool, **Then** the guidance explicitly states that `_bmad-output/` must not be added to `.gitignore` and explains that the installer will remove it if found.
3. **Given** the README section on `_bmad-output`, **When** a developer's IDE or tooling suggests adding it to `.gitignore`, **Then** the documentation gives them the language to confidently decline (i.e., the rationale is clear and actionable).

## Tasks / Subtasks

- [x] Add `_bmad-output/` policy section to README.md (AC: #1, #3)
  - [x] Place section under an appropriate heading — after the installation section or as part of a "Project Structure" or "How It Works" section
  - [x] Section heading: `## Project Knowledge: _bmad-output/`
  - [x] Content must include:
    - [x] What the folder is: planning artifacts generated by BMAD agents (PRDs, architecture docs, epics, stories, sprint status)
    - [x] Why it is tracked: enables team alignment on AI-generated plans, provides context continuity for AI agents across sessions, preserves decision history
    - [x] Explicit statement: "Do not add `_bmad-output/` to your `.gitignore`"
    - [x] Note: the installer automatically removes `_bmad-output/` from `.gitignore` if it finds it there
- [x] Add `_bmad-output/` guidance to installation documentation (AC: #2)
  - [x] If a dedicated installation guide exists (e.g., INSTALL.md, docs/getting-started.md, or equivalent): add a note in the post-install or project setup section
  - [x] If no separate installation doc exists: add the note to the README installation section
  - [x] Content: "`_bmad-output/` is tracked by the installer as version-controlled project knowledge. Do not add it to `.gitignore`. If it is present in `.gitignore`, the installer will remove it automatically."
- [x] Verify the section is discoverable (AC: #3)
  - [x] Confirm the `_bmad-output/` section is reachable from the README table of contents (if one exists) or appears within the first two major sections of the document
- [x] Test — README contains required content (AC: #1)
  - [x] Assert README.md contains the exact heading `## Project Knowledge: _bmad-output/` (or equivalent agreed heading)
  - [x] Assert README.md contains the phrase "Do not add `_bmad-output/` to your `.gitignore`"
  - [x] Assert README.md mentions at least one reason for tracking (e.g., "team alignment", "AI context", "planning artifacts")
- [x] Test — installation guidance contains the policy note (AC: #2)
  - [x] Assert the relevant installation doc contains the phrase "`_bmad-output/`" in a policy/setup context
  - [x] Assert the installer behavior (auto-removal from .gitignore) is mentioned

## Dev Notes

### Scope
This is a documentation-only story. No code changes to `lib/installer.js`, `lib/agents.js`, or any other source file. The deliverables are markdown edits to `README.md` and optionally one installation documentation file.

### Rationale to Include
The documentation must give developers enough context to push back when their IDE suggests adding `_bmad-output/` to `.gitignore`. The key points:
1. **What**: AI-generated planning artifacts (PRDs, architecture, epics, stories, sprint plans)
2. **Why commit**: Team members need to see the same plans; AI agents need prior context across sessions; the history of decisions is valuable
3. **Installer behavior**: The tool actively removes this entry from `.gitignore` — documenting this prevents confusion when developers notice their `.gitignore` was modified

### Section Placement
Prefer placing the section near the existing description of how the tool works — not buried in a troubleshooting FAQ. Developers should encounter it during normal onboarding, not only when something goes wrong.

### Test Strategy
Documentation tests can be implemented as simple grep/regex assertions in the test suite:
```js
const readme = fs.readFileSync('README.md', 'utf-8');
assert(readme.includes('_bmad-output'));
assert(readme.includes('Do not add'));
```
These serve as regression guards — if someone accidentally removes the section, CI catches it.

### Critical Guardrails
- Do NOT modify any source code files in this story — documentation only
- Do NOT remove existing README sections — only add or extend
- The exact phrase "Do not add `_bmad-output/` to your `.gitignore`" (or semantically equivalent) must appear in the written content

### Project Structure Notes
- Modify: `README.md` — add `_bmad-output/` policy section
- Modify (if exists): installation guide or getting-started doc — add policy note
- No source code changes

### References
- [FR59: _bmad-output policy documented in README and installation guidance]
- [FR58: _bmad-output not added to .gitignore by installer — covered in Story 10.1]
- [Story 10.1 — ensureBmadOutputTracked() behavior that this story documents]

## Dev Agent Record

### Agent Model Used
claude-sonnet-4-6

### Debug Log References
None — documentation-only story.

### Completion Notes List
- ✅ Added `## Project Knowledge: _bmad-output/` section to README.md placed between "How It Works" and "Supported Agents" sections (discoverable early in document)
- ✅ Section covers: what the folder contains, why it's tracked (3 reasons), explicit do-not-gitignore directive, installer behaviour note
- ✅ No separate installation doc exists; policy guidance is in the README installation context (AC #2 satisfied)
- ✅ 5 regression tests added to `test/yes-flag.test.js` — all pass

### File List
- `README.md` (modified — added `## Project Knowledge: _bmad-output/` section)
- `test/yes-flag.test.js` (modified — added Story 10.2 documentation regression tests)

### Change Log
- 2026-03-18: Implemented Story 10.2 — documented _bmad-output/ policy in README.md with regression tests
