fix(rules): blank-line separate multiple-choice options (#246)#278
Open
gluefactory wants to merge 1 commit into
Open
fix(rules): blank-line separate multiple-choice options (#246)#278gluefactory wants to merge 1 commit into
gluefactory wants to merge 1 commit into
Conversation
Consecutive `A) ... B) ...` option lines without a blank-line separator collapse into a single paragraph in strict CommonMark renderers (IntelliJ / PyCharm preview), because soft line breaks render as spaces. - Add blank lines between options in the question-format template, its examples, and the four files that follow the template (session-continuity, security-baseline.opt-in, property-based-testing.opt-in, WORKING-WITH-AIDLC). - Add CI step that fails when consecutive option lines lack a blank-line separator. Scope mirrors .markdownlint-cli2.yaml ignores. Closes awslabs#246 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
harmjeff
approved these changes
May 18, 2026
Contributor
harmjeff
left a comment
There was a problem hiding this comment.
LGTM! Clean fix for a real usability issue that hits users in the common case (IDE-driven workflows with strict CommonMark rendering).
Highlights:
- Correct approach per CommonMark spec — blank lines between options is the proper way to ensure they render as separate lines
- CI guard (
awkregex check) is smart and scoped consistently with existing markdownlint ignores - Good decision to leave evaluator golden files out of scope to keep the PR focused
- Thorough test plan (manual PyCharm verification + regression guard catching 38 existing offenders)
No concerns — approve.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #246.
Per the CommonMark spec, a soft line break renders as a single space. So
the multiple-choice template used in
question-format-guide.md—— collapses into one paragraph (
A) Option A B) Option B C) Option C) instrict renderers (IntelliJ, PyCharm preview, VS Code without the GFM
setting). Most AI-DLC users are in those exact IDE-driven workflows, so
this hits in the common case.
Changes
that follows it:
aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md(template + all in-page examples)
aidlc-rules/aws-aidlc-rule-details/common/session-continuity.mdaidlc-rules/aws-aidlc-rule-details/extensions/security/baseline/security-baseline.opt-in.mdaidlc-rules/aws-aidlc-rule-details/extensions/testing/property-based/property-based-testing.opt-in.mddocs/WORKING-WITH-AIDLC.mdmarkdownlint) fails whenany two consecutive lines both match
^[A-Z]\)without a blank-lineseparator. Scope mirrors
.markdownlint-cli2.yamlignores so behavioris consistent with existing markdown CI.
Out of scope (intentional)
Two evaluator golden files under
scripts/aidlc-evaluator/test_cases/still use the old format. They are excluded from the CI scope (same as
markdownlint's ignore list) and left untouched to keep this PR focused.
Test plan
this branch into a fresh project per the README's "Claude Code —
Option 1" instructions, then drove the workflow far enough to
generate a clarifying-questions file. Opened it in PyCharm's
Markdown preview (strict CommonMark) and confirmed each option
renders on its own line. Before this fix, the same flow produces
the collapsed-paragraph behaviour described in [Bug]: Question-format template renders as a single paragraph in strict CommonMark renderers (IntelliJ/PyCharm preview, etc.) #246.
main's content(38 offending option-line pairs across 5 files) and passes after
the fixes in this PR.
markdownlint-cli2continues to passcleanly across 43 in-scope files locally.
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.