soia-env-storage-cleanup

soia-env-storage-cleanup

First perform a read-only measurement of SOIA managed directories, then generate a time-limited cleanup plan with a summary. Deletion is an irreversible high-risk action: the candidate categories, sizes, conditions, and risks must be shown to the customer, and only after the customer explicitly authorizes this plan may it be executed and verified.

Customer-readable description

What this skill can do

The customer wants	The skill will do	The customer can see
See how much space SOIA data occupies	Read-only measurement of configuration, state, cache, and temporary directories	Size, file count, and cleanable size for each category
Determine which files can be cleaned	Classify by time limit, capacity, safety markers, and activity status	Cleanable, requires authorization, prohibited from cleaning, and the reasons
Clean expired data	First freeze the plan, warn about risks, and wait for explicit authorization before deleting according to the plan	Number deleted, failed items, and actual space freed
Verify cleanup results	Recheck deletion results and receipt summary	Whether deletion succeeded and whether any files reappeared

This skill only cleans SOIA standard managed directories. It does not scan or clean the entire disk, and does not delete ordinary downloads, projects, photos, documents, or other application data.

How the customer uses it

The customer only needs to state the goal in natural language and does not need to operate a terminal:

1. When the customer says "Check SOIA usage", only a scan is performed, and no files are deleted.
2. When the customer says "Clean cache", first generate a plan and show the risks; this sentence only indicates the goal, not final deletion authorization.
3. The Agent must stop and wait for the customer to explicitly reply after seeing the latest plan, for example "Confirm deletion according to plan <plan_id> ".
4. Only after the same unexpired plan is authorized may the Agent execute cleanup; vague "continue" or "handle it as you like" cannot serve as authorization.
5. After cleanup is complete, recheck and report the actual results to the customer.

Dependencies and installation

Dependencies	Type	Installation / configuration	What to do if missing
Python 3.10+	Strong dependency	Use the system or soia-env-python-install Python provided by	Stop cleanup and only explain how to fill the gap
soia-env-storage-cleanup	This skill	claude plugin install soia-env@soia(or the npx route npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-storage-cleanup -y）	Prefer installing the domain plugin; the npx route will fall into the shared source of truth

This skill does not store accounts or credentials. The following variables can only override managed directory locations, and the values must be directories rather than secrets:

SOIA_SKILLS_CONFIG_HOME
SOIA_SKILLS_STATE_HOME
SOIA_SKILLS_CACHE_HOME
SOIA_SKILLS_TEMP_HOME

When using environment variables to specify a custom root directory, you must first show the target directory to the customer and obtain configuration confirmation, then write the category-matching .soia-storage-root.json; when the marker is missing, the executor refuses to claim any arbitrary directory as SOIA storage.

WorkBuddy The loading unit of is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it; it must be installed separately, see docs/install/workbuddy.md。

Private information and intermediate data

• The configuration directory is only counted, not deleted; credentials are still managed by the provider login state or the system credential store.
• Cleanup plans and receipts are stored in the user state directory with user-private permissions; they must not be committed to Git.
• The plan itself may store exact paths to prevent deleting the wrong items, but customer replies only show desensitized categories, counts, and sizes.
• Do not read file contents or compute content summaries; status cleanup only reads managed policy markers.
• Do not claim repositories, user home directories, customer deliverables, or unknown directories as cleanable directories.

Mandatory authorization and risk reminders

Scanning, planning, and deletion are three independent stages. The initial "help me clean up" request cannot simultaneously authorize a candidate list that has not yet been generated.

Before executing deletion, the following must be shown to the customer:

风险提醒：下面的删除不可撤销，可能导致缓存重新下载、审计历史缩短，
或使依赖这些中间文件的任务需要重新运行。配置、凭据和客户交付物不会删除。
请确认是否按计划 <plan_id> 删除 <候选文件数> 个文件，预计释放 <大小>。

Only if the customer explicitly confirms the current plan_idafter this reminder can authorization_id be generated and the execution command be called. In the following cases, rescanning and reauthorization are required:

• the plan is older than 30 minutes;
• the plan summary does not match;
• the candidate files or status policy have changed;
• the customer changes the cleanup scope;
• new directories or data categories need to be added.

Cleanup scope and method

Data category	Default condition	Cleanup method	Risk
Configuration	None	Never automatically cleaned, only counted	Deletion prohibited
Audit status	older than 30 days, more than 100 items, or more than 10 MiB, and the skill directory has a managed marker that permits cleanup	After customer authorization, delete ordinary files in expiration/oldest order	High
Cache	older than 7 days, or total size exceeds 512 MiB	After customer authorization, delete in expiration/oldest order	Medium
Temporary files	older than 24 hours and no active marker	After customer authorization, delete	Medium

Regardless of how the customer authorizes, the following objects must still be refused:

• paths outside the SOIA managed root directory;
• symbolic links, devices, sockets, and non-ordinary files;
• active directories containing a fresh .soia-active marker;
• .soia-active、.soia-managed-storage.json the security marker itself;
• .soia-storage-root.json the root directory marker itself;
• state files without a valid status cleanup marker;
• candidates whose file size or modification time changes after the plan;
• configurations, credentials, and customer deliverables.

For the detailed machine contract and marker format, see Cleanup security contract。

Workflow

1. Read-only scan

Agent runs:

python3 scripts/storage_cleanup.py scan --json

Scanning must not create directories, plans, or receipts. Convert the machine output into the customer list below, without echoing exact private paths.

2. Generate cleanup plan

When the customer requests cleanup, run:

python3 scripts/storage_cleanup.py plan --json

The plan can only be written to the managed state directory, and includes a 30-minute validity period, candidate file metadata, and plan_digest. Generating a plan still does not represent authorization, nor does it delete files.

3. Present the plan and wait for customer authorization

Present to the customer:

Data category	Current size	Cleanable size	Candidate files	Cleanup condition	Risk
<Configuration/Audit status/Cache/Temporary files>	<Size>	<Size>	<Count>	<Condition>	<Prohibited/High/Medium>

Then send a mandatory risk reminder and end the current execution round. Without a new customer reply, step 4 must not be entered.

4. Clean up according to the authorized plan

After confirming that the customer has explicitly authorized the current plan, the Agent generates a random authorization_id, records the authorization time, and runs:

python3 scripts/storage_cleanup.py clean \
  --plan <managed-plan-path> \
  --plan-digest <plan-digest> \
  --confirmed-plan-id <plan-id-confirmed-by-customer> \
  --authorization-id <opaque-authorization-id> \
  --authorized-at <RFC3339-with-timezone> \
  --acknowledge-risk CUSTOMER_APPROVED_IRREVERSIBLE_DELETE \
  --execute --json

Must not pre-fill authorization on behalf of the customer, and must not put --execute into the scan or plan command.--confirmed-plan-id Must come from the customer's explicit reply after the risk reminder and must precisely match the plan. The executor deletes only ordinary files in the plan that are still unchanged and still meet the conditions; uncertain items go into skipped。

5. Review

After cleanup, run:

python3 scripts/storage_cleanup.py verify --receipt <managed-receipt-path> --json

Verify the actual number deleted, number of bytes deleted, failed/skipped items, changes in disk free space, and whether files reappear. A deletion command returning 0 cannot replace the review.

Customer status list (mandatory)

Skills	Current status	Current version	Latest version	Running status	Update time	Processing result
Storage cleanup	<Scanned/Awaiting authorization/Cleaned/Blocked>	1.0.0	<Version or not obtained>	<Normal/Warning/Abnormal/Unverified>		<Candidate found/Awaiting customer confirmation/Space freed/Blocked: reason>

• Write "Scanned" only when the scan is complete; after generating the plan, write "Awaiting authorization".
• When there is no explicit customer authorization for the current plan, the processing result must say "Awaiting customer confirmation" and must not say "Cleaned".
• 更新时间 is the completion time of the last scan or deletion review, not the skill file modification time.

Logs and completion receipt

Customer-visible replies report only:

• The size, file count, and candidate size of the four managed data categories;
• Current plan_id, validity period, and whether it is awaiting authorization;
• Risk reminders and prohibited cleanup categories;
• After authorization, the actual number deleted/skipped, number of bytes deleted, and review status;
• Do not display exact private paths, file names, user names, tokens, or file contents.

Local machine receipt saves plan_digest、authorization_id、authorized_at、checked_at, deletion results, and receipt_digest, using directory permissions as much as possible 0700, file 0600。

Forward testing

At least cover the following fixtures: configuration files are never deleted; expired cache/temp can enter the plan; new files and active directories do not enter the plan; reject when state is missing a marker; reject symbolic links; block on incorrect/expired digests and missing authorization; skip candidates that changed after the plan; after successful authorization, delete only files within the plan and review the receipt.

Real-machine acceptance runs only scan. Before deleting, the forward test must be completed within the test temporary directory; it must not be verified using a real customer directory.