BMAD-METHOD/.patch/830/plan.md

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 <if tag="template-output"> 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 <mandate critical="true"> 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 <if tag="template-output"> 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 <mandate critical="true"> 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.