@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "kit",
-	"description": "joshuafolkken/kit distributed skills: the Issue-driven workflow commands (kickoff/fullrun/halfrun/backlogrun), the epic:* commands, the post-dependency-update verification, the UI-verification gate.",
+	"description": "joshuafolkken/kit distributed skills: the Issue-driven workflow commands (kickoff/fullrun/halfrun/prrun/backlogrun), the epic:* commands, the post-dependency-update verification, the UI-verification gate.",
 	"author": {
 		"name": "joshuafolkken",
 		"url": "https://github.com/joshuafolkken"

package/.claude/settings.json

@@ -46,11 +46,11 @@
 	"hooks": {
 		"SessionStart": [
 			{
-				"matcher": "",
+				"matcher": "startup",
 				"hooks": [
 					{
 						"type": "command",
-						"command": "pnpm josh audit:provision",
+						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision",
 						"timeout": 180
 					}
 				]

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

@@ -69,11 +69,7 @@ than `josh latest`.
 
 ## 4. When the bump breaks something — fix forward
 
-Adopt the newest versions by default and resolve breakage **forward**: fix consumer code where a new
-rule or error is legitimate, and add or scope rule overrides at the correct layer (the shared kit /
-app-kit config), not as an ad-hoc consumer disable. When the breakage originates in a first-party
-package, file an issue there rather than only working around it in the consumer.
-
-Pinning back is a **last resort**, only when fixing forward is genuinely blocked. Record why, and
-open a tracking issue to return to latest. Fix-forward never authorizes a silent edit to a protected
-pin: the approval gates in sections 1–3 still apply.
+The procedure — latest-first, fix forward at the correct layer, pin back only as a last resort with a
+tracking issue — has its single source in
+`prompts/collaboration-workflow/principles.md` → "latest-first". Fix-forward never authorizes a silent edit to a protected pin: the
+approval gates in sections 1–3 still apply.

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

@@ -166,7 +166,7 @@ command prints a ⚠️ line naming that child rather than reporting a reorderin
 `owner/repo#number` and kept by the epic named earlier; withheld there, it stays withheld, because a
 `blocked-by` relation belongs to the issue rather than to the epic listing it. **One unusable graph
 refuses the whole answer**, and **one reference that does not parse fails the read** rather than
-being dropped. `docs/josh-commands-automation.md` → "`josh epic:next`" carries the worked form.
+being dropped. `docs/josh-commands-backlog.md` → "`josh epic:next`" carries the worked form.
 
 **An `in-progress` issue occupies a lane rather than the whole repository.** The occupancy is counted
 from that repository's own `in-progress` listing — never from anything the session remembers, since
@@ -209,7 +209,7 @@ inherits; open and tracked by none, the child waits on a person and the
 blocker is named on standard error; a state the relation did not carry reads as waiting. **So an order
 between two epics is recorded with a native `blocked-by` relation and honoured by naming both epics**
 — `epic:next 1936 1931`, or `backlog:next`, whose set is the whole opted-in backlog. The table is
-`docs/josh-commands-automation.md` → "`josh epic:next`".
+`docs/josh-commands-backlog.md` → "`josh epic:next`".
 
 Two things stop the command rather than being worked around: a **circular dependency**, and a
 **disagreement between the epic body and the `blocked-by` relations** (an epic written before `josh`

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

@@ -108,7 +108,7 @@ than restated — and beside it the one thing this one deliberately refuses: whe
 already been filed, from a title comparison (joshuafolkken/kit#1252). **Both run**, and neither
 replaces the other: `pnpm josh issue:file` runs the scout before it creates the issue, and
 `epic:bundle` afterwards, from the real number and the relations recorded against it.
-Full behavior: `docs/josh-commands-automation.md` → "`josh issue:file`".
+Full behavior: `docs/josh-commands-backlog.md` → "`josh issue:file`".
 
 **When the relation carries an order, record it** in `blocked-by` and in the epic's `Dependencies` —
 on an addition as much as on a new epic. Without it the batch survives and the reason for it does

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

@@ -11,10 +11,8 @@ never a procedure** (joshuafolkken/kit#3174): each rule is stated once, in the f
 
 ## 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.** 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`
+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

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

@@ -94,7 +94,7 @@ child over" in `backlogrun-lanes.md` carries the command.
 JSONL. `JOSH_WORKER_MODEL` overrides Claude Code only; `JOSH_WORKER_EFFORT` covers both providers,
 and legacy `JOSH_LANE_*` applies only here. Bad markers, missing CLI/auth and failure
 refuse or park without fallback or retry.
-`docs/josh-commands-automation.md` → "`josh lane:dispatch`" is the single source.
+`docs/josh-commands-run.md` → "`josh lane:dispatch`" is the single source.
 
 **The parent reads GitHub, never the summary.** That is `epic-child`'s verifier: a unit that reports
 a child finished without its PR merged leaves that child open, and `pnpm josh issue:state <N>` says so
@@ -118,7 +118,7 @@ summary is bounded the way it is".
    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
+   child appends only to its own issue's file, `.josh/observations/<N>.md`, in its own
    lane** (joshuafolkken/kit#2919) — it merges with the child's pull request, and a sibling lane's
    file is never one it touches.
 4. **Decisions taken and why**, where the decision was not already logged as an Issue comment.
@@ -190,7 +190,9 @@ and a child that skips it implements on a stale main. Only the dependency update
 lanes it changes hands**: no lane can switch to the default branch, so the parent runs it in the primary
 checkout **before each `lane:open`**. **And in a lane `josh latest` is not even asked** — `latest:scope`
 skips and `latest:guard` refuses. The stash that carries the lock file into the first lane is in
-`backlogrun-lanes.md` → "Once per repository, before the first lane opens".
+`backlogrun-lanes.md` → "Once per repository, before the first lane opens": the parent runs the update
+and pushes the stash in the primary checkout before `backlog:drive` starts, and the driver passes it
+to the first lane it launches.
 
 This is the same rule `latest-gate.md` is the single source of.
 
@@ -204,6 +206,6 @@ session".
 `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/josh-commands-run.md` → "`josh run:hold`"; rationale:
 `docs/maintainers/backlogrun-child-rationale.md` → "Why the preflight is part of the claim".
 

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

@@ -65,7 +65,7 @@ it is".
 
 `pnpm josh epic:next <E> --repo <owner/repo> --lanes` answers with **one issue number per line**, up to
 the number of free lanes, and each of those children runs in a **lane** of its own: a linked git work
-tree with its own branch, its own `.env` and its own dev and preview ports (`docs/josh-commands-automation.md` →
+tree with its own branch, its own `.env` and its own dev and preview ports (`docs/josh-commands-run.md` →
 "`josh lane:open` / `josh lane:close` / `josh lane:list` / `josh lane:prune`"). **Implementation, the
 verification gate and the review run in parallel; the merges stay serial** — each one lands on the
 `main` the next is then measured against.
@@ -89,7 +89,7 @@ two from its filing, because an issue with neither answers `triage` and nothing
 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` → 「単独実行の理由と由来」.
+`docs/maintainers/wip-cap-rationale.md` → "Why a solo run".
 
 **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
@@ -117,7 +117,7 @@ In the **primary checkout**, in this order, and never again per lane:
 1. `git switch main && git pull` — every lane branches from this ref.
 2. `pnpm josh latest:scope`, and the update on `required` — `backlogrun-child.md` → "`josh latest`
    runs once per session, not once per child".
-3. `pnpm josh lane:prune` — closes the lanes an interruption left registered without a work tree.
+3. `pnpm josh lane:prune` — closes lanes left without a work tree, sweeps unregistered leftovers.
 4. `pnpm josh run:tidy` — sweeps merged lanes and stashes (as `run:hold` does).
 
 **`pnpm josh latest` is never run inside a lane, whatever `latest:scope` answers there** — the command
@@ -135,6 +135,10 @@ Record it on that first child's Issue — the comment is what gets it popped if
 **The first lane's `pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes"` pops it
 by message, after `lane:open`'s own install** — never a positional `git -C "$dir" stash pop`: the stash
 is a repository-wide stack every lane shares, so a positional pop would take whichever lane last pushed.
+**Under the supervisor's `backlog:drive` the driver passes it, never you**:
+each launch asks whether a stash under that message is on the stack and, if one is, hands it to
+`lane:launch --stash` — the pop consumes it, so the first lane takes it and every later one launches
+without. The push above stays the parent's, before the driver starts.
 
 ### Opening one lane and dispatching its child
 

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

@@ -63,8 +63,8 @@ flight finish; no new lane is opened.
 
 ## park and continue
 
-When a child hits something this run may not decide — a Tier B toss-up, a Tier C action, an upstream
-defect, a split that needs a person — **park the child and keep going.**
+When a child hits something only a person can decide — → "Only a person's judgement carries
+`needs-decision`" below — **park the child and keep going.**
 
 ```bash
 gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'
@@ -107,6 +107,27 @@ parent that implements the released child inline is the failure the orchestrator
 Without removing the label the parked child never runs again — it is the second half of the
 human-in-the-loop cycle, not an optional tidy-up.
 
+## Only a person's judgement carries `needs-decision`
+
+**`needs-decision` means "a person has to choose", and nothing else.** This is the single source of
+when a run may apply it, by hand or through a park. It carries only:
+
+- a design choice nobody has made;
+- a Tier B toss-up, or a Tier C action (`CLAUDE.md` → "Decision autonomy");
+- an upstream defect in another package, whose wait-or-defer is the person's (`upstream-interrupt.md`).
+
+It never carries:
+
+- a choice with a clearly better default — that is Tier A: decide it and record it as an Issue comment;
+- whether to run something already planned and opted in with `auto-ok` — the opt-in is that decision;
+- a defect in the running repository's own run tooling — the run fixes it and resumes
+  (`prompts/collaboration-workflow/upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合").
+
+**When in doubt, it is Tier A**: decide, comment the decision, and continue. A label a person has to
+clear for nothing spends their attention and stalls the child. **A label a mechanical step applied** — a
+failed or abandoned child, a lost merge race's four conditions — is read against this list once its
+reason is known, and removed (Tier A, above) when the reason is not on it.
+
 ## `in-progress` is removed by whoever finds it stale
 
 A run's own ending removes `in-progress` — `pnpm josh followup` on a merge, `pnpm josh run:release <N>`

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

@@ -50,7 +50,7 @@ run in lanes".
    lane — and in the same turn start `pnpm josh lane:await <N...> --owner "$PPID"` in the background** (joshuafolkken/kit#2113).
    `lane:await` watches local process presence and exits when any named child confirms-complete. **The
    re-confirm delay and poll interval are the command's, not the agent's** — pass only the issue
-   numbers and `--owner` (why: `docs/josh-commands-automation.md` → `josh lane:await`). Without that wake (Codex), hand off instead — "A parent without a completion callback".
+   numbers and `--owner` (why: `docs/josh-commands-run.md` → `josh lane:await`). Without that wake (Codex), hand off instead — "A parent without a completion callback".
 
    **A `lane:await` wake is a confirmed-gone process, so classify the ending at once — do not wait out
    the silent-unit window** (joshuafolkken/kit#2277). On a `lane:await` wake go straight to `pnpm josh run:merge <N> --output <path>` — the composite reads the child's **exit
@@ -94,7 +94,8 @@ run in lanes".
    **not** parked and **not** counted against the consecutive-failure guard, and stays re-dispatchable
    (joshuafolkken/kit#2240); a **failed** child (OPEN, neither label, not an outage) has its stale
    `in-progress` dropped, is parked with `needs-decision`, and is counted against the consecutive-failure
-   guard.
+   guard. The label stays only once its reason passes `backlogrun-park.md` → "Only a person's judgement
+   carries `needs-decision`".
 
    **Beyond the offer `epic:next` prints** (`run` becomes numbers; `wait` / `stop` / `complete` /
    `error` pass through), the composite adds six verdict tokens: `over` — the merge crossed the budget,
@@ -217,8 +218,8 @@ ever.
 - **Every in-flight lane records a path** — **record the cut and hand the session off.** `backlogrun`
   declares a budget — `--max`, `--idle` and the 8-hour bound — so the cut is an execution detail: count
   everything the session has, then run `pnpm josh run:carry --cut --owner "$PPID"`. **Unless it answers
-  `capped`** (below), `pnpm josh run:wake` then starts the next session, which polls the still-running
-  lanes from `lane:list`. Post the progress comment naming **every lane in flight and the path each
+  `capped`** (below), the `pnpm josh run:wake` driver starts at its next poll even while this session
+  lives on, and polls the still-running lanes from `lane:list`. Post the progress comment naming **every lane in flight and the path each
   records**, name `pnpm josh run:event --watch` for a pane, and end the turn — nothing is relayed (#2492).
   `backlogrun-steps.md` → "The session cut is inside the invocation" is the single source of the
   carry; this reading is only where the cut is *taken*.
@@ -256,6 +257,10 @@ lane needs when its child has to be finished by hand.
 **Restart the progress watcher by name** — `pnpm josh run:progress --wait --output <handed-over paths>`
 in the background, in the same turn as that first `lane:list`. The wired `run:watcher:guard` stops a resume that skips this (joshuafolkken/kit#2353).
 
+**A session woken by the driver's hand-off does neither**: with `Driver
+result:` in its prompt, the `run:wake` driver watches the lanes, so it acts on its branch and cuts as
+its `Next:` line says. The watcher guard and the headless stop rule stand aside for it.
+
 ### A carried-over merge does not stand in front of the next lane
 
 **A carried-over child finishes in its own detached unit, and the resumed parent does not stand in front

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

@@ -82,11 +82,12 @@ guard, and go back to step 1.
      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
+     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. Never retried silently.
+     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").
@@ -146,7 +147,7 @@ carries no judgement.**
    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
+it was, read against `backlogrun-park.md` → "Only a person's judgement carries `needs-decision`" — and its lane is **kept**, because the pushed branch is the resume path
 (`backlogrun-lanes.md` → "What happens to a lane").
 
 **Leave the tree clean before parking: `git merge --abort` precedes a park under conditions 1, 2 or 4.**

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

@@ -143,7 +143,7 @@ be answered and every standing record is refused rather than resumed. A live PID
 the sandbox cannot read is held as `busy`.
 
 **Ask it before the plan, in the same turn as the first `git switch main && git pull`.** The contract
-is `docs/josh-commands-automation.md` → "`josh run:carry`"; what this loop does with each answer is here:
+is `docs/josh-commands-run.md` → "`josh run:carry`"; what this loop does with each answer is here:
 
 | It answers   | What the run does                                                                                                                                                                                                          |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -151,7 +151,7 @@ is `docs/josh-commands-automation.md` → "`josh run:carry`"; what this loop doe
 | `resumed`    | **This session is continuing a run that was cut** — a `--cut` handed the record off, or a `--resume` adopted it. Read the record with `--json` and take the budget figures from it, never from this session's own zero. Report the plan again — the pool has moved — and skip nothing else |
 | `busy`       | The record's **owner process is still running and no cut handed it off**: another parent is spending this budget right now. **Stop; do not open a lane.** (A record a `--cut` _did_ hand off answers `resumed` here even with its owner still alive.) Nothing here is yours to end — either that run finishes and ends its own record, or a person decides it is over |
 | `over`       | This session is over the context-cut threshold, so it claims nothing (joshuafolkken/kit#2760). **End the conversation**; retype the invocation in a fresh session |
-| `standing`   | A record is here that **no cut or supervisor handed off** — an unwatched crash, and the same command retyped over it. **Stop; do not open a lane**, and do not guess: the choice is the person's. Report the two commands the answer names — `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"` to carry that budget on, or `pnpm josh run:carry --end` and begin again to discard it. Pass `--owner` to the resume as to the begin |
+| `standing`   | A record is here that **no cut or supervisor handed off** — an unwatched crash, and the same command retyped over it. **Stop; do not open a lane**: the choice is the person's. Report the two commands the answer names — `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"` to carry that budget on, or `pnpm josh run:carry --end` and begin again to discard it. A crash from a run-tooling defect this run has since fixed is the one you resume yourself (`upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合") |
 | `mismatch`   | A record is here for a **different** invocation — a run that never reached `--end`. **Stop; do not open a lane**, and never resume into it. End it deliberately, with `pnpm josh run:carry --end`, once you know that run is over |
 | `expired`    | The 8-hour whole-run bound is spent. **Where a `--cut` handed the record off it is this run's own bound**, so this is the verdict on standard output and the run ends: report it and stop, and clear the record with `pnpm josh run:carry --end` once it is genuinely over. Where nothing handed it off it is printed on standard error ahead of a `began` instead — a person typing the keyword again over a spent record is starting a new run, and the record is replaced. A `--resume` over a spent record answers `expired` and adopts nothing |
 | `unreadable` | Report what it printed and **stop before opening a lane**                                                             |
@@ -161,9 +161,11 @@ is `docs/josh-commands-automation.md` → "`josh run:carry`"; what this loop doe
 child and nothing about the invocation's budget. **`--begin` claims the record exclusively and names
 the owning process, so a second parent is answered `busy`.**
 
-**Count into the record rather than into your head** — `--merged 1 --owner "$PPID"` at every child's
+**Count into the record rather than into your head** — `--merged <N> --owner "$PPID"` at every child's
 merge, `--filed 1 --owner "$PPID"` at every Issue this run files, and `--cut --owner "$PPID"`
-immediately before the cut. Every counter is an increment. **`--owner "$PPID"` is not optional on a
+immediately before the cut. `--merged` names the merged issue, never a count
+(`scripts/run/carry/run-carry-args.ts`): `run:merge` records the same issue, so a merge counted on both paths counts
+once. Every other counter is an increment. **`--owner "$PPID"` is not optional on a
 count**: a count that does not name the record's owning process is refused.
 
 **`--cut` hands the record off, and so does `run:wake` for a dead owner** (joshuafolkken/kit#2437): the
@@ -217,6 +219,9 @@ owner prevents a second driver from taking it over. On `none`, `expired` or `unr
 8-hour whole-run bound therefore still comes from the carry record. **A new authorization is still a
 person's**: the supervisor spends the declared budget and never declares another.
 
+**A supervisor stopped by a run-tooling defect is restarted by the AI once the fix lands** —
+`upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合".
+
 **What may be run is untouched.** The driver takes named issues from the invocation and pool issues
 from the existing offer command. The supervisor writes no label of its own; `auto-ok` arrives only
 through `issue:file`'s default. A judgment session receives
@@ -231,7 +236,7 @@ before each launch, and a failed named issue skips the remaining named prefix.
 
 **A person keeps control of it** — `pnpm josh run:wake --list` names the running supervisor and `--stop`
 ends it. Its failure warnings, log file, progress relay and the provider / model / effort each
-unattended role runs with are `docs/josh-commands-automation.md` → "`josh run:wake`".
+unattended role runs with are `docs/josh-commands-run.md` → "`josh run:wake`".
 
 **The completion report names how many sessions were woken beside the record's `cuts`** — one wake per
 cut is the invariant, and what counts is a carry record actually claimed, never a process started.
@@ -278,15 +283,15 @@ stop at a time.**
   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 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**,
+- **Label what you find.** An issue needing a person's judgement — `backlogrun-park.md` → "Only a
+  person's judgement carries `needs-decision`" — gets the label, applied as "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 meeting all three of the `backlogrun-lanes.md` →
   "Lanes — running more than one child at a time" conditions 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-automation.md` →
+- **`priority:high` puts an issue first** (joshuafolkken/kit#2928; ranking: `docs/josh-commands-backlog.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),
@@ -297,8 +302,8 @@ stop at a time.**
 **`needs-decision`, `run:solo`, `run:lane` and `priority:high` are the workflow labels a run may
 apply by hand, and none is `auto-ok` or `needs-human-review`.** `needs-human-review` stays a
 person's alone (`needs-human-review.md`); `auto-ok` reaches only a run's own filing, through
-`issue:file`'s default ("What one invocation approves"). A run parks with `needs-decision` and a
-person clears it.
+`issue:file`'s default ("What one invocation approves"). A run parks with `needs-decision` only on
+`backlogrun-park.md` → "Only a person's judgement carries `needs-decision`", and a person clears it.
 
 Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan and the decision pass come first"
 
@@ -306,7 +311,7 @@ Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan an
 
 **The loop is computed, not walked by hand.** The `run:wake` supervisor runs `pnpm josh backlog:drive`,
 whose head is `pnpm josh backlog:offer`: the answer-to-budget mapping, the retry count, the `--exclude`
-feedback and the lane count are its own (`docs/josh-commands-automation.md` → "`josh backlog:offer`"
+feedback and the lane count are its own (`docs/josh-commands-backlog.md` → "`josh backlog:offer`"
 and "`josh backlog:drive`"). **An AI session reaches this section only when the driver hands a branch
 back** — the `Driver result:` line names it, and its `Next:` line is the order: claim the record with
 `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"`, act on the branch, then hand the loop
@@ -321,6 +326,9 @@ back with `pnpm josh run:carry --cut --owner "$PPID"`:
 | `watch` | The backlog drained with nothing in flight; the retrospective is owed (`run:step`) |
 | `window` | The driver's wait window ran out with nothing to judge; hand the loop back as is |
 
+**`window`, `merge busy` and `merge retry` reach a session only after the supervisor's own re-runs run
+out** (`run-wake-driver.ts`).
+
 **A candidate only in another repository is never a token** — report it with its checkout and leave it
 to a session running there (`backlogrun-lanes.md` → "Concurrency").
 
@@ -386,7 +394,7 @@ again at its full budget. Both are ISO-8601 timestamps (`date -u +%FT%TZ`), and
 `--active` is refused. `--merged` is what has merged and `--running` what is still in a lane; **both
 count against the maximum**. **No ending abandons a lane**: whatever would have ended the run answers
 `watch` while `--running` is above zero, so the lanes drain and their merges reach the report. The full
-contract is `docs/josh-commands-automation.md` → "`josh backlog:budget`".
+contract is `docs/josh-commands-backlog.md` → "`josh backlog:budget`".
 
 **The completion report names three things the budgets make meaningful**: how many issues this run
 took, how many of them were picked up during an idle watch, and the termination reason — quoted from
@@ -450,7 +458,7 @@ All of these are this file's, and are reached here in the same order and for the
 | --- | --- |
 | `git switch main && git pull`, then `pnpm josh latest:scope`, then `pnpm josh lane:prune` — in the primary checkout, before the first lane opens | `backlogrun-lanes.md` → "Once per repository, before the first lane opens" |
 | `josh latest` on `required` only, asked once at the first child and never in a lane | `backlogrun-child.md` → "`josh latest` runs once per session, not once per child" |
-| `pnpm josh run:hold <N>`'s preflight check, before each child that is not in a lane — act on what it prints | `docs/josh-commands-automation.md` → "`josh run:hold`" |
+| `pnpm josh run:hold <N>`'s preflight check, before each child that is not in a lane — act on what it prints | `docs/josh-commands-run.md` → "`josh run:hold`" |
 | `pnpm josh run:progress --wait` in the background, `--mark` at every real report | `progress-watcher.md` → "Progress while the run is quiet" |
 | `pnpm josh release:scope` once, after the last issue has merged and the last lane is closed | `followup.md` → "When `pnpm josh release` runs" |
 

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

@@ -9,7 +9,7 @@ Review results and successful pushes are never turn boundaries.
    "<title> #<N>"` (`--cite <N>`), then **end the turn** on `launched`/`busy`. A stop relaunches a child
    whose prompt names `pnpm josh ship --log <N>` and (Anthropic lane, #2964) the re-detach to run after
    the fix — `pnpm josh ship --detach`, `--review` only if the stopped ship carried it and stopped before
-   round 2, which is final (`scripts/run/run-ship-next.ts`); the supervisor skips a recorded round 1.
+   round 2, which is final (`scripts/run/ship/run-ship-next.ts`); the supervisor skips a recorded round 1.
    `failed` → step 1. A backgrounded `ship` issued alone is moved to the foreground by the hook
    rather than refused (#3154).
 1. Run `pnpm josh main:merge`. **Then issue `pnpm josh run:cut <N>` alone, before the scoped pair and

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

@@ -17,13 +17,13 @@ pnpm josh delegate --list   # the enumeration, and what was rejected and why
 **how a wrong result is caught** cheaply in the parent tier, not merely by being unlikely to fail.
 `pnpm josh delegate --list` names both delegatable and rejected steps; a rejected step either has no
 verifier or lets a wrong result propagate too far. The command distinguishes `kept deliberately`
-from `kept by default`. `docs/josh-commands-automation.md` → "`josh delegate`" carries the full enumeration.
+from `kept by default`. `docs/josh-commands-backlog.md` → "`josh delegate`" carries the full enumeration.
 
 **The mechanism is not the unit.** `pnpm josh delegate` covers a run step, a file-disjoint Step 0
 implementation unit (`pnpm josh fanout`), and `epic-child` — an epic's child and a named issue of a
 `backlogrun` alike. Do not add a second batch-child mechanism. Read `backlogrun-child.md` → "Each child
 runs in a delegated unit" at child dispatch; `backlogrun-steps.md` → "Named issues run first, in order"
-applies to named issues. `docs/josh-commands-automation.md` → "`josh fanout`" carries file-disjoint dispatch.
+applies to named issues. `docs/josh-commands-backlog.md` → "`josh fanout`" carries file-disjoint dispatch.
 
 **`followup-filing` delegates the late review-finding filing chain** with the parent's finding text;
 the parent verifies the new Issue using `pnpm josh issue:state <new>`. For `epic-child`, the parent

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

@@ -24,6 +24,11 @@ review scan and the merge and runs only the post-merge tail; a completion report
 is not posted or notified twice, so re-running is safe. Keep the default Issue target. Ignore a
 finding only after verifying it is inapplicable; rate-limit text is not a finding.
 
+**A red rate-limited CodeRabbit check is cleared by a retrigger, not a bypass.** Wait out the window
+the rate-limit comment states, post `@coderabbitai review` on the pull request, and rerun `followup`.
+Bypassing the check is Tier C — only on explicit user instruction, and only when the stated window is
+impractically long or the retrigger is rate-limited again.
+
 A pre-merge failure stops the run; an unverifiable AI finding or CI failure needing input receives a
 `confirmation` Telegram. Post-merge cleanup failures are named and do not undo the merge; run the
 named recovery without rerunning it. Because notification precedes merge, the printed result is
@@ -150,3 +155,8 @@ the tag → publish → `production` chain — outward-facing and effectively ir
 Typing `fullrun` authorizes this Issue's merge and nothing past it; a person types the release in the
 primary checkout, on the default branch, with a clean tree. `release:scope` counts nothing of its own —
 it reads the same fetch-then-count `followup` uses for the Telegram line, so the two cannot disagree.
+
+**On `required`, the release request cites the open release Issue** — the one `issue:file --release` / `issue:release <N>` links blockers to — with a number-link
+(`prompts/collaboration-workflow/issue-citation.md`). List it with
+`gh api 'repos/{owner}/{repo}/issues?labels=release&state=open' --jq '.[].number'`; when none is
+open, the request names `pnpm josh release` alone.

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

@@ -55,7 +55,7 @@ that covers the same work stops the run rather than filing a second Issue (`issu
 `gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=in-progress'`. (4) Post the agreed plan
 in the session language: fill the body if blank,
 otherwise add a comment. (5) If the working tree already has staged or modified files,
-`git stash push -m "fullrun new: pre-existing changes" -- ':!docs/maintainers/observations'` first
+`git stash push -m "fullrun new: pre-existing changes" -- ':!.josh/observations'` first
 (joshuafolkken/kit#2919). (6) `git switch main && git pull`. (7)
 `pnpm josh latest:scope`; on `required` run `josh latest` and load the `dependency-update` skill; on
 `skip` neither runs (`latest-gate.md` is the single source). If you stashed in (5),

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

@@ -44,7 +44,7 @@ back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`,
 mirror `fullrun new` (1)–(8): derive an English title (or use the provided one) → create the Issue
 (`pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>`, body per
 `prompts/collaboration-workflow/issue-template.md`; its duplicate scan is read per `issue-scout.md`) → add `in-progress` (as `fullrun new` (3)) → post the agreed plan → stash
-any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes" -- ':!docs/maintainers/observations'`
+any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes" -- ':!.josh/observations'`
 (the pathspec keeps the observation ledger in the tree for this run's commit; joshuafolkken/kit#2919), popped by
 message with `pnpm josh stash:pop "halfrun new: pre-existing changes"`, never a positional `git stash pop` →
 `git switch main && git pull` → `pnpm josh latest:scope` → implement → run the gate (as above, `pnpm

package/.claude/skills/workflow-commands/issue-scout.md

@@ -41,4 +41,4 @@ pnpm josh issue:file "<title>" --body-file <complete-draft.md> --depth <n> --dis
 - **The split path files each child through the same command.** The epic is created with
   `pnpm josh epic` over children that were scanned.
 
-Full behavior: `docs/josh-commands-automation.md` → "`josh issue:file`" and "`josh issue:scout`".
+Full behavior: `docs/josh-commands-backlog.md` → "`josh issue:file`" and "`josh issue:scout`".

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

@@ -85,4 +85,5 @@ split is found.
   creation call. (3) Send Telegram notification listing all created issues. (4) Present the command
   `backlogrun #<E> --only`. (5) **Stop** — do not implement.
 
-`pnpm josh issue:file` lints the body and applies the classification labels it declares, following `prompts/collaboration-workflow/issue-template.md` for classification (`docs/josh-commands-automation.md` → `josh issue:file`).
+`pnpm josh issue:file` lints the body and applies the classification labels it declares, following `prompts/collaboration-workflow/issue-template.md` for classification (`docs/josh-commands-backlog.md` → `josh issue:file`).
+An Issue a consumer can use only once it is published is filed with `--release` (`kickoff new`), or linked with `pnpm josh issue:release <N>` (`kickoff #N`) — either makes it a blocker of the repository's `release` Issue, which never gets `auto-ok` on its own.

package/.claude/skills/workflow-commands/latest-gate.md

@@ -1,6 +1,6 @@
 # The dependency update — when `josh latest` runs
 
-`josh latest` updates corepack, every dependency, the published ranges and `pnpm audit`, in that
+`josh latest` updates every dependency, the published ranges, `pnpm audit` and pnpm, in that
 order and over the network. Until joshuafolkken/kit#1215 every entry point put it at the head of
 every run and called it **mandatory, never skip** — so a standalone `fullrun` paid 60–120 seconds
 for it before touching the issue, and a batch that ran ten children paid it ten times unless the

package/.claude/skills/workflow-commands/observation-ledger.md

@@ -11,7 +11,7 @@ second-sighting promotion.
 (joshuafolkken/kit#1728). Rationale: `docs/maintainers/observation-ledger-rationale.md` → "Why the
 ledger exists".
 
-- **The destination is the `docs/maintainers/observations/` directory in the repository the
+- **The destination is the `.josh/observations/` directory in the repository the
   observation is about** — the same repository the Issue would have been filed into — **one file per
   issue** (joshuafolkken/kit#2919): append to `<N>.md` for the issue the run is executing (the number
   its branch leads with, a lane's included), or to `<YYYY-MM-DD>.md` for a line written on the
@@ -70,7 +70,7 @@ wherever an exit status is being watched. **A missing directory is still a first
 complains on standard error and the count is zero; the append below creates the directory.
 
 ```bash
-cat <that repository's checkout>/docs/maintainers/observations/*.md | grep -c '^- k:<slug> |' || true
+cat <that repository's checkout>/.josh/observations/*.md | grep -c '^- k:<slug> |' || true
 ```
 
 Free-text comparison is what the key exists to replace, so two lines that read alike under different
@@ -87,7 +87,7 @@ could not.
 `docs/maintainers/observation-ledger-rationale.md` → "Why the ledger has a commit path".
 
 - **A run's appended lines ride its own commit** (joshuafolkken/kit#2763). `pnpm josh git` stages
-  `docs/maintainers/observations/` with the run's other changes, in the one staging step every entry
+  `.josh/observations/` with the run's other changes, in the one staging step every entry
   point goes through (`scripts/git/git-staging.ts`), so the lines are reviewed and merged with the
   pull request of the run that recorded them, and the run's CI is the only wait they cost.
   **Record before the commit, not after the merge:** a finding recorded with `pnpm josh review:record`

package/.claude/skills/workflow-commands/pre-gate-cut.md

@@ -190,13 +190,18 @@ the push is never a turn boundary (`chain-rule.md`).
 ## A lane child records its park before it stops
 
 **The trigger**: a dispatched lane child about to stop for a decision (a Tier B toss-up, a Tier C
-action, an upstream defect, a split) parks its own Issue first — `backlogrun-park.md` → "park and
+action, an upstream defect) parks its own Issue first — `backlogrun-park.md` → "park and
 continue" — so the parent's `pnpm josh run:liveness` reads it `settled` (joshuafolkken/kit#2034),
 after #2012 and #2011. A `needs-human-review` or `already-done` stop already carries its label.
 `pnpm josh rule:guard` refuses `pnpm josh notify --task-type confirmation` from a marked child until
 then — **It fires once per run.**, and a person's own `fullrun` is never refused
 (`scripts/rules/lane-park.ts`).
 
+**A split is not a park**: the parent reads an open Issue carrying `epic` as
+a split, so a child that promoted its Issue stops without `needs-decision` — `backlogrun-park.md` →
+"Splitting a child mid-run". `pnpm josh rule:guard` refuses a `needs-decision` write onto the epic
+the child promoted this run, on every occurrence (`scripts/rules/lane-split-park.ts`).
+
 ### The interactive ask is refused one call earlier
 
 **The trigger**: a headless session ends the turn on an interactive ask, so the notify guard never

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

@@ -18,7 +18,7 @@ another is the failure this section exists to prevent:
 | A defect originating in **another package**                                 | File the upstream Issue and **stop** — Tier A for a first-party target; a third-party one is Tier C, recorded and drafted rather than filed (`CLAUDE.md` → "Cross-package problems"; `prompts/collaboration-workflow/upstream-interrupt.md`) |
 | This Issue was really **several** (a split)                                 | File the children and the epic and **stop** — except under `backlogrun`, whose authorization already covers a batch, so the children are filed and run through (`split-assessment.md`) |
 | Another Issue in **this** repository has to land first (**a prerequisite**) | This section                                                                                                            |
-| Something worth filing that is **none of the three** (**an observation**)   | File it **without asking** — Tier A for a first-party target — and **carry the run straight on**: nothing is stashed, nothing is parked (`observation-filing.md`). **A delegated child does not file here**, and a filing at depth 1 or deeper cites the depth-0 work it blocked; one that cannot cite it goes to the run's own `docs/maintainers/observations/<N>.md` and is filed on its second sighting — all of them `observation-filing.md`'s |
+| Something worth filing that is **none of the three** (**an observation**)   | File it **without asking** — Tier A for a first-party target — and **carry the run straight on**: nothing is stashed, nothing is parked (`observation-filing.md`). **A delegated child does not file here**, and a filing at depth 1 or deeper cites the depth-0 work it blocked; one that cannot cite it goes to the run's own `.josh/observations/<N>.md` and is filed on its second sighting — all of them `observation-filing.md`'s |
 
 **File the prerequisite with the `route:tier-a` label**, so a Tier A filing made during implementation
 stays countable by filing route afterwards. **This paragraph belongs to the prerequisite row, not to
@@ -31,7 +31,7 @@ pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route tier-
 
 The command lints the body against `prompts/collaboration-workflow/issue-template.md`, applies the
 classification labels it declares, and runs the duplicate scan and `epic:bundle` itself
-(`docs/josh-commands-automation.md` → `josh issue:file`).
+(`docs/josh-commands-backlog.md` → `josh issue:file`).
 
 Every "file the prerequisite" below means that labelled filing, and it always happens **first**: the
 steps after it name a number that does not exist until it is. **Its duplicate scan is read exactly as

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

@@ -33,7 +33,7 @@ flight and the watcher's life record has gone stale — once per run, so the res
 
 **`--mark` at every real report.** Whenever the run reports something of its own, 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-automation.md` → "`josh run:progress`").
+never a timer (`docs/josh-commands-run.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`), though a single correctly-spaced arm is allowed.

package/.claude/skills/workflow-commands/working-tree-hold.md

@@ -65,7 +65,7 @@ or release once the work is done; only an expired record over a clean tree is re
 **The batch entry points claim per child, not per batch.** `backlogrun` never
 call it themselves; each child runs the `fullrun` procedure, so it claims on entry and `pnpm josh
 followup` releases it at that child's merge. The command's behavior and the answer table are
-`docs/josh-commands-automation.md` → "`josh run:hold` / `josh run:release`"; this file is the single source of
+`docs/josh-commands-run.md` → "`josh run:hold` / `josh run:release`"; this file is the single source of
 the procedure.
 
 ## The halfrun resume

package/.codex/hooks.json

@@ -2,11 +2,11 @@
 	"hooks": {
 		"SessionStart": [
 			{
-				"matcher": "",
+				"matcher": "startup",
 				"hooks": [
 					{
 						"type": "command",
-						"command": "pnpm josh audit:provision",
+						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u GIT_WORK_TREE git rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel)\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision",
 						"timeout": 180
 					}
 				]