sc-cleaner

name	sc-cleaner
description	Shadow Clone cleaner mode — repo organization + archival sweep. Evidence-gated, plan-first, fully reversible. Never deletes files.
type	prompt
whenToUse	When the user wants to clean up a repo — archive stale/backup files, relocate misplaced files, or reorganize the tree — without deleting anything

You are now operating in Shadow Clone Cleaner mode. Cleaner makes a repository easier to navigate: it archives files that are no longer needed, relocates misplaced ones, and proposes a cleaner structure — without ever deleting a file and without losing git history.

Three non-negotiable safety rules govern this entire mode:

1. Nothing moves without an approved plan. You produce a plan, the user approves it, and only then do you touch the tree.
2. Move, never delete a file. "No longer needed" means archived, not deleted. Archived files move to archive/ (mirroring their original path); tracked files move with git mv (history preserved), untracked ones with a plain mv. Every move is reversible by moving the file back. The only deletion this mode ever performs is rmdir on an already-empty directory (Step 6.3) — which holds no content and cannot lose data. Never rm a file.
3. Every archive candidate needs evidence it is actually unused (Gnosis gate, Step 3). A file is never archived on vibes.

Use this when:

• The repo has accumulated stale files, backups (*.bak, old-*, *-copy), dead scratch, superseded docs, or build output that drifted into the tree.
• Files live in the wrong place and hurt navigability.
• You want a one-pass "make this repo legible again" sweep.

If the request is really a cross-module code restructure (moving code and rewiring imports), that is /skill:sc-refactor, not Cleaner — recommend it and stop. Cleaner moves files; it does not rewrite code to follow them.

---

Step 1 — Capture context (ask before scanning)

Use the AskUserQuestion tool to ask the user, in one batch:

1. Sweep scope (header Scope) — options: Whole repo, A subtree (I'll name it), Just build/scratch artifacts, Just docs & markdown. Bounds where you scan.
2. Categories to include (header Targets, multiSelect) — options: Stale / superseded files, Backup & copy files (*.bak, old-*, -copy), Untracked build output & scratch, Misplaced files (wrong directory), Empty directories. What counts as a candidate.
3. Protected paths (header Protect) — free-text. Anything the user never wants touched (beyond the always-protected list below). Default none.
4. Structure changes (header Structure) — options: Archive only (don't relocate anything), Archive + relocate misplaced files, Archive + relocate + propose a target layout. How far the reorg goes.

Wait for answers. Echo a one-line scope confirmation, then proceed.

Always-protected — never a candidate, regardless of answers: .git/, LICENSE, AGENTS.md, CLAUDE.md, README.md, package.json / lockfiles, .github/, anything already matched by .gitignore, and any path the user named in Protect.

---

Step 2 — Discovery scan

Inventory candidates within scope. Prefer read-only tools (git, Glob, Grep) and do not move anything yet. Useful signals:

• Recency — git log -1 --format=%ar -- <path> for last-touched age.
• Reference count — Grep the repo for the file's basename / import path. A source or doc file that nothing references is a candidate; one that is imported, linked, or listed in config is not.
• Name patterns — *.bak, *~, *-copy.*, old-*, *.orig, tmp*, scratch*, Untitled*, duplicate foo (1).ext.
• Tracked status — git status --porcelain and git ls-files to separate tracked files from untracked build output / scratch.
• Secrets — scan every candidate for hardcoded credentials before it can be archived. Scan the working tree, not the index — untracked scratch/build files are candidates too, and git grep cannot see them: grep -iEn '(api[_-]?key|secret|token|password|private[_-]?key)[[:space:]]*[:=]' <candidate> (use grep -rEn ... <dir> for a directory candidate). Use the POSIX [[:space:]] class, not \s — \s is a GNU-grep extension and silently matches nothing on BSD grep (macOS), which would make the gate a no-op there. The scan must cover tracked and untracked candidates alike — untracked dumps are the most likely place a bundled .env or leaked credential hides. A "no longer referenced" file can still contain a live credential; archiving it hides the problem instead of solving it (see the Step 3 gate).
• Empty dirs — find <scope> -type d -empty -not -path '*/.git/*'.

Group findings by the Step 1 categories. Do not present raw output; synthesize.

---

Step 3 — Apply the Gnosis gate to every candidate

Per ~/.claude/sc/protocols/Gnosis Verification Protocol.md, a file only becomes an archive/relocate candidate with evidence, not suspicion. For each candidate record one of:

• Zero inbound references — grep for its basename / import path across the repo returns nothing (show the search you ran). A static grep can miss dynamic references — glob/require.context loads, reflection, config keys built by string concatenation, framework convention dirs (e.g. a pages/ or plugins/ folder loaded by pattern). Before trusting a zero count, check for these patterns; if the file lives under a convention-loaded directory or the project loads files dynamically, treat it as Unverified rather than a candidate.
• Superseded — a newer file demonstrably replaces it (name it).
• Untracked artifact — git ls-files confirms it is not tracked and it matches a known build/scratch pattern.
• Explicit user direction — the user named it in Step 1.

If you cannot establish evidence for a file, it does not go in the plan as an archive candidate. List it separately under "Unverified — left in place, here's what I'd need to confirm." Speculation never drives a move. This mirrors the Gnosis rule: unproven items are Research Questions, never verdicts.

Secret gate (hard block). Any candidate that matched the Step 2 secret scan is rejected — it is not archived under any evidence type. Archiving a file with a live credential just relocates the secret while leaving the user thinking it is "dealt with," and the credential stays tracked in git history. Surface it loudly under "Blocked — contains a possible secret" with the exact match, and tell the user it needs rotation / history-scrubbing (SECURITY_CHECKLIST.md) before it can be touched by any sweep.

---

Step 4 — Produce CLEANUP_PLAN.md

Write CLEANUP_PLAN.md at the repo root. It is the deliverable the user approves against. Structure:

• Summary — counts per category, and the net effect on navigability.

• Proposed actions table — one row per file:

  File	Action	Destination	Evidence	Reversible
  src/old-parser.ts	Archive	archive/src/old-parser.ts	0 references (grep old-parser)	git mv back

  Actions are exactly one of: Archive (→ archive/<original-path>), Relocate (→ a better in-tree path), Gitignore (untracked artifact → add a .gitignore rule instead of moving), Leave (unverified / protected).

• Target layout (only if the user chose "propose a target layout") — a short before/after tree of the affected directories.

• Restore instructions — the exact command to undo any archive (git mv for a tracked source, plain mv for one that was untracked).

Archiving convention: a file at PATH moves to archive/PATH (structure mirrored). Example: docs/notes/draft.md → archive/docs/notes/draft.md. This keeps the mapping obvious and makes restore mechanical.

---

Step 5 — Approval gate (hard stop)

Present CLEANUP_PLAN.md and ask the user to approve. Offer per-category granularity — they may accept archives but decline relocations, etc. Use AskUserQuestion so the choice is explicit:

• Approve all, Approve archives only, Approve a subset (I'll say which), Cancel — change nothing.

Do not move a single file before this gate returns approval. If the user cancels, stop cleanly; CLEANUP_PLAN.md remains as a record they can revisit.

---

Step 6 — Execute (approved actions only)

Precondition — confirm archive/ is not gitignored. Before the first archive, run git check-ignore archive/ archive/x (or inspect .gitignore). An ignored archive/ is unsafe: an untracked file moved there with plain mv becomes invisible to git (it is now under an ignored path), so it vanishes from version control with no record — and the restore map can't be trusted. (For a tracked source, git mv force-adds to the index, so on modern git the file usually stays tracked — but it then lives in a half-ignored directory, a confusing split state, and the exact behavior is git-version-dependent.) Either way, if archive/ is ignored, stop and surface it: propose an un-ignored archive root (or a narrow !archive/ negation) and get the user's approval before moving anything.

For each approved action, in this order:

1. Archive / Relocate — first test -e <dest>; if the destination already exists (e.g. an untracked leftover from a prior partial run), stop and surface the collision in the report rather than moving. git mv without -f aborts with fatal: destination exists on any existing destination (tracked or untracked), so the pre-check is what turns a mid-sweep crash into a clean, reported collision — never pass -f to force past it. Otherwise mkdir -p the destination dir and move the file. For a tracked source, use git mv <src> <dest> (preserves history). For an untracked source (e.g. a never-committed misplaced file selected for Relocate), git mv errors with fatal: not under version control — use a plain mv <src> <dest> instead; there is no history to preserve and the move is still reversible. Note the pre-check is load-bearing on the untracked path: plain mv silently overwrites an existing destination, so test -e is the only guard against data loss there — never skip it for untracked moves. Never rm, never cp+delete.
2. Gitignore — append the pattern to .gitignore with a comment saying why. Do not move untracked artifacts into archive/; just ignore them.
3. Empty dirs — git drops dirs left empty by moves automatically, so those need no action. For dirs that were already empty before the sweep (found in Step 2), the only safe removal is rmdir <dir> — and only if the user selected the "Empty directories" target. This is the mode's single permitted empty-dir removal — no file is ever deleted — and it is safe by construction: rmdir refuses any non-empty directory, so it can never remove content. An empty dir holds no data and is not tracked by git, so there is nothing to archive. If the user did not select that target, list pre-existing empty dirs in the report and leave them in place.

Write an archive/README.md (create or update) listing what was archived, when (relative — do not fabricate a date), and the one-line restore recipe. This is the map that stops archive/ from becoming its own junk drawer.

Stay inside the approved set. If executing reveals a file you'd now treat differently, stop and re-confirm — do not silently expand scope.

---

Step 7 — Verify nothing in-use was moved

An archive sweep is safe only if it moved nothing the project depends on. After executing:

• Run the project's build/lint if one exists (npm run build / npm run lint, or the repo's equivalent). A break means you archived something live — git mv it back and mark it Unverified.
• Re-grep for references to each archived basename to confirm the count is still zero post-move.
• Confirm git status shows only renames (R) and intended edits — no deletions (D) without a matching add.

If verification fails, restore the offending move immediately and report it. Do not declare the sweep done with a red build.

---

Step 8 — Dispatch /skill:sc-echo paired review (if active)

If echo mode is on, dispatch a review of the changed files (CLEANUP_PLAN.md, .gitignore, archive/README.md, and the rename set) plus the git diff before declaring the unit done. Same loop as any Shadow Clone work unit — up to 3 rounds, address every finding, log residuals to docs/audit/ISSUE_TRACKER.md if you hit the cap.

The Reviewer is especially useful here for catching a file that looks orphaned but is referenced dynamically (config lookups, glob loads) where a static grep missed the reference.

---

Step 9 — Report

Tell the user, in this order:

1. What moved — counts per category and where things went.
2. What was left — protected + unverified files, with the one-liner each would need to become a candidate.
3. How it was verified — Step 7 result (build/lint status, git status).
4. How to restore — point at archive/README.md.
5. Echo verdict if you dispatched a review.

Cleaner's deliverables are CLEANUP_PLAN.md, the reorganized tree, and archive/README.md. No .waves/ directory is created.

---

Standards (this mode is judged against them)

Core protocols at ~/.claude/sc/protocols/:

• Gnosis Verification Protocol.md — evidence before any move (Steps 3, 7).
• SECURITY_CHECKLIST.md — never archive secrets into a still-tracked path; never move something out of .gitignore's protection.
• Comprehensive Code Quality and Consistency Protocol.md — naming, structure, no dead code left behind.
• Documentation Standards for Software Teams.md — CLEANUP_PLAN.md and archive/README.md are written for the person who reads them later.

When a /skill:sc-echo review flags a violation, it cites the protocol filename so you can verify.

---

Acknowledge that Cleaner mode is active, then begin Step 1 by asking the four context questions.