diff --git a/src/bmm/workflows/4-implementation/code-review/instructions.xml b/src/bmm/workflows/4-implementation/code-review/instructions.xml index e5649559d..77116caac 100644 --- a/src/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/bmm/workflows/4-implementation/code-review/instructions.xml @@ -94,6 +94,17 @@ 5. **Test Quality**: Are tests real assertions or placeholders? + + If story has a "Requirements Traceability" section (Enterprise track): + 1. **Verification Method Check**: For each referenced requirement, check if the specified verification method is satisfied: + - **Test**: Are there actual tests that verify this requirement? Tests must exist and be meaningful. + - **Demonstration**: Can the implemented feature be demonstrated to satisfy the requirement? + - **Inspection**: Does the code implementation clearly match the requirement intent? + - **Analysis**: Are there calculations, models, or analysis artifacts that verify the requirement? + 2. **Requirement Coverage**: Are ALL referenced PRD FRs actually addressed by the implementation? + 3. If verification gaps found → HIGH SEVERITY finding: "Requirement {{REQ-ID}} verification method '{{method}}' not satisfied" + + NOT LOOKING HARD ENOUGH - Find more problems! Re-examine code for: diff --git a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/bmm/workflows/4-implementation/sprint-planning/instructions.md index 316d2fec3..c19dfe8ec 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/bmm/workflows/4-implementation/sprint-planning/instructions.md @@ -144,7 +144,28 @@ development_status: Ensure all items are ordered: epic, its stories, its retrospective, next epic... - + +Check if the project is Enterprise track (look for StRS/SyRS/RTM documents or PRD frontmatter `track: enterprise`) + +If Enterprise track, enrich the sprint status with a requirements traceability comment block: + +```yaml +# REQUIREMENTS TRACEABILITY (Enterprise Track): +# ============================================= +# This section maps stories to their source requirements for traceability. +# Format: story-key: [PRD FR IDs] ← [SyRS IDs] ← [StRS IDs] +# +# requirements_trace: +# 1-1-user-authentication: [FR-AUTH-001, FR-AUTH-002] ← [SYS-FUNC-001] ← [STK-BIZ-001] +# 1-2-account-management: [FR-AUTH-003] ← [SYS-FUNC-002] ← [STK-BIZ-001] +``` + +Extract requirement ID references from each story's "Requirements Traceability" section (if present in epics document) +Add as YAML comments to sprint status for reference during development +If no requirement traceability found in stories, add a note suggesting to run the RTM workflow + + + Perform validation checks: - [ ] Every epic in epic files appears in {status_file} diff --git a/src/bmm/workflows/shared/templates/context-guard-rules.md b/src/bmm/workflows/shared/templates/context-guard-rules.md new file mode 100644 index 000000000..0419ecd48 --- /dev/null +++ b/src/bmm/workflows/shared/templates/context-guard-rules.md @@ -0,0 +1,39 @@ +# Context Guard Rules - Enterprise Track + +These rules MUST be followed by all agents when working with requirement documents in Enterprise track projects. They prevent common AI agent errors that can corrupt the requirements chain. + +## Requirement Modification Rules + +- **BASELINE CHECK:** Before modifying any requirement, verify the document's current `baseline_version` in frontmatter. If a baseline exists, changes MUST go through the change management workflow (`RM` command). +- **RTM UPDATE:** After any requirement change (add, modify, delete), the Requirements Traceability Matrix MUST be updated. Never leave the RTM out of sync. +- **TRACEABILITY:** Every new requirement MUST have a `Source` attribute referencing its origin (stakeholder need, StRS requirement, or technical derivation). +- **QUALITY:** Every new or modified requirement MUST satisfy the 9 ISO quality criteria: necessary, implementation-free, unambiguous, consistent, complete, singular, feasible, traceable, verifiable. +- **SCOPE GUARD:** NEVER add requirements that are not traceable to a stakeholder need or documented derivation. If a new need is discovered, it must be documented as a change request. + +## Document Integrity Rules + +- **VERSION TRACKING:** Always update `version` in frontmatter when modifying a requirement document. Use semantic versioning (1.0.0 → 1.1.0 for additions, 1.0.0 → 1.0.1 for corrections). +- **CHANGE LOG:** Always add an entry to the document's change history when making modifications. +- **STATUS MANAGEMENT:** Document status progresses: `draft` → `review` → `approved` → `baseline`. Never skip states. Never revert from `baseline` without a formal change request. +- **UNIQUE IDs:** Never reuse a deleted requirement's ID. Maintain ID sequence continuity without gaps. + +## Cross-Document Consistency Rules + +- **TERMINOLOGY:** Use terms consistently across all documents. If a concept is named "user" in the StRS, it must be "user" in the SyRS, PRD, and stories - not "customer", "end-user", or "client" interchangeably. +- **SCOPE ALIGNMENT:** PRD scope must not exceed StRS scope. SyRS scope must not exceed PRD scope. Stories must not introduce features beyond PRD scope. +- **PRIORITY CONSISTENCY:** A requirement's priority should not increase downstream without justification (e.g., StRS "Should" should not become PRD "Must" without documented rationale). +- **CONTRADICTION DETECTION:** If you detect a contradiction between documents, STOP and flag it to the user. Do not silently resolve contradictions. + +## Assumption Management Rules + +- **NO SILENT ASSUMPTIONS:** Never fill in missing requirement details with assumptions. If information is missing, ask the user. +- **DOCUMENT ASSUMPTIONS:** If an assumption must be made to proceed, document it explicitly in the document's Assumptions section. +- **VALIDATE ASSUMPTIONS:** When loading input documents, verify that assumptions from upstream documents have been validated or still hold. + +## Usage + +These rules should be referenced by Enterprise track workflow steps. Include this at the beginning of content-generation steps: + +```markdown +**Enterprise Track Context Guards Active.** All requirement modifications follow formal change control. +``` diff --git a/src/bmm/workflows/shared/templates/document-versioning-guide.md b/src/bmm/workflows/shared/templates/document-versioning-guide.md new file mode 100644 index 000000000..5f511c964 --- /dev/null +++ b/src/bmm/workflows/shared/templates/document-versioning-guide.md @@ -0,0 +1,99 @@ +# Document Versioning and Approval Guide - Enterprise Track + +## Frontmatter Standard + +All Enterprise track requirement documents MUST include these frontmatter fields: + +```yaml +--- +version: "1.0.0" +status: "draft" +baseline_version: null +track: "enterprise" +last_updated: "{{date}}" +last_updated_by: "{{agent_name}}" +change_log: + - version: "1.0.0" + date: "{{date}}" + change: "Initial creation" + by: "{{agent_name}}" +--- +``` + +## Version Numbering + +Follow semantic versioning for requirement documents: + +| Change Type | Version Bump | Example | +|------------|-------------|---------| +| Initial creation | 1.0.0 | First draft | +| New requirements added | +0.1.0 | 1.0.0 → 1.1.0 | +| Requirement modifications | +0.1.0 | 1.1.0 → 1.2.0 | +| Corrections/typos | +0.0.1 | 1.2.0 → 1.2.1 | +| Major restructuring | +1.0.0 | 1.2.1 → 2.0.0 | +| Post-baseline changes | +0.1.0 minimum | Via change request only | + +## Document Status Lifecycle + +``` +draft → review → approved → baseline + ↑ | + └──── (change request) ─────┘ +``` + +### Status Definitions + +| Status | Meaning | Who Can Transition | +|--------|---------|-------------------| +| **draft** | Document is being created or actively modified | Any agent during workflow | +| **review** | Document is complete and ready for quality validation | Workflow completion step | +| **approved** | Document has passed quality validation | User confirmation | +| **baseline** | Document is locked for reference; changes require formal CR | User explicit approval | + +### Transition Rules + +1. `draft` → `review`: Workflow completion step sets this automatically +2. `review` → `approved`: User confirms after validation workflow passes +3. `approved` → `baseline`: User explicitly baselines (typically at phase transition quality gate) +4. `baseline` → `draft` (new version): Only via approved Change Request (CR) + +## Baseline Management + +### When to Baseline + +- At each quality gate (QG-1, QG-2, QG-3) for documents assessed +- Before starting the next development phase +- When all stakeholders agree the document is stable + +### Baseline Rules + +1. Record `baseline_version` in frontmatter (matches current `version`) +2. All requirement IDs are frozen at baseline +3. Changes after baseline require formal Change Request +4. Previous baseline versions should be noted in change log + +## Change Log Format + +Each change log entry should include: + +```yaml +change_log: + - version: "1.2.0" + date: "2024-01-15" + change: "Added FR-AUTH-005 per CR-003" + by: "John (PM)" + cr_ref: "CR-003" # Optional: link to change request +``` + +## Approval History (Optional) + +For formal approval tracking: + +```yaml +approval_history: + - version: "1.0.0" + date: "2024-01-10" + approved_by: "Mary (Analyst)" + status: "approved" + notes: "Initial StRS approved after QG-1" +```