marathon-cleanup

name

marathon-cleanup

description

Audit active PDDA marathon plans and bundles, reconcile every lane against canonical project docs, frontmatter and status tables, GitHub issue and PR state, landed commits, tests, and CHANGELOG evidence, then archive only verified-complete task docs and fully complete marathons. Use when asked to clean up, reconcile, retire, archive, or sweep completed marathon files under PROJECT/2-WORKING, especially after marathon lanes merge. Defaults to report-only and requires explicit confirmation before moving files or changing lifecycle records.

Marathon cleanup

Reconcile marathon execution artifacts with PDDA lifecycle state. A move is the final bookkeeping step, never the evidence that work completed.

Guardrails

• Read ROUTER.md, AGENTS.md, GUIDING-PRINCIPLES.md, ROADMAP.md, PROJECT/PDDA.md, and the candidate marathon in full before classifying it.
• Default to audit-only. Do not edit, move, close issues, create commits, or change ROADMAP or CHANGELOG until the operator confirms the exact proposed move set.
• Never classify from a closed issue, checked box, frontmatter word, commit message, or changelog entry alone. Require converging durable evidence and no contradiction.
• Preserve unrelated dirty-worktree changes. Stop if a candidate or lifecycle ledger has overlapping edits that cannot be safely merged.
• Use git mv for approved repo moves. Never delete marathon files or rewrite history.
• Treat unavailable GitHub state as UNKNOWN, not complete.

1. Inventory marathon candidates

Inspect only active execution artifacts under PROJECT/2-WORKING:

find PROJECT/2-WORKING -maxdepth 1 \
  \( -type f -o -type d \) \
  \( -name 'MARATHON-*.md' -o -name 'MARATHON-*' \) \
  -print | LC_ALL=C sort

Include hand-authored and generated marathon plans plus execution bundle directories. Classify generated HQ rollups, triage reports, examples, snapshots, and docs that merely mention marathons as NOT-EXECUTION-DOC; do not archive them through this workflow.

For each candidate, extract lane IDs from frontmatter (lanes), wave/lane tables, issue links, phase briefs, and bundle YAML. Resolve each lane to its canonical GH-<n>-*.md document when one exists. Report duplicate or contradictory mappings rather than choosing silently.

2. Build an evidence record per lane

Collect these signals without changing state:

Signal	What to verify	Weight
Canonical PDDA doc	Location, terminal frontmatter, exact Status table, acceptance/QA state, explicit remaining work	Primary scope record
Marathon plan or brief	Bounded lane scope, terminal lane result, reviewer verdict, branch/PR/commit references	Scope and execution record
GitHub issue	Open/closed state, close reason, linked PRs, comments that narrow or preserve remaining scope	Corroboration; closed alone is insufficient
Delivery	Merged PR or commit is reachable from the intended target branch; changed paths match the lane	Required for implementation lanes
Verification	Recorded tests/gates passed for the shipped scope; no unresolved failed gate	Required
CHANGELOG	Dated entry names the issue/scope and delivery outcome	Provenance corroboration

Useful read-only probes:

gh issue view <n> --json number,title,state,stateReason,closedAt,url,comments
gh pr list --state all --search '<n>' --json number,title,state,mergedAt,mergeCommit,url
git log --all --decorate --oneline --grep='GH-<n>\|#<n>'
git merge-base --is-ancestor <commit> development
rg -n "GH-<n>|#<n>" CHANGELOG.md PROJECT ROADMAP.md

Use the actual target branch from repo policy or the marathon contract in place of development when they differ. Verify a referenced commit exists before running merge-base.

3. Classify every lane

Assign exactly one result:

Result	Rule	Parent marathon eligible?
VERIFIED-COMPLETE	Entire canonical task scope is terminal, delivered, verified, and consistent	Yes; task doc may move
VERIFIED-MARATHON-SLICE	This marathon's explicitly bounded slice is delivered and verified, while separately stated issue scope remains	Yes; task doc stays active
OPEN	Acceptance work remains or issue/doc says active	No
BLOCKED	Work is parked, failed, awaiting review, unmerged, or gate-failed	No
AMBIGUOUS	Evidence is missing or too weak	No
CONFLICT	Durable sources disagree about completion, target, or scope	No

VERIFIED-COMPLETE requires all of the following:

1. The canonical doc explicitly records the completed outcome and has no in-scope next action.
2. Implementation is merged/reachable on the intended target branch, or a docs/research lane records its required durable artifact.
3. The lane's acceptance criteria and relevant gates have positive verification evidence.
4. GitHub state and CHANGELOG do not contradict the local outcome. An open issue requires an explicit reason; otherwise classify CONFLICT.

Use VERIFIED-MARATHON-SLICE only when the plan defined the slice before or during execution and the canonical doc clearly separates remaining issue work. Do not retroactively narrow scope to make a marathon look complete.

4. Decide task-doc and marathon moves separately

A canonical GH-*.md task doc may move from 2-WORKING to 3-COMPLETED only when its result is VERIFIED-COMPLETE. Before proposing the move, require a PDDA terminal lead word such as Complete, Shipped, Fixed, Closed, Merged, Resolved, or Landed, and reconcile its Status table.

The parent marathon may move only when:

• every lane is VERIFIED-COMPLETE or VERIFIED-MARATHON-SLICE;
• no wave, lane, review, merge, gate, or operator action remains;
• the marathon's own status can truthfully become terminal;
• all sibling bundle files describe the same terminal outcome;
• the destination does not already exist; and
• relative links will remain valid or are included in the proposed edit set.

An open issue does not block a completed marathon slice by itself. It does block moving that issue's canonical task doc unless the entire issue is complete and the open state is being explicitly reconciled.

5. Report before mutation

Return one table per marathon with lane result, canonical doc, GitHub state, delivery proof, verification proof, CHANGELOG proof, contradictions, and proposed action. End with one exact move set, for example:

git mv PROJECT/2-WORKING/GH-123-EXAMPLE.md PROJECT/3-COMPLETED/
git mv PROJECT/2-WORKING/MARATHON-PLAN-YYYY-MM-DD.md PROJECT/3-COMPLETED/

Also list required content edits and ledger updates. Ask for explicit confirmation of that set. If any lane is not eligible, leave the marathon in place and state the smallest evidence or work needed.

6. Apply a confirmed cleanup

After confirmation, execute in this order:

1. Re-check git status, GitHub state, target-branch reachability, and destination absence.
2. Update eligible task docs to terminal frontmatter and an evidence-backed Status row; preserve issue links and outcome detail.
3. Update the marathon plan and every file in its bundle to the verified terminal outcome. Do not leave not yet fired, ready, or an outstanding next action inside 3-COMPLETED.
4. Use git mv for eligible task docs, then the fully complete marathon file or directory.
5. Update ROADMAP pointers and state in place. Keep it a pointer ledger; do not copy execution detail.
6. Add a concise dated CHANGELOG entry naming the verified outcome and moved artifacts.
7. Run utils/pdda/pdda.sh run. Run relevant link or repo validation when links or code changed.
8. Report moves, evidence, validation output, and anything deliberately left active.

If validation fails, do not claim completion. Repair only changes in the confirmed cleanup scope; if the failure is unrelated, report it precisely without altering unrelated user work.