abildtoft/kramme:workflow-artifacts:cleanup

Clean Up Artifacts

Delete workflow artifacts from the current working directory, local context evidence under .context/, and generated diagram files under ~/.kramme-cc-workflow/diagrams/. This is a destructive command: deletion is recoverable from the system Trash only when trash is installed (see Step 4), so it always confirms first.

Parse $ARGUMENTS before Step 1. If --auto is present, set AUTO_MODE=true. --auto deletes only current-project always-candidate artifacts from Step 1, keeps permanent SIW specs, and excludes shared diagram files under ~/.kramme-cc-workflow/diagrams/. It requires trash to be available and aborts on dirty tracked artifact files; it never falls back to permanent deletion.

Note: For SIW-specific cleanup, consider using /kramme:siw:remove instead. This cleanup command intentionally leaves siw/DISCOVERY_BRIEF.md and siw/SPEC_STRENGTHENING_PLAN.md alone because they can still be active handoff artifacts, while /kramme:siw:remove deletes them as part of destructive SIW cleanup.

Target Files

The complete inventory of cleanup targets lives in references/disposable-artifacts.yaml — the single source of truth. Read it before Step 1 and build the scan lists from its entries; do not maintain a separate inline inventory here. Only targets that exist on disk are deleted or reported; missing targets are ignored.

Each registry entry declares:

• path — a literal path, a shell glob pattern, or a directory (see type).
• type — file, glob (expand before deleting), or dir (delete the whole directory).
• category — working-dir (a project-local artifact), shared-diagram (the global ~/.kramme-cc-workflow/diagrams/*.html files generated by /kramme:visual:*, shared across sessions and projects), or permanent-spec (a durable SIW specification).
• retention — disposable (a candidate for deletion) or permanent (kept unless the user explicitly opts in during Step 3).
• condition / expected_contents — optional gates for conditional directories (see Step 1).

Group the entries into the two workflow groups:

• Always candidates for deletion — every disposable entry. The working-dir entries are the project-local review, audit, planning, SIW-tracking, and .context/ evidence artifacts. The single shared-diagram entry is shared across sessions and projects and is confirmed separately in Step 3.
• Permanent — kept by default — every permanent-spec entry. These are durable SIW specifications, not throwaway output, and are deleted only if the user explicitly opts in during Step 3.

When a producer adds a new fixed default output, register it in references/disposable-artifacts.yaml once and both this cleanup flow and its test pick it up. Never register user-supplied or custom output paths.

Workflow

Step 1: Scan

Read references/disposable-artifacts.yaml and record which registered targets exist, as three separate lists keyed by category: working-directory artifacts (working-dir, including the .context/ evidence directories), shared diagram files (shared-diagram, under ~/.kramme-cc-workflow/diagrams/), and permanent specs (permanent-spec). Expand glob entries so unmatched patterns contribute nothing. Only items discovered here are deleted or reported in later steps, and any entry's condition marker (such as siw/OPEN_ISSUES_OVERVIEW.md) is read here, before anything is deleted.

For directory entries that declare a condition and expected_contents:

• The directory is a candidate only if its condition marker exists. For example, siw/issues/ and siw/qa-intake/ are candidates only when siw/OPEN_ISSUES_OVERVIEW.md exists.
• If the directory contains files that do not match its expected_contents glob (ISSUE-*.md for siw/issues/, QA-INTAKE-*.md for siw/qa-intake/), drop it from the candidates and report it as skipped.

If no candidates and no specs exist, report No artifact files found. and stop.

Step 2: Warn on uncommitted changes

If the working directory is a git repository, run git status --porcelain --untracked-files=no -- against the found working-directory paths. If any tracked found file has uncommitted changes, list it and warn that deletion will discard that work (recoverable from Trash only if trash is installed). Skip this step when not in a git repo. Untracked found artifacts are expected cleanup targets and are listed in the confirmation prompt; do not treat ?? entries as dirty for this guard.

If AUTO_MODE=true and any tracked found working-directory path has uncommitted changes, stop without deleting anything.

Step 3: Confirm

Ask the user to confirm before deleting anything. Build the options from the Step 1 lists only — never list files that were not found. Present:

• the always-candidate artifacts found in the working directory,
• the shared diagram files found under ~/.kramme-cc-workflow/diagrams/, noting they are shared across sessions and projects,
• the permanent SIW specs found (default kept; delete only if the user explicitly includes them).

Offer at least: delete artifacts only (keep specs), delete everything found (artifacts + specs), or cancel. Omit the "everything" option when no permanent specs were found. If the user cancels, stop without deleting.

If AUTO_MODE=true, skip this prompt and choose "delete current-project artifacts only (keep specs and shared diagrams)". Never include shared diagram files or permanent specs in the auto-selected artifact set.

Step 4: Delete

Delete only the confirmed set. Prefer trash for recoverability. Build the set from discovered paths only. Expand globs before deletion so unmatched patterns are never reported as deleted. If the confirmed set is empty after filtering to existing paths, skip the deletion command and report that nothing matched the selection.

Delete every discovered entry whose registry type is dir by passing it to trash as a normal path argument; do not pass recursive flags to trash. Do not suppress deletion errors. Capture stderr/stdout so failures can be reported.

If AUTO_MODE=true, verify trash is installed before deleting anything. If it is missing, stop with MISSING REQUIREMENT: trash is required for --auto cleanup; rerun without --auto to confirm permanent deletion.

If trash is not installed and AUTO_MODE is false, warn that deletion will be permanent and ask for explicit confirmation after the warning:

Warning: 'trash' command not found. Files will be permanently deleted.
Install with `brew install trash` (macOS) or your distro's `trash-cli` package (Linux).

The fallback must respect this plugin's block-rm-rf PreToolUse hook (enabled by default), which blocks recursive forced deletion patterns and other destructive removal tools. Do not improvise around the guardrail with subshells, flag tricks, or alternate destructive tools. Instead:

• Files: after the explicit permanent-deletion confirmation, delete each file one at a time using the shell's standard non-recursive file-removal command with no force option.
• Directories: there is no permitted fallback while the guardrail is active. Ask the user to install trash; otherwise skip directory targets and report them as skipped.

After deletion, verify every target with [ ! -e "$path" ]. Record only verified-absent paths in deleted_paths. Record any surviving paths in failed_delete_paths with the captured error output; these must be reported as failures instead of "deleted".

Step 5: Report

• List files and directories from deleted_paths, and whether they went to the system Trash or were permanently removed.
• List failed_delete_paths with the captured error output.
• List anything skipped (directories with unexpected contents, specs the user chose to keep).
• Note if no artifact files were found.