75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
|
# 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.
|