clean-artifacts

name	clean-artifacts
description	Audit + groom `docs/forsvn/artifacts/` — classify every file (KEEP/STALE/ORPHAN/LEGACY/EPHEMERAL), surface references + risk. On `--apply` archives candidates behind per-category confirmation (moves to dated archive, never deletes). Not for cleaning code (use clean-code) or machine state (use clean-machine).
argument-hint	[scope path | --dry-run | --apply | --threshold-days N]
allowed-tools	Read Grep Glob Bash Edit
user-invocable	true
disable-model-invocation	true
metadata	{"version":"1.1.0","budget":"standard","estimated-cost":"$0.05-0.20"}

Cleanup Artifacts — Orchestrator

Single-agent — orchestrator IS the runner; critic in-procedure. Audit + groom docs/forsvn/artifacts/: classify every file, surface refs + risk, archive non-KEEP on --apply. Never deletes. Metadata: routing.yaml. Methodology / when-not-to-use: references/playbook.md.

Core question: load-bearing, or cruft from weeks ago?

Critical Gates — load first

1. MOVE, never delete. mv into docs/forsvn/artifacts/.archive/[YYYY-MM-DD]/. --purge-archive (v1 out of scope) is the only deletion path.
2. HARD-NEVER refused. Canonical (brand/, research/, architecture/); VCS (.git/, .gitmodules, submodules); infra (.forsvn/index/manifest.json); append-only (docs/forsvn/experience/); anchors (docs/forsvn/artifacts/meta/{roadmap,tasks}.md).
3. --dry-run default. No move without --apply + per-category confirm.
4. Critic gate non-negotiable. Grep 5 random STALE/ORPHAN refs across docs/forsvn/artifacts/, brand/, research/, architecture/. Live ref → escalate (no prompt), refs surfaced.
5. Manifest-sync. Re-run bun scripts/manifest-sync.ts after any move.

Before Starting + Pre-Dispatch

Apply references/_shared/{before-starting-check, pre-dispatch-protocol, mode-resolver}.md. budget: standard; --fast bypasses prompts — Critical Gates supersede --fast. Read .forsvn/index/{manifest.json,artifact-index.md} + docs/forsvn/experience/technical.md (prior excludes). Manifest missing/stale (>1d) → NEEDS_CONTEXT. Dimensions: scope, mode, threshold (90d), excludes. Session execution profile (single-vs-multi): inherit per references/_shared/execution-policy.md.

Warm Start (procedure)

! `<cmd>` interpolation fires ONLY from SKILL.md slash invocation (not refs) — that is why this prompt stays in body.

Found:
- scope → "[full docs/forsvn/artifacts/ | <subpath>]"
- disk → ! `find docs/forsvn/artifacts -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' '` files;
  ! `find docs/forsvn/artifacts -name "*.md" -type f -mtime +90 2>/dev/null | wc -l | tr -d ' '` older than 90d
- manifest last touched → ! `git log -1 --format='%cr' .forsvn/index/manifest.json 2>/dev/null | grep . || echo 'untracked or no git history'`
- excluded paths → "[list or none]"

Default --dry-run, threshold 90d. Override (e.g., --apply, --threshold-days 30) or proceed?

Cold Start (no scope hint)

procedure — 4-question prompt, persist excludes to docs/forsvn/experience/technical.md.

Decision Tree

Canonical: references/procedures/runner.md. Phases: sanity-check → walk (skip .git/, node_modules/, .archive/, excludes, symlinks) → classify per cleanup-rules.md order HARD-NEVER → LEGACY → EPHEMERAL → KEEP → STALE → ORPHAN → critic gate → candidate table w/ risk tier (TIER-1 gitignored / TIER-2 tracked-clean / TIER-3 tracked-dirty / HARD-NEVER; TIER-3 NEVER moved) → dry-run report OR apply per-category prompts → mv to archive → manifest-sync → write report (order matters). Critic-FAIL walkthrough: references/examples/escalation-walkthrough.md. Report: references/report-template.md.

Classification Vocabulary

Full taxonomy: references/cleanup-rules.md.

Class	Meaning	Default
KEEP	manifest fresh, recently consumed, OR canonical/anchor	Leave
STALE	manifest entry > threshold AND no recent consumer	ARCHIVE; confirm
ORPHAN	no manifest entry; producing skill removed; hand-created + abandoned	ARCHIVE; confirm
LEGACY	frontmatter status: superseded/archived OR lifecycle: ephemeral	ARCHIVE (strong)
EPHEMERAL	matches known ephemeral pattern	ARCHIVE (strong)

HARD-NEVER overrides: emit KEEP (hard-never) regardless of mtime/manifest state.

Artifact Contract

• Path: docs/forsvn/artifacts/meta/records/[YYYY-MM-DD]-cleanup-artifacts-<slug>.md (dated, immutable). Lifecycle: snapshot. Consumer: operator audit trail.
• Frontmatter: skill · produced_by · version · date · status · mode · scope · threshold_days · total_candidates · total_archived · critic_gate · provenance.
• Template: references/report-template.md.
• Side effect: docs/forsvn/artifacts/.archive/[YYYY-MM-DD]/... on --apply; manifest re-sync after any move.

Configuration + Anti-Patterns

Params + v1-out-of-scope flags: references/configuration.md. Anti-patterns: references/anti-patterns.md — re-read before EPHEMERAL on a dated record, find -L, or per-file prompts.

Durable Rules (protected)

Completion Status

• DONE — critic passed, confirmations resolved, files moved (or dry-run written), manifest-sync clean, zero TIER-3 surprises, zero declined categories.
• DONE_WITH_CONCERNS — applied but flagged: TIER-3 surfaced (skipped), category declined, or tracked files moved. Report enumerates.
• BLOCKED — critic found live refs on --apply; HARD-NEVER violation; or scope missing.
• NEEDS_CONTEXT — manifest missing/corrupt. Recommend bun scripts/manifest-sync.ts.

Next Step

Operator reviews dry-run report; if comfortable, re-invoke --apply and walk per-category prompts. Commit archive + manifest-sync diff.