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 - only from a separate plan a human reviewed and approved, or from an exact approved trash-purge bundle that binds each target to live trash facts. Trashed records stay discoverable until you deliberately remove them, and the UI purge path states there is no recovery path.

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, or ui execute for an exact approved trash-purge bundle.
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. UI purge bundles are also separate approvals over exact selected trash targets. 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 the CLI purge path:

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

For browser review, approve a trash-purge bundle only after checking the grouped purge lane and its no-recovery warning. Nothing is selected by default; the agent deletes only the exact selected targets through ui execute.

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.