feat(platform): implement commit-cadence enforcement and change-history plumbing (ANGA-654)

[anhermon]

Summary

Implements platform-level mechanisms to enforce commit cadence and preserve verifiable change history for auditable workflow evolution.

Addresses: ANGA-654

Changes

1. Commit cadence guardrail (scripts/check-commit-cadence.sh)

   • Prevents uncommitted changes older than 24h (configurable via COMMIT_CADENCE_THRESHOLD_HOURS)
   • Integrated into pre-commit hook workflow
   • Provides actionable guidance when violations detected

2. Enhanced commit-msg hook (.githooks/commit-msg)

   • Validates Conventional Commits format (existing)
   • NEW: Requires "Rationale:" field for feat/fix/refactor and workflow-scope commits
   • Minimum 10-character rationale for meaningful explanation
   • Helpful error messages with examples

3. Commit message template (.gitmessage)

   • Documents required format: <type>(<scope>): <description>
   • Explains rationale requirements by commit type/scope
   • Provides examples of well-formed commits
   • Includes Co-Authored-By trailer pattern

4. Machine-readable change-history script (scripts/generate-change-history.sh)

   • Parses git log into structured JSON output
   • Extracts: hash, author, email, date, type, scope, description, rationale, full body
   • Supports filtering: --since, --limit, --output
   • Extensible to YAML/CSV (JSON implemented)

5. Documentation (scripts/README.md)

   • Usage guide for all scripts and hooks
   • Integration with git workflow
   • Troubleshooting section
   • Examples for each tool

6. Gitignore update (.gitignore)

   • Added .paperclip/ directory exclusion

Verification

• Platform guardrail exists that prevents long-lived uncommitted changes beyond 24h threshold
• Commit message template/check documents required rationale fields and is wired into pre-commit workflow
• Machine-readable change-history output produced (sample: /tmp/sample-change-history.json)

Testing

Tested locally:

• Commit cadence check: ✅ passes when changes are recent
• Change-history generation: ✅ produces valid JSON output
• Commit-msg hook: ✅ validates format and rationale (this commit passed validation)

Files Changed

• .githooks/commit-msg - enhanced rationale validation
• .githooks/pre-commit - integrated cadence check
• .gitignore - added .paperclip/ exclusion
• .gitmessage - new commit template
• scripts/check-commit-cadence.sh - new cadence guardrail
• scripts/generate-change-history.sh - new change-history generator
• scripts/README.md - new documentation

Test plan

• Review implementation against ANGA-654 verification criteria
• Test commit cadence script with various thresholds
• Test commit-msg hook with valid/invalid messages
• Test change-history generation with different filters
• Verify documentation is clear and complete
• Confirm all scripts are executable and work on different platforms

🤖 Generated with Claude Code