# Research: File Housekeeping Best Practices
# PATH: backend/docs/research/housekeeping-best-practices.md
# COLLECTED: 08/06/26 by Claude Code
# SOURCE: Nextcloud, JFrog, cPanel documentation + server management guides
# PURPOSE: Reference for building SOP-HOUSEKEEPING.md and housekeeping.php
---

## Key Finding: Nextcloud's Tiered Retention Algorithm

The most battle-tested version retention system found. Keeps ONE version per time tier,
prunes oldest first when storage fills. Named/current versions never auto-deleted.

| Time Since Creation | Keep 1 version per... |
|---|---|
| First 10 seconds | 2 seconds |
| First minute | 10 seconds |
| First hour | 1 minute |
| First 24 hours | 1 hour |
| First 30 days | 1 day |
| After 30 days | 1 week |

**Platform application:** EXEC_OPEN files — keep only the LATEST revision (highest letter suffix).
All prior revisions (O, P, Q, R when S exists) are safe to trash.

---

## Key Finding: JFrog's Two-Bucket Model

Everything is either Cleanup or Archive. Nothing hard-deletes without trash first.

- **Cleanup**: stale packages/files → move to trash → permanent delete after N days
- **Archive**: move to cold storage → restorable on demand

**Safety rule (JFrog):** "Data is permanently lost if cleanup is done without using the Trash Can."

**Platform application:** We already have `Trash/` at root. All automated cleanup moves
to `Trash/`, never deletes. Trash lifecycle (permanent delete) runs separately.

---

## Key Finding: Standard Server Housekeeping Categories

From cPanel/server management consensus — five categories, each with a rule:

| Category | Location Pattern | Max Age / Retention |
|---|---|---|
| Temp/staging files | `backend/tmp/`, `/tmp/` | 7 days |
| Log files | `error_log`, `*.log` | 30 days or 500KB threshold |
| Old backup versions | `backups/[system]/` | Keep CURRENT + PREVIOUS only |
| Orphan scripts at root | Root-level `.php` not in whitelist | Flag immediately |
| Archive ZIPs at root | Root-level `*.zip` | 30 days then trash |

---

## Key Finding: "Keep Last N" Pattern

More reliable than age-based for versioned files. Algorithm:
1. Find all files matching a pattern (e.g. `EXEC_OPEN_Admin_00_*.txt`)
2. Sort by name descending (alphabetical suffix = latest)
3. Keep first N (usually 1 for startup files, 2 for backups)
4. Move rest to Trash/

This handles irregular update cadence better than age-based rules.

---

## Safety Workflow (from multiple sources)

1. **Scan** — identify all files matching cleanup rules
2. **Categorize** — KEEP / TRASH_SAFE / REVIEW (never skip REVIEW for unknowns)
3. **Log** — record every file before moving it
4. **Move to Trash** — never hard-delete in automated jobs
5. **Verify** — confirm platform still healthy after cleanup
6. **Permanent delete** — separate manual step, after verification

**David's role:** Permanent delete step only. Everything else can be automated.

---

## Platform-Specific Rules (derived from research + platform knowledge)

### Gov Files — What's Safe to Trash
- `*.previous.md` — zero retained, always trashable
- `EXEC_OPEN_[Sys]_[decade]_[X].txt` where X is not the latest letter — trash
- `ARTIFACTS-[decade].previous.md` — trash
- `knowledge-[decade].previous.md` — trash

### Root Directory — Orphan Scripts (trash immediately)
These were one-off tools, migration scripts, or debug files. Migration complete 08/01/26.
- `gov_scan.php`, `gov2_scan.php`, `gov_final_check.php`
- `legacy_rename.php` (migration done)
- `master_handoff_fix.php` (one-off fix)
- `sync_debug.php` (explicitly flagged safe to delete in platform memory)
- `vl_audit.php`, `vl_fix.php`, `vl_read.php`
- `cmd_audit.php`
- `EXEC_OPEN_[System].[decade].D.txt` (all 11 — old Series D, wrong location)
- `EXEC_OPEN_Series_E_07_08_26.zip`, `EXEC_OPEN_Series_F_ALL_07-08-26.zip`
- `Builder_EXEC_OPEN_Series_D_07_08_26/` (directory)

### Root Directory — CHECK BEFORE TRASHING
- `api_restore.php` — emergency restore script; ask David if still needed
- `GymLogger_Session_07_10_26/` — unknown purpose; inventory contents first
- `0369/` — unknown; inventory contents first
- `nc_assets/` — possibly Nextcloud assets; check if referenced anywhere

### Backups — Keep Last 2
Each system in `backups/[system]/` should have CURRENT + PREVIOUS only.
The CURRENT/PREVIOUS rotation already exists. Any third+ copies → Trash.

---

## Sources

- Nextcloud File Versioning: https://docs.nextcloud.com/server/stable/admin_manual/configuration_files/file_versioning.html
- JFrog Retention Policies: https://docs.jfrog.com/administration/docs/retention-policies
- Cyberly Server Disk Cleanup: https://www.cyberly.org/en/how-do-i-automate-server-disk-cleanup/index.html
- cPanel Residual Files: https://www.unitech.qa/announcements/155/Automating-Residual-Files-Cleanup-in-cPanel-Websites.html
- Backup Retention Pruning: https://dohost.us/index.php/2026/02/27/pruning-the-past-setting-up-automated-retention-policies-for-your-backups/