Instruction on check_adr.py script

:::{glossary}
ADR 26001
: [Title](path/to/adr_26001_slug.md)

ADR 26002
: [Another Title](path/to/adr_26002_slug.md)
:::

# Required frontmatter fields
required_fields: [id, title, date, status, tags]

# Date format (regex)
date_format: "^\\d{4}-\\d{2}-\\d{2}$"

# Valid tags
tags: [architecture, documentation, hardware, model, workflow, ...]

# Required document sections
required_sections: [Context, Decision, Consequences, Alternatives, References, Participants]

# Valid statuses
statuses: [proposed, accepted, rejected, superseded, deprecated]

# Status to section mapping for partitioned index
sections:
  Active Architecture: [accepted]
  Evolutionary Proposals: [proposed]
  Historical Context: [rejected, superseded, deprecated]

# Typo corrections (typo → correct)
status_corrections:
  proposed: [prposed, draft, pending, wip]
  accepted: [acepted, approved, active]
  ...

- id: check-adr-index
  name: Check ADR Index
  entry: uv run --active tools/scripts/check_adr.py
  language: python
  files: ^architecture/(adr/adr_.*\.md|adr_index\.md)$
  pass_filenames: false
  stages: [pre-commit, manual]

adr-index:
  runs-on: ubuntu-latest
  steps:
    - name: Run ADR Index Check
      run: uv run tools/scripts/check_adr.py --verbose

uv run pytest tools/tests/test_check_adr.py -v

# 1. Copy template
cp architecture/adr/adr_template.md architecture/adr/adr_26018_my_new_decision.md

# 2. Edit the file (update frontmatter and content)
# - Set id: 26018
# - Set title: "My New Decision"
# - Set date: 2026-02-01
# - Set status: proposed
# - Set tags: [architecture]
# - Fill in Context, Decision, Consequences, etc.

# 3. Validate (will show "missing_in_index" error)
uv run tools/scripts/check_adr.py --verbose

# 4. Auto-fix to add to index
uv run tools/scripts/check_adr.py --fix

# 5. Stage changes
git add architecture/adr/adr_26018_my_new_decision.md architecture/adr_index.md

# 1. Check which ADRs need migration (look for "missing_field" errors)
uv run tools/scripts/check_adr.py --verbose

# Example output:
# - ADR 26001 missing required field: 'id'
# - ADR 26001 missing required field: 'date'
# ...

# 2. Run migration to add frontmatter automatically
uv run tools/scripts/check_adr.py --migrate

# Example output:
# Migrated: adr_26001_use_of_python.md
# Migrated: adr_26002_adoption_of_pre_commit.md
# Migrated 2 ADR file(s).

# 3. Regenerate the partitioned index
uv run tools/scripts/check_adr.py --fix

# 4. Review and commit
git diff architecture/adr/
git add architecture/adr/ architecture/adr_index.md

# 1. Validation shows invalid status
uv run tools/scripts/check_adr.py --verbose

# Output:
# - ADR 26005 has invalid status: 'prposed' (valid: accepted, deprecated, proposed, rejected, superseded)

# 2. Run fix mode (will prompt for correction)
uv run tools/scripts/check_adr.py --fix

# Interactive prompt:
# ADR 26005 has invalid status: 'prposed'
# Valid statuses: accepted, deprecated, proposed, rejected, superseded
# Suggested correction: 'prposed' -> 'proposed'
# Apply suggested fix 'proposed'? [Y/n/custom]:
# (Press Enter to accept)

# 3. Stage the fixed file
git add architecture/adr/adr_26005_*.md

# 1. Validation shows title mismatch
uv run tools/scripts/check_adr.py --verbose

# Output:
# - ADR 26003 has mismatched titles: header='Adoption of Gitlint', frontmatter='Old Title'

# 2. Run fix mode (will prompt for confirmation)
uv run tools/scripts/check_adr.py --fix

# Interactive prompt:
# ADR 26003 title mismatch:
#   Header title:      'Adoption of Gitlint'
#   Frontmatter title: 'Old Title'
# The header title is authoritative. Update frontmatter to match?
# Apply fix? [y/N]: y

# 3. Stage the fixed file
git add architecture/adr/adr_26003_*.md

# 1. Rename the file
mv architecture/adr/adr_26001_old_name.md architecture/adr/adr_26001_new_name.md

# 2. Validation detects wrong link
uv run tools/scripts/check_adr.py --verbose

# Output:
# - ADR 26001 has wrong link: /architecture/adr/adr_26001_old_name.md (expected /architecture/adr/adr_26001_new_name.md)

# 3. Auto-fix updates the index
uv run tools/scripts/check_adr.py --fix

# 4. Stage changes
git add architecture/adr/adr_26001_new_name.md architecture/adr_index.md
git rm architecture/adr/adr_26001_old_name.md

# 1. Edit the ADR file and change status in frontmatter
# From: status: proposed
# To:   status: accepted

# 2. Validation detects wrong section placement
uv run tools/scripts/check_adr.py --verbose

# Output:
# - ADR 26010 is in section 'Evolutionary Proposals' but should be in 'Active Architecture'

# 3. Auto-fix regenerates the partitioned index
uv run tools/scripts/check_adr.py --fix

# 4. Stage changes
git add architecture/adr/adr_26010_*.md architecture/adr_index.md

# 1. Validation shows invalid tag
uv run tools/scripts/check_adr.py --verbose

# Output:
# - ADR 26015 has invalid tag: 'performance' (valid: architecture, ci, documentation, ...)

# 2. Option A: Use an existing tag instead
# Edit the ADR and change to a valid tag

# 3. Option B: Add the new tag to config (if it should be allowed)
# Edit architecture/adr/adr_config.yaml:
# tags:
#   - architecture
#   - ...
#   - performance  # Add new tag

# 4. Re-run validation
uv run tools/scripts/check_adr.py --verbose

# The pre-commit hook runs automatically when you commit ADR files
git add architecture/adr/adr_26018_new_feature.md
git commit -m "feat: Add ADR 26018"

# If validation fails, you'll see:
# Check ADR Index...................................................Failed
# - ADR 26018 (adr_26018_new_feature.md) not in index
# Run with --fix to update the index automatically.

# Fix and retry:
uv run tools/scripts/check_adr.py --fix
git add architecture/adr_index.md
git commit -m "feat: Add ADR 26018"

# 1. Create/edit ADR
cp architecture/adr/adr_template.md architecture/adr/adr_NNNNN_slug.md
# Edit the file...

# 2. Validate
uv run tools/scripts/check_adr.py --verbose

# 3. Fix any issues
uv run tools/scripts/check_adr.py --fix

# 4. Commit
git add architecture/adr/ architecture/adr_index.md
git commit -m "feat: Add ADR NNNNN"