@joshuafolkken/kit 1.872.0

package/.claude/skills/workflow-commands/backlogrun-lanes.md

@@ -0,0 +1,345 @@
+# `backlogrun` — lanes and concurrency
+
+**Read this file in full before the first lane opens** — in the turn that reaches
+`pnpm josh lane:open`. It is a point-of-use document, never an entry read: the entry procedure is
+`backlogrun.md`, which points here at that step (joshuafolkken/kit#2010). This file is the single
+source of the per-repository lane ceiling, the lane lifecycle, and how a merge conflict between lanes
+is resolved.
+
+## Concurrency: as many children per repository as it has free lanes
+
+Execution state lives on GitHub and nowhere else, so **an `backlogrun` need not be a single session.** One
+session per repository; each calls `josh epic:next <E> --repo <owner/repo>` and runs only its own
+repository's children.
+
+```bash
+# In the kit checkout
+pnpm josh epic:next 858 --repo joshuafolkken/kit
+```
+
+A child in another repository is read against that repository through `gh api`, so no clone is needed
+to learn its state — only to implement it. A repository with no checkout here says so rather than being
+cloned.
+
+**A dependency that crosses a repository is not satisfied when the blocking issue closes.** Merging
+kit's issue does not publish kit, so such a dependency resolves only once the blocker is closed *and*
+its release has appeared in the registry — and while the blocker is still open the registry is never
+consulted. **Unless that repository publishes nothing** — no `package.json` on its default branch, or
+one declaring `private` — in which case a closed blocker there resolves. The answer is read from the
+blocker repository's manifest, never from the registry (a 404 also means "this token may not see it").
+
+**The lane count is per repository, and `epic:next` is what applies it.** When it has a child to offer,
+it first asks that repository **how many of its lanes are already running something**: every open issue
+carrying `in-progress` and not parked counts for one — whichever epic it belongs to. What is left of
+`JOSH_LANE_LIMIT` (**default 6**) is what gets offered, and at zero the answer is `wait`. It is asked
+**only when there is a candidate**. A **parked** issue does not hold a lane: `needs-decision` outranks
+`in-progress` here exactly as in the classification. A child stopped by `needs-human-review` is
+deliberately not parked and goes on holding its lane, because its uncommitted work is still in that
+checkout.
+
+**It is advisory and not atomic.** The label is applied when a child is dispatched — the parent claims
+it in `lane:dispatch` before the child process starts, and a standalone `fullrun` / `halfrun` claims it
+the moment `run:hold` answers `hold` — *after* this read, so two sessions starting in the same instant
+can both read the same free lane. What the check closes is the window that actually occurs — a
+dispatched lane holds the label from the launch onward, not the tens of minutes it took when the
+child's own `fullrun` had to reach its own apply first. It is a guard that makes the invariant
+mechanical, not a mutex.
+
+**It is scoped to the resource, not the epic.** A lane is its own checkout with its own branch and
+ports, so the repository-wide number is a **ceiling on how many lanes run at once**. How a session
+drives more than one child at a time is "Lanes — running more than one child at a time" below.
+
+**A stale label holds a lane, so the stale rule reaches past this epic's own children** — "`in-progress`
+is removed by whoever finds it stale" below applies to **any** open issue in the repository. `epic:next`
+names the holders on standard error, and the 90-minute stale window bounds the wait.
+
+**A listing it could not read is not an idle repository.** `epic:next` answers `wait` there rather than
+offering the child — reading a failed read as "nothing is running" is the one direction this guard may
+not fail in, because that answer *starts* work. **A listing that was *cut short* is the same answer**: a
+short one with no visible holder is `wait`, with its own message.
+
+**Two children of one repository may run at once, and the section below is how.** The guard is a
+ceiling rather than a prohibition, scoped to the lane rather than to the epic. **Do not read this as
+"concurrency needs no coordination"**: the coordination is this section plus the one below, and
+switching the guard off is not one of the ways to get parallelism.
+
+Parallelism only helps children that do not depend on each other. When app-kit's child needs kit's new
+feature, that is recorded as `blocked-by` and `epic:next` makes it wait.
+
+## Lanes — running more than one child at a time
+
+`pnpm josh epic:next <E> --repo <owner/repo> --lanes` answers with **one issue number per line**, up to
+the number of free lanes, and each of those children runs in a **lane** of its own: a linked git work
+tree with its own branch, its own `.env` and its own dev and preview ports (`docs/josh-commands.md` →
+"`josh lane:open` / `josh lane:close` / `josh lane:list` / `josh lane:prune`"). **Implementation, the
+verification gate and the review run in parallel; the merges stay serial** — each one lands on the
+`main` the next is then measured against.
+
+**A lane child may cut its own turn before the gate.** Implementation done, it ends its process and a
+fresh one resumes the same lane from the gate onward — the boundary, the two commands and the resume
+verification are `pre-gate-cut.md`, the single source. **The child is told apart from a person, and its
+resume stage is handed to it, by a mark the dispatch sets** — `JOSH_LANE_CHILD`, the lane's issue
+number (`pre-gate-cut.md` → "The dispatch mark" and "The stage is passed to the resumed child").
+
+**One kind of child takes no lane beside anything: an interrupt whose subject is a defect in the
+verification path itself.** It runs alone, and the batch resumes only once it has merged. **Decide it
+from the enumeration, never from how serious it looks** — does the defect reach the verification gate
+(lint / type check / spell check / unit tests), the code review, the pre-push hook, or the merge
+checks? One of those, and the offered children wait; none, and it fills a lane like any other child.
+**Ask it of what `epic:next --lanes` just offered, before opening a second lane**; the rule is
+`prompts/collaboration-workflow/wip-cap.md` → 「実行のしかた」, its single source.
+
+**A lane's review does not inherit the lane, and `pnpm josh review:brief` is what closes that.**
+`/code-review` is forked by the harness into the **session's** working directory, which during a lane
+run is a different tree — usually the default branch. Reading that, the review finds nothing wrong and
+**the failure arrives as approval**: the child counts the round as clean and commits a diff nobody
+read. **So the path is no longer something a brief has to remember to carry**: `pnpm josh review:brief`
+prints the lane's absolute root, branch and HEAD, hands over targets written `git -C <root> …`, and
+prints a nonce the review attests with `pnpm josh review:attest <nonce>` from the checkout it actually
+read. **The child asks `pnpm josh review:attest --check` before it counts a round**, and
+`pnpm josh followup` asks again before it merges; `missing` and `mismatch` are both refusals. A clean
+round is therefore the case to check hardest, not the case to skip the check on.
+
+**A lane's branch is `<N>-lane`, and the issue number leads it so that the commit path accepts it.**
+`pnpm josh git` refuses to commit from a branch that is neither the default branch nor one sharing the
+child's `<N>-` prefix (`scripts/git/git-branch.ts` → `has_same_issue_prefix`, `/^\d+-/`). **Switching
+the lane to another branch is not the way round it**: `lane-registry.ts` → `branch_issue` identifies a
+lane **by** that branch name, so a switched lane drops out of `list_lanes()` — losing its seat, its
+listing and its isolation. So `epic:next` is asked **with** `--lanes`, and everything below runs as
+written.
+
+**Running unattended gets harder, not easier, and that is the honest trade.** Many lanes make the
+overlap between children real, and every overlap that becomes a conflict costs the child that loses the
+race a resolution, a re-run gate and a review ("Conflicts are not predicted" below), and parks it
+outright under that section's four conditions. The run finishes more work per hour **and** spends more
+of each child's budget on merge races. Do not report the first without the second.
+
+### Once per repository, before the first lane opens
+
+In the **primary checkout**, in this order, and never again per lane:
+
+1. `git switch main && git pull` — every lane is branched from this ref.
+2. `pnpm josh latest:scope`, and the update on `required` — "`josh latest` runs once per session" above.
+3. `pnpm josh lane:prune` — closes the lanes an interruption left registered without a work tree.
+
+**`pnpm josh latest` is never run inside a lane, whatever `latest:scope` answers there** — the command
+enforces it: `latest:scope` answers `skip` in a lane and `pnpm josh latest` refuses outright, fronted
+by `pnpm josh latest:guard`. Ask it in the primary checkout, per step 2 above.
+
+**The rewritten lock file still has to reach a pull request**, and with lanes no child runs in the
+primary checkout to carry it. `git stash` is a repository-level ref shared by every work tree:
+
+```bash
+git stash push -u -m "backlogrun: josh latest before lanes"   # primary checkout, only if the update rewrote anything
+```
+
+Record it on that first child's Issue — the comment is what gets it popped if the run dies in between.
+**The first lane's `pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes"` pops it
+by message, after `lane:open`'s own install** — never a positional `git -C "$dir" stash pop`: the stash
+is a repository-wide stack every lane shares, so a positional pop would take whichever lane last pushed.
+
+### Opening one lane and dispatching its child
+
+**One command opens the lane, prepares it, and dispatches the child — `pnpm josh lane:launch`**
+(joshuafolkken/kit#2162). It runs `lane:open`, then — only when `--stash` is given, which is the first
+lane alone — pops that stash into the lane and re-installs against the lock it brought in, then
+`lane:dispatch`. Four to six turns of the parent folded into one:
+
+```bash
+pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else; alias: josh lnla
+pid=$(pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes") || exit 1   # the first lane only, and only if `josh latest` stashed
+```
+
+`lane:launch` is a thin layer over `lane:open`, `stash:pop` and `lane:dispatch`, so each of their
+guards, refusals and messages holds unchanged; the bullets below describe the steps it runs.
+
+- **A refusal is an empty capture beside a non-zero exit**, with the reason on standard error: `full`,
+  `already-open`, and a **failed install** — which leaves a real work tree behind holding its seat, so
+  the next launch answers `already-open` and never retries. **Park that child and name
+  `pnpm josh lane:close <N>`** — a lock the lane cannot build is a state a person fixes. A refused
+  `lane:open`, a pop that refused, or a failed re-install each **stop the launch before the child is
+  dispatched**.
+- **`lane:open` installs; the `--stash` lane re-installs, and only that lane needs it.** A failed
+  install fails `lane:open`, so `lane:launch` reaching `lane:dispatch` is the guarantee the lane runs.
+- **What the pop changes is the lock, which is why that one lane installs twice.** The pop brings in
+  the `pnpm-lock.yaml` that `josh latest` rewrote, which this child's gate must build against. **A pop
+  that fails stops the lane** rather than re-installing anyway.
+- **A `<N>-lane` that already exists is attached to, and `lane:open` says so on standard error** — the
+  way back to a child parked after it pushed: a local branch of that name gets the work tree put on it,
+  and where there is none the **remote** is asked (`ls-remote`, fetched first) and the lane cut from
+  `origin/<N>-lane` where the branch survives — otherwise from the default branch. **A reused branch is
+  not a fresh lane.** Nothing deletes a branch to open a lane, so a reopen cannot cost the pushed work.
+- **Nothing switches the lane's branch** — the registry identifies a lane by that branch, so a switch
+  costs it its seat, listing and isolation, and `<N>-lane` is already a name `pnpm josh git` commits
+  from.
+- **`pnpm josh run:hold`'s preflight check is not asked in a lane; `lane:open`'s own answer replaces it.** A fresh
+  lane is clean by construction, preflight's `reclaim` arm (HEAD != default branch) is true of every
+  lane, and its recovery (`git switch <default>`) cannot run in a linked work tree. What a leftover
+  looks like here is `lane:open` answering `already-open`.
+- **`pnpm josh run:hold` is unchanged, and is claimed inside the lane** — it keys on
+  `git rev-parse --absolute-git-dir` (`.git/worktrees/<name>`), so each lane holds independently.
+
+### Handing the child over
+
+The child runs as `fullrun #<N>` in that lane, and neither `josh latest` nor a progress watcher is
+started there. Everything else — the plan, the gate, `/code-review`, `pnpm josh git`,
+`pnpm josh followup` — is unchanged, and `pnpm josh followup` releases that lane's hold at the merge.
+
+**The child is started as a process of its own, not as a subagent of this session** — `lane:launch`'s
+final step, the `lane:dispatch` it runs after the lane is opened and prepared, whose pid it returns.
+The bullets below describe that dispatch:
+
+- **It records where the child writes as it starts it** — the dispatch's own
+  `<temp>/josh-lane-dispatch-<N>.log` — so "this lane records no path" is no longer a state the hand-off
+  has to except.
+- **A refusal is an empty capture beside a non-zero exit**, and every refusal also sends a `warning`
+  Telegram — no lane open, a path that could not be recorded, a launch that failed. **Park that child
+  and name the log the message carries**; do not re-dispatch into the same lane without reading it.
+- **A child that started with nowhere to write exits zero and warns.** The launcher starts the session
+  even when it could not open the log, so the child really is running. **Poll that lane on the process
+  trace alone**, because its log will never grow.
+- **The brief the child used to be handed is now the invocation itself.** The child is started as
+  `fullrun #<N>` with the lane as its working directory. The batch a person approved by typing
+  `backlogrun` covers the child.
+- **It does not pass `--dangerously-skip-permissions`.** What the child may do is the checkout's own
+  `.claude/settings.json` to decide; a headless child reaches `gh` and merges through `pnpm josh
+  followup` without the flag, and the run reports what stopped rather than loosening it.
+
+**Start each child without blocking on it, and poll them all.** That is "A delegated unit that stopped
+without reporting" above applied N times, and `pnpm josh run:liveness <N> --output <path> --process
+alive` is read **in that child's lane**. **Run `pgrep -laf "(fullrun|run-ship-cli\.ts .*) #<N>$"`
+first and pass what it found** — `alive` where the child is there, `none` where it is not, and never
+`alive` merely because the child was dispatched. The command line carries no path; the `$` anchor
+keeps `#12` from matching a running `#123`.
+
+**`git switch main && git pull` is the parent's now, not the child's.** No lane can switch to the
+default branch, so the refresh moves to the primary checkout **before each `lane:open`** — the ref the
+lane is cut from.
+
+### Conflicts are not predicted
+
+**The child merges `origin/main` into its lane before its gate now, so this path is the fallback rather
+than the first line.** Every `fullrun` runs `pnpm josh main:merge` ahead of the gate
+(`chain-rule.md` → "origin/main is merged in before the gate", the single source), so an overlap
+already on `main` is resolved before the gate reads the tree. What this section covers is an overlap
+that lands on `main` *after* it, which `followup` still reports as a conflict.
+
+**Nothing here forecasts which children will overlap.** The overlap surfaces where GitHub already
+reports it: a pull request that conflicts with its base comes back `mergeStateStatus: DIRTY`, which
+`git-pr-checks-eval.ts` reads as a **failure** rather than polling through it — so `pnpm josh followup`
+ends that child with a named conflict in about ten seconds.
+
+**That child does not stop: it resolves the conflict in its own lane.** It is **not** counted against
+the consecutive-failure guard either way — a lost merge race is an ordinary outcome of running many
+lanes.
+
+**Nothing is at risk while it resolves, because the work is already committed and pushed.** The pull
+request holds the branch, `git merge --abort` puts the tree back, and no step below rewrites a pushed
+commit. **The merge direction is `origin/main` into the lane's branch, never a rebase** — a rebase would
+rewrite pushed commits and need a force push, which this package denies.
+
+1. **Resolve in the lane.** `git fetch origin main`, merge `origin/main` into the lane's branch, resolve
+   in place. Do not close the lane, open another, or switch its branch. **`pnpm josh lane:open` can now
+   reattach to a pushed branch**, so a lane closed by mistake here is recoverable; staying put is still
+   what keeps the run clear of the question.
+2. **Re-run the whole gate.** The tree changed, so the green recorded before the conflict is void:
+   `pnpm josh lint:related` and `pnpm josh test:related`, then `pnpm josh gate`.
+3. **Review the resolution, one round.** Brief it with `pnpm josh review:brief` and run `/code-review`
+   over the resolution diff, then require `pnpm josh review:attest --check` to answer `ok`. That round
+   is a different subject and does not spend one of the two the cap allows — `prompts/review.md` →
+   "Review round cap" carries the exception.
+4. **Conclude the merge and push it, with `pnpm josh git -y`.** Without this step nothing changes on
+   `origin`: GitHub still returns `mergeStateStatus: DIRTY`, step 5 reports the same conflict, and
+   condition 3 reads that as a second one and parks the child for good. The distributed
+   `.claude/settings.json` denies `Bash(git commit*)` and `Bash(git add*)`, so the node script is the
+   only sanctioned way. **Record the resolution on the Issue in this same step** — a comment naming the
+   conflicting paths — because condition 3 counts resolutions off the Issue comments, not off memory.
+5. **Merge**, by re-running `pnpm josh followup` exactly as before.
+
+**The safeguard is the re-run verification, not who holds the pen.** What is dangerous is unreviewed
+code merging onto a branch whose review has converged, and that happens identically whichever hand did
+the work — so routing the decision to a person does not address it, while re-running the gate and the
+review does. **In this repository routing it to a person does not even resolve it**: the user does not
+read code, so a code-level conflict handed over is a deferral rather than a decision.
+
+**The run steps back under these four conditions, and under no others. The list is exhaustive and
+carries no judgement.**
+
+1. **The resolution requires deleting the other side's change.** That decides intended behavior, not
+   text. It goes to the user as a **specification** question — "behavior A or behavior B" — never as a
+   diff.
+2. **Both sides rewrote the same lines** — overlapping, not adjacent. Read off the structure of the
+   conflict hunks, so it needs no interpretation.
+3. **A second conflict on the same child.** One resolution per child; the count is read off the Issue
+   comments step 4 writes, so it survives an interrupt.
+4. **The re-run gate did not come back green, or the resolution review returned a High.** Not only a
+   High: a lint error, a failing test or a spell-check hit that merging a moved `main` introduced is
+   this condition too.
+
+Meeting any of the four, the child is parked — `needs-decision` plus a comment naming which of the four
+it was — and its lane is **kept**, because the pushed branch is the resume path (the table below).
+
+**Leave the tree clean before parking: `git merge --abort` precedes a park under conditions 1, 2 or 4.**
+Conditions 1 and 2 are read mid-merge with conflict markers still in the tree, condition 4 after a merge
+that is resolved but not committed; condition 3 fires before any merge is started, so there is nothing
+to abort.
+
+### What happens to a lane
+
+| When | The lane | Why |
+| --- | --- | --- |
+| The child **merged** | `pnpm josh lane:close <N>` | `followup` released the hold and the branch is on `main`; nothing in that tree is wanted |
+| The child was **parked before its commit** | `git -C <dir> stash push -u -m "backlogrun: parked #<N>"`, record it on the Issue, then `pnpm josh lane:close <N>` | The stash is a repository-level ref, so it outlives the work tree — and `lane:close` is a **forced** removal that would otherwise take the work. `epic:next` counts a parked child's lane as released, so a lane left open holds a seat the count believes is free |
+| The child was **parked after its commit and push** | **Left open**, its directory and held seat recorded on the Issue | The stash step is a **no-op** (tree clean because committed). What `lane:close` would take is the **local branch**, which is the resume path |
+| The child hit a **merge conflict** | **Left open** — the resolution happens in it | The child resolves in place ("Conflicts are not predicted"). Closing it would delete the local branch the pull request carries — **`lane:open` does now put that branch back**, so a mistaken close is recoverable. A park under that section's four conditions takes the row above |
+| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work *is* the artifact a person has to look at. Name the lane directory in the stop report and in the Telegram |
+| The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count | Same reasoning; only the counter differs. **A merge conflict is not this row** — it takes the row above, and it is not counted |
+| **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child | A lane exists that no `pnpm josh …` runs in and the next `lane:open` answers `already-open`. Closing frees the seat; parking is right because the cause is one a person fixes. Carry pnpm's reason into the park note |
+| The run was **interrupted** | Nothing to do — the work tree survives on disk | The next session's `pnpm josh lane:prune` closes what git no longer has a tree for. **Park that child**, naming the lane and `pnpm josh lane:close <N>` as the way out |
+
+**A committed child's lane is kept because it is the cheapest resume, not because closing it is final.**
+`lane:close` follows the work-tree removal with `git branch -D <N>-lane` (the force flag is there so an
+unmerged lane branch goes too), and resume is a re-run of `pnpm josh followup`, which reads the branch
+**locally** (a `git diff` against the merge base) — so with no local branch the gate cannot be
+re-evaluated. Keeping the lane is worth a seat: the tree, the branch and its `node_modules` are still
+there, and the resume is one command.
+
+**What is no longer true is that closing it is unrecoverable.** `pnpm josh lane:open <N>` now attaches
+to a `<N>-lane` that exists locally and creates one from `origin/<N>-lane` where only the remote has it,
+saying on standard error which it reused. So a lane closed after a push is reopened rather than lost.
+**The branch still has to have reached the remote for that to hold** — a child parked before its commit
+has nothing on `origin`, which is why that row stashes first and this one does not.
+
+**Which row a child takes is decided by what `followup` printed, not by reading the situation.** **What
+it prints is `PR checks failed (merge conflict)`** — that string is what reaches you;
+`mergeStateStatus: DIRTY` is the internal spelling `git-pr-checks-eval.ts` compares against, never an
+output line to search for. That string sends the child to resolve the conflict in the lane it is
+standing in. Do not grep the output for `mergeable_state`: that is the REST field name, normalized away
+before anything prints it. **Every after-commit park now keeps its lane, with no exception left in this
+table.**
+
+**A kept lane holds its seat, and that is the price rather than an oversight.** Seats are read back out
+of the live work trees, so `lane:open` answers `full` rather than handing out ports twice. The optimism
+is `epic:next`'s — it counts a parked child as having released its lane — and it costs one child offered
+that cannot get a lane, which is visible and recoverable. **Say it in the park comment**: the lane
+directory, that its seat is held, and `pnpm josh lane:close <N>` as the way to give it back.
+
+**Release the hold on either parked arm, and leave the lane before closing it.** `pnpm josh followup`
+releases the working-tree hold at the **merge**, so a parked child's is still held: run
+`pnpm josh run:release <N>` in the lane — **a release names the run it belongs to**, and the child's own
+number is what that record carries. **A `needs-human-review` stop is not a park and keeps its hold.**
+`lane:close` does not release the hold for you — the record is keyed to the work tree's git directory,
+so removing the tree strands it. And `cd` out of the lane **before** `pnpm josh lane:close <N>`: the
+close removes the directory the shell is sitting in.
+
+**A `needs-human-review` stop ends the run, and the lanes already in flight are allowed to finish.** No
+new lane is opened, but killing units mid-gate would strand as many trees as there are lanes. When the
+others have merged or parked, report and stop.
+
+### CI concurrency
+
+Past a GitHub account's concurrency entitlement, jobs **queue** rather than fail, which could cancel out
+what the lanes bought; **`JOSH_LANE_LIMIT` lowers the ceiling with no code**. `ci.yml`'s concurrency
+group is keyed on `${{ github.ref }}`, so N lanes on N branches are N independent groups and no lane
+cancels another's run. Whether queueing bites is read from the multi-day backlog timing report — a
+`checks-wait` that grows with the lane count is the queueing.

package/.claude/skills/workflow-commands/backlogrun-park.md

@@ -0,0 +1,179 @@
+# `backlogrun` — a child that cannot finish
+
+**Read this file in full when a child cannot finish** — before parking it, before a
+`needs-human-review` stop, or before recording a mid-run prerequisite or split. It is a point-of-use
+document, never an entry read: the entry procedure is `backlogrun.md`, which points here at that
+moment (joshuafolkken/kit#2010). This file is the single source of park-and-continue, the
+`needs-human-review` stop, a stale `in-progress`, a prerequisite discovered mid-run, and a mid-run
+split.
+
+## What happens to a child that cannot finish
+
+Nothing here is new, and nothing here is restated — a `backlogrun` child is a `fullrun` under a batch
+authorization, whether it came from a named epic or from the opted-in pool:
+
+- **A stop that would end the run parks one issue and the run continues** — → "park
+  and continue", which is that rule's single source, including what happens to the issue's lane.
+- **A prerequisite discovered mid-run is recorded as a dependency rather than parked** —
+  → "A prerequisite discovered mid-run", and `SKILL.md` → §2d for the three-way
+  distinction between a prerequisite, a split and an upstream defect. **One thing is genuinely
+  different**: with no epic, there is no `pnpm josh epic --add` to record the ordering into, so the
+  prerequisite is filed with `route:tier-a` and the blocked issue is parked with `needs-decision`
+  naming it. The parked issue returns to the pool when a person clears the label, and the
+  prerequisite is offered on the next ask if it carries `auto-ok`.
+- **A split found mid-run** files the children and the epic and does not stop the batch, because the
+  keyword already authorized a batch — `split-assessment.md` for the assessment, → "Splitting a child
+  mid-run" for the branch. The split child is not parked or counted as a failure; its new children
+  remain available to the normal `backlog:next` / `epic:next` offer.
+- **`in-progress` left behind by an interrupted run** is → "`in-progress` is removed by
+  whoever finds it stale".
+- **A child released from `needs-decision` is re-dispatched to a lane, never implemented by the
+  parent.** The parent is an orchestrator: → "The parent orchestrates and never
+  implements a child in its own context" is the single source, and → "Removing the label
+  is Tier A" carries the re-dispatch itself. A released child takes a lane exactly as any batch child
+  does.
+
+## `needs-human-review` — the one stop that is not a park
+
+A child carrying **`needs-human-review`** is degraded to a `halfrun`-shaped stop and **the whole run ends
+there** — implementation and the verification gate run, nothing is committed, the working tree is left
+dirty and unstashed, a `confirmation` Telegram carrying the resume command goes out, and the remaining
+children are not started.
+
+**This is the exception to park-and-continue below, and it is not an oversight.** Parking works because
+the parked child leaves the checkout clean; this child does not. Its uncommitted work is the artifact a
+person has to look at — which is why the alternative that kept the batch running (commit, open a PR,
+merge nothing) was rejected: it satisfies "a person approves publication" and fails "a person chooses".
+
+**The child goes on holding its repository.** `needs-decision` outranks `in-progress` in the
+per-repository exclusion so a parked child releases the checkout; this label deliberately does not,
+because releasing it would start the next child on top of uncommitted work. **Its lane is left open and
+untouched**, for the same reason. **Name the lane directory in the stop report and in the Telegram** — a
+person told to look at a working tree and not told which one has been told nothing. The lanes already in
+flight finish; no new lane is opened.
+
+**Never apply or remove the label** — `auto-ok`'s rule, at `auto-ok`'s strength. Full definition and the
+`needs-decision` comparison: `SKILL.md` → §2z, which is the single source.
+
+## park and continue
+
+When a child hits something this run may not decide — a Tier B toss-up, a Tier C action, an upstream
+defect, a split that needs a person — **park the child and keep going.**
+
+```bash
+gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'
+pnpm josh issue:comment <N> --body-file <path>   # what needs deciding, and the options
+```
+
+`in-progress` is left as it is, and the parked child does **not** hold the repository — `epic:next` gives
+`needs-decision` precedence over `in-progress`, so the next child is offered normally. Then return to
+step 1; the other children are unaffected unless they depend on this one.
+
+**What happens to a parked child's lane depends on whether it had committed, and the two answers are
+opposite.** **Parked before its commit**, the lane is stashed and closed:
+`git -C <dir> stash push -u -m "backlogrun: parked #<N>"`, the stash recorded on the Issue, then
+`pnpm josh lane:close <N>` (`epic:next` counts a parked child's lane as released, and `lane:close`
+removes the work tree by force). **Parked after its commit and push**, the lane is *kept*: nothing to
+stash, and closing would delete the local branch the resume needs. **A lost merge race is not one of
+these rows** — it resolves in its lane ("Conflicts are not predicted" above), and parks only under that
+section's four conditions, which take the after-commit row. Both rows and the `pnpm josh run:release
+<N>` every parked ending owes are "What happens to a lane" above, the single source.
+
+**Parking replaces stopping the session, not the rule that produced the stop.** An upstream defect is
+still filed immediately and unconditionally (Tier A for a first-party target), and a workaround is still
+forbidden. **A placement choice is not one of the things this run may not decide.** `epic:bundle`'s
+`ask` is Tier A: choose the epic you recommend, add it with `pnpm josh epic --add <E> <N> --after <M>`,
+and record the decision on both the new Issue and that epic's `## Decisions`. What remains a park is a
+genuine toss-up between two equally apt epics, and that is rare.
+
+**Removing the label is Tier A — do it without asking.** When the decision is recorded (to the epic's
+`## Decisions`), remove the label; the state is on GitHub, so the run picks up where it left off.
+
+```bash
+gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/needs-decision 2>/dev/null || true
+```
+
+**The released child goes back to a lane, never into the parent's own context.** A parent that is
+*already* running, and clears a label mid-run because a person just answered, dispatches it the same way
+rather than picking up its diff itself — `pnpm josh lane:open <N>` then `pnpm josh lane:dispatch <N>`. A
+parent that implements the released child inline is the failure the orchestrator rule is written against:
+"The parent orchestrates and never implements a child in its own context" above.
+
+Without removing the label the parked child never runs again — it is the second half of the
+human-in-the-loop cycle, not an optional tidy-up.
+
+## `in-progress` is removed by whoever finds it stale
+
+Nothing in the codebase removes `in-progress`; a normal finish closes the issue. An interrupted run
+leaves it behind, and a child that carries it is excluded from every future `epic:next` — permanently.
+**A session that detects a stale child removes the label itself** (Tier A) and reports it, before
+continuing the loop.
+
+**It costs more than that one child now.** An open issue carrying `in-progress` occupies one of the
+repository's lanes — whichever epic it belongs to — so a stale label narrows every epic that touches
+that checkout. **The rule therefore applies to any open issue in the repository, not only to this epic's
+children**, and `epic:next` names the holders on standard error. **Age alone is not the test.** Check the
+90-minute window below *and* look at what is holding it, because three states hold the label legitimately
+for longer: a `halfrun` stopped for manual verification, any run paused mid-child, and a child stopped by
+`needs-human-review` (which waits on a person reading an artifact, and carries its own label alongside
+`in-progress`). **All three leave uncommitted work in the checkout**, so `git status` there is the
+decisive read: a dirty tree means the hold is real — leave the label alone and report, never strip it and
+start a second child on top of that work.
+
+**A closed issue's labels are neither a finding nor something to clean up.** A closed issue holds no lane
+(`epic-busy.ts` counts holders from the open listing alone) and `epic:next` never offers it, so
+`in-progress` left behind on one changes nothing. **Do not report it, and do not strip it** — a report is
+read as something that needs attention, so a run that lists non-findings is a run whose real findings are
+harder to see.
+
+```bash
+gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true
+```
+
+## A prerequisite discovered mid-run
+
+Finding that something else in **this** repository has to land first is not a split, and not an upstream
+defect. The child in hand is still one deliverable; it just needs another one before it. The three-way
+distinction, the `route:tier-a` filing command and the filing ceiling are `SKILL.md` → §2d, the single
+source; what follows is this entry's branch.
+
+`<M>` below is the child being implemented when the prerequisite turned up; `<N>` is the new Issue.
+
+1. File the prerequisite Issue `<N>` with the `route:tier-a` label — Tier A for a first-party
+   repository, no confirmation. It is filed **first** because the next step names it.
+2. **Stash the work in progress.** A child is implemented on the default branch with an uncommitted tree,
+   so `<M>`'s half-finished edits are sitting there, and the next child's `git switch main && git pull`
+   would refuse or carry them into the prerequisite's branch and PR.
+
+   ```bash
+   git stash push -u -m "backlogrun: paused #<M> for prerequisite #<N>"
+   pnpm josh issue:comment <M> --body-file <path>   # what was stashed, and that #<N> must land first
+   ```
+
+   **`-u` is not optional** (a new `*.test.ts` is untracked). The comment makes the paused state
+   auditable and tells the session that resumes `<M>` a stash is waiting. **Pop it by message, never by
+   position** — `pnpm josh stash:pop "backlogrun: paused #<M> for prerequisite #<N>"` — when `epic:next`
+   offers `<M>` again, after its `git switch main && git pull`. The stash is a repository-wide stack
+   every lane shares, so a bare `git stash pop` would take whichever lane last pushed; the message
+   targets this one. The prerequisite has merged by then, so expect to resolve conflicts.
+
+3. `pnpm josh epic --add <E> <N> --before <M>` — one command writes the task-list row, the declaration
+   and the `blocked-by` relation together. Never edit the body by hand: the declaration and the relations
+   then disagree, `epic:next` returns `error`, and the unattended run stops.
+4. **Remove `in-progress` from `<M>`** — `gh api -X DELETE repos/{owner}/{repo}/issues/<M>/labels/in-progress 2>/dev/null || true`.
+   This is what lets `<M>` run again: `epic:next` classifies a child carrying `in-progress` as waiting on
+   time **before** it looks at any blocker, so a child left labelled is never offered again.
+5. **Do not park.** Go back to step 1 of the loop. `epic:next` classifies the original child as resolving
+   on its own and hands back the prerequisite first, so the order is kept with no human input.
+
+**Parking is only for a prerequisite that cannot be expressed as a dependency** — one that needs a design
+decision nobody has made, or that is a Tier B toss-up or a Tier C action. Parking one that *can* be
+expressed inverts the whole point: `needs-decision` is cleared by a person.
+
+## Splitting a child mid-run
+
+Discovering that a child is really several is not a reason to stop. File the new children with the
+`route:split` label (Tier A for a first-party repository — no confirmation), then add them with
+`pnpm josh epic --add <E> <N...> [--before <M> | --after <M>]` rather than editing the epic body by hand.
+Use the same split criteria as `kickoff`. If what remains of the original child needs a person, park
+**that** child and move on. Splitting alone never adds `needs-decision` to the promoted epic.