docsync-setup — track and fix doc drift

Frontmatter schema — every tracked .md carries its own state, no separate registry:

---
doc_type: "llm"                # optional; absent or unrecognized => user. values: llm | user | skip
last_updated: "2026-07-19"     # sole staleness input (YYYY-MM-DD, LOCAL time)
sync_procedure: "what to check / where to look when syncing"   # optional, prose
---

Staleness is DATE ONLY: today - last_updated > threshold_days. No hashing, no depends_on graph.

• Values are quoted. The hooks’ frontmatter parser strips surrounding quotes either way, so unquoted docs already in your repo keep working — but a real YAML consumer types an unquoted 2026-07-19 as a Date, so everything the skill emits is quoted.
• doc_type: "skip" excludes a file entirely. Absent or unrecognized doc_type is normalized to user by a docTypeOf() helper present in all three hooks — the default is enforced in code, not only described here.
• sync_procedure is a model-only hint: no hook parses it. sync mode and the gate’s block message tell Claude to read the doc and follow it.

Enable/disable polarity — the opposite of what you’d guess. The flag lives in config.json under "enabled", and an absent key means ENABLED: every hook’s loadConfig() reads enabled: c.enabled !== false. So "enabled": false is installed-but-inert, not missing — a config with no enabled key at all is live. This is the reverse of brewtools:agent-deadline-setup, whose gate checks cfg.enabled !== true, so an absent key there is INERT. Do not assume the two setups share a polarity.

Before this release, enable/disable required the version/generated_by/last_updated trio to already be present byte-identical, and failed when it was missing. They now ADD the trio when absent, so a pre-standard config.json gets backfilled instead of staying unstamped forever.

The three hooks

The gate’s asked flag is one boolean per session: after that single block, docs that go stale or get touched later in the same session produce no further signal until the next session. That is deliberate — a Stop hook that blocks repeatedly loops. A doc that is only ever read and carries no last_updated still produces a signal: the gate lists it under no last_updated.

Project root resolution — the hooks resolve it themselves, at runtime. Each hook tries CLAUDE_PROJECT_DIR first, then walks upward from the hook’s own cwd for the nearest .git or .claude marker, then falls back to that same cwd — there is no git rev-parse rung inside the hooks. The skill’s own install/upgrade/status Bash snippets add one extra rung, git rev-parse --show-toplevel, between the env var and the walk; the two agree on every layout except a nested .claude, where the hooks — not the skill’s shell snippet — decide where config and state actually land. input.cwd is never treated as the root: it drifts mid-session, so it is used only to resolve a relative tool_input path.

Hooks are self-contained ESM (Node built-ins only), read state from .claude/docsync/ at runtime, and take effect starting the next session. Line 2 of each carries a // brewcode-meta: version=… generated_by=brewdoc:docsync-setup stamp baked at release, so an installed copy can be compared byte-for-byte against the plugin’s. tests/suite-hooks.mjs exercises all three hooks directly — session isolation, exclude globs, the disabled-polarity fix, gate blocking at most once, a missing config file — 26 checks, all passing.

State / config — .claude/docsync/:

• config.json — { "version": "X.Y.Z", "generated_by": "brewdoc:docsync-setup", "last_updated": "2026-08-08", "enabled": true, "threshold_days": 7, "exclude": ["node_modules/**", ...] } — the three provenance keys come first, in that order, ahead of the skill-private ones
• state.json — install writes { "session_id": null, "touched": [], "asked": false }; the hooks own it from then on, replacing null with the live session id and resetting touched/asked on every session change

Scope — all *.md in the project minus exclude globs and any file marked doc_type: "skip". All three hooks apply both filters, the Stop gate included, so marking a doc skip mid-session silences it immediately — even if it was already touched. Only docs actually read or edited in a session are candidates for the end-of-turn nag; untouched docs are never nagged.

uninstall removes only the 3 docsync hook entries from settings.json (foreign entries preserved), deletes the 3 hook files, and asks separately whether to drop .claude/docsync/ — keeping it means a later install reuses the config. purge is uninstall with no survivors: .claude/docsync/ is deleted outright, foreign settings and the .bak backup untouched.