Merge branch 'docs/planning-artifacts-and-bmad-update' into 'main'

chore(bmad): update BMAD modules to latest

See merge request orgdocs/development-standards!24

Author: Matthew

_bmad-output/planning-artifacts/prd.md

@@ -0,0 +1,243 @@
+---
+validationTarget: '_bmad-output/planning-artifacts/prd.md'
+validationDate: 2026-03-06
+inputDocuments:
+  - _bmad-output/planning-artifacts/prd.md
+  - _bmad-output/planning-artifacts/product-brief-development-standards-2026-03-06.md
+  - README.md
+  - STABILITY.md
+  - dev-toolchain/STABILITY.md
+  - dev-toolchain/CHANGELOG.md
+validationStepsCompleted: [format-detection, full-validation, fixes-applied, accepted]
+validationStatus: ACCEPTED
+overallResult: PASS WITH WARNINGS
+acceptedBy: Matthew
+acceptedDate: 2026-03-07
+fixesApplied:
+  - "C1: Target count removed, help/init added to inline list"
+  - "W7: '23 standards files' replaced with descriptive text (3 locations)"
+  - "C2: Planning repo STABILITY.md and CHANGELOG synced with actual repo"
+  - "W3: FR38 cross-referenced to FR7"
+  - "W6: Horizontal rule added before Phase 2 FRs"
+  - "FR56 added: make release target for manual versioned releases"
+---
+
+# PRD Validation Report
+
+**PRD Being Validated:** _bmad-output/planning-artifacts/prd.md
+**Validation Date:** 2026-03-06
+
+## Input Documents
+
+- PRD: prd.md
+- Product Brief: product-brief-development-standards-2026-03-06.md
+
+## Validation Findings
+
+## Format Detection
+
+**PRD Structure (## Level 2 Headers):**
+1. Executive Summary
+2. Success Criteria
+3. User Journeys
+4. Innovation & Novel Patterns
+5. Developer Tool Specific Requirements
+6. Product Scope & Phased Development
+7. Functional Requirements
+8. Non-Functional Requirements
+
+**BMAD Core Sections Present:**
+- Executive Summary: Present
+- Success Criteria: Present
+- Product Scope: Present (as "Product Scope & Phased Development")
+- User Journeys: Present
+- Functional Requirements: Present
+- Non-Functional Requirements: Present
+
+**Format Classification:** BMAD Standard
+**Core Sections Present:** 6/6
+
+**Additional Sections:** Innovation & Novel Patterns (maps to Innovation Analysis), Developer Tool Specific Requirements (maps to Project-Type Requirements)
+
+---
+
+## Full Validation Results
+
+**Overall Status: PASS WITH WARNINGS**
+
+| Severity | Count |
+|---|---|
+| Critical | 2 |
+| Warning | 8 |
+| Informational | 5 |
+
+---
+
+### Critical Findings
+
+#### C1: Makefile Target Count Inconsistency
+
+**Location:** Product Scope & Phased Development > MVP (Shipped)
+
+The PRD body (line 272) states **"10 Makefile targets"** and lists: lint, format, fix, test, security, scan, docs, changelog, check, install-hooks. However, the Makefile Target Contract table in the Developer Tool Specific Requirements section lists **12 targets** (adding `help` and `init`).
+
+**Impact:** Internal inconsistency — a reader gets different numbers depending on which section they read.
+
+**Fix:** Update body text to "12 Makefile targets" and add `help` and `init` to the inline list, or explicitly note which targets are excluded from the count and why.
+
+#### C2: Rust Release Status Unclear in Reference Documents
+
+**Location:** Cross-document consistency
+
+The PRD claims Rust as part of the shipped MVP ("8 language ecosystems"). The memory notes Rust was added 2026-03-04 as v1.4.0. However, the dev-toolchain CHANGELOG (used as a validation reference) shows v1.4.0 (2026-03-01) adding only `make init` — no Rust. The `[Unreleased]` section mentions "all 7 languages" (not 8). The dev-toolchain STABILITY.md also says "all 7 ecosystems."
+
+**Impact:** The PRD asserts Rust is shipped, but supporting reference documents don't yet reflect this. Either Rust hasn't been formally released, or the CHANGELOG/STABILITY docs are stale.
+
+**Fix:** Confirm Rust's release status in the actual dev-toolchain repo. If shipped, update CHANGELOG and STABILITY.md to reflect 8 ecosystems. If not yet released, PRD should note Rust as "integrated, pending release."
+
+---
+
+### Warnings
+
+#### W1: Implementation Leakage in Functional Requirements
+
+**Location:** FR9, FR16, FR17, FR18, FR21, FR46
+
+Several FRs name specific tools or implementation details that belong in architecture, not requirements:
+
+| FR | Leakage |
+|---|---|
+| FR9 | Names trivy, gitleaks, git-cliff as universal tools |
+| FR16 | Names trivy, gitleaks as scan tools |
+| FR17 | Names terraform-docs as docs tool |
+| FR18 | Names git-cliff as changelog tool |
+| FR21 | Describes two-layer delegation pattern (public targets → Docker → internal `_` targets) |
+| FR46 | Names Hugo and Cloudflare as implementation choices |
+
+**Impact:** If a tool is replaced (e.g., trivy → grype), the PRD needs updating. FRs should describe *what* the system does, not *how*.
+
+**Recommendation:** Accept as-is for a developer tool PRD where the tools *are* the product. Flag for awareness but don't rewrite — the specificity adds clarity for this project type.
+
+#### W2: Measurability Gaps in Agent-Related FRs
+
+**Location:** FR2, FR42, FR44
+
+| FR | Issue |
+|---|---|
+| FR2 | "AI agent can read agent instruction files and determine project standards without human explanation" — how is "determine" measured? |
+| FR42 | "AI agent can produce conventional commits without human reminding" — subjective ("without reminding") |
+| FR44 | "BMAD planning agents can incorporate DevRail standards into architecture and planning artifacts when instructed" — vague scope |
+
+**Impact:** These FRs describe desired agent behaviors but lack clear pass/fail criteria.
+
+**Recommendation:** Accept as aspirational for agent-related FRs — agent behavior is inherently harder to specify with binary pass/fail. The pre-commit hooks and CI provide the actual enforcement layer.
+
+#### W3: FR7 / FR38 Duplication
+
+**Location:** FR7 (Dev-Toolchain Container), FR38 (CI/CD Pipeline)
+
+- FR7: "Container can execute `make check` against any DevRail-compliant project and produce identical results to CI"
+- FR38: "CI results are identical to local `make check` results (same container, same tools, same config)"
+
+These say the same thing from opposite directions.
+
+**Recommendation:** Consolidate into one FR or cross-reference. Both exist because they're in different requirement groups, which is defensible — but note the duplication.
+
+#### W4: Product Brief Alignment — Token Efficiency Framing
+
+**Location:** Success Criteria
+
+The Product Brief explicitly states token efficiency is "not explicitly measured, but a natural consequence." The PRD's Success Criteria section reflects this accurately. However, the Executive Summary still references "burning tokens on boilerplate instructions" as a primary framing.
+
+**Recommendation:** Minor — the framing is accurate, just ensure the distinction between "motivation" (tokens) and "metric" (agent consistency, setup friction) remains clear.
+
+#### W5: Missing "Container Only" Adoption Path in User Journeys
+
+**Location:** User Journeys vs. Developer Tool Specific Requirements
+
+The Adoption Methods table lists 5 methods including "Container only" (docker pull for custom workflows). No user journey covers this path.
+
+**Recommendation:** Acceptable gap — this is a power-user path that doesn't need a narrative journey. Note for completeness.
+
+#### W6: Phase 2 FRs Mixed with Shipped FRs
+
+**Location:** Functional Requirements > Phase 2 Features
+
+FR52-FR55 are Phase 2 features grouped at the end. This is clear but could be visually stronger — a reader scanning FRs might not notice the phase boundary.
+
+**Recommendation:** Consider adding a horizontal rule or more prominent header before FR52.
+
+#### W7: "23 Standards Files" Count Not Verified
+
+**Location:** FR1, Executive Summary
+
+The PRD references "23 standards files" in multiple places. This count was not independently verified against the actual standards directory.
+
+**Recommendation:** Verify by counting files in `standards/` directory. If the count has changed, update all references.
+
+#### W8: NFR Performance Targets Are Aspirational
+
+**Location:** Non-Functional Requirements > Performance
+
+Performance NFRs specify targets (< 5 min for make check, < 60s for individual targets, < 30s for pre-commit) that read as aspirational rather than measured baselines.
+
+**Recommendation:** Accept as targets. When measured, note whether these are met. For a shipped product, empirical validation would strengthen these.
+
+---
+
+### Informational
+
+#### I1: Innovation Section Competitive Analysis Is Appropriately Scoped
+
+The competitive analysis (Super-linter, Cookiecutter, trunk.io) is honest and doesn't overstate claims. Good calibration for a solo developer project.
+
+#### I2: Risk Mitigation Is Practical
+
+Risk section covers technical, market, resource, and innovation risks with concrete mitigations. The container size risk and agent instruction format drift risks are particularly well-addressed.
+
+#### I3: User Journey Progression Is Logical
+
+The five journeys progress from zero-touch (greenfield) → partial adoption (brownfield) → system actor (agent) → future capability (init) → aspirational (contributor). Good arc.
+
+#### I4: NFR Integration Section Lists Specific Versions Implicitly
+
+The NFR compatibility section specifies minimum versions (Git 2.28+, pre-commit v3+) which is good for a developer tool. The 8-language concurrency requirement is explicitly stated.
+
+#### I5: Phasing Restructure Reflects Reality
+
+The MVP-as-shipped, Phase 2a/2b/3 structure accurately reflects the project's current state. No "we'll build it later" items blocking current use.
+
+---
+
+## Validation Summary
+
+| Dimension | Result | Notes |
+|---|---|---|
+| **Internal Consistency** | WARN | Target count mismatch (C1) |
+| **Cross-Document Consistency** | WARN | Rust release status (C2), standards file count unverified (W7) |
+| **Brief Alignment** | PASS | PRD faithfully reflects Product Brief vision, metrics, and scope |
+| **FR Quality** | WARN | Implementation leakage (W1), measurability gaps (W2), duplication (W3) |
+| **NFR Quality** | PASS | Performance targets aspirational but acceptable (W8) |
+| **Scoping** | PASS | Clear phase boundaries, shipped state accurately represented |
+| **Domain Compliance** | PASS | Developer tool requirements well-specified |
+| **Holistic Quality** | PASS | Well-structured, comprehensive, appropriate for project type and stage |
+
+---
+
+## Recommended Actions
+
+### Must Fix (Critical)
+1. Fix target count: update line 272 from "10" to "12" and add `help` and `init` to the list
+2. Verify Rust release status in actual dev-toolchain repo and update CHANGELOG/STABILITY if needed
+
+### Should Consider (Warnings)
+3. Consolidate FR7/FR38 or add cross-reference
+4. Verify "23 standards files" count against actual directory
+5. Add visual separator before Phase 2 FRs (FR52+)
+
+### Accept As-Is
+6. Implementation leakage in FRs (W1) — tools are the product
+7. Agent FR measurability (W2) — enforcement is via hooks/CI, not FR measurement
+8. Token efficiency framing (W4) — motivation vs metric distinction is clear enough
+9. Missing "container only" journey (W5) — power-user path
+10. NFR performance targets (W8) — reasonable aspirations

_bmad-output/planning-artifacts/product-brief-development-standards-2026-03-06.md

@@ -50,4 +50,4 @@ tea,4-implementation,ATDD,AT,10,_bmad/tea/workflows/testarch/atdd/workflow.yaml,
 tea,4-implementation,Test Automation,TA,20,_bmad/tea/workflows/testarch/automate/workflow.yaml,bmad_tea_automate,false,tea,bmad:backend services:agent:tea,Murat,🧪 Master Test Architect and Quality Advisor,Create Mode,Expand test coverage,test_artifacts,test suite
 tea,4-implementation,Test Review,RV,30,_bmad/tea/workflows/testarch/test-review/workflow.yaml,bmad_tea_test-review,false,tea,bmad:backend services:agent:tea,Murat,🧪 Master Test Architect and Quality Advisor,Validate Mode,Quality audit (0-100 scoring),test_artifacts,review report
 tea,4-implementation,NFR Assessment,NR,40,_bmad/tea/workflows/testarch/nfr-assess/workflow.yaml,bmad_tea_nfr-assess,false,tea,bmad:backend services:agent:tea,Murat,🧪 Master Test Architect and Quality Advisor,Create Mode,Non-functional requirements,test_artifacts,nfr report
-tea,4-implementation,Traceability,TR,50,_bmad/tea/workflows/testarch/trace/workflow.yaml,bmad_tea_trace,false,tea,bmad:backend services:agent:tea,Murat,🧪 Master Test Architect and Quality Advisor,Create Mode,Coverage traceability and gate,test_artifacts,traceability matrix|gate decision
+tea,4-implementation,Traceability,TR,50,_bmad/tea/workflows/testarch/trace/workflow.yaml,bmad_tea_trace,false,tea,bmad:backend services:agent:tea,Murat,🧪 Master Test Architect and Quality Advisor,Create Mode,Coverage traceability and gate,test_artifacts,traceability matrix|gate decision

_bmad-output/planning-artifacts/validation-report-2026-03-06.md

@@ -221,4 +221,4 @@ description: Brief description
 author: Author name
 date: YYYY-MM-DD
 ---
-```
+```

_bmad/_config/bmad-help.csv

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
           - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
       </step>
       <step n="3">Remember: user's name is {user_name}</step>
-      
+
       <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
       <step n="5">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example></step>
       <step n="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>

_bmad/_memory/tech-writer-sidecar/documentation-standards.md

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
           - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
       </step>
       <step n="3">Remember: user's name is {user_name}</step>
-      
+
       <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
       <step n="5">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example></step>
       <step n="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>

_bmad/bmm/agents/analyst.md

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
           - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
       </step>
       <step n="3">Remember: user's name is {user_name}</step>
-      
+
       <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
       <step n="5">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example></step>
       <step n="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>

_bmad/bmm/agents/architect.md

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
           - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
       </step>
       <step n="3">Remember: user's name is {user_name}</step>
-      
+
       <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
       <step n="5">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example></step>
       <step n="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>

_bmad/bmm/agents/pm.md

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
           - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
       </step>
       <step n="3">Remember: user's name is {user_name}</step>
-      
+
       <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
       <step n="5">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example></step>
       <step n="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>