4.3 KiB

Raw Blame History

Issue #483: Generated story Markdown deviates from GFM/CommonMark (CRLF & whitespace) — breaks automated edits on Windows

Issue URL: https://github.com/bmad-code-org/BMAD-METHOD/issues/483 Status: Open Created: 2025-08-20T00:22:02Z Updated: 2025-08-20T00:24:39Z Author: amjarmed

Description

Describe the bug The markdown generated for story files (e.g., docs/stories/1.1.story.md) deviates from CommonMark / GitHub Flavored Markdown (GFM) conventions and uses non‑deterministic whitespace/line endings. On Windows, the output includes CRLF and inconsistent blank lines, which causes automated edit tools to fail exact‑match replacements. It also includes heading spacing that isn't standard and occasionally embeds punctuation that doesn't render consistently.

This makes the content brittle and hard to process with tooling (linting, remark/unified transforms, static site generators, and CLI edit steps).

Steps to Reproduce

Generate an example story using BMAD Methods for a Next.js app (Windows environment).
Attempt to programmatically update the QA Results section with an exact‑match old_string via the BMAD edit tool (or similar scripted replacement).
Observe that no occurrences are found even though the visual text appears identical.

Example terminal output:

x  Edit {"old_string":"## QA Results\\n\\n### Review Summary:\\n\\nThe story \"Project Initialization & Setup\" (Story 1.1) is well-defined and covers the essential setup for a new Next.js 15 application. The acceptance criter… |
|
|    Failed to edit, 0 occurrences found for old_string in C:\\Users\\amjarmed\\Desktop\\coding\\autoinvoice.com\\docs\\stories\\1.1.story.md. No edits made. The exact text in old_string was not found. Ensure you're not escaping content incorrectly and check whitespace, indentation, and context. Use read_file tool to verify.

Proposed Solution (PR)

Happy to open a PR to:

Normalize EOL to \n (LF) in generated markdown and templates across platforms; add an .editorconfig entry to enforce.
Apply Prettier to all generated .md with proseWrap: "always" (or preserve, your preference) to standardize spacing and remove trailing whitespace.
Add remark + remark-lint with remark-preset-lint-consistent and remark-preset-lint-recommended to enforce CommonMark/GFM conventions.
Update story templates to ensure:
- Single H1 per file, consistent H2/H3 hierarchy (e.g., ## QA Results, ### Review Summary).
- Consistent blank lines around headings/lists/blocks (one blank line before/after).
- No smart quotes/ellipses; use straight quotes " and three dots ... only when needed.
- Fenced code blocks with language hints (bash, json, etc.).
- No trailing spaces; no box‑drawing characters.
Add a test that snapshots a generated story and asserts normalized EOL + lint‑clean output.

References

CommonMark: https://commonmark.org/
GitHub Flavored Markdown: https://github.github.com/gfm/
Prettier: https://prettier.io/
remark/remark-lint: https://github.com/remarkjs/remark-lint

Expected Behavior

Generated story markdown is deterministic and GFM‑compliant.
Automated edits that rely on exact matches (and CI markdown tooling) succeed across OSes.
Rendering is consistent on GitHub and static site pipelines.

Environment Details

Please be Specific if relevant

Model(s) Used: Gemini cli, cline with gemini api
Agentic IDE Used: vscode CLI & web
WebSite Used: Local project
Project Language: TypeScript / Next.js 15
BMad Method version: latest as of 2025‑08‑20 (please confirm exact version)

Screenshots or Links

Screenshot: attached below

Terminal log: see snippet above

Additional Context

OS: Windows 11 (CRLF by default)
Likely contributors to mismatch: CRLF vs LF, extra blank lines, or punctuation differences. Normalizing templates + adding lint/format steps should resolve and improve downstream tooling compatibility.

Issue Metadata

Issue ID: 3336116275
Issue Number: 483
State: open
Comments: 0
Reactions: 2 (+1s)
Labels: None specified

4.3 KiB Raw Blame History Unescape Escape