write-code

name

write-code

description

Pick the next actionable issue off the configured target repo and execute it end to end — claim it by self-assigning, implement on a branch, open a PR that closes it, log progress on the issue, and hand off to the parent epic; OR, given a PR number, enter repair mode and consume a gate's latest FAIL verdict to fix-and-resubmit on the same branch. Trigger on "work the next issue", "pick up an issue", "implement issue

write-code

You are the executor. The backlog has already been triaged (triage) and any epic has been planned into children with a dependency topology (plan-epic). Your job is to take the next actionable issue, claim it, build it, and open a PR that closes it — leaving a trail (progress comments, an epic handoff note) so the next agent picks up cold without spelunking your head.

You operate autonomously. You don't propose-first or wait for sign-off on the pick — triage already decided this work is worth doing and plan-epic already sequenced it. Pick, claim, implement, hand off. The one gate downstream is review-code, which verifies your PR against the issue's acceptance criteria before it merges; your job is to make that verification pass, not to merge on your own authority.

You are the implementer, never the reviewer of your own diff (the split-role firewall). The whole point of the pipeline is split-role review — implementer ≠ reviewer — so the self-evaluation bias of grading your own work never enters the merge decision. That guard lives in who runs the gate, and it is structural, not advisory: write-code never invokes review-code/review-doc/review-skill on the PR it just opened or repaired, and never posts a review-(code|doc|skill): PASS/FAIL marker on its own output. The gate is run by a separate reviewer agent; you hard-stop at PR-open (initial mode) and after resubmit (repair mode) and leave the verdict to them. Re-reading your own diff to self-check before you push is fine — what's forbidden is stepping into the gate role: running a review skill on your PR, or emitting a verdict marker. Repair mode's loop is sound for the same reason — you fix, an independent re-review re-gates; you never write the PASS (see Why the author may fix its own FAIL'd PR). This invariant is the skill's own rule, enforced here — it does not rely on a per-spawn hand-off instruction (which agents demonstrably ignored, walking themselves into the gate on their own PR — #664).

All GitHub ops via gh api REST — never GraphQL

Every issue/PR/label read and write goes through gh api — the org's legacy Projects-classic integration errors out GraphQL issue queries, so this is a hard constraint, not a style call (branch/commit/PR-open use git/gh per repo conventions). Resolve the target repo once, up front (this skill is repo-agnostic — every call targets $REPO); the full resolution rule is the shared contract's Target repo resolution (../gh-issue-intake-formats.md, ADR 0062 §1), defaulting to kamp-us/phoenix with no config.

REPO="${CLAUDE_PIPELINE_REPO:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"

The formats contract

You read three and write two of the shared formats; read the contract before you start: ../gh-issue-intake-formats.md.

• ## Dependencies grammar (format 1) — you read it off a parent epic to derive whether a sub-issue is eligible (phase predecessors closed + every requires: #N closed). Blockedness is derived from this section, never a label.
• Sub-issue body (format 2) — you read it as your spec: ### What to build is what to do, ### Acceptance criteria is the contract review-code will verify, the **TDD:** flag is advice on whether to go test-first.
• Progress comment (format 3) — you write these on the issue you're working: Completed / Decisions / Gotchas / Next.
• Epic handoff note (format 4) — you write one on the parent epic when you finish a sub-issue: Done / Affects siblings / Watch out.

Read tolerantly (the formats are conventions, not parser specs — a synonym or a slightly different bullet style still means what it means), write canonically.

The glossary — read .glossary/, use the canonical terms

Before you draft a PR title/body, a progress comment, an epic handoff, or any identifier you introduce, read the repo-owned vocabulary register and reach for its names rather than inventing your own (the one-concept-named-four-ways drift, #851; ADR 0099): .glossary/TERMS.md (domain nouns) and .glossary/LANGUAGE.md (architecture vocabulary) — the single source; never copy a definition into this skill.

---

Invocation — two modes, disambiguated by what you're given

write-code has two invocation shapes, and the argument tells them apart:

• A PR number → repair mode. "Repair PR #N" / "fix the failed review on #N" hands you an existing PR. Go to Repair mode: resolve the PR's latest gate verdict, and only if that latest verdict is FAIL, read the findings, fix them on the existing branch, push so the stateless gate re-runs, and stop. You do not pick new work, you do not branch, you do not merge.
• An issue number, or no argument → initial-build mode. "Implement #N" / "work the next issue" runs the normal pick → claim → Steps 4–7 path below. This is unchanged.

The two are unambiguous: a PR number routes to repair, an issue number (or nothing) routes to the pick-and-build path. If you're handed a bare number and genuinely can't tell which it is, resolve it once — gh api repos/$REPO/pulls/<N> succeeds for a PR and 404s for a plain issue — and branch accordingly.

The ownership boundary, stated once and load-bearing throughout: write-code owns fail → fix → re-request; ship-it owns PASS → merge. You own the branch and the PR, so driving a FAIL'd PR back through the gate is your loop — but the merge is never yours, in either mode (this mirrors the gh-issue-intake-formats.md §5/§6/§6.5 relationship table, which names write-code the consumer of all three FAIL markers and ship-it the consumer of all three PASS markers).

A rebase invalidates the PASS — rebase → re-review → ship is atomic

Whenever a PR head moves after it was reviewed — most often a rebase to catch up to main, but any force-push — the prior review-code/review-doc/review-skill PASS is bound to the old head and is staleness-invalidated (ADR 0058): the verdict attests the exact tree it reviewed, and the rebased head is, in principle, un-reviewed. ship-it will then correctly refuse with unverified (verdict not bound to current head) (its Step 2b). That refusal is the system working, not a stall — never weaken the SHA-binding to route around it, and never wait on a human for it.

So a rebase is never the last step before ship. Rebase → re-review → ship is one atomic sequence: after you rebase (or force-push) a PR, the new head needs a fresh review against that head before ship-it can act — re-run the matching gate (review-code for code, review-doc for docs, review-skill for skills) against the new head, and only once its latest verdict is a current-head PASS hand off to ship-it. Never ship on a pre-rebase PASS — the rebase invalidated it the moment it landed, so "ship on the existing PASS after a rebase" is self-contradictory.

The pattern that never hits this: review the exact head you ship. A flow that reviews and ships in one pass over a single head never orphans its verdict; the split review-then-rebase-then-ship flow is the only one that does, and the fresh re-review is what re-binds the verdict to the head being merged (#310).

---

Step 1 — Pick the next issue

The pick rule is deterministic. Among open issues that are status:triaged and unassigned:

1. Highest priority bucket first: all p0 before any p1, all p1 before any p2.
2. Milestone tiebreaker within a bucket: among equal-priority candidates, prefer one in the active milestone — never across buckets.
3. Oldest first otherwise: lowest issue number / earliest created_at.

The priority spine is sovereign — p0 outranks any milestone lean. Milestone only reorders within a single priority bucket; it never reaches across one. A p0 outside the active milestone is therefore always picked before a lower-priority issue inside it — the campaign bias is a tiebreaker, not a new top-level sort key. See Milestone-aware ordering for the full rule, including the explicit work milestone N mode and why p0-sovereignty holds in both modes.

Assigned issues are someone else's claim — skip them. Skip on any non-null assignee, not on an exact match: under the Step 3 claim race an issue may transiently show two co-assignees for the window before the winner evicts the loser, and skipping any assigned issue keeps that transient state safe — a half-resolved claim is never double-picked, it's simply passed over until it settles to its single winner. status:needs-triage, status:needs-info, and closed issues are not pickable (they haven't cleared triage).

Pre-pick exception — resume your own failed PR first

The "skip assigned issues" rule has exactly one exception: a PR you opened that came back FAIL. Its Fixes #N issue is still assigned to you (review-code/review-doc/review-skill leave it open and assigned on a FAIL), which would make it unpickable by the rule above — but that arc is yours to drive forward, not skip. So before picking new status:triaged work, scan your own open PRs for one whose latest gate verdict (in any of the three namespaces) is an unaddressed FAIL:

ME=$(gh api user --jq '.login')
# resolve the verdict CLI once via the `bin/pipeline-cli` shim — in-repo bin, else the installed
# bin, else the pinned `pnpm dlx` fallback reading the one pin (hooks/pin.sh); no version pinned
# here (#3653; ADR 0062/0064; epic #994). Each per-(PR, gate) FAIL-bound-to-head resolution below
# delegates to `pipeline-cli verdict read` (ACL author-gate + latest-wins + SHA-staleness, ADR
# 0055/0058; its unit tests are the contract).
VERDICT="${CLAUDE_PLUGIN_ROOT:-claude-plugins/kampus-pipeline}/bin/pipeline-cli verdict"
# open PRs you authored; print each one whose latest verdict in EITHER namespace is FAIL,
# UNLESS it has already hit the N=3 repair cap (then it's a human's, not yours to re-pick)
gh api "repos/$REPO/pulls?state=open&per_page=100" \
  --jq ".[] | select(.user.login==\"$ME\") | .number" | while read PR; do
  # The N=3 FAIL-round count is the one thing `verdict read` does NOT do (it resolves the latest
  # verdict, it does not count rounds) — genuinely more than a single (PR, gate) resolution, so it
  # stays inline. Author-gate the FAIL markers to write+ collaborators (ADR 0055, supersedes 0051)
  # so a forged review-(code|doc|skill): FAIL can't inflate the count; an empty authorized set counts
  # zero rounds — fail-closed. Cluster by timestamp gap (>120s = new round), per fix-round not per
  # marker (a both-namespace round counts once), the same identity the Bounding count uses.
  comments_file=$(mktemp)
  gh api "repos/$REPO/issues/$PR/comments?per_page=100" > "$comments_file"
  markerAuthors=$(jq -r '[.[]
      | select(.body | test("^\\s*\\**\\s*review-(code|doc|skill):\\s*(PASS|FAIL)"; "i"))
      | .user.login] | unique | .[]' "$comments_file")
  authorized='[]'
  while IFS= read -r a; do
    [ -z "$a" ] && continue
    perm=$(gh api "repos/$REPO/collaborators/$a/permission" --jq .permission 2>/dev/null)
    case "$perm" in
      admin|maintain|write) authorized=$(jq -c --arg a "$a" '. + [$a]' <<<"$authorized") ;;
    esac
  done <<<"$markerAuthors"
  ROUNDS=$(jq --argjson authorized "$authorized" \
    '[.[] | select(.user.login | IN($authorized[]))
          | select(.body | test("^\\s*\\**\\s*review-(code|doc|skill):\\s*FAIL"; "i"))
          | .created_at | sub("\\..*Z$";"Z") | fromdateiso8601]
     | sort
     | reduce .[] as $t ({n:0, prev:null};
         if (.prev == null) or ($t - .prev) > 120
         then {n:(.n+1), prev:$t} else {n:.n, prev:$t} end)
     | .n' "$comments_file")
  [ "$ROUNDS" -ge 3 ] && continue   # at the cap → already escalated to a human, excluded from the scan
  # resolve each namespace's latest current-head verdict through the shared verb — exit 0 iff HEAD
  # carries a current FAIL in that gate (a stale / SHA-less / PASS / none verdict exits non-zero).
  $VERDICT read --pr "$PR" --gate code  --expect FAIL >/dev/null 2>&1 && echo "#$PR review-code FAIL"
  $VERDICT read --pr "$PR" --gate doc   --expect FAIL >/dev/null 2>&1 && echo "#$PR review-doc FAIL"
  $VERDICT read --pr "$PR" --gate skill --expect FAIL >/dev/null 2>&1 && echo "#$PR review-skill FAIL"
done

If such a PR exists, repair it instead of picking new work — go to Repair mode with that PR number. Only once you have no PR with an unaddressed latest FAIL do you fall through to the normal pick below. (This scan resolves each (PR, gate) verdict through the same authoritative SHA-bound pipeline-cli verdict read repair mode Step R1 uses; R1 still re-resolves at repair time because the head may move between this scan and the repair — a PR that flipped to PASS, or whose FAIL went stale in that window, is then a clean no-op.)

Two properties make this scan terminate rather than starve:

• Author-gated verdicts (ADR 0055). Markers count as a verdict only from a write+ repo collaborator — the same GitHub-ACL gate ship-it Step 2 applies before the marker regex. A self-authored or forged review-(code|doc|skill): FAIL is invisible here, so write-code can't pull itself into spurious repair (and a forged PASS can't mask a real FAIL).
• Cap exclusion. A PR already at the N=3 cap is skipped (ROUNDS >= 3 → continue): escalation hands it to a human but leaves its latest verdict at FAIL, so without this skip the scan would re-match it forever — re-enter repair, recount 3 FAILs, re-escalate — and never advance to fresh work. Excluding capped PRs lets the picker step over the escalated PR and pick new status:triaged work.

List the candidate pool, priority bucket by priority bucket, stopping at the first bucket that has any unassigned candidate:

# p0 first; only fall through to p1, then p2 if a bucket is empty of unassigned issues
for P in p0 p1 p2; do
  gh api "repos/$REPO/issues?state=open&labels=status:triaged,$P&sort=created&direction=asc&per_page=100" \
    --jq '.[] | select(.assignee == null and (.pull_request | not)) | "#\(.number)\t\(.created_at)\t\(.title)"'
done

(.pull_request | not) filters out PRs (the issues endpoint returns both). Take the first unassigned issue in the highest non-empty bucket — applying the milestone tiebreaker below when several issues share that bucket. That's your pick — unless it's a sub-issue, in which case run the eligibility check in Step 2 first.

Milestone-aware ordering

Milestone is the optional fourth intake dimension — strategic sequencing / campaign grouping, not feature breakdown — defined once in the formats contract's ## Milestone section (the single source of truth; read it for what a milestone is and its REST surface — ADR 0072). write-code is the consumer named there: milestone influences pick-order only, and only as a tiebreaker that respects the priority spine — it never gates, never blocks a merge, and never changes which issues are pickable.

The precedence rule (p0 stays sovereign — state this, never weaken it). A milestone preference orders candidates strictly within a single priority bucket and never across buckets. The priority spine — all p0 before any p1, all p1 before any p2 — is the top-level sort and is never overridden by a campaign lean. Concretely: a p0 outside the active milestone is always picked before any lower-priority issue inside it. A milestone bias that could starve an out-of-milestone p0 is a bug, not a feature; the within-bucket confinement is what makes the campaign lean safe. This precedence holds in both modes below — never reintroduce a milestone-over-priority sort.

Milestone shapes the pick in two modes:

• Default mode — within-bucket tiebreaker. With no milestone named, run the normal priority-then-age pick, but when a single priority bucket holds several unassigned candidates, break the tie toward the active milestone: prefer the in-milestone candidate over an equal-priority out-of-milestone one; fall back to oldest-first when the milestone dimension doesn't separate them (both in, both out, or no active milestone). The "active milestone" is resolved from a single durable surface, not a per-run guess: it is the arc pinned by the one active row of ROADMAP.md's ## Arcs table (the founder-voice roadmap projects each arc onto a GitHub milestone; exactly one arc is active at a time — ADR 0078). An operator's explicit work milestone N still overrides it (the mode below). When no ## Arcs row is marked active, there is no active milestone and this degrades cleanly to plain oldest-first. Because the tiebreaker lives inside a bucket, it can only reorder equal-priority issues — it can never pull a lower-priority in-milestone issue ahead of a higher-priority one.

• Explicit work milestone N mode — drain that milestone. When invoked as "work milestone N" (or "drain milestone N"), scope the pool to that milestone via the REST filter and pick from it by the same priority-then-age order:

  # explicit milestone drain: same priority spine, scoped to milestone N (REST, never GraphQL)
  for P in p0 p1 p2; do
    gh api "repos/$REPO/issues?state=open&milestone=$N&labels=status:triaged,$P&sort=created&direction=asc&per_page=100" \
      --jq '.[] | select(.assignee == null and (.pull_request | not)) | "#\(.number)\t\(.created_at)\t\(.title)"'
  done
  

  Even here the priority spine wins inside the milestone (p0s in the milestone before its p1s), and the explicit scope is the operator's choice — naming milestone N is a deliberate decision to work that campaign, so confining the pool to it is intentional, not starvation. If you must guarantee no global p0 is left behind while draining a campaign, run the default unscoped pick first; the explicit mode is for when the operator has chosen to focus N.

In both modes the pickability predicate is unchanged — milestone only orders among issues that are already pickable (status:triaged + unassigned, sub-issue eligibility per Step 2). Read an issue's milestone with gh api repos/$REPO/issues/<N> --jq '.milestone.number // "none"' (none ⇒ the well-formed default — most issues carry no milestone) per the contract's REST surface.

Is it a sub-issue?

An issue may be a child of an epic. Check before claiming — a sub-issue carries dependency constraints the bare issue doesn't show.

Resolve the parent through GET /repos/{owner}/{repo}/issues/<N>/parent, the dedicated sub-endpoint ADR 0131 §3 already names the authoritative linkage — and read three outcomes off it, never two:

# `-i` keeps the status line on stdout even when gh exits non-zero, which is the whole point:
# it is what distinguishes a genuine 404 ("No parent issue found" ⇒ standalone) from an
# UNREADABLE response (5xx, rate-limit, auth, network ⇒ UNKNOWN). Collapsing those two into
# "no parent" is a silent no-op that skips Step 2 on a real epic child (#4171, #3715, #4108).
PARENT_RESP="$(gh api "repos/$REPO/issues/<N>/parent" -i 2>/dev/null)"
PARENT_STATUS="$(printf '%s\n' "$PARENT_RESP" | head -n1 | awk '{print $2}')"
case "$PARENT_STATUS" in
  200)
    EPIC="$(printf '%s\n' "$PARENT_RESP" | awk 'body{print} /^\r?$/{body=1}' | jq -r '.number // empty')"
    : "${EPIC:?parent read returned 200 with no .number — UNKNOWN, not standalone; refusing to claim <N>}"
    echo "#<N> is a sub-issue of epic #$EPIC → Step 2 (derive eligibility BEFORE claiming)" ;;
  404)
    echo "#<N> is standalone (404 'No parent issue found') → Step 3 (claim it)" ;;
  *)
    echo "write-code FAILED (fail-closed): parent read on #<N> returned HTTP '${PARENT_STATUS:-none}' — UNKNOWN, which is NOT evidence of 'no parent'. Refusing to claim: retry, or re-pick per Step 1." >&2
    exit 1 ;;
esac

• Parent resolved (200) → go to Step 2 and derive eligibility before claiming.
• Standalone (404) → skip to Step 3.
• Anything else → stop, loudly. An unreadable parent read is unknown, not absent; proceeding would claim a child whose dependencies were never checked.

Never read .parent off the plain issue payload. The single-issue REST response carries no parent key at all (the linkage surfaces there as parent_issue_url), so the read this step used to carry — a --jq on .parent with a "no parent (standalone)" jq-alternative default — fired its default unconditionally and answered "standalone" for every issue: a well-formed, plausible, always-wrong answer that skipped the whole Step 2 derivation on every epic child and left no trace (#4171). ADR 0131 §3 states the same thing from the other side: the child's own .parent field is unreliable, the sub-endpoint is the source of truth.

---

Step 2 — Sub-issue eligibility (derive blockedness, never read a label)

For a sub-issue, read the parent epic first — its plan, its ## Dependencies topology, and its progress (the handoff-note comment stream). A child is only pickable when its dependencies are all closed. There is no status:blocked label; eligibility is computed fresh on every pick from the epic's ## Dependencies section.

EPIC=<the parent number Step 1's sub-endpoint read resolved — never a guessed or remembered one>
# the epic body carries the plan + the ## Dependencies topology
gh api repos/$REPO/issues/$EPIC --jq '.body'
# the real child set + each child's state (the list endpoint is source of truth;
# sub_issues_summary undercounts under mixed closed/open children)
gh api "repos/$REPO/issues/$EPIC/sub_issues?per_page=100" \
  --jq '.[] | "#\(.number) [\(.state)] \(.title)"'
# the cross-task signal siblings left — read before assuming what's done
gh api "repos/$REPO/issues/$EPIC/comments?per_page=100" --jq '.[].body'

The derivation rule (from the formats ## Dependencies grammar):

A child #C is unblocked iff:

• Phase predecessors closed: every issue in every phase before #C's phase is closed. (Phases are the sequential spine — Phase 2 can't start until all of Phase 1 is closed.) A child within a phase has no ordering against its phase-siblings.
• requires: closed: every issue named in #C's requires: #N, #M … annotation is closed. This is the cross-boundary gate for a dependency that doesn't fall on a phase line.

Both conditions must hold. If either fails — a phase predecessor is open, or a requires: target is open — the child is blocked: skip it and fall back to the next pickable issue (the next unassigned status:triaged issue in priority/age order, re-running Step 1 with this child excluded). Do not apply a label, do not comment "blocked" — blockedness is a derived, transient fact, not a stored state. The child becomes pickable the moment its blocker closes; on the next pick the recomputation will let it through.

Worked: epic with ### Phase 1: #210, #211 and ### Phase 2: #212 (requires: #210). If you're eyeing #212: it needs #210 closed (its requires:). It does not need #211 — #211 is a phase-1 sibling but #212 only gated on #210. Note the subtlety: #212 is in Phase 2, so the phase-boundary rule would also gate it on all of Phase 1 — but a requires: that names a strict subset is the planner saying "this specific edge is what matters." When a requires: is present, honor it as the precise gate; when it's absent, fall back to the phase-boundary default. If a child in Phase 2 has no requires:, it waits on all of Phase 1.

---

Step 3 — Claim by writing your session-id claim marker (the agent-distinguishable claim, ADR 0115)

Claiming backs Step 1's "skip assigned issues" rule so other write-code agents step over a claimed issue. But the bare GitHub assignee cannot be the claim: it is last-write-wins, additive, not compare-and-swap (two agents that both saw #N unassigned co-assign [A, B], #260) — and worse, every draining agent here pushes as the single git identity usirin, so the old min(login) tiebreak degenerated to a no-op (both co-racers compute min == usirin == me and both implement #N; the #1431 double-implement). The fix is the agent-distinguishable claim marker (ADR 0115, #1452): a claim comment stamped with your CLAUDE_CODE_SESSION_ID, the per-agent UUID the runtime exposes that the shared login cannot provide.

Single-source the primitive — do not re-derive it. The canonical claim-comment grammar, the CLAIM_RE matcher, the write+ ACL trust root (ADR 0055), and the earliest-authorized-claim tiebreak are defined once in ../gh-issue-intake-formats.md §7 (the agent-distinguishable claim marker). This step is the issue-claim consumer of that primitive — it writes the claim and resolves ownership by §7's rules; it never invents a second grammar or a second CLAIM_RE. The marker is the one line:

claim: <CLAUDE_CODE_SESSION_ID> · <ISO-8601-UTC>

The claim is two layers (§7): the assignee stays as the coarse, login-blind availability gate the Step-1 picker reads (skip on any non-null assignee), and the session-id claim comment is the fine, agent-distinguishable resolver. You self-assign and post the claim comment; the comment, not the assignee, decides who owns the work.

Delegated claim — the orchestrated path (recognize, don't re-race)

If the orchestrator (.claude/workflows/drive-issue.js) claimed pre-spawn and threaded a claim token into your prompt ("your delegated claim token is <token>"), the claim is already yours — the orchestrator posted it on your behalf (ADR 0115 §3, Delegated ownership). Do not post a second, redundant claim and do not re-race. Confirm the delegation by resolving §7's tiebreak once — the earliest authorized claim's embedded session id must equal the threaded token — then proceed straight to implementing:

# Orchestrated path: confirm the delegated claim is the earliest authorized claim, then proceed.
# WINSID is resolved by the §7 CLAIM_RE + write+ ACL + min(created_at, comment id) resolver — do
# NOT re-derive that grammar here; run §7's canonical resolution snippet against issue <N>.
[ "$WINSID" = "$DELEGATED_TOKEN" ] || { echo "delegated token is not the earliest authorized claim — abort, do not implement." >&2; exit 1; }
# delegation confirmed — skip the direct-path claim below and go implement

Direct path — claim it yourself (no orchestrator)

When write-code is invoked directly (no threaded token), make the claim here, before you branch or build, using your own CLAUDE_CODE_SESSION_ID as the token:

The whole claim-comment write — Rule-0 defer, the POST, the checkpoint-GET tiebreak, and retract-on-loss — is owned by one verb, pipeline-cli tracker claim (§7's write surface). Run it; never hand-roll a claim: body, which silently skips the ADR-0191 presence stamp and leaves this lane's claim permanently unprobeable (#3987):

# §CLI — resolve the shim by path; `pipeline-cli` is NOT on PATH (ADR 0207; #3314).
PCLI="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)/claude-plugins/kampus-pipeline}/bin/pipeline-cli"
# 0. Fail-closed on a missing token: the claim comment is the ONLY agent-distinguishable signal
#    under the shared `usirin` login — with no token a co-racer is unresolvable, so NEVER claim
#    (and never fall back to the login-keyed assignee as ownership — that is the §7 degeneracy).
#    The verb enforces this too (it backs off on an empty session), so this is a fast local exit.
if [ -z "$CLAUDE_CODE_SESSION_ID" ]; then
  echo "no CLAUDE_CODE_SESSION_ID in env — cannot post an agent-distinguishable claim. BACK OFF, re-pick." >&2
  exit 0   # → re-run Step 1
fi

# 1. Claim through the verb FIRST — layer two, the fine agent-distinguishable resolver. It defers
#    to a pre-existing authorized owner WITHOUT posting, posts a PRESENCE-STAMPED marker under
#    $CLAUDE_CODE_SESSION_ID, re-reads canonical state, and retracts its OWN claim if it lost.
#    Exit 0 = the claim is mine; non-zero = backed off, having mutated nothing that is not ours.
if ! "$PCLI" tracker claim <N>; then
  echo "did not win the claim on #$N (held by another agent, or lost the tiebreak) — back off, re-pick."
  exit 0   # → re-run Step 1
fi

# 2. ONLY NOW self-assign — the coarse availability gate the Step-1 picker reads (§7 layer one).
#    Defer-then-assign is load-bearing, not stylistic: every agent authenticates as the SAME login,
#    so the assignee is ONE shared slot. Assigning first would make the back-off above a cleanup
#    unassign that strips the LIVE incumbent's assignment — clearing the coarse gate on an issue
#    someone else legitimately holds. Claiming first removes the cleanup entirely: we only ever
#    assign on a won claim, so there is no assignment of ours to undo (#4015).
ME=$(gh api user --jq '.login')
gh api -X POST repos/$REPO/issues/<N>/assignees -f "assignees[]=$ME" >/dev/null
# claim won and confirmed (earliest authorized claim is mine) — proceed to implement

The operating rule. Posting the claim comment detects a race; the checkpoint GET (re-reading the issue's comments and resolving the earliest authorized claim per §7) resolves it — the verb does both, and neither leg is prunable as "redundant" (without the checkpoint both staggered co-racers proceed, a double-pick). The winner is the earliest authorized claim (min created_at, then min comment id) whose claimant is not provably dead, recognized because its embedded session id equals your CLAUDE_CODE_SESSION_ID; because earliest-claim-wins, Rule 0 (defer to a pre-existing owner) and the tiebreak are the same fact. Every loser retracts its own claim comment (the verb's own last act) and, having claimed before assigning, has no assignment to undo — it just re-picks. Never co-occupy, and never delete another agent's claim, never unassign a slot you did not fill, and never fall back to the login-keyed assignee as ownership. This is detect-and-tiebreak, not a lock; the residual transient window — a claim already posted while the assignee is not yet set — is tolerated, because an agent that picks the still-unassigned issue in that window runs the verb and defers to the earlier claim.

See ../gh-issue-intake-formats.md §7 for the canonical CLAIM_RE, the full write+-ACL resolution snippet, the staggered-co-racer / straggler / transient derivation, and the pre-spawn / delegated-ownership protocol — this step implements that contract, it does not re-derive it.

Now route by type before implementing — a type:decision or type:investigation issue is not a "write code and open a PR" issue. See Type routing and branch there if the issue carries one of those types. Everything else (type:feature, type:chore, type:bug) is the implement-and-PR path below.

---

Step 3.5 — The mis-attribution guard (verify the target is mine before mutating it)

The claim (Step 3) guarantees you won a unit of work; this guard guarantees you only ever operate on a number you won. They are complements: without it, a mis-attributed issue/PR number — a wrong <N> substituted into a gh api … /comments, a git push to the wrong branch, a close on the wrong issue — silently mutates another agent's live work. That is the #1404 near-miss this step closes (a coder nearly killed another agent's live PR via a mis-attributed number); it is the write-code adoption of ADR 0115 §4 (surface #1456).

Before any mutating action that targets an issue/PR number — open a PR against it (Step 5), comment on it (Step 6 progress, Step 7 handoff), git switch/git push its branch (repair R2/R3), or close it (type routing) — verify the target carries your own session-stamped claim, and refuse — loudly, fail-closed — if that claim is absent or another agent's. The guard reuses the §1 claim-marker read (ADR 0115 §1/§2); it introduces no second claim mechanism.

Your claim token — MY_CLAIM (own session id, or the orchestrator's delegated token)

The token this run owns its work under is MY_CLAIM, resolved once at the top of the run:

• Direct path — write-code invoked directly: MY_CLAIM is the coder's own CLAUDE_CODE_SESSION_ID (the same token the Step-3 claim writes — ADR 0115 §3 direct path).
• Orchestrated path — dispatched by the orchestrator, which pre-claims before spawn (.claude/workflows/drive-issue.js, ADR 0115 §3) and threads its winning claim token into the spawn prompt: MY_CLAIM is that threaded delegated token. write-code recognizes the threaded claim as its delegated own and does not re-race (it posts no second claim) — the guard treats a target whose earliest authorized claim equals the threaded token as mine.

# the claim token this run owns work under: the orchestrator's threaded delegated token if it
# pre-claimed, else my own session id (the direct-path Step-3 self-claim). Fail-closed: with
# NEITHER set there is no agent-distinguishable identity to verify ownership under — abort, never
# fall back to the bare assignee login (that login degeneracy is the exact defect ADR 0115 removes).
MY_CLAIM="${THREADED_CLAIM_TOKEN:-$CLAUDE_CODE_SESSION_ID}"
: "${MY_CLAIM:?mis-attribution guard: no claim token — CLAUDE_CODE_SESSION_ID absent and none threaded; refusing to claim or mutate (ADR 0115 Consequences — never a login fallback)}"

claim_is_mine <N> — MANDATED before every issue/PR-number mutation

Define the guard once and gate every number-targeting mutation on it, exactly as wt_preflight gates every git mutation — a green claim_is_mine is the only sanctioned path to a mutation that names <N>, no bypass:

# §CLI — resolve the shim by path; `pipeline-cli` is NOT on PATH (ADR 0207; #3314).
PCLI="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)/claude-plugins/kampus-pipeline}/bin/pipeline-cli"
# claim_is_mine <N>: resolve the EARLIEST AUTHORIZED claim marker on #N (issue or PR) and assert
# its embedded session id == MY_CLAIM. Returns 0 only on a proven-own claim; non-zero (REFUSE) on
# an absent OR a foreign claim. The ADR-0115 §2 resolution — CLAIM_RE + the write+ ACL trust root
# (ADR 0055) + the earliest-(created_at, comment id) tiebreak — is owned once by the shared verb
# `pipeline-cli claim is-mine`; CITE it, never hand-roll the jq (#3687, the same envelope
# extraction the shipped review-verdict and tracker verbs underwent). The verb is default-deny: an absent claim, an
# unauthorized-only claim, a foreign owner, and a missing session all resolve NOT-mine (exit
# non-zero) — exactly this guard's fail-closed refusal, so the exit-status contract is preserved.
claim_is_mine() {
  "$PCLI" claim is-mine --issue "$1" --session "$MY_CLAIM"   # exit 0 = mine; non-zero = REFUSE (default-deny)
}

claim_is_mine "<N>" && gh api repos/$REPO/issues/<N>/comments -f body="…"   # the guard gates the mutation; never run it ungated

The guard is fail-closed by construction — the verb proceeds (exit 0) only on positive evidence of an authorized claim whose session is MY_CLAIM; an absent claim, an unauthorized-only claim, and a foreign claim all resolve not-mine and refuse (exit non-zero). It is observable (the verb prints the resolved owner vs MY_CLAIM, the outcome reason, and any superseded dead-claimant claims) and idempotent (a read-only GET). Never route around it by widening the comparison or treating the bare assignee as the owner — the assignee is a coarse availability gate only (ADR 0115 §1), and a login-keyed ownership check is the degeneracy this guard exists to remove. A refusal is also never overridable by reasoning: an explicit-looking dispatch brief, or independently re-deriving that the PR/branch/issue/verdict all line up, establishes that the dispatch was coherent — not who owns the lane. Proceeding on that corroboration is what made the guard advisory in the field (#3751); the only sanctioned response to a refusal is to stop and surface it to whoever dispatched you.

Ownership resolves against the earliest live authorized claim (ADR 0191 supersession). The verb drops a claim whose claimant is provably dead — its marker's presence stamp names a session process this host can probe, and the process is gone — so a dead session's older marker no longer shadows a legitimate later claim on an abandoned lane (the orchestrated-repair case, #3751). Supersession needs positive evidence of death: an unstamped/legacy marker, a claim stamped on another host, and an unprobeable pid all stay indeterminate, still count as owners, and still refuse. So the guard's fail-closed direction is unchanged — what changed is that the legitimate case can now resolve, instead of being permanently unprovable.

Which <N> to guard at each site. The guarded number is the work-target whose mutation could clobber another agent: Step 5 guards the issue you open the PR against; Step 6 the issue you comment on; Step 7 guards the child you own (the handoff to the parent epic is predicated on owning the child — gate on claim_is_mine <child>, not the epic, which you never claim); repair R2/R3 guard the PR's linked issue #N (the claim lives on the issue, so resolving Fixes #N and confirming its claim is MY_CLAIM is what proves the PR is yours to push); the repair escalation sites — both the N=3 cap block and the freeze-after-round-K block — guard the PR's linked issue #N too (the escalation comment + status:needs-triage relabel are number-targeting mutations reachable as a fresh stateless repair's first mutation, escalating instead of running R2/R3, so the R2/R3 guards never fire — gate the escalation itself); type-routing closes guard the issue you close.

Composition + ship-ordering (the one honest caveat). This guard is the read-side complement of the claim write: it verifies the marker that the claim surface posts — the Step-3 issue self-claim and the §7 contract (surface #1453), or the orchestrator's pre-spawn claim threaded as MY_CLAIM (surface #1454). It is live-correct only once a claim marker is posted ahead of the mutation — which the integrated pipeline always does (orchestrator pre-claims, or write-code self-claims at its claim step). Landing this guard ahead of a claim-marker-posting surface would, by its own fail-closed contract, refuse write-code's own mutations (no marker yet to verify) — so its ship is sequenced with or after #1453/#1454, a control-plane ship decision, not a fail-open hedge to weaken here.

Rehearsal — a mis-attributed number is refused (the #1404 reproduction)

The guard handed a number it did not claim refuses to mutate it. Walk the three resolutions:

1. Foreign claim — REFUSE. Agent B (its own session B-sid) holds the earliest authorized claim on issue #900. Agent A (MY_CLAIM = A-sid) is handed #900 by a mis-attributed number and reaches a mutation. claim_is_mine 900 resolves winner = B-sid; B-sid != A-sid ⇒ FAILED (fail-closed): #900 is claimed by ANOTHER agent — A pushes/closes nothing. This is the #1404 near-miss, now structurally unreachable.
2. Absent claim — REFUSE. The number names an issue with no authorized claim marker (or only a forged claim from a non-collaborator, which the ADR 0055 author-gate drops). winner is empty ⇒ FAILED (fail-closed): no authorized claim marker — A cannot prove ownership, so it refuses rather than mutate an unclaimed number.
3. My own claim — PROCEED. The earliest authorized claim on #N carries A-sid (A's own Step-3 self-claim) or the token threaded to A by the orchestrator (delegated own). winner == MY_CLAIM ⇒ the guard prints earliest authorized claim == mine and the single guarded mutation runs.

Exactly one of three outcomes, decided by a re-read of canonical issue state against MY_CLAIM — the same detect-and-tiebreak shape (ADR 0115 §2), here read-only and on the acting side.

---

Step 4 — Implement on a branch

write-code MUST run in an isolated git worktree — when spawned as a subagent, via the Agent tool's isolation: worktree. The operator loop requires it so concurrent runs can't race or dirty the primary checkout.

Step 4 preflight — assert you're in a worktree, fail closed if not (ADR 0092)

Run this before you branch or touch a single file. "write-code runs in a worktree" was a documented invariant nobody asserted — so a misconfigured spawn (no isolation: worktree, or a harness cwd-reset that drops you back in the primary checkout between calls) would sail past it and branch the owner's primary checkout, the exact mis-branch the MEMORY notes burn on. This is the silent-no-op failure mode at the agent layer, so it gets the same fix the gates get: emit what you scanned, then FAIL CLOSED on the unsafe state (ADR 0092).

The check is a one-liner of plumbing, portable across git ≥ 2.5: a linked worktree's per-tree git dir (.git/worktrees/<id>) is not the shared common dir (<primary>/.git), whereas in the primary checkout they are the same path. Equal ⇒ you're in the primary checkout (or a bare/no-repo edge) ⇒ stop; differ ⇒ you're in a linked worktree ⇒ proceed.

# fail closed unless we're in a LINKED git worktree (not the primary checkout)
GITDIR="$(git rev-parse --absolute-git-dir 2>/dev/null)" || {
  echo "write-code preflight FAILED: not inside a git repository — refusing to mutate." >&2; exit 1; }
COMMON="$(git rev-parse --git-common-dir 2>/dev/null)"
case "$COMMON" in /*) ;; *) COMMON="$(pwd)/$COMMON" ;; esac   # normalize relative `.git` (older git)
COMMON="$(cd "$COMMON" && pwd)"

# Was worktree isolation EXPECTED for this run? The coder agent-type (agents/coder.md) asserts
# isolation UNCONDITIONALLY, so any run under it expects the harness to have provisioned a linked
# worktree + set $WORKTREE_ROOT. Three machine-checkable, harness-set signals arm it — NOT a per-run
# guess — mirroring the repo-side guard's `isIsolationExpected` (bash-pin.ts) exactly (#3406):
#   1. a direct isolation-asserting agent-type name ($CLAUDE_CODE_AGENT matching coder/reviewer/shipper);
#   2. a set $WORKTREE_ROOT (the harness signalled a provisioned root);
#   3. the ENV-INDEPENDENT corroboration — any agent-context run ($CLAUDE_CODE_AGENT non-empty) sitting
#      on the PRIMARY checkout (git-dir == common-dir). A NESTED/renamed coder spawn inherits the
#      PARENT's agent-type string (e.g. `crew-engineering-manager` / `junior-engineer`, ADR 0189), so the
#      NAME match alone goes inert for it — but such a spawn on the primary checkout is a broken/absent
#      worktree whatever its inherited name, and clause 3 catches it regardless of the string. Keying on
#      the agent-type LITERAL alone was the #3406 defect: a renamed coder computed isolation-expected=0
#      and silently self-provisioned. Do NOT hard-code any agent-type name (junior-engineer or otherwise)
#      to "fix" it — that just relocates the coupling to the next rename; the corroboration removes it.
# A genuine standalone human run (a direct `/write-code`, $CLAUDE_CODE_AGENT unset) matches NONE of the
# three, so it never over-refuses and still reaches the Non-isolated fallback. This is what lets the
# fail-closed branch below distinguish "isolation expected but the harness no-op'd provisioning" (#2440)
# from a legitimate standalone run, firing LOUD in the first case without regressing the second. See
# ADR 0172, #2462 (the guard's parallel re-keying), and #3406.
ISOLATION_EXPECTED=0
case "$CLAUDE_CODE_AGENT" in *coder*|*reviewer*|*shipper*) ISOLATION_EXPECTED=1 ;; esac   # direct isolation-asserting agent-type name
[ -n "$WORKTREE_ROOT" ] && ISOLATION_EXPECTED=1                            # harness signalled a provisioned root
# env-independent corroboration: a non-empty agent-type on the PRIMARY checkout (git-dir == common-dir) —
# catches a nested/renamed coder whose inherited agent-type string doesn't name a role (#3406).
[ -n "$CLAUDE_CODE_AGENT" ] && [ "$GITDIR" = "$COMMON" ] && ISOLATION_EXPECTED=1
echo "write-code preflight: git-dir=$GITDIR common-dir=$COMMON cwd=$(pwd) isolation-expected=$ISOLATION_EXPECTED (agent=${CLAUDE_CODE_AGENT:-unset} worktree-root=${WORKTREE_ROOT:+set})"   # emit scanned scope (ADR 0092 §1)
if [ "$GITDIR" = "$COMMON" ]; then
  if [ "$ISOLATION_EXPECTED" = 1 ]; then
    # FAIL-CLOSED LOUD (the #2443 branch): isolation was EXPECTED but this run is on the PRIMARY
    # checkout with no linked worktree — the harness's `git worktree add` + $WORKTREE_ROOT injection
    # silently didn't run for this coder spawn (#2440's harness no-op). Because the whole repo-side
    # worktree-guard keys on $WORKTREE_ROOT, that no-op ALSO disarmed it, leaving this preflight the
    # sole surviving layer. Do NOT self-provision here: doing so papers over the harness failure and
    # leaves the two-layer primary-corruption defense collapsed to one, invisibly (#2270 class).
    echo "write-code preflight FAILED (fail-closed, LOUD): worktree isolation was EXPECTED (agent=${CLAUDE_CODE_AGENT:-?}, worktree-root=${WORKTREE_ROOT:+set}) but this run is on the PRIMARY checkout (git-dir == common-dir) and \$WORKTREE_ROOT is unset." >&2
    echo "  ROOT CAUSE: the harness's worktree provisioning (git worktree add + \$WORKTREE_ROOT injection) did NOT run for this coder spawn — the #2440 harness no-op. The repo-side worktree-guard also keys on \$WORKTREE_ROOT, so it is disarmed too; only this preflight is left." >&2
    echo "  REFUSING to self-provision — that would hide the harness failure and leave the two-layer defense collapsed to one, invisibly (the primary-checkout-corruption class, #2270)." >&2
    echo "  ROUTED BLOCKER — surface UP to the operator/EM: 'harness worktree provisioning no-op'd for a coder spawn (isolation expected, \$WORKTREE_ROOT unset); the out-of-repo harness half (#2440) needs attention. Do NOT blindly retry the same spawn.'" >&2
    exit 1
  fi
  # isolation was NOT expected ⇒ a genuine standalone run: fall through to the Non-isolated fallback,
  # which self-provisions a worktree (this path is unchanged, and the loud branch above never fires for it).
  echo "write-code preflight FAILED (fail-closed): git-dir == common-dir ⇒ this is the PRIMARY checkout, not an isolated worktree." >&2
  echo "  Refusing to branch/commit here — a spawn without isolation:worktree (or a cwd reset to the primary tree) would mis-branch the owner's checkout." >&2
  echo "  This run did NOT expect isolation (standalone) — take the Non-isolated fallback below to create a worktree before mutating." >&2
  exit 1
else
  # POSITIVE worktree assertion — loud + EARLY (#3458). git-dir != common-dir is the ONE trust
  # signal for "I am in my own linked worktree" that survives the misleading env a worktree spawn
  # is handed: $WORKTREE_ROOT is unset (the reverted #2938 provisioning hook) and $CLAUDE_CODE_AGENT
  # reports the PARENT's value (inherited agent-type, #2462) — so neither can anchor worktree
  # identity. This git-plumbing check can, and does so independently of both. Capture $WT from THIS
  # evidence, never from the untrustworthy env and never from a file. This assertion fires BEFORE the
  # first Edit/Write on purpose: a raw Edit/Write to a primary-checkout absolute path is not a git op,
  # so neither the repo-side worktree-guard nor wt_preflight fires on it — the ONLY thing standing
  # between a cwd-reset + stale-Read-cache and a stray write into shared primary `main` is anchoring
  # every edit under this $WT (see "Anchor every Edit/Write to $WT" below). Establishing $WT loudly
  # here is what makes that anchoring actionable from the first file touch.
  WT="$(git rev-parse --show-toplevel)"
  echo "write-code preflight CONFIRMED (LOUD): in a LINKED worktree at $WT (git-dir != common-dir) — worktree identity established from git plumbing, INDEPENDENT of \$WORKTREE_ROOT (${WORKTREE_ROOT:+set}${WORKTREE_ROOT:-unset}) and \$CLAUDE_CODE_AGENT (${CLAUDE_CODE_AGENT:-unset}), both of which may misreport. Anchor EVERY Edit/Write and git op to this \$WT (absolute) — never a primary-checkout path."
fi

The preflight is fail-closed by construction: it refuses on the primary checkout, on a not-a-repo cwd, and on the ambiguous default — only positive evidence of a linked worktree (git-dir ≠ common-dir) lets it through. It is observable (it prints the two dirs + cwd + isolation-expected it compared, so "what did the preflight look at" is answerable from the run log) and idempotent (read-only git rev-parse, safe to re-run). Never route around the preflight by deleting it or relaxing the comparison; a green preflight is the precondition every mutation in Steps 4–7 relies on.

The primary-checkout refusal forks on whether isolation was expected (ADR 0172, #2443). The git-dir == common-dir refusal is a hard stop in both directions, but how you're meant to recover differs, and conflating the two is what let a harness failure hide:

• Isolation was EXPECTED (isolation-expected=1 — the run is under the coder agent-type, or $WORKTREE_ROOT was set) yet you're on the primary checkout ⇒ fail closed LOUD and STOP. This is the #2440 harness no-op: the harness was supposed to provision a linked worktree and inject $WORKTREE_ROOT but silently didn't, which also disarms the whole $WORKTREE_ROOT-keyed repo-side worktree-guard — so this preflight is the only surviving layer. Do NOT self-provision to route around it. Self-provisioning here would paper over the harness failure and leave the two-layer primary-corruption defense collapsed to one, invisibly (the #2270 primary-checkout-corruption class). Instead surface the printed ROUTED BLOCKER up to the operator/EM so the out-of-repo harness half gets fixed rather than silently absorbed.
• Isolation was NOT expected (isolation-expected=0 — a genuine standalone write-code, e.g. a human running /write-code directly) ⇒ take the Non-isolated fallback below, which creates a real linked worktree and cds into it, after which this same check passes. This is the only path where self-provisioning is sanctioned; the loud branch above never fires for it, so the standalone flow is unchanged.

The isolation-expected signal is machine-checkable and grounded in the coder agent-type's unconditional-isolation assertion (../../agents/coder.md), read from the harness-set $CLAUDE_CODE_AGENT env (stable across an agent's separate Bash calls) plus a set $WORKTREE_ROOT — never a per-run guess. It fails safe: if the agent-type value ever differs from what's matched, the run degrades to isolation-expected=0 (today's silent self-provision), never to a dangerous primary-checkout mutation — the loud branch only adds a stop, it never removes the existing refusal.

The success path asserts worktree identity LOUDLY, on env-independent evidence (#3458). When git-dir != common-dir the preflight no longer proceeds silently: it captures $WT from that positive git-plumbing evidence and prints a CONFIRMED line naming the worktree root. This is the producer/preflight half of the worktree-misID class — a worktree-isolated spawn is handed a misleading process env ($WORKTREE_ROOT unset because the #2938 provisioning hook was reverted; $CLAUDE_CODE_AGENT carrying the parent's agent-type via inheritance, #2462), so neither env var can anchor "am I in my worktree?" The git-dir != common-dir plumbing can, and the assertion keys on only that — never on an agent-type string, so no fix relocates the fragile coupling (the same principle as #3406's ADR 0189 note). This is deliberately distinct from #3406. #3406 is the consumer/failure-side change: it re-keys the ISOLATION_EXPECTED detector (the case "$CLAUDE_CODE_AGENT" on the git-dir == common-dir branch above) onto the same env-independent primary-checkout corroboration, to parity with bash-pin.ts. This issue is the positive/success-side assertion. The two live on opposite sides of the same if and do not overlap: #3406 hardens when to fail closed, #3458 hardens what a pass positively establishes. The ISOLATION_EXPECTED detector is intentionally left untouched here so the two changes can't double-implement or contradict.

The preflight runs once at Step-4 start AND re-asserts before EVERY git-mutating op. The harness resets an isolated subagent's shell cwd back to the primary checkout between Bash calls (edits still land in the worktree, but a fresh git invocation runs where the cwd points). A git commit/git push/branch op issued after such a reset runs against the shared primary tree even though the opening preflight was green — so two parallel runs serialize their commits onto whatever branch the primary tree is on, cross-contaminating each other's PRs (#832). One pass at Step-4 start does not hold for the whole run.

Capture your worktree root once, then run this mandatory per-mutation preflight — wt_preflight — immediately before every git commit, git push, and branch create/switch (Steps 4, 5, R2, R3). It re-cds to your own worktree root first (correcting a between-calls reset), then re-runs the same fail-closed check and asserts the toplevel is your worktree. A green wt_preflight is the only sanctioned path to a mutation — no bypass, same construction as the opening preflight:

WT="$(git rev-parse --show-toplevel)"   # same $WT the opening preflight CONFIRMED; re-derive per Bash call (shell state doesn't survive), never from a file
wt_preflight() {   # MANDATED before every git commit/push/branch op — fail-closed, re-correcting cwd
  cd "$WT" || { echo "wt_preflight FAILED: cannot cd to worktree root $WT" >&2; return 1; }
  GITDIR="$(git rev-parse --absolute-git-dir 2>/dev/null)" || {
    echo "wt_preflight FAILED: not in a git repo at $WT" >&2; return 1; }
  COMMON="$(git rev-parse --git-common-dir 2>/dev/null)"
  case "$COMMON" in /*) ;; *) COMMON="$(pwd)/$COMMON" ;; esac
  COMMON="$(cd "$COMMON" && pwd)"
  TOP="$(git rev-parse --show-toplevel)"
  echo "wt_preflight: git-dir=$GITDIR common-dir=$COMMON toplevel=$TOP wt=$WT"
  [ "$GITDIR" != "$COMMON" ] || { echo "wt_preflight FAILED (fail-closed): on the PRIMARY checkout, not the worktree — refusing to mutate." >&2; return 1; }
  [ "$TOP" = "$WT" ]        || { echo "wt_preflight FAILED (fail-closed): toplevel ($TOP) != my worktree ($WT) — cwd reset landed me in a sibling/primary tree." >&2; return 1; }
}
wt_preflight && git <commit|push|switch …>   # the guard gates the mutation; never run the mutation without it

Anchor EVERY Edit/Write to $WT — the raw-write path no git guard covers (#3458). wt_preflight and the repo-side worktree-guard both gate head-moving git ops. A raw Edit/Write to a file is not a git op, so neither guard fires on it — an edit whose target is a primary-checkout absolute path writes straight into the shared primary tree, silently, and is caught (if at all) only by a coder noticing the primary went dirty before commit. This is not hypothetical: with $WORKTREE_ROOT unset and the cwd reset to the primary checkout between calls, a coder's first Edit/Write took primary-checkout absolute paths from session gitStatus/Read context and landed edits on primary main (#3458 sharpening) — the guards never saw it because it wasn't a git op.

So the opening preflight's $WT capture is load-bearing for file edits, not just git ops: every Edit/Write target path MUST be under $WT (the absolute worktree root the preflight CONFIRMED), never a bare primary-checkout absolute path — even one the harness handed you in gitStatus or a Read result. The Edit/Write tools do not auto-target the worktree; an absolute path outside $WT edit-bleeds into whatever tree it names. Before the first edit, know $WT; for every edit, confirm the path begins with $WT. Treat a primary-checkout absolute path in your context as stale (cwd-reset + Read-cache), not as your worktree.

Pushing: the verdict is the ref, not the exit code — always pipeline-cli verified-push (#4213). A push is the one mutation whose failure is invisible by default, and not because of git. Two observation-layer defects destroy the signal independently: piping a push through tail reports tail's status (pipefail is off on this platform, measured — so the pipeline returns 0 however git died), and a detached run's output file carries no exit status at all, so success gets inferred from the absence of an error: line — which is exactly what a SIGPIPE'd git, printing nothing, looks like. Both fired on one lane (#4042 / PR #4142): the branch simply was not there, and every downstream stage — reviewer checkout, SHA-bound verdict, shipper merge — assumed a branch that did not exist.

So never invoke git's push porcelain directly from this skill. Use pipeline-cli verified-push, which pushes and then reads the remote ref back independently, and emits its verdict as a single grep-able line last on stdout — PUSH-VERDICT: MOVED, NOT-MOVED, or UNKNOWN — in addition to the exit code (0 / 1 / 3). stdout is the one channel that survives both masking layers, so … | tail -1 now yields exactly the verdict instead of erasing it, and a detached run's output file ends with it.

Three outcomes, and the third is not a success. MOVED means the remote ref was confirmed at your local head. NOT-MOVED means it was confirmed not to be. UNKNOWN means the probe could not determine it — a dead transport, an unresolvable head, a ref that matches while the push itself misbehaved. Treat UNKNOWN exactly like a failure: stop and surface it. Do not re-run the push hoping it takes (the verb deliberately does not retry — a blind retry hides the contention it exists to expose, #4136), and do not proceed to open a PR, request a re-review, or report the work landed.

This is enforced mechanically, not by attention (ADR 0202): pipeline-cli gh-phoenix lint-skills reds on a git push invocation in any runnable block of the skill corpus and fails closed on zero scope, so a bare push cannot re-enter this file.

This constrains how you branch: main is already checked out in the primary tree, so git checkout main fails inside an isolated worktree (fatal: 'main' is already checked out at <primary>). Branch from latest origin main without checking it out:

# Fetch the base fresh, and FAIL-LOUD if it doesn't run: FETCH_HEAD is what the branch below is
# cut from, so a silently-failed fetch (network blip, a harness worktree whose exec env stripped
# PATH) leaves FETCH_HEAD at a STALE prior tip, and the branch misses a base file merged just
# before branch-cut → the SHA-bound run-evidence check false-fails on a file the head never
# carried (#1920; the same stale-base class #1837 fixed at the repair step). Never proceed on an
# unverified fetch — assert it succeeded before branching off FETCH_HEAD.
git fetch origin main || { echo "write-code: 'git fetch origin main' failed — refusing to branch off a stale FETCH_HEAD (would cut a head missing a just-merged base file; #1920)." >&2; exit 1; }
# Derive the prefix from THIS checkout's git identity — never a hardcoded literal. A copied
# literal namespaces every agent's branch under one person's handle regardless of who runs.
PREFIX="$(git config user.name | tr '[:upper:] ' '[:lower:]-')"   # e.g. "Umut Sirin" → "umut-sirin"
: "${PREFIX:?set git user.name to derive a branch prefix}"        # empty identity ⇒ "/slug…" (leading slash) git rejects with an opaque error; fail here with a fixable one
# Per-run suffix: the deterministic $PREFIX/<slug-for-issue-N> is the SAME ref for every
# run on this issue, so two concurrent runs would both push origin/<that branch> and the
# second push would clobber the first's commits. A per-invocation nonce keeps them distinct.
BRANCH="$PREFIX/<slug-for-issue-N>-$(uuidgen | head -c 8)"
wt_preflight && git switch -c "$BRANCH" FETCH_HEAD   # branch create is a git mutation → gate it (per-mutation preflight above)

It's git switch -c "$BRANCH" FETCH_HEAD (not git checkout main) on purpose: in an isolated worktree main is checked out elsewhere, so branching directly off the freshly-fetched FETCH_HEAD is the only flow that works — don't "fix" it back to a main checkout.

The branch name is created once here, then RE-DERIVED LIVE from the worktree at every later git op — NEVER carried across Bash calls in a shared file. $BRANCH is a shell variable, and shell state does not survive between an agent's separate Bash invocations (env vars are gone by the next call, the same way the cwd is reset back to the primary tree — which the per-mutation preflight corrects). So by push time (Step 5) $BRANCH is empty, and an agent that "carries" it by writing the name to a scratchpad file improvises a cross-lane hazard: a plain /tmp (or shared-scratchpad) path like branch.txt is unkeyed, so a concurrent lane clobbers it mid-run and the reader pushes to the sibling lane's ref (#2038 — the #2018 lane pushed toward the #2021 lane's branch). The uuidgen nonce makes each lane's value unique, but a shared filename is what collides.

The rule (mandatory, at every git op after this create): re-derive the branch live from your own worktree — never read it from a file. Right after wt_preflight re-cds you to $WT, the checked-out branch is your work branch, so read it straight from the worktree HEAD:

BRANCH="$(git -C "$WT" branch --show-current)"   # live from the worktree — the source of truth, re-read at each git op
: "${BRANCH:?could not re-derive branch from worktree $WT — refusing to push to a guessed/cached ref}"

This is exactly the recovery the reported incident used to self-heal, promoted to the standing rule. Do NOT persist the branch name to a scratchpad//tmp file to carry it across calls. This is the local instance of the per-run scratchpad namespace, §SP of ../gh-issue-intake-formats.md — and it is §SP's first rule, "prefer no file at all," which the live re-derivation above satisfies outright. If — and only if — a per-run cache is genuinely unavoidable, allocate it under $RUN_SCRATCH per §SP (never a bare branch.txt, and never a path keyed only on the issue number). The reason this matters beyond a mis-push: a clobbered scratchpad file reads back successfully with the sibling lane's content, so nothing errors and the wrong ref looks right (#2038, and the #3718 reviewer that diffed the wrong PR).

The prefix is derived from this checkout's git config user.name, not a copied literal — so the branch lands under your handle (<your-handle>/…), whoever runs the skill, instead of inheriting someone else's namespace. Append a short kebab-case slug naming the work and the per-run nonce so two concurrent runs on the same issue never push the same origin/ ref. Read the issue's ### What to build for scope and honor the **TDD:** flag — yes means write the failing test first, then make it pass; no means config/docs/scaffolding where test-first doesn't apply.

As you write, apply CLAUDE.md's "Comments earn their place or die" collapse convention to the code you generate: state a why once at its most load-bearing site and point elsewhere with // See ADR NNNN / #NNNN — never re-derive the same ADR rationale across multiple docblocks in a file (the coder.md standing invariant is the source; #2186).

Non-isolated fallback. For the rare invocation that isn't already in a worktree, spin one up rather than checking out main. Fetch first — the local origin/main remote-tracking ref can predate a just-merged base commit (e.g. a run-evidence-referenced tooling file added seconds before branch-cut), so git worktree add … origin/main off a stale ref cuts a head that misses that file and false-fails the SHA-bound CI (#1920; the same stale-base class #1837 fixed at the repair step). Create the worktree on the per-run $BRANCH (nonce and all) at a per-run worktree path off the freshly-fetched tip, so two concurrent fallback runs collide on neither the branch nor the dir: git fetch origin main; WT="../wt-issue-<N>-$(uuidgen | head -c 8)"; git worktree add -b "$BRANCH" "$WT" FETCH_HEAD, then cd "$WT". Branch off FETCH_HEAD (the just-fetched origin tip), never the possibly-stale origin/main ref. When you're done, remove it with git worktree remove "$WT" (never --force — a dirty tree then errors out and is KEPT). A build worktree that made commits and is not removed here (an aborted run, a fallback that never reached its done-step) does not leak unbounded: it is backstopped by pipeline-cli worktree-sweep --execute (#1243/#2785), which reclaims a .claude/worktrees/ build tree only once it is clean + merged + idle + unlocked with no open PR — the #2240 liveness guard, non---force. After the cd "$WT", re-run the Step 4 preflight — the fresh worktree's git-dir now differs from the common dir, so the check passes and you may mutate. This fallback is only for the standalone (isolation-expected=0) path — a run where isolation was expected must NOT reach it: the preflight's loud branch (ADR 0172, #2443) hard-stops that case before here, because self-provisioning would silently absorb a harness provisioning failure (#2440) and collapse the two-layer defense to one. For a standalone run this is the only sanctioned route from a primary-checkout start; the preflight stays fail-closed until a real worktree exists. Here too the branch name is created once and thereafter re-derived live from the worktree (git -C "$WT" branch --show-current) at each later git op — never carried across Bash calls in a shared file (see the live-derivation rule above; the same cross-lane clobber applies to a fallback run).

Ground the implementation in the codebase the way the repo expects: the ADRs in .decisions/ are the why and the binding decisions, the patterns in .patterns/ are how the current code is shaped — read the relevant ones before writing, and follow them over intuition (per CLAUDE.md). Implement the issue's acceptance criteria; they are the literal checklist review-code will verify, so build to make every box checkable from the outside. Run the pre-push typecheck (below) and the test suite as the repo conventions require before you open the PR.

Pre-push typecheck — run the EXACT CI command (pnpm typecheck), never a hand-rolled tsc

Run pnpm typecheck — the exact command CI's lint / format / typecheck job runs (.github/workflows/ci.yml) — and refuse to push on any non-zero exit. This is the only typecheck that predicts the gate, because it is byte-for-byte the gate's own command:

pnpm typecheck

pnpm typecheck fans out (turbo run typecheck) to each app's project-aware checker — for apps/web that is pnpm fate:generate && tsgo -b tsconfig.worker.json tsconfig.node.json && tsgo -p tsconfig.app.json … — so it covers the full workspace under the real project graph, including every newly-added test file, with the repo's strict flags (noUncheckedIndexedAccess, exactOptionalPropertyTypes) in force. Do NOT substitute a hand-rolled tsc -p tsconfig.json (or any bare tsc): the repo's checker is tsgo (@effect/tsgo / @typescript/native-preview), a different engine than stock tsc, and a root-tsconfig.json tsc run uses a different, partial project scope that omits the app's test files — so a type error in a new test file passes your self-check and only surfaces when CI (or review-code) re-runs the real pnpm typecheck at head, costing a full FAIL → repair round-trip the pre-push gate exists to prevent (#1479; the #1406 / #1407 incidents — new test files that failed TS18048 / TS2412 / TS2345 only under the gate's tsgo). New test files are full TS under the same flags and the same project as production code — a test-file type error is a real gate failure, not noise. So run pnpm typecheck after your final test edits, over the whole workspace, and treat a non-zero exit as a hard "do not push" — never report "typecheck clean" off a narrower or different-engine run.

For lint, run pnpm lint:worktree, not pnpm lint. Bare pnpm lint (biome check .) self-no-ops from inside the worktree: . resolves to the worktree's own CWD, which physically sits under .claude/worktrees/<id> and so matches the retained !**/.claude/worktrees exclusion — biome reports "0 files / paths ignored" without linting anything (a false-clean that sailed past local checks and only failed in CI; #236, #553, ADR 0060). pnpm lint:worktree lints the explicit changed files instead (committed and working-tree, vs origin/main), filtered to biome-handled extensions so a docs/markdown-only diff is a clean skip (exit 0), never bare .. It catches the same violations CI's lint / format / typecheck job would — including in root and .claude/** files, which a bare biome check apps packages would miss — so a clean pnpm lint:worktree reliably predicts a green CI lint.

pnpm lint:worktree

Editing a skill — use the real skills/** path, never the .claude/skills/** symlink

When the issue has you editing a skill (a SKILL.md or its supporting files), edit the real path under claude-plugins/<plugin>/skills/<name>/… (e.g. claude-plugins/kampus-pipeline/skills/write-code/SKILL.md), never the .claude/skills/<name>/… path. .claude/skills is a symlink to the real plugin skills dir — both resolve to the same file on disk — but the harness's auto-mode self-modification classifier keys on the path string: any Edit/Write whose target contains .claude/ is flagged "Self-Modification (config file controlling agent behavior)" and hard-blocked when the authorization comes from an issue/tool rather than the user's own message. The identical file edited via the real claude-plugins/**/skills/** path is not flagged. So the .claude/ path is a coin-flip into an opaque failure (it surfaces as a generic build-failed with no PR, not "blocked by the self-mod guard"), costing a wasted retry + manual diagnosis (#599, #637). Always resolve the real path first. PR bodies and progress comments must describe the changed path as the real claude-plugins/**/skills/** path too, so the diff a reviewer reads matches what you wrote.

Editing .claude/ content (not a symlinked skill) needs a Bash scripted-replace. The same guard blocks the Edit/Write tools on any genuine .claude/ path that has no real-path alias — e.g. .claude/settings.json. There's no symlink to route around for those, so apply the change with a Bash-scripted in-place replace (a node/sed splice) rather than the Edit tool. (Most write-code tasks don't touch .claude/ content at all — this is the escape hatch for the ones that must.)

Commit per repo conventions, gating each git commit on wt_preflight (the per-mutation preflight above) so a between-calls cwd reset can't land the commit on the primary tree. Don't push to or PR from main.

---

Step 4a — Read the four-pillars design law before you generate any UI (UI diffs only)

When this diff will generate or edit a user-facing UI surface, read design-system-manifest.md before you author the UI, and generate to it — role-token annotations, component-selection rules, and the per-pillar prohibitions. That manifest is the agent-readable transcription of the four-pillars design law (ADR 0162) — the CLAUDE.md-for-design a UI-generating agent applies from the first draft. This is the read-before counterpart to Step 4d's look-after self-check and Step 4e's prose-before read: consult the law on the way in so the generated UI conforms from the start, rather than leaving review-design to catch a pillar violation after the fact. Making this an explicit step closes the build-vs-review asymmetry — review-design binds the manifest explicitly at gate time, so the build side must too, not rely on CLAUDE.md happening to name the file.

Fires only for a UI diff — a no-op otherwise (graceful absence). Scope it to a diff that changes a rendered frontend surface (apps/web/src/**, the same probe as Step 4d); a worker/tooling/docs/skill diff authors no UI and skips this step entirely — the same first-class-absence shape as Steps 4b/4d/4e.

---

Step 4b — Ship dark behind a default-off flag on a containment-marked child

When the child you picked carries **Containment:** flag (default-off), the implementation above isn't done until the new user-facing path ships dark: behind a boolean flag that is off by default, so the feature reaches main and production deployed-but-not-live until a human deliberately flips it. This is the product-development cycle's agents-deploy / humans-release contract (ADR 0083): your autonomous merge is the deploy, the flip is the human release, and a default-off flag is what makes the no-eyeball auto-ship safe — a bad merge sits dark, contained, never seen by a user. plan-epic stamps the marker, you ship dark on it, and review-code Step 3b verifies the gating.

The marker contract — its values, its tolerant-read rule, who writes vs reads it — is defined once in ../gh-issue-intake-formats.md (§The product-development cycle hook); read it there, this step is the reader's behavior on the ship side.

Read the marker off the child you're implementing, tolerantly per the formats §Reading stance — a **Containment:** line, with a leading bold-marker, anywhere in the body; a missing line reads as none:

# the child's containment marker; a missing line reads as `none` (formats §2 tolerant-read rule)
CONTAINMENT=$(gh api repos/$REPO/issues/<N> --jq '.body' \
  | grep -ioE '\**\s*Containment:\**\s*(flag|exempt|none)' | head -n1 \
  | grep -ioE '(flag|exempt|none)' || echo none)

Graceful absence — the dark-ship behavior applies only when there's a cycle. It fires only when the marker resolves to flag and the repo has a product-development-cycle.md (the one canonical probe, formats §1). On exempt, none, a missing line, or an absent cycle doc (a foreign install with no cycle and no flag substrate — ADR 0062), this step is a no-op: you implement and ship the change exactly as Steps 4/5 already describe, with no flag introduced. Absence is a first-class, correct state, not a defect — the same graceful-absence contract plan-epic (stamp) and review-code (verify) honor:

# the canonical cycle-doc probe (formats §1); absent ⇒ no cycle ⇒ ship normally, no flag
gh api "repos/$REPO/contents/product-development-cycle.md" --jq '.path' >/dev/null 2>&1 \
  && CYCLE_DOC=present || CYCLE_DOC=absent
# ship dark ONLY when:  [ "$CONTAINMENT" = flag ] && [ "$CYCLE_DOC" = present ]

When it does fire, ship dark per the dark-ship procedure — don't re-derive the mechanics. The change gates behind a default-off flag, which is one of two shapes that this step treats identically from here on:

• Newly-declared in this diff — no suitable flag exists yet, so you mint one: declare a default-off flag and gate the new path following .patterns/feature-flags-agent-workflow.md (the ship-behind-flag workflow, #514), naming the flag by the grammar in .patterns/feature-flags-schema-lifecycle.md (<product>-<feature>-<purpose>, kebab-case, #513).
• Gated behind a flag a PRIOR PR already declared — the flag resource is not in this diff (an earlier PR minted it; you only add the gated path under the existing key). The #1277/#1205 shape: a feature gated behind the prior-PR #1204 authorship flag.

Whichever shape applies, capture the exact kebab-case flag key as FLAG_KEY — it is the single fact that flows out of this step. The load-bearing invariant the patterns own is default = safe-state, the three facets review-code Step 3b will verify, so build to make each checkable from the outside:

• Declare it default-off (newly-declared shape only) — a