merge-cleanup-deep

Read-only, sub-agent-driven triage of the checkouts /merge-cleanup preserved (PRESERVE_UNPUSHED, PRESERVE_DIRTY, PRESERVE_UNVERIFIED_*): zip each clone to a dated backup with a manifest, fan out at mo

SKILL.md

GitHub

/merge-cleanup-deep — Preserved-Checkout Triage (backup → fan-out → verdicts → handoff)

/merge-cleanup preserves any checkout it cannot prove landed, and its Phase 3 only escalates with "recommend a deeper scan". This skill is that deeper scan. It owns the judgment the script refuses to make — is the unlanded work in this clone worth a PR, already landed under another name, or scrap — and it produces evidence an operator can act on. It reads; /merge-cleanup writes.

Strictly adheres to WORKTREE-SAFETY.md and AGENTS.md.


Recite this — verbatim, as the first thing in your first response

Merge-Cleanup-Deep Discipline:

  1. Intake from the scanner, never a second discovery (Phase 0). Take /merge-cleanup's audit (scan_clones.py --json) and select the non-exempt PRESERVE_* rows; list live checkouts as skipped, never as candidates.
  2. Back up before you look (Phase 1). Zip every candidate with its .git to a dated backup folder and write the manifest; no analysis starts on an un-backed-up clone.
  3. Fan out read-only, grouped by branch family (Phase 2). At most three sub-agents, every clone of one branch name to the same agent, hard read-only rules, evidence checklist a–g, verdicts with the deciding line.
  4. Re-verify before you believe (Phase 3). Every "unique defect" claim is re-checked against current development and open issues; one landed-elsewhere claim per family is spot-checked by the caller; ancestry is not content and a clean diff is not provenance.
  5. Hand off, do not mutate (Phase 4). PR-WORTHY → fresh clone and cherry-pick; NEEDS-OWNER → issue comment naming the backup; SUPERSEDED / ABANDON → the list goes to /merge-cleanup teardown; a clone equal to an open PR head is a hold, named with its PR.

Overall Goal: Every preserved checkout carries a verdict, the evidence line that decides it, a backup it can be restored from, and one next step — with nothing in any clone changed.

Then begin work.


When to use / not use

  • Use after a /merge-cleanup run leaves PRESERVE_UNPUSHED / PRESERVE_DIRTY / PRESERVE_UNVERIFIED_* rows and the operator wants to know what is in them; or standalone when a parent directory has accumulated task clones nobody remembers.
  • Do not use to land PRs, to tear down clones, or to "fix" a clone in place. Teardown stays in /merge-cleanup Phase 6 (fresh inspection, Trash only, GH-534 A.5). PR creation goes through /start-task-style fresh clones. This skill writes only to the backup folder, the scratchpad, and — on request — a GitHub issue comment.

Why a separate skill

/merge-cleanup is script-owned, parity-guarded and pinned by tests; its rule is the script owns the evidence and the cap, the caller owns the analysis. This triage is caller-owned judgment, costs three agents' worth of tokens per run, and must be opt-in. Discovery is not duplicated: Phase 0 consumes the scanner's JSON, and Phase 4 hands the disposable list back to the scanner's teardown.


Phase 0 — Intake from the scanner

Read the target primary's policy through the same cleanup resolver before briefing agents:

python3 skills/2-daily/merge-cleanup/scripts/merge_cleanup.py \
  --primary "$PRIMARY" --show-merge-policy > "$SCRATCH/merge-policy.json"

Use the installed cleanup script path outside Forge. Require exit 0 and a nonempty JSON report; otherwise stop and name the policy error. Pass its preserve_commit_history, strategy, and source to every agent and retain the report with the audit. Do not parse another config or infer policy from a stale clone or the vendored harness. The maintainer contract is in merge-cleanup.

python3 skills/2-daily/merge-cleanup/scripts/scan_clones.py --json \
  --primary "$PRIMARY" --root "$(dirname "$PRIMARY")" --prefix <repo-name> > "$SCRATCH/scan.json"
  • Pass --root explicitly: SAFE_ROOTS does not include the primary's own parent, and SOP task clones are siblings of the primary (#722). An empty table is "unscanned", not "clean".
  • Candidates are rows whose disposition starts with PRESERVE_ and is not PRESERVED_USER_EXCLUDE or PRESERVE_WIKI. PRIMARY_CHECKOUT is never a candidate.
  • Rows carrying ACTIVE_WRITING, ACTIVE_PROCESS, ACTIVE_TICK_CLAIM, or a driver lock are live sessions: list them under "live — skipped" with the reason, and never assign them to an agent. The same applies to any clone whose directory name matches an open PR's branch that another session is still pushing to.
  • Record the shared facts every agent needs: origin/<integration> head, merged PR heads and merge-result SHAs (including historical squash commits) for the branches involved, open PR heads (gh pr list --state all --head <branch>).

Phase 1 — Backup before analysis

# Standardized clone backup at <top-level>/_backups/<repo>/<timestamp>/
python3 skills/2-daily/merge-cleanup/scripts/backup_clones.py \
  --primary "$PRIMARY" \
  --candidates-json "$SCRATCH/candidates.json" \
  --backup-root "$(dirname "$PRIMARY")/_backups" \
  --json > "$SCRATCH/backup.json"
DEST="$(python3 -c "import json; print(json.load(open('$SCRATCH/backup.json'))['run_dir'])")"
  • Standardized Directory Hierarchy: <root>/_backups/<repo-name>/<timestamp>/
    • zips/: Individual <clone>.zip archives (with .git included, disposable caches like node_modules and .venv excluded).
    • metadata/: MANIFEST.tsv (SHA256, branch, HEAD, dirty count, unpushed commits, verified status), manifest.json, and per-clone <clone>.git-summary.txt.
    • reports/: Triage reports and teardown logs ($DEST/reports/).
    • SUMMARY.md: Human-readable summary table and inventory.
  • Integrity Validation: Automatically tests zip CRC and compression (testzip()) and computes SHA256 before analysis or teardown begins.
  • Backups and integrity verification complete before sub-agent analysis begins, guaranteeing an airtight restore point for standalone full clones. Linked worktrees with external Git storage cannot produce self-contained archives and are refused; unverified or unsupported candidates are not analysed or torn down.

Phase 2 — Fan-out (≤3 read-only sub-agents)

Group candidates so that every clone of one branch name goes to the same agent — ancestry chains between five clones of feat/gh646-status-label can only be established by one agent that can fetch each HEAD into a temp ref. Balance the remaining clones for count. Use the prompt template in agents/scan-prompt.md; fill in the clone list, the shared facts, and the report path. Sonnet-class agents are sufficient; the checklist does the work.

Hard rules the template carries (a violation is worse than an incomplete report):

  • Never run git checkout/switch/reset/stash/clean/rebase/merge/commit/push/branch -D, rm, mv, or any test suite (validate.sh, test/*.sh, pytest) in a clone. Never edit a file in a clone.
  • git -C "<path>" for every command; never cd into a clone.
  • git fetch is allowed (origin, a PR head into refs/deepscan/prN, a sibling clone's HEAD into refs/deepscan/<name>); every refs/deepscan/* ref is deleted with git update-ref -d at exit. A clone whose origin is a local path fetches the integration branch from the GitHub URL.
  • Report only to its own scratchpad file. Nothing else is written anywhere.
  • Other agents' clones, the primary, and live-session clones are out of bounds.

Per-clone evidence checklist (the agent quotes commands and output):

Evidence Command shape
a remote, branch, HEAD, dirty files (diff shown unless a generated view), ignored files of note git remote -v, status --porcelain --untracked-files=all, status --ignored
b unlanded commits per local ref incl. backup/* and a detached HEAD, files touched log <dev>..<ref>, diff --stat $(merge-base <dev> <ref>)..<ref>
c landed-elsewhere: by ancestry (merge-base --is-ancestor <ref> <merged-pr-head>), by content per non-generated file (diff <dev> <ref> -- <path>; empty = landed; distinctive-identifier git grep on <dev> for reshaped hunks), and against open PR heads (refs/pull/N/head) one line per file: LANDED / PARTIALLY LANDED (what remains) / NOT LANDED
d QA attestation: relay-drive: attest … approved, final QA approved, LGTM, QA approved in commit messages, relay-system/, PROJECT/2-WORKING/GH-*; quote it and say what it attests (plan vs implementation) git log --grep, grep -rn
e linked issue(s) and state gh issue view N --json state,title,closedAt
f family view: ancestry between the clones of one branch name; which holds the superset merge-base --is-ancestor pairwise on temp refs
g verdict with the deciding evidence line and one next step see below

Verdicts:

  • PR-WORTHY — unique, coherent work not on development or in an open PR, attested or one QA round from attested. Names the files and the issue it closes.
  • SUPERSEDED — the content is on development or in an open PR; names the PR/commit and the diff that proved it (a deletions-only diff against the merged head is the classic signature).
  • NEEDS-OWNER — unique work that is incomplete or unattested; names what is missing (a QA round that never ran, a Blocked status header, an escalated relay).
  • ABANDON-CANDIDATE — nothing unique beyond generated views (LEADERBOARD.md, releases.*), scratch, backups whose content landed, or a doc development deliberately deleted.
  • HOLD — HEAD equals an open PR's head exactly; keep until that PR lands or closes.

Phase 3 — Synthesis with re-verification

The caller does not forward verdicts; it checks them.

  • Every "unique defect / unfiled finding" claim is re-run against current development (grep -n the cited lines) and against gh issue list --state all --search … before it becomes intake. Today's finding: both "undisposed blockers" a QA relay surfaced were already #656/#657, and the fix for them lived in a different clone family.
  • One landed-elsewhere claim per family is spot-checked by the caller with git -C <clone> diff <dev> HEAD -- <path>.
  • Watch for the shared false positive: a file that development deliberately deleted after the clones forked shows as "unique" in every clone (PROJECT/1-INBOX/GH-505-*.md on 2026-09-21).
  • Evidence standards (workhorse Rung 5): ancestry proves graph reachability; per-path blob/diff identity proves content; an attestation proves review, not landing. A commit not being an ancestor is not evidence its content is missing; a clean diff is not provenance.
  • Report original commits preserved separately from content landed. Test each relevant local ref against origin/<integration> with merge-base --is-ancestor; ancestry to a PR head alone does not prove those commits survived its merge. Use yes/no/not established with cited SHAs. Missing ancestry is not proof of missing content or a retroactive policy violation: old squash landings still use the existing provenance checks. Never let an enabled policy bypass them.
  • Produce one disposition table: clone · verdict · original commits preserved · content landed · deciding evidence · next step. Copy the agent reports into the backup folder (<DEST>/reports/) so the analysis outlives the session.

Phase 4 — Handoff (no mutation here)

Include the effective policy/source and both ancestry/content findings in every handoff. PR-WORTHY work carries the requirement for its eventual merge method; cherry-picking recovery work creates new IDs, so name the source commits and backup rather than claiming original IDs were preserved. Cleanup re-reads the primary's policy and fresh safety evidence before acting. Historical content equivalence never becomes a blanket authorization to remove a checkout.

Verdict Handoff
PR-WORTHY Fresh full clone from origin/<integration>, cherry-pick the named hunks/tests (never push the stale branch as-is — its base is typically dozens of commits old), final QA per repo policy, one PR naming the issues.
NEEDS-OWNER Comment on the linked issue: clone name, backup zip path, what is missing.
SUPERSEDED / ABANDON-CANDIDATE Hand the list to /merge-cleanup … --teardown-only --execute (fresh inspection, Trash only). Never rm -rf; never move a clone by hand.
HOLD Name the PR; re-run after it lands.
live — skipped Report; the owning session decides.

The backup zips make teardown doubly recoverable (Trash + zip); say so in the report so the operator can empty Trash without losing the restore path.

Worked example — 2026-09-21, XYZ-forge, 14 preserved clones

3 agents (5/5/4, grouped by branch family), ~380k tokens, 20 minutes; zips 991 MB. Result: 1 PR-WORTHY (closeout-evidence-fixes: real fixes for #656/#657, final QA never run, base 64 commits old), 1 HOLD (gh646-pr-completion == draft #723 head), 12 SUPERSEDED/ABANDON — including five independent re-executions of one GH-646 plan whose core connector was byte-identical to #723, and a flightdeck branch whose diff against the merged #719 head was deletions only. No clone was modified; every refs/deepscan/* ref was deleted.

Safety guarantees

  1. Zero mutation of any clone. Sub-agents run under hard read-only rules; the caller never writes into a clone either. Backups happen before analysis.
  2. Discovery and teardown are not duplicated. Phase 0 is the merge-cleanup scanner's JSON; Phase 4 returns to the merge-cleanup teardown.
  3. Live sessions are never triaged. Activity, open handles, tick claims, and driver locks make a checkout "skipped", not "candidate".
  4. Verdicts are re-verified. No finding becomes an issue, and no clone becomes disposable, on a sub-agent's word alone.