feat(snapshot): --snapshot-prune to delete the unused snapshot files

[Chemaclass]

Problem

--snapshot-report-unused (added in #902) identifies snapshot files that no test resolved, and its help text is explicit that it "deletes nothing" (bashunit test --help). So the workflow stops halfway: bashunit tells you which files are dead, and you delete them by hand, one path at a time, hoping you did not miss one or delete one that was merely filtered out of that run.

The detection logic is already there — bashunit::snapshot::report_unused (src/assert/snapshot.sh:96).

Proposal

--snapshot-prune      Delete the snapshot files no test resolved

• Only valid on a full run. --filter, --tag, --shard, --rerun-failed or --changed narrow the set of tests, which makes untouched snapshots look unused — combining prune with any of them must be a hard error, not a data-loss surprise. --snapshot-report-unused already restricts itself to full runs; apply the same rule and make it explicit.
• Prints every deleted path.
• Deletes nothing when the run has failures, on the same reasoning: a failing run may not have reached the assertions that resolve those snapshots.
• Exit code unaffected by deletions.

Consider a --snapshot-prune-dry-run only if it does not duplicate --snapshot-report-unused, which is already the dry run.

Where to change

• src/assert/snapshot.sh:96 report_unused — factor the discovery so both flags share it.
• src/main/run.sh:126-128 (the report-unused call site), src/main/test.sh, src/main/validate.sh:60 for the mutual-exclusion check.

Acceptance criteria

• --snapshot-prune deletes exactly the files --snapshot-report-unused lists for the same run
• Every deleted path is printed
• Combining it with --filter, --tag, --shard, --rerun-failed or a single-file path argument exits non-zero before running, with an explanatory message
• Nothing is deleted when the run has failures
• Nothing is deleted on a run where no snapshots are unused
• --snapshot-update and --snapshot-prune in the same run behave sanely (define and test it)
• Named snapshots (feat(snapshot): add named snapshots and better mismatch guidance #986) are resolved correctly and not falsely reported unused
• Absolute test paths resolve correctly (fix(snapshot): two false passes in the placeholder path, and cover its behaviour #1002 regression guard)
• Works under --parallel, where each worker resolves its own snapshots — the unused set must be computed in the parent (fix(reports): every report format is empty under --parallel #1004 class of bug)
• Acceptance test operating on a fixture snapshot directory in a temp dir, never on the repo's own snapshots

Repo checklist (agent)

• TDD: RED → GREEN → REFACTOR. Write the failing test first.
• Bash 3.0+ only: no printf -v, no += append, no declare -A, no [[ ]], no ${var,,}, no &>>, no ${arr[-1]}. Expanding a possibly-empty array under set -u needs ${arr[@]+"${arr[@]}"}.
• A new CLI flag must be wired in all of these or a parity test fails:
  • parse in src/main/test.sh (report-style flags need export -n, see src/main/test.sh:188-196 for why)
  • validate the value in bashunit::main::validate_config_or_exit (src/main/validate.sh:60) — unvalidated input used to run the wrong thing and exit 0 (Unknown options are silently ignored: a typo'd flag runs a different suite and exits 0 #871, --jobs with a non-integer value hangs on Bash 3.x and is silently ignored on Bash 4.3+ #873)
  • default + env var in src/config/env.sh and a documented line in .env.example
  • --help text in the same block it belongs to
  • both completions/bashunit.bash and completions/_bashunit (anti-drift test feat(cli): bash and zsh completion scripts with an anti-drift test #778 fails otherwise)
• Gates: make sa, make lint, ./bashunit tests/, ./bashunit --parallel tests/. Never run shfmt -w.
• Docs: update docs/command-line.md. Editing docs/assertions.md invalidates the bashunit doc acceptance snapshot — regenerate it.
• CHANGELOG.md: add one line under ## Unreleased.
• Fixtures under tests/acceptance/fixtures/ must not end in *test.sh.
• One issue = one PR.