ci: add markdownlint infrastructure#159
Conversation
Add .markdownlint-cli2.yaml with all current violations temporarily disabled and tiered for incremental re-enablement by prompt impact. Add ci.yml workflow with markdownlint-cli2-action on pull_request, push to main, and workflow_dispatch. Add .pre-commit-config.yaml for optional local pre-commit linting. No markdown content changes — violation fixes planned for follow-up PRs.
scottschreckengaust
force-pushed
the
worktree-add-markdownlint
branch
from
8380b3d to
b121070
Compare
Change `## Code of Conduct` to `# Code of Conduct` (H2 → H1) to satisfy MD041/first-line-heading. Only violation was outside aidlc-rules/ — zero LLM prompt impact. Rule re-enabled in config.
Fix 585 violations across 25 non-LLM-prompt files: - MD028: fix 4 blank lines in blockquotes (WORKING-WITH-AIDLC.md) - MD040: add language specifiers to 84 fenced code blocks - MD060: normalize table pipe spacing across 13 files (322 fixes) - Auto-fix: MD009, MD012, MD022, MD029, MD031, MD032, MD047, MD049 Re-enable 3 rules now at zero violations: MD049, MD034, MD028. Update remaining violation counts to aidlc-rules/-only totals. No files under aidlc-rules/ were modified — zero LLM prompt impact.
Set MD060 to "aligned" style in project config — all table columns are now width-padded with vertically aligned pipes. Add aidlc-rules/.markdownlint-cli2.yaml to suppress MD060 in LLM prompt files pending separate review. Aligned tables in 14 files outside aidlc-rules/ using automated formatter. Zero aidlc-rules/ content files modified.
Update git-cliff body template: - Add blank line after ### group headings (MD022/MD032) - Add postprocessor to collapse triple+ blank lines (MD012) - Set trim = false so leading \n creates inter-body separators Add CHANGELOG.md to markdownlint ignores since git-cliff postprocessors run per-body and cannot control inter-body spacing or trailing whitespace. Regenerate CHANGELOG.md with improved template.
Move all temporarily disabled rules from the top-level config into aidlc-rules/.markdownlint-cli2.yaml since violations exist only in that directory. The top-level config now contains only permanently disabled rules and global style settings.
github-actions
bot
added
documentation
Four tables had misaligned trailing pipes due to rows with longer content or multi-byte characters (em dash). Padded shorter rows so all pipes in each column align vertically.
scottschreckengaust
had a problem deploying
to
codebuild
GitHub Actions
Error
scottschreckengaust
requested review from
a team,
harmjeff,
raj-jain-aws,
scoropeza and
spraja08
scottschreckengaust
temporarily deployed
to
codebuild
GitHub Actions
Inactive
A. Executive SummaryLatest release: PR #159 High-level snapshot comparing the latest release against the golden baseline (the reference evaluation used as the quality target).
Full trend report available in the workflow artifacts. |
scoropeza
left a comment
scoropeza
left a comment
There was a problem hiding this comment.
Review — Non-blocking suggestions
Nice work on the incremental approach here — the tiered remediation plan ordered by LLM prompt impact is really well thought out, and keeping aidlc-rules/ untouched in this first PR is the right call.
Two minor things that can be addressed in a follow-up:
1. Concurrency group consistency
The new ci.yml uses {workflow}-{ref} for the concurrency group, while security-scanners.yml (from #161) recently added {event_name} to the group key to prevent push events from cancelling scheduled runs. Not an issue today since ci.yml has no schedule trigger, but worth aligning for consistency — and to avoid a subtle bug if a schedule trigger is ever added.
2. Pre-commit vs CI version mismatch
.pre-commit-config.yaml pins markdownlint-cli2 at v0.22.0, but the CI action uses v23.0.0. Different major versions could produce different results locally vs CI, which would be confusing for contributors. Aligning these would help ensure local and CI linting agree.
Tracking both as a follow-up issue. Everything else looks great — the permissions model, SHA pinning, per-directory config override, and the mechanical markdown fixes are all solid.
…nner section Add blank lines around fenced code blocks (MD031), align table pipes (MD060), and remove double blank line (MD012) in the security scanner documentation added by #161.
Aligns ci.yml concurrency group with the {workflow}-{event_name}-{ref}
pattern used across all other workflows.
scottschreckengaust
requested a deployment
to
codebuild
GitHub Actions
Waiting
added the event name to the concurrency group to future proof. |
Aligns codebuild.yml and pull-request-lint.yml concurrency groups with
the {workflow}-{event_name}-{ref} pattern for consistency and to prevent
schedule triggers from cancelling push events if added later.
scottschreckengaust
had a problem deploying
to
codebuild
GitHub Actions
Error
The v23.0.0 is the action wrapper version, not the CLI tool version. The action's package.json declares "markdownlint-cli2": "0.22.0" as its dependency. Both local pre-commit and CI are running the exact same linter |
scottschreckengaust
had a problem deploying
to
codebuild
GitHub Actions
Error
dreamorosi
left a comment
dreamorosi
left a comment
There was a problem hiding this comment.
Left a comment to simplify the permission group in the GH workflow
Uses the documented shorthand `permissions: {}` which is functionally
equivalent and future-proof against new permission scopes. Job-level
permissions that grant specific access are preserved.
scottschreckengaust
requested a deployment
to
codebuild
GitHub Actions
Waiting
scottschreckengaust
requested review from
MichaelWalker-git,
dreamorosi,
harmjeff and
scoropeza
done |
There was a problem hiding this comment.
@scottschreckengaust
Minor/Nits
- The ci.yml workflow name is very generic ("CI"). If we add more CI jobs added (tests, build, validation), the name is fine. But if it stays markdownlint-only, something more specific like "Lint" might be clearer in the GitHub Actions UI.
The PR adds an [Unreleased] section and moves the 0.1.6 block, creating a structural change to an auto-generated file. Since CHANGELOG.md is generated by git-cliff (cliff.toml), and the PR itself adds CHANGELOG.md to the markdownlint ignores list, these manual edits will likely be overwritten by the next release PR. The CHANGELOG changes and the ignore entry contradict each other -- if it's ignored from linting, there's no need to fix its formatting in this PR.
Approving as this can be tracked in a later issues and looks for good for the current PR PR
7 participants
Summary
Adds markdownlint-cli2 infrastructure and fixes all violations outside
aidlc-rules/. Remaining violations exist only in LLM prompt files and are temporarily disabled in config for incremental remediation..markdownlint-cli2.yaml— project rule configuration with tiered exceptions.github/workflows/ci.yml— CI workflow (pull_request,pushto main,workflow_dispatch).pre-commit-config.yaml— optional local pre-commit hookaidlc-rules/changes)Why a separate
ci.yml(notpull-request-lint.yml)pull-request-lint.ymlusespull_request_targetand deliberately never checks out PR code — it only inspects metadata (title, labels, body). Running markdownlint requires checking out code, which must usepull_requestto avoid running untrusted PR code in a privileged base-branch context.Violation Report
Starting point: 3,118 violations across 57 files (603,487 chars total)
What this PR resolves
aidlc-rules/Rules permanently disabled (1,674 violations)
MD013MD033<img>tags for screenshots/badges in READMEMD024MD036Rules fully re-enabled (0 violations)
MD041CODE_OF_CONDUCT.mdH2→H1MD049_→*outsideaidlc-rules/; zero violations insideMD034aidlc-rules/; zero violations insideMD028WORKING-WITH-AIDLC.mdblockquote continuations; zero insideIncremental Remediation Plan — Remaining
aidlc-rules/ViolationsAll 859 remaining violations are exclusively inside
aidlc-rules/(LLM prompt instructions). Each follow-up PR re-enables one rule and fixes its violations, ordered by minimal prompt impact.Tier 1: Zero prompt impact — invisible whitespace (15 violations)
MD009MD012MD047Tier 2: Zero prompt impact — formatting normalization (18 violations)
MD029MD026##markers, not:Tier 3: Zero prompt impact — blank line structure (731 violations)
MD022##regardless of whitespaceMD032MD031```markersTier 4: Minimal prompt impact — table formatting (34 violations)
MD060Tier 5: Low prompt impact — structural cosmetic (42 violations)
MD046MD007Tier 6: Needs review — adds content or changes structure (31 violations)
MD040MD025Permanently disabled — not planned
MD013MD033<img>tags needed for image sizing/alignmentMD024MD036Total summary
aidlc-rules/)Licenses
All dependencies are MIT licensed:
Test plan
ci.ymlworkflow runs successfully on this PR (0 violations expected)npx markdownlint-cli2 "**/*.md"produces 0 errors locally.pre-commit-config.yamlworks withpre-commit run --all-filesaidlc-rules/were modifiedaidlc-rules/By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.