@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/.claude/settings.json

@@ -54,7 +54,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision",
 						"timeout": 180
 					}
 				]
@@ -66,7 +66,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh session-lang",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh session-lang",
 						"timeout": 10
 					}
 				]
@@ -74,11 +74,11 @@
 		],
 		"PreToolUse": [
 			{
-				"matcher": "Bash|Edit|Read|Write|AskUserQuestion",
+				"matcher": "Bash|Edit|Read|Write|AskUserQuestion|Agent|Task",
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh pretool-guard",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh pretool-guard",
 						"timeout": 20
 					}
 				]
@@ -90,7 +90,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh format-edited",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh format-edited",
 						"timeout": 90
 					}
 				]
@@ -102,7 +102,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh stop-guard",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh stop-guard",
 						"timeout": 20
 					}
 				]

package/.claude/skills/epic-commands/SKILL.md

@@ -5,9 +5,6 @@ description: Procedures for `josh epic:audit`, `epic:next` and `epic:bundle`. Re
 
 # The `josh epic:*` commands
 
-This skill is the single source for the three commands. Reasons: `docs/maintainers/epic-commands-rationale.md`
-→ "Where each rule came from".
-
 The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `prrun`, `backlogrun` — live in the
 `workflow-commands` skill.
 
@@ -61,8 +58,7 @@ pnpm josh epic "<epic-title>" <N1> <N2> ... --ordered  # argument order is the d
 
 After any hand edit run `pnpm josh epic:check <E>` (exit 1 when the body no longer parses).
 `pnpm josh followup` closes the epic once every task-list child is closed; one tracking a
-cross-repository child is closed by hand. Without `josh`: `issue-template.md`; the format's history:
-`docs/maintainers/epic-commands-rationale.md` → "Creating an epic by hand".
+cross-repository child is closed by hand. Without `josh`: `issue-template.md`.
 
 ## `josh epic:audit <E>` — contradictions across the children
 
@@ -98,8 +94,6 @@ The two `orphan search` findings are about the search, not the children:
 owns updating the existing code referencing that concept — do that at planning. Label names live in
 `scripts/issue/issue-labels.ts`.
 
-History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why the children are read across".
-
 ## `josh epic:next <E…>` — what is runnable
 
 Returns **every** runnable child, bundled per repository with its local checkout. `--repo <owner/repo>`
@@ -143,8 +137,6 @@ Two things stop the command: a **circular dependency**, and a **disagreement bet
 and the `blocked-by` relations**. Only a line that is *nothing but* a chain is a declaration — a prose
 line recommending an execution order is a suggestion, not a dependency.
 
-Why: `docs/maintainers/epic-commands-rationale.md` → "`epic:next` — why it answers as it does".
-
 ## Epics that span repositories
 
 Write cross-repository children as `owner/repo#N` or a full issue URL. Their state is read through
@@ -163,7 +155,7 @@ branch declares is in the registry** (checked in that order; that exact version)
 bumps the version, so the target is the release that includes the blocker. **Unless that repository
 publishes nothing**: no `package.json` on its default branch, or `private`, resolves on close — read
 from its manifest, never the registry; a failed manifest read (not a 404) still waits. The publish
-check is `josh propagate`'s. History: `docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
+check is `josh propagate`'s.
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
@@ -181,7 +173,3 @@ when that step printed `⚠`. **It recommends; it writes nothing.**
 | **The epic listing was cut short** | **Nothing** — every placing row above is withheld | — |
 
 **A placing answer is acted on with `epic-bundle.md`**. `Nothing to bundle.` needs no further read.
-
-History: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why issues filed apart are bundled afterwards";
-the reasons behind `epic-bundle.md`: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why each answer reads as it does";
-behind `execution-waves.md`: `docs/maintainers/epic-commands-rationale.md` → "Execution waves — why a wave is not a mechanism".

package/.claude/skills/epic-commands/epic-bundle.md

@@ -2,14 +2,18 @@
 
 Read this when a filing's `epic:bundle` answer places the issue (`add_to_epic`, `create_epic`, or a
 choice between epics), or when `SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with
-one already filed?" does not settle it. `Nothing to bundle.` needs neither. Reasons:
-`docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why each answer reads as it does".
+one already filed?" does not settle it. `Nothing to bundle.` needs neither.
 
-**Only two things count as a signal**: the issues referring to each other in prose, or a `blocked-by`
-already recorded between them. **A similar title never counts on its own.**
+**Only two things count as a signal**: one issue naming the other in its acceptance criteria
+(`## 受け入れ条件` / `## Acceptance criteria`) or its `parent: #N` / `親: #N` line, or a `blocked-by`
+recorded between them. A reference elsewhere, or a similar title, never counts; the evidence line
+names the section.
+
+**A placing answer you do not follow** — check it against both issues first; record the reason as an
+`Auto-decided:` line on the issue.
 
 **The release issue is neither a candidate nor a subject**, like an epic — its `blocked-by` relations
-are mechanical. Any other `blocked-by` or prose reference still counts.
+are mechanical. Any other `blocked-by` or counted reference still counts.
 
 **The search is not limited to the open backlog.** Every number the subject's own body names is read
 (capped at twenty), whatever its state:

package/.claude/skills/epic-commands/execution-waves.md

@@ -1,8 +1,7 @@
 # Execution waves — parallel, then one alone, then the rest
 
 Read this when an epic's children need an order between groups — a wave boundary, or one child that
-must run alone. It builds on `SKILL.md` → "`josh epic:next <E…>` — what is runnable". Reasons:
-`docs/maintainers/epic-commands-rationale.md` → "Execution waves — why a wave is not a mechanism".
+must run alone. It builds on `SKILL.md` → "`josh epic:next <E…>` — what is runnable".
 
 **A wave is not a mechanism, and there is nothing to add for one** — the dependency declaration
 already expresses it.

package/.claude/skills/verify-ui/SKILL.md

@@ -7,8 +7,7 @@ argument-hint: '[route] [route...]'
 # Verify the rendered screen
 
 A rendered-UI change is not done until someone has looked at it (`CLAUDE.md` → completion gate);
-passing tests are not that look. Rationale: `docs/maintainers/verify-ui-rationale.md` → "Why the skill
-reads as it does".
+passing tests are not that look.
 
 ## 1. Decide which routes to capture
 

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

@@ -5,10 +5,7 @@ description: Procedures for `kickoff`, `fullrun`, `halfrun`, `prrun` and `backlo
 
 # Issue-driven workflow commands
 
-`kickoff`, `fullrun`, `halfrun`, `prrun` and `backlogrun` are the shorthand commands this
-package's collaboration workflow is built on. **This file is their manifest — triggers and pointers,
-never a procedure**: each rule is stated once, in the file its row names. History:
-`docs/maintainers/workflow-commands-rationale.md` → "Where each rule came from".
+Each rule is stated once, in the file its row names.
 
 ## 0. The rule that fires before any of them — explicit invocation
 
@@ -19,8 +16,9 @@ alone**: `backlogrun-steps.md` → "The session cut is inside the invocation".
 ## 1. Which file to read
 
 Read this file, then the files the typed command's row names. A command file is a **manifest** of
-terse triggers and pointers; `pnpm josh run:step <N>` prints the run's next single action, computed
-from the event stream, the carry record and the issue state, never the conversation.
+terse triggers and pointers; `pnpm josh run:step <N>` prints the run's next single action and the
+section that governs it, computed from the event stream, the carry record and the issue state, never
+the conversation; a section it prints is not fetched again.
 
 | Typed keyword                            | Read                                        |
 | ---------------------------------------- | ------------------------------------------- |
@@ -31,8 +29,8 @@ from the event stream, the carry record and the issue state, never the conversat
 | `backlogrun` / `backlogrun #N…` / `backlogrun #E…` | `backlogrun.md` — its dispatched child reads `fullrun.md` + `split-assessment.md` in its own unit, not the parent at entry |
 
 `entry-sequence.md` holds the entry sequence and stop branches `fullrun`, `halfrun` and `prrun` share;
-each manifest carries only its difference. `split-assessment.md` → "The question" is read at the
-entry as a section, its split-handling detail only when a split is found.
+each manifest carries only its difference. `split-assessment.md` → "The question" is printed by
+`pnpm josh run:entry` at the entry, its split-handling detail read only when a split is found.
 
 ### The fetch is one `Read` call per file
 
@@ -100,7 +98,7 @@ from — read at that trigger, never restated here.
 | `backlogrun`'s authorization | The whole `auto-ok` opted-in pool as well as its named items; `pnpm josh backlog:next` offers them | `backlogrun.md` |
 | `run:step` prints the retrospective step (a run drained its backlog and stopped, not a lane child) | Run what it prints once, file 0–2 improvements, then `pnpm josh run:carry --retrospective` | `retrospective.md` |
 | Any artifact prose (Issue bodies, comments, Telegram) | Session language (`JOSH_SESSION_LANG`, default `ja`); Issue/PR titles stay English | `prompts/collaboration-workflow/overview.md` |
-| Any mid-workflow stop | Send a `confirmation` Telegram first, so the user is alerted off-screen | `CLAUDE.md` → "Mid-workflow stop notification" |
+| Any mid-workflow stop | `stop:guard` sends the `confirmation` Telegram; on its refusal, send it | `CLAUDE.md` → "Mid-workflow stop notification" |
 
 ## 3. What stays resident, and what is read from here
 

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

@@ -17,7 +17,6 @@
 - A lane child's hand-off or pre-gate cut is the sole turn boundary before the push (`chain-rule.md`).
 
 Use harness detachment so completion returns to the run. Foreground timeouts stay within the cap.
-Where each rule came from: `docs/maintainers/background-commands-rationale.md` → "Where each rule came from".
 
 ## How the wait ends — the task's exit, never a regex over its output
 
@@ -27,8 +26,7 @@ limit.
 
 **Never hand-write a `while`/`until` … `sleep` loop over the output file** — a regex that never matches
 waits to the block limit, one that matches a mid-run line exits early. `pnpm josh rule:guard` refuses it
-(`prompts/collaboration-workflow/rule-delivery.md`; `docs/maintainers/background-commands-rationale.md`
-→ "Why a poll loop is refused").
+(`prompts/collaboration-workflow/rule-delivery.md`).
 
 **To glance at interim output, `Read` the output file once**, never in a sleep loop. CI is waited on by
 `pnpm josh followup`; a progress heartbeat is `run:progress --wait`'s job (`early-heartbeat` refuses a
@@ -37,8 +35,7 @@ hand-armed timer).
 ## The tail and what overlaps each wait
 
 **Never give a foreground call a timeout above the harness cap** — a larger number detaches it without
-the completion notification (`docs/maintainers/background-commands-rationale.md` → "Why the tail
-collects idle time").
+the completion notification.
 
 **The tail is emptied before `followup` is issued.** Each step is asked one question: **does it read the
 merge result?**
@@ -64,8 +61,7 @@ merge result?**
 **The turn never ends at the push.** The `pnpm josh git -y` completion resumes the run, and that turn
 goes straight through any branch-2 filing and `pnpm josh epic:bundle` to `pnpm josh followup`. `pnpm
 josh rule:guard` refuses the foreground push (`prompts/collaboration-workflow/rule-delivery.md`); the
-push reissued detached is not refused again (`docs/maintainers/background-commands-rationale.md` → "Why
-the push is guarded").
+push reissued detached is not refused again.
 
 **One turn does end before the push: a dispatched lane child's pre-gate cut** — `pre-gate-cut.md` →
 "Taking the cut".

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

@@ -1,14 +1,6 @@
 # `backlogrun` — running a child (shared mechanics, delegation, liveness, session setup)
 
-Point-of-use, read one section at a time from `backlogrun.md` → "The route table". Reasons:
-
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the file is read by section"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why a bare Issue promotes itself under `backlogrun` but not under `fullrun`"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why each child runs in a delegated unit"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the summary is bounded the way it is"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the audit runs before the first child"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why `josh latest` is hoisted to the session"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the preflight is part of the claim"
+Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow".
 
 ## Running a child — the shared mechanics
 
@@ -89,7 +81,8 @@ is unchanged.
 
 ## A delegated unit that stopped without reporting
 
-**Hand the child off without blocking, and poll** — a stopped unit leaves no notification. Once its
+**Hand the child off without blocking, and wait on `pnpm josh lane:await <N>`** — a stopped unit
+leaves no notification, so the await's exit is the wake. Once its
 output is unchanged for the silent-unit window, read `backlogrun-recovery.md` → "A delegated unit that
 stopped without reporting" and ask `pnpm josh run:liveness`.
 

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

@@ -1,15 +1,6 @@
 # `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
 
@@ -29,7 +20,6 @@ answer wrongly (a false green or a false red)? All three, and the issue carries
 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".
 
 ## Lanes — running more than one child at a time
 
@@ -77,7 +67,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 +86,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

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
 
@@ -33,8 +30,6 @@ parks, re-dispatches or files.
 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".
 
 **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.
@@ -90,8 +85,7 @@ It never carries:
 
 **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
 

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 |
 | --- | --- |
@@ -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,8 +65,7 @@ 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.
 
@@ -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,14 +19,11 @@ 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 |
 | `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`:
 
@@ -39,7 +37,10 @@ unit parked it, then stopped: leave the label on and count nothing. Otherwise, w
    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's issue, 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
 
@@ -135,7 +127,7 @@ 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
 

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,52 +24,46 @@ 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
 
@@ -85,11 +74,3 @@ never a whole document (`SKILL.md` → "A section reference is read as a section
 | 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.