82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# 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`.
|