CR-2026-03-25: Claude Code AsciiDoc Attribute Validation Hook

Change Summary

Field Value

Change ID

CR-2026-03-25-claude-code-hooks-001

Requested By

Self (PRJ-claude-code-features)

Target Date

2026-03-25

Systems Affected

~/.claude/hooks.json, ~/.claude/hooks/ scripts

Risk Level

Medium (workflow impact on failure)

Rollback Time

< 1 minute (restore backup)

Change Window

Any (personal development environment)

Category

Normal (follows full process)

Business Justification

Problem Statement

AsciiDoc files in the domus-* documentation ecosystem use Antora attributes ({attribute-name}) defined in antora.yml. When Claude Code edits .adoc files, undefined attributes cause:

  1. Build warnings - Antora logs "skipping reference to missing attribute"

  2. Broken rendering - Literal {attribute-name} appears instead of value

  3. Delayed detection - Errors found at build time, not edit time

  4. Rework cycles - Must stop, identify, fix, rebuild, verify

Root Cause History

Incident Impact Resolution Time

RCA-2026-02-26-001

6 missing attributes across 3 files

45 minutes

RCA-2026-03-19-001

Relative xrefs in nested directories

30 minutes

Ad-hoc occurrences

~2 per week average

15-30 minutes each

Benefits (Quantified)

Benefit Measurement Value

Error prevention

Catch undefined attrs at edit time

~2 incidents/week × 30 min = 1 hour/week saved

Reduced context switches

No need to stop work, debug, rebuild

Improved focus and flow state

Documentation quality

Guaranteed attribute resolution

Zero broken renders from attrs

Learning reinforcement

Immediate feedback on patterns

Faster antora.yml familiarity

ROI Estimate: 1 hour/week × 52 weeks = 52 hours/year recovered

Technical Specification

Hook Architecture

Claude Code hooks execute shell commands at defined lifecycle events. This change adds a PostToolUse hook for the Edit tool targeting .adoc files.

Environment Variables

Variable Description

$ARGUMENTS

JSON string containing tool arguments (includes file_path)

stdin

Full tool_input JSON (available but not used by this hook)

$TOOL_NAME

Tool that triggered the hook (e.g., "Edit")

$TOOL_RESULT

Result of tool execution (PostToolUse only)

Exit Code Semantics

Code Meaning Behavior

0

Success (may include warnings)

Tool execution proceeds/completes

1

Script error

Logged, tool continues

2

Blocking error (with JSON)

Tool execution blocked, user sees message

This hook uses exit 0 for all cases (including warnings) to avoid blocking edits. Warnings are informational, not blocking.

Official Documentation

Anthropic Claude Code Hooks

Resource URL

Hooks User Guide

docs.anthropic.com/en/docs/claude-code/hooks

hooks.json Schema

github.com/anthropics/claude-code/…​/hooks.md

Best Practices

github.com/anthropics/claude-code/…​/best-practices.md

Example Hooks

github.com/anthropics/claude-code/…​/examples/hooks

hooks.json Schema Reference

{
  "hooks": {
    "<HookEvent>": [
      {
        "matcher": "<tool-name-regex>",
        "hooks": [
          {
            "type": "command",
            "command": "<shell-command>",
            "timeout": <seconds>
          }
        ]
      }
    ]
  }
}

Valid <HookEvent> values:

  • PreToolUse - Before tool execution

  • PostToolUse - After tool execution

  • SessionStart - When Claude Code session begins

  • UserPromptSubmit - When user submits prompt