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