Entity: ADR-009

Brief: Adds opt-in pre-commit hooks so documentation can ship in the same commit as the feature: a pre-commit docs check (warn/strict), a Claude Code commit gate, and a pre-commit capture mode. Capture modes are mutually exclusive and hooks.py install is declarative.

Context

ADR-008 automated capture in a post-commit hook. The docs for a change still land in a later commit (or never), because the queue is only synthesized afterwards. The goal is for a feature commit to carry its documentation.

Hooks cannot write documentation — synthesis needs an LLM. So "docs in the same commit" can only be achieved by making sure synthesis happens before committing, and by checking that it did.

Decision

Three independent, opt-in hooks.py install flags:

  1. --docs-check warn|strict — git pre-commit runs capture.py --check-docs [--strict]. undocumented_changes() lists staged files that pass skip_reason() (code, not secrets/binaries/ignored dirs) when no staged path under ouro/wiki/ other than capture-queue.md exists. warn prints the list; strict exits 1. Bypass once with OURO_SKIP_DOCS_CHECK=1 (or --no-verify). The hook block skips itself when Python or capture.py is missing, and internal errors never fail the commit.
  2. --commit-gate — Claude Code PreToolUse hook (matcher Bash) running hooks.py claude-commit-gate. It applies the same rule to git commit commands the agent runs and exits 2 with a message listing the files, which Claude Code feeds back to the agent. -a/--all commits also include unstaged tracked changes. OURO_SKIP_DOCS_CHECK=1 in the command allows it.
  3. --capture-on pre-commit — git pre-commit runs capture.py --from-index: pointer entries for staged files with Commit: staged, then git add ouro/wiki/capture-queue.md so the entries ship in the same commit.

Supporting decisions:

Alternatives Considered

Trade-offs

Factor Impact
Docs in the same commit Enforced (strict / gate) or nudged (warn); still authored by the agent or developer
Check precision Coarse: a one-line wiki edit satisfies it for any number of files
Commit friction strict blocks human commits; mitigated by OURO_SKIP_DOCS_CHECK=1
Agent coverage Commit gate is Claude Code–only and regex-based (aliases/scripts not gated); the git docs check covers everyone
Pre-commit capture Queue entries versioned with the change; an aborted commit (e.g. a failing later hook) leaves captures staged
git commit <paths> Git restores the real index afterwards, leaving a stale staged queue (MM); the next pre-commit run re-stages the working-tree copy so the stale copy is never committed
Queue churn in history Pre-commit capture commits capture-queue.md changes alongside code

Rationale

The only reliable way to get docs into a feature commit is to make the missing docs visible, or unmissable, at the moment of committing, and to put the agent in charge of writing them before it commits. A deterministic, index-based rule works identically for humans (git hook) and agents (PreToolUse gate), never needs an LLM in git, and composes with either capture mode without deadlocking.