From d01242ae7c101e062dd9d5506cba485ea777213b Mon Sep 17 00:00:00 2001
From: Stefan <stefan.goppelt@yoorie.de>
Date: Sun, 29 Mar 2026 15:14:33 +0200
Subject: [PATCH] docs(dod): enforce markdownlint rule for markdown files

---
 .githooks/README.md        |  5 +++++
 .githooks/pre-commit       | 15 +++++++++++++++
 AGENTS.md                  | 16 +++++++++-------
 docs/DEFINITION_OF_DONE.md |  6 ++++--
 4 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/.githooks/README.md b/.githooks/README.md
index 3d2190a..ad95056 100644
--- a/.githooks/README.md
+++ b/.githooks/README.md
@@ -14,3 +14,8 @@ The pre-commit hook validates for staged `.sh` files:
 
 - executable bit in Git index (`100755`)
 - LF line endings (no CRLF)
+
+The pre-commit hook also validates staged `.md` files with `markdownlint`:
+
+- no `markdownlint` errors or problems
+- requires `markdownlint` CLI in PATH (for example via `npm install --global markdownlint-cli`)
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index a8652d4..df1a085 100644
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -5,6 +5,7 @@ failed=0
 cr=$(printf '\r')
 
 staged_shell_files=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.sh$' || true)
+staged_markdown_files=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.md$' || true)
 
 for file in $staged_shell_files; do
   mode=$(git ls-files --stage -- "$file" | awk '{print $1}')
@@ -19,6 +20,20 @@ for file in $staged_shell_files; do
   fi
 done
 
+if [ -n "$staged_markdown_files" ]; then
+  if ! command -v markdownlint >/dev/null 2>&1; then
+    echo "ERROR: markdownlint is required to validate staged Markdown files (.md)." >&2
+    echo "Install with npm: npm install --global markdownlint-cli" >&2
+    failed=1
+  else
+    # Validate the staged markdown files currently present in the working tree.
+    # This keeps the hook simple and fast for standard project usage.
+    if ! markdownlint $staged_markdown_files; then
+      failed=1
+    fi
+  fi
+fi
+
 if [ "$failed" -ne 0 ]; then
   echo "Pre-commit check failed." >&2
   exit 1
diff --git a/AGENTS.md b/AGENTS.md
index 6de3336..b98e294 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,12 +23,12 @@ except `README.md` and `AGENTS.md`.
 
 ## Testing Expectations
 
-1. Add or update tests for behaviour changes.
+1. Add or update tests for behavior changes.
 2. Keep tests deterministic and fast.
 3. Prefer table-driven tests where they improve readability.
 4. Run relevant tests locally before finishing changes.
 5. For Go projects, use `github.com/smartystreets/goconvey`
-  as the standard test library.
+   as the standard test library.
 
 ## Build Artifacts and Reports
 
@@ -39,9 +39,9 @@ except `README.md` and `AGENTS.md`.
 
 1. Shell scripts (`*.sh`) must use LF line endings.
 2. Shell scripts committed to the repository must be executable
-  in Git index (mode `100755`).
-3. When adding a new shell script, set execute permissions before commit:
-  `git add --chmod=+x path/to/script.sh`.
+   in Git index (mode `100755`).
+3. When adding a new shell script, set execute permissions
+   before commit: `git add --chmod=+x path/to/script.sh`.
 
 ## Git Bash Execution Defaults
 
@@ -78,6 +78,7 @@ for every completed change in this repository.
 - Documentation is written in English.
 - Documentation files are placed under `docs/`.
 - Exceptions: `README.md` and `AGENTS.md` remain at repository root.
+- Markdown files have no `markdownlint` errors or problems.
 
 ### Technical Completion Criteria
 
@@ -89,8 +90,8 @@ for every completed change in this repository.
 1. No unresolved critical issues
 
 - No new blocking errors are introduced.
-- Known non-blocking warnings are acceptable only if unrelated
-  to the change or documented.
+- Known non-blocking warnings are acceptable
+  only if unrelated to the change or documented.
 
 1. SonarQube status
 
@@ -110,5 +111,6 @@ for every completed change in this repository.
 - [ ] Functionality is documented.
 - [ ] Documentation is in English.
 - [ ] Documentation is located under `docs/` (except `README.md` and `AGENTS.md`).
+- [ ] Markdown files have no `markdownlint` errors or problems.
 - [ ] No SonarQube errors are present.
 - [ ] No critical regressions found.
diff --git a/docs/DEFINITION_OF_DONE.md b/docs/DEFINITION_OF_DONE.md
index 1bdb9ee..bc0471b 100644
--- a/docs/DEFINITION_OF_DONE.md
+++ b/docs/DEFINITION_OF_DONE.md
@@ -25,6 +25,7 @@ for every completed change in this repository.
 - Documentation is written in English.
 - Documentation files are placed under `docs/`.
 - Exceptions: `README.md` and `AGENTS.md` remain at repository root.
+- Markdown files have no `markdownlint` errors or problems.
 
 ## Technical Completion Criteria
 
@@ -36,8 +37,8 @@ for every completed change in this repository.
 1. No unresolved critical issues
 
 - No new blocking errors are introduced.
-- Known non-blocking warnings are acceptable only if unrelated
-  to the change or documented.
+- Known non-blocking warnings are acceptable
+  only if unrelated to the change or documented.
 
 1. SonarQube status
 
@@ -57,5 +58,6 @@ for every completed change in this repository.
 - [ ] Functionality is documented.
 - [ ] Documentation is in English.
 - [ ] Documentation is located under `docs/` (except `README.md` and `AGENTS.md`).
+- [ ] Markdown files have no `markdownlint` errors or problems.
 - [ ] No SonarQube errors are present.
 - [ ] No critical regressions found.