Add AsciiDoc linter as pre-commit hook

[raifdmueller]

Problem

AsciiDoc files are repeatedly written with incorrect syntax, particularly when AI-generated content is involved. Recent example: ADR-011 and ADR-012 contain Markdown tables instead of AsciiDoc table syntax.

Example of incorrect syntax in src/docs/arc42/adr/ADR-011.adoc (lines 11-17):

| Dimension | Score | Level | Evidence |
|-----------|-------|-------|----------|
| Code Type | 2 | Business Logic | Click commands... |
| Language | 2 | Dynamically typed | Python 3.12+ |

This is Markdown table syntax, not AsciiDoc. Correct AsciiDoc syntax would be:

[cols="2,1,2,4"]
|===
| Dimension | Score | Level | Evidence

| Code Type | 2 | Business Logic | Click commands...
| Language | 2 | Dynamically typed | Python 3.12+
|===

Impact

• Documentation may not render correctly in AsciiDoc processors
• Inconsistent syntax across documentation files
• Manual review required to catch these errors
• Wastes time in PR reviews

Proposed Solution

Add an AsciiDoc linter as a pre-commit hook to catch syntax errors before commit.

Linter to use: docToolchain AsciiDoc Linter

Implementation Plan

1. Research the linter:

   • Check if it's available as a standalone CLI tool
   • Verify it can be integrated with pre-commit framework
   • Understand configuration options for arc42 documentation

2. Add to .pre-commit-config.yaml:

   - repo: https://github.com/docToolchain/asciidoc-linter  # (verify actual repo)
     rev: v1.0.0  # (use latest version)
     hooks:
       - id: asciidoc-lint
         files: \.(adoc|asciidoc)$
         args: ['--config', 'arc42']  # (if configurable)

3. Configure linter rules:

   • Table syntax validation (Markdown vs AsciiDoc)
   • Heading syntax (= vs #)
   • List syntax validation
   • Code block syntax (---- vs ```)
   • Include directive syntax

4. Test on existing files:

   • Run linter on all .adoc files in src/docs/
   • Fix reported issues
   • Verify linter catches the Markdown table issue

5. Update documentation:

   • Add linter setup to CLAUDE.md
   • Document how to run linter manually: uv run pre-commit run asciidoc-lint --all-files
   • Add to contributor guidelines

Alternative Approaches

If the docToolchain linter is not pre-commit compatible:

1. Wrap it in a local hook script:
   Create .pre-commit-hooks/asciidoc-lint.sh that calls the linter

2. Use asciidoctor with --warnings-as-errors:
   Less comprehensive but catches basic syntax errors

3. Create custom regex-based checks:
   Add simple regex patterns to catch common mistakes (Markdown tables, # headings)

Acceptance Criteria

• AsciiDoc linter integrated as pre-commit hook
• Linter runs on all .adoc files before commit
• Linter catches Markdown table syntax in AsciiDoc files
• Linter catches other common AsciiDoc syntax errors
• Pre-commit hook passes on correctly formatted AsciiDoc
• Documentation updated with linter usage
• CI workflow validates AsciiDoc syntax (same linter in GitHub Actions)

Related Issues

• Current ADR syntax errors: ADR-011 and ADR-012 have Markdown tables (should be fixed separately)

Priority

Medium - Improves code quality and reduces review burden, but not blocking current work.

Labels

enhancement, documentation, tooling, pre-commit

---

Context: Discovered while reviewing Risk Radar ADRs in PR #284. The Markdown tables were created by AI assistance and not caught during creation.