@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/.claude/settings.json

@@ -54,7 +54,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision",
 						"timeout": 180
 					}
 				]
@@ -66,7 +66,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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 session-lang",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh session-lang",
 						"timeout": 10
 					}
 				]
@@ -74,11 +74,11 @@
 		],
 		"PreToolUse": [
 			{
-				"matcher": "Bash|Edit|Read|Write|AskUserQuestion",
+				"matcher": "Bash|Edit|Read|Write|AskUserQuestion|Agent|Task",
 				"hooks": [
 					{
 						"type": "command",
-						"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 pretool-guard",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh pretool-guard",
 						"timeout": 20
 					}
 				]
@@ -90,7 +90,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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 format-edited",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh format-edited",
 						"timeout": 90
 					}
 				]
@@ -102,7 +102,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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 stop-guard",
+						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh stop-guard",
 						"timeout": 20
 					}
 				]

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

@@ -5,76 +5,47 @@ description: Checks after `pnpm update`, `josh latest`, `josh adopt`, `pnpm josh
 
 # After a dependency-update command
 
-`CLAUDE.md` → "Decision autonomy" keeps both prohibitions resident as Tier C — never touch `overrides`
-in either file, never touch `devEngines`, without explicit user approval. This skill is the other
-half: what you actually run to find out whether a command already touched them, and how to read the
-one change that is expected. It applies after `pnpm update`, `josh latest`, `josh adopt` (which runs
-`josh latest` as one of its steps), `pnpm josh overrides`, a Dependabot merge, or any other command
-that can rewrite dependency versions.
-
-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).
+`CLAUDE.md` → "Decision autonomy" keeps both prohibitions resident as Tier C: never touch `overrides`,
+never touch `devEngines`, without explicit user approval. This skill is the single source of how to check
+whether a command touched them, after `pnpm update`, `josh latest`, `josh adopt` (which runs
+`josh latest`), `pnpm josh overrides`, a Dependabot merge, or any command that rewrites dependency
+versions. Overrides exist on purpose (e.g. `"esbuild@<=0.24.2": ">=0.25.0"` for Workers builds).
 
 ## 1. Effective overrides live in the workspace — inspect both files
 
-**pnpm 11 and 12 read effective overrides only from `pnpm-workspace.yaml`.** The old
-`pnpm.overrides` field in **`package.json` is ignored**, as verified with pnpm 12.6.0. Inspect both
-files to preserve any existing declarations, but do not count the package field as an effective
-override. An absent or empty package field says nothing about workspace overrides: app-kit's
-`package.json` has no `pnpm` field, while its workspace has a real override.
+**pnpm 11 and 12 read effective overrides only from `pnpm-workspace.yaml`.** `pnpm.overrides` in
+**`package.json` is ignored** (verified with pnpm 12.6.0). Inspect both to preserve existing
+declarations, but an absent package field says nothing about workspace overrides.
 
 ## 2. The check is a command you run, not a conclusion you reach
 
-**The check is a command you run, not a conclusion you reach.** After `pnpm update`, `josh latest`,
-or any dependency-update command, verify the overrides in both `pnpm-workspace.yaml` and
-`package.json` by running
-
 ```bash
 git diff -- pnpm-workspace.yaml package.json
 ```
 
-(after `josh adopt`, which has already committed and returned to the default branch, compare the
-pull-request branch instead: `git diff <default>...<branch> -- 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, investigate why it changed, and report that to the user — never
-keep the change without explicit approval.
+(after `josh adopt`, which has already committed and returned to the default branch:
+`git diff <default>...<branch> -- pnpm-workspace.yaml package.json`). Confirm both overrides blocks
+are untouched **and** `devDependencies` still respect the effective overrides. A removed, modified or
+over-bumped entry: restore it immediately, investigate, and report — never keep it without 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
-entries against a saved snapshot and reports ignored package entries — **quote what one printed.**
+`josh latest` prints its verdict as its last overrides line (`✔ overrides unchanged (<n> from
+<file>)` or `⚠ overrides changed`); `pnpm josh overrides` compares against a saved snapshot —
+**quote what one printed.**
 
 ## 3. `devEngines` — the one expected change
 
-Verify `devEngines` was not changed **outside the legitimate `josh latest` pnpm bump**. If it changed
-in any other way, restore it immediately and ask the user before making any change.
-
-**Exception — the `josh latest` lockstep pnpm bump is expected, NOT a violation.** `josh latest`
-deliberately bumps `devEngines.packageManager.version` in lockstep with the top-level
-`packageManager` pin (see `scripts/version/latest-corepack.ts` → `sync_development_engines`); the two
-MUST stay exactly equal — **byte-identical, `+sha512…` Corepack integrity suffix included**. pnpm
-compares them as raw strings, so a bare `11.18.0` paired with `pnpm@11.18.0+sha512…` is a mismatch
-and the dual-declaration warning fires; only a character-for-character match suppresses it.
-
-So after `josh latest`, **KEEP** a `devEngines.packageManager.version` change **if and only if** it
-now equals everything after `pnpm@` in the new `packageManager` pin (same version string **and** same
-integrity suffix; only the `version` field moved). Reverting it would both undo a valid toolchain
-update **and** re-introduce a `packageManager`/`devEngines` mismatch — the opposite of the rule's
-intent.
+**Exception — the `josh latest` lockstep pnpm bump is expected, NOT a violation.** **KEEP** a
+`devEngines.packageManager.version` change **if and only if** it equals everything after `pnpm@` in
+the new `packageManager` pin — **byte-identical, `+sha512…` Corepack integrity suffix included**
+(`scripts/version/latest-corepack.ts` → `sync_development_engines`). Reverting it would re-introduce
+the mismatch.
 
-**Restore + ask only** when `devEngines` changed in some OTHER way: its version no longer matches
-`packageManager` (a dropped, stale, or truncated integrity suffix counts as a mismatch), its
-structure changed (`name` / `onFail` / fields added or removed), or it was touched by something other
-than `josh latest`. The one structural change that is expected is `josh sync` moving
-`devEngines.packageManager.onFail` from `"error"` to `"download"` — a user-approved migration that
-leaves `name` and `version` untouched; keep it.
+**Restore + ask** when `devEngines` changed any other way: the version no longer matches
+`packageManager` (a dropped or truncated suffix counts), its structure changed (`name` / `onFail` /
+fields), or something other than `josh latest` touched it. One structural change is expected and
+kept: `josh sync` moving `devEngines.packageManager.onFail` from `"error"` to `"download"`.
 
 ## 4. When the bump breaks something — fix forward
 
-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.
+Single source: `prompts/collaboration-workflow/principles.md` → "latest-first". Fix-forward never
+authorizes a silent edit to a protected pin; sections 1–3 still apply.

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

@@ -5,10 +5,6 @@ description: Procedures for `josh epic:audit`, `epic:next` and `epic:bundle`. Re
 
 # 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. **This skill is their single source**; where each rule came from is
-`docs/maintainers/epic-commands-rationale.md` → "Where each rule came from".
-
 The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `prrun`, `backlogrun` — live in the
 `workflow-commands` skill.
 
@@ -19,27 +15,23 @@ epic:audit → find contradictions across the children, and fix what it finds (T
 backlogrun → which calls epic:next each round
 ```
 
-Front-loading every `needs-decision` in one pass is `backlogrun`'s job, not a command of this skill:
-`backlogrun-steps.md` → "Resolve what the plan can resolve, before starting". A `backlogrun #E --only`'s
-pre-check is `epic:audit`.
+Front-loading every `needs-decision` is `backlogrun`'s job: `backlogrun-steps.md` → "Resolve what
+the plan can resolve, before starting". A `backlogrun #E --only`'s pre-check is `epic:audit`.
 
-**Two references are read only when their case arises**: `execution-waves.md` when an epic's children
-need an order between groups (a wave boundary, or one child that must run alone), and
-`epic-bundle.md` when a filing's `epic:bundle` answer places the issue.
+Read `execution-waves.md` only when children need an order between groups (a wave boundary, or a child
+that must run alone), and `epic-bundle.md` only when a filing's `epic:bundle` answer places the issue.
 
 ## Recording a decision
 
-**A decision is recorded in two places, and one without the other loses half of it.** The epic's
-`## Decisions` log carries the decision; a comment on each child it applies to carries the reasoning
-for that child's reader. **Recording a decision removes that child's `needs-decision` label** (Tier A);
-the label-clearing rule itself is `backlogrun-park.md` → "park and continue".
+Record it in both places: the epic's `## Decisions` log, and a comment on each child it applies to.
+Recording a decision removes that child's `needs-decision` label (Tier A; `backlogrun-park.md` →
+"park and continue").
 
-- **A decision taken *as* a child joins the epic** goes through `pnpm josh epic --add … --decision-file`
-  — `epic-bundle.md` is that flag's single source, and it writes both halves at once.
-- **A decision about a child the epic already tracks** cannot use that flag: an insertion with nothing
-  to add is refused outright. Until an entry point for already-tracked children exists, write the
-  child comments with `pnpm josh issue:comment <N> --body-file <path>` on each child the answer
-  applies to, and **say in the report that the epic's `## Decisions` entry is still pending**.
+- **Decided as a child joins the epic**: `pnpm josh epic --add … --decision-file` writes both
+  (`epic-bundle.md`).
+- **About a child the epic already tracks**: that flag refuses an insertion with nothing to add.
+  Comment on each child with `pnpm josh issue:comment <N> --body-file <path>`, and **say in the report
+  that the epic's `## Decisions` entry is still pending**.
 
 ```md
 ## Decisions
@@ -55,8 +47,8 @@ the label-clearing rule itself is `backlogrun-park.md` → "park and continue".
 
 ## Creating an epic
 
-A split into two or more issues always gets an epic (`prompts/collaboration-workflow/issue-template.md`).
-Create it with the command, never by hand-writing the body:
+A split into two or more issues always gets an epic (`prompts/collaboration-workflow/issue-template.md`),
+created with the command, never by hand:
 
 ```bash
 pnpm josh epic "<epic-title>" <N1> <N2> ...            # order-free batch
@@ -64,105 +56,68 @@ pnpm josh epic "<epic-title>" <N1> <N2> ... --ordered  # argument order is the d
 # --rationale-file <path|-> fills Split rationale; --origin <owner/repo#N> adds the backlink
 ```
 
-The body format is the command's output, and `pnpm josh epic:check <E>` answers whether a body still
-meets it (the parser auto-close reads; exit 1 on a miss) — run it after any hand edit. `pnpm josh
-followup` closes the epic once every task-list child is closed; one tracking a cross-repository child
-is closed by hand. The by-hand fallback where `josh` is unavailable: `issue-template.md`; the format's
-reasons and the history: `docs/maintainers/epic-commands-rationale.md` → "Creating an epic by hand".
+After any hand edit run `pnpm josh epic:check <E>` (exit 1 when the body no longer parses).
+`pnpm josh followup` closes the epic once every task-list child is closed; one tracking a
+cross-repository child is closed by hand. Without `josh`: `issue-template.md`.
 
 ## `josh epic:audit <E>` — contradictions across the children
 
-`epic:check` verifies one epic's *format*; this verifies that the children agree.
-
-Run it **without being asked**: when a `backlogrun` starts a named epic's children, and right
-after a child is added or a dependency changed.
-
-The cycle and declaration-mismatch checks are `epic:next`'s, reused rather than re-derived. What this
-adds is reading *inside* the children:
+`epic:check` verifies the format; this verifies the children agree. Run it **without being asked**
+when a `backlogrun` starts a named epic's children, and right after a child is added or a dependency
+changed. Cycle and declaration checks are reused from `epic:next`; it adds:
 
 | Check | Level |
 | --- | --- |
 | A child's body names another child, nothing orders the two | warning |
-| A child's **acceptance criteria** name another child, nothing orders the two | **error**; a warning once both children are closed, and a warning when the pair is in two repositories. A warning there does **not** mean the pair is safe: the child is still offered as runnable, and recording the relation is what clears it |
+| A child's **acceptance criteria** name another child, nothing orders the two | **error**; a warning once both are closed or when the pair spans two repositories — the child is still offered as runnable until the relation is recorded |
 | A body cites a missing or already-closed issue | warning |
-| A task-list row points at another **epic** | warning — `epic:next` withholds the row, so the batch is already safe; what is left is a thing a person has to look at |
+| A task-list row points at another **epic** | warning — `epic:next` already withholds the row; a person should look |
 | An issue names this epic as parent that the task list does not track | warning |
 | 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** (exit 1); a warning leaves the exit code alone and is for the reader to judge
-— the first check fires on a legitimate forward reference as readily as on a missing dependency. A
-forward reference the other child *already depends on* is not reported at all.
-
-**A pair with either child closed is a warning, not an error**, and **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.
+**Only errors fail it** (exit 1). A forward reference the other child already depends on is not
+reported. A pair is demoted to a warning only when the closed state is **confirmed** (any state but
+`CLOSED` normalizes to `OPEN`).
 
-**Fixing what it finds is Tier A** — re-pointing a dependency or correcting prose is reversible and
-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.
+**Fixing what it finds is Tier A** — fix it and record why on the issue. Park with `needs-decision`
+only for 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:
+The two `orphan search` findings are about the search, not the children:
 
-- `✖ orphan search: Could not list the open issues…` — the search never ran, so "no orphans" would
-  be a claim about a listing that never arrived. It fails the audit, which stops the epic's run at its
-  step 0. **Re-run the audit**; that is the whole response. There is nothing to fix and nothing to
-  decide, so neither Tier A nor a `needs-decision` park applies. If it keeps failing, check
-  `gh auth status` and whether the rate limit has reset.
-- `⚠ orphan search: The open-issue scan hit its …` — the search covered only the newest part of the
-  backlog (500 issues, or 50 bodies mentioning the epic). It ran, so the audit passes; read the line,
-  and look further down the backlog by hand if an orphan is expected there.
+- `✖ orphan search: Could not list the open issues…` — **re-run the audit**; nothing to fix or decide.
+  If it keeps failing, check `gh auth status` and the rate limit.
+- `⚠ orphan search: The open-issue scan hit its …` — only the newest 500 issues (or 50 bodies) were
+  covered; the audit passes. Look further by hand if an orphan is expected.
 
-**One thing it cannot check** belongs to planning: when a child introduces a new label, command,
-state or artifact, list the existing code referencing that concept and confirm some child owns
-updating it. Label names are single-sourced in `scripts/issue/issue-labels.ts`.
-
-History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why the children are read across".
+**It cannot check** that when a child introduces a new label, command, state or artifact, some child
+owns updating the existing code referencing that concept — do that at planning. Label names live in
+`scripts/issue/issue-labels.ts`.
 
 ## `josh epic:next <E…>` — what is runnable
 
-Returns **every** runnable child, bundled per repository with the local checkout to run it in.
-`--repo <owner/repo>` narrows to one and prints a single token: the issue number, or the verdict.
-`--lanes` beside it prints one issue number per line instead, **up to the number of free lanes in
-that repository** — so a caller that reads one token keeps reading one token.
-
-**It takes more than one epic, and they answer as one.** Every leading argument is an epic
-reference — the split is on the first flag, so `epic:next 858 909 --repo X --lanes` reads two — and
-their runnable children merge into one candidate pool per repository, so six free lanes fill from
-every named epic rather than from whichever was typed first. **The priority order is the order the
-epics were named.** **Inside one epic the order is that epic's own task list**: its declared chain
-still decides which children are *runnable*, and among those, the order the task list names them is
-the order they are offered — so an epic says "do this one first" by moving the row, not by declaring
-a chain, which would stop every child behind a stuck one.
-**`pnpm josh epic --add <E> <N> --order-before <M>` is what moves that row**: the row goes where the
-flag names, and the declaration and the `blocked-by` relations are left exactly as they stood — so
-"moving the row" is a command rather than the hand edit `epic --add` exists to prevent.
-`--order-after <M>` is its other direction, and both work on a child the epic already tracks, which
-is a pure reorder. **A child a chain still holds is not freed by moving its row**: `epic:next`
-filters by `blocked-by` before it applies task-list order, so the command prints a ⚠️ line naming
-that child rather than reporting a reordering nothing can observe. **A child two epics both track
-enters once**, keyed by `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-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 — and
-what is left of `JOSH_LANE_LIMIT` (**default 4**) is what gets offered. At zero the answer is `wait`
-and the holders are named on standard error. A parked child releases its lane; one stopped by
-`needs-human-review` goes on holding one, because its uncommitted work is still in that checkout.
-
-**A child that is itself an epic is never offered** — an epic is not a unit of work. It waits on a
-*person*, because no amount of waiting turns an epic into work. **The test is the child's `epic`
-label, never how its task-list row is written**: a row naming `owner/repo#N` is a different property
-and a legitimate one — it disables the epic auto-close by design, which is why a cross-repository
-backlink is prose rather than a row — so a cross-repository child that is not an epic stays
-runnable, and one that is an epic is withheld exactly like a local one. **A parent epic over another
-epic never auto-closes**: the auto-close evaluates only the epics whose own task list holds the issue
-a merge just closed, and a grandchild merging never reaches the grandparent. `epic:audit` reports the
-same row, with that consequence in the finding.
+Returns **every** runnable child, bundled per repository with its local checkout. `--repo <owner/repo>`
+narrows to one and prints a single token (an issue number or the verdict); `--lanes` beside it prints
+one number per line, **up to the number of free lanes in that repository**.
+
+- **Several epics answer as one**: every argument before the first flag is an epic; their runnable
+  children merge into one pool per repository. **Priority is the order the epics were named**, then
+  each epic's own task-list order (its declared chain still decides what is runnable).
+- **Reorder with `pnpm josh epic --add <E> <N> --order-before <M>`** (or `--order-after <M>`), never a
+  hand edit; declarations and `blocked-by` relations stay as they were. Moving a row does not free a
+  child a chain still holds — the command prints a ⚠️ line instead.
+- **A child two epics track enters once**, kept by the epic named earlier.
+- **One unusable graph refuses the whole answer**; **one reference that does not parse fails the
+  read**. Worked form: `docs/josh-commands-backlog.md` → "`josh epic:next`".
+
+**An `in-progress` issue occupies a lane, not the repository.** Free lanes are `JOSH_LANE_LIMIT`
+(**default 4**) minus that repository's `in-progress` listing. At zero the answer is `wait`, with the
+holders on standard error. A parked child releases its lane; a `needs-human-review` stop keeps it.
+
+**A child that is itself an epic is never offered** and waits on a *person*. The test is the child's
+`epic` label, never how its row is written: a cross-repository `owner/repo#N` row that is not an epic
+stays runnable. **A parent epic over another epic never auto-closes** (a grandchild's merge never
+reaches it); `epic:audit` reports the row.
 
 Children that are not runnable are sorted by **whether waiting helps**, never by label:
 
@@ -172,62 +127,40 @@ Children that are not runnable are sorted by **whether waiting helps**, never by
 | Waiting on time | Wait and ask again |
 | Waiting on a person | Stop and report |
 
-**A blocker outside every named epic is weighed, not ignored.** Closed, it resolves (a
-cross-repository one still waits for its release); open and tracked by any epic named in the same
-call, the child waits on time unless that blocker itself waits on a person, which the child
-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 <E1>
-<E2>`, or `backlog:next`, whose set is the whole opted-in backlog. The table is
-`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`
-recorded them, a recording that failed, or a relation hand-added since). Only a line that is
-*nothing but* a chain counts as a declaration — a prose line recommending an execution order is a suggestion, not a dependency.
+**A blocker outside every named epic is weighed**: closed, it resolves (cross-repository: after its
+release); open and tracked by an epic named in the same call, the child waits on time (or on a person,
+if the blocker does); open and untracked, the child waits on a person and the blocker is named on
+standard error; an unknown state reads as waiting. **Order two epics with a native `blocked-by`
+relation and name both** — `epic:next <E1> <E2>`, or `backlog:next`.
 
-Why it orders and counts as it does: `docs/maintainers/epic-commands-rationale.md` → "`epic:next` — why it answers as it does".
+Two things stop the command: a **circular dependency**, and a **disagreement between the epic body
+and the `blocked-by` relations**. Only a line that is *nothing but* a chain is a declaration — a prose
+line recommending an execution order is a suggestion, not a dependency.
 
 ## Epics that span repositories
 
-Write cross-repository children in the task list as `owner/repo#N` or a full issue URL. Their state
-is read against that repository through `gh api`, so **no local clone is needed to learn it** — only
-to implement.
+Write cross-repository children as `owner/repo#N` or a full issue URL. Their state is read through
+`gh api`, so **no local clone is needed to learn it** — only to implement.
 
-- **The owner restriction is inherited unchanged**: a repository with a different owner is never a
-  target, by any route.
-- **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
+- **The owner restriction is inherited unchanged**: a different owner is never a target.
+- **The epic auto-closes only when every cross-repository child's state could be read.**
+- **An epic in another repository is referenced as `owner/repo#N`** — `backlogrun
   joshuafolkken/kit#<E> --only`, `epic:next joshuafolkken/kit#<E> --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 the repository discovery
-  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. It resolves only when the blocker is closed **and** the version its default branch
-declares has appeared in the registry.
-
-**Unless that repository publishes nothing.** A repository with no `package.json` on its default
-branch, or one declaring `private`, ships no release for the check to wait on, so a closed blocker
-there resolves. 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"). 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 child no longer bumps the version**: the version moves only
-when `pnpm josh release` runs, so the target is the release that includes the blocker, not the
-default branch's version just after its merge (the previous release). The publish check shares
-`josh propagate`'s implementation; it is not defined twice. History:
-`docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
+  bare `#N` is this repository's issue.
+- **`epic:next` prints each candidate's local checkout**; none prints `(no local checkout)` and is
+  **never cloned on its own**.
+
+**A cross-repository dependency resolves only when the blocker is closed and the version its default
+branch declares is in the registry** (checked in that order; that exact version). A child no longer
+bumps the version, so the target is the release that includes the blocker. **Unless that repository
+publishes nothing**: no `package.json` on its default branch, or `private`, resolves on close — read
+from its manifest, never the registry; a failed manifest read (not a 404) still waits. The publish
+check is `josh propagate`'s.
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
-It runs right after an issue is filed: by `kickoff` / `fullrun` / `halfrun`, or by any Tier A filing
-mid-implementation, including inside a `backlogrun`. **`pnpm josh issue:file` runs it as its last step**;
-run it by hand only when that step printed `⚠`. **It recommends; it writes nothing.**
+Runs right after any filing; **`pnpm josh issue:file` runs it as its last step** — run it by hand only
+when that step printed `⚠`. **It recommends; it writes nothing.**
 
 | Candidates | Do | Tier |
 | --- | --- | --- |
@@ -239,10 +172,4 @@ run it by hand only when that step printed `⚠`. **It recommends; it writes not
 | No strong signal | Nothing | — |
 | **The epic listing was cut short** | **Nothing** — every placing row above is withheld | — |
 
-**A placing answer is acted on with `epic-bundle.md`** — what counts as a signal, the cut listing,
-choosing between epics, and the `--decision-file` record that pays for the choice. `Nothing to
-bundle.` needs no further read.
-
-History: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why issues filed apart are bundled afterwards";
-the reasons behind `epic-bundle.md`: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why each answer reads as it does";
-behind `execution-waves.md`: `docs/maintainers/epic-commands-rationale.md` → "Execution waves — why a wave is not a mechanism".
+**A placing answer is acted on with `epic-bundle.md`**. `Nothing to bundle.` needs no further read.