@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/.claude/settings.json

@@ -56,11 +56,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary in the session language — 3 plain sentences (Now / Change / Check) a non-programmer can follow. Name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen. Then Details, then every change with its test. Ordinary markdown, never wrapped in a code fence. Required in fullrun/halfrun/backlogrun even when the Issue body was filled; presentation only, never a confirmation stop. Completion reports lead with Cause / Fix / Result. Tests are required for ALL changes; zero tests without explicit approval is a violation. Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
-					},
-					{
-						"type": "command",
-						"command": "echo 'Deleting a git-tracked file is reversible, so it is NOT Tier C — do not ask for confirmation on reversibility grounds. Still inspect the target first and surface anything that contradicts the task.'"
+						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary (Now / Change / Check, then every change with its test). Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
 					},
 					{
 						"type": "command",

package/.claude/skills/dependency-update/SKILL.md

@@ -11,8 +11,10 @@ half: what you actually run to find out whether a command already touched them,
 one change that is expected. It applies after `pnpm update`, `josh latest`, `pnpm josh overrides`,
 a Dependabot merge, or any other command that can rewrite dependency versions.
 
-The canonical extended reference is `prompts/collaboration-workflow/operating-rules.md` → the overrides protection
-section; this skill is the operational procedure, and the two must agree.
+This skill is the single source of the overrides protection's procedure;
+`prompts/collaboration-workflow/operating-rules.md` only points here. Overrides were added on
+purpose — for security, compatibility or a working guarantee (for example
+`"esbuild@<=0.24.2": ">=0.25.0"` for Workers build compatibility).
 
 ## 1. Effective overrides live in the workspace — inspect both files
 
@@ -35,7 +37,8 @@ git diff -- pnpm-workspace.yaml package.json
 and confirm the effective `overrides:` block in `pnpm-workspace.yaml` and any historical
 `pnpm.overrides` declarations in `package.json` are untouched, **and** that `devDependencies`
 versions still respect the effective overrides. If any entry was removed, modified, or bumped past
-an override, restore it immediately.
+an override, restore it immediately, investigate why it changed, and report that to the user — never
+keep the change without explicit approval.
 
 `josh latest` prints its own verdict as its last overrides line (`✔ overrides unchanged (<n> from
 <file>)`, or a `⚠ overrides changed` warning), and `pnpm josh overrides` compares effective workspace

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

@@ -6,8 +6,9 @@ description: The procedures for the `josh epic:*` commands that make an epic run
 # The `josh epic:*` commands
 
 These three commands are what turn an epic from a list of issue numbers into something a run can
-execute unattended. The canonical extended reference is `prompts/collaboration-workflow/` — `epic-bundle.md`, `epic-audit.md` and `cross-repo-epic.md` between them; this
-skill is the operational procedure, and the two must agree.
+execute unattended. **This skill is their single source**: `prompts/collaboration-workflow/` keeps
+`epic-bundle.md`, `epic-audit.md` and `cross-repo-epic.md` only as pointers here, and the history
+behind the rules is `docs/maintainers/epic-commands-rationale.md` (joshuafolkken/kit#2892).
 
 The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `backlogrun` — live in the
 `workflow-commands` skill.
@@ -80,9 +81,12 @@ adds is reading *inside* the children:
 | The search for those issues could not read the open backlog | **error** |
 | That search stopped before the end of the backlog | warning |
 
-**Only errors fail it.** The first check fires on a legitimate forward reference as readily as on a
-real missing dependency; failing on both would make design notes unwritable. A forward reference the
-other child *already depends on* is not reported at all.
+**Only errors fail it** (exit 1); a warning leaves the exit code alone. The first check fires on a
+legitimate forward reference as readily as on a real missing dependency; failing on both would make
+design notes unwritable, so the reader judges and the machine only keeps it from being missed. A
+forward reference the other child *already depends on* is not reported at all. Acceptance criteria
+that require what a child free to run later produces cannot be met however anyone decides, which is
+why that check is an error.
 
 **A pair with either child closed is a warning, not an error.** What makes an undeclared order a
 contradiction is that the criteria's child *can run first*, and one end closing is enough to make
@@ -92,11 +96,13 @@ audit forever, which stops every future run of that epic at the first step. It i
 dropped because dropping it hands the same pair to the first check, which reports it as an implicit
 dependency instead: the same one line, minus the detail that the name is in the acceptance criteria
 (joshuafolkken/kit#1010, widened from both-closed to either-closed by joshuafolkken/kit#1597 after a
-closed child citing an open sibling **as evidence** held an epic red at step one).
+closed child citing an open sibling **as evidence** held an epic red at step one). **The demotion
+needs the closed state confirmed**: `epic_issue.normalize_state` maps every state but `CLOSED`
+(`MERGED` included) to `OPEN`, so a state that could not be confirmed stays an error.
 
 **Fixing what it finds is Tier A** — re-pointing a dependency or correcting prose is reversible and
-will otherwise stall the work. Park with `needs-decision` only when the contradiction is a design
-choice nobody has made.
+will otherwise stall the work, so fix it without asking and record why on the issue. Park with
+`needs-decision` only when the contradiction is a design choice nobody has made.
 
 **The two `orphan search` findings are the exception, because neither is a contradiction.** They are
 about the search itself rather than about anything the children say (joshuafolkken/kit#1033):
@@ -114,6 +120,8 @@ about the search itself rather than about anything the children say (joshuafolkk
 state or artifact, list the existing code referencing that concept and confirm some child owns
 updating it. Label names are single-sourced in `scripts/git/issue-labels.ts`.
 
+History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why the children are read across".
+
 ## `josh epic:next <E…>` — what is runnable
 
 Returns **every** runnable child, bundled per repository with the local checkout to run it in.
@@ -243,12 +251,12 @@ in `Dependencies` — is what a wave has to satisfy, and editing the body alone
 with nothing after it** — which is exactly what a hub is the moment the earlier wave has been chained
 into it. `chains_containing` finds several indices; `is_branching_after` does not hold, because it
 requires a successor in **every** chain naming the target and a hub has none in any of them; so
-`ambiguous_position_error` is raised (`scripts/git/git-epic-chains.ts`). **The first child of the
+`ambiguous_position_error` is raised (`scripts/epic/epic-chains.ts`). **The first child of the
 next wave therefore goes into the declaration by hand**, with its `blocked-by` recorded to match.
 Once the hub has a successor, `--after <hub>` branches a new line and the rest of that wave goes in
 with it.
 
-**Nothing in the parsing or the consistency check forbids this.** `DECLARED_CHAIN_LINE` in `scripts/git/git-epic-parse.ts`
+**Nothing in the parsing or the consistency check forbids this.** `DECLARED_CHAIN_LINE` in `scripts/epic/epic-parse.ts`
 asks only that a line be *nothing but* a chain, so there may be any number of chain lines and **one
 child may be an endpoint of several of them** — `parse_dependency_links` expands each line
 independently and flattens the result, dropping only self-loops. `find_anomalies` in
@@ -328,7 +336,11 @@ to implement.
 - **The epic auto-closes only when every cross-repository child's state could actually be read.** One
   unreadable child leaves it open, exactly as before.
 - **An epic in another repository must be referenced as `owner/repo#N`** — `backlogrun
-  joshuafolkken/kit#858 --only`. A bare `#N` resolves to *this* repository's issue of that number.
+  joshuafolkken/kit#858 --only`, `epic:next joshuafolkken/kit#858 --repo joshuafolkken/app-kit`. A
+  bare `#N` resolves to *this* repository's issue of that number. A cross-repository epic exists in
+  one repository only.
+- **`epic:next` prints each candidate's repository and local checkout** from joshuafolkken/kit#869's
+  map; a repository with no checkout prints `(no local checkout)` and is **never cloned on its own**.
 
 **A dependency that crosses a repository is not satisfied by the blocking issue closing.** Merging
 does not publish: the merge, the auto-tag and the publish run one after another, so a consumer told
@@ -341,12 +353,17 @@ default branch declares has appeared in the registry.
 wait on — so a closed blocker there resolves rather than waiting until the run's own eight-hour
 timeout with nothing an operator can edit to clear it. The answer is read from the blocker
 repository's own manifest and never from the registry: a registry 404 also means "this token may not
-see it", so resolving on one would start a consumer child before its blocker's release existed.
+see it", so resolving on one would start a consumer child before its blocker's release existed. A
+manifest read that fails (rather than answering 404) is told apart by HTTP status and still waits.
 
 **The evaluation is an AND in that order.** While the blocker is open the registry is never
 consulted, so a run never stalls on a publish from the moment it starts. The target is that exact
 version, never "something newer" — a consumer several releases behind would otherwise be satisfied by
-a publish that predates the change.
+a publish that predates the change. **A child no longer bumps the version** (joshuafolkken/kit#1486):
+the version moves only when `pnpm josh release` runs, so the target is the release that includes the
+blocker, and the default branch's version just after its merge is the previous release, which would
+satisfy the wait at once. The publish check shares `josh propagate`'s implementation; it is not
+defined twice. History: `docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
@@ -373,14 +390,18 @@ all: `repos/{owner}/{repo}/issues/<N>` serves one too, and a merged PR does not
 
 **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. Reported as a gap it puts `⚠ Could not read #N.` above the verdict, and the rule below stops an
-unattended run on exactly that, for a reference that never existed (joshuafolkken/kit#957). **The two
+read. Reported as a gap it puts `⚠ Could not read #N.` above the verdict, and the could-not-answer rule
+(`prompts/review.md` → "Three-way disposition after the cap") stops an unattended run on exactly that, for a reference that never existed (joshuafolkken/kit#957). **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. GitHub answers 404 for an issue the token may not see as well, so as not to leak
 its existence — which does not reach this command, because it probes the repository whose open issues
 it has just listed. The probe costs one REST request and runs **only** when a read has already
 failed, and only on the path that needs the distinction: the backlog's own relation reads, up to two
-hundred of them, never pay it.
+hundred of them, never pay it, and the referenced-number reads are capped at twenty. **Only the
+subject's own body is followed** — the reverse direction would scan every closed issue, and a
+follow-up already names its parent. The reference parsing is the same implementation as
+`epic:audit`'s implicit-dependency check, applied to the backlog instead of one epic. The open backlog
+is small enough to scan whole, so there is no index or cache.
 
 | Candidates | Do | Tier |
 | --- | --- | --- |
@@ -392,6 +413,11 @@ hundred of them, never pay it.
 | No strong signal | Nothing | — |
 | **The epic listing was cut short** | **Nothing** — every placing row above is withheld | — |
 
+**`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**
 (joshuafolkken/kit#1697). "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
@@ -399,7 +425,8 @@ children invisibly. **`add_to_epic` rests on it as much as `create_epic` does**:
 the epic a *candidate* sits in, while an unseen epic already tracks the issue itself, is the same
 duplicate by another route. The cut was already on standard error
 (`⚠ The epic listing …`) while standard output went on printing an executable
-instruction such as `Create an epic for these (Tier A — do it).` — and the rule below that reads a warning as "could not answer" is written for one above
+instruction such as `Create an epic for these (Tier A — do it).` — and the rule that reads a warning as "could not answer" (`prompts/review.md` → "Three-way
+disposition after the cap") is written for one above
 `Nothing to bundle.`, so it never reached this verdict. Acted on as Tier A, that is a **second epic
 over an already-tracked issue**, which the auto-close and `epic:next` cannot both be right about
 (joshuafolkken/kit#943). The verdict now says so itself:
@@ -462,3 +489,5 @@ Full behavior: `docs/josh-commands.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**.
+
+History: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why issues filed apart are bundled afterwards".

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

@@ -15,7 +15,7 @@ green while spacing, layout and styling are visibly broken. This skill is the lo
 In order:
 
 1. The routes given as arguments (`/verify-ui / /blog`).
-2. Otherwise, derive the candidates with `pnpm josh ui:routes` (alias `josh uir`): it reads the
+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.

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

@@ -28,16 +28,8 @@ resident in the AI documents, because it has to hold when this skill has *not* b
 - 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.** A `backlogrun` that is cut and
-resumed is still the one invocation a person typed — the keyword authorized the declared budget, and
-the cut is an execution detail of spending it. What this rule forbids is _inferring_ a workflow from a
-request's shape. **The reading covers `backlogrun` and it alone** — a `fullrun` cut still waits for
-the keyword, because a `fullrun` ends at one issue and has nothing to carry.
-
-**`backlogrun-steps.md` → "The session cut is inside the invocation" is the single source of the
-mechanism** — the record, the two commands, and what each answer means, and how a named-issue
-`backlogrun #N1 #N2 …` pins its list to what was typed while the issues it has finished live in the
-record's `done` field rather than shrinking the string.
+**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".
 
 ## 1. Which file to read
 
@@ -62,7 +54,7 @@ lists `backlogrun.md` alone: its parent orchestrates and never implements, so `f
 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 `rule-residency.md`, reached only when a rule is placed, moved or retired.
+in `prompts/collaboration-workflow/residency.md`, reached only when a rule is placed, moved or retired.
 
 ### The fetch is one `Read` call per file
 
@@ -100,8 +92,8 @@ procedure alone, and the rest of `backlogrun-park.md` is read only when it is re
 **A pointer written `` `X.md` → "Heading" `` is read as that section, never by opening `X.md` whole:**
 
 ```bash
-pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim ; alias: josh ds
-pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs ; alias: josh rs
+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
@@ -251,15 +243,8 @@ there. A dispatched lane child never runs the retrospective.
 
 ## 3. What stays resident, and what is read from here
 
-**The residency criterion and its procedure are `rule-residency.md`, read only when a rule is being
-placed, moved or retired — never at any entry, and never during a run.** It carries question 0 (is the
-answer computable from mechanically readable inputs, so it is a decision oracle — `pnpm josh
-oracle:list`), the ordering question (does it decide *when or in what order* rather than *what*, so it
-goes in the run driver `pnpm josh run:step` — `prompts/collaboration-workflow/residency.md` → ordering
-question), the first question (can the trigger be named as one tool call, so the body moves out of
-`CLAUDE.md` to a hook via `prompts/collaboration-workflow/rule-delivery.md`), the second question
-(does it have to fire on a turn where no skill was loaded, so it stays in `CLAUDE.md`), and the
-procedure that decides how much of a resident rule is resident — the trigger-plus-pointer shape, the
-enumeration of every resident rule with an on-demand counterpart, and the retirement route and its
-three tests. `rule-residency.md` is the single source; the moment it binds is a turn spent editing
-these documents, never a turn spent executing an Issue.
+**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.

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

@@ -2,7 +2,7 @@
 
 ## Background the gate and push
 
-- **The clean path folds the region into one backgrounded `pnpm josh ship`** (gate → `git -y` →
+- **The clean path folds the region into one backgrounded `pnpm josh ship`** (preflight → gate → `git -y` →
   foreground `followup` → `run:tail`; joshuafolkken/kit#2398). The calls below serve a due second round.
 - Background `pnpm josh gate` beside the review; join it before commit.
 - Issue `pnpm josh git -y` in the background; its completion resumes the run, so the turn never ends

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

@@ -117,8 +117,10 @@ summary is bounded the way it is".
    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
    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. **The
-   child never writes that file** — it cannot tell its observation from the sibling lane's.
+   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
+   lane** (joshuafolkken/kit#2919) — it merges with the child's pull request, and a sibling lane's
+   file is never one it touches.
 4. **Decisions taken and why**, where the decision was not already logged as an Issue comment.
 5. **What was left undone**, and under whose authority.
 
@@ -162,7 +164,7 @@ unit was given** — this session's own unless the unit was handed a separate wo
 the recovery below is taken there too.
 
 ```bash
-pnpm josh run:liveness <N> --output <path> --process none    # alias: josh rv
+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>
 ```
@@ -288,7 +290,7 @@ separate command to ask first. Rationale: `docs/maintainers/backlogrun-child-rat
 preflight is part of the claim".
 
 ```bash
-answer=$(pnpm josh run:hold 926)   # alias: josh rh ; one token on stdout, prose on stderr
+answer=$(pnpm josh run:hold 926)   # one token on stdout, prose on stderr
 ```
 
 | Answer | What it found | What to do |

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

@@ -137,7 +137,7 @@ runs `lane:open`, then — only when `--stash` is given, which is the first lane
 into the lane and re-installs against the lock it brought in, then `lane:dispatch`:
 
 ```bash
-pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else; alias: josh lnla
+pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else
 pid=$(pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes") || exit 1   # the first lane only, and only if `josh latest` stashed
 ```
 

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

@@ -33,6 +33,12 @@ authorization, whether it came from a named epic or from the opted-in pool:
   is Tier A" carries the re-dispatch itself. A released child takes a lane exactly as any batch child
   does.
 
+## The parent does not investigate a lane failure itself
+
+**A lane failure whose reason is not on its Issue is read by a unit** — `pnpm josh delegate
+lane-failure-investigation` (joshuafolkken/kit#2947); the parent checks the cited lines and
+`pnpm josh issue:state` before it parks, re-dispatches or files.
+
 ## `needs-human-review` — the one stop that is not a park
 
 A child carrying **`needs-human-review`** is degraded to a `halfrun`-shaped stop and **the whole run ends

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

@@ -50,11 +50,11 @@ for a whole interval (that exit says so on standard error). **Nothing in flight
 parked, a stop — run `pnpm josh run:progress --mark` in the same turn to restart the silence clock. The clock is silence, never a timer
 (`docs/josh-commands.md` → "`josh run:progress`").
 
-**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking.
-`scripts/rules/early-heartbeat.ts` → `decide` refuses a sleep-only `Bash` call on three tests — a timer it already allowed is still live, the
-report it would produce would land before the interval is up, or the wait runs longer than the interval
-— so **a single correctly-spaced arm is allowed**. It is still not the way to report; the step above
-prints without arming anything, and `--wait` is not a wait timer.
+**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking
+(`scripts/rules/early-heartbeat.ts` → `decide`), though **a single correctly-spaced arm is allowed**. It
+is still not the way to report; the step above prints without arming anything, and `--wait` is not a
+wait timer. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the heartbeat reads
+as it does".
 
 **The default interval is twenty minutes, overridable — by the person, not the run.**
 `JOSH_PROGRESS_INTERVAL_MINUTES` moves both sides (the guard reads it through the watcher's reader);
@@ -65,14 +65,11 @@ moves the watcher alone** — it makes the watcher quieter than the floor, never
 **Every unscheduled progress statement is answered by `pnpm josh run:progress --once`** — presented in
 the same five field lines, the reply to an explicit ask and the note just after a run starts alike.
 **Never write a clock time the command did not print** (not an approximation, not a placeholder — where
-a field is missing, say so). **`--once` records the report**, so no `--mark` beside it. **A live timer
-is counted from the record the guard writes when it allows one**, never from the machine's `sleep`
-processes.
+a field is missing, say so). **`--once` records the report**, so no `--mark` beside it.
 
 **Every report opens with the time the observation was taken** — not only how long it has been quiet: an
-absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **The date is part of it**, and **the local clock
-leads with UTC beside it and the offset that ties them**. **It is added, never substituted for the
-elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
+absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **It is added, never substituted for
+the elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
 `at` stamp and the `next` field.
 
 **The line carries observations, never "still running", and nothing in it is a verification result** —
@@ -87,8 +84,8 @@ promoted to interrupt, never demoted to requested.**
 
 **The report surface belongs to the run, not to the session** (joshuafolkken/kit#2207). The run's
 session-facing events — a plan posted, a child launched, a PR opened, a review round, a park, a cut, a
-stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`),
-which survives the cut because it is the run's and not any one session's. **Every session is a writer;
+stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`).
+**Every session is a writer;
 the reader is a script in a pane of the person's own, never a conversation** (#2492):
 `pnpm josh run:event --watch` prints each event the moment it lands, in the session language, and the
 `heartbeat` events say the run is alive when quiet. **No session relays the stream** — name the watch command once, at the first cut or when
@@ -106,8 +103,7 @@ remaining child blocked behind a parked one, the backlog drained of anything run
 streak tripped — is pushed to the interrupt tier: `pnpm josh run:carry --end --stopped "<reason>"` sends one ⏸️ confirmation
 as it ends the record, and because the record is gone by the second `--end` the same stop never notifies
 twice. A parked child is pushed by the child itself, which records the park and sends its own
-`confirmation` before it stops (`backlogrun-park.md`). **Nothing new carries either one** — both ride the
-existing notification types and the record the watcher already keeps. Rationale for the tiers:
+`confirmation` before it stops (`backlogrun-park.md`). Rationale for the tiers:
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the signal tiers are split this way".
 
 **A heartbeat is emitted from the moment a run has started, even before any child carries
@@ -146,9 +142,8 @@ long.
 watcher's scope and placement: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the watcher
 runs where it does".
 
-**A run that merges needs no teardown; a run that stops has to end the reporting itself.** The issue
-leaves the `in-progress` listing at the merge, so whatever is waiting prints nothing and `--hours` ends
-it. **A stop keeps that label on purpose** — so **no further `--wait` is started** after the stop
+**A run that merges needs no teardown; a run that stops has to end the reporting itself.** **A stop
+keeps the `in-progress` label on purpose** — so **no further `--wait` is started** after the stop
 notification, and any long-running watcher still in the background is stopped in the same turn. That
 covers `halfrun`'s stop before commit, a `needs-human-review` stop, a split or prerequisite stop, and
 a `backlogrun` named issue's failure stop.
@@ -167,9 +162,9 @@ answers=$(pnpm josh epic:next 858 909 --repo joshuafolkken/kit --lanes)
 # every named epic, merged into the same pool — "Several epics in one run" above
 ```
 
-**`--lanes` is the form to use.** A lane's branch is `<N>-lane`, which `pnpm josh git` commits from, so
-a child handed a lane runs the whole `fullrun` procedure inside it. Read a line per child, and treat a
-single non-numeric line as the verdict.
+**`--lanes` is the form to use.** Read a line per child, and treat a single non-numeric line as the
+verdict. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why a named epic's children
+run in lanes".
 
 1. Run the command above.
 2. **One or more numbers** — where the child runs in this session's own checkout, its `fullrun` claim
@@ -317,8 +312,8 @@ the next turn of this session costs more than the threshold in billed input.
 
 **135,000 is shared by the scheduler entry, scheduler hand-off and lane worker implementation cut.**
 The value is `CONTEXT_CUT_THRESHOLD` in `scripts/cost-runtime/context-cut-threshold.ts`; `cost --cut`,
-`run:merge` and `run_cut.IMPLEMENTATION_CONTEXT_THRESHOLD` all read it rather than carrying separate
-numbers. The output ceiling and the entry-read figure are a separate 150,000, not this threshold.
+`run:merge`, `run_cut.IMPLEMENTATION_CONTEXT_THRESHOLD` and the parent hand-off guard all read it. The
+output ceiling and the entry-read figure are a separate 150,000, not this threshold.
 
 ### The check is asked at every merge, and delegation does not excuse it
 
@@ -333,7 +328,7 @@ answer, and take `over`'s branch at that child.
 
 ### When to ask, and what to do
 
-**Ask once per child, immediately after its merge and `pnpm josh ms`** — never mid-child.
+**Ask once per child, immediately after its merge and `pnpm josh ms`**; mid-child, a hook asks (#2947).
 
 ### A parent without a completion callback hands off at its first dispatch
 
@@ -443,10 +438,9 @@ survive the cut is re-dispatched, never adopted** — `pnpm josh lane:open <N>`
 progress comment is generated from it** (joshuafolkken/kit#2024) — children run, Issues filed,
 **consecutive failures**, and the time the run started. `pnpm josh run:merge` writes the merge into
 the record and mirrors the counters onto the epic comment at every child's merge. **The
-consecutive-failure count is the one that matters** — the stopped-unit section leans on it to notice
-the environment is at fault, and a merge resets it. **The record survives a session cut and a
-compaction alike.** Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives
-in records, not the conversation".
+consecutive-failure count is the one that matters**, and a merge resets it. Rationale:
+`docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives in records, not the
+conversation".
 
 ### What carries over, and where it lives
 
@@ -463,16 +457,18 @@ in records, not the conversation".
 
 ## Waiting, and never waiting forever
 
-| Setting | Value | Why |
+| Setting | Value | Meaning |
 | --- | --- | --- |
 | Polling interval | 60 s | **A floor between two asks, never a clock the parent sets.** It bounds a re-ask made while the parent is *already awake*; what wakes it is "The parent keeps no clock of its own" below. |
 | `backlogrun` idle-watch poll | 5 min | Not the interval above, and a floor in the same sense. |
 | Silent delegated unit | 30 min | Not the child's duration — the time its output has gone **unchanged**. Past it, run the traces above and book a stopped unit as a failure. |
-| Stale `in-progress` | 90 min | Longer than any single child has taken; past it, the other session is gone. |
+| Stale `in-progress` | 90 min | Past it, the other session is gone. |
 | Publish wait | 10 min | `josh propagate`'s own budget. A failed publish never appears. |
-| Whole run | 8 h | An unattended run that has not finished overnight needs a person, not more waiting. |
+| Whole run | 8 h | Past it, the run needs a person. |
 
-Each timeout **ends the wait and reports** — none is retried indefinitely. A stale child's label is
+Each timeout **ends the wait and reports** — none is retried indefinitely. Rationale for the figures:
+`docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
+clock". A stale child's label is
 removed first, so the next poll can offer it. **A graph that has deadlocked on a cycle is not this loop's
 to untangle**: `epic:next` detects it and exits with an error.
 
@@ -487,9 +483,7 @@ source and `run:report` the final report.
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
 clock".
 
-The driver checks lane completion every five seconds and makes a new backlog offer no sooner than one
-minute after the previous offer, except after collecting a child — waits that cost no AI turns. The
-watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
+The watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
 
 #### The wake exists only while something is in flight
 
@@ -527,7 +521,7 @@ Per-child completion notifications are unchanged: `pnpm josh followup` sends one
 **start** notification when the run begins, and an epic **completion** summary at the end. **Do not
 compose that summary by hand — `pnpm josh run:report` generates it from this invocation's events**
 (joshuafolkken/kit#2249, scoped in #2393): it renders what merged, what parked and why, and what was cut,
-reusing `format_event`, closing with the release tail below. Its output is the Telegram body too — pass it to
+closing with the release tail below. Its output is the Telegram body too — pass it to
 `pnpm josh notify --body-file`.
 
 **That same session asks `pnpm josh release:scope` once, after the last child has merged** — in the

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

@@ -131,7 +131,7 @@ single source.
 carried in a record rather than in the conversation:
 
 ```bash
-pnpm josh run:carry --begin "backlogrun --max 5 --idle 30" --owner "$PPID"   # alias: josh rc
+pnpm josh run:carry --begin "backlogrun --max 5 --idle 30" --owner "$PPID"
 pnpm josh run:carry --json                                                   # read it back in a resumed session
 ```
 
@@ -204,7 +204,7 @@ judgment starts an AI session, with the branch result and resume flags in its pr
 **Start it in the same turn as `--begin`, and stop it in the same turn as `--end`:**
 
 ```bash
-pnpm josh run:wake --start   # alias: josh rw ; right after `run:carry --begin`
+pnpm josh run:wake --start   # right after `run:carry --begin`
 pnpm josh run:wake --stop    # in the same turn as `run:carry --end`
 ```
 
@@ -267,7 +267,7 @@ run.
 **The plan is one command's output, not an assembly of several:**
 
 ```bash
-pnpm josh backlog:plan          # alias: josh blp
+pnpm josh backlog:plan
 ```
 
 **It renders the same classified pool `backlog:next` answers from**, so **the plan cannot promise an
@@ -282,9 +282,8 @@ order the run does not take**. Its four sections are:
   is distinguished from "not reached yet".
 
 **Report all four to the person, in the session language, before the first child starts.** Epic
-children are enumerated individually rather than summarized under their root. A `⚠` about a truncated
-listing is reported with them: the plan is then partial, and saying so is what keeps it from reading as
-complete.
+children are enumerated individually rather than summarized under their root. Report a truncated-listing
+`⚠` with them: the plan is then partial.
 
 ### Resolve what the plan can resolve, before starting
 
@@ -293,27 +292,28 @@ stop at a time.**
 
 - **Decide everything decidable from the issue itself.** Read the issue's body **and its comments**
   (`SKILL.md` → §2g), and where the answer is already there, record it as an Issue comment and
-  **remove the label** — `CLAUDE.md` → "Decision autonomy" already makes that Tier A. **Read every one
-  of them in one call** — `pnpm josh issue:read <N> <N> …`, the numbers the plan just listed under
-  "Waiting on a person" — rather than a `gh api` pair per issue.
+  **remove the label** — `CLAUDE.md` → "Decision autonomy" already makes that Tier A. **Read them all in
+  one `pnpm josh issue:read <N> <N> …` call**, not a `gh api` pair per issue.
 - **Never measure in order to decide.** A question needing a benchmark, a profile, or a run of the
   thing itself is not settled here: it stays labelled and the plan says so.
-- **Label what you find.** An issue that turns out to need a person's judgement has `needs-decision`
-  applied — the same label a parked child gets, applied the way `backlogrun-park.md` → "park and continue"
-  applies it. **The next plan then classifies it by reading the label alone**, never by reading the
-  body again.
+- **Label what you find.** An issue needing a person's judgement gets `needs-decision`, applied as
+  `backlogrun-park.md` → "park and continue" does. **The next plan classifies it by the label alone**,
+  never the body.
 - **Order and isolate the pool in the same pass** (joshuafolkken/kit#2776), from the same
   `issue:read`: an issue that must land first (it builds what another reuses, or both edit one code
   path) becomes a native `blocked-by`; an issue the `wip-cap.md` → 「実行のしかた」 enumeration hits
   gets `run:solo`, **every other one `run:lane`**. Comment the reason; the offer commands enforce all
   three, answering `triage` while an issue has neither.
+- **`priority:high` puts an issue first** (joshuafolkken/kit#2928; ranking: `docs/josh-commands.md` →
+  `josh backlog:next`). Apply it only on a cited ground — a stated deadline or urgency, or a person's
+  written policy — commenting the ground; **never remove it**.
 - **Report the order those labels produce — `pnpm josh backlog:plan --waves`** (joshuafolkken/kit#2778),
   `backlog:next` played forward wave by wave. Report it with the plan, never an order derived by hand.
 - **Then start the loop.** Whatever is still labelled is reported as parked and left standing; the
   run does not wait on it.
 
-**`needs-decision`, `run:solo` and `run:lane` are the workflow labels a run may apply, and none is
-`auto-ok` or `needs-human-review`.** Those two stay a person's alone (this file, `SKILL.md` → §2z); a
+**`needs-decision`, `run:solo`, `run:lane` and `priority:high` are the workflow labels a run may
+apply, and none is `auto-ok` or `needs-human-review`.** Those two stay a person's alone (this file, `SKILL.md` → §2z); a
 run parks with `needs-decision` and a person clears it.
 
 Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan and the decision pass come first"
@@ -331,7 +331,7 @@ returns the verdict with the issues to start. It stays both halves' contract sou
 *means* changes here.
 
 ```bash
-offer=$(pnpm josh backlog:offer --started "$started" --active "$active")   # alias: josh blo
+offer=$(pnpm josh backlog:offer --started "$started" --active "$active")
 offer=$(pnpm josh backlog:offer --started "$started" --active "$active" --exclude 1630,1631)   # after #1630, #1631 merged
 ```
 

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

@@ -27,18 +27,9 @@ therefore runs exactly one epic's children and stops.
 
 ## Explicit invocation required (MANDATORY)
 
-**Never start a `backlogrun` unless the user has typed the keyword in the current turn's prompt.**
-This is the same rule the other entry points carry, at the same strength — `SKILL.md` → §0 is its
-single source, and `CLAUDE.md` → "Explicit invocation required (MANDATORY)" is where it stays resident
-so it binds on a turn where nothing here has been read. It matters more here than anywhere else,
-because this is the entry point with the widest authorization: a conversational "clear the backlog" is
-**not** an invocation, a confirmation question is no substitute for the keyword, and an earlier turn's
-authorization does not carry.
-
-**The keystroke starts the invocation; it does not have to land in every session that invocation
-spans.** A `backlogrun` cut mid-run and resumed is still that one invocation
-(`backlogrun-steps.md` → "The session cut is inside the invocation"). This reading covers `backlogrun`
-and it alone — a `fullrun` cut still waits for the keyword.
+**Never start a `backlogrun` unless the user has typed the keyword in the current turn's prompt** —
+`SKILL.md` → "0. The rule that fires before any of them — explicit invocation"; a cut and resumed run
+is still that one invocation (`backlogrun-steps.md` → "The session cut is inside the invocation").
 
 ## The manifest — the ordered flow
 

package/.claude/skills/workflow-commands/chain-rule.md

@@ -35,8 +35,8 @@ Review results and successful pushes are never turn boundaries.
    **`pnpm josh followup` refuses the merge until the round is recorded**
    (`pnpm josh review:record --check --issue <N>`, joshuafolkken/kit#2343).
 5. **The clean path ships in one call** — with no second round due, background
-   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: gate → `git -y` → foreground `followup` → `run:tail`, stopping at the
-   first failure (joshuafolkken/kit#2398). `--review` runs both rounds (#2489). **Else a due round 2
+   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: PR preflight (#2946) → gate → `git -y` →
+   `followup` → `run:tail`, stopping at the first failure (#2398). `--review` runs both rounds (#2489). **Else a due round 2
    does not fit `ship`**: the PR opens between the rounds — background `pnpm josh git -y "<title> #<N>"`, round 2 beside CI, then
    `pnpm josh followup`.