4.4Agents · Clean

Execute only what was reviewed and approved.

Clean is meant to be boring. The human approves one plan, the agent runs exactly that plan, leaves durable receipt evidence before moving files, and checks that the next review comes back quiet.

Cleanup boundary

Allowed freely validate, review, and cleanup --dry-run.
Needs approval cleanup --execute --plan-id for one reviewed plan.
Refused No daemon, no auto-execute, no global execute, no fresh-plan-then-execute.

# free to run any time: read-only checks and plan previews
artshelf validate --json
artshelf review --all --json
artshelf cleanup --dry-run --json
artshelf cleanup --dry-run --all --json

# only after a human approves this exact plan id
artshelf cleanup --execute --plan-id <id>

Hard boundary

Cleanup execution needs explicit human approval for the reviewed plan id. cleanup=trash quarantines files into Artshelf trash — recoverable, not deleted — and cleanup=delete stays refused. Emptying the trash for good is a separate stage: see Purge.

Dispose one reviewed record

dispose is the per-record reviewed path that follows get --inspect: one record id, one action, one reviewed plan id. It never runs in batch and never deletes physically.

# classify one inspected record into a reviewed plan
artshelf dispose --id <id> --action trash-resolve|resolve-only|snooze|keep --dry-run [--reason <text>] [--ttl <ttl>|--retain-until <date>] --ledger <ledger-path> --json

# approve: approve artshelf dispose ledger <ledger-path> plan <plan-id>
# only after a human approves this exact plan id
artshelf dispose --execute --plan-id <plan-id> --ledger <ledger-path>

Actions: trash-resolve moves the subject into plan-scoped Artshelf trash and resolves the row; resolve-only resolves the ledger row only (requires --reason); snooze extends retention (requires --ttl or --retain-until); keep stamps the record reviewed-and-kept. Execute re-snapshots the subject and refuses drift or a target conflict; reruns are idempotent and a receipt is left for audit.

Resolve confirmed records

Resolve only updates the ledger; it does not move or delete files.

# mark a record handled without touching the file
artshelf resolve <id> --status resolved --reason <text>

The approval wording for resolving a batch of missing records:

approve artshelf resolve missing ledger <ledger-path> ids <id...>

Verify quiet

After cleanup execute, dispose execute, or resolve, verify with artshelf review --all --json.

Cleanup execution writes a started receipt before the first move, completes it after ledger updates, and updates touched ledger records to trashed, review-required, or cleanup-refused. Dispose execution writes its own receipt, stamps dispose audit fields, and either resolves, snoozes, or keeps the reviewed row. Rerunning the same plan id resumes or idempotently replays durable receipt/trash evidence. Generated plans and receipts are recorded as owner=artshelf artifacts.