@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -1,97 +1,43 @@
 # `backlogrun` — recovering a child that went wrong
 
-**Read the section you need at the moment it is needed, never at the entry or before the first child**
-(joshuafolkken/kit#3175). Both sections below are reached only on failure — a unit that went silent, a
-lane whose pull request conflicts with `main` — so a run in which nothing fails never pays for them.
-`backlogrun-child.md`, `backlogrun-lanes.md` and `chain-rule.md` point here at those triggers.
+Point-of-use, read one section at the failure that reaches it; the single source of `run:liveness`.
 
 ## 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 `backlogrun-child.md`'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.
+**A stop from outside leaves no notification behind, so the parent polls rather than waits.** Record
+where a lane child writes with `pnpm josh lane:output <N> <path>` in the dispatch turn, and once its
+output has been unchanged for the silent-unit window (`backlogrun-progress.md` → "Waiting, and never
+waiting forever") **ask the command rather than combining the traces yourself**, in the checkout the
+unit was given:
 
 ```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>
+unit_output=$(pnpm josh lane:output <N>) &&
+  pnpm josh run:liveness <N> --output "$unit_output"     # the `&&` is load-bearing: `none` is no path
+pnpm josh run:liveness <N> --output <absolute path> --process <command lines naming this checkout>   # a unit in this session's own checkout
 ```
 
-| 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-recovery-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.
+| Answer | What the parent does |
+| --- | --- |
+| `alive` | Keep polling; touch nothing |
+| `settled` | Re-read with `pnpm josh run:status <N>` and take the branch its state section says |
+| `undetermined` | Read the trace that failed and ask again. **A second in a row on the same child is a fault in the check**: send a `confirmation` naming the trace and stop — never escalate it to `stopped` |
+| `stopped` | The recovery below |
+
+Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why liveness needs silence and no
+process together".
+
+**On `stopped`, re-read with `pnpm josh run:status <N>`.** **A re-read carrying `needs-decision`** — the
+unit parked it, then stopped: leave the label on and count nothing. Otherwise, while `state: OPEN`:
 
 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/merge/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 — the label then answers to `backlogrun-park.md` → "Only a person's
-     judgement carries `needs-decision`". 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.
+   record it on the Issue; it is popped by message, `pnpm josh stash:pop "backlogrun: stopped unit for
+   #<N>"`, never positionally.
+2. **Classify and act in one call** — `pnpm josh run:merge <N> --output <path>` (`--epic <E> --repo
+   <owner/repo> --owner "$PPID"` for a named epic), **the same composite a returned child takes**. It
+   tells an `outage` (re-dispatched with its session resumed, uncounted, bounded by
+   `CONSECUTIVE_OUTAGE_LIMIT`) from an `abandoned` child (parked `needs-decision` and counted), and drops
+   the stale `in-progress` itself.
+3. **Act on the token it printed** — `backlogrun-progress.md` → "Running a named epic's children".
 
 Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why the poll routes through `run:merge`".