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.

Enable/disable refreshes provenance and content-version metadata while preserving threshold and excludes.

Write failure and recovery. Install/upgrade snapshots every destination before mutation and publishes each file through a checked atomic rename. If a destination changes meanwhile, setup stops rather than overwriting it. On failure, rollback restores each committed file’s prior bytes and mode only if it still matches this run’s output; concurrent edits remain intact and recovery gaps are reported. This is per-file publication and recovery, not an all-files atomic transaction.

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. Their line-2 metadata supports installed-copy comparison. Local hook tests cover session isolation, excludes, enabled polarity, gate blocking and missing config. Suite output supplies the current pass/fail totals; this page does not claim a live runtime run.

State / config — .claude/docsync/:

• config.json — version/content-version provenance, enabled state, threshold and exclude globs; upgrade retains configuration values while refreshing metadata.
• state-<session_id>.json — hook-owned touched set and asked flag for each session. A missing session id falls back to state.json. Install/upgrade preserves existing session files.

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 three docsync hook entries and files, preserving foreign entries, then asks whether to remove .claude/docsync/. Keeping that directory retains configuration and session history. purge removes it as well; foreign settings and the settings backup remain.