docs(dod): enforce markdownlint rule for markdown files

.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`)

.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

AGENTS.md

@@ -23,7 +23,7 @@ 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.
@@ -40,8 +40,8 @@ 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:
+3. When adding a new shell script, set execute permissions
-  `git add --chmod=+x path/to/script.sh`.
+   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
+- Known non-blocking warnings are acceptable
-  to the change or documented.
+  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.

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
+- Known non-blocking warnings are acceptable
-  to the change or documented.
+  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.