2026-07-13 13:18:23 +00:00
|
|
|
|
# os-doc-hygiene — component detail
|
|
|
|
|
|
|
|
|
|
|
|
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
|
|
|
|
|
|
|
|
|
|
|
**Global os-doc-hygiene plugin** — `cc-os/plugins/os-doc-hygiene/` (git-tracked,
|
|
|
|
|
|
2026-07-03); symlinked into `~/.claude/plugins/os-doc-hygiene`.
|
|
|
|
|
|
|
|
|
|
|
|
- Hooks: `hooks/hooks.json` → SessionStart hook (matcher: startup|resume) runs
|
|
|
|
|
|
`scripts/reminder.py` via `${CLAUDE_PLUGIN_ROOT}` (5s timeout), emitting a deterministic
|
|
|
|
|
|
zero-token reminder banner (once/day snooze).
|
|
|
|
|
|
- Behavior: monitors stale and bloated project documentation; per-project state under
|
|
|
|
|
|
`.cc-os/dochygiene/` (gitignored; moved from `.dochygiene/` 2026-07-12 per ADR-0027, with
|
|
|
|
|
|
canonical-then-legacy fallback reads and auto-migration + legacy dir removal on first
|
|
|
|
|
|
write; scanner self-excludes `.cc-os/`).
|
|
|
|
|
|
- Skills (verb-first, no `commands/` dispatcher — invoked directly as
|
|
|
|
|
|
`/os-doc-hygiene:<skill>`, per [[cc-os-plugin-skill-naming-convention]]): `check`
|
|
|
|
|
|
(AI-assisted classification of staleness signals, emits machine+human reports), `clean`
|
|
|
|
|
|
(AI-assisted or deterministic patch application with git-safe scoped cleanup), `status`
|
|
|
|
|
|
(read-only lifecycle-timestamp read), `sweep` (check then clean in sequence).
|
|
|
|
|
|
Reversion-protected via invariants.md + golden-example test fixtures.
|
|
|
|
|
|
- Scanner signals: broken refs, version skew, churn, archive ratio, frontmatter markers,
|
|
|
|
|
|
and — added 2026-07-13 (issue #25 part 1) — a deterministic `file_length` signal
|
|
|
|
|
|
(defaults 400 lines / 4000 estimated tokens, `--max-lines` / `--max-tokens`; token
|
|
|
|
|
|
estimate via `scripts/token_estimator.py`). Objective facts only; classification lives
|
|
|
|
|
|
downstream. Suite 286 passed as of 2026-07-13 (279 at the ADR-0027 move).
|
|
|
|
|
|
- Migration: migrated from standalone repo (`~/dev/cc-plugins/doc-hygiene/`, 2026-07-03) and
|
|
|
|
|
|
integrated into cc-os; no content conflicts. Renamed `doc-hygiene` → `os-doc-hygiene` per
|
|
|
|
|
|
the cc-os naming convention; skills renamed `hygiene-check`/`hygiene-clean` →
|
|
|
|
|
|
`check`/`clean`; the `commands/hygiene.md` dispatcher was removed in favor of two new
|
|
|
|
|
|
skills (`status`, `sweep`), aligning with the no-`commands/`-directory pattern
|
|
|
|
|
|
(2026-07-03).
|
2026-07-15 11:41:59 +00:00
|
|
|
|
- **Lifecycle-aware hygiene (2026-07-15, ADR-0038–0041)** — adds a rulebook layer on top of
|
|
|
|
|
|
the existing stale/bloat scanner: a global `rulebook.json` plus an optional per-project
|
|
|
|
|
|
`.dochygiene-rules.json` declare lifetime rules for known-temporary artifacts (ADR-0038).
|
|
|
|
|
|
Rules classify matched paths into the lifetime taxonomy and drive a tier matrix from
|
|
|
|
|
|
scanner-proven+tracked+clean (`auto`) down to classifier-judged (`confirm`) (ADR-0039); an
|
|
|
|
|
|
IGNORE sentinel prunes matched paths with zero emission and does not propagate ignore
|
|
|
|
|
|
status to children (ADR-0040). Classifier-judged matches that recur are surfaced
|
|
|
|
|
|
deterministically as `promotion_candidates` from `conventions.json`, not model-authored
|
|
|
|
|
|
(ADR-0041). New `/os-doc-hygiene:calibrate` skill runs the cluster/nominate/judge/
|
|
|
|
|
|
human-report protocol to tune rules against a real project. Calibration pass #1 (cc-os)
|
|
|
|
|
|
ran 2026-07-14/15 and passed both the protected-set hard gate and the recall floor across
|
|
|
|
|
|
all 4 mandatory rows; rule persistence to `.dochygiene-rules.json` is pending human
|
|
|
|
|
|
approval. Results: `plugins/os-doc-hygiene/openspec/changes/lifecycle-aware-doc-hygiene/calibration-pass-1-results.md`.
|
|
|
|
|
|
Design: `plugins/os-doc-hygiene/lifecycle-spec.md`. Suite: 407 passed.
|
2026-07-15 18:59:58 +00:00
|
|
|
|
- **Calibrate assessment inventory implemented (2026-07-15, map #49 / ADR-0038-0039
|
|
|
|
|
|
amendments)** — the locked nominations-memory design is now code: `RulesFileWriter`
|
|
|
|
|
|
(single canonical serialization path for `.dochygiene-rules.json`; tier-grouped,
|
|
|
|
|
|
glob-sorted, idempotent, unknown fields warn-and-round-trip) and `NominationIntakeFilter`
|
|
|
|
|
|
(deterministic Step 3.5 — exact glob+lifetime repeats dropped, variants annotated via
|
|
|
|
|
|
shortlist match-set intersection, open consults always forwarded) in
|
|
|
|
|
|
`calibrate_helpers.py`; calibrate SKILL.md Steps 3.5/5/6 wired (Open-consults report
|
|
|
|
|
|
section with the three exits; keep verdicts, human declines, and consults all persist
|
|
|
|
|
|
through the writer); `patch_applier.py` extract-then-delete appends the `extracted.md`
|
|
|
|
|
|
vault pointer (keyed off `extraction_target: "cross-repo"` + a skill-supplied
|
|
|
|
|
|
`extraction_pointer`, fail-closed: no pointer → no delete); clean SKILL.md Step 6.5
|
|
|
|
|
|
supplies the pointer metadata. OpenSpec change:
|
|
|
|
|
|
`plugins/os-doc-hygiene/openspec/changes/calibrate-assessment-inventory/`. Suite: 434
|
|
|
|
|
|
passed (26 new unit tests across writer/intake-filter/applier seams).
|
