Okhp3 Replit Repl Janitor

okhp3-replit-repl-janitor

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Safely clean one Replit workspace's Git checkout without confusing generated branch names with proof, a closed pull request with a merged one, or an untidy filename with permission to rename it. The workflow is read-only first, evidence-led, and destructive only after the owner approves exact line items.

Scope

Safety contract

1. Start read-only. Run the bundled audit without --fetch; it reads the current checkout and prints JSON. Fetch separately only when network access is appropriate. Never prune during discovery.
2. Fail visibly. A missing base ref, failed Git command, detached HEAD, or non-repository path is evidence, not an empty result. Stop and report it.
3. Separate three facts. "Merged into origin/main", "closed pull request", and "abandoned with no PR" are different states. Never substitute one for another.
4. Names are hints, not verdicts. subrepl-*, replit-agent, and agent/* suggest generated work but do not prove it is safe to delete. The current branch is never a deletion candidate.
5. Plan before touching. Return the exact keep, merge, delete, and review branch buckets plus file actions. Wait for explicit approval of individual destructive lines.
6. Rename atomically. A file rename must update every importer and link in the same change. A public URL needs a redirect or transition plan.
7. Protect recovery paths. Never rewrite main, force-push, or delete stashes or archive refs under this skill.

Workflow

1. Establish a trustworthy baseline

Record the repository root, current branch, configured remotes, base ref, and working-tree status before making recommendations:

git status --short --branch
git remote -v
git rev-parse --verify origin/main

If remote-tracking refs may be stale, run git fetch --all separately and inspect its result. Do not add --prune: pruning before classification destroys evidence about stale remote branches.

NON-NEGOTIABLE — NO EARLY PRUNING: Never run git fetch --all --prune, git fetch --prune, or git remote prune until every stale remote branch has been classified. Refresh refs without pruning during discovery.

Run the deterministic local audit:

python3 .agents/skills/okhp3-replit-repl-janitor/scripts/audit-repo.py \
  --root . \
  --base origin/main

The script is read-only by default. --fetch is available only as an explicit opt-in and still never prunes.

2. Resolve pull-request state

The audit reports Git facts; it does not infer hosted pull-request state. For every unmerged branch, use the git-remote skill or GitHub CLI:

gh pr list --head '<branch>' --state all
gh pr view <number> --json state,mergeStateStatus,reviewDecision,statusCheckRollup,headRefOid

Do not infer "no PR" from a failed network call. Record the lookup as unknown and place the branch in review.

3. Classify every branch

Every non-current, non-main branch belongs in exactly one bucket:

Generated naming affects the explanation, never the bucket by itself.

4. Audit naming and detritus

Apply references/naming-conventions.md:

• default to kebab-case;
• preserve PascalCase .tsx/.jsx components;
• preserve camelCase useFoo.ts hooks;
• preserve root governance, tool-required, and web-standard filenames;
• flag spaces, mixed case, underscores, and uppercase extensions when no exception applies.

For detritus folders such as attached_assets/, _unused/, _drafts/, _scratch/, _old/, tmp/, temp/, and unused/, inspect contents before choosing delete or gitignore-and-untrack. A folder name is evidence for triage, not permission to discard its contents.

5. Present the plan and stop

Use this exact report shape:

## Branches & PRs
- KEEP: <branch> — <evidence>
- MERGE: <branch> — <PR and check evidence>
- DELETE: <branch> — <merged or owner-confirmed abandonment evidence>
- REVIEW: <branch> — <unknown fact and smallest next check>

## A. DELETE
- <path> — <why it is verified disposable>

## B. GITIGNORE-AND-UNTRACK
- <path> — <why it is generated but currently tracked>

## C. TRIAGE-THEN-DELETE
- <path> — <what must be inspected first>

## D. RENAME
- <old> → <new> — <rule, import/link impact, validation>

Stop. General approval of "the cleanup" is not approval of every destructive line; obtain an exact go/no-go for each merge, delete, and rename.

6. Execute approved items in small batches

Before each branch operation, run the bundled pre-delete check with the exact branch and SHA recorded in the approved plan:

python3 .agents/skills/okhp3-replit-repl-janitor/scripts/audit-repo.py \
  --root . \
  --check-delete \
  --branch '<branch>' \
  --reviewed-head '<reviewed SHA>'

The JSON result records both reviewed_head and the freshly read current_head. If the bucket is review, stop, record the hold, and run no deletion command. Only a delete result may be executed, and its deletion_commands must be run in the emitted order. The sequence is remote-first (git push origin --delete <branch>) and local second (git branch -d <branch>). The check is read-only and never executes either command.

For an approved merge:

1. Confirm PR approval and required checks.
2. Confirm the PR head SHA matches the reviewed branch head.
3. Squash-merge through the pull request.
4. Fetch and verify the merged result is reachable from the base.
5. Delete the exact remote branch first.
6. Delete its local tracking branch second.

For approved files, use git rm and git mv so the change is explicit. Plain rm is acceptable only for an untracked or gitignored working file.

7. Verify and report

After every approved batch:

python3 .agents/skills/okhp3-replit-repl-janitor/scripts/audit-repo.py \
  --root . \
  --base origin/main
git status --short

If a tracked source file moved or was renamed, run the relevant validation and restart the affected workflow, then inspect its logs and preview. Report what changed, what remains, and which recovery path is still available.

Output contract

Return:

• repository root, current branch, base ref, and whether refs were fetched;
• the four branch buckets with evidence for every item;
• the four file-action sections;
• unresolved unknowns and the smallest safe next check;
• exact writes performed, or an explicit statement that discovery was read-only;
• post-change audit, Git status, and workflow validation results when execution was authorized.

Failure handling

Resources

• scripts/audit-repo.py — deterministic, no-fetch-by-default JSON audit of branches, naming violations, and nested detritus.
• references/naming-conventions.md — portable kebab-case policy and structural exceptions.
• references/foundry-architecture.md — Phase 1 intent, scope, and brand decision for this renamed skill.
• evals/evals.json — three live-evaluation prompts with four anchored expectations each.
• benchmarks/benchmark.json — version-matched Foundry evidence after live execution.

About

Built by Jamie Hill · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.