10days
Sweep GitHub issues opened or updated in an age window (default: last 10 days; the window is adjustable, e.g. an 11-14-day slice to avoid overlapping another sweep), evaluate PRS 4-axis ratings (prior
SKILL.mdskills/3-weekly/10days/SKILL.md
GitHub/10days — recent-issue sweep → PRS rating prioritization → marathon → fire
PRS is the Product Release System, the RELEASES ledger (definition).
Turn "what's landed in GitHub in the last N days that's still worth doing" into a fired
marathon, unattended. This is start-marathon's more automated sibling: where
start-marathon stops at a plan and hands it to the operator, /10days carries the
plan through PRS rating evaluation, preflight, branch-cut, and execution in one run — because that is
literally what it was built for (a canned macOS text-replacement snippet that expects
one shot, no back-and-forth).
The canned request, verbatim (moved out of the description to fit the 1024-char loader limit, GH-942): "look through recent GH issues within the last 10 days and check if they are still valid, reproducible, not completed already... add each one to a marathon file, run preflight, cut a new branch and execute on the marathon."
Read this whole file before running anything. The auto-fire behavior below is a named exception to house convention, not an oversight — know why before you invoke it.
Reviewed 2026-07-16 & Refined 2026-09-05 via /consult --models agy and /relay-xyz Codex:
incorporates PRS 4-axis rating system prioritization (GH-108: pri/sev/appeal/effort, calc sum,
and ovr manual overrides), full clone folder isolation per GH-564 and WORKTREE-SAFETY.md,
safe JSON in find-doc.sh, per-issue swarm-preflight.sh invocations, live marathon collision guards,
origin sync verification, and robust multi-lane execution containment.
Guardrails (read first)
- Sandbox off for
ghandgit fetch/git push— everyghcall and preflight run here fails under the Bash sandbox (TLS/keychain). Run with the sandbox disabled. - Auto-fire is intentional here, and only here.
GUIDING-PRINCIPLES.md§8 and thestart-marathonskill both say never auto-fire a marathon — that default stands everywhere else in this repo./10dayswas authorized by the operator (2026-07-16) to override the pause, not the substance: it still requires a clean working tree AND an idle coordination layer before cutting anything (Step 7), still runs every gate, still stops the run cold on a red gate or a git-safety violation, and still prints every command it runs. If any precondition in Step 7 fails, stop and report — do not force through it. - Prioritize via PRS 4-Axis Ratings & Manual Overrides (GH-108).
- The canonical task rating system has four 1–100 axes: pri (priority/queue position), sev (severity/pain if left undone), appeal (attraction/energy), and effort (cheapness/ease — inverted, so 100 = easiest/cheapest, 1 = hardest). Higher is better on every axis.
calc= equal-weighted sum of the four axes (range 4–400). High-scoring issues provide a strong signal to prioritize candidates into earlier marathon waves.ovr(operator override) = manual score on the 4–400 scale. Anovrscore overridescalcarithmetic and represents an explicit operator pin to the front of the queue. Always sort manual overrides ahead of calculated scores when selecting and ordering marathon candidates.
- Execute in a Disposable Full Clone Folder, Not the Primary Checkout (GH-564 & WORKTREE-SAFETY.md).
- Linked worktrees isolate working-tree files but share
.git/config, remotes, refs, hooks, and stashes with their parent clone. Running mutation-heavy gates (validate.sh,test/*.sh) in a linked worktree can contaminate or corrupt the parent clone's.git/configand origin URLs (GH-564). - Always run the marathon and test gate validation in a dedicated disposable full clone folder
(e.g.
~/marathon-clones/10days-YYYY-MM-DD-<repo-slug>or~/marathon-clones/marathon-gh-<umbrella>-<slug>). - Within the marathon, parallel runner subagents may use isolated worktrees (
isolation: "worktree") or disposable sub-clones for independent edits, but the parent repo must remain protected.
- Linked worktrees isolate working-tree files but share
- Never mark an issue "already done" without evidence. A hunch is not evidence. A
merged commit/PR that references the issue number, or an existing capture doc parked
in
PROJECT/3-COMPLETED, is evidence. - Check for a concurrently-running marathon before touching the branch, not just the
current branch name. A dirty tree, a non-empty
.tick/locks/, or a fresh untrackedPROJECT/2-WORKING/MARATHON-*directory all mean something else is mid-flight — cutting a branch or firing on top of that state will collide with it. Step 7 checks all three, not justgit branch --show-current. - Parallel lanes run in isolated worktrees or sub-clones, not on the shared tree. Dispatching
concurrent Agent calls directly against one working tree is a containment violation
(GUIDING-PRINCIPLES.md §3/§4) — two lanes writing at once with no isolation can orphan
each other's commits. Step 7 uses the Agent tool's
isolation: "worktree"or disposable full clones for every parallel lane. - A lane only ever touches its contract's
artifactsallowlist. No lane edits the roadmap ledger beyond the intake row/pointer line this skill itself registers in Step 4. - Auto-drafted preflight contracts are a best-effort guess, not a verified fact —
and the fix for a wrong guess has to land before firing, not in the after-the-fact
report. A wrong
artifactslist makesmarathon-plan.sh's wave/collision map untrustworthy: two lanes it thinks are disjoint could actually touch the same file and race. Step 6.5 adds a cheap deterministic overlap check specifically to catch this before any wave runs concurrently, in addition to the Step 8 report flag.
Preconditions — install once
Claude Code and Antigravity only scan their respective global skill directories, not this repo's
top-level skills/. Run this once from a harness clone:
bash skills/3-weekly/10days/install.sh # symlinks this clone's skills/3-weekly/10days into ~/.claude/skills/ and ~/.gemini/config/skills/
Procedure
0. Resolve harness root, confirm sweep target, and prepare full clone workspace
Resolve the harness root via the locator loop and evaluate its exported environment:
L=""
for candidate in "${XYZ_HARNESS:+$XYZ_HARNESS/skills/1-hourly/relay-xyz/find-harness.sh}" \
"$HOME/.claude/skills/relay-xyz/find-harness.sh" \
"$HOME/.codex/skills/relay-xyz/find-harness.sh" \
"$HOME/.gemini/config/skills/relay-xyz/find-harness.sh" \
"$HOME/.gemini/antigravity/skills/relay-xyz/find-harness.sh" \
"$HOME/.gemini/antigravity-cli/skills/relay-xyz/find-harness.sh" \
"$(git rev-parse --show-toplevel 2>/dev/null)/.claude/skills/relay-xyz/find-harness.sh" \
"$(git rev-parse --show-toplevel 2>/dev/null)/skills/1-hourly/relay-xyz/find-harness.sh"; do
[ -n "$candidate" ] && [ -f "$candidate" ] && { L="$candidate"; break; }
done
[ -n "$L" ] || { echo "relay-xyz: locator not found — install the skill or set XYZ_HARNESS" >&2; exit 1; }
eval "$("$L" --env)"
Reference every harness script below as $HARNESS/utils/… — not bare utils/… paths, which
resolve to nothing (or to an unrelated utils/ directory) in a vendored .xyz/ install.
The two bundled scripts (Steps 1 and 2) ship beside this SKILL.md, so set SKILL_DIR to whatever
directory this file was loaded from — ~/.claude/skills/10days, a clone's skills/3-weekly/10days, or a
vendored .xyz/skills/3-weekly/10days are all valid. Do not assume skills/3-weekly/10days/ relative to the
swept repo; when sweeping a foreign repo that path does not exist:
SKILL_DIR=/absolute/path/to/this/skill/directory # substitute the real one
Confirm the target repository and prepare a verified, collision-free full clone folder (GH-564 & WORKTREE-SAFETY.md):
TARGET_REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)" # repo you intend to sweep
REPO_REMOTE="$(git remote get-url origin)"
REPO_SLUG="$(echo "$TARGET_REPO" | tr '/:' '--')"
SWEEP_DATE="$(date +%Y-%m-%d)"
SWEEP_TS="$(date +%Y%m%d-%H%M%S)"
MARATHON_CLONE="$HOME/marathon-clones/10days-${SWEEP_DATE}-${REPO_SLUG}-${SWEEP_TS}"
CURRENT_TOPLEVEL="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Pre-clone coordination check: assert source repo has clean tree, no active locks, and no untracked plans
SOURCE_STATUS="$(git -C "$CURRENT_TOPLEVEL" status --porcelain 2>/dev/null || true)"
[[ -z "$SOURCE_STATUS" ]] || { echo "Fatal: source repo has uncommitted/dirty state ($SOURCE_STATUS)" >&2; exit 1; }
if [[ -d "$CURRENT_TOPLEVEL/.tick/locks" ]]; then
SOURCE_LOCKS="$(ls "$CURRENT_TOPLEVEL/.tick/locks" 2>/dev/null || true)"
[[ -z "$SOURCE_LOCKS" ]] || { echo "Fatal: source repo has active tick locks in .tick/locks/ ($SOURCE_LOCKS)" >&2; exit 1; }
fi
# Prepare unique dedicated disposable full clone (never reuse/reset an existing dirty workspace):
mkdir -p "$HOME/marathon-clones"
git clone "$REPO_REMOTE" "$MARATHON_CLONE"
cd "$MARATHON_CLONE"
# Unconditional assertion: must be inside verified full clone matching REPO_REMOTE
[[ -d ".git" ]] || { echo "Fatal: workspace is not a full clone root (.git missing or worktree)" >&2; exit 1; }
[[ "$(git config --get remote.origin.url 2>/dev/null)" == "$REPO_REMOTE" ]] || { echo "Fatal: origin URL mismatch" >&2; exit 1; }
# Establish canonical base tracking checkout in the disposable clone before planning:
BASE_BRANCH="${XYZ_BASE_BRANCH:-development}"
git fetch origin "$BASE_BRANCH" --quiet
git checkout "$BASE_BRANCH"
git reset --hard "origin/$BASE_BRANCH"
[[ "$(git rev-list --count HEAD..origin/"$BASE_BRANCH")" -eq 0 ]] || { echo "Fatal: HEAD is behind origin/$BASE_BRANCH" >&2; exit 1; }
Run every subsequent step from the swept repo's root in the full clone.
1. Pull the candidate window (deterministic — no judgment calls)
bash "$SKILL_DIR/scan-issues.sh" [MAX_DAYS] [MIN_DAYS] # default: 10 0 (last 10 days)
MAX_DAYS is how far back the window opens; MIN_DAYS (default 0 = today) is how
close to today it closes. Use the two-argument form to carve out a slice that skips a
range another sweep already owns — e.g. scan-issues.sh 14 11 covers issues 11-14
days old and deliberately excludes the last 10 days.
Emits one JSON object per OPEN issue updated in the window ({number, title, createdAt, updatedAt, url, labels}), sorted by issue number. This is a plain gh issue list
wrapper — it makes no validity/completion judgment, so it is safe to re-run and diff.
2. Cheap local reconcile and PRS ratings lookup
For every issue number from Step 1:
Doc & Bucket Check:
bash "$SKILL_DIR/find-doc.sh" <N>bucket: "3-COMPLETED"→ strong already-done signal. Exclude immediately; note on the "propose closing #<N>" list.bucket: "2-WORKING"withhas_contract: true→ preflight contract exists; route through Step 3 for freshness check.bucket: nullorhas_contract: false→ needs full Step 3 check and contract authoring in Step 4.
PRS Ratings Extraction & Validation (GH-108): Query
releases.db(or capture doc frontmatter) for existing ratings:python3 "$HARNESS/utils/py/releases_app.py" roadmap show <N> 2>/dev/null || true- Validate & Recompute Stored Ratings:
- Verify each axis (
rating_pri,rating_sev,rating_appeal,rating_effort) is an integer in range[1, 100]. - Always recompute
calc = rating_pri + rating_sev + rating_appeal + rating_effort(range[4, 400]) rather than trusting stored sums. - If
rating_ovr(ovr) is present: verify it is an integer in range[4, 400]. If malformed or out of range, invalidate and mark it for clearing (ovr: null,is_manual_override: false).
- Verify each axis (
- Validate & Recompute Stored Ratings:
Gotcha to carry into Step 3: swarm-preflight.sh fix-probes detect the bug, not
the fix (grep_present = bug still there, grep_absent = fix landed). Read a stale
doc's own probe definitions before trusting its verdict — don't assume "has a contract"
means "verdict is current."
3. Validity / reproducibility / completion / PRS evaluation fan-out (subagents)
For every issue that survives Step 2, spawn subagents (batch in groups of ~5-6 concurrent) to answer, with receipts:
gh issue view <N> --json title,body,comments,state,labels,url— read the actual ask, comments, and any operator-posted scores.- Requirement & Blocker Validity Filter: Apply
sanity-checkcriteria. An open issue reporting a failure is not automatically an INCLUDE: if the failure protects an obsolete requirement, was an unsupported-platform experiment, or is low-consequence noise with a clear deferral path, classify it as EXCLUDE (reason: "sanity-check: obsolete or low-risk noise"). - Ledger & PRS cross-check: query
releases.dbfor roadmap items by GH number to extract existing PRS ratings and manual overrides. - Deterministic PRS Scoring Rubric for Unscored or Incomplete Issues (GH-108):
If a candidate has no stored rating, or if stored axis values are partial, non-integer, or out of range
[1, 100](orovris malformed/out of range[4, 400]), assign deterministic integer point values based on observable properties:- pri (queue priority):
90= critical path blocker / front-of-line ask;60= standard backlog task;30= minor/niche improvement. - sev (severity / pain):
90= crash, data corruption, or severe gate blocker;60= functional bug / incorrect output;30= cosmetic / documentation / typo. - appeal (motivation / clarity):
90= clear reproduction steps and unambiguous fix locus;60= clear ask needing modest investigation;30= open-ended or underspecified report. - effort (cheapness / ease — inverted):
90= surgical single-file change ≤ 20 lines;60= moderate multi-file change ≤ 200 lines;30= massive architectural rework > 200 lines. - Compute
calc = pri + sev + appeal + effort(range[4, 400]). Markprovisional: true. - Override Handling & Explicit Clear: If
ovris invalid or absent, clear it by runningroadmap rate --issue-num <N> --rated <P>/<S>/<A>/<E> --force(omitting--ovr), and assert read-back viaroadmap show <N>returnsovr: nullandis_manual_override: false. Setis_manual_override: trueif and only if a valid, verifiedovrin range[4, 400]is present. - Persist newly evaluated ratings to
releases.dbviareleases roadmap rate(see Step 4).
- pri (queue priority):
git log --all --oneline -i --grep="#<N>\b" --grep="GH-<N>\b"— commit evidence.gh pr list --state merged --search "<N> in:body"(and--search "#<N>") — merged PR evidence.- If a capture doc exists (from Step 2), read its own "Status" table and frontmatter.
Return one structured verdict per issue:
{
"issue": N,
"decision": "INCLUDE|EXCLUDE",
"reason": "...",
"evidence": ["commit abc123 fixes this", "..."],
"already_done": false,
"duplicate_of": null,
"needs_contract": true,
"prs": {
"pri": 70,
"sev": 80,
"appeal": 60,
"effort": 75,
"calc": 285,
"ovr": null,
"effective_score": 285,
"is_manual_override": false,
"provisional": true
}
}
Prioritization Rules:
effective_score=ovrif present and valid ([4, 400]), else recomputedcalc(pri + sev + appeal + effort).- Manual override items (
is_manual_override: true) are operator pins: rank them at the very front of the candidate queue regardless of arithmetic. - High calculated scores (
calc >= 250, orsev >= 75/pri >= 75): serve as a strong signal to prioritize the candidate into earlier waves. EXCLUDEwhen: already fixed by commit/PR, duplicate, unreproducible, or not a work item.
Runtime-aware reproducibility (
runtime:*-labeled issues only). If an issue carries aruntime:bashlabel, reproduce it underXYZ_PYTHON=0before ruling it not-reproducible or already-fixed: since the default flipped, a plain repro runs the Python twin, so a Bash-path bug won't surface and would be falselyEXCLUDEd as "already done."runtime:python/runtime:parityreproduce under the default path. These labels exist only inxyz-3-agents-swarm, so this is a silent no-op for any other repo the sweep runs against.
4. Ensure every INCLUDE has a contract-carrying capture doc in 2-WORKING
The acceptance criteria are COPIED, never restated (GH-400). Everything downstream — preflight, the packet, the relay file, the builder, the reviewer — reads this doc; the issue text reaches none of them. So the moment you summarise the acceptance block, your summary is the contract and no role left in the pipeline can compare it to anything. Measured case:
rebalance-OS#202 required a malformed row be "proven to be either reconciled or surfaced, never silently dropped"; the capture doc this step wrote asked instead to assert "the actual current behavior (drop the row)"; two independent marathon runs then delivered a test namedmalformed_source_row_is_dropped, and every gate reported success. Summarise the background as much as you like. Reproduce the## Acceptanceblock byte-for-byte (re-wrapping to ~80 columns is fine — nothing else is).swarm-preflightnow re-fetches the issue and refuses to emit a packet on unexplained divergence, so a restatement here does not merely risk a wrong build, it hard-fails the lane at Step 6.
For each INCLUDE verdict:
Doc already exists (1-INBOX or 2-WORKING): move it to
2-WORKINGif it isn't there yet; add a## Swarm Preflight Contractblock ifhas_contractwas false. Update frontmatter with PRS ratings and override fields if newly evaluated. If it has no## Acceptancesection and the issue does, add one — copied verbatim.No doc exists: author
PROJECT/2-WORKING/GH-<N>-<slug>.mdusing this repo's standard capture-doc frontmatter (gh_issue,source,title,status,created,updated,owner,doc_type,rating(GH-108:"pri/sev/appeal/effort <pri>/<sev>/<appeal>/<effort> · calc <calc>"),rating_ovr(nullable integer4–400),is_manual_override(true|false),ratings_provisional: true,goal), wheresourceis the full tracking-issue URL so a reader can diff the doc against the issue it claims to implement in one step. Give it an## Acceptancesection copied verbatim from the issue's, plus a best-effort contract:## Swarm Preflight Contract ```json { "target": { "repo": ".", "ref": "development" }, "gate": "bash validate.sh", "fix_probes": [ /* inferred from the issue body — grep for the bug it describes */ ], "artifacts": [ /* files the issue names, or the subagent identified as the touch surface */ ], "remediation": { "source": "issue#<N>", "criteria": "<one-line SUMMARY for ranking — NOT the definition of done; that is the verbatim ## Acceptance block>" }, "lanes": { "agy_safe": [], "orchestrator_only": [ /* kernel/.tick paths, if any */ ] } }**Persist ratings to releases.db**: ```bash python3 "$HARNESS/utils/py/releases_app.py" roadmap rate --issue-num <N> \ --rated <P>/<S>/<A>/<E> [--ovr <O>] [--force]**`source:` is always the tracking issue (GH-425).** It must name this repository and the `gh_issue` number, not merely an issue with the same number in another repository. When an issue originated elsewhere, retain that URL under the established free-text `related:` field instead; do not delete it or put it in `source:`. For example: ```yaml gh_issue: 94 source: https://github.com/Acme/tracking-repo/issues/94 related: - "https://github.com/Upstream/origin-repo/issues/2 — originating issue"Preflight validates
source:against the target repository and tracking issue.related:remains context rather than a new linted schema: it preserves the cross-repo provenance while keeping the gate's tracking-issue check deterministic.For a
runtime:bash-labeled issue, set the gate to"XYZ_PYTHON=0 bash validate.sh"so the lane verifies against the Bash path the bug actually lives on, not the Python default (again, a no-op outsidexyz-3-agents-swarm, where the label is absent).Mark it explicitly in the doc body: "Contract auto-drafted by /10days from the issue text — artifacts/lanes not yet operator-verified." This is the one place this skill guesses; the report in Step 8 must surface every auto-drafted contract by name.
When a criterion genuinely cannot be carried as written — unreachable in this repo, superseded by later work, or deliberately split across lanes — do not quietly rewrite the list. Keep the issue's wording and record the delta in a section preflight can check:
## Acceptance — deviations from the issue - [dropped] <verbatim issue criterion> — reason: <why> - [changed] <verbatim issue criterion> -> <replacement> — reason: <why> - [added] <new criterion> — reason: <why>Each entry needs a real
— reason:, and the entries must reconcile the two lists exactly: an entry naming a criterion that is not actually different is rejected, so the section cannot become a rubber stamp. This is the only supported way to diverge; there is no env-var bypass, because a deviation should live in the doc where the next reader finds it.Audit the guess like
start-marathondoes: do the declaredartifactspaths actually exist (or, for a new file, does the issue actually call for creating one at that path)? Does the set plausibly match the issue's real subject, not a generic or copy-pasted guess? A contract that fails this sniff test is a placeholder — its collision map can't be trusted at all; drop that issue back toneeds_contractand exclude it from this run rather than firing on an untrustworthy guess.Park intake via
python3 "$HARNESS/utils/py/releases_app.py" roadmap add(the canonical roadmap ledger since GH-169/GH-269; for legacy repos using ROADMAP.md, append a pointer line) so$HARNESS/utils/marathon-plan.shdiscovers it in Step 5.
5. Build and rank the marathon file
"$HARNESS/utils/marathon-plan.sh" --deep
--deep delegates to $HARNESS/utils/swarm-preflight.sh --dry-run per ready item for an
authoritative freshness verdict while ranking (slower, needs network — that's fine,
gh/network access is already required by this point). Writes
PROJECT/2-WORKING/MARATHON-PLAN-<today>.md — this is "the marathon file" the
operator's snippet refers to. Read its Held/Flagged section: anything held here drops
out of the fire list in Step 6, with the reason already stated by the planner.
marathon-plan.sh ranks the ENTIRE ROADMAP ledger, not just this sweep's issues —
filter its waves down to this run's candidate set and order by effective PRS score before treating anything as fireable:
- Intersect the plan's assigned items with this sweep's
INCLUDEset. Drop unrelated or unselected issues. - Order surviving issues by effective PRS score:
- Manual overrides (
ovr) first — operator front-of-line pins supersede calculated arithmetic. - Highest
calcsums (pri + sev + appeal + effort) next. - Secondary tiebreakers: highest
sev(severity), then highestpri(priority).
- Manual overrides (
- Respect the planner's zone constraints (kernel ≤ 1 per wave) and wave serialization, slotting the highest-scored candidates into the earliest available wave slots.
6. Preflight the fire list — one issue per invocation
for N in <surviving issue numbers>; do
"$HARNESS/utils/swarm-preflight.sh" --gh-issue "$N"
done
Run it once per issue, never bundled (--gh-issue N --gh-issue M in one call is a
different feature — merge-contracts.mjs folds every listed issue into one packet, so
a single invalid contract fails the entire bundle and stops filtering per-issue; that
is not what this step needs). No --dry-run — this run is going to fire, so let it
write the real packet, one per issue. Read the verdict per exit code: 0 ready · 3
contract missing/invalid · 4 stale/already landed (drop it, propose closing the GH
issue — the fix shipped without this run knowing) · 5 not marathon-ready · 6
blocked/missing-target · 7 ambiguous. Only exit-0 issues carry into Step 6.5. Every
non-zero drop gets one line in the Step 8 report with its exit code and reason — never
silently disappear an issue from the count.
An exit 5 reading acceptance criteria diverge from issue #N is your own Step 4 output being
rejected (GH-400), not a defect in the issue. Preflight re-fetched the issue and found the doc's
## Acceptance block says something the issue does not. Fix it by going back to the doc and copying
the issue's block verbatim — or, if the difference is deliberate, by declaring it under
## Acceptance — deviations from the issue as Step 4 specifies. Do not work around it by
deleting the doc's acceptance section (a doc with none, against an issue that has one, is refused
too) and do not drop the issue from the run on these grounds. The check reports unknown and does
not block when it simply cannot see the issue (no gh, unauthenticated, offline, or an issue with
no ## Acceptance section), so a green run offline is not evidence the criteria were verified —
the packet says which of the two it was.
6.5. Cross-issue artifact-overlap check — before any wave runs concurrently
marathon-plan.sh already groups exit-0 issues into waves by disjoint artifacts
sets. That grouping is only as trustworthy as the contracts feeding it, and Step 4 can
include auto-drafted ones. Before accepting a wave's concurrency as safe:
- Diff every pair of lanes slotted into the same wave: do their
artifactslists literally intersect (a bug in the planner or the contract) or does either lane's underlying issue body/title mention a file path that appears in the other lane'sartifacts? Either signal is enough. - Any lane pair with a hit — serialize them: move one to the next wave regardless of what the planner computed. This costs wall-clock time, not correctness; the planner's wave grouping is an optimization, not a safety guarantee, once an auto-drafted contract is in the mix.
- Log every serialization decision so Step 8 can report it — a silently-reordered wave is still a surprise the operator should see.
7. Cut the branch, commit planning artifacts, and execute — no pause (see Guardrails)
Preconditions & Collision Predicates — verify inside the dedicated full clone workspace:
BASE_BRANCH="${XYZ_BASE_BRANCH:-development}"
# 1. Assert not already on a marathon/* branch
CURRENT_BRANCH="$(git branch --show-current)"
[[ "$CURRENT_BRANCH" != marathon/* ]] || { echo "Fatal: already on a marathon branch ($CURRENT_BRANCH)" >&2; exit 1; }
# 2. Assert no active tick locks / claims
ACTIVE_LOCKS="$(ls .tick/locks/ 2>/dev/null || true)"
[[ -z "$ACTIVE_LOCKS" ]] || { echo "Fatal: active tick locks found in .tick/locks/" >&2; exit 1; }
# 3. Assert no foreign untracked marathon plan in PROJECT/2-WORKING
FOREIGN_UNTRACKED_PLANS="$(git status --porcelain --untracked-files=all -- PROJECT/2-WORKING 2>/dev/null | grep -E '^\?\?[[:space:]]+PROJECT/2-WORKING/MARATHON-' | grep -v "MARATHON-PLAN-${SWEEP_DATE}.md" || true)"
[[ -z "$FOREIGN_UNTRACKED_PLANS" ]] || { echo "Fatal: foreign untracked marathon plan found: $FOREIGN_UNTRACKED_PLANS" >&2; exit 1; }
If any check fails, stop and report which one, and do not touch the branch.
Then:
- Branch Cut & Planning Artifact Commit:
- Cut branch from canonical base:
BRANCH_NAME="${packet_suggested_branch:-marathon/10days-${SWEEP_DATE}}" && git checkout -b "$BRANCH_NAME". - Stage and commit the deliberate intake capture docs (including any
1-INBOXmoves), marathon plan, and updated roadmap ledger:git add -A -- PROJECT/1-INBOX PROJECT/2-WORKING releases.db releases.sql if [[ -f "ROADMAP.md" ]]; then git add ROADMAP.md; fi git commit -m "chore(marathon): initialize 10days marathon plan and roadmap ledger for ${SWEEP_DATE}" - Assert clean working tree before dispatching lane agents:
[[ -z "$(git status --porcelain)" ]] || { echo "Fatal: uncommitted state remaining after plan commit" >&2; exit 1; } - Ensure the final PR targets
$BASE_BRANCH(development), nevermain.
- Cut branch from canonical base:
- Execute per the proven Marathon execution pattern (GH-221 builder/orchestrator split):
- Claude Code is the orchestrator and reviewer, not a default builder. It plans waves, dispatches builder lanes, and verifies emitted artifacts / test gates.
- Agy CLI and Codex CLI are the default headless builders (
--builder agy/--builder codex, subscription-billed / cost-blind). - Claude CLI is NOT a builder by default — use a headless Claude CLI builder only with explicit user confirmation/cost acknowledgement.
- Walk the MARATHON-PLAN doc's waves in order, respecting any Step 6.5 serialization:
- Within a wave, dispatch one builder turn per lane with
isolation: "worktree"(or in dedicated disposable sub-clones beneath the full clone) to prevent concurrent lanes from writing over each other. Respect zone caps (kernel ≤ 1 per wave). - Each lane agent writes only inside its contract's
artifactsallowlist.
- Within a wave, dispatch one builder turn per lane with
- After all of a wave's lane agents return, before merging any lane's worktree
commit(s), verify that lane's worktree base against the marathon branch's start
commit:
git merge-base --is-ancestor <marathon-branch-start-sha> <lane-worktree-HEAD>. Confirmed live 2026-07-17 (GH-225):isolation:"worktree"lanes can silently branch from a stale historical commit instead of the marathon branch — do not assume the ancestry check will pass. If it passes, fast-forward/merge as normal. If it fails, the worktree is based on a stale/unrelated point — cherry-pick the lane's specific new commit(s) onto the marathon branch instead; nevergit mergethe isolation branch wholesale in that case, or it silently reintroduces every already-superseded file state between the stale base and the marathon branch tip. Merge/cherry-pick each lane one at a time (not concurrently) so the branch ref never has two writers racing it. - Once a lane's commit(s) are merged, remove its worktree:
git worktree remove <path>(fall back togit worktree remove --force <path>if it still reports uncommitted/stray state). Do this for every lane in the wave, right alongside the gate check below — left as-is, a run with several parallel lanes accumulates orphaned worktree directories under the repo's git metadata across sessions. A removal failure does not stop the run: record the lane, path, and error for the Step 8 report and continue. - After a wave's merges land, run its gate (the contract's
gate, defaultbash validate.sh) before starting the next wave. Running this gate inside the full clone folder ensures tests cannot contaminate the primary repo (GH-564). A red gate stops the run — do not advance to the next wave, do not force-merge, report it in Step 8 and leave the branch as-is for the operator to inspect.
- Commit per lane/wave with a message referencing the GH issue number(s) it closes.
8. Report
One final summary, always — even (especially) on a partial or stopped run:
- Scan Window & Intake Counts: N days scanned, total open issues reviewed.
- PRS Ratings & Prioritization Table:
- Issue number, title, 4-axis ratings (
pri/sev/appeal/effort),calcsum,ovroverride, effective score, and ranking verdict. - Explicitly highlight any manual overrides (
ovr) and high-scoring quick wins.
- Issue number, title, 4-axis ratings (
- Exclusion Ledger: items excluded with reasons (already-done / duplicate / not reproducible / not-a-work-item / held-by-preflight / held-by-planner).
- Execution Ledger:
- Included and fired issues, with their issue numbers, branch, and final commit(s).
- Full clone folder path used for execution.
- Every auto-drafted contract, named individually, flagged for operator review.
- Every Step 6.5 serialization — which lane pairs were pulled out of a concurrent wave and why, so a wave that ran slower than expected isn't a mystery.
- Every gate result per wave (green/red) and, if red, exactly where the run stopped.
- Every worktree-cleanup failure — lane, worktree path, and the
git worktree removeerror — if any lane's worktree failed to remove after its merge. Never silently ignore a leftover worktree; if none failed, say so explicitly (all worktrees removed cleanly). - Branch name, and whether it's ready for a PR or still mid-marathon.
Never mask a stopped run as a finished one — an honest partial report is the point of this whole skill (GUIDING-PRINCIPLES.md §8: the operator decides, but only if they know what actually happened).
Bundled deterministic scripts
scan-issues.sh— Step 1, the GH window pull. No judgment calls.find-doc.sh— Step 2, the capture-doc lookup for one issue number. No judgment calls.
Both exist so the mechanical parts of this sweep run byte-identical every time instead
of being re-typed as ad hoc gh/ls/grep one-liners each invocation.