@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -1,21 +1,11 @@
 # `backlogrun` — lanes and concurrency
 
-Point-of-use, read one section at a time from `backlogrun.md` → "The route table". Reasons:
-
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why the lane ceiling is shaped the way it is"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why CI concurrency is capped by the lane limit"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why a lane's review needs a brief and an attestation"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why the lane branch is `<N>-lane` and never switched"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why lanes cost as well as buy throughput"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why `lane:launch` folds the lane steps into one"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Why a committed child's lane is kept"
-- `docs/maintainers/backlogrun-lanes-rationale.md` → "Where each rule came from"
+Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow".
 
 ## Concurrency: as many children per repository as it has free lanes
 
-**One session per repository**, each running only its own repository's children. The lane ceiling is
-`.claude/skills/epic-commands/SKILL.md` → "An `in-progress` issue occupies a lane"; a dependency that
-crosses a repository is `.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories".
+**One session per repository**, each running only its own repository's children. The lane ceiling and a
+dependency that crosses a repository are `docs/josh-commands-backlog.md` → "`josh epic:next`".
 
 ## A solo run
 
@@ -25,11 +15,15 @@ merged. **Decide it from three conditions that must all hold, never from how ser
 it a defect (not an improvement, refactor, removal or feature)? Is it in kit's own verification gate
 (lint / type check / spell check / unit tests), the code review, the pre-push hook, or the merge
 checks — not a consumer repository's CI or template? Does it, on `main` now, make unrelated PRs
-answer wrongly (a false green or a false red)? All three, and the issue carries `run:solo`; any one
-missing, and it carries `run:lane`. `backlog:next` and `epic:next --lanes` answer `triage` for an
-issue with neither, so a filed issue carries one of the two from its filing. **It stops the other
-lanes for one reason only: a batch run on broken verification leaves nobody's result trustworthy.**
-This section is the rule's single source; why: `docs/maintainers/wip-cap-rationale.md` → "Why a solo run".
+answer wrongly (a false green or a false red) **on every run**? All three, and the issue carries
+`run:solo`; any one missing, and it carries `run:lane`. `backlog:next` and `epic:next --lanes` answer
+`triage` for an issue with neither, so a filed issue carries one of the two from its filing. **It stops
+the other lanes for one reason only: a batch run on broken verification leaves nobody's result
+trustworthy.**
+
+**A wrong answer that only comes some of the time — a flaky test, a timeout under load — is not a solo
+run.** It carries `run:lane` and `priority:critical`, so it leads the next offer while the other lanes
+keep running: a flake costs another lane one rerun, less than every lane stopped until it merges.
 
 ## Lanes — running more than one child at a time
 
@@ -41,7 +35,7 @@ stay serial.**
 
 **A lane child may cut its own turn before the gate** — `pre-gate-cut.md`, the single source. The
 child is told apart from a person, and handed its resume stage, by `JOSH_LANE_CHILD`
-(`pre-gate-cut.md` → "The dispatch mark" and "The stage is passed to the resumed child").
+(`docs/josh-commands-run.md` → "`josh run:cut`"; `pre-gate-cut.md` → "The stage is passed to the resumed child").
 
 **A lane's review does not inherit the lane, and `pnpm josh review:brief` is what closes that**: it
 prints the lane's root, branch and HEAD, targets written `git -C <root> …`, and a nonce the review
@@ -57,14 +51,14 @@ are not predicted").
 
 ### Once per repository, before the first lane opens
 
-In the **primary checkout**, in order, never per lane: `pnpm josh ms`; `pnpm josh latest:scope` and the
-update on `required` (`backlogrun-child.md` → "`josh latest` runs once per session, not once per
+In the **primary checkout**, in order, never per lane: `pnpm josh ms`; `pnpm josh latest:if-required`
+(`backlogrun-child.md` → "`josh latest` runs once per session, not once per
 child"); `pnpm josh lane:prune`; `pnpm josh run:tidy`.
 
 **The rewritten lock file reaches a pull request through the first lane.** Only if the update rewrote
-anything: `git stash push -u -m "backlogrun: josh latest before lanes"` in the primary checkout, and
+anything: `pnpm josh stash:push "backlogrun: josh latest before lanes"` in the primary checkout, and
 record it on the first child's Issue. **The first lane's `pnpm josh lane:launch "$n" --stash
-"backlogrun: josh latest before lanes"` pops it by message** — never a positional `stash pop`. **Under
+"backlogrun: josh latest before lanes"` pops it by message.** **Under
 `backlog:drive` the driver passes `--stash`, never you**; the push stays the parent's.
 
 ### Opening one lane and dispatching its child
@@ -77,7 +71,7 @@ pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothi
 
 | It answers | What the run does |
 | --- | --- |
-| a pid | The child runs; poll it |
+| a pid | The child runs; wait on it with `lane:await` |
 | empty, non-zero, `full` | No free lane; wait for one |
 | empty, non-zero, `already-open` or a failed install | **Park that child and name `pnpm josh lane:close <N>`** — a lock the lane cannot build is a person's to fix |
 | `lane:open` reports a reused `<N>-lane` on stderr | The way back to a child parked after it pushed — **a reused branch is not a fresh lane** |
@@ -96,14 +90,15 @@ Everything else is unchanged; `pnpm josh followup` releases the lane's hold at t
 - **It records where the child writes** — `<temp>/josh-lane-dispatch-<N>.log`.
 - **A refusal is an empty capture beside a non-zero exit**, with a `warning` Telegram. **Park that
   child and name the log the message carries**; never re-dispatch into the same lane without reading it.
-- **A child that started with nowhere to write exits zero and warns** — **poll that lane on the
-  process trace alone**.
+- **A child that started with nowhere to write exits zero and warns** — **wait on that lane with
+  `lane:await`, which reads the process trace alone**.
 - **The child is started as `fullrun #<N>` with the lane as its working directory**; the typed
   `backlogrun` covers it.
 - **It passes `--permission-mode bypassPermissions`, never `--dangerously-skip-permissions`.**
   `.claude/settings.json`'s `deny` list still refuses what it names; report what stopped, never loosen it.
 
-**Start each child without blocking on it, and poll them all** — a silent one is
+**Start each child without blocking on it, then wait on `backlog:drive` or `lane:await`**
+(`scripts/run/run-poll-hook.ts`) — a silent one is
 `backlogrun-recovery.md` → "A delegated unit that stopped without reporting", read in that child's lane.
 
 **`pnpm josh ms` is the parent's now, not the child's** — run it in the primary checkout **before
@@ -122,7 +117,7 @@ read `backlogrun-recovery.md` → "Conflicts are not predicted" when `pnpm josh
 | The child was **parked before its commit** | **Left open**, its uncommitted work in place, its directory and held seat recorded on the Issue | The shared stash stack is unsafe; `lane:close` is a **forced** removal. `pnpm josh lane:launch <N>` re-dispatches into the kept lane (a failed-install lane is still refused) |
 | The child was **parked after its commit and push** | **Left open**, its directory and held seat recorded on the Issue | `lane:close` would take the **local branch**, the resume path |
 | The child hit a **merge conflict** | **Left open** — the resolution happens in it | `backlogrun-recovery.md` → "Conflicts are not predicted"; a park there takes the row above |
-| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work is what a person looks at. Name the lane directory in the stop report and Telegram |
+| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work is what a person looks at. `run:hold <N> --human-review-stop` names the lane directory in the Telegram; the stop report names it too |
 | The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count | **A merge conflict is not this row**, and is not counted |
 | **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child | Frees the seat; a person fixes the cause. Carry pnpm's reason into the park note |
 | The lane is **spent** — no child working in it, its Issue closed, not one this run launched and has not collected with `run:merge`, a clean tree, no commit that is on no remote | Nothing to do — `pnpm josh lane:prune` closes it | Any other lane is kept, with the reason on standard error |

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

@@ -1,10 +1,7 @@
 # `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. Point-of-use, never an
-entry read (`backlogrun.md` points here). Single source of park-and-continue, the `needs-human-review`
-stop, a stale `in-progress`, a mid-run prerequisite and a mid-run split. Provenance:
-`docs/maintainers/backlogrun-park-rationale.md` → "Where each rule came from".
+`needs-human-review` stop, or before recording a mid-run prerequisite or split.
 
 ## What happens to a child that cannot finish
 
@@ -31,13 +28,12 @@ parks, re-dispatches or files.
 ## `needs-human-review` — the one stop that is not a park
 
 A child carrying **`needs-human-review`** stops `halfrun`-shaped and **the whole run ends there**:
-implementation and the gate run, nothing is committed, the tree is left dirty and unstashed, a
-`confirmation` Telegram carries the resume command, and the remaining children are not started.
-Rationale: `docs/maintainers/backlogrun-park-rationale.md` → "Why `needs-human-review` ends the run
-instead of parking".
+implementation and the gate run, nothing is committed, the tree is left dirty and unstashed,
+`pnpm josh run:hold <N> --human-review-stop` sends the `confirmation` Telegram with the resume command
+and the lane directory, and the remaining children are not started.
 
 **The child goes on holding its repository**, and **its lane is left open and untouched**. **Name the
-lane directory in the stop report and in the Telegram.** Lanes in flight finish; no new lane opens.
+lane directory in the stop report.** Lanes in flight finish; no new lane opens.
 
 **Never apply or remove the label** — a person's alone (`needs-human-review.md`, the single source).
 
@@ -47,8 +43,7 @@ When a child hits something only a person can decide (→ "Only a person's judge
 `needs-decision`"), **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
+pnpm josh run:park <N> --body-file <path>   # what needs deciding, and the options; applies needs-decision
 ```
 
 `in-progress` stays; the parked child does **not** hold the repository (`needs-decision` takes
@@ -65,7 +60,7 @@ still filed at once, and a workaround is still forbidden. `epic:bundle`'s `ask`
 **Removing the label is Tier A — do it without asking**, once the decision is recorded:
 
 ```bash
-gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/needs-decision 2>/dev/null || true
+pnpm josh run:park <N> --clear   # succeeds when the label is already off
 ```
 
 **The released child goes back to a lane, never into the parent's own context** — `pnpm josh
@@ -86,12 +81,13 @@ It never carries:
 - a wait for the next published release — a dependency, `pnpm josh issue:release <N> --wait`
   (`prerequisite.md`);
 - a defect in the running repository's own run tooling — the run fixes it and resumes
-  (`prompts/collaboration-workflow/upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合").
+  (`prompts/collaboration-workflow/upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合");
+- a wait on an open blocker or a start date — `run:merge` releases it (`run-merge-steps.ts`);
+- a mechanical failure — the driver applies `run:stalled` (`RUN_STALLED_LABEL` in `issue-labels.ts`).
 
 **When in doubt, it is Tier A**: decide, comment the decision, and continue. **A label a mechanical step
 applied** (a failed or abandoned child, a lost merge race) is read against this list once its reason is
-known, and removed when the reason is not on it. Rationale:
-`docs/maintainers/backlogrun-park-rationale.md` → "Why a run spends no attention on a non-finding".
+known, and removed when the reason is not on it.
 
 ## `in-progress` is removed by whoever finds it stale
 
@@ -120,22 +116,11 @@ Something else in **this** repository has to land first: not a split, not an ups
 
 1. File the prerequisite `<N>` with `route:tier-a` (Tier A, first-party, no confirmation) — **first**,
    because the next step names it.
-2. **Stash the work in progress**:
-
-   ```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** (new test files are untracked). **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 `pnpm josh ms`; expect conflicts.
-3. `pnpm josh epic --add <E> <N> --before <M>` — row, declaration and `blocked-by` in one command;
-   never a hand edit. **With no epic**, record `<M>` blocked by `<N>` alone with the `gh api
-   …/dependencies/blocked_by` call in
-   `prompts/collaboration-workflow/issue-template.md` → "複数 Issue に分割するときの epic Issue", step 4.
-4. **Remove `in-progress` from `<M>`** — `pnpm josh run:release <M>`; a labelled child is never offered again.
-5. **Do not park.** Back to step 1 of the loop; `epic:next` hands back the prerequisite first.
+2. **`pnpm josh run:pause <M> --for <N>`** — the stash, the comment naming its `stash:pop`, `<M>`
+   blocked by `<N>` (the epic's row and declaration too) and `run:release <M>` in one call
+   (`prerequisite.md`). Pop the stash the comment names when `epic:next` offers `<M>` again, after its
+   `pnpm josh ms`; expect conflicts.
+3. **Do not park.** Back to step 1 of the loop; `epic:next` hands back the prerequisite first.
 
 **A stop a dependency can express is never parked**, including a defect in this repository's own gate
 or run tooling — `prerequisite.md`.

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

@@ -1,14 +1,11 @@
 # `backlogrun` — progress, the hand-off, resume and waiting
 
-Point-of-use, read one section at a time from `backlogrun.md` → "The route table"; the heartbeat is `progress-watcher.md` → "Progress while the run is quiet".
+Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow"; the heartbeat is `progress-watcher.md` → "Progress while the run is quiet".
 
 ## Running a named epic's children
 
-**`backlog:drive` walks this loop on its own; a session runs it when the driver hands back `epic #N`**
-(the loop: `docs/maintainers/backlogrun-driver.md`; rationale:
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why a named epic's children run in lanes";
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives in records, not the
-conversation"). Each child runs as `fullrun #<N>` in a lane —
+**`backlog:drive` walks this loop on its own; a session runs it when the driver hands back `epic #N`.**
+Each child runs as `fullrun #<N>` in a lane —
 `pnpm josh lane:launch <N>` (`backlogrun-lanes.md` → "Opening one lane and dispatching its child"),
 then `pnpm josh lane:await <N...> --owner "$PPID"` in the background — and every ending is read by one
 command:
@@ -20,10 +17,7 @@ next=$(pnpm josh run:merge <N> --epic <E> --repo <owner/repo> --owner "$PPID" --
 **`pnpm josh run:merge <N>` is the only reading of how a child ended** — never
 classify `issue:state` by hand or ask `epic:next` in its place. **Pass `--output <path>`, the child's
 transcript**; the named-epic flags are dropped for the opted-in backlog. It classifies, counts, closes
-the lane and comments itself; act on the token. Rationale:
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why a child's ending is read by `run:merge` alone";
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why a child's ending is classified at once";
-provenance of each rule: `docs/maintainers/backlogrun-progress-rationale.md` → "Where each rule came from".
+the lane and comments itself; act on the token.
 
 | It prints | What the run does |
 | --- | --- |
@@ -32,7 +26,7 @@ provenance of each rule: `docs/maintainers/backlogrun-progress-rationale.md` →
 | `complete` | Record the root done (`backlogrun-steps.md` → "The session cut is inside the invocation") and post the epic summary |
 | `over` | Hand the lanes over and take the cut — "The hand-off" below |
 | `human-review` | Stop, leave `in-progress` on; send a `confirmation` only where the child ran in this session's own context (`needs-human-review.md`) |
-| `stop` / `environment` | Report the parked children (or the outage) and stop |
+| `stop` / `environment` | Report the parked children (or the outage, or the `/login` an authentication failure needs) and stop |
 | `resumed` | `lane:await <N>` it again |
 | `retry` / `busy` | Re-read the child |
 
@@ -52,8 +46,7 @@ after every child's merge and `pnpm josh ms`, never wired to `pnpm josh delegate
 carrying the budget** (`backlogrun-steps.md` → "The session cut is inside the invocation"); it is not a
 stop. The threshold is `CONTEXT_CUT_THRESHOLD` in `scripts/cost-runtime/context-cut-threshold.ts`
 (135,000, shared by the scheduler entry, hand-off and the lane worker cut, `pre-gate-cut.md` → "The
-implementation-phase cut"). Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the
-hand-off check is asked at every merge".
+implementation-phase cut").
 
 | It answers | What the run does |
 | --- | --- |
@@ -72,12 +65,11 @@ and output path; fill a missing path with `pnpm josh lane:output <N> <path>`:
   closed by `pnpm josh lane:prune`.
 - **Every in-flight lane records a path** — count everything, run `pnpm josh run:carry --cut --owner
   "$PPID"`, post the progress comment naming every lane and its path with `pnpm josh run:board`, and end
-  the turn; the `run:wake` driver polls the lanes. Rationale:
-  `docs/maintainers/backlogrun-progress-rationale.md` → "Why lanes are handed over rather than drained".
+  the turn; the `run:wake` driver polls the lanes.
 - **`--cut` answers `capped`** (`MAX_CUTS`) — **do not `run:wake` or hand off**;
   carry this session on and re-ask at the next merge.
 
-The hand-off report's format is `backlogrun-handoff-report.md`. **This is not a failure and not a
+The hand-off report is `pnpm josh run:report --handoff` (`backlogrun-handoff-report.md`). **This is not a failure and not a
 park** — nothing is labelled, stashed or filed.
 
 ## Resuming after a cut
@@ -88,7 +80,7 @@ park** — nothing is labelled, stashed or filed.
 ### Picking the lanes up in the fresh session
 
 **Start no child again and open no lane already open.** In one turn: `pnpm josh lane:list` (a line
-with a path is a handed-over child, polled per `backlogrun-recovery.md` → "A delegated unit that stopped
+with a path is a handed-over child, waited on per `backlogrun-recovery.md` → "A delegated unit that stopped
 without reporting"), `pnpm josh run:progress --wait --output <handed-over paths>` in the background
 (`run:watcher:guard`), `pnpm josh run:liveness`, and `epic:next --lanes`, a lane per child it offers.
 **A carried-over child finishes in its own unit — never run its `followup` yourself**; one lost in the
@@ -104,15 +96,14 @@ the epic body; what merged the epic's task list.
 
 | Setting | Value | Meaning |
 | --- | --- | --- |
-| Polling interval | 60 s | **In flight, a floor between two asks, never a clock** — the wake is `lane:await`'s completion or the watcher's arrival exit, never a report. **With nothing in flight no wake comes: it is the parent's own clock.** A `backlogrun` idle watch is polled at this same interval. |
+| Re-ask floor | 60 s | **In flight, never a clock — the wait is `backlog:drive` or `lane:await`**, and the wake is their exit or the watcher's arrival exit, never a report; a state read repeated with nothing decided in between is refused. **With nothing in flight no wake comes: it is the parent's own clock.** A `backlogrun` idle watch re-asks at this same floor. |
 | Silent delegated unit | 30 min | Not the child's duration — the time its output has gone **unchanged**. Past it, ask `run:liveness` and book a stopped unit as a failure. |
 | Stale `in-progress` | 90 min | Past it, the other session is gone. |
 | Publish wait | 10 min | `josh propagate`'s own budget. A failed publish never appears. |
 | `backlogrun` idle watch | 8 h | Counted from when the run's hands became free, never from its start; `pnpm josh backlog:budget` decides it. |
 
-Each timeout **ends the wait and reports** — none is retried indefinitely. Rationale for the figures:
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
-clock". A stale child's label is removed first, so the next poll can offer it. **A graph that has
+Each timeout **ends the wait and reports** — none is retried indefinitely. A stale child's label is
+removed first, so the next ask can offer it. **A graph that has
 deadlocked on a cycle is not this loop's to untangle**: `epic:next` detects it and exits with an error.
 
 ## Who sends the summary, and who propagates

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

@@ -4,7 +4,8 @@ Point-of-use, read one section at the failure that reaches it; the single source
 
 ## A delegated unit that stopped without reporting
 
-**A stop from outside leaves no notification behind, so the parent polls rather than waits.** Record
+**A stop from outside leaves no notification behind, so the parent waits on `lane:await`, whose exit
+covers it.** Record
 where a lane child writes with `pnpm josh lane:output <N> <path>` in the dispatch turn, and once its
 output has been unchanged for the silent-unit window (`backlogrun-progress.md` → "Waiting, and never
 waiting forever") **ask the command rather than combining the traces yourself**, in the checkout the
@@ -18,28 +19,28 @@ pnpm josh run:liveness <N> --output <absolute path> --process <command lines nam
 
 | Answer | What the parent does |
 | --- | --- |
-| `alive` | Keep polling; touch nothing |
+| `alive` | Wait on `lane:await` again; touch nothing |
+| `paused` | Tell the person; neither wait nor recover (`docs/josh-commands-run.md` → `josh run:liveness`) |
 | `settled` | Re-read with `pnpm josh run:status <N>` and take the branch its state section says |
 | `undetermined` | Read the trace that failed and ask again. **A second in a row on the same child is a fault in the check**: send a `confirmation` naming the trace and stop — never escalate it to `stopped` |
 | `stopped` | The recovery below |
 
-Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why liveness needs silence and no
-process together".
-
 **On `stopped`, re-read with `pnpm josh run:status <N>`.** **A re-read carrying `needs-decision`** — the
 unit parked it, then stopped: leave the label on and count nothing. Otherwise, while `state: OPEN`:
 
-1. **Stash the half-finished work** — `git stash push -u -m "backlogrun: stopped unit for #<N>"` — and
-   record it on the Issue; it is popped by message, `pnpm josh stash:pop "backlogrun: stopped unit for
-   #<N>"`, never positionally.
+1. **Stash the half-finished work** — `pnpm josh stash:push "backlogrun: stopped unit for #<N>"` — and
+   record it on the Issue; it is popped with `pnpm josh stash:pop "backlogrun: stopped unit for #<N>"`.
 2. **Classify and act in one call** — `pnpm josh run:merge <N> --output <path>` (`--epic <E> --repo
    <owner/repo> --owner "$PPID"` for a named epic), **the same composite a returned child takes**. It
    tells an `outage` (re-dispatched with its session resumed, uncounted, bounded by
-   `CONSECUTIVE_OUTAGE_LIMIT`) from an `abandoned` child (parked `needs-decision` and counted), and drops
+   `CONSECUTIVE_OUTAGE_LIMIT`) from an `abandoned` child (parked `run:stalled` and counted), and drops
    the stale `in-progress` itself.
 3. **Act on the token it printed** — `backlogrun-progress.md` → "Running a named epic's children".
 
-Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why the poll routes through `run:merge`".
+## A person withdraws a running child
+
+On a person's instruction to drop a running child, run `pnpm josh lane:withdraw <N>
+--reason "<their reason>"` — `docs/josh-commands.md` → "`josh lane:withdraw`".
 
 ## Conflicts are not predicted
 
@@ -51,8 +52,7 @@ 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**, uncounted by the
 consecutive-failure guard. **The merge direction is `origin/main` into the lane's branch, never a
-rebase**; no step rewrites a pushed commit (`docs/maintainers/backlogrun-recovery-rationale.md` → "Why a
-conflict is resolved in the lane rather than handed to a person").
+rebase**; no step rewrites a pushed commit.
 
 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.

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

@@ -1,14 +1,6 @@
 # `backlogrun` — the detailed procedure behind the manifest
 
-Point-of-use, read one section at a time from `backlogrun.md` → "The route table"; how the driver runs the loop on its own is `docs/maintainers/backlogrun-driver.md`. Reasons:
-
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the authorization boundary is shaped this way"
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Why a session cut does not end the run"
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan and the decision pass come first"
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the loop's contract is shaped this way"
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the idle watch lasts 8 hours from when the hands became free"
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the cost check skips a watch"
-- `docs/maintainers/backlogrun-steps-rationale.md` → "Where each rule came from"
+Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow".
 
 ## What one invocation approves
 
@@ -28,13 +20,13 @@ judgement** — a Tier B toss-up or a Tier C action inside it; `--no-auto-ok` wi
 
 ### The brake that replaces the promise
 
-**Every bound is counted in the carry record rather than in the conversation:**
+**Every bound is counted by a record or a guard rather than in the conversation:**
 
 | The bound | What it limits | Counted by |
 | --- | --- | --- |
 | `--max` | merges per invocation — a run's own filing competes for it | `run:carry --merged` |
 | `--idle` (8 hours unless typed) | how long the run waits once nothing can proceed | `--active`, the moment its hands became free |
-| **Ten filings per invocation** | additions to the pool on **every** filing route (`prerequisite.md`) — `route:tier-a`, `route:interrupt` and a review branch-2 filing are exempt from the depth test (`observation-filing.md`), never from this ceiling | `run:carry --filed` |
+| **Ten filings per run** | additions to the pool on **every** filing route (`prerequisite.md`) — `route:tier-a`, `route:interrupt` and a review branch-2 filing are exempt from the depth test (`observation-filing.md`), never from this ceiling | `scripts/rules/filing-cap.ts` |
 | The WIP cap on open issues | the pool across invocations | `prompts/collaboration-workflow/wip-cap.md` |
 
 **This section is the single source of how the `epic:bundle` obligation and this boundary meet.**
@@ -74,7 +66,7 @@ record is the parent loop's; a lane never touches it**. Count with `--merged <N>
 | `resumed` | Take the budget from `--json`, report the plan again, read `backlogrun-progress.md` → "Resuming after a cut" |
 | `busy` / `mismatch` / `unreadable` / `unknown` | **Stop; do not open a lane** — report what it printed; never resume into another invocation's record |
 | `over` | **End the conversation**; retype the invocation in a fresh session |
-| `standing` | **Stop; do not open a lane**: report `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"` and `pnpm josh run:carry --end` for the person to choose — a crash from a run-tooling defect this run has since fixed you resume yourself (`upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合") |
+| `standing` | **Stop; do not open a lane**: report `pnpm josh backlogrun --restart` (continue the run) and `pnpm josh run:carry --end` (discard it) for the person to choose — a crash from a run-tooling defect this run has since fixed you resume yourself (`upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合") |
 **End the record when the run ends** — `pnpm josh run:report`, then `pnpm josh run:carry --end`, **never
 batched with it**, and `pnpm josh run:wake --stop` in the same turn. **A run that ends by _stopping_**
 (a `stop` verdict or the consecutive-failure guard) **ends with `pnpm josh run:carry --end --stopped
@@ -99,21 +91,21 @@ Waiting on a person, Out of scope) in the session language, with any truncated-l
 **Settle every `needs-decision` issue the plan listed in one pass**, from one `pnpm josh issue:read <N>
 <N> …` call (`issue-comments.md`):
 
-- **An answer already in the issue** — record it as a comment and **remove the label** (Tier A).
+- **An answer already in the issue** — record it as a comment and **remove the label** with `pnpm josh run:park <N> --clear` (Tier A).
   **Never measure in order to decide**: a question needing a benchmark or a run stays labelled.
 - **A person's judgement** — apply `needs-decision` (`backlogrun-park.md` → "Only a person's judgement
   carries `needs-decision`").
 - **Order and isolate** — a native `blocked-by` where one must land first; `run:solo` on all three
   `backlogrun-lanes.md` → "A solo run" conditions, **every other one `run:lane`**, commenting the
   reason.
-- **`priority:high`** only on a cited ground (a stated deadline, a person's written policy), commented;
-  **never remove it**.
+- **`priority:critical` / `priority:high`** are applied at filing by `pnpm josh issue:file` from the
+  body's `- 優先度:` declaration (`issue-template.md`); **only a person removes them**.
 - **Report `pnpm josh backlog:plan --waves`** with the plan, never an order derived by hand; then start
   the loop, leaving whatever is still labelled parked.
 
-**`needs-decision`, `run:solo`, `run:lane` and `priority:high` are the only workflow labels a run
-applies by hand** — never `needs-human-review` (`needs-human-review.md`), and `auto-ok` only through
-`pnpm josh issue:file` or `pnpm josh auto-ok:judge`.
+**`needs-decision`, `run:solo` and `run:lane` are the only workflow labels a run applies by hand** —
+never `needs-human-review` (`needs-human-review.md`), the priority labels only through
+`pnpm josh issue:file`, and `auto-ok` only through it or `pnpm josh auto-ok:judge`.
 
 ## The loop
 
@@ -135,14 +127,14 @@ section the row names:
 | `window` | Hand the loop back as is | — |
 
 **A candidate only in another repository is never a token** — report it with its checkout. The budgets,
-verdicts and stops are the driver's own: `docs/maintainers/backlogrun-driver.md`.
+verdicts and stops are the driver's own.
 
 ## What runs once per session, not once per issue
 
 | Step | Where it is defined |
 | --- | --- |
 | `run:carry --begin` + `run:wake --start` before the plan; `run:carry --end` + `run:wake --stop` at the end | "The session cut is inside the invocation" above |
-| `pnpm josh ms`, `pnpm josh latest:scope`, `lane:prune` in the primary checkout before the first lane | `backlogrun-lanes.md` → "Once per repository, before the first lane opens" |
+| `pnpm josh ms`, `pnpm josh latest:if-required`, `lane:prune` in the primary checkout before the first lane | `backlogrun-lanes.md` → "Once per repository, before the first lane opens" |
 | `josh latest` on `required` only, once, never in a lane | `backlogrun-child.md` → "`josh latest` runs once per session, not once per child" |
 | `pnpm josh run:hold <N>`'s preflight, before each child not in a lane | `docs/josh-commands-run.md` → "`josh run:hold`" |
 | `pnpm josh run:progress --wait` in the background, `--mark` at every real report | `progress-watcher.md` → "Progress while the run is quiet" |

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

@@ -1,10 +1,5 @@
 # `backlogrun` — the manifest (named issues, epics and the opted-in backlog)
 
-**This file is the manifest, not the procedure**: the ordered flow as terse triggers, and the route
-table naming the one section each moment reads. Rationale and provenance:
-`docs/maintainers/backlogrun-rationale.md` → "Why the loop's position is computed";
-`docs/maintainers/backlogrun-rationale.md` → "Where each rule came from".
-
 **`backlogrun` names either nothing, or the issues and epics to run first.** With no argument it runs
 whatever `pnpm josh backlog:next` offers — the whole opted-in backlog, every issue carrying `auto-ok`
 plus every child of an epic whose root carries it, ordered by dependency and grouped into waves. With
@@ -12,9 +7,9 @@ plus every child of an epic whose root carries it, ordered by dependency and gro
 that same backlog. **`--only` stops it after the named list**, draining nothing.
 
 **The loop's current position is computed, not carried in the conversation.** `pnpm josh run:step <N>`
-reads where the run is from the event stream, the carry record and the issue state, and prints the next
-single action — a runnable command, or the one point a person has to judge. **With no `<N>` it answers
-for the parent itself**, from the carry record alone.
+reads it from the event stream, the carry record and the issue state, and prints the next single
+action — a runnable command, or the one point a person has to judge — followed by the section that
+governs it. With no `<N>` it answers for the parent itself, from the carry record alone.
 
 **A named item may be a single issue or an epic.** A single-issue item is one `fullrun`; **a named epic runs its children in
 dependency order across the free lanes, and the run does not advance to the next named item until
@@ -29,67 +24,53 @@ is still that one invocation (`backlogrun-steps.md` → "The session cut is insi
 
 ## The manifest — the ordered flow
 
+A section `run:step` prints is not fetched again. Every other one is read at its step with
+`pnpm josh doc:section <file> "<heading>"` — never a whole document (`SKILL.md` → "A section
+reference is read as a section").
+
 1. **Claim nothing at the entry — this parent orchestrates and never implements.** The working-tree
    hold, the split assessment and `fullrun.md` are read by a dispatched child inside its own delegated
    `fullrun` unit, never at the parent's entry.
 2. **Begin the carry record before the plan** — `pnpm josh run:carry --begin "<invocation>" --owner
-   "$PPID"` and `pnpm josh run:wake --start`, in the same turn as the first `pnpm josh ms`.
+   "$PPID"` and `pnpm josh run:wake --start`, in the same turn as the first `pnpm josh ms`. Its answers:
+   `backlogrun-steps.md` → "The session cut is inside the invocation"; a resumed session:
+   `backlogrun-progress.md` → "Resuming after a cut".
 3. **What this invocation approves** — the opted-in pool, a run's own filings once bundled, and the
-   brake that bounds the amount; the route table's row points at the single source of the `auto-ok` rule.
+   brake that bounds the amount: `backlogrun-steps.md` → "What one invocation approves".
 4. **Report the plan before the first child** — `pnpm josh backlog:plan`, then resolve every
    `needs-decision` issue decidable from its body in one pass, recording `blocked-by`, `run:solo` and
-   `run:lane` in the same pass.
+   `run:lane` in the same pass: `backlogrun-steps.md` → "The plan, before the first child starts";
+   `run:solo`: `backlogrun-lanes.md` → "A solo run".
 5. **Named issues run first, in order** — each as a delegated `fullrun`, one at a time, then the pool;
    `--only` stops after the list.
+   - Once per session: `backlogrun-steps.md` → "What runs once per session, not once per issue" and
+     `backlogrun-child.md` → "`josh latest` runs once per session, not once per child"
+     (`latest-gate.md` whole on `required`).
+   - The watcher: `progress-watcher.md` → "Progress while the run is quiet".
+   - Lanes: `backlogrun-lanes.md` → "Once per repository, before the first lane opens", by hand
+     `backlogrun-lanes.md` → "Opening one lane and dispatching its child".
+   - Dispatch: `backlogrun-child.md` → "Each child runs in a delegated unit".
 6. **The loop belongs to the supervisor — hand it over with what the bare `pnpm josh run:step`
    prints**, whatever the plan held: `run:wake` runs `backlog:drive`, which returns a branch to an AI
-   session only when it needs judgment.
+   session only when it needs judgment (`backlogrun-steps.md` → "The loop").
+   - An `epic #N` hand-back or a `merge` branch: `backlogrun-progress.md` → "Running a named epic's
+     children".
+   - A merge answered `over`: `backlogrun-progress.md` → "The hand-off".
+   - A unit gone silent: `backlogrun-recovery.md` → "A delegated unit that stopped without reporting".
+   - A child that cannot finish: `backlogrun-park.md` → "park and continue".
 7. **End the record when the run ends** — `run:report`, then `run:carry --end` (or `--end --stopped
-   "<reason>"`) and `run:wake --stop`. An empty plan is not that end; the driver's idle watch decides it.
-   A person stops a run from the terminal with `pnpm josh backlogrun --stop`, which makes both calls.
-
-## The route table
-
-**Read one section, at the moment its row names, with `pnpm josh doc:section <file> "<heading>"`** —
-never a whole document (`SKILL.md` → "A section reference is read as a section"):
-
-| The moment | Read |
-| --- | --- |
-| The entry: the carry record and its answers | `backlogrun-steps.md` → "The session cut is inside the invocation" |
-| What the invocation may merge, and the `auto-ok` rule | `backlogrun-steps.md` → "What one invocation approves" |
-| Before the first child: the plan and the decision pass | `backlogrun-steps.md` → "The plan, before the first child starts" |
-| The driver hands a branch back | `backlogrun-steps.md` → "The loop" |
-| Once per session | `backlogrun-steps.md` → "What runs once per session, not once per issue" |
-| `josh latest:scope` answers `required` | `latest-gate.md` (whole) |
-| Starting the progress watcher | `progress-watcher.md` → "Progress while the run is quiet" |
-| The run ends | `backlogrun-steps.md` → "End the record when the run ends" |
-| Labelling an issue `run:solo` | `backlogrun-lanes.md` → "A solo run" |
-| Before the first lane opens | `backlogrun-lanes.md` → "Once per repository, before the first lane opens" |
-| Opening a lane by hand | `backlogrun-lanes.md` → "Opening one lane and dispatching its child" |
-| The first child is in hand | `backlogrun-child.md` → "`josh latest` runs once per session, not once per child" |
-| Dispatching a child | `backlogrun-child.md` → "Each child runs in a delegated unit" |
-| An `epic #N` hand-back, a `merge` branch, or a `run:merge` token | `backlogrun-progress.md` → "Running a named epic's children" |
-| A merge answered `over` | `backlogrun-progress.md` → "The hand-off" |
-| A resumed session | `backlogrun-progress.md` → "Resuming after a cut" |
-| The run's last merge | `backlogrun-progress.md` → "Who sends the summary, and who propagates" |
-| `josh release:scope`, after the last merge | `followup.md` → "When `pnpm josh release` runs" |
-| A unit went silent | `backlogrun-recovery.md` → "A delegated unit that stopped without reporting" |
-| A child cannot finish | `backlogrun-park.md` → "park and continue" |
+   "<reason>"`) and `run:wake --stop`: `backlogrun-steps.md` → "End the record when the run ends".
+   - An empty plan is not that end; the driver's idle watch decides it. A person stops a run from the
+     terminal with `pnpm josh backlogrun --stop`, which makes both calls.
+   - The last merge: `backlogrun-progress.md` → "Who sends the summary, and who propagates", then
+     `followup.md` → "When `pnpm josh release` runs".
 
 ## Guards
 
 | Guard | Limit | On reaching it |
 | --- | --- | --- |
 | Children per run | 30 | Stop and report; an epic this large should be split. |
-| Issues filed per run | 10 | Stop and report; a run filing more than this has lost the plot. |
+| Issues filed per run | `prerequisite.md`'s cap | Stop and report. |
 | Consecutive child failures | 3 | Stop and report; something is wrong with the environment, not the children. |
 
 A failure that is not consecutive parks its child and the run continues.
-
-## This file is the single source of the `backlogrun` procedure
-
-`CLAUDE.md` carries the keyword's row in the shorthand table and the explicit-invocation rule;
-`SKILL.md` → §1 routes here. This manifest names which children there are and in what order; each
-step's procedure is the section its route-table row names. Where any of them could disagree, the rule
-is that this manifest and `backlogrun-steps.md` add nothing to a child's procedure — they only say
-which children there are.