@joshuafolkken/kit 1.1128.0 → 1.1166.0

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

@@ -6,64 +6,40 @@ description: The procedures for the Issue-driven shorthand commands `kickoff`, `
 # Issue-driven workflow commands
 
 `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.
-
-Each topic file under `prompts/collaboration-workflow/` sources its own rule; this skill sources the
-procedures. Neither restates the other.
+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.
 
 ## 0. The rule that fires before any of them — explicit invocation
 
 **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.
-
-- Conversational requests like "implement X", "fix Y", "open a PR for Z" are **NOT** implicit
-  invocations. Even if the task clearly fits one of these workflows, do not infer authorization from
-  the request shape.
-- Do **NOT** ask confirmation questions like "May I proceed with `halfrun new`?" or "Shall I run
-  `fullrun`?". A confirmation prompt is not an acceptable substitute for explicit invocation.
-- Instead, **prompt the user to type the command themselves**, with the exact phrasing: "Please run
-  \`<command>\` to start this task."
-- The rule applies even when the user authorized a related workflow in an earlier turn. Each
-  invocation must be re-typed by the user in the current turn.
-
-**A session cut inside a declared budget is not a new invocation — for `backlogrun` alone**; its
-single source is `backlogrun-steps.md` → "The session cut is inside the invocation".
+`#N` and `new` variants) unless the user has typed the keyword in the current turn's prompt.** Its
+single source is `CLAUDE.md` → "Explicit invocation required (MANDATORY)", resident because it holds
+when this skill is not loaded. **A session cut inside a declared budget is not a new invocation — for `backlogrun`
+alone**: `backlogrun-steps.md` → "The session cut is inside the invocation".
 
 ## 1. Which file to read
 
-Read this file, then the one for the command that was typed. The command file is a **manifest** — the
-ordered steps as 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
-(`run:next` is its pre-implementation degenerate form) — and each step's detail is read on demand from
-the file its pointer names (for `fullrun`, the step lists are `fullrun-steps.md`).
+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.
 
 | Typed keyword                            | Read                                        |
 | ---------------------------------------- | ------------------------------------------- |
 | `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 |
+| `fullrun` / `fullrun #N` / `fullrun new` | `fullrun.md` + `entry-sequence.md`          |
+| `halfrun` / `halfrun #N` / `halfrun new` | `halfrun.md` + `entry-sequence.md`          |
+| `prrun` / `prrun #N` / `prrun new`       | `prrun.md` — the difference over `fullrun.md`, read with it and `entry-sequence.md` |
 | `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
-entry as a section; the split-handling detail (what each entry does with the answer, promote or create
-an epic) is read on demand only when a split is found (joshuafolkken/kit#2189). `backlogrun`'s row
-lists `backlogrun.md` alone: its parent orchestrates and never implements, so `fullrun.md` and
-`split-assessment.md` are read by a dispatched child in its own delegated unit (`backlogrun-child.md`).
-Every procedure for *running* a `backlogrun` item — lanes (`backlogrun-lanes.md`), park-and-continue,
-the guards — stays `backlogrun.md`'s. The on-demand sections `into-target.md` (an `into` suffix) and `target-repository.md`
-(an `owner/repo#` prefix) are read only when their trigger is typed, and §3's residency procedure lives
-in `prompts/collaboration-workflow/residency.md`, reached only when a rule is placed, moved or retired.
+`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.
 
 ### The fetch is one `Read` call per file
 
-**Fetch each file above with one `Read` call of its own — never `cat`, and never two of them in one
-command.** The distributed `.claude/settings.json` caps a Bash result at `BASH_MAX_OUTPUT_LENGTH`
-characters, and every document over it is handed back by `cat` as a middle-truncated preview, then
-read a second time. `pnpm josh read:set [<keyword>]` prints the cap and marks every file that exceeds
-it; `pnpm josh doc:read <file>` is the Bash-cap-safe whole-file read.
+**Fetch each file above with one `Read` call of its own — never `cat`, never two in one command.** A
+Bash result is capped at `BASH_MAX_OUTPUT_LENGTH` characters and truncates a longer document;
+`pnpm josh doc:read <file>` is the cap-safe whole-file read.
 
 ### Four documents are read at the point of use, not at the entry
 
@@ -74,19 +50,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 section is how the gate starts, overlapped with the review, so it is read before the gate rather than before the `/code-review` step |
+| `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`) |
 
-A `skip` answer from `latest:scope` reads nothing; `latest-gate.md` remains a whole-file read, while
-the other three fetch only the operational section named above. The trigger sentence for each is
-resident in §2 and in the command's manifest, so a run that never opens these documents still calls
-the right command at the right moment. `followup.md`'s post-execution reference is in
-`followup-reference.md`, reached through a section pointer from `followup.md`.
-
-**A lane child that parks reads `backlogrun-park.md` → "park and continue" at that point of use**, so
-the pointer names that heading rather than the whole file: the entry read is charged for the park
-procedure alone, and the rest of `backlogrun-park.md` is read only when it is reached
-(joshuafolkken/kit#2189).
+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).
 
 ### A section reference is read as a section
 
@@ -97,162 +67,46 @@ pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim
 pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs
 ```
 
-The section is fetched in the same turn, printed verbatim with its subsections; **a heading that does
-not resolve is refused, with the file's own headings listed**, as is an ambiguous prefix. The set is
-derived from the table above and the documents themselves, not transcribed;
-`scripts/document/entry-read-set.test.ts` pins the derivation and
-`scripts/rules/entry-read-set-document-rule.test.ts` pins this rule.
+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.
 
 ## 2. What every one of them shares
 
 Each shared rule is a **trigger, a one-line action, and the single source** the procedure is read
-from. The single source is where the rule is stated in full — this list is the manifest, not the
-procedure.
+from — read at that trigger, never restated here.
 
 | Trigger | Action | Single source |
 | --- | --- | --- |
+| 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`; `busy` / `unknown` stop | `working-tree-hold.md` |
+| `run:entry` prints its stage line | The command sets how far a run goes, the Issue where it starts; **`start: reached` redoes nothing** — stop (at `merged`, the next line answers) | `docs/how-to/run-issues.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) |
+| An entry typed with an `owner/repo#` prefix or a short `repo#` name | Resolve the target and its checkout; an explicit foreign owner stops the run | `target-repository.md` |
+| A `new` entry typed with an `into <target>` suffix | Insert the artifact into the named epic with `pnpm josh epic --add <E> <N>` | `into-target.md` |
+| 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" |
+| Before implementing (every `#N` entry) | `pnpm josh issue:read <N>` — the body and the comments; the later of a body and a comment wins | `issue-comments.md` |
+| `pnpm josh issue:state <N>` answers `human_review: yes` | Implement and gate, then stop before the commit; the label is applied only by a person | `needs-human-review.md` |
 | Before implementing (every implementing entry) | `pnpm josh latest:scope`; on `required` read the doc and run `josh latest`, then load the `dependency-update` skill; `kickoff` never reaches it | `latest-gate.md` (read whole, only on `required`) |
-| Implementation is done | The verification gate: refactor → `pnpm josh main:merge` → `pnpm josh gate` started beside a subagent `/code-review` and joined before the commit → the two-round cap → PR opened between the rounds → merge; `kickoff` never reaches it | `chain-rule.md` → "Run the review-to-merge chain" |
-| 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` |
+| Before delegating any run step | `pnpm josh delegate <step>` decides eligibility, never you | `delegation.md` |
+| The pre-implementation reading reaches 3 unedited files | Delegate the unread investigation; a file this run will edit is read in the main line | `delegation.md` → "The pre-implementation reading" |
+| Immediately before implementation | Present the two-layer work summary (once per Issue); `kickoff` posts a plan instead | `prompts/collaboration-workflow/report-format.md` |
+| While implementing | Re-run one check by name, not the whole gate — `pnpm josh lint:related`, `pnpm josh cspell:dot`, `pnpm josh test:related`; `pnpm josh review:brief` refuses a brief on a tree the last two were not green on | `chain-rule.md` |
+| 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" |
-| 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` |
+| 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" |
 | 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 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` |
-| `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` | §2j → `retrospective.md` |
-| The pre-implementation reading reaches 3 unedited files | Delegate it; a file this run will edit is read in the main line | §2b → "The pre-implementation reading" |
-| Before implementing (every `#N` entry) | Read the Issue's comments — the later of a body and a comment wins | §2g → `issue-comments.md` |
-| Immediately before implementation | Present the two-layer work summary (once per Issue); `kickoff` posts a plan instead | `prompts/collaboration-workflow/report-format.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" |
 
-## 2z. `needs-human-review` — the child that stops before its commit
-
-**Trigger:** `pnpm josh issue:state <N>` answers `human_review: yes` — asked once, before implementing.
-**Then:** implement and run the verification gate normally, but commit nothing — leave the tree
-uncommitted and unstashed, send a `confirmation` Telegram with the resume command, and stop the whole
-run (inside a `backlogrun` this is the one child stop that is *not* park-and-continue). **The label is
-applied only by a person; never apply or remove it.** The full procedure — why it stops the *end* not
-the *start*, why the repository stays held, and the resume — is `needs-human-review.md`, its single
-source, read at that trigger.
-
-## 2a. The `into <target>` suffix — where the new Issue lands
-
-**The suffix and its procedure are `into-target.md`, read at its point of use — the moment a `new`
-entry (`kickoff new` / `fullrun new` / `halfrun new`) is typed with an `into <target>` suffix.** It
-names the epic the run's artifact joins, inserts it with `pnpm josh epic --add <E> <N>` as soon as the
-artifact exists, and refuses a target that is not an epic. A run given a `#N` or a bare `new` never
-reaches it. `into-target.md` is the single source.
-
-## 2b. Delegating a step to a cheaper tier
-
-**Before delegating any run step, ask `pnpm josh delegate <step>`; never decide eligibility yourself.**
-Read `delegation.md` at the first delegation decision for its units and verification rules. An item
-absent from the enumeration stays in the main line. A dispatched `epic-child` that returns open with
-`human_review: yes` is an authorized stop, not a failed child (§2z).
-
-### The pre-implementation reading — what goes to a unit, and from which file
-
-**When the next pre-implementation read would reach 3 files this run will not edit, delegate the
-unread investigation before that read.** Keep edit-target reads in the main line. The full procedure
-and the `file:line` verification are in `delegation.md` → "The pre-implementation reading"; the
-threshold is counted by `pnpm josh investigation:guard`.
-
-## 2c. The `owner/repo#` prefix — which repository the run acts on
-
-**The prefix and its procedure are `target-repository.md`, read at its point of use — the moment an
-entry is typed with an `owner/repo#` prefix or a short `repo#` name.** It names the repository the run
-acts on; a short name expands by the session owner and is first-party by construction, an explicit
-foreign owner is a third-party target that stops the run, and an implementing entry resolves that
-repository's checkout from `pnpm josh doctor` rather than cloning. No prefix leaves the target as the
-session's own repository, so a run without one never reaches it. `target-repository.md` is the single
-source.
-
-## 2d. A prerequisite discovered mid-run — a dependency, not a park
-
-**Trigger:** a run finds that another Issue in *this* repository has to land first. **Then:** it is
-still one deliverable with another in front of it — file the prerequisite with the `route:tier-a` label
-(scouted first, §2e), stash the work in progress with `git stash push -u` and record it on the Issue,
-record the dependency in the epic, and — under `fullrun` / `halfrun` — **stop**, or — under
-`backlogrun` — **continue** (`backlogrun-park.md` → "A prerequisite discovered mid-run"). It is the
-third of four mid-run discoveries, distinct from an upstream defect, a split (`split-assessment.md`)
-and an observation (§2i). The full table, the filing command, the `-u`/`stash:pop` steps and the
-10-per-run cap are `prerequisite.md`, its single source, read at that trigger. **When the prerequisite
-is the run's second filing, `pnpm josh issue:fold` runs first** (§2e), and `pnpm josh rule:guard`
-refuses the second `pnpm josh issue:file` call until it has.
-
-## 2e. Before filing a new Issue — `pnpm josh issue:scout`
-
-**Every new Issue is filed with `pnpm josh issue:file`, which runs the `issue:scout` scan first — read
-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-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:** 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
-the `--force` spelling are `working-tree-hold.md`, its single source, read at that trigger.
-
-## 2g. An Issue's comments are part of the Issue
-
-**Trigger:** before implementing at every `#N` entry point (`fullrun`, `halfrun`, `kickoff`, and each
-`backlogrun` child in its own unit). **Then:** `pnpm josh issue:read <N> [<N> ...]` reads the body and
-the comments in one call — a decision recorded after the body was written lives only in a comment, and
-of a body and a comment that disagree the later text wins. Two comment kinds are not the run's to act
-on blindly — a scope reassigned to another Issue, and an Issue already merged (the `already-done`
-exit) — and both, the long-thread delegation and why `pnpm josh rule:guard` refuses the body-only read,
-are `issue-comments.md`, its single source, read at that trigger.
-
-## 2h. A command that can take minutes is issued in the background
-
-**Trigger:** before backgrounding the first long-running command (`pnpm josh gate`). **Then:** issue
-`pnpm josh git -y`, `pnpm josh gate` and the CI wait detached while `pnpm josh followup` stays in the
-foreground — the turn never ends at the push, bar a dispatched lane child's pre-gate cut
-(`pre-gate-cut.md`). A parent waiting on its children is the same rule at the batch's scale: a
-background command's completion re-invokes the session, so the `backlogrun` loop starts no sleep of
-its own. The single source is `background-commands.md` → "Background the gate and push", with the
-parent-wake half at `backlogrun-progress.md` → "The parent keeps no clock of its own".
-
-## 2i. An observation worth filing is filed without asking
-
-**When a first-party observation is worth filing, file it without asking and continue the run.**
-Read `observation-filing.md` in full before filing: it decides the depth test, filing ceilings, labels,
-second-filing fold, ledger fallback and delegated-child handoff. Use `pnpm josh repo:party` to decide
-first-party status, then file with `pnpm josh issue:file` (§2e). A third-party target remains
-Tier C (`CLAUDE.md`).
-
-## 2j. The end-of-run retrospective — read when `run:step` prints it
-
-**When `pnpm josh run:step` prints the retrospective step, read `retrospective.md` in full and run the
-digest it names once.** File up to two worthwhile improvements through `issue:file` (scout and
-`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
-only when a rule is being placed, moved or retired, never at any entry and never during a run.** Its
-questions are asked there in order — question 0 (`pnpm josh oracle:list`), the ordering question
-(`pnpm josh run:step`), the first and the second — beside how much of a resident rule stays and the
-retirement route; none is restated here.
+only when a rule is placed, moved or retired, never during a run.** Its questions — question 0
+(`pnpm josh oracle:list`), the ordering question (`pnpm josh run:step`), the first and the second —
+are asked there in order; none is restated here.

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

@@ -88,4 +88,4 @@ backgrounded `josh gate` / `git` / `followup` / `ship` there, and the `Stop` hoo
 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.
+`progress-watcher.md` → "Progress while the run is quiet" route here for it rather than restating it.

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

@@ -24,7 +24,7 @@ bare Issue promotes itself under `backlogrun` but not under `fullrun`"):
 2. **Stash the work in progress and remove `in-progress` from `#<N>`**, exactly as steps 2 and 4 of
    "A prerequisite discovered mid-run" do — `git stash push -u -m "..."` with the `-u`, the
    `gh api repos/{owner}/{repo}/issues/<N>/comments` post that records the stash, and
-   `gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true`.
+   `pnpm josh run:release <N>`, which removes the label with the hold.
 3. **Ask `pnpm josh epic:bundle <N>` whether an epic already tracks `#<N>` before creating one.**
 
    | Answer | What to do |
@@ -115,7 +115,7 @@ summary is bounded the way it is".
 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 — `SKILL.md` → §2i, the single source. **What the parent does with 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, `docs/maintainers/observations/<N>.md`, in its own
@@ -148,92 +148,10 @@ asked at every merge; delegation is not an alternative to it.
 
 ## A delegated unit that stopped without reporting
 
-**A unit can be stopped from outside, and a stop leaves no notification behind** — and a stopped unit
-trips none of this file's guards, which all assume it is running. **So the parent checks rather than
-waiting — which means it must not be waiting.** **Hand the child to the unit without blocking on its
-return, and poll** at the loop's polling interval; ask once the unit's output has been unchanged for
-the silent-unit window (`| Silent delegated unit | 30 min |` in `backlogrun-progress.md`).
-
-**Note where the unit writes at hand-off; the modification time is read from the file, not carried.**
-**Where the child runs in a lane, that note goes into the lane rather than the conversation** —
-`pnpm josh lane:output <N> <path>`, in the same turn as the dispatch, so it comes back from
-`pnpm josh lane:output <N>` in any session.
-
-**Ask the command rather than combining the traces yourself.** Traces are read **in the checkout the
-unit was given** — this session's own unless the unit was handed a separate work tree, and the stash in
-the recovery below is taken there too.
-
-```bash
-pnpm josh run:liveness <N> --output <path> --process none
-pnpm josh run:liveness <N> --output <path> --process alive
-pnpm josh run:liveness <N> --output <path> --process none --window 45 --repo <owner/repo>
-```
-
-| Answer | What it found | What the parent does |
-| --- | --- | --- |
-| `alive` | The output moved, or a process of the child is running | Keep polling; touch nothing |
-| `stopped` | The output has been frozen past the window and no process of the child is alive | The recovery below |
-| `settled` | The child closed, or the unit parked it with `needs-decision` | Re-read it with `pnpm josh run:status <N>` — one read-only call whose state section says which branch and whose carry counters beside it feed the failure-streak decision — and take the branch its state section says |
-| `undetermined` | A trace could not be read | Read the trace that failed and ask again — and see the two-in-a-row rule below |
-
-**Two `undetermined` answers in a row is a fault in the check, not a slow unit.** The second
-consecutive `undetermined` on the same child ends the polling: send a `confirmation` Telegram naming
-the trace that failed, and stop. **It is never escalated to a `stopped`** — nothing was read.
-
-**Silence and no process together — never either one alone.** **A trace that could not be read answers
-`undetermined`, never `stopped`**, and a process trace nobody gave is an unasked question rather than
-"no process". **Output that moved answers `alive` on its own; a live process is weighed only once every
-trace has answered.** Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why liveness needs
-silence and no process together".
-
-**The path passed to `--output` is absolute** — the command refuses a relative one. **The process
-trace is the one the command does not read for itself**: run it in the unit's checkout and read the
-command lines rather than the names — `pgrep -laf 'josh gate'` etc. — looking for one naming **that
-checkout's path**, since several kit projects may run at once. **Read the file the path points at, not
-the link**: a transcript path is a symlink whose own modification time never changes, so a `stat` typed
-by hand needs `-L` (`run:liveness` follows the link itself).
-
-**A clean checkout is not evidence that the unit is alive** — a stop can come while the unit is still
-reading the skill and the issue. The checkout is read only for whether there is work to stash before
-the child is parked; **"nothing was ever opened for the child" is `pnpm josh run:hold`'s preflight check
-at the start of the next child, not this one's.**
-
-**What follows is what a failed child already gets.** Re-read the child first with
-`pnpm josh run:status <N>` — its state section carries the same `state:` / `labels:` /
-`human_review:` lines `issue:state` prints, and folds in the carry counters this recovery reads
-anyway; then, while it is still `state: OPEN` and not carrying `needs-decision`.
-**A re-read carrying `needs-decision`** means the unit parked the child and then stopped, so fall
-through to the loop's park branch: leave the label on, count nothing against the consecutive-failure
-guard, and go back to step 1.
-
-1. **Stash the half-finished work** — `git stash push -u -m "backlogrun: stopped unit for #<N>"` — and
-   record it on the Issue. `-u` is not optional, and the comment is what gets the stash popped — by
-   message, `pnpm josh stash:pop "backlogrun: stopped unit for #<N>"`, never a positional
-   `git stash pop` that a shared stack lets another lane divert.
-2. **Classify how the child ended and act, in one call** — `pnpm josh run:merge <N> --output <path>`
-   (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic). **It is the same composite a
-   returned child takes** (`backlogrun-progress.md` → "Running a named epic's children"), reached here
-   from the poll rather than from a return — **one** decision, never a second copy of it. It **reads the
-   child's exit record without waiting for the unit to return**, telling an `outage` — a child that
-   could not reach the API — apart from an `abandoned` one that stopped mid-implementation, and it drops
-   the stale `in-progress` itself, so there is no separate label-removal step:
-   - **outage** — the child never reached the API, so it is counted into its own outage streak and
-     **re-dispatched in the same run** by being offered again, **not** parked with `needs-decision` and
-     **not** counted against the consecutive-failure guard. **The re-dispatch resumes the child's
-     session**: `lane:dispatch` reads the `session_id` off the exit record and relaunches with
-     `--resume`; with no session id it falls back to a fresh `fullrun`, and the report says which path
-     it took. **Outages inside a two-minute window count once** toward the streak. The re-dispatch is
-     bounded by `CONSECUTIVE_OUTAGE_LIMIT` in `scripts/run/run-merge.ts`: *distinct* outages trip the
-     separate outage guard, at which point the command prints `environment` and the run stops. It never
-     re-dispatches into a dead API forever.
-   - **abandoned** — counted against the consecutive-failure guard and parked with `needs-decision`,
-     exactly as a failed child. Never retried silently.
-3. **Read the token it printed and take that branch** — a next child number to run (the re-dispatched
-   outage child among them), `environment` / `stop` to end the run, or `busy` / `retry` to re-read —
-   the same tokens the merge event reads (`backlogrun-progress.md` → "Running a named epic's children").
-   Then go back to step 1 of the loop.
-
-Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why the poll routes through `run:merge`".
+**Hand the child to the unit without blocking on its return, and poll** — a stopped unit leaves no
+notification behind. Once its output has been unchanged for the silent-unit window, read
+`backlogrun-recovery.md` → "A delegated unit that stopped without reporting" and ask
+`pnpm josh run:liveness`.
 
 ## Audit before the first child
 
@@ -281,40 +199,11 @@ This is the same rule `latest-gate.md` is the single source of.
 Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why `josh latest` is hoisted to the
 session".
 
-## Preflight — reclaim what an interrupted run left, before the next child starts
-
-**The child's claim is what asks it.** `pnpm josh run:hold <N>` — the first call of the child's
-`fullrun` procedure — runs the preflight check before it takes the tree: it hands back a hold **only on
-a clean tree**, and returns `reclaim` / `resume` / `park` without claiming otherwise. There is no
-separate command to ask first. Rationale: `docs/maintainers/backlogrun-child-rationale.md` → "Why the
-preflight is part of the claim".
+## Preflight — the child's claim asks it
 
-```bash
-answer=$(pnpm josh run:hold 926)   # one token on stdout, prose on stderr
-```
+`pnpm josh run:hold <N>`, the first call of the child's `fullrun`, checks for an interrupted run's
+leftovers before it claims the tree, and prints the step for each answer (`reclaim` / `resume` /
+`park`) on stderr — follow it, and report a reclaim or resume with its stash reference. The answers are
+`docs/josh-commands-automation.md` → "`josh run:hold`"; rationale:
+`docs/maintainers/backlogrun-child-rationale.md` → "Why the preflight is part of the claim".
 
-| Answer | What it found | What to do |
-| --- | --- | --- |
-| `hold` | Nothing left behind; the tree is claimed | Start the child. This is the ordinary answer. |
-| `reclaim` | Uncommitted changes, or HEAD off the default branch | Run what stderr printed: `git stash push -u -m "run:hold reclaimed before #<N>"`, then `git switch <default> && git pull`. **`-u` is not optional** (a new `*.test.ts` is untracked). **Then record the stash on `#<N>` as a comment, and ask `run:hold` again** — the check is re-askable. |
-| `resume` | An open PR, or a `#<N>` branch with commits or a dirty lane | **Reuse it and run the whole verification gate from the start** — never only the part the interrupted run had not reached. The tools are idempotent; what was missing was that **nobody had verified what the dead run already committed**. |
-| `park` | The pull request for `#<N>` is **merged** or **closed** | **Park the child** — `needs-decision` plus a comment naming what was found — and continue. Carrying on over a merged PR duplicates work; over a closed one revives rejected work. Do not delete the branch, reopen the PR, or commit on top of it. |
-| `busy` | Another **live** run holds this tree | Stop before filing anything — `run:hold`'s own answer, unchanged. |
-| `unknown` | The tree could not be read | Stop the session and report. It is not "the tree is clean". |
-
-**The rule answers, so the run does not judge.**
-
-**The `git stash` above is one of the flows that authorizes automatic stashing**
-(`prompts/collaboration-workflow/operating-rules.md` → the `git stash` bullet). **It is the one entry
-there not followed by a pop**: what is stashed belongs to a run that is gone, so **the Issue comment is
-the only thing that can bring it back** — recovered by message, `pnpm josh stash:pop "run:hold
-reclaimed before #<N>"`, never a positional `git stash pop` a shared stash stack lets another lane
-divert.
-
-**Report what was reclaimed** — a child that started from a `reclaim` or a `resume` says so, with the
-stash reference where there was one.
-
-**It is not asked in a lane** — `run:hold` claimed inside a lane skips the check, and `lane:open`'s own
-answer covers an interrupted lane instead. **Asked in the primary checkout while a lane for that child
-is open, `run:hold` reads `resume` only if `<N>-lane` has a commit or a dirty tree** — a clean one
-at the default branch reads `hold`. The loop never gets there, because `epic:next` does not offer a child already carrying `in-progress`.

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

@@ -84,8 +84,12 @@ it a defect (not an improvement, refactor, removal or feature)? Is it in kit's o
 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.
+#2779), and an issue a run files (an interrupt, a split child, a prerequisite) carries one of the
+two from its filing, because an issue with neither answers `triage` and nothing starts. **It stops
+the other lanes for one reason only: a batch run on broken verification leaves nobody's result
+trustworthy** — that the issue's own verification sits under the defect is the issue's own concern,
+checked by the verification after the fix. This paragraph is the rule's single source; rationale:
+`docs/maintainers/wip-cap-rationale.md` → 「単独実行の理由と由来」.
 
 **A lane's review does not inherit the lane, and `pnpm josh review:brief` is what closes that.**
 `pnpm josh review:brief` prints the lane's absolute root, branch and HEAD, hands over targets written
@@ -103,7 +107,7 @@ isolation. So `epic:next` is asked **with** `--lanes`, and everything below runs
 switched".
 
 **Report the throughput gain only with its merge-race cost** — every overlap that becomes a conflict
-costs a resolution, a re-run gate and a review ("Conflicts are not predicted" below). Rationale:
+costs a resolution, a re-run gate and a review (`backlogrun-recovery.md` → "Conflicts are not predicted"). Rationale:
 `docs/maintainers/backlogrun-lanes-rationale.md` → "Why lanes cost as well as buy throughput".
 
 ### Once per repository, before the first lane opens
@@ -205,62 +209,9 @@ lane is cut from.
 
 ### Conflicts are not predicted
 
-**The child merges `origin/main` into its lane before its gate now, so this path is the fallback rather
-than the first line.** Every `fullrun` runs `pnpm josh main:merge` ahead of the gate
-(`chain-rule.md` → "origin/main is merged in before the gate", the single source), so an overlap
-already on `main` is resolved before the gate reads the tree. What this section covers is an overlap
-that lands on `main` *after* it, which `followup` still reports as a conflict.
-
-**Nothing here forecasts which children will overlap.** The overlap surfaces where GitHub already
-reports it: a pull request that conflicts with its base comes back `mergeStateStatus: DIRTY`, which
-`git-pr-checks-eval.ts` reads as a **failure** rather than polling through it — so `pnpm josh followup`
-ends that child with a named conflict in about ten seconds.
-
-**That child does not stop: it resolves the conflict in its own lane.** It is **not** counted against
-the consecutive-failure guard either way.
-
-**The merge direction is `origin/main` into the lane's branch, never a rebase**, and no step below
-rewrites a pushed commit. Rationale: `docs/maintainers/backlogrun-lanes-rationale.md` → "Why a conflict
-is resolved in the lane rather than handed to a person".
-
-1. **Resolve in the lane.** `git fetch origin main`, merge `origin/main` into the lane's branch, resolve
-   in place. Do not close the lane, open another, or switch its branch.
-2. **Re-run the whole gate.** The tree changed, so the green recorded before the conflict is void:
-   `pnpm josh lint:related` and `pnpm josh test:related`, then `pnpm josh gate`.
-3. **Review the resolution, one round.** Brief it with `pnpm josh review:brief` and run `/code-review`
-   over the resolution diff, then require `pnpm josh review:attest --check` to answer `ok`. That round
-   is a different subject and does not spend one of the two the cap allows — `prompts/review.md` →
-   "Review round cap" carries the exception.
-4. **Conclude the merge and push it, with `pnpm josh git -y`** — the only sanctioned way; without it
-   nothing changes on `origin` and condition 3 parks the child for good. **Record the resolution on the
-   Issue in this same step** — a comment naming the conflicting paths — because condition 3 counts
-   resolutions off the Issue comments, not off memory.
-5. **Merge**, by re-running `pnpm josh followup` exactly as before.
-
-**The safeguard is the re-run verification, not who holds the pen** — a conflict the run can resolve is
-not routed to a person.
-
-**The run steps back under these four conditions, and under no others. The list is exhaustive and
-carries no judgement.**
-
-1. **The resolution requires deleting the other side's change.** That decides intended behavior, not
-   text. It goes to the user as a **specification** question — "behavior A or behavior B" — never as a
-   diff.
-2. **Both sides rewrote the same lines** — overlapping, not adjacent. Read off the structure of the
-   conflict hunks, so it needs no interpretation.
-3. **A second conflict on the same child.** One resolution per child; the count is read off the Issue
-   comments step 4 writes, so it survives an interrupt.
-4. **The re-run gate did not come back green, or the resolution review returned a High.** Not only a
-   High: a lint error, a failing test or a spell-check hit that merging a moved `main` introduced is
-   this condition too.
-
-Meeting any of the four, the child is parked — `needs-decision` plus a comment naming which of the four
-it was — and its lane is **kept**, because the pushed branch is the resume path (the table below).
-
-**Leave the tree clean before parking: `git merge --abort` precedes a park under conditions 1, 2 or 4.**
-Conditions 1 and 2 are read mid-merge with conflict markers still in the tree, condition 4 after a merge
-that is resolved but not committed; condition 3 fires before any merge is started, so there is nothing
-to abort.
+**A child whose pull request conflicts with `main` resolves it in its own lane rather than stopping** —
+read `backlogrun-recovery.md` → "Conflicts are not predicted" when `pnpm josh followup` reports the
+conflict.
 
 ### What happens to a lane
 
@@ -269,7 +220,7 @@ to abort.
 | The child **merged** | `pnpm josh lane:close <N>` | `followup` released the hold and the branch is on `main`; nothing in that tree is wanted |
 | The child was **parked before its commit** | `git -C <dir> stash push -u -m "backlogrun: parked #<N>"`, record it on the Issue, then `pnpm josh lane:close <N>` | The stash is a repository-level ref, so it outlives the work tree — and `lane:close` is a **forced** removal that would otherwise take the work. `epic:next` counts a parked child's lane as released, so a lane left open holds a seat the count believes is free |
 | The child was **parked after its commit and push** | **Left open**, its directory and held seat recorded on the Issue | The stash step is a **no-op** (tree clean because committed). What `lane:close` would take is the **local branch**, which is the resume path |
-| The child hit a **merge conflict** | **Left open** — the resolution happens in it | The child resolves in place ("Conflicts are not predicted"). A park under that section's four conditions takes the row above |
+| The child hit a **merge conflict** | **Left open** — the resolution happens in it | The child resolves in place (`backlogrun-recovery.md` → "Conflicts are not predicted"). A park under that section's four conditions takes the row above |
 | The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work *is* the artifact a person has to look at. Name the lane directory in the stop report and in the Telegram |
 | The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count | Same reasoning; only the counter differs. **A merge conflict is not this row** — it takes the row above, and it is not counted |
 | **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child | A lane exists that no `pnpm josh …` runs in and the next `lane:open` answers `already-open`. Closing frees the seat; parking is right because the cause is one a person fixes. Carry pnpm's reason into the park note |