feat: add AsciiDoc linter pre-commit hook (#285) (#286)

* chore: add AsciiDoc linter as pre-commit hook

Added docToolchain/asciidoc-linter to catch AsciiDoc syntax errors
before commit.

Changes:
- Add asciidoc-linter as dev dependency (from git)
- Configure local pre-commit hook for .adoc files
- Enable direct git references in hatchling config

Limitations:
- Linter does NOT currently detect Markdown tables (issue #38)
- Only detects WS001 warnings (missing spaces after markers)
- Requires manual fix of false positives (*bold* vs list markers)

Feature requests filed in asciidoc-linter repo:
- #38: Detect Markdown table syntax
- #39: Add native pre-commit hooks support (.pre-commit-hooks.yaml)
- #40: Publish to PyPI for easier installation

Testing:
- Tested on ADR-011.adoc with known Markdown table (not detected)
- Pre-commit hook runs successfully but needs improvements

Related: #285 (parent issue for AsciiDoc linting)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix: convert Markdown tables to AsciiDoc syntax in ADRs

Fixed incorrect Markdown table syntax in ADR-011 and ADR-012.
Converted to proper AsciiDoc table format with [cols] directive.

Before (Markdown):
| Dimension | Score | Level | Evidence |
|-----------|-------|-------|----------|
| Code Type | 2 | ... | ... |

After (AsciiDoc):
[cols="2,1,2,5"]
|===
| Dimension | Score | Level | Evidence

| Code Type | 2 | ... | ...
|===

Note: The asciidoc-linter does not yet detect this error (issue #38).
These were found by manual code review.

Linter status:
- Remaining WS001 warnings are false positives (confuses *bold* with * list)
- Same syntax exists in ADR-001 through ADR-010 (valid AsciiDoc)
- Commit uses --no-verify due to false positives blocking commit

Related: #285, docToolchain/asciidoc-linter#38

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* docs: document AsciiDoc linter setup and known issues

Added section to CLAUDE.md explaining:
- AsciiDoc linter integration via pre-commit hook
- Known issue: WS001 false positives on *bold* syntax
- Known issue: Markdown tables not detected
- Workaround: Use --no-verify for false positives
- Linter runs on all .adoc files in repository

This helps contributors understand:
- Why commits may be blocked by the linter
- How to distinguish real errors from false positives
- When to use --no-verify safely

Related: #285, asciidoc-linter#38, asciidoc-linter#41

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: raifdmueller

.pre-commit-config.yaml

@@ -25,3 +25,13 @@ repos:
       - id: check-merge-conflict
       - id: check-toml
       - id: mixed-line-ending
+
+  # AsciiDoc linter (local hook - requires dev dependencies)
+  - repo: local
+    hooks:
+      - id: asciidoc-linter
+        name: AsciiDoc Linter
+        entry: uv run asciidoc-linter
+        language: system
+        files: \.(adoc|asciidoc)$
+        args: [--format, plain]

CLAUDE.md

@@ -64,6 +64,40 @@ Development happens on a fork to keep `upstream/main` stable for `uv tool instal
 - Documentation, Issues, Pull-Requests etc. is always written in english
 - use responsible-vibe-mcp wherever suitable
 
+### AsciiDoc Linting
+
+The project uses [asciidoc-linter](https://github.com/docToolchain/asciidoc-linter) as a pre-commit hook to catch AsciiDoc syntax errors.
+
+**Known Issues (as of 2026-02-11):**
+
+- **WS001 false positives**: Linter incorrectly flags `*bold*` and `**bold**` syntax as list markers needing spaces
+  - These warnings can be safely ignored - the syntax is correct AsciiDoc
+  - See [asciidoc-linter#41](https://github.com/docToolchain/asciidoc-linter/issues/41)
+  - All ADR files (ADR-001 through ADR-013) trigger these false positives
+
+- **Markdown tables NOT detected**: Linter does not catch Markdown table syntax (`|---|---|`) in AsciiDoc files
+  - See [asciidoc-linter#38](https://github.com/docToolchain/asciidoc-linter/issues/38)
+  - Manual review required for table syntax
+
+**Workaround for commits:**
+
+When committing changes to `.adoc` files, the pre-commit hook may fail due to WS001 false positives:
+
+```bash
+# If only false positives (verify manually):
+git commit --no-verify -m "your message"
+
+# Or fix the linter output and commit normally
+git commit -m "your message"
+```
+
+**Real errors to watch for:**
+- Incorrect table syntax (Markdown vs AsciiDoc)
+- Heading hierarchy issues (HEAD001-003)
+- Unterminated blocks (BLOCK001)
+
+The linter runs on **all `.adoc` and `.asciidoc` files** in the repository.
+
 ## Commands
 
 ```bash

pyproject.toml

@@ -35,6 +35,7 @@ Issues = "https://github.com/docToolchain/dacli/issues"
 
 [project.optional-dependencies]
 dev = [
+    "asciidoc-linter @ git+https://github.com/docToolchain/asciidoc-linter.git",
     "hypothesis>=6.0.0",
     "pre-commit>=4.0.0",
     "pytest>=8.0.0",
@@ -55,6 +56,9 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/dacli"]
 
+[tool.hatch.metadata]
+allow-direct-references = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]

src/docs/arc42/adr/ADR-011.adoc

@@ -8,13 +8,16 @@
 
 The dacli CLI module requires risk classification according to the Risk Radar framework to determine appropriate security and quality assurance measures. The assessment evaluates five dimensions:
 
-| Dimension | Score | Level | Evidence |
-|-----------|-------|-------|----------|
-| Code Type | 2 | Business Logic | Click commands, service layer orchestration (`src/dacli/cli.py`, `src/dacli/services/`) |
-| Language | 2 | Dynamically typed | Python 3.12+ — 100% `.py` files |
-| Deployment | 1 | Internal tool | Command-line tool for documentation teams |
-| Data Sensitivity | 1 | Internal business data | Operates on internal documentation |
-| Blast Radius | 2 | Data loss (recoverable) | Could corrupt docs, recoverable from git |
+[cols="2,1,2,5"]
+|===
+| Dimension | Score | Level | Evidence
+
+| Code Type | 2 | Business Logic | Click commands, service layer orchestration (`src/dacli/cli.py`, `src/dacli/services/`)
+| Language | 2 | Dynamically typed | Python 3.12+ — 100% `.py` files
+| Deployment | 1 | Internal tool | Command-line tool for documentation teams
+| Data Sensitivity | 1 | Internal business data | Operates on internal documentation
+| Blast Radius | 2 | Data loss (recoverable) | Could corrupt docs, recoverable from git
+|===
 
 *Decision:*
 

src/docs/arc42/adr/ADR-012.adoc

@@ -8,13 +8,16 @@
 
 The dacli-mcp MCP server module requires risk classification according to the Risk Radar framework to determine appropriate security and quality assurance measures. The assessment evaluates five dimensions:
 
-| Dimension | Score | Level | Evidence |
-|-----------|-------|-------|----------|
-| Code Type | 2 | Business Logic | MCP tools, service layer (`src/dacli/mcp_app.py`, `src/dacli/services/`) |
-| Language | 2 | Dynamically typed | Python 3.12+ — 100% `.py` files |
-| Deployment | 1 | Internal tool | MCP server for LLM integration in internal workflows |
-| Data Sensitivity | 1 | Internal business data | Operates on internal documentation |
-| Blast Radius | 2 | Data loss (recoverable) | Could corrupt docs, recoverable from git |
+[cols="2,1,2,5"]
+|===
+| Dimension | Score | Level | Evidence
+
+| Code Type | 2 | Business Logic | MCP tools, service layer (`src/dacli/mcp_app.py`, `src/dacli/services/`)
+| Language | 2 | Dynamically typed | Python 3.12+ — 100% `.py` files
+| Deployment | 1 | Internal tool | MCP server for LLM integration in internal workflows
+| Data Sensitivity | 1 | Internal business data | Operates on internal documentation
+| Blast Radius | 2 | Data loss (recoverable) | Could corrupt docs, recoverable from git
+|===
 
 **Note:** Initial consideration was given to Code Type score 3 (API/Database Queries) since the module exposes API endpoints (MCP tools). However, user confirmed score 2 as these are internal service APIs without public exposure or direct database access.