# 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`.