@joshuafolkken/kit 1.1455.0 → 1.1514.0

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

@@ -1,44 +1,34 @@
 # `epic:bundle` — the detail behind the answer
 
-**Read this when a filing's `epic:bundle` answer places the issue** — `add_to_epic`, `create_epic`,
-or a choice between epics — or when the answer is one the summary in the `epic-commands` skill
-(`SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with one already filed?") does not
-settle. `Nothing to bundle.` needs neither.
-
-**Only two things count as a signal**: the issues referring to each other in prose, or a `blocked-by`
-already recorded between them. **A similar title never counts on its own** — "related" expands
-without limit, and the threshold is what keeps an unrelated issue out.
-
-**The release issue is neither a candidate nor a subject**, like an epic. `issue:file --release` records
-every change awaiting publication as its blocker, so that relation is mechanical, not a sign of shared
-work. Counted as a signal, it would put the release and an unrelated change in one epic. A
-`blocked-by` or a prose reference between any other two issues still counts.
-
-**The search is not limited to the open backlog.** Every issue number the subject's body names is read
-on its own, whatever its state. A **closed** reference counts only when an open epic already tracks
-it, since the answer worth recovering is `add_to_epic`; an epic created over a closed issue has
-nothing left to run. An **open** reference counts either way. A read that fails — and a reference the
-per-issue cap never reached — is reported as a gap, never folded into "no strong signal". A number
-that answers with a **pull request** is not a candidate at all: `repos/{owner}/{repo}/issues/<N>`
-serves one too, and a merged PR does not report `CLOSED`.
-
-**A number that does not exist is not a gap.** A typo, or another repository's number quoted in
-prose, is dropped in silence — neither a candidate nor something the command reports it could not
-read. **The two are told apart by HTTP status, never by `gh`'s wording**: 404 is nothing at that
-number, 403 and 429 are a rate limit. The referenced-number reads are capped at twenty, and **only
-the subject's own body is followed**.
-
-**`none` is a legitimate answer** — a self-review outside any workflow has no current issue to point
-at, so the issue stays in the backlog: what the procedure requires is running the command and
-following its answer, not landing every issue in an epic. The review-cap follow-up's filing and the
-answer table it acts on are `prompts/review.md` → "Three-way disposition after the cap".
-
-**Every row that *places* the issue asserts a negative, so a cut epic listing withholds all of them.**
-"No epic already tracks this issue" — which `create_epic` asserts about the candidates too — is only
-as good as the listing it was read from, and an epic past the cut tracks its children invisibly.
-**`add_to_epic` rests on it as much as `create_epic` does**: adding the issue to the epic a
-*candidate* sits in, while an unseen epic already tracks the issue itself, is the same duplicate by
-another route. The verdict says so itself:
+Read this when a filing's `epic:bundle` answer places the issue (`add_to_epic`, `create_epic`, or a
+choice between epics), or when `SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with
+one already filed?" does not settle it. `Nothing to bundle.` needs neither.
+
+**Only two things count as a signal**: one issue naming the other in its acceptance criteria
+(`## 受け入れ条件` / `## Acceptance criteria`) or its `parent: #N` / `親: #N` line, or a `blocked-by`
+recorded between them. A reference elsewhere, or a similar title, never counts; the evidence line
+names the section.
+
+**A placing answer you do not follow** — check it against both issues first; record the reason as an
+`Auto-decided:` line on the issue.
+
+**The release issue is neither a candidate nor a subject**, like an epic — its `blocked-by` relations
+are mechanical. Any other `blocked-by` or counted reference still counts.
+
+**The search is not limited to the open backlog.** Every number the subject's own body names is read
+(capped at twenty), whatever its state:
+
+- A **closed** reference counts only when an open epic already tracks it; an **open** one counts either way.
+- A **pull request** number is not a candidate.
+- A failed read, or a reference past the cap, is reported as a gap — never folded into "no strong signal".
+- **A number that does not exist is not a gap** — dropped in silence. Told apart **by HTTP status,
+  never by `gh`'s wording**: 404 is nothing there; 403 and 429 are a rate limit.
+
+**`none` is a legitimate answer** — the issue stays in the backlog. The review-cap follow-up's filing:
+`prompts/review.md` → "Three-way disposition after the cap".
+
+**A cut epic listing withholds every placing row**, `add_to_epic` as much as `create_epic` — an unseen
+epic may already track the issue. The verdict says so, and the exit code stays `0`:
 
 ```text
 Could not confirm which epic already tracks these — do not place this issue in one.
@@ -46,50 +36,32 @@ Could not confirm which epic already tracks these — do not place this issue in
   Related: #<N>
 ```
 
-**The children and the order are deliberately absent** — they are the recipe for the placement that
-line says not to make. The exit code stays `0`, as it does for every other "do nothing" answer. **What
-survives the cut is a membership that *was* found**: the table's first row names the epic it read
-tracking the issue, and epics past the cut cannot unseat it.
-
-**Placing an issue is not merging epics.** Bundling is reversible — one `epic --add` moves an issue
-to a different epic — so choosing between two candidate epics is Tier A: take the one you recommend,
-and write the decision (what was taken, what was rejected, why, and the date) on **both** the issue
-and the epic's `## Decisions`. **Merging two epics is a different action, and nothing here proposes
-it.**
+It prints no children or order. What survives the cut is a membership that *was* found (the table's
+first row).
 
-**An epic and its own parent do not produce the spread verdict at all.** The parent already contains
-the child, so the pair is narrowed to the inner epic and the issue is added there. **The narrowing
-drops parents, never peers**: one unrelated epic beside a nested chain still asks, and so does a
-cyclic declaration, where there is no inner epic to pick. Stop only where the epics left are
-genuinely too close to separate, which is the toss-up Tier B is for and is rare.
+**Placing an issue is not merging epics.** Choosing between two candidate epics is Tier A: take the one
+you recommend and write the decision (taken, rejected, why, date) on **both** the issue and the epic's
+`## Decisions`. **Merging two epics is a different action, and nothing here proposes it.**
 
-**The decision record is what pays for the autonomy** — without it the run has taken a decision
-nobody can find afterwards.
+**An epic and its own parent do not produce the spread verdict** — the issue goes to the inner epic.
+**The narrowing drops parents, never peers**: an unrelated epic beside a nested chain, or a cyclic
+declaration, still asks. Stop (Tier B) only where the epics left are genuinely too close to separate.
 
 **Write both halves in the one call that places the issue: `pnpm josh epic --add <E> <N...>
---decision-file <path|->`.** It appends the record to the epic's `## Decisions` inside the body edit
-the insertion already makes, and posts the same text as a comment on each child added. **Never
-hand-edit the epic body to add the entry** — that is the operation `--add` exists to remove. Two
-constraints on the record's own text, both refused before anything is written:
-
-- **No line that is *nothing but* a `#A -> #B` chain.** Such a line is read as part of the epic's
-  declaration wherever it sits in the body, so the record would declare an order nobody decided. Quote
-  the order inside backticks, or put it in a fenced block; either is accepted.
-- **The record must say something, and the path must be readable.** An empty file is refused, and so is
-  `--decision-file` with no usable path — otherwise the insertion lands, no record is written anywhere,
-  and the command still exits 0.
-
-Answers about children the epic already tracks cannot use this flag; `SKILL.md` → "Recording a
-decision" says what to do instead.
-
-**Its sibling runs before the filing, not after it: `pnpm josh issue:scout "<title>"`.** That command
-answers the same epic question for an issue that does not exist yet — this decision, called rather
-than restated — and beside it the one thing this one deliberately refuses: whether the work has
-already been filed, from a title comparison. **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:
+--decision-file <path|->`.** It appends to the epic's `## Decisions` and comments the same text on
+each child added. **Never hand-edit the epic body to add the entry.** Refused before anything is
+written:
+
+- **A line that is *nothing but* a `#A -> #B` chain** — it would be read as a declaration. Quote the
+  order in backticks or a fenced block.
+- **An empty record, or `--decision-file` with no usable path.**
+
+For children the epic already tracks: `SKILL.md` → "Recording a decision".
+
+**Its sibling runs before the filing: `pnpm josh issue:scout "<title>"`** — the same epic question for
+an issue not yet filed, plus whether the work is already filed. **Both run**: `pnpm josh issue:file`
+runs the scout before creating the issue and `epic:bundle` after. Full behavior:
 `docs/josh-commands-backlog.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
-not. An order **nobody declared is not invented**.
+on an addition as much as on a new epic. An order **nobody declared is not invented**.

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

@@ -1,19 +1,15 @@
 # Execution waves — parallel, then one alone, then the rest
 
-**Read this when an epic's children need an order between groups** — a wave boundary, or one child
-that must run alone. It is a reference of the `epic-commands` skill (`SKILL.md`), which carries the
-commands themselves; the dependency declaration this file builds on is `SKILL.md` → "`josh epic:next
-<E…>` — what is runnable".
+Read this when an epic's children need an order between groups — a wave boundary, or one child that
+must run alone. It builds on `SKILL.md` → "`josh epic:next <E…>` — what is runnable".
 
-**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.
+**A wave is not a mechanism, and there is nothing to add for one** — the dependency declaration
+already expresses it.
 
 ## The shape
 
-**A wave boundary is drawn by chaining every child of the later wave to every child of the earlier
-one.** Wave 1 `{#A, #B, #C}` → wave 2 `{#D}` → wave 3 `{#X, #Y, #Z}` is written in the epic's
-`## Dependencies` as three chain lines:
+**Chain every child of the later wave to every child of the earlier one.** Wave 1 `{#A, #B, #C}` →
+wave 2 `{#D}` → wave 3 `{#X, #Y, #Z}` in the epic's `## Dependencies`:
 
 ```
 #A -> #D -> #X
@@ -21,85 +17,51 @@ one.** Wave 1 `{#A, #B, #C}` → wave 2 `{#D}` → wave 3 `{#X, #Y, #Z}` is writ
 #C -> #D -> #Z
 ```
 
-- **#A #B #C are blocked by nobody, so they start together** — as many at once as there are free lanes.
-- **#D is `time` until all three have closed**, and becomes runnable the moment the last one does.
+- **#A #B #C are blocked by nobody, so they start together** — as many as there are free lanes.
+- **#D is `time` until all three have closed**, then runnable.
 - **#X #Y #Z are blocked by #D, so #D necessarily runs alone.**
-- **#D closing releases wave 3**, which again runs as wide as the lanes allow.
-
-**The block above is an illustration, not something to paste.** `parse_dependency_chains` strips
-fenced blocks before it matches, so a `## Dependencies` section whose chains sit inside a fence reads
-as **no declaration at all** rather than as an error — and `#A` / `#B` are not issue numbers anyway.
-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.** 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
-half by hand is the `declaration_mismatch` below, arrived at from the other direction.
-
-**Write the boundary with `pnpm josh epic --add`, not by hand.** A declared link with no recorded
-`blocked-by` relation is the `declaration_mismatch` that `find_anomalies` reports, and it stops
-`epic:next` and the run that consumes it outright; the rule `epic-bundle.md` ends on — record the order in `blocked-by` **and**
-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. **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
-chains through it collapse into one line each. Where both sides of a boundary hold several children
-the count grows — and that is the moment to ask whether the boundary is real, rather than to go
-looking for a shorter notation.
+- **#D closing releases wave 3.**
+
+**The block above is an illustration, not something to paste**: chains inside a fence read as no
+declaration at all. Write the lines unfenced, with real numbers.
+
+**Write the boundary with `pnpm josh epic --add`, not by hand** — a declared link with no recorded
+`blocked-by` is a `declaration_mismatch` that stops `epic:next` and the run. **`--before <hub>` and
+`--after <hub>` are both refused while the hub sits in more than one chain with nothing after it**, so
+**the first child of the next wave goes into the declaration by hand**, with its `blocked-by` recorded
+to match; after that, `--after <hub>` branches the rest.
+
+**Delete a declared order with `pnpm josh epic --remove <E> <M> <N> [<N2> …]`, never a hand edit.**
+Each consecutive pair is one order. **The ends are never reconnected** (`#A -> #B -> #C` minus
+`#B -> #C` leaves `#A -> #B`). Deleting the last link writes the unordered sentence.
+`--decision-file` records why on the epic and on both ends.
+
+**Any number of chain lines is allowed**; only a **cycle** and a **disagreement between the
+declaration and the recorded `blocked-by`** are rejected. The line count is the widest wave; when both
+sides of a boundary hold several children, ask whether the boundary is real.
 
 ## Running one child alone is a wave of one
 
-**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.
+**There is no `solo` mechanism.** Chain into it every child that must not overlap it, and out of it
+every child that must not precede it.
 
 ## When a wave may be declared
 
-**Declare a boundary only where the later wave needs the earlier wave's artifact.** That is the whole
-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 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>`**, 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.
+**Only where the later wave needs the earlier wave's artifact.**
 
-## What a jam does, and how it is cleared
+- **A preference of order is not a dependency** — use task-list order: `--order-before <M>` /
+  `--order-after <M>` move the row and declare nothing. They do not help at a wave boundary.
+- **Two children editing the same file are not a dependency** — run them in parallel; conflicts
+  resolve in the lane (`pnpm josh main:merge`; `backlogrun-recovery.md` → "Conflicts are not
+  predicted"; `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 reason to wait means no declaration** — say so in prose and leave the graph empty.
 
-**Declare a boundary and one stuck child in the earlier wave stops every wave behind it.**
-`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".
+## What a jam does, and how it is cleared
 
-**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.
+**One stuck child in an earlier wave stops every wave behind it**: a `needs-decision` child makes
+every child behind it "waiting on a person" (`from_blockers` in `scripts/epic/epic-classify.ts`).
+`backlogrun` parks it and runs the rest of the wave; the session stops once nothing is runnable.
+**Clear it by removing that child's `needs-decision`** once the decision is recorded.
 
-**A wave is declared for a real wait and removed when the wait ends; it is not the standing shape of
-an epic.**
+**A wave is declared for a real wait and removed when the wait ends.**

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

@@ -6,84 +6,58 @@ 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. This skill is
-the look. Rationale: `docs/maintainers/verify-ui-rationale.md` → "Why the skill reads as it does".
+A rendered-UI change is not done until someone has looked at it (`CLAUDE.md` → completion gate);
+passing tests are not that look.
 
 ## 1. Decide which routes to capture
 
-In order:
-
 1. The routes given as arguments (`/verify-ui / /blog`).
-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.
-3. If it derives no route — it prints that plainly rather than guessing — ask which screen to look
-   at. Do not guess.
+2. Otherwise `pnpm josh ui:routes` (branch diff, or `--staged`) lists the routes the change touches;
+   **pick the ones a reader would notice**.
+3. If it derives none, ask which screen to look at. Do not guess.
 
-State the list before capturing, so a wrong route is caught before the build.
+State the list before capturing.
 
 ## 2. Find this project's screenshot command
 
-The command belongs to the application layer, not to this package, and it differs per project type.
-Look for it in this order and stop at the first hit:
+Stop at the first hit:
 
 1. `pnpm josh-app shot` — the SvelteKit application toolkit (`@joshuafolkken/app-kit`).
 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 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
+Option 1 exists since app-kit 0.86.0; game-kit carries no `shot` yet —
 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
-list names it. An unknown subcommand exits non-zero with the same usage line, so a toolkit that is
-present but has no `shot` command and a toolkit that is absent are told apart by reading the list,
-not by whether the invocation succeeded.
+**Decide by the printed command list, not by whether the toolkit is installed.** Run the toolkit with
+no subcommand (`pnpm josh-app`) and read its usage line; an absent toolkit and one without `shot` both
+exit non-zero.
 
 ### When there is no screenshot command
 
-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.
-
-**Otherwise stop and say so.** Report, in the session language:
+**Capture through the project's own E2E suite**: add `await page.screenshot({ path: … })` to the
+Playwright spec covering the screen (or a new spec) and run it.
 
-- that this project has neither a screenshot command nor an E2E suite to capture through, naming
-  what you looked for;
-- that the UI verification gate is therefore **not** closed by this run;
-- that the change needs a human to look at the screen, and ask the user to do it.
+**Otherwise stop and say so**, in the session language: what you looked for, that the UI verification
+gate is **not** closed by this run, and ask the user to look at the screen.
 
 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. 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. A project that should have the command and does not is an issue against
+the application toolkit.
 
 ## 3. Capture
 
-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.
+Run the command once for every route (`pnpm josh-app shot / /blog`) and note the output directory (on
+the E2E fallback, the `path` option). A non-zero exit is 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 — 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
-disappeared or moved; the layout is not broken at the captured viewport.
+Read every produced image with the Read tool — capturing without opening does not close the gate.
+Check the change's intent: element present, placed, sized, spaced, colored and worded as intended;
+nothing else disappeared or moved; the layout holds at the captured viewport.
 
 ## 5. Report
 
-- **Matches the intent**: say what you looked at, route by route, and what you checked on each. Name
-  the image paths so the user can open the same files.
-- **Does not match**: for each mismatch give the route, what the change was supposed to produce,
-  what the image actually shows, and the image path. Then fix and capture again. Do not report the
-  work as done with a known mismatch outstanding.
+- **Matches the intent**: route by route, what you checked, with the image paths.
+- **Does not match**: route, intended result, what the image shows, image path. Fix and capture again.
 - **Could not capture**: the report from step 2 or step 3, unchanged. This is not a pass.

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

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

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

@@ -17,73 +17,58 @@
 - 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
 
-**Background it from the first, then end the turn.** A command issued with `run_in_background` set
-re-invokes the run when it exits, and that completion notification is what ends the wait — on the
-task's *exit*, not on a regex match and not on the harness block limit. So the moment you background
-a long command there is nothing to wait *on*: end the turn, and the wake-up brings you back with the
-command finished.
+**Background it from the first, then end the turn.** A `run_in_background` command re-invokes the run
+when it *exits* — that completion notification is what ends the wait, not a regex match or the block
+limit.
 
-**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. `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".
+**Never hand-write a `while`/`until` … `sleep` loop over the output file** — a regex that never matches
+waits to the block limit, one that matches a mid-run line exits early. `pnpm josh rule:guard` refuses it
+(`prompts/collaboration-workflow/rule-delivery.md`).
 
-**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`.
+**To glance at interim output, `Read` the output file once**, never in a sleep loop. CI is waited on by
+`pnpm josh followup`; a progress heartbeat is `run:progress --wait`'s job (`early-heartbeat` refuses a
+hand-armed timer).
 
 ## 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".
+**Never give a foreground call a timeout above the harness cap** — a larger number detaches it without
+the completion notification.
 
-**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
+**The tail is emptied before `followup` is issued.** Each step is asked one question: **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`. **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* 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:
+- **It does — it stays after `followup`**: `pnpm josh ms`, `pnpm josh issue:state <N>`,
+  `pnpm josh epic:next`, `pnpm josh backlog:next --exclude <N>`, `pnpm josh lane:close` /
+  `pnpm josh lane:list`. **De-duplicating a step is not removing it** — none is dropped or answered
+  from memory.
+- **It does not — it is composed in the turn that issues `followup`**: the epic progress counter
+  *values* and the completion report body. **Only the write follows the merge.**
+- **`pnpm josh cost --cut` stays after the merge**, though it reads nothing from it (`backlogrun-progress.md`
+  → "The check is asked at every merge").
+
+**Beside a backgrounded command runs only work that writes nothing to the working tree**:
 
 | While this runs | Do this beside it |
 | --------------- | ----------------- |
 | `pnpm josh gate` | a subagent running `/code-review` with the brief `pnpm josh review:brief` prints |
 | `pnpm josh git -y` | Write the completion notification body to a file for `--notify-message-file`, and settle the three-way disposition of any remaining non-High finding |
 | CI, after the push | The second review round where one is due, the branch-2 filing through `pnpm josh issue:file`, which runs `epic:bundle` itself (`prompts/review.md` → "Review round cap") |
-| `pnpm josh followup` | Nothing — it is foreground and holds the session. **The post-merge tail is what overlaps here, and it is taken before the call rather than beside it**: compose the epic progress counters first, and leave after the merge only the steps that read its result, plus `pnpm josh cost --cut` |
+| `pnpm josh followup` | Nothing — it is foreground. **The post-merge tail is taken before the call**: compose the epic progress counters first, and leave after the merge only the steps that read its result, plus `pnpm josh cost --cut` |
 
-**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`. `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".
+**The turn never ends at the push.** The `pnpm josh git -y` completion resumes the run, and that turn
+goes straight through any branch-2 filing and `pnpm josh epic:bundle` to `pnpm josh followup`. `pnpm
+josh rule:guard` refuses the foreground push (`prompts/collaboration-workflow/rule-delivery.md`); the
+push reissued detached is not refused again.
 
-**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.
+**One turn does end before the push: a dispatched lane child's pre-gate cut** — `pre-gate-cut.md` →
+"Taking the cut".
 
 **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); `pnpm josh rule:guard` refuses a
+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` (`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.