@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/.claude/settings.json

@@ -5,6 +5,11 @@
 		"deny": [
 			"Bash(rm -rf *)",
 			"Bash(rm -rf /*)",
+			"Bash(rm -fr *)",
+			"Bash(gh repo delete*)",
+			"Bash(gh repo archive*)",
+			"Bash(gh pr close*)",
+			"Read(./.env)",
 			"Bash(git push --force*)",
 			"Bash(git push -f*)",
 			"Bash(git push *--force*)",
@@ -56,11 +61,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary (Now / Change / Check, then every change with its test). Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
-					},
-					{
-						"type": "command",
-						"command": "if [ -f dist/hooks/session-lang.js ]; then node dist/hooks/session-lang.js; else pnpm josh session:lang; fi",
+						"command": "if 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)\"; 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)\" || exit 1; fi; cd \"$project_root\" && if node --disable-warning=ExperimentalWarning scripts/hooks/hook-bundle-ready.ts; then node dist/hooks/session-lang.js; else pnpm josh session:lang; fi",
 						"timeout": 10
 					}
 				]
@@ -72,7 +73,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if [ -f dist/hooks/pretool-guard.js ]; then node dist/hooks/pretool-guard.js; else pnpm josh pretool:guard; fi",
+						"command": "if 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)\"; 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)\" || exit 1; fi; cd \"$project_root\" && if node --disable-warning=ExperimentalWarning scripts/hooks/hook-bundle-ready.ts; then node dist/hooks/pretool-guard.js; else pnpm josh pretool:guard; fi",
 						"timeout": 20
 					}
 				]
@@ -84,7 +85,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if [ -f dist/hooks/format-edited.js ]; then node dist/hooks/format-edited.js; else pnpm josh format:edited; fi",
+						"command": "if 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)\"; 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)\" || exit 1; fi; cd \"$project_root\" && if node --disable-warning=ExperimentalWarning scripts/hooks/hook-bundle-ready.ts; then node dist/hooks/format-edited.js; else pnpm josh format:edited; fi",
 						"timeout": 90
 					}
 				]
@@ -96,7 +97,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if [ -f dist/hooks/stop-guard.js ]; then node dist/hooks/stop-guard.js; else pnpm josh stop:guard; fi",
+						"command": "if 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)\"; 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)\" || exit 1; fi; cd \"$project_root\" && if node --disable-warning=ExperimentalWarning scripts/hooks/hook-bundle-ready.ts; then node dist/hooks/stop-guard.js; else pnpm josh stop:guard; fi",
 						"timeout": 20
 					}
 				]

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

@@ -6,9 +6,7 @@ description: The procedures for the `josh epic:*` commands that make an epic run
 # The `josh epic:*` commands
 
 These three commands are what turn an epic from a list of issue numbers into something a run can
-execute unattended. **This skill is their single source**: `prompts/collaboration-workflow/` keeps
-`epic-bundle.md`, `epic-audit.md` and `cross-repo-epic.md` only as pointers here, and the history
-behind the rules is `docs/maintainers/epic-commands-rationale.md` (joshuafolkken/kit#2892).
+execute unattended. **This skill is their single source**, and the history behind the rules is `docs/maintainers/epic-commands-rationale.md` (joshuafolkken/kit#2892).
 
 The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `backlogrun` — live in the
 `workflow-commands` skill.
@@ -118,7 +116,7 @@ about the search itself rather than about anything the children say (joshuafolkk
 
 **One thing it cannot check** belongs to planning: when a child introduces a new label, command,
 state or artifact, list the existing code referencing that concept and confirm some child owns
-updating it. Label names are single-sourced in `scripts/git/issue-labels.ts`.
+updating it. Label names are single-sourced in `scripts/issue/issue-labels.ts`.
 
 History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why the children are read across".
 
@@ -153,7 +151,7 @@ command prints a ⚠️ line naming that child rather than reporting a reorderin
 `owner/repo#number` and kept by the epic named earlier; withheld there, it stays withheld, because a
 `blocked-by` relation belongs to the issue rather than to the epic listing it. **One unusable graph
 refuses the whole answer**, and **one reference that does not parse fails the read** rather than
-being dropped. `docs/josh-commands.md` → "`josh epic:next`" carries the worked form.
+being dropped. `docs/josh-commands-automation.md` → "`josh epic:next`" carries the worked form.
 
 **An `in-progress` issue occupies a lane rather than the whole repository.** The occupancy is counted
 from that repository's own `in-progress` listing — never from anything the session remembers, since
@@ -196,7 +194,7 @@ inherits; open and tracked by none, the child waits on a person and the
 blocker is named on standard error; a state the relation did not carry reads as waiting. **So an order
 between two epics is recorded with a native `blocked-by` relation and honoured by naming both epics**
 — `epic:next 1936 1931`, or `backlog:next`, whose set is the whole opted-in backlog. The table is
-`docs/josh-commands.md` → "`josh epic:next`".
+`docs/josh-commands-automation.md` → "`josh epic:next`".
 
 Two things stop the command rather than being worked around: a **circular dependency**, and a
 **disagreement between the epic body and the `blocked-by` relations** (an epic written before `josh`
@@ -484,7 +482,7 @@ than restated — and beside it the one thing this one deliberately refuses: whe
 already been filed, from a title comparison (joshuafolkken/kit#1252). **Both run**, and neither
 replaces the other: `pnpm josh issue:file` runs the scout before it creates the issue, and
 `epic:bundle` afterwards, from the real number and the relations recorded against it.
-Full behavior: `docs/josh-commands.md` → "`josh issue:file`".
+Full behavior: `docs/josh-commands-automation.md` → "`josh issue:file`".
 
 **When the relation carries an order, record it** in `blocked-by` and in the epic's `Dependencies` —
 on an addition as much as on a new epic. Without it the batch survives and the reason for it does

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

@@ -15,7 +15,7 @@ green while spacing, layout and styling are visibly broken. This skill is the lo
 In order:
 
 1. The routes given as arguments (`/verify-ui / /blog`).
-2. Otherwise, derive the candidates with `pnpm josh ui:routes` (alias `josh uir`): it reads the
+2. Otherwise, derive the candidates with `pnpm josh ui:routes`: it reads the
    change (the branch diff, or the staged diff with `--staged`) and lists the routes it touches,
    tracing a changed shared component to the routes that render it. From that list **pick the ones a
    reader would notice** — that narrowing is the judgement the command leaves to you.

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

@@ -1,20 +1,20 @@
 ---
 name: workflow-commands
-description: The procedures for the Issue-driven shorthand commands `kickoff`, `fullrun`, `halfrun` and `backlogrun` — planning, implementation, the verification gate, unattended epic and backlog execution, the `/code-review` → `followup` chain rule, auto-merge and the Telegram notifications. Read this the moment the user types one of those keywords (with or without `#N` / `new`), before running any command, and read it too when asked what one of them does or when a run of one has to be resumed or repaired.
+description: The procedures for the Issue-driven shorthand commands `kickoff`, `fullrun`, `halfrun`, `prrun` and `backlogrun` — planning, implementation, the verification gate, unattended epic and backlog execution, the `/code-review` → `followup` chain rule, auto-merge and the Telegram notifications. Read this the moment the user types one of those keywords (with or without `#N` / `new`), before running any command, and read it too when asked what one of them does or when a run of one has to be resumed or repaired.
 ---
 
 # Issue-driven workflow commands
 
-`kickoff`, `fullrun`, `halfrun` and `backlogrun` are the shorthand commands this
+`kickoff`, `fullrun`, `halfrun`, `prrun` and `backlogrun` are the shorthand commands this
 package's collaboration workflow is built on. Their procedures live here rather than in `CLAUDE.md`
 because each one applies only while its own command is running.
 
-The canonical extended reference is `prompts/collaboration-workflow/` (indexed by
-`prompts/collaboration-workflow.md`); this skill is the operational procedure, and the two must agree.
+Each topic file under `prompts/collaboration-workflow/` sources its own rule; this skill sources the
+procedures. Neither restates the other.
 
 ## 0. The rule that fires before any of them — explicit invocation
 
-**Never start a `kickoff` / `halfrun` / `fullrun` / `backlogrun` workflow (including their
+**Never start a `kickoff` / `halfrun` / `prrun` / `fullrun` / `backlogrun` workflow (including their
 `#N` and `new` variants) unless the user has typed the keyword in the current turn's prompt.** This rule is also
 resident in the AI documents, because it has to hold when this skill has *not* been loaded.
 
@@ -44,6 +44,7 @@ the file its pointer names (for `fullrun`, the step lists are `fullrun-steps.md`
 | `kickoff` / `kickoff #N` / `kickoff new` | `kickoff.md`                                |
 | `fullrun` / `fullrun #N` / `fullrun new` | `fullrun.md`                                |
 | `halfrun` / `halfrun #N` / `halfrun new` | `halfrun.md`                                |
+| `prrun` / `prrun #N` / `prrun new`       | `prrun.md` — the difference over `fullrun.md`, read with it |
 | `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 |
 
 Each command manifest cites `split-assessment.md` → "The question" — the split decision, read at the
@@ -92,8 +93,8 @@ procedure alone, and the rest of `backlogrun-park.md` is read only when it is re
 **A pointer written `` `X.md` → "Heading" `` is read as that section, never by opening `X.md` whole:**
 
 ```bash
-pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim ; alias: josh ds
-pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs ; alias: josh rs
+pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim
+pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs
 ```
 
 The section is fetched in the same turn, printed verbatim with its subsections; **a heading that does
@@ -115,12 +116,12 @@ procedure.
 | While implementing | Re-run one check by name, not the whole gate — `pnpm josh lint:related`, `pnpm josh cspell:dot`, `pnpm josh test:related`; the last pair runs in front of the gate, and `pnpm josh review:brief` refuses a brief on a tree neither was green on | `chain-rule.md` |
 | A review has run | Its verdict counts only once `pnpm josh review:attest --check` answers `ok`; `missing` / `mismatch` are refusals `pnpm josh followup` blocks the merge on | `chain-rule.md` → "The brief names the checkout, and a review that read another one is refused" |
 | E2E gate | The CI E2E job where the command ends in a PR (`fullrun` / `backlogrun`, enforced by `pnpm josh followup`); you run `pnpm josh test:e2e` yourself where it does not (`halfrun`) | `prompts/testing-guide.md` → "Closing the E2E gate without a human run" |
-| A defect in the verification path turns up | The interrupt runs alone; a batch resumes only once it has merged — decided from an enumeration, not from how serious it looks | `prompts/collaboration-workflow/wip-cap.md` → 「実行のしかた」 |
+| A defect in kit's own verification turns up | It runs alone, and a batch resumes only once it has merged, when three conditions all hold (a defect, in kit's own verification, making unrelated PRs answer wrongly on `main` now) — never from how serious it looks | `prompts/collaboration-workflow/wip-cap.md` → 「実行のしかた」 |
 | A command can take minutes | Issue it in the background; the turn never ends at the push (`pnpm josh followup` stays foreground) | §2h → `background-commands.md` → "Background the gate and push" |
 | `pnpm josh issue:state <N>` answers `human_review: yes` | Implement and gate, then stop before the commit | §2z → `needs-human-review.md` |
 | Under `backlogrun`, a stop that would end a batch, or a named non-epic item | Park one child and continue; run a named non-epic item as a `fullrun` | `backlogrun-park.md` → "park and continue"; `backlogrun-child.md` → "When `#N` is not an epic" |
 | `backlogrun`'s authorization | The whole `auto-ok` opted-in pool as well as its named items; `pnpm josh backlog:next` offers them | `backlogrun.md` |
-| First call of `fullrun` / `halfrun` (not `kickoff`) | Claim the tree: `fullrun #N` starts with `pnpm josh run:entry <N>` (which runs the hold); `fullrun new` and `halfrun` use `pnpm josh run:hold` | §2f → `working-tree-hold.md` |
+| First call of any entry | `#N`: `pnpm josh run:entry <N> --to <command>` (claims the tree, except `kickoff`); `new` (not `kickoff`): `pnpm josh run:hold` | §2k; §2f → `working-tree-hold.md` |
 | Same turn as the hold (not a dispatched child, not `kickoff`) | `pnpm josh cost --cut`; `under` continues, `over` stops with a `confirmation` Telegram and the resume command, then `pnpm josh run:release` | `backlogrun-progress.md` → "The hand-off" (shared 135,000 threshold) |
 | Before any work starts (every entry) | The split assessment; the default is not to split — separability **and** a scope clearly over one gate must hold together; a `fullrun` / `halfrun` that finds a split files the epic and **stops** | `split-assessment.md` → "The question" |
 | Another Issue here must land first | A prerequisite is a dependency, not a park (the third of four mid-run discoveries) | §2d → `prerequisite.md` |
@@ -193,14 +194,14 @@ refuses the second `pnpm josh issue:file` call until it has.
 its duplicate and epic answers.** This applies inside every workflow, including observations and review
 follow-ups. The guard refuses any other filing call. Read `issue-scout.md` at that point for the
 duplicate, closed-Issue and epic decisions and for `--distinct`; `issue-fold-existing.md` handles a
-compatible duplicate. `docs/josh-commands.md` → "`josh issue:file`" defines the command.
+compatible duplicate. `docs/josh-commands-automation.md` → "`josh issue:file`" defines the command.
 
 ## 2f. The working-tree hold — one run per tree
 
 **Trigger:** the first call of `fullrun` and `halfrun` alike — before the title is normalized, before
-`git switch main`, and before a `new` entry files its Issue. **Then:** `fullrun #N` first runs
-`pnpm josh run:entry <N>`, which includes the tree claim; `fullrun new` and `halfrun` first run
-`pnpm josh run:hold [<N>]`. `hold` continues; `busy` and `unknown` stop with a `confirmation` Telegram
+`git switch main`, and before a `new` entry files its Issue. **Then:** a `#N` entry first runs
+`pnpm josh run:entry <N> --to <command>` (§2k, the tree claim included); `new` runs bare
+`pnpm josh run:hold`. `hold` continues; `busy` and `unknown` stop with a `confirmation` Telegram
 carrying what stderr printed. **`kickoff` is exempt** (it edits nothing). A stop that leaves the tree
 clean releases explicitly with `pnpm josh run:release [<N>]`; a `halfrun` or `needs-human-review` stop
 keeps the hold; `pnpm josh followup` releases a merged run. The answer table, the per-child rule and
@@ -241,6 +242,13 @@ digest it names once.** File up to two worthwhile improvements through `issue:fi
 `epic:bundle` included), stack the rest in the observation ledger, and close the step with the command described
 there. A dispatched lane child never runs the retrospective.
 
+## 2k. The stage ladder
+
+`kickoff` → `halfrun` → `prrun` → `fullrun` (joshuafolkken/kit#3042): the command sets how far a run
+goes, the Issue where it starts. `run:entry <N> --to <command>` prints `stage #<N> — at: … · start:
+…`; **`start: reached` redoes nothing — stop** (at `merged`, the next line answers). A
+stop's `Next:` line names the commands further up. Table: `docs/how-to/run-issues.md`.
+
 ## 3. What stays resident, and what is read from here
 
 **The residency criterion is `prompts/collaboration-workflow/residency.md`, its single source — read

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

@@ -2,7 +2,7 @@
 
 ## Background the gate and push
 
-- **The clean path folds the region into one backgrounded `pnpm josh ship`** (gate → `git -y` →
+- **The clean path folds the region into one backgrounded `pnpm josh ship`** (preflight → gate → `git -y` →
   foreground `followup` → `run:tail`; joshuafolkken/kit#2398). The calls below serve a due second round.
 - Background `pnpm josh gate` beside the review; join it before commit.
 - Issue `pnpm josh git -y` in the background; its completion resumes the run, so the turn never ends
@@ -131,9 +131,10 @@ turn-end this section forbids. The boundary, its two commands and the resume ver
 
 **A headless lane child (`claude -p`) is where "a background command re-invokes the run" does not
 hold: its background Bash tasks are killed when its turn ends** (joshuafolkken/kit#2704). It hands the
-gate-to-merge region to `pnpm josh ship --detach` instead (`chain-rule.md` step 0); `pnpm josh
-rule:guard` refuses a backgrounded `josh gate` / `git` / `followup` there, and the `Stop` hook sends a
-child with a task still running back to wait rather than to notify.
+gate-to-merge region to a foreground `pnpm josh ship --detach` instead (`chain-rule.md` step 0) —
+its preflight runs before the supervisor exists, so a backgrounded `ship` dies with the turn
+(joshuafolkken/kit#3027); `pnpm josh rule:guard` refuses a backgrounded `josh gate` / `git` /
+`followup` / `ship` there, and the `Stop` hook sends a child with a task still running back to wait.
 
 The operational section above is the single source of the rule. `followup.md`, `chain-rule.md` and
 `backlogrun-progress.md` → "Progress while the run is quiet" route here for it rather than restating it.

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

@@ -94,7 +94,7 @@ child over" in `backlogrun-lanes.md` carries the command.
 JSONL. `JOSH_WORKER_MODEL` overrides Claude Code only; `JOSH_WORKER_EFFORT` covers both providers,
 and legacy `JOSH_LANE_*` applies only here. Bad markers, missing CLI/auth and failure
 refuse or park without fallback or retry.
-`docs/josh-commands.md` → "`josh lane:dispatch`" is the single source.
+`docs/josh-commands-automation.md` → "`josh lane:dispatch`" is the single source.
 
 **The parent reads GitHub, never the summary.** That is `epic-child`'s verifier: a unit that reports
 a child finished without its PR merged leaves that child open, and `pnpm josh issue:state <N>` says so
@@ -164,7 +164,7 @@ unit was given** — this session's own unless the unit was handed a separate wo
 the recovery below is taken there too.
 
 ```bash
-pnpm josh run:liveness <N> --output <path> --process none    # alias: josh rv
+pnpm josh run:liveness <N> --output <path> --process none
 pnpm josh run:liveness <N> --output <path> --process alive
 pnpm josh run:liveness <N> --output <path> --process none --window 45 --repo <owner/repo>
 ```
@@ -290,7 +290,7 @@ separate command to ask first. Rationale: `docs/maintainers/backlogrun-child-rat
 preflight is part of the claim".
 
 ```bash
-answer=$(pnpm josh run:hold 926)   # alias: josh rh ; one token on stdout, prose on stderr
+answer=$(pnpm josh run:hold 926)   # one token on stdout, prose on stderr
 ```
 
 | Answer | What it found | What to do |

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

@@ -65,7 +65,7 @@ it is".
 
 `pnpm josh epic:next <E> --repo <owner/repo> --lanes` answers with **one issue number per line**, up to
 the number of free lanes, and each of those children runs in a **lane** of its own: a linked git work
-tree with its own branch, its own `.env` and its own dev and preview ports (`docs/josh-commands.md` →
+tree with its own branch, its own `.env` and its own dev and preview ports (`docs/josh-commands-automation.md` →
 "`josh lane:open` / `josh lane:close` / `josh lane:list` / `josh lane:prune`"). **Implementation, the
 verification gate and the review run in parallel; the merges stay serial** — each one lands on the
 `main` the next is then measured against.
@@ -76,12 +76,14 @@ verification are `pre-gate-cut.md`, the single source. **The child is told apart
 resume stage is handed to it, by a mark the dispatch sets** — `JOSH_LANE_CHILD`, the lane's issue
 number (`pre-gate-cut.md` → "The dispatch mark" and "The stage is passed to the resumed child").
 
-**One kind of child takes no lane beside anything: an interrupt whose subject is a defect in the
-verification path itself.** It runs alone, and the batch resumes only once it has merged. **Decide it
-from the enumeration, never from how serious it looks** — does the defect reach the verification gate
+**One kind of child takes no lane beside anything: a defect in kit's own verification that makes
+unrelated PRs answer wrongly on `main` today.** It runs alone, and the batch resumes only once it has
+merged. **Decide it from three conditions that must all hold, never from how serious it looks** — is
+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? 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,
+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` 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.
 
@@ -137,7 +139,7 @@ runs `lane:open`, then — only when `--stash` is given, which is the first lane
 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
+pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else
 pid=$(pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes") || exit 1   # the first lane only, and only if `josh latest` stashed
 ```
 

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

@@ -33,6 +33,12 @@ authorization, whether it came from a named epic or from the opted-in pool:
   is Tier A" carries the re-dispatch itself. A released child takes a lane exactly as any batch child
   does.
 
+## The parent does not investigate a lane failure itself
+
+**A lane failure whose reason is not on its Issue is read by a unit** — `pnpm josh delegate
+lane-failure-investigation` (joshuafolkken/kit#2947); the parent checks the cited lines and
+`pnpm josh issue:state` before it parks, re-dispatches or files.
+
 ## `needs-human-review` — the one stop that is not a park
 
 A child carrying **`needs-human-review`** is degraded to a `halfrun`-shaped stop and **the whole run ends

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

@@ -48,13 +48,13 @@ for a whole interval (that exit says so on standard error). **Nothing in flight
 
 **`--mark` at every real report.** Whenever this loop reports something of its own — a child merged,
 parked, a stop — run `pnpm josh run:progress --mark` in the same turn to restart the silence clock. The clock is silence, never a timer
-(`docs/josh-commands.md` → "`josh run:progress`").
+(`docs/josh-commands-automation.md` → "`josh run:progress`").
 
-**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking.
-`scripts/rules/early-heartbeat.ts` → `decide` refuses a sleep-only `Bash` call on three tests — a timer it already allowed is still live, the
-report it would produce would land before the interval is up, or the wait runs longer than the interval
-— so **a single correctly-spaced arm is allowed**. It is still not the way to report; the step above
-prints without arming anything, and `--wait` is not a wait timer.
+**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking
+(`scripts/rules/early-heartbeat.ts` → `decide`), though **a single correctly-spaced arm is allowed**. It
+is still not the way to report; the step above prints without arming anything, and `--wait` is not a
+wait timer. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the heartbeat reads
+as it does".
 
 **The default interval is twenty minutes, overridable — by the person, not the run.**
 `JOSH_PROGRESS_INTERVAL_MINUTES` moves both sides (the guard reads it through the watcher's reader);
@@ -65,14 +65,11 @@ moves the watcher alone** — it makes the watcher quieter than the floor, never
 **Every unscheduled progress statement is answered by `pnpm josh run:progress --once`** — presented in
 the same five field lines, the reply to an explicit ask and the note just after a run starts alike.
 **Never write a clock time the command did not print** (not an approximation, not a placeholder — where
-a field is missing, say so). **`--once` records the report**, so no `--mark` beside it. **A live timer
-is counted from the record the guard writes when it allows one**, never from the machine's `sleep`
-processes.
+a field is missing, say so). **`--once` records the report**, so no `--mark` beside it.
 
 **Every report opens with the time the observation was taken** — not only how long it has been quiet: an
-absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **The date is part of it**, and **the local clock
-leads with UTC beside it and the offset that ties them**. **It is added, never substituted for the
-elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
+absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **It is added, never substituted for
+the elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
 `at` stamp and the `next` field.
 
 **The line carries observations, never "still running", and nothing in it is a verification result** —
@@ -87,8 +84,8 @@ promoted to interrupt, never demoted to requested.**
 
 **The report surface belongs to the run, not to the session** (joshuafolkken/kit#2207). The run's
 session-facing events — a plan posted, a child launched, a PR opened, a review round, a park, a cut, a
-stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`),
-which survives the cut because it is the run's and not any one session's. **Every session is a writer;
+stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`).
+**Every session is a writer;
 the reader is a script in a pane of the person's own, never a conversation** (#2492):
 `pnpm josh run:event --watch` prints each event the moment it lands, in the session language, and the
 `heartbeat` events say the run is alive when quiet. **No session relays the stream** — name the watch command once, at the first cut or when
@@ -106,8 +103,7 @@ remaining child blocked behind a parked one, the backlog drained of anything run
 streak tripped — is pushed to the interrupt tier: `pnpm josh run:carry --end --stopped "<reason>"` sends one ⏸️ confirmation
 as it ends the record, and because the record is gone by the second `--end` the same stop never notifies
 twice. A parked child is pushed by the child itself, which records the park and sends its own
-`confirmation` before it stops (`backlogrun-park.md`). **Nothing new carries either one** — both ride the
-existing notification types and the record the watcher already keeps. Rationale for the tiers:
+`confirmation` before it stops (`backlogrun-park.md`). Rationale for the tiers:
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the signal tiers are split this way".
 
 **A heartbeat is emitted from the moment a run has started, even before any child carries
@@ -146,9 +142,8 @@ long.
 watcher's scope and placement: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the watcher
 runs where it does".
 
-**A run that merges needs no teardown; a run that stops has to end the reporting itself.** The issue
-leaves the `in-progress` listing at the merge, so whatever is waiting prints nothing and `--hours` ends
-it. **A stop keeps that label on purpose** — so **no further `--wait` is started** after the stop
+**A run that merges needs no teardown; a run that stops has to end the reporting itself.** **A stop
+keeps the `in-progress` label on purpose** — so **no further `--wait` is started** after the stop
 notification, and any long-running watcher still in the background is stopped in the same turn. That
 covers `halfrun`'s stop before commit, a `needs-human-review` stop, a split or prerequisite stop, and
 a `backlogrun` named issue's failure stop.
@@ -167,9 +162,9 @@ answers=$(pnpm josh epic:next 858 909 --repo joshuafolkken/kit --lanes)
 # every named epic, merged into the same pool — "Several epics in one run" above
 ```
 
-**`--lanes` is the form to use.** A lane's branch is `<N>-lane`, which `pnpm josh git` commits from, so
-a child handed a lane runs the whole `fullrun` procedure inside it. Read a line per child, and treat a
-single non-numeric line as the verdict.
+**`--lanes` is the form to use.** Read a line per child, and treat a single non-numeric line as the
+verdict. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why a named epic's children
+run in lanes".
 
 1. Run the command above.
 2. **One or more numbers** — where the child runs in this session's own checkout, its `fullrun` claim
@@ -317,8 +312,8 @@ the next turn of this session costs more than the threshold in billed input.
 
 **135,000 is shared by the scheduler entry, scheduler hand-off and lane worker implementation cut.**
 The value is `CONTEXT_CUT_THRESHOLD` in `scripts/cost-runtime/context-cut-threshold.ts`; `cost --cut`,
-`run:merge` and `run_cut.IMPLEMENTATION_CONTEXT_THRESHOLD` all read it rather than carrying separate
-numbers. The output ceiling and the entry-read figure are a separate 150,000, not this threshold.
+`run:merge`, `run_cut.IMPLEMENTATION_CONTEXT_THRESHOLD` and the parent hand-off guard all read it. The
+output ceiling and the entry-read figure are a separate 150,000, not this threshold.
 
 ### The check is asked at every merge, and delegation does not excuse it
 
@@ -333,7 +328,7 @@ answer, and take `over`'s branch at that child.
 
 ### When to ask, and what to do
 
-**Ask once per child, immediately after its merge and `pnpm josh ms`** — never mid-child.
+**Ask once per child, immediately after its merge and `pnpm josh ms`**; mid-child, a hook asks (#2947).
 
 ### A parent without a completion callback hands off at its first dispatch
 
@@ -443,10 +438,9 @@ survive the cut is re-dispatched, never adopted** — `pnpm josh lane:open <N>`
 progress comment is generated from it** (joshuafolkken/kit#2024) — children run, Issues filed,
 **consecutive failures**, and the time the run started. `pnpm josh run:merge` writes the merge into
 the record and mirrors the counters onto the epic comment at every child's merge. **The
-consecutive-failure count is the one that matters** — the stopped-unit section leans on it to notice
-the environment is at fault, and a merge resets it. **The record survives a session cut and a
-compaction alike.** Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives
-in records, not the conversation".
+consecutive-failure count is the one that matters**, and a merge resets it. Rationale:
+`docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives in records, not the
+conversation".
 
 ### What carries over, and where it lives
 
@@ -463,16 +457,18 @@ in records, not the conversation".
 
 ## Waiting, and never waiting forever
 
-| Setting | Value | Why |
+| Setting | Value | Meaning |
 | --- | --- | --- |
 | Polling interval | 60 s | **A floor between two asks, never a clock the parent sets.** It bounds a re-ask made while the parent is *already awake*; what wakes it is "The parent keeps no clock of its own" below. |
 | `backlogrun` idle-watch poll | 5 min | Not the interval above, and a floor in the same sense. |
 | Silent delegated unit | 30 min | Not the child's duration — the time its output has gone **unchanged**. Past it, run the traces above and book a stopped unit as a failure. |
-| Stale `in-progress` | 90 min | Longer than any single child has taken; past it, the other session is gone. |
+| 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. |
-| Whole run | 8 h | An unattended run that has not finished overnight needs a person, not more waiting. |
+| Whole run | 8 h | Past it, the run needs a person. |
 
-Each timeout **ends the wait and reports** — none is retried indefinitely. A stale child's label is
+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 deadlocked on a cycle is not this loop's
 to untangle**: `epic:next` detects it and exits with an error.
 
@@ -487,9 +483,7 @@ source and `run:report` the final report.
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
 clock".
 
-The driver checks lane completion every five seconds and makes a new backlog offer no sooner than one
-minute after the previous offer, except after collecting a child — waits that cost no AI turns. The
-watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
+The watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
 
 #### The wake exists only while something is in flight
 
@@ -527,7 +521,7 @@ Per-child completion notifications are unchanged: `pnpm josh followup` sends one
 **start** notification when the run begins, and an epic **completion** summary at the end. **Do not
 compose that summary by hand — `pnpm josh run:report` generates it from this invocation's events**
 (joshuafolkken/kit#2249, scoped in #2393): it renders what merged, what parked and why, and what was cut,
-reusing `format_event`, closing with the release tail below. Its output is the Telegram body too — pass it to
+closing with the release tail below. Its output is the Telegram body too — pass it to
 `pnpm josh notify --body-file`.
 
 **That same session asks `pnpm josh release:scope` once, after the last child has merged** — in the