I built this project to solve a simple team problem: code changes were landing faster than documentation updates, so README files became stale over time. This problem has been exacerbated by the rise of AI-assisted programming. With AI-assisted programming, keeping documentation fresh becomes even more important for context engineering and maintenance.

The hook inspects staged files with git diff --cached --name-only, filters out README-only commits, and then finds the nearest README for each changed code file by walking up parent directories. A commit passes only when all required README files are also staged.

I focused heavily on developer experience. When the hook fails, it prints exactly which README files are missing, shows any README files that were staged but not relevant, and suggests quick ways to make a meaningful docs update.

A key design decision was requiring the nearest README per changed path, not just any README in the repository. That keeps documentation accountability local to the part of the codebase that changed.

This project is an exercise in balancing strict workflow enforcement with practical flexibility: the tool enforces documentation hygiene without requiring any configuration or adding a large dependency surface.