From 4bef2a2aaa7e57f035deab5cde34acb6d1029182 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?=
 <ralf.d.mueller+AI@gmail.com>
Date: Fri, 13 Feb 2026 20:33:25 +0100
Subject: [PATCH] feat: Set up pre-commit hooks with AsciiDoc linter

- Add .pre-commit-config.yaml with AsciiDoc linter hook
- Add .pre-commit-install.sh installation script
- Update CONTRIBUTING.adoc with developer setup section
- Hooks run automatically on git commit
- Validates all .adoc files before commit

Closes #82
---
 .pre-commit-config.yaml | 30 ++++++++++++++++++++++++++++++
 .pre-commit-install.sh  | 28 ++++++++++++++++++++++++++++
 CONTRIBUTING.adoc       | 41 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 99 insertions(+)
 create mode 100644 .pre-commit-config.yaml
 create mode 100755 .pre-commit-install.sh

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..899db54
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,30 @@
+# Pre-commit hooks for Semantic Anchors
+# Install: pip install pre-commit
+# Setup: pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  # AsciiDoc Linter
+  - repo: local
+    hooks:
+      - id: asciidoc-linter
+        name: AsciiDoc Linter
+        entry: asciidoc-linter
+        language: system
+        files: \.adoc$
+        pass_filenames: true
+        args: [--format, console]
+        stages: [commit]
+
+  # Trailing whitespace
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: \.(adoc|md)$
+      - id: end-of-file-fixer
+        exclude: \.(adoc|md)$
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+        args: [--maxkb=1000]
diff --git a/.pre-commit-install.sh b/.pre-commit-install.sh
new file mode 100755
index 0000000..f70345c
--- /dev/null
+++ b/.pre-commit-install.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# Installation script for pre-commit hooks
+
+set -e
+
+echo "Installing pre-commit framework..."
+
+# Check if Python is available
+if ! command -v python3 &> /dev/null; then
+    echo "Error: Python 3 is required"
+    exit 1
+fi
+
+# Install pre-commit
+pip install pre-commit
+
+# Install AsciiDoc linter
+pip install git+https://github.com/doctoolchain/asciidoc-linter.git
+
+# Install pre-commit hooks
+pre-commit install
+
+echo "✓ Pre-commit hooks installed successfully!"
+echo ""
+echo "Usage:"
+echo "  - Hooks run automatically on 'git commit'"
+echo "  - Run manually: pre-commit run --all-files"
+echo "  - Update hooks: pre-commit autoupdate"
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 8bee50e..df02b71 100644
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -61,6 +61,47 @@ Evaluate the response:
 * *Depth:* Does it cover multiple related concepts?
 * *Specificity:* Is the scope well-defined?
 
+== Developer Setup
+
+=== Prerequisites
+
+* Git
+* Python 3.12+ (for pre-commit hooks)
+* Node.js 20+ (for website development, optional)
+
+=== Installing Pre-Commit Hooks
+
+**Required for all contributors!**
+
+Run the installation script:
+
+[source,bash]
+----
+./pre-commit-install.sh
+----
+
+This installs:
+
+* **AsciiDoc Linter** - validates anchor file syntax automatically
+* **pre-commit framework** - runs checks before each commit
+* **Standard hooks** - trailing whitespace, YAML/JSON validation
+
+=== Manual Hook Execution
+
+Run all hooks on all files:
+
+[source,bash]
+----
+pre-commit run --all-files
+----
+
+Run specific hook:
+
+[source,bash]
+----
+pre-commit run asciidoc-linter --all-files
+----
+
 == How to Propose a New Anchor
 
 We use an *automated workflow with GitHub Copilot* to validate and enrich proposals: