@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

@@ -7,9 +7,7 @@ commands themselves; the dependency declaration this file builds on is `SKILL.md
 
 **A wave is not a mechanism, and there is nothing to add for one.** "Run #A, #B and #C together, then
 #D by itself, then the rest together" is already expressible with the dependency declaration
-`SKILL.md` describes, and wanting it only became common once parallel lanes
-(joshuafolkken/kit#1170) let several children run at once. What was missing was never the mechanism —
-it was that nobody had written down how to build one, or when not to (joshuafolkken/kit#1584).
+`SKILL.md` describes.
 
 ## The shape
 
@@ -34,10 +32,10 @@ as **no declaration at all** rather than as an error — and `#A` / `#B` are not
 The lines go into the epic body unfenced, with real numbers.
 
 **Deleting a declared order is `pnpm josh epic --remove <E> <M> <N> [<N2> …]`, and never a hand edit
-either** (joshuafolkken/kit#1712). The arguments are a path, so each consecutive pair is one order and
-a whole chain goes in one call; the body's declaration and the `blocked-by` relations are written from
-that one input, exactly as `--add` writes them. **The ends are never reconnected** — `#A -> #B -> #C`
-minus `#B -> #C` leaves `#A -> #B`, and taking out a middle child's two links leaves `#A` and `#C`
+either.** The arguments are a path, so each consecutive pair is one order and a whole chain goes in
+one call; the body's declaration and the `blocked-by` relations are written from that one input,
+exactly as `--add` writes them. **The ends are never reconnected** — `#A -> #B -> #C` minus
+`#B -> #C` leaves `#A -> #B`, and taking out a middle child's two links leaves `#A` and `#C`
 unordered rather than declaring `#A -> #C`. Deleting the last link writes the unordered sentence, so
 the section never ends up with no machine-readable declaration. Pass `--decision-file` to record why;
 the record lands on the epic's `## Decisions` and on both ends of every deleted order. Doing either
@@ -49,18 +47,12 @@ half by hand is the `declaration_mismatch` below, arrived at from the other dire
 in `Dependencies` — is what a wave has to satisfy, and editing the body alone satisfies half of it.
 **`--before <hub>` and `--after <hub>` are both refused while the hub sits in more than one chain
 with nothing after it** — which is exactly what a hub is the moment the earlier wave has been chained
-into it. `chains_containing` finds several indices; `is_branching_after` does not hold, because it
-requires a successor in **every** chain naming the target and a hub has none in any of them; so
-`ambiguous_position_error` is raised (`scripts/epic/epic-chains.ts`). **The first child of the
-next wave therefore goes into the declaration by hand**, with its `blocked-by` recorded to match.
-Once the hub has a successor, `--after <hub>` branches a new line and the rest of that wave goes in
-with it.
-
-**Nothing in the parsing or the consistency check forbids this.** `DECLARED_CHAIN_LINE` in `scripts/epic/epic-parse.ts`
-asks only that a line be *nothing but* a chain, so there may be any number of chain lines and **one
-child may be an endpoint of several of them** — `parse_dependency_links` expands each line
-independently and flattens the result, dropping only self-loops. `find_anomalies` in
-`scripts/epic/epic-graph.ts` rejects exactly two things, a **cycle** and a **disagreement between the
+into it. **The first child of the next wave therefore goes into the declaration by hand**, with its
+`blocked-by` recorded to match. Once the hub has a successor, `--after <hub>` branches a new line and
+the rest of that wave goes in with it.
+
+**Any number of chain lines is allowed, and one child may be an endpoint of several of them.** The
+consistency check rejects exactly two things, a **cycle** and a **disagreement between the
 declaration and the recorded `blocked-by`**; a fan-in and a fan-out are neither.
 
 **The number of lines is the size of the widest wave**, because a one-child wave is a hub and the
@@ -72,9 +64,7 @@ looking for a shorter notation.
 
 **There is no `solo` mechanism, and none is needed.** "This one must not run beside anything" is the
 shape above with a wave of size one: chain into it every child that must not overlap it, and out of
-it every child that must not precede it. Adding a third axis — an exclusivity label, an
-`## Exclusive` section — would put a second way to say what the dependency declaration already says,
-and a second consistency check to keep the two agreeing.
+it every child that must not precede it.
 
 ## When a wave may be declared
 
@@ -82,15 +72,19 @@ and a second consistency check to keep the two agreeing.
 condition, and it is narrower than it sounds:
 
 - **A mere preference of order is not a dependency.** Wanting one child to go first — to see its
-  result early, to get the risky one out of the way — is presentation order, and joshuafolkken/kit#1583
+  result early, to get the risky one out of the way — is presentation order, and the task-list order
   is where that belongs. Substituting a dependency for it buys the order and pays with the stall below.
-  **Write it with `--order-before <M>` / `--order-after <M>`** (joshuafolkken/kit#1738), which move the
-  task-list row and declare nothing; `--before` / `--after` are for an order that really is a
-  dependency. Neither of the order-only flags helps at a **wave boundary**, which is a dependency by
-  definition — the hub case below stays what it is.
-- **Two children that would edit the same file** are the case with no better answer today: separating
-  them into different waves is how it is done, and the price — a fixed order, plus the stall — is
-  accepted knowingly rather than by default.
+  **Write it with `--order-before <M>` / `--order-after <M>`**, which move the task-list row and
+  declare nothing; `--before` / `--after` are for an order that really is a dependency. Neither of the
+  order-only flags helps at a **wave boundary**, which is a dependency by definition — the hub case
+  above stays what it is.
+- **Two children that merely edit the same file are not a dependency.** A textual conflict resolves
+  inside the lane: every run merges `origin/main` before its gate (`pnpm josh main:merge`), and an
+  overlap that lands after it is resolved where it surfaces (`backlogrun-recovery.md` → "Conflicts are
+  not predicted"). Run them in parallel; the per-conflict price is `backlogrun-lanes.md` → "Lanes —
+  running more than one child at a time".
+- **Two children that would each build the same mechanism are a dependency.** No merge reconciles two
+  implementations of one thing — the later child must build on the earlier one's, so the boundary stays.
 - **No reason to wait means no declaration.** An epic whose children are mostly independent says so in
   prose and leaves the graph empty.
 
@@ -100,27 +94,12 @@ condition, and it is narrower than it sounds:
 `from_blockers` in `scripts/epic/epic-classify.ts` propagates `human`: a wave-1 child labelled
 `needs-decision` makes every child behind it "waiting on a person" rather than "waiting on time".
 
-**The park itself is not the halt, and reading it as one hides how the cost arrives.** `backlogrun` parks
-that child and goes on running the rest of wave 1 exactly as it always does; the session stops once
-those close and nothing is runnable, because every later wave has been classified `human`. So a
-boundary is paid for at the *end* of the wave rather than at the moment one child parks — which is
-what makes one easy to declare and expensive to have declared. **Clearing it is removing that child's
+**The park itself is not the halt.** `backlogrun` parks that child and goes on running the rest of
+wave 1 exactly as it always does; the session stops once those close and nothing is runnable,
+because every later wave has been classified `human`. So a boundary is paid for at the *end* of the
+wave rather than at the moment one child parks. **Clearing it is removing that child's
 `needs-decision`** once the decision has been recorded — the removal recording a decision already
 requires — after which the waves behind it become runnable on the next round.
 
-This is why the answer to "how do I build waves" is a paragraph rather than a feature. **A wave is
-declared for a real wait and removed when the wait ends; it is not the standing shape of an epic.**
-
-## The worked example — joshuafolkken/kit#1474
-
-That epic has grown to **46 children while its declared chains have stayed at three**, and its body
-says why:
-
-> **鎖として宣言していない。** 19 件はほぼ独立しており、順序を依存として宣言すると 1 件詰まっただけ
-> で残り全部が止まる。以下は推奨であって制約ではない。
-
-The nineteen that paragraph was written about are ordered in **prose — a group, not a graph** — so a
-reader gets the intent and no run is stopped by it, and none of the children added since has needed a
-chain either. joshuafolkken/kit#1262 is the same lesson from the other
-side: **24 false dependencies invented by `epic --add` have been removed from it**, each one an order
-nobody needed that could have stopped everything behind it.
+**A wave is declared for a real wait and removed when the wait ends; it is not the standing shape of
+an epic.**

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

@@ -1,14 +1,14 @@
 ---
 name: verify-ui
-description: Close the UI verification gate on a change that alters the rendered screen — capture a screenshot of the affected route through this project's own screenshot command, look at it, and report whether it matches the intent. Use it before reporting any UI, layout, styling, copy, visible-state or interaction change as done. It reports that the project has no screenshot command rather than passing when it cannot capture anything.
+description: Screenshot the affected route with the project's own command and check it matches the intent. Use it before reporting any UI, layout, styling, copy or interaction change as done.
 argument-hint: '[route] [route...]'
 ---
 
 # Verify the rendered screen
 
 The completion gate in `CLAUDE.md` says a change that affects the rendered UI is not done until
-someone has looked at the rendered result. Passing unit and E2E tests are not that look: they stay
-green while spacing, layout and styling are visibly broken. This skill is the look.
+someone has looked at the rendered result; passing unit and E2E tests are not that look. This skill is
+the look. Rationale: `docs/maintainers/verify-ui-rationale.md` → "Why the skill reads as it does".
 
 ## 1. Decide which routes to capture
 
@@ -33,10 +33,9 @@ Look for it in this order and stop at the first hit:
 2. `pnpm josh-game shot` — the game toolkit (`@joshuafolkken/game-kit`).
 3. A project-local script named `shot`, `screenshot` or `verify:ui` in `package.json`.
 
-Option 1 exists: `shot` shipped in app-kit 0.86.0 (joshuafolkken/app-kit#200). Option 2 does not
-yet — game-kit carries no `shot` — so a game project still lands on option 3 or the fallback below.
-Neither statement is a substitute for the check in the next paragraph: both are true of a version,
-and the version a project has installed is the only thing that decides.
+Option 1 exists since app-kit 0.86.0; game-kit carries no `shot` yet, so a game project lands on
+option 3 or the fallback below. Both are true of a version, and
+the version a project has installed is the only thing that decides.
 
 **Decide by the printed command list, not by whether the toolkit is installed.** Run the toolkit
 with no subcommand (`pnpm josh-app`) and read the usage line it prints; `shot` exists only if that
@@ -50,9 +49,7 @@ The gate still has to be met, so fall back in this order.
 
 **Capture through the project's own E2E suite.** If it has Playwright specs, add a
 `await page.screenshot({ path: … })` to the spec that already covers the affected screen — or a new
-spec if none does — and run it. This is a real capture and it is committed test code, which is why
-it is a fallback and not a workaround: it leaves the project with a screenshot the next run can take
-again.
+spec if none does — and run it.
 
 **Otherwise stop and say so.** Report, in the session language:
 
@@ -62,25 +59,21 @@ again.
 - that the change needs a human to look at the screen, and ask the user to do it.
 
 Never report the gate as satisfied on tests alone. Never stand up a preview server by hand and drive
-it from a throwaway script left outside the repository: server lifecycle is what the toolkit command
-owns, and an improvised one leaves a process running and nothing the next run can reuse. If the
-project should have the command and does not, that is an issue to file against the application
-toolkit.
+it from a throwaway script left outside the repository. If the project should have the command and
+does not, that is an issue to file against the application toolkit.
 
 ## 3. Capture
 
-Run the command once for every route in a single invocation (`pnpm josh-app shot / /blog`). One
-invocation is what keeps the build and the preview server to one start and one stop. Wait for it to
-finish and note the output directory it prints. On the E2E fallback, run the spec and note where its
+Run the command once for every route in a single invocation (`pnpm josh-app shot / /blog`). Wait for
+it to finish and note the output directory it prints. On the E2E fallback, run the spec and note where its
 `path` option wrote the images.
 
 If it exits non-zero, report the failure as the result. A failed capture is not a passed gate.
 
 ## 4. Look at the images
 
-Read every produced image with the Read tool. Actually look at each one — the point of the gate is
-the look, and a run that captures files without opening them has done nothing the tests did not
-already do.
+Read every produced image with the Read tool. Actually look at each one — capturing files without
+opening them does not close the gate.
 
 Check what the change was supposed to do to the screen: the element is present, in the right place,
 at the right size, with the intended spacing, color and text; nothing that used to be there has

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

@@ -1,13 +1,14 @@
 ---
 name: workflow-commands
-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.
+description: Procedures for `kickoff`, `fullrun`, `halfrun`, `prrun` and `backlogrun`. Read it the moment one is typed (with or without `#N` / `new`), before any command, and when asked what one does or a run must be resumed or repaired.
 ---
 
 # 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** (joshuafolkken/kit#3174): each rule is stated once, in the file its row names.
+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".
 
 ## 0. The rule that fires before any of them — explicit invocation
 
@@ -48,13 +49,13 @@ Each is fetched at its named scope, in the same turn, by the named command that
 | ----------------------- | ------------------------------------------------------------------------------ |
 | `latest-gate.md`        | `pnpm josh latest:scope` answers `required` — before `josh latest` runs         |
 | `followup.md` → "Run `pnpm josh followup`" | Before issuing `pnpm josh followup`, in that same turn |
-| `chain-rule.md` → "Run the review-to-merge chain" | Before the first `pnpm josh gate` launch (`fullrun` / `backlogrun`) — the gate starts overlapped with the review, so the section is read before the gate |
-| `background-commands.md` → "Background the gate and push" | Before backgrounding `pnpm josh gate` — the first long-running command a run detaches (`fullrun` / `halfrun` / `backlogrun`) |
+| `chain-rule.md` → "Run the review-to-merge chain" | Before the first `pnpm josh gate` launch (`fullrun` / `prrun` / `backlogrun`) — the gate overlaps the review, so the section is read before it |
+| `background-commands.md` → "Background the gate and push" | Before backgrounding `pnpm josh gate` — the first long-running command a run detaches (`fullrun` / `halfrun` / `prrun` / `backlogrun`) |
 
 A `skip` answer from `latest:scope` reads nothing. **A lane child that parks reads
 `backlogrun-park.md` → "park and continue" at that point of use**, and **every implementing run reads
 `progress-watcher.md` → "Progress while the run is quiet"** before starting `pnpm josh run:progress
---wait` once its hold is claimed (joshuafolkken/kit#3172).
+--wait` once its hold is claimed.
 
 ### A section reference is read as a section
 
@@ -65,8 +66,7 @@ pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim
 pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs
 ```
 
-A heading that does not resolve is refused, with the file's own headings listed. The set is derived
-from the table above and the documents themselves, never transcribed.
+A heading that does not resolve is refused, with the file's own headings listed.
 
 ## 2. What every one of them shares
 
@@ -91,11 +91,11 @@ from — read at that trigger, never restated here.
 | Implementation is done | Refactor → `pnpm josh main:merge` → `pnpm josh gate` beside a subagent `/code-review`, joined before the commit → round cap → PR → merge | `chain-rule.md` → "Run the review-to-merge chain" |
 | 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" |
 | A command can take minutes | Issue it in the background; the turn never ends at the push (`pnpm josh followup` stays foreground) | `background-commands.md` → "Background the gate and push" |
-| 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" |
+| E2E gate | The CI E2E job where the command ends in a PR (`fullrun` / `prrun` / `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" |
 | Filing any new Issue | `pnpm josh issue:file` — it runs the `issue:scout` scan first; read its duplicate and epic answers | `issue-scout.md` |
 | Another Issue here must land first | A prerequisite is a dependency, not a park — file it, stash, record the dependency; `fullrun` / `halfrun` stop, `backlogrun` continues | `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 | `observation-filing.md` |
-| A defect in kit's own verification turns up | It runs alone when all three conditions hold; a batch resumes once it merges | `backlogrun-lanes.md` → "Lanes — running more than one child at a time" |
+| Something worth filing, none of the three | Unattended: file it (Tier A, first-party); else ask; a delegated child returns it to the parent instead | `observation-filing.md` |
+| A defect in kit's own verification turns up | It runs alone when all three conditions hold; a batch resumes once it merges | `backlogrun-lanes.md` → "A solo run" |
 | 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` |
 | `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` |

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

@@ -3,12 +3,12 @@
 ## Background the gate and push
 
 - **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.
+  foreground `followup` → `run:tail`). 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
   at the push.
 - Keep `pnpm josh followup` in the foreground — nearly every following step reads its result.
-- **Record before the CI wait ends, never after the merge** (joshuafolkken/kit#2763): the commit
+- **Record before the CI wait ends, never after the merge**: the commit
   carries the observation ledger lines recorded so far, and while CI runs the run makes the records
   that need no CI result — observation Issues, the completion report draft.
 - Overlap only tree-readers, and compose merge-independent tail data before `followup` (the table
@@ -17,6 +17,7 @@
 - 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
 
@@ -82,8 +83,7 @@ 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.** 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
+a foreground `pnpm josh ship --detach` instead (`chain-rule.md` step 0); `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.
 

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

@@ -1,12 +1,6 @@
 # `backlogrun` — running a child (shared mechanics, delegation, liveness, session setup)
 
-**Read this file in full once per session — before the first child is dispatched**, in the turn that
-reaches `pnpm josh delegate epic-child` (or `pnpm josh lane:dispatch`). **A later child does not re-read
-the whole file; it fetches only the section that child needs** — `pnpm josh doc:section backlogrun-child.md
-"<heading>"`. It is a point-of-use document, never an entry read: the entry procedure is `backlogrun.md`,
-which points here at that step. This file is the single source of how one `backlogrun` child — of a
-named epic, a named issue, or the opted-in pool — is run. Rationale:
-`docs/maintainers/backlogrun-child-rationale.md` → "Why the file is read once and then by section".
+Point-of-use, read one section at a time from `backlogrun.md` → "The route table" (rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why the file is read by section").
 
 ## Running a child — the shared mechanics
 
@@ -66,85 +60,35 @@ reference is named, the refusal is the whole answer. Where several are, a task-l
 `backlogrun #<N>` on its own after the epic.
 ## Each child runs in a delegated unit
 
-**A child is not run in the parent loop's context.** One child goes to an isolated execution unit,
-and only its summary comes back. Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why
-each child runs in a delegated unit".
+**A child is not run in the parent loop's context** — **whatever offers a child — the loop, or a
+person clearing a label — the child is handed to a lane, never to the parent.** `pnpm josh delegate
+epic-child` answers `delegate`; in a lane the unit is a detached process started by `pnpm josh
+lane:launch` (`backlogrun-lanes.md` → "Opening one lane and dispatching its child"), with the invoking
+CLI's `worker` profile — Claude Code defaults to Anthropic `claude-opus-5-5` / `medium`
+(`docs/josh-commands-run.md` → "`josh lane:dispatch`", the single source).
+Where no isolated unit exists, run the child in the parent's context; the hand-off is still asked at
+every merge. Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why each child runs in a
+delegated unit".
 
-**The supervisor's driver is the mechanical parent after hand-off.** It uses the same lane dispatch
-and GitHub verification commands; an AI parent handles only a returned judgment branch. *Every* child takes a
-delegated unit — a fresh one and **a child just released from `needs-decision`** alike. The rule is
-one sentence: **whatever offers a child — the loop, or a person clearing a label — the child is handed
-to a lane, never to the parent.**
+**The parent reads GitHub, never the summary** — `pnpm josh issue:state <N>` (or `run:merge`) is the
+verifier; **never advance the loop on the summary alone**.
 
-**The mechanism is the one `pnpm josh delegate` defines** — the enumeration plus the command — with
-the unit changed from one step of a run to one child of an epic. Never build a second. Ask the command
-rather than deciding:
+**The brief names the invocation it descends from** — e.g. `backlogrun #<E> --only`, the child number,
+and that the child runs as `fullrun #<N>` under that authorization; the unit refuses a brief without it.
 
-```bash
-pnpm josh delegate epic-child   # → delegate
-```
-
-**In a lane, that unit is a detached operating-system process rather than a subagent of this
-session.** The verifier is still `pnpm josh issue:state <N>` read from GitHub, and the summary is
-still bounded at 25 lines. `pnpm josh lane:dispatch` is where a lane's child is started; "Handing the
-child over" in `backlogrun-lanes.md` carries the command.
-
-**The lane child uses the invoking CLI's `worker` profile.** Claude Code defaults to Anthropic
-`claude-opus-5-5` / `medium`; Codex uses `codex exec`, OpenAI `gpt-6.1-sol` / `medium`, workspace-write and
-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-run.md` → "`josh lane:dispatch`" is the single source.
+### What the summary carries, and how long it may be
 
-**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
-in one call. The child's own gate, `/code-review` and CI run inside the unit. **Never advance the
-loop on the summary alone** — that discards the verifier.
+**The summary carries only what GitHub does not, in at most 25 lines; the brief states the bound.**
+Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why the summary is bounded the way it is".
 
-### What the summary carries, and how long it may be
+- **Kept**: `Cause` / `Fix` / `Result`; every verification result not closed the ordinary way, named
+  as such; observations that could bite later — **the only route a child's discretionary observation
+  has** (`observation-filing.md` → "A delegated child does not take this route"); decisions not already
+  logged; what was left undone, and under whose authority.
+- **Cut**: the changed-file list, per-round review detail, and restated rules.
 
-**The summary's only job is to carry what GitHub does not.** Both lists below are written out, and the
-brief hands them to the unit. Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why the
-summary is bounded the way it is".
-
-**Always kept — five things, because none of them is anywhere else:**
-
-1. **`Cause` / `Fix` / `Result`**, the three plain lines — the parent's orientation.
-2. **Every verification result the run did not close in the ordinary way**, named as such. A result
-   nobody obtained must never reach the parent as a run that passed.
-3. **Observations that could bite later** — something noticed and not filed, a flaky check, a
-   surprising diff, work a later child will collide with. **This is the only route a child's
-   discretionary observation has**: a child files `route:tier-a` and `route:interrupt` only, and the
-   parent files what survives — `observation-filing.md`, the single source. **What the parent does with the
-   rest is append it, not drop it**: an observation that cannot cite the depth-0 work it blocked
-   becomes one line in the observation ledger, and a second line under the same key files it. **A
-   child appends only to its own issue's file, `.josh/observations/<N>.md`, in its own
-   lane** (joshuafolkken/kit#2919) — it merges with the child's pull request, and a sibling lane's
-   file is never one it touches.
-4. **Decisions taken and why**, where the decision was not already logged as an Issue comment.
-5. **What was left undone**, and under whose authority.
-
-**Always cut — three things, because GitHub already holds them:** the changed-file enumeration (the
-pull request's own file list), the per-round review detail (each round's verdict is one line; the
-findings are on the pull request), and restatements of rules the parent already holds.
-
-**The bound is 25 lines, and it is a number so that it is not a judgement.** **The brief states the
-bound.**
-
-**This does not shorten the person-facing completion report.**
-`prompts/collaboration-workflow/report-format.md` → 「完了報告（セッション向け）」 is unchanged. What is
-bounded here is the child's hand-back to the parent.
-
-**Read the state directly rather than asking `epic:next` again.** A child that did not finish still
-carries `in-progress`, which `epic:next` classifies as waiting on time before it consults any blocker.
-
-**The merge authorization reaches the unit**, and **so does the explicit invocation**. **The brief
-therefore names the invocation it descends from** — `backlogrun #<E> --only`, the child number, and that
-the child is to be run as `fullrun #<N>` under that authorization. A brief that omits it is the defect,
-and the unit refuses it.
-
-**Where no isolated unit exists, run the child in the parent's context.** The hand-off below is still
-asked at every merge; delegation is not an alternative to it.
+The person-facing report (`prompts/collaboration-workflow/report-format.md` → 「完了報告（セッション向け）」)
+is unchanged.
 
 ## A delegated unit that stopped without reporting
 
@@ -168,35 +112,16 @@ back a child number — before implementing that child — and never again:
 ```bash
 pnpm josh latest:scope   # → required | skip ; the reason on stderr
 git stash push -u -m "backlogrun: josh latest #<N>"        # only if the tree has staged or modified files — never conditional on the answer
-git switch main && git pull
+pnpm josh ms
 pnpm josh latest         # on `required` only
 pnpm josh stash:pop "backlogrun: josh latest #<N>"         # only if you stashed above — by message, not a positional pop
 ```
 
-On `required`, load the `dependency-update` skill and follow its procedure — the overrides in **both**
-`pnpm-workspace.yaml` and `package.json`, and the one expected `devEngines` pnpm bump. **The answer is
-the command's, never a judgement**, and `latest-gate.md` is its single source.
-
-**Session, not run** — each session runs one repository's children, so each updates its own checkout;
-never skip it because another repository's session already ran it. **Never ask it before a child is
-in hand.**
-
-**The lock file the update rewrites lands with the first child.** The first child's `pnpm josh git -y`
-commits it — so that one PR carries the dependency bumps and the other children carry none. Should the
-first child fail CI on a bump, fix it forward before parking it.
-
-**`git switch main && git pull` stays per child** — it brings the previous child's merge into the tree,
-and a child that skips it implements on a stale main. Only the dependency update moves to the run. **In
-lanes it changes hands**: no lane can switch to the default branch, so the parent runs it in the primary
-checkout **before each `lane:open`**. **And in a lane `josh latest` is not even asked** — `latest:scope`
-skips and `latest:guard` refuses. The stash that carries the lock file into the first lane is in
-`backlogrun-lanes.md` → "Once per repository, before the first lane opens": the parent runs the update
-and pushes the stash in the primary checkout before `backlog:drive` starts, and the driver passes it
-to the first lane it launches.
-
-This is the same rule `latest-gate.md` is the single source of.
-
-**A resumed `backlogrun` is a new session**, so it asks once again before its first child.
+On `required`, load the `dependency-update` skill; `latest-gate.md` is the single source. **Session,
+not run** — each session updates its own checkout, and a resumed `backlogrun` asks again. **The lock
+file lands with the first child's `pnpm josh git -y`**; fix a failing bump forward. **`josh latest` is
+never run inside a lane** (`pnpm josh latest:guard` refuses it) — with lanes the parent runs it in the
+primary checkout (`backlogrun-lanes.md` → "Once per repository, before the first lane opens").
 
 Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why `josh latest` is hoisted to the
 session".

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

@@ -0,0 +1,29 @@
+# `backlogrun` — the hand-off report
+
+The format of the report a `backlogrun` writes when it hands the rest of a batch to a new session —
+read when the run stops at the hand-off (`backlogrun-progress.md` → "The hand-off"). The two-layer
+structure and the label translations are `prompts/collaboration-workflow/report-format.md`.
+
+**The hand-off is a fourth kind of stop — not a completion, a park or a failure.**
+**It never uses `Cause` / `Fix` / `Result`**: an unfinished epic would read as finished.
+
+```md
+**■ 区切り**
+
+- **終わったこと**: <このセッションでマージした子を番号で名指しする>
+- **残っていること**: <残りの子を件数と番号で名指しする。park した子はその旨も>
+- **止めた理由**: <なぜここで区切ったか。判断ではなくコマンドの答えを書く>
+- **次に打つコマンド**: <このランを再開するコマンド。`backlogrun` なら残りだけの `backlogrun #<next> #<after> …`（指定 epic だけなら `backlogrun #<E> --only`）>
+
+**技術詳細**
+
+- 計測: <`pnpm josh cost` が出した値と閾値>
+- 引き継ぎ: <状態は GitHub にあり、会話には何も無いこと>
+```
+
+- One sentence per line, no internal identifiers, every child named by number. **Never omit
+  `Remaining`** — it is the one line that tells this report from a completion report
+- Telegram uses the same format and is **sent with `--task-type confirmation`** (`completion` would
+  announce an unfinished epic as done)
+- **Write it only when the run stops.** While a run carries on past the threshold it writes none; the
+  epic progress comment is the record