@joshuafolkken/kit 1.1050.0 → 1.1128.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/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
@@ -115,13 +116,13 @@ 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` |
-| 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) |
+| 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 — `run:entry` notifies and runs `run:release` (by hand for `new`) | `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` |
 | Something worth filing, none of the three | File it without asking (Tier A, first-party) and carry on; a delegated child returns it to the parent instead | §2i → `observation-filing.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

@@ -28,83 +28,39 @@ command finished.
 
 **Never hand-write a `while`/`until` … `sleep` loop over the output file.** The loop does not know
 when the command finished: a regex that never matches waits to the block limit, and one that matches
-a mid-run line exits too early — either way a full-context round trip is spent for nothing. Six lanes
-lost about 45 minutes, 13% of their wall clock, to exactly this (joshuafolkken/kit#2371), and in the
-worst case a lane grepped a merged PR's output file for 30 minutes after the merge had already
-landed. `pnpm josh rule:guard` refuses the poll loop and hands back this route, so the guarantee is a
-mechanism rather than prose to remember (`prompts/collaboration-workflow/rule-delivery.md`).
+a mid-run line exits too early. `pnpm josh rule:guard` refuses the poll loop and hands back this route
+(`prompts/collaboration-workflow/rule-delivery.md`). Rationale:
+`docs/maintainers/background-commands-rationale.md` → "Why a poll loop is refused".
 
 **To glance at interim output, `Read` the output file once** — the notification names its path — and
 never in a sleep loop. If what you are waiting on is CI, `pnpm josh followup` waits on it for you in
 the foreground; a bare `sleep` that arms a progress heartbeat is `run:progress --wait`'s job, refused
-in front of a hand-armed timer by `early-heartbeat` (joshuafolkken/kit#1570). This loop is the case
-that rule leaves alone by design, because a loop ends on a condition rather than a clock — and here
-the condition it ends on is the wrong one.
-
-## Decision record
-
-This document is read at its point of use, not at the entry: it binds only after the first edit —
-at the gate, the push, the CI wait and `pnpm josh followup` — so it is fetched in full, in the turn
-that reaches the first backgroundable command (`pnpm josh gate`), by the run that has to obey it
-(`SKILL.md` → §1, "Five documents are read at the point of use"). `SKILL.md` → §2h is the resident
-pointer to it, and carries the one thing it does not: the same rule at a batch's scale.
-
-**A run's idle time collects in its tail, and the two ways it collects there are one mistake**
-(joshuafolkken/kit#1510). `fullrun #1501` ran 45m03s on about 17 minutes of work. Of the 25 minutes
-nothing was running, **6m28s** was a `pnpm josh git -y` issued in the **foreground** with a
-900-second tool timeout — above the harness's own 600-second cap, so the harness detached it at the
-cap and nothing read the output file for six and a half minutes afterwards — and **6m06s** was bare
-CI: the push landed, the turn ended, and the merge started only once the person asked whether it was
-merging. Both halves handed the deciding of *when to look back* to something that was never going to
-decide it.
-
-**Issue it in the background, and never give a foreground call a timeout above the harness cap.**
-The cap decides how long a foreground call waits, not the number passed to it, so a number above the
-cap chooses the detached path without choosing the completion notification that should come with it.
-A call issued detached from the start re-invokes the run when it exits — which is what makes the
-completion *delivered* rather than something to remember to poll for.
-
-The measured outliers were a 6m28s foreground `git -y`, 6m06s of unattended CI and a 19m26s push
-transport fault. The operational section above maps those waits to background gate/push and a
-foreground `followup`; `followup.md` remains its command procedure.
-
-**A tail does follow the merge, and it is not small** (joshuafolkken/kit#1462). This section first
-gave a different reason for that last bullet — that the merge ends the run, leaving no tail to
-overlap — and the measurement says otherwise. The run-timing report charges to **`post-run`** exactly what runs
-after the last `followup` span ends: **3.0 min, 5.9% of a 50.5-minute run**, in the lane child
-`--issue 1599` (PR #1602); **2 min 31 s, 14% of 20m15s**, in the plain `fullrun #1597` (PR #1603);
-**3.1 min** hand-measured in run #1441's delegated child, which is where this Issue started. **What
-was wrong is the premise, not the conclusion** — `followup` stays foreground, and what changes is
-*where the tail's work is done*.
-
-**So the tail is emptied before `followup` is issued, rather than worked through after it returns.**
+in front of a hand-armed timer by `early-heartbeat`.
+
+## The tail and what overlaps each wait
+
+**Never give a foreground call a timeout above the harness cap** — the cap decides how long a
+foreground call waits, so a larger number detaches the call without the completion notification.
+Rationale: `docs/maintainers/background-commands-rationale.md` → "Why the tail collects idle time".
+
+**The tail is emptied before `followup` is issued, rather than worked through after it returns.**
 One question decides each step, and it is asked of the step rather than judged: **does it read the
 merge result?**
 
 - **It does — the step stays after `followup`.** `pnpm josh ms`, `pnpm josh issue:state <N>`,
   `pnpm josh epic:next`, `pnpm josh backlog:next --exclude <N>`, and `pnpm josh lane:close` /
-  `pnpm josh lane:list`. Each is a verifier or is keyed to a merge that has to have happened, and
-  bringing one forward would have it read a state nobody has reached yet. **De-duplicating a step is
-  not removing it**: the parent reads the child's state from GitHub *because* a summary is not a
-  verifier ("Each child runs in a delegated unit"), so none of these may be dropped or answered from
-  memory.
+  `pnpm josh lane:list`. **De-duplicating a step is not removing it**: none of these may be dropped or
+  answered from memory.
 - **It does not — the step is composed in the turn that issues `followup`.** The epic progress
-  comment's counter *values* (children run, Issues filed, consecutive failures, the run's start time)
-  are all counted inside the run, and the completion report body is already
-  placed beside `pnpm josh git -y` in the table below. **Only the write follows the merge.** The
-  comment exists because a compaction takes the counters at a moment nobody chooses (`backlogrun-progress.md` →
-  "The counters live in the record"), so composing the values earlier moves no write and loses
-  no counter.
-- **`pnpm josh cost --cut` stays after the merge, and reads nothing from it.** It measures
-  this session's own transcript, so the question above would bring it forward — but its answer grows
-  with the session, and asking it a call early under-reads the very number the hand-off is decided
-  on. It is seconds of tail against a guard on session size, so it keeps its documented seam
-  (`backlogrun-progress.md` → "The check is asked at every merge").
-
-**What runs beside a backgrounded command is the work that writes nothing to the working tree.** That
-is the whole test, and it is the same one that lets the gate and the review overlap (`SKILL.md` →
-§2): a step that edits makes the background command's result stale, so it is not something to overlap
-with. Applied to the three waits a run actually has:
+  comment's counter *values* and the completion report body (placed beside `pnpm josh git -y` in the
+  table below). **Only the write follows the merge.**
+- **`pnpm josh cost --cut` stays after the merge, and reads nothing from it** — its answer grows with
+  the session, so it keeps its documented seam (`backlogrun-progress.md` → "The check is asked at
+  every merge").
+
+**What runs beside a backgrounded command is the work that writes nothing to the working tree** — a
+step that edits makes the background command's result stale. Applied to the three waits a run
+actually has:
 
 | While this runs | Do this beside it |
 | --------------- | ----------------- |
@@ -115,25 +71,21 @@ with. Applied to the three waits a run actually has:
 
 **The turn never ends at the push.** The completion notification for `pnpm josh git -y` is what
 resumes the run, and the turn that reads it goes straight through any branch-2 filing and
-`pnpm josh epic:bundle` to `pnpm josh followup`. joshuafolkken/kit#1333 had already settled that end
-state for a clean second round, and symptom 2 above is its regression — **so the guarantee is a
-mechanism and not only the procedure**: `pnpm josh rule:guard` refuses the foreground push step and
-states both halves at that call (`prompts/collaboration-workflow/rule-delivery.md`). A turn *ending*
-is the absence of a call and no `PreToolUse` hook can see one, so the last call before the seam is
-where the rule can be put; the push reissued detached is not refused again, so a run that obeys pays
-nothing.
-
-**One turn does end before the push, and only one: a dispatched lane child's pre-gate cut**
-(joshuafolkken/kit#1839). It ends the turn before the gate and relaunches a fresh process in the same
-act, so the run continues rather than stalling — the sanctioned boundary distinct from the push
-turn-end this section forbids. The boundary, its two commands and the resume verification are the
-`pre-gate-cut.md` skill document, its single source.
+`pnpm josh epic:bundle` to `pnpm josh followup`. `pnpm josh rule:guard` refuses the foreground push
+step and states both halves at that call (`prompts/collaboration-workflow/rule-delivery.md`); the push
+reissued detached is not refused again. Rationale: `docs/maintainers/background-commands-rationale.md`
+→ "Why the push is guarded".
+
+**One turn does end before the push, and only one: a dispatched lane child's pre-gate cut.** It ends
+the turn before the gate and relaunches a fresh process in the same act — `pre-gate-cut.md` → "Taking
+the cut" is its single source.
 
 **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.
+hold: its background Bash tasks are killed when its turn ends.** It hands the 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; `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

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.
 

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

@@ -18,14 +18,16 @@ by that supervisor; an AI parent is started only for a driver branch that requir
 pnpm josh run:progress --wait --output <the transcript path of each delegated unit>   # in the background
 ```
 
-**`--wait` waits one silence interval out, prints one line and exits** — the long-running form (no
-`--wait`) is right only where output is streamed. The parent changes no value on the line. **Every
-interval is three moves and no fourth:**
+**Start it once; it reports by itself** (joshuafolkken/kit#3102). Each silence interval appends the
+five labelled lines to the run's event stream as a heartbeat and to the ambient log, prints nothing to
+standard output and keeps running — so a scheduled report never wakes the parent, and the parent
+relays none. **It exits only on one of three, and the command computes which:**
 
-1. Start `pnpm josh run:progress --wait --output <transcript paths>` **in the background**.
-2. When it exits, **present what it printed as-is** — the command prints the five labelled lines and the
-   next report time itself.
-3. **In that same turn, start the next one.** The interval is measured from the last report.
+| Exit                                                    | What the parent does                                                   |
+| ------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Newly runnable backlog work (the `ready #N` line)       | Read the ready line, act on it, and restart the watcher in that turn  |
+| `pnpm josh followup` removed the run's life record      | Nothing — the run has ended                                            |
+| `--hours` elapsed (8 by default for `--wait`)           | Restart the watcher in that turn                                       |
 
 **`pnpm josh run:watcher:guard` detects a missed restart** (joshuafolkken/kit#2113): it refuses when
 lane children are in-flight but the watcher's life record has gone stale. **It is wired into
@@ -33,22 +35,22 @@ lane children are in-flight but the watcher's life record has gone stale. **It i
 until the watcher is restarted — once per run, so the `pnpm josh run:progress --wait` that fixes it is
 not blocked.
 
-**`run:progress` prints the five labelled lines itself (joshuafolkken/kit#2026); present them as-is.** It emits the observation instant (`at`, local first and UTC beside it), the elapsed figures
+**`run:progress` writes the five labelled lines itself (joshuafolkken/kit#2026).** It emits the observation instant (`at`, local first and UTC beside it), the elapsed figures
 (`quiet` and `unchanged`), the children in flight, the run state (`lanes`, `load`, `record`), and the
-scheduled `next`, each behind its own label and on its own line — so relay the output verbatim and
-round, rephrase or re-label nothing. How each field reads when it has nothing to report (`record
+scheduled `next`, each behind its own label and on its own line — so where a session does present them
+(`--once`), it relays the output verbatim and rounds, rephrases or re-labels nothing. How each field reads when it has nothing to report (`record
 unread`, `no in-progress child yet`, `lanes none`, an absent `next`) is fixed by the command's own unit
 tests. **A value said that way is still an observation, never a state**: `record unread` means no
 `--output` path was given, not *not stalled*; `lanes none` is *no lane is open*, not *nothing is
 running*; and the `next` line is a schedule — the time *if the silence continues*, superseded when a
 real report resets the clock through `--mark`.
 
-**It exits only when it has a line to hand over**, or when `--hours` runs out having never gone quiet
-for a whole interval (that exit says so on standard error). **Nothing in flight keeps it waiting.**
+**A report is not an exit, and neither is a decline** — with no run recorded it keeps waiting, and the
+`--hours` exit says so on standard error.
 
 **`--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`), though **a single correctly-spaced arm is allowed**. It
@@ -130,21 +132,13 @@ in the same turn as each: **the Step 0 work summary, the pull request opening, e
 verdict, and any `confirmation` / `failure` / `completion` notification or stop.** **A tool result only
 you read is not one** — a gate run, a `gh` read, an edit.
 
-**On a quiet tick the turn is the relayed line plus at most two lines of the run's own prose**, saying
-only what changed stage and what is being waited on. **A tick is quiet when none of the real reports
-happened since the last one**; a gate that went green, a review round, a file edited, a poll answering
-`wait` are the run working, not a report. **No table, no re-listing of children, no restating of the
-plan** — `epic:next`, the epic body and the progress comment hold all three. **A real report is not
-bounded by that**: `--mark` restarts the clock, so a merge, a park or a stop is where the run may be
-long.
-
 **`--output` is omitted in a single-issue run, and `record` reads `unread`.** Rationale for the
 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.** **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
+notification, and the running `--wait` is stopped in the same turn, since no report ends it. 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.
 
@@ -275,11 +269,12 @@ run in lanes".
    a session that cannot measure is read as `over`. **Never read the condition off `pnpm josh delegate
    epic-child`** ("The check is asked at every merge" below).
 3. **`wait`** — go back to step 1. **With something of this run's own in flight, that happens on the
-   wake the progress watcher's exit delivers** and the parent starts no sleep of its own; the 60 s
-   figure bounds how soon the ask may be repeated. **With nothing in flight the watcher declines and
-   never exits, so the parent keeps the interval** — the case for "another repository has work but this
-   one does not", and for a cross-repository publish wait. The table in "The wake exists only while
-   something is in flight" below decides which.
+   wake `lane:await` or the progress watcher's arrival exit delivers** and the parent starts no sleep
+   of its own; the 60 s figure bounds how soon the ask may be repeated. **A scheduled report is not one
+   of those wakes** (joshuafolkken/kit#3102). **With nothing in flight neither wake comes, so the parent
+   keeps the interval** — the case for "another repository has work but this one does not", and for a
+   cross-repository publish wait. "The wake exists only while something is in flight" below decides
+   which.
 4. **`stop`** — report the parked children and finish.
 5. **`complete`** — post the epic summary and finish.
 6. **Exit code 1** — `epic:next` refused a cyclic or contradictory graph, or could not read a child.
@@ -421,8 +416,8 @@ in the background, in the same turn as that first `lane:list`. The wired `run:wa
 
 **A carried-over child finishes in its own detached unit, and the resumed parent does not stand in front
 of its merge.** A lane handed over at the cut is still running its own `fullrun` — the foreground
-`pnpm josh followup` and the CI wait included — in a process of its own (background-commands.md →
-"`pnpm josh followup` — foreground": foreground is *within the unit*, the background from the parent).
+`pnpm josh followup` and the CI wait included — in a process of its own (`background-commands.md` →
+"Background the gate and push": foreground is *within the unit*, the background from the parent).
 **So the parent never runs a carried-over child's `followup` itself**: it polls the handed-over lane and
 opens new work beside it. **The reads and the dispatches go out together, in one turn** — `pnpm josh lane:list`,
 `pnpm josh run:liveness`, `epic:next --lanes`, and opening a lane for a child it offers take none of each
@@ -472,7 +467,7 @@ 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.
 
-### The parent keeps no clock of its own — the watcher's exit is the wake
+### The parent keeps no clock of its own — a child's completion or an arrival is the wake
 
 **After hand-off, the supervisor's driver owns the mechanical clock.** `backlog:drive` polls lane
 completion and the backlog inside the detached process, without waking an AI parent; the parent-turn
@@ -483,12 +478,14 @@ source and `run:report` the final report.
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
 clock".
 
-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 to the event stream and exits only on an arrival, so a judgment
+session takes that exit — or a `lane:await` completion — as its prompt to act, never a report.
 
 #### The wake exists only while something is in flight
 
-`run:progress --wait` prints only when it has a human-facing line. With no child in flight it may
-decline; the driver still polls for new work and enforces the idle and whole-run bounds. A GitHub
+`lane:await` wakes on a child's completion and `run:progress --wait` on an arrival; its reports wake
+nobody. With no child in flight it may decline; the driver still polls for new work and enforces the
+idle and whole-run bounds. A GitHub
 listing failure stays a retry or unreadable answer from the offer command, never an empty backlog.
 
 `epic:next` does not report when a label was applied, so read that from the issue's timeline: