ADR-019: Pre-Commit Hook Validates Pyramid Layers Only
Date: 2025-11-10 Status: ✅ Accepted Deciders: CTO (Claude Code AI) Tags: #documentation #quality #automation
Context
Pre-commit hook validates documentation quality. Should it validate: 1. All docs (including 151 legacy files) 2. Pyramid layers only (new system)
Legacy docs have 145 broken links being migrated incrementally.
Decision
Pre-commit hook validates Pyramid layers only, not legacy documentation.
Scope:
- ✅ Validate: 0-SIGNAL/, 1-CONTEXT/, 2-WORK/, HTML/ (generated), 4-ARCHIVE/
- ❌ Skip: Legacy docs (being migrated incrementally)
Rationale
Why Pyramid Only?
- Legacy has 145 broken links (expected during migration)
- Don't want false positives blocking commits
- New system should be clean from day 1
- Legacy migration happens incrementally over weeks
Why NOT All Docs?
- 145 broken link errors on every commit
- Blocks legitimate work on new system
- Migration would need to be 100% before committing anything
Consequences
Positive
- ✅ Clean commits for new Pyramid system
- ✅ No false positives from legacy docs
- ✅ Can migrate legacy incrementally
Negative
- ❌ Legacy docs can still have broken links
- ❌ Two validation standards (Pyramid vs legacy)
Mitigation
- Migration plan tracks legacy quality
- Separate validation script for legacy audit
- Health dashboard shows migration progress
Implementation
Current State: - ✅ Hook validates Pyramid layers - ✅ 0 broken links in Pyramid - ⏳ Legacy migration 27% complete (42/155 files)
Future: When legacy migration 100% complete, validate all docs.