project-archive-cleanup
Archive-clean finished, long-idle project directories — retain planning documents and result artifacts, strip execution traces (one-off scripts, import intermediates, scrape snapshots, console logs, superseded versions, byte-identical duplicates). Use when asked to clean up project leftovers, reduce process noise, or archive completed work. Always read-only scan first, then a two-phase backup-and-delete with batching for the safe-delete threshold.
project-archive-cleanup
When to use
- A project is described as finished or long-idle and the ask is to reduce process residue — keep the planning and result layer, drop the execution layer.
- Periodic workspace hygiene alongside a disk health check.
- After iterative work left several near-identical versions of one deliverable.
Do not use for: active projects (last activity < ~14 days), the runtime dir itself (~/.workbuddy, a disk-health job), or any unit holding private or company-restricted data without explicit sign-off.
Steps
-
Scope the units. Enumerate top-level dirs plus one level under the main project root. Skip
.git,.venv,node_modules,__pycache__,site-packages. Record size / file count / last-activity / process-file ratio per unit.- Reusable scanner: an
outputs/scan_projects.py-style walk that reportssize / files / last activity / process-file countper unit.
- Reusable scanner: an
-
Classify each unit before touching anything:
- Active (last activity < 14d) → out of scope.
- Restricted (company or brand campaign material, anything with holdings or PII) → list as "needs sign-off", do not clean.
- Finished + idle + unrestricted → in scope.
-
Apply the keep/strip rule:
keep strip planning PRD, strategy, checklists, changelog, history index — result latest deliverable, report, source, cloud functions, config, result data byte-identical duplicate copies process — one-off scripts, import intermediates, scrape snapshots, console logs, superseded versions -
Prove "duplicate" with sha256, never by name or size. Size equality is not identity. Recurring shapes: two identical page snapshots from the same browser run; report copies identical to files already in the result dir; a
before-*.docxidentical to the final stage output. -
Check references before deleting a script. Grep the project for the base name, then judge the source of the hit:
- hit only in workspace memory logs or a changelog → process trace, safe to strip.
- hit in a result doc (e.g. a test report) or it is an operational script → keep, otherwise the result file loses its referent.
-
Check installation before deleting any skill or dependency copy, and require explicit user confirmation for the deletion. Compare against
{p.name for p in (~/.workbuddy/skills).iterdir()}— if the local copy is not installed there, it is the only copy and long idle time says nothing about disposability. Include these items in the dry-run report and obtain approval before any--apply. -
Two-phase execution. Dry-run script prints every item with size + reason; only
--applywrites.- Respect the safe-delete limit — do not work around it. Count every file a recursive delete expands, submit the complete deletion manifest through the approved deletion mechanism in one turn, and stop for explicit user authorization when the hook's threshold (50 expanded files, scope=turn) is reached. Do not split batches across separate processes or switch to a lower-level API to stay under the limit — already-deleted items do not roll back, so a run that hits the limit is reported and resumed only after approval.
- Directory deletes go through the same approved mechanism; verify removal with
[System.IO.Directory]::Exists($p)and reconcile against the manifest.
-
Back up before delete to
<workspace>/outputs/_archive_<date>/, then verify by comparing file counts src vs bak for every entry. Do not trust the script's success echo. -
Clean up directories your own deletes emptied; leave pre-existing empty dirs alone (they are often tool-expected paths such as template output dirs or sync audit scratch dirs).
-
Write the outcome into the health/archive report: what was stripped, what was kept and why, the backup location, and a "needs your call" table for restricted or private items.
Pitfalls
- "Long idle" is not "dead". Check whether a copy is the only surviving instance before judging it disposable.
- Same size ≠ same file. Always hash. Files that look like a pair by name can differ by tens of KB.
- Version series are the trap. Keep the newest + the history index; superseded chains (earlier
vNwhen a later version exists elsewhere) are the noise, but recent mid-series versions (last few days) belong in "archive, don't delete". - Volume is a poor success metric. A cleanup of many items may reclaim very little disk — the value is structural, say so instead of selling a number.
- Do not blanket-delete 0-byte files. Virtualenv trees are full of legitimate empty
__init__.py/py.typed. - Windows reserved names (
nul,con) break Pythonexists()(always True) andos.remove; use .NETFile.Deletewith the\\?\prefix and verify viaos.listdir.
Verification
- Per-item
exists()recheck after deletion; for reserved names use directory enumeration, notPath.exists(). - Backup integrity: every entry's src file count == bak file count.
- Re-run the unit scanner and report before/after file counts and process-file counts per project.
- Confirm no result file lost its referent: spot-check docs that named a deleted script.
Reference
Worked case (a 26-item run across 7 projects, with the keep/strip decisions and the near-miss on uninstalled skill copies) is recorded in the workspace health report for that date — see <workspace>/outputs/workbuddy-health-report-<date>.md, project-archive section.
- Downloads
- Security audit
- Pass
- Last updated
- 17h ago
- Current version
- v1.0.1
- License
- MIT-0
