@joshuafolkken/kit 1.957.0 → 1.978.0

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

@@ -2,15 +2,13 @@
 
 **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.
+`backlogrun.md`, which points here at that step. 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.
+**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
@@ -26,7 +24,7 @@ kit's issue does not publish kit, so such a dependency resolves only once the bl
 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").
+blocker repository's manifest, never from the registry.
 
 **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
@@ -34,29 +32,23 @@ carrying `in-progress` and not parked counts for one — whichever epic it belon
 `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.
+deliberately not parked and goes on holding its lane.
 
 **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.
+the moment `run:hold` answers `hold` — *after* this read. It is a guard, 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`
+**A stale label holds a lane, so the stale rule reaches past this epic's own children** — `backlogrun-park.md` →
+"`in-progress` is removed by whoever finds it stale" 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.
+offering the child. **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
@@ -66,6 +58,9 @@ 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.
 
+Rationale: `docs/maintainers/backlogrun-lanes-rationale.md` → "Why the lane ceiling is shaped the way
+it is".
+
 ## 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
@@ -85,41 +80,37 @@ number (`pre-gate-cut.md` → "The dispatch mark" and "The stage is passed to th
 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
+checks? One of those, and the issue carries `run:solo`; none, and it carries `run:lane` and fills a
+lane like any other child. `backlog:next` and `epic:next --lanes` enforce both (joshuafolkken/kit#2776,
+#2779). 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.
+`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 the case to check hardest, not the case to skip the check on. Rationale:
+`docs/maintainers/backlogrun-lanes-rationale.md` → "Why a lane's review needs a brief and an
+attestation".
 
 **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. Report the throughput gain only with its merge-race
-cost.
+**Never switch the lane to another branch** — a switched lane loses its seat, its listing and its
+isolation. So `epic:next` is asked **with** `--lanes`, and everything below runs as written. Rationale:
+`docs/maintainers/backlogrun-lanes-rationale.md` → "Why the lane branch is `<N>-lane` and never
+switched".
+
+**Report the throughput gain only with its merge-race cost** — every overlap that becomes a conflict
+costs a resolution, a re-run gate and a review ("Conflicts are not predicted" below). Rationale:
+`docs/maintainers/backlogrun-lanes-rationale.md` → "Why lanes cost as well as buy throughput".
 
 ### 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 branches from this ref.
-2. `pnpm josh latest:scope`, and the update on `required` — "`josh latest` runs once per session" above.
+2. `pnpm josh latest:scope`, and the update on `required` — `backlogrun-child.md` → "`josh latest`
+   runs once per session, not once per child".
 3. `pnpm josh lane:prune` — closes the lanes an interruption left registered without a work tree.
 4. `pnpm josh run:tidy` — sweeps merged lanes and stashes (as `run:hold` does).
 
@@ -141,10 +132,9 @@ is a repository-wide stack every lane shares, so a positional pop would take whi
 
 ### 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:
+**One command opens the lane, prepares it, and dispatches the child — `pnpm josh lane:launch`.** 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`:
 
 ```bash
 pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else; alias: josh lnla
@@ -153,6 +143,8 @@ pid=$(pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes")
 
 `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.
+Rationale: `docs/maintainers/backlogrun-lanes-rationale.md` → "Why `lane:launch` folds the lane steps
+into one".
 
 - **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
@@ -162,21 +154,15 @@ guards, refusals and messages holds unchanged; the bullets below describe the st
   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 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`.
+- **Nothing switches the lane's branch.**
+- **`pnpm josh run:hold`'s preflight check is not asked in a lane; `lane:open`'s own answer replaces it.**
+  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.
 
@@ -191,27 +177,25 @@ final step, the `lane:dispatch` it runs after the lane is opened and prepared, w
 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.
+  `<temp>/josh-lane-dispatch-<N>.log`.
 - **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.
+- **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`.
+**Start each child without blocking on it, and poll them all.** That is `backlogrun-child.md` → "A
+delegated unit that stopped without reporting" 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
@@ -231,37 +215,28 @@ reports it: a pull request that conflicts with its base comes back `mergeStateSt
 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.
+the consecutive-failure guard either way.
 
-**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.
+**The merge direction is `origin/main` into the lane's branch, never a rebase**, and no step below
+rewrites a pushed commit. Rationale: `docs/maintainers/backlogrun-lanes-rationale.md` → "Why a conflict
+is resolved in the lane rather than handed to a person".
 
 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.
+   in place. Do not close the lane, open another, or switch its branch.
 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.
+4. **Conclude the merge and push it, with `pnpm josh git -y`** — the only sanctioned way; without it
+   nothing changes on `origin` and condition 3 parks the child for good. **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 safeguard is the re-run verification, not who holds the pen** — a conflict the run can resolve is
+not routed to a person.
 
 **The run steps back under these four conditions, and under no others. The list is exhaustive and
 carries no judgement.**
@@ -292,38 +267,27 @@ to abort.
 | 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 hit a **merge conflict** | **Left open** — the resolution happens in it | The child resolves in place ("Conflicts are not predicted"). 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.
+**A lane closed after a push is reopened by `pnpm josh lane:open <N>`**, which attaches to a local
+`<N>-lane` or creates one from `origin/<N>-lane`, saying on standard error which it reused. **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 the after-push row does not. Rationale:
+`docs/maintainers/backlogrun-lanes-rationale.md` → "Why a committed child's lane is kept".
 
 **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.**
+before anything prints it.
 
-**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.
+**A kept lane holds its seat. 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
@@ -334,13 +298,12 @@ so removing the tree strands it. And `cd` out of the lane **before** `pnpm josh
 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.
+new lane is opened, and no unit is killed mid-gate. 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.
+**`JOSH_LANE_LIMIT` lowers the ceiling with no code** when CI jobs start to queue. Whether queueing
+bites is read from the multi-day backlog timing report — a `checks-wait` that grows with the lane count
+is the queueing. Rationale: `docs/maintainers/backlogrun-lanes-rationale.md` → "Why CI concurrency is
+capped by the lane limit".