Skip to content

feat: add on-demand cleanup sweep mode - #319

Merged
dnth merged 3 commits into
mainfrom
fm/fm-cleanup-sweep-mode
Nov 17, 2026
Merged

dnth merged 3 commits into
mainfrom
fm/fm-cleanup-sweep-mode

Conversation

@dnth

@dnth dnth commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Summary

/cleanup keeps its full report-first review; /cleanup sweep is the on-demand narrow path the captain asked for: one pooled-copy table, one captain word, one clean-tier pass, then measured results.

/cleanup sweep
  config/treehouse-sweep-clean absent -> name the flag, stop
  bin/fm-treehouse-sweep.sh --all      # read-only tiers + tool dry run
  du -sk <path>                        # measured size per copy
  find <path> ! -user "$(id -u)"       # clean rows: foreign-owned = potential obstacle
  table: tier | path | size | suggestion; sum of clean rows = reclaim total
  one captain word                     # existing wholesale clean-tier approval
  df -h/-k before, --apply-clean once, df + --all after (also on refusal/failure)
  report removed copies, space change, leftovers; no retry, no sudo

Files changed:

.agents/skills/cleanup/SKILL.md                    # description trigger + Sweep mode
.agents/skills/agent-skill-trigger-index/SKILL.md  # one-line trigger update
AGENTS.md                                          # one-line section 6 pointer
README.md                                          # one-line command-table entry (pipeline document fix)
  • Safety rules and "Stale working copies for done or merged tasks" are unchanged; the new section cross-references them, so dirty, damaged, claimed, leased, and occupied copies stay report-only, clean slots are never removed per slot, and --force stays forbidden.
  • A refusal or a failed slot is reported without retry or workaround; not-owned paths left in a failed copy are listed as exact sudo rm -rf <path> lines for the captain, and firstmate never runs sudo.
  • The missing config/treehouse-sweep-clean flag is named and the sweep is not attempted.

Pipeline fixes

The pipeline caught two misses in the first draft and fixed both in review fix c078d044:

  • R2: capture df -h/df -k before the pass, not only afterward, so a partly deleted copy that stays listed still shows the observed space change.
  • R3: a foreign-owned path is a potential deletion obstacle, not proof that --apply-clean will fail; before a failure it no longer suggests sudo.

The document step's README command-table line landed in 40cc0ddf.

Why the sweep script is unchanged

bin/fm-treehouse-sweep.sh still classifies only through the ownership proof, and its clean tier is decided by porcelain cleanliness, unpushed commits, and merge reachability (cited: the classification branch in bin/fm-treehouse-sweep.sh). A "contains paths not owned by the current user" flag could not be tested through the script's public interface without root: an unprivileged fixture cannot create a foreign-owned path, and a test-only ownership override in production code is disallowed. The check stays in the skill procedure, where find <path> ! -user "$(id -u)" runs read-only on clean rows only, and the apply pass's stop-on-failure behavior is untouched.

Follow-up recommendation

--apply-clean stops the whole pass at the first treehouse destroy failure (cited: the die "treehouse destroy failed for clean slot $canon" branch), so one root-owned path costs the remaining clean slots in that run (the 2026-11-17 incident: copy 38 failed, nine copies waited for a second pass). A follow-up could continue past a failed slot, report each failure with its exact path, and exit non-zero at the end; this PR leaves that behavior alone.

Evidence

  • Before: the skill had one mode: the full report (finished work, pooled copies, panes and processes, disk) before any removal.
    After: /cleanup sweep prints one pooled-copy table, waits for one word, runs --apply-clean once, and re-measures with before and after filesystem readings.

Dry walkthrough against this machine's live pools (bin/fm-treehouse-sweep.sh --all, du -sk, find ! -user; no apply run, no removal):

tier slot measured size path
skipped 1 19 MiB /home/dnth/.treehouse/firstmate-e1905f/1/firstmate
damaged 28 3.3 GiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/28/infoconnect-search-engine
damaged 38 151 MiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/38/infoconnect-search-engine
skipped 39 2.0 GiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/39/infoconnect-search-engine
damaged 57 299 MiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/57/infoconnect-search-engine
skipped 58 1.4 GiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/58/infoconnect-search-engine
damaged 60 0 MiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/60/infoconnect-search-engine
damaged 61 0 MiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/61/infoconnect-search-engine
clean 73 854 MiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/73/infoconnect-search-engine
clean 74 875 MiB /home/dnth/.treehouse/infoconnect-search-engine-f4e2f3/74/infoconnect-search-engine
skipped 9 204 MiB /home/dnth/.treehouse/kcc-chatbot-8d3b35/9/kcc-chatbot
damaged 40 115 MiB /home/dnth/.treehouse/superfk-aceh-f7e8ed/40/superfk-aceh
damaged 55 1.3 GiB /home/dnth/.treehouse/superfk-aceh-f7e8ed/55/superfk-aceh
dirty 57 1.3 GiB /home/dnth/.treehouse/superfk-aceh-f7e8ed/57/superfk-aceh

Clean-tier reclaim total for that run: 1.7 GiB (1,770,776 KiB) measured by du -sk over the clean rows, and both clean rows passed the not-owned check (find printed nothing). The opt-in flag was present at config/treehouse-sweep-clean. Pool filesystem: /dev/mapper/data-root 929G, 660G used, 222G available. Raw capture: data/fm-cleanup-sweep-mode/artifacts/sweep-all-live.txt and sweep-sizes.tsv.

  • bash tests/fm-cleanup-skill.test.sh - both contract tests pass.
  • bin/fm-doc-audience-check.sh - ok surfaces=104 local_links=544.
  • PR checks: 20 passed, 0 failed. The first run failed one unrelated tests/fm-ext-plugin-dest.test.sh attachment e2e shard; it is unchanged from base and passed locally, and the single authorized rerun passed with no code change.

Merge Danger

Door: Two-way. Reverting restores the previous skill text; nothing else reads the new section.

Blast Radius: Operator-only.

Only agents following the cleanup skill change behavior; this PR adds no script, daemon, trigger, or automatic removal. The one authority rule it leans on (wholesale clean-tier approval) already exists.

Testing

Confirmed that changes affect only natural-language instructions and trigger pointers. No runtime tests or live scenarios were executed, no artifacts were generated, and the previously declined missing-live-validation finding was not repeated.

  • Live validation: ⚠️ no-surface - 0 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Invoke cleanup sweep and receive a pooled-copy report before approval ⏸️ untested no No live-validatable surface changed. The report and approval behavior are natural-language agent instructions; executing the unchanged sweep script cannot validate their interpretation.
Approve one clean-tier pass and receive removal results with before-and-after space measurements ⏸️ untested no The sequencing and measurement requirements exist only in skill instructions. No executable implementation changed that can demonstrate this interaction live.
Encounter missing opt-in or partial deletion without retrying or removing non-clean copies ⏸️ untested no The new handling is instruction-only. The unchanged executable and mocked tests cannot establish agent compliance with the new procedure.
  • Outcome: ⚠️ 1 warning across 2 runs (2m3s)

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 error
  • 🚨 .agents/skills/cleanup/SKILL.md:56 - The intent requires a clean-tier reclaim figure "taken from the tool's own dry-run report," but this line instead defines it as "the sum of the measured clean rows"; line 58 repeats that substitution. This also conflicts with the existing tool-measured-reclaim rule at line 78. Restore the required measurement source, or obtain explicit approval to change that requirement.
  • ⚠️ .agents/skills/cleanup/SKILL.md:61 - Capture filesystem usage before applying the sweep as well as afterward. Currently the only df measurement occurs after deletion, and classification reports no sizes. In the stated partial-deletion scenario, the same slot remains listed after losing 23 GB, so comparing removed rows cannot establish space freed. Preserve a before measurement and compare it with the required after measurement, including on failure.
  • ⚠️ .agents/skills/cleanup/SKILL.md:57 - A foreign-owned path does not establish that deletion will fail: a root-owned regular file inside a user-owned writable directory can be unlinked successfully. This instruction would incorrectly report a guaranteed failure and recommend an unnecessary sudo operation. Describe the result as foreign ownership and a potential deletion obstacle, rather than proof that --apply-clean will stop.

🔧 Fix applied.
1 error still open:

  • 🚨 .agents/skills/cleanup/SKILL.md:56 - The intent requires a clean-tier reclaim figure "taken from the tool's own dry-run report," but this line instead defines it as "the sum of the measured clean rows"; line 58 repeats that substitution. This also conflicts with the existing tool-measured-reclaim rule at line 78. Restore the required measurement source, or obtain explicit approval to change that requirement.
⚠️ **Test** - 1 warning
  • ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 3 scenarios were driven live against the product); Invoke cleanup sweep and receive only the pooled-copy report before approval.: This change contains natural-language skill instructions and trigger pointers only. There is no new executable interface; executing the unchanged sweep script cannot demonstrate agent interpretation of the procedure.; Approve the clean tier once and receive removal results with before-and-after filesystem measurements.: The approval interaction and reporting behavior exist only as agent instructions. No live-validatable runtime implementation changed.; Encounter missing opt-in or deletion failure without retrying or removing non-clean copies.: These changes instruct agent behavior rather than modify executable guards. Existing tests use a fake treehouse and cannot establish live compliance with the new skill procedure.
  • Live validation: ⚠️ no-surface - 0 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Invoke cleanup sweep and receive only the pooled-copy report before approval. ⏸️ untested no This change contains natural-language skill instructions and trigger pointers only. There is no new executable interface; executing the unchanged sweep script cannot demonstrate agent interpretation o…
Approve the clean tier once and receive removal results with before-and-after filesystem measurements. ⏸️ untested no The approval interaction and reporting behavior exist only as agent instructions. No live-validatable runtime implementation changed.
Encounter missing opt-in or deletion failure without retrying or removing non-clean copies. ⏸️ untested no These changes instruct agent behavior rather than modify executable guards. Existing tests use a fake treehouse and cannot establish live compliance with the new skill procedure.
  • git diff --stat 9c930f8418a1e9480dc6e0383c5bac8cb80a2f3e c078d044b6d2ca923db5057439ce1da97f7e7160
  • Inspected the complete change across cleanup skill, trigger index, and AGENTS.md.
  • Read bin/fm-treehouse-sweep.sh and relevant existing test fixtures in tests/fm-treehouse-sweep.test.sh.

🔧 No changes applied.
1 warning still open:

  • ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 3 scenarios were driven live against the product); Invoke cleanup sweep and receive a pooled-copy report before approval: No live-validatable surface changed. The report and approval behavior are natural-language agent instructions; executing the unchanged sweep script cannot validate their interpretation.; Approve one clean-tier pass and receive removal results with before-and-after space measurements: The sequencing and measurement requirements exist only in skill instructions. No executable implementation changed that can demonstrate this interaction live.; Encounter missing opt-in or partial deletion without retrying or removing non-clean copies: The new handling is instruction-only. The unchanged executable and mocked tests cannot establish agent compliance with the new procedure.
  • Live validation: ⚠️ no-surface - 0 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Invoke cleanup sweep and receive a pooled-copy report before approval ⏸️ untested no No live-validatable surface changed. The report and approval behavior are natural-language agent instructions; executing the unchanged sweep script cannot validate their interpretation.
Approve one clean-tier pass and receive removal results with before-and-after space measurements ⏸️ untested no The sequencing and measurement requirements exist only in skill instructions. No executable implementation changed that can demonstrate this interaction live.
Encounter missing opt-in or partial deletion without retrying or removing non-clean copies ⏸️ untested no The new handling is instruction-only. The unchanged executable and mocked tests cannot establish agent compliance with the new procedure.
  • git diff --stat 9c930f8418a1e9480dc6e0383c5bac8cb80a2f3e c078d044b6d2ca923db5057439ce1da97f7e7160
  • Inspected the complete three-file change and existing sweep script interface.
  • Inspected tests/fm-treehouse-sweep.test.sh to assess whether it could demonstrate the changed behavior.
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

dnth added 3 commits November 17, 2026 12:56
- Add `/cleanup sweep` to the cleanup skill: report only pooled copies with measured sizes, wait for one word, run --apply-clean once, re-measure.
- List not-owned paths inside clean slots as sudo rm -rf lines for the captain; firstmate never runs sudo.
- Extend the skill description, trigger index, and the one-line AGENTS.md pointer.
@dnth
dnth merged commit e91d2db into main Nov 17, 2026
39 of 40 checks passed
@dnth
dnth deleted the fm/fm-cleanup-sweep-mode branch November 17, 2026 05:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant