# doc-hygiene

Claude Code plugin that monitors and manages **stale** and **bloated** project
documentation. Installed globally, operates per-project. Reminds (deterministic,
zero-token) on `SessionStart`; checks and cleans on demand via skills.

> `PRD.md` is the historical source-of-truth design doc (see its top-of-file
> migration note for current location). This file is a current-state index,
> not a build map — the plugin is fully built (5 skills, tests passing).

> Vault user guide (nuance/mental-model, not a how-to):
> `~/Documents/SecondBrain/user-guide/os-doc-hygiene-user-guide.md`.

## Core distinction (do not conflate)

- **Stale** = the doc is *wrong* (contradicted, orphaned, superseded,
  provisional, completed-in-place, duplicated). Remedy: fix or remove.
- **Bloat** = the doc is *true but mostly irrelevant* (distill, split, freeze).
  Remedy: change its altitude, almost never delete history.

Severity scales with **injection frequency** — a stale line in `CLAUDE.md` (auto
-injected every session) is worse than the same line in a doc nobody opens.

## Component map

- `skills/` — five skills: `check`, `clean`, `status`, `sweep`, `calibrate`
  (each `SKILL.md` + `workflows/`); see `skills/CONTEXT.md` for the index.
- `scripts/` — deterministic Python core (scanner, state store, reminder,
  report builder, validator, patch applier, token estimator, rulebook,
  calibrate helpers); see `scripts/CONTEXT.md`.
- `hooks/hooks.json` — `SessionStart` → `scripts/reminder.py` (banner only,
  no analysis, no mutation beyond `last_reminded`).
- `tests/` — pytest suite covering every deterministic seam; see
  `tests/CONTEXT.md`.
- `invariants.md` — the reversion-protection contract (numbered behavioral
  invariants); read before changing scanner, state, or safety-tier logic.
- `examples/golden/` — golden classifier fixtures (Layer 2 of reversion
  protection, paired with `invariants.md`).
- `lifecycle-spec.md` — the rulebook layer (global `rulebook.json` +
  per-project `.dochygiene-rules.json`) feeding tier derivation and the
  `calibrate` skill; decisions are ADR-0038–0041.
- `openspec/` — this plugin's own OpenSpec changes/specs tree (archived
  changes correspond to shipped features).

## Conventions

- **Language**: Python, OOP — small single-responsibility classes, dependency
  injection, immutable transforms where possible. See
  `../cc-architect/references/tool-patterns/deterministic-scripting.md`.
- **Model routing**: scripts = no model; classification = Sonnet (hard cases →
  Opus); generative distillation = Sonnet (NOT Haiku).
- **Reversion protection**: `invariants.md` + `examples/golden/` + human gate
  for changes to either. See
  `../cc-architect/references/tool-patterns/reversion-protection.md`.
- Read a directory's `CONTEXT.md` before its source files (progressive
  disclosure).

Changing any invariant requires updating `invariants.md` and the golden
examples, with explicit human approval — do not restate the invariants here.