# Change: Add Clean

## Why

The `check` capability writes a machine report and a human report, but nothing acts on
them. The `SessionStart` banner already tells users their docs may be stale and
advertises `/hygiene check`; the check skill now delivers a report — but the feature
loop is still open: **no `/hygiene clean` or `/hygiene sweep` exists**, so the report
sits in `.dochygiene/` and nothing is ever fixed. `patch_applier.py` and its 263
tests are already built; this change wires the remaining pieces so the plugin
actually remediates doc rot.

## What Changes

- **`patch_applier.py`** (already built — 263 tests pass): a standalone deterministic
  script that applies a report's entries to project files in per-file transactions,
  with a content-hash guard, incompatible-ops detection, and precise git staging.
  Marked DONE in the task list.
- **`skills/hygiene-clean/SKILL.md`**: the orchestration skill — loads the current
  report, partitions entries by safety tier and op type, gates `confirm`-tier entries
  with a batch-confirm prompt (per-entry opt-out), applies deterministic entries via
  `patch_applier.py`, delegates generative entries to a Sonnet subagent (via
  `workflows/distill.md`), stages precisely, and commits once via
  `git-context commit-apply`.
- **`workflows/distill.md`**: the generative Sonnet workflow invoked for
  `distill`/`split`/`generative` entries; isolated from the skill via a LOOP-GUARD
  subagent pointer.
- **`commands/hygiene.md` update**: replaces the "not yet implemented (Phase 4)"
  stubs for `clean` and `sweep` with live routing to the `hygiene-clean` skill.
- **Integration tests** (`tests/test_clean_integration.py`): fixture-repo tests
  covering invariant #5 GAP (dirty→checkpoint+exactly-one cleanup commit;
  clean→one commit; all-skipped→zero commits) and invariant #7 sweep-gating GAP
  (confirm escalates under `sweep`).

## Capabilities

### New Capabilities

- `doc-clean`: the clean pipeline and its guarantees — the `hygiene-clean` skill
  orchestration (load report → gate confirms → git preflight → apply deterministic
  entries → dispatch generative → stage precisely → single commit → stamp
  `last_clean`), the per-file transaction model in `patch_applier.py` (content-hash
  guard, descending-anchor application, incompatible-ops detection, precise staging),
  safety-tier gating (invariant #7), git-safety (invariant #5: WIP checkpoint,
  single commit, tracked-files-only, rollback on hard failure), and the `sweep`
  composition (`/hygiene sweep` = check-then-clean without double-commit). One
  capability because the applier, the skill, the gating, and git safety are a single
  atomic pipeline — splitting them would scatter tightly coupled guarantees across
  capability boundaries.

### Modified Capabilities

None. The `doc-check` capability is **consumed, not modified** — the clean skill
reads the report written by check without changing any check requirement.

## Impact

- **Affected specs:** creates one new capability — `doc-clean`. Consumes the frozen
  `report-schema`, `doc-scanner`, `state-store`, and `doc-check` capabilities without
  modifying them.
- **Affected code:** introduces `skills/hygiene-clean/SKILL.md`,
  `workflows/distill.md`, integration tests, and CONTEXT.md updates for
  `skills/hygiene-clean/` and `scripts/`. Updates `commands/hygiene.md` (stub
  replacement only — no structural change). `patch_applier.py` and its unit tests
  already exist and pass.
- **Out of scope (named owners):**
  - `token_estimate` weighting (`injection_frequency`, `weighted_tokens`, bottom-up
    rollup) — v2 bonus per PRD phase 5.
  - Link rewrite after `move-to-archive` — v1 moves only, next `/hygiene check` flags
    new orphans.
  - Live model-classification regression harness — separate, manually invoked.
- **Dependencies:** depends on `report-schema` (frozen), `doc-scanner`,
  `state-store`, `doc-check` (produces the report this change consumes), and the
  already-built `patch_applier.py`. No upstream capability specs are modified.