Owner PR: Local artifacts: - PR-830-Summary.md - PR-830.diff - PR-830-conversation.md ## Objective Establish standards-compliant Markdown output across BMAD by validating the proposal in PR #830, detecting any related formatting defects already in v6-alpha, designing automated tests, implementing safe fixes (either by accepting the mandate, complementing it, or refining generators), and verifying with multiple parsers. ## Scope - Affects Markdown output generated by BMAD workflows/tasks, specifically around: - Blank lines around bullet and numbered lists - Blank lines around tables - Blank lines around fenced code blocks - Bullet style consistency (`-`) - Language identifiers for fenced code blocks - Does not change semantic content, ordering, or business logic. ## Constraints & Assumptions - Windows dev host (PowerShell). CI is GitHub Actions. - We will not mass-format repository docs; scope is limited to generator rules and tests. - We will prefer minimal changes with high leverage (mandate text + generator hygiene). ## Prior Work to Review (.patch) - .patch/483 — Markdown formatting utilities and tests (historical). Extract lessons/reusable checks. - .patch/821 — May include doc/format adjustments from other feature work; ensure no conflicts. - .patch/827 — Version string replacement effort provides patterns for safe batch validation. - Any other .patch/* items referencing "markdown" or "format". ## Detection Strategy 1. Static audit of generators - Inspect `bmad/core/tasks/workflow.xml` around `` to see how content is emitted. - Inspect `tools/format-workflow-md.js` (if used) and any output-format helpers under `tools/`. 2. Sample generation run - Choose 2–3 representative workflows (document-heavy, lists/tables/code present): - `bmad/bmb/workflows/convert-legacy/` - `bmad/core/workflows/brainstorming/` - One module workflow under `src/modules/bmm/...` - Generate outputs to a temp folder and collect resulting .md files. 3. Automated conformance checks - Rule-based regex checks for required blank lines around: lists, tables, code fences. - Check bullet characters normalization to `-`. - Check fenced code blocks have a language or fallback `text`. 4. Cross-parser verification - Pipe markdown through `commonmark` CLI to HTML and sanity-diff. - Optionally add `markdownlint` rules for blank-lines and fence language (non-blocking). ## Test Design - Unit-like checks (Node script): - Input: generated markdown string. - Asserts: - List blocks have blank line before and after when adjacent to non-list blocks. - Tables (`^\|`) have blank boundary lines. - Fenced blocks ``` have preceding/following blank line and a language token. - Bullet markers are `-` (not `*`/`+`). - Integration checks: - Generate from each selected workflow. - Run conformance script; capture violations with line numbers and rule ids. - Exit non-zero on violations; report summary. ## Fix Options - Option A (Accept PR mandate as-is): - Merge the new `` that encodes the six rules. - Pros: Minimal change, easy to maintain. Cons: Textual mandate may not enforce all edge cases. - Option B (Complementary generator hygiene): - Normalize bullets to `-` at emission time. - Add language when missing to fenced code (fallback `text`). - Auto-insert blank lines at block boundaries in formatter. - Option C (Post-processor): - After content generation, run a small formatting pass to insert/normalize boundaries. - Pros: Centralized; Cons: Risk of over-touching content if not carefully scoped. ## Risks and Mitigations - Over-formatting (false positives): - Mitigate with conservative regex that only operates at block boundaries. - Performance impact: - Minimal; formatting pass is linear. - Spec interpretation differences: - Link to CommonMark examples in tests; document allowed exceptions. ## Acceptance Criteria - No violations found by conformance checks on the selected workflows (0 errors). - `commonmark` output from before/after indicates improved structural HTML (lists rendered as lists, tables/blocks preserved). - No semantic diffs in content (only spacing). - CI job (optional) can run the conformance script and fail on regressions. ## Work Plan (High Level) 1. Review .patch antecedents (.patch/483 et al.) for reusable checks. 2. Implement quick Node conformance script under `tools/` (non-invasive; optional commit). 3. Generate sample outputs; baseline run -> record violations. 4. Apply PR #830 mandate text locally (no push yet). 5. Add minimal generator hygiene for bullets and fence language (if needed). 6. Re-run conformance; iterate until 0 errors. 7. Final verification with `commonmark` HTML diff. 8. Commit on `patch-830`; prepare review notes. ## Deliverables - Conformance script (Node) and its README (tiny). - Test run output logs under `.patch/830/test-logs/` (ignored by git if desired). - Change set: updated `workflow.xml` + (optional) small formatter hygiene. - Review update posted to PR #830. ## Rollback Plan - Changes are isolated; revert commits on `patch-830` or drop branch. No data migration needed. # PR-830 Investigation and Implementation Plan Title: CommonMark-compliant Markdown formatting rules Branch: patch-830 Owner PR: https://github.com/bmad-code-org/BMAD-METHOD/pull/830 Local artifacts: - PR-830-Summary.md - PR-830.diff - PR-830-conversation.md ## Objective Establish standards-compliant Markdown output across BMAD by validating the proposal in PR #830, detecting any related formatting defects already in v6-alpha, designing automated tests, implementing safe fixes (either by accepting the mandate, complementing it, or refining generators), and verifying with multiple parsers. ## Scope - Affects Markdown output generated by BMAD workflows/tasks, specifically around: - Blank lines around bullet and numbered lists - Blank lines around tables - Blank lines around fenced code blocks - Bullet style consistency (`-`) - Language identifiers for fenced code blocks - Does not change semantic content, ordering, or business logic. ## Constraints & Assumptions - Windows dev host (PowerShell). CI is GitHub Actions. - We will not mass-format repository docs; scope is limited to generator rules and tests. - We will prefer minimal changes with high leverage (mandate text + generator hygiene). ## Prior Work to Review (.patch) - .patch/483 — Markdown formatting utilities and tests (historical). Extract lessons/reusable checks. - .patch/821 — May include doc/format adjustments from other feature work; ensure no conflicts. - .patch/827 — Version string replacement effort provides patterns for safe batch validation. - Any other .patch/* items referencing "markdown" or "format". ## Detection Strategy 1. Static audit of generators - Inspect `bmad/core/tasks/workflow.xml` around `` to see how content is emitted. - Inspect `tools/format-workflow-md.js` (if used) and any output-format helpers under `tools/`. 2. Sample generation run - Choose 2–3 representative workflows (document-heavy, lists/tables/code present): - `bmad/bmb/workflows/convert-legacy/` - `bmad/core/workflows/brainstorming/` - One module workflow under `src/modules/bmm/...` - Generate outputs to a temp folder and collect resulting .md files. 3. Automated conformance checks - Rule-based regex checks for required blank lines around: lists, tables, code fences. - Check bullet characters normalization to `-`. - Check fenced code blocks have a language or fallback `text`. 4. Cross-parser verification - Pipe markdown through `commonmark` CLI to HTML and sanity-diff. - Optionally add `markdownlint` rules for blank-lines and fence language (non-blocking). ## Test Design - Unit-like checks (Node script): - Input: generated markdown string. - Asserts: - List blocks have blank line before and after when adjacent to non-list blocks. - Tables (`^\|`) have blank boundary lines. - Fenced blocks ``` have preceding/following blank line and a language token. - Bullet markers are `-` (not `*`/`+`). - Integration checks: - Generate from each selected workflow. - Run conformance script; capture violations with line numbers and rule ids. - Exit non-zero on violations; report summary. ## Fix Options - Option A (Accept PR mandate as-is): - Merge the new `` that encodes the six rules. - Pros: Minimal change, easy to maintain. Cons: Textual mandate may not enforce all edge cases. - Option B (Complementary generator hygiene): - Normalize bullets to `-` at emission time. - Add language when missing to fenced code (fallback `text`). - Auto-insert blank lines at block boundaries in formatter. - Option C (Post-processor): - After content generation, run a small formatting pass to insert/normalize boundaries. - Pros: Centralized; Cons: Risk of over-touching content if not carefully scoped. Recommendation: Blend A + B. Land the mandate (alignment with PR #830), plus minimal targeted hygiene in formatter for the two mechanical rules that a writer could miss: fence language fallback and bullet normalization. ## Risks and Mitigations - Over-formatting (false positives): - Mitigate with conservative regex that only operates at block boundaries. - Performance impact: - Minimal; formatting pass is linear. - Spec interpretation differences: - Link to CommonMark examples in tests; document allowed exceptions. ## Acceptance Criteria - No violations found by conformance checks on the selected workflows (0 errors). - `commonmark` output from before/after indicates improved structural HTML (lists rendered as lists, tables/blocks preserved). - No semantic diffs in content (only spacing). - CI job (optional) can run the conformance script and fail on regressions. ## Work Plan (High Level) 1. Review .patch antecedents (.patch/483 et al.) for reusable checks. 2. Implement quick Node conformance script under `tools/` (non-invasive; optional commit). 3. Generate sample outputs; baseline run -> record violations. 4. Apply PR #830 mandate text locally (no push yet). 5. Add minimal generator hygiene for bullets and fence language (if needed). 6. Re-run conformance; iterate until 0 errors. 7. Final verification with `commonmark` HTML diff. 8. Commit on `patch-830`; prepare review notes. ## Deliverables - Conformance script (Node) and its README (tiny). - Test run output logs under `.patch/830/test-logs/` (ignored by git if desired). - Change set: updated `workflow.xml` + (optional) small formatter hygiene. - Review update posted to PR #830. ## Rollback Plan - Changes are isolated; revert commits on `patch-830` or drop branch. No data migration needed.