4.1 KiB

Raw Blame History

Proposal: lifecycle-aware-doc-hygiene

Why

os-doc-hygiene monitors stale/bloated docs but cannot manage document lifecycle: disposable artifacts (autoresearch runs, handoff files, served plans) accumulate as clutter that distracts AI navigation and search. The lifecycle-aware design is locked (wayfinder map #31, lifecycle-spec.md, ADRs 0038–0041); this change implements it.

What Changes

New scripts/rulebook.py loader: global rulebook.json + committed repo-root .dochygiene-rules.json override, add-only merge with source-then-specificity precedence, glob.translate dialect, skip-and-warn validation (unconfirmed rules never act), hard-fail on unparseable JSON/unknown schema_version.
Scanner gains a lifecycle signal class; directory-rule matches prune the walk (which implements the explicit IGNORE surface: graphify-out/**, .dochygiene/** — never inferred from .gitignore).
Report schema + clean applier gain delete and extract-then-delete op types with the ADR-0039 autonomy tier matrix (tracked+clean = auto; dirty/untracked = confirm; classifier-judged served_when = always confirm), verified at runtime via git, never trusted from the rule.
Temporary tier: retain-recent-N (default 3) + max_age_days (default 3), age from git commit time falling back to mtime; retention unit = the rule's match entry (file or run directory).
delete-once-served: deterministic served_when_path (scanner-proven, may auto-delete) vs free-text served_when (classifier-judged, forced confirm).
Determinism promotion (ADR-0041): global-only conventions.json catalog (v1: archive-bucket, status-frontmatter); :check reports gain a promotion-candidates section.
New :calibrate skill (the ONLY new skill): cluster-and-sample unmatched files → haiku glob nomination → strong-model batched judgment (confirm/reject/amend/consult) → human rule report (glob verbatim, matches, near-miss boundary, tier, plain-language why) → persistence (project rules on judge confirm; global writes human-gated) → retest loop (<2 new rules or <10% shrink, cap 3 rounds).
Extraction reuses existing knowledge routing (ADR route: repo-durable → docs/ADR/CLAUDE.md; cross-repo → vault). No propagate_ignore (ADR-0040).
Calibration pass #1 against cc-os per spec §9 (protected-set hard gate, 8-of-10 recall floor with 4 mandatory rows, seed hold-out — pass #1 only).

Capabilities

New Capabilities

lifecycle-rulebook: rulebook file format, locations, merge/precedence, glob dialect, validation, and scanner consumption (walk pruning + lifecycle signals + IGNORE surface).
lifecycle-deletion: lifetime taxonomy semantics — temporary tier (retain-recent + age), delete-once-served (served_when_path vs served_when), autonomy tier matrix, true-git-deletion in a dedicated hygiene commit, extract-then-delete routing.
determinism-promotion: conventions.json catalog and promotion-candidate nudging split across :check (names) and :calibrate (drafts).
calibrate: the learn-new-rules protocol, rule-quality tests (class-not-path, prefer-narrower), and calibration-pass validation criteria.

Modified Capabilities

doc-check: scanner walks are pruned by directory rules; lifecycle signals enter classification; reports include promotion candidates.
doc-clean: applies delete/extract-then-delete ops under the tier matrix with runtime git tracked/dirty verification.
report-schema: new op types delete and extract-then-delete, lifecycle signal fields, promotion-candidates section.

Impact

plugins/os-doc-hygiene/scripts/: new rulebook.py; changes to scanner.py, report_builder.py, validate_report.py, patch_applier.py.
New data files: rulebook.json, conventions.json (plugin root).
New skill dir skills/calibrate/SKILL.md (no name: frontmatter; naming per convention doc). Updates to check/clean SKILL.md.
Tests: TDD (red-green) on every deterministic piece; existing suite (286) must stay green.
Per-project surface: optional committed .dochygiene-rules.json.
After source edits: bin/refresh-plugins.

4.1 KiB Raw Blame History Unescape Escape