# Doc-review reminder: a generic one-shot hook

- Version: 1.0.0
- Released: 2026-09-27
- Author: ChatGPT (AI-generated), published by eigentime.org
- License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
- Download: `doc-review-reminder-v1.0.0.zip`

## What it is

A documentation-review reminder for Claude Code and Codex. It is a different design from this site's [doc-freshness gate](/en/resources/doc-freshness-hook/):

| | Doc-freshness gate | Doc-review reminder |
|---|---|---|
| Hooks | PreToolUse, intercepts `git commit` / `git push` | UserPromptSubmit records a baseline, Stop reminds |
| Behavior | Denies when code changed but no doc did | Reminds once when this turn changed non-doc paths and the reply has no docs status line |
| Asks for | A touched doc path | One line: `Docs: updated / not needed / pending (reason)` |
| Fits | A personal repo with an explicit doc contract | General use, without regex interception of commit commands |

It asks for a stated assessment, not for an arbitrary Markdown edit. A status line proves the agent reported something, not that the docs are right.

## How it behaves

- At each user turn it snapshots the working tree and HEAD; at Stop it compares and only counts non-doc paths that actually changed during that turn.
- At most one reminder per turn; it stays quiet when `stop_hook_active` is true or it has already reminded, so it cannot loop.
- Claude gets `additionalContext`; Codex gets `decision:"block"` plus `reason`. Both cost one more model turn — neither is a free notification.
- If input, Git state or the resource budget cannot be checked, it lets work continue but returns a `systemMessage` saying the review was skipped, rather than looking like a pass.
- State lives in `<git-dir>/agent-doc-review/` and stores hashes only, never file contents.
- Requires Node.js ≥ 20 and git on PATH; no dependencies, no network, no commits, no doc writes.

## Install

Unzip and follow the bundled `INSTALL-PROMPT.md`, or hand it to an AI agent:

1. Copy `.agent-hooks/` to the target repository root (check for conflicts first).
2. Merge `config/claude.settings.fragment.json` into `.claude/settings.json` and `config/codex.hooks.fragment.json` into `.codex/hooks.json`. Merge; do not replace existing hooks.
3. Run the bundled tests (command in the bundle README).
4. Confirm registration with `/hooks` in each client, and complete Codex's trust review. In a throwaway repository, test one reminder, one no-reminder case and loop protection.

`AGENTS.example.md` is an example of companion personal agent guidance — merge from it, never replace your existing global or repository instructions with it.

## Verification boundary

- **Verified**: on 2026-09-27 this site ran the bundle's 35 tests on Node 24 (Linux/WSL); all passed.
- **Not verified**: registration and end-to-end behavior inside a real Claude Code or Codex client, and native Windows. Do step 4 yourself before relying on it.
- Both hosts' hook events and output fields keep changing; check the current official docs.