216 lines
11 KiB
Markdown
216 lines
11 KiB
Markdown
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.
|