4.0 KiB

Raw Blame History

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.

4.0 KiB Raw Blame History