4.5Agents · Purge

Delete for real, from its own reviewed plan.

Purge is the only stage that physically deletes. Clean trashes; purge empties the trash — and only from a separate plan a human reviewed and approved. Trashed records stay discoverable until you deliberately remove them.

Purge boundary

Allowed freely trash list and trash purge --dry-run — discover and preview, moving nothing.
Needs approval trash purge --execute --plan-id for one reviewed purge plan, on one ledger.
Refused No global purge — --all is not supported for purge — and no piggybacking on the cleanup plan that trashed the file.

Hard boundary

The purge plan is always separate from the cleanup plan and separately reviewed. Physical deletion never happens as a side effect of cleanup.

Preview, then purge

Purge runs the loop one more time: list what is in trash, preview an age-based purge plan to get a purge plan id, then execute only that id after a human approves it.

# what is in trash for this ledger
artshelf trash list --ledger <ledger-path> --json

# preview an age-based purge and get a purge plan id
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json

# delete for real, only with the reviewed purge plan id
artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json

The approval wording for a purge:

approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>

Verify quiet

After a purge executes, confirm the trash is empty and the shelf is quiet with artshelf trash list --all --json and artshelf review --all --json.

Purge writes a receipt and records it as an owner=artshelf artifact, so the deletion stays auditable even after the files are gone.