jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/docs/implementation-status/os-doc-hygiene.md

4.5 KiB
Raw Blame History

os-doc-hygiene — component detail

Leaf file of ../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).
  • 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.
  • 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).