ci: add markdownlint infrastructure (awslabs#159)

* ci: add markdownlint infrastructure (config, CI workflow, pre-commit)

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.

* ci: fix MD041 in CODE_OF_CONDUCT.md, re-enable rule

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: resolve all markdownlint violations outside aidlc-rules/

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.

* style: enforce MD060 aligned table style, fix 1645 violations

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.

* chore: improve cliff.toml template for markdownlint compliance

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.

* refactor: move aidlc-rules/ exceptions to per-directory config

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.

* fix: align table pipes in ADMINISTRATIVE_GUIDE.md for MD060

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.

* fix: resolve markdownlint violations in DEVELOPERS_GUIDE security scanner 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 awslabs#161.

* fix: add event_name to concurrency group key for consistency

Aligns ci.yml concurrency group with the {workflow}-{event_name}-{ref}
pattern used across all other workflows.

* fix: add event_name to concurrency group keys for all workflows

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.

* fix: replace verbose deny-all permissions with permissions: {}

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.

---------

Co-authored-by: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com>
Co-authored-by: Sam Castro <scoropeza@gmail.com>

Author: scottschreckengaust

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  push:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdownlint:
+    name: Markdown Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 #v6.0.1
+      - uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 #v23.0.0
+        with:
+          globs: "**/*.md"

.github/workflows/codebuild.yml

@@ -21,29 +21,14 @@ on:
       - 'v*'
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
   cancel-in-progress: true
 
 env:
   CODEBUILD_PROJECT_NAME: ${{ vars.CODEBUILD_PROJECT_NAME || 'codebuild-project' }}
   LABEL_REMINDER_MARKER: rules-label-reminder
 
-permissions:
-  actions: none
-  attestations: none
-  checks: none
-  contents: none
-  deployments: none
-  discussions: none
-  id-token: none
-  issues: none
-  models: none
-  packages: none
-  pages: none
-  pull-requests: none
-  repository-projects: none
-  security-events: none
-  statuses: none
+permissions: {}
 
 jobs:
   label-reminder:

.github/workflows/pull-request-lint.yml

@@ -15,25 +15,10 @@ on:
     types:
       - checks_requested
 
-permissions:
-  actions: none
-  attestations: none
-  checks: none
-  contents: none
-  deployments: none
-  discussions: none
-  id-token: none
-  issues: none
-  models: none
-  packages: none
-  pages: none
-  pull-requests: none
-  repository-projects: none
-  security-events: none
-  statuses: none
+permissions: {}
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
   cancel-in-progress: true
 
 env:

.github/workflows/release-pr.yml

@@ -21,22 +21,7 @@ on:
         required: false
         type: string
 
-permissions:
-  actions: none
-  attestations: none
-  checks: none
-  contents: none
-  deployments: none
-  discussions: none
-  id-token: none
-  issues: none
-  models: none
-  packages: none
-  pages: none
-  pull-requests: none
-  repository-projects: none
-  security-events: none
-  statuses: none
+permissions: {}
 
 jobs:
   release-pr:

.github/workflows/release.yml

@@ -23,22 +23,7 @@ on:
     tags:
       - 'v*'
 
-permissions:
-  actions: none
-  attestations: none
-  checks: none
-  contents: none
-  deployments: none
-  discussions: none
-  id-token: none
-  issues: none
-  models: none
-  packages: none
-  pages: none
-  pull-requests: none
-  repository-projects: none
-  security-events: none
-  statuses: none
+permissions: {}
 
 jobs:
   release:

.github/workflows/security-scanners.yml

@@ -10,22 +10,7 @@ on:
   pull_request:
     branches: [main]
 
-permissions:
-  actions: none
-  attestations: none
-  checks: none
-  contents: none
-  deployments: none
-  discussions: none
-  id-token: none
-  issues: none
-  models: none
-  packages: none
-  pages: none
-  pull-requests: none
-  repository-projects: none
-  security-events: none
-  statuses: none
+permissions: {}
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}

.github/workflows/tag-on-merge.yml

@@ -16,22 +16,7 @@ on:
   pull_request:
     types: [closed]
 
-permissions:
-  actions: none
-  attestations: none
-  checks: none
-  contents: none
-  deployments: none
-  discussions: none
-  id-token: none
-  issues: none
-  models: none
-  packages: none
-  pages: none
-  pull-requests: none
-  repository-projects: none
-  security-events: none
-  statuses: none
+permissions: {}
 
 jobs:
   tag:

.markdownlint-cli2.yaml

@@ -0,0 +1,39 @@
+# markdownlint-cli2 configuration
+# https://github.com/DavidAnson/markdownlint-cli2
+# Run: npx markdownlint-cli2 "**/*.md"
+# Fix: npx markdownlint-cli2 --fix "**/*.md"
+
+config:
+  # ============================================================
+  # PERMANENTLY DISABLED — conflict with project documentation style
+  # ============================================================
+
+  # Line-length — long URLs, tables, code examples, ASCII diagrams
+  MD013: false
+
+  # Inline HTML — <img> tags for screenshots/badges in README
+  MD033: false
+
+  # Duplicate headings — section names repeat across platform guides
+  MD024: false
+
+  # Emphasis as heading — bold text used as sub-labels in lists
+  MD036: false
+
+  # ============================================================
+  # STYLE SETTINGS
+  # ============================================================
+
+  # Tables must use aligned column style (pipes vertically aligned)
+  MD060:
+    style: "aligned"
+
+# Ignore generated/vendored/test fixture files
+ignores:
+  - "node_modules/**"
+  - ".claude/**"
+  - "scripts/aidlc-evaluator/test_cases/**"
+  # CHANGELOG.md is auto-generated by git-cliff (cliff.toml controls its format).
+  # git-cliff postprocessors run per-body so inter-body spacing and trailing
+  # whitespace cannot be fully controlled via template alone.
+  - "CHANGELOG.md"

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.22.0
+    hooks:
+      - id: markdownlint-cli2

CHANGELOG.md

@@ -1,8 +1,10 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
-## [0.1.7] - 2026-04-02
 
+## [Unreleased]
+
+## [0.1.7] - 2026-04-02
 
 ### Bug Fixes
 
@@ -17,13 +19,25 @@ All notable changes to this project will be documented in this file.
 - use PR head branch for rules-ref instead of merge ref (#168)
 - write aidlc-rules/VERSION in release PR to trigger CodeBuild (#169)
 
+### CI/CD
+
+- add markdownlint infrastructure (config, CI workflow, pre-commit)
+- fix MD041 in CODE_OF_CONDUCT.md, re-enable rule
 
 ### Documentation
 
 - add developer's guide for running CodeBuild locally (#94)
 - add working-with-aidlc interaction guide and writing-inputs documents (#121)
 - comprehensive documentation review and remediation (#113)
 
+- enforce MD060 aligned table style, fix 1645 violations
+
+## [0.1.6] - 2026-03-05
+
+### Bug Fixes
+
+- codebuild cache and download fix (#93)
+- correct copy-paste error in error-handling.md (#96)
 
 ### Features
 
@@ -36,7 +50,6 @@ All notable changes to this project will be documented in this file.
 - gate CodeBuild on 'codebuild' label + aidlc-rules paths (#150)
 - auto-label PRs touching aidlc-rules/ with codebuild label (#158)
 
-
 ### Miscellaneous
 
 - bump pyjwt in /scripts/aidlc-evaluator (#129)
@@ -45,77 +58,65 @@ All notable changes to this project will be documented in this file.
 - bump cryptography in /scripts/aidlc-evaluator (#148)
 - bump pygments in /scripts/aidlc-evaluator (#151)
 - bump aiohttp in /scripts/aidlc-evaluator (#163)
-## [0.1.6] - 2026-03-05
-
-
-### Bug Fixes
-
-- codebuild cache and download fix (#93)
-- correct copy-paste error in error-handling.md (#96)
 
+## [0.1.5] - 2026-02-24
 
 ### Features
 
 - add CodeBuild workflow (#92)
 
-
 ### Miscellaneous
 
 - add templates for github issues (#97)
-## [0.1.4] - 2026-02-24
 
+## [0.1.4] - 2026-02-24
 
 ### Bug Fixes
 
 - correct GitHub Copilot instructions and Kiro CLI rule-details path resolution (#82, #84) (#87)
-## [0.1.3] - 2026-02-11
 
+## [0.1.3] - 2026-02-11
 
 ### Bug Fixes
 
 - require actual system time for audit timestamps (#56)
 
-
 ### Documentation
 
 - clarify ZIP download location and consolidate notes (#70)
-## [0.1.2] - 2026-02-08
 
+## [0.1.2] - 2026-02-08
 
 ### Bug Fixes
 
 - typo in core-workflow.md
 - rename rule and move to bottom of Critical Rules section
 
-
 ### Documentation
 
 - update README to direct users to GitHub Releases (#61)
 - add Windows CMD setup instructions and ZIP note (#68)
 
-
 ### Features
 
 - add test automation friendly code generation rules
 - add frontend design coverage in Construction phase
-## [0.1.1] - 2026-01-22
 
+## [0.1.1] - 2026-01-22
 
 ### Features
 
 - adding AIDLC skill to work with IDEs such as Claude, OpenCode and others
 - addin
 - add leo file
 
-
 ### Miscellaneous
 
 - removing wrong files
 - removing wrong files
-## [0.1.0] - 2026-01-22
 
+## [0.1.0] - 2026-01-22
 
 ### Features
 
 - add Kiro CLI support and multi-platform architecture
-