@joshuafolkken/kit 1.1453.0 → 1.1471.0

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,9 +5,8 @@ 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".
+This skill is the single source for the three commands. Reasons: `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 +18,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 +50,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 +59,71 @@ 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`; the format's history:
+`docs/maintainers/epic-commands-rationale.md` → "Creating an epic by hand".
 
 ## `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.
+**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`).
 
-**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.
+**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.
 
-**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.
+The two `orphan search` findings are about the search, not the children:
 
-**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:
+- `✖ 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.
 
-- `✖ 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.
-
-**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`.
+**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`.
 
 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.
-`--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 +133,42 @@ 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`".
+**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`.
 
-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.
+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.
 
-Why it orders and counts as it does: `docs/maintainers/epic-commands-rationale.md` → "`epic:next` — why it answers as it does".
+Why: `docs/maintainers/epic-commands-rationale.md` → "`epic:next` — why it answers as it does".
 
 ## 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. History: `docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
 
 ## `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,9 +180,7 @@ 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.
+**A placing answer is acted on with `epic-bundle.md`**. `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";

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

@@ -1,44 +1,30 @@
 # `epic:bundle` — the detail behind the answer
 
-**Read this when a filing's `epic:bundle` answer places the issue** — `add_to_epic`, `create_epic`,
-or a choice between epics — or when the answer is one the summary in the `epic-commands` skill
-(`SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with one already filed?") does not
-settle. `Nothing to bundle.` needs neither.
+Read this when a filing's `epic:bundle` answer places the issue (`add_to_epic`, `create_epic`, or a
+choice between epics), or when `SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with
+one already filed?" does not settle it. `Nothing to bundle.` needs neither. Reasons:
+`docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why each answer reads as it does".
 
 **Only two things count as a signal**: the issues referring to each other in prose, or a `blocked-by`
-already recorded between them. **A similar title never counts on its own** — "related" expands
-without limit, and the threshold is what keeps an unrelated issue out.
-
-**The release issue is neither a candidate nor a subject**, like an epic. `issue:file --release` records
-every change awaiting publication as its blocker, so that relation is mechanical, not a sign of shared
-work. Counted as a signal, it would put the release and an unrelated change in one epic. A
-`blocked-by` or a prose reference between any other two issues still counts.
-
-**The search is not limited to the open backlog.** Every issue number the subject's body names is read
-on its own, whatever its state. A **closed** reference counts only when an open epic already tracks
-it, since the answer worth recovering is `add_to_epic`; an epic created over a closed issue has
-nothing left to run. An **open** reference counts either way. A read that fails — and a reference the
-per-issue cap never reached — is reported as a gap, never folded into "no strong signal". A number
-that answers with a **pull request** is not a candidate at all: `repos/{owner}/{repo}/issues/<N>`
-serves one too, and a merged PR does not report `CLOSED`.
-
-**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. **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. The referenced-number reads are capped at twenty, and **only
-the subject's own body is followed**.
-
-**`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.**
-"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 children invisibly.
-**`add_to_epic` rests on it as much as `create_epic` does**: adding the issue to the epic a
-*candidate* sits in, while an unseen epic already tracks the issue itself, is the same duplicate by
-another route. The verdict says so itself:
+already recorded between them. **A similar title never counts on its own.**
+
+**The release issue is neither a candidate nor a subject**, like an epic — its `blocked-by` relations
+are mechanical. Any other `blocked-by` or prose reference still counts.
+
+**The search is not limited to the open backlog.** Every number the subject's own body names is read
+(capped at twenty), whatever its state:
+
+- A **closed** reference counts only when an open epic already tracks it; an **open** one counts either way.
+- A **pull request** number is not a candidate.
+- A failed read, or a reference past the cap, is reported as a gap — never folded into "no strong signal".
+- **A number that does not exist is not a gap** — dropped in silence. Told apart **by HTTP status,
+  never by `gh`'s wording**: 404 is nothing there; 403 and 429 are a rate limit.
+
+**`none` is a legitimate answer** — the issue stays in the backlog. The review-cap follow-up's filing:
+`prompts/review.md` → "Three-way disposition after the cap".
+
+**A cut epic listing withholds every placing row**, `add_to_epic` as much as `create_epic` — an unseen
+epic may already track the issue. The verdict says so, and the exit code stays `0`:
 
 ```text
 Could not confirm which epic already tracks these — do not place this issue in one.
@@ -46,50 +32,32 @@ Could not confirm which epic already tracks these — do not place this issue in
   Related: #<N>
 ```
 
-**The children and the order are deliberately absent** — they are the recipe for the placement that
-line says not to make. The exit code stays `0`, as it does for every other "do nothing" answer. **What
-survives the cut is a membership that *was* found**: the table's first row names the epic it read
-tracking the issue, and epics past the cut cannot unseat it.
+It prints no children or order. What survives the cut is a membership that *was* found (the table's
+first row).
 
-**Placing an issue is not merging epics.** Bundling is reversible — one `epic --add` moves an issue
-to a different epic — so choosing between two candidate epics is Tier A: take the one you recommend,
-and write the decision (what was taken, what was rejected, why, and the date) on **both** the issue
-and the epic's `## Decisions`. **Merging two epics is a different action, and nothing here proposes
-it.**
+**Placing an issue is not merging epics.** Choosing between two candidate epics is Tier A: take the one
+you recommend and write the decision (taken, rejected, why, date) on **both** the issue and the epic's
+`## Decisions`. **Merging two epics is a different action, and nothing here proposes it.**
 
-**An epic and its own parent do not produce the spread verdict at all.** The parent already contains
-the child, so the pair is narrowed to the inner epic and the issue is added there. **The narrowing
-drops parents, never peers**: one unrelated epic beside a nested chain still asks, and so does a
-cyclic declaration, where there is no inner epic to pick. Stop only where the epics left are
-genuinely too close to separate, which is the toss-up Tier B is for and is rare.
-
-**The decision record is what pays for the autonomy** — without it the run has taken a decision
-nobody can find afterwards.
+**An epic and its own parent do not produce the spread verdict** — the issue goes to the inner epic.
+**The narrowing drops parents, never peers**: an unrelated epic beside a nested chain, or a cyclic
+declaration, still asks. Stop (Tier B) only where the epics left are genuinely too close to separate.
 
 **Write both halves in the one call that places the issue: `pnpm josh epic --add <E> <N...>
---decision-file <path|->`.** It appends the record to the epic's `## Decisions` inside the body edit
-the insertion already makes, and posts the same text as a comment on each child added. **Never
-hand-edit the epic body to add the entry** — that is the operation `--add` exists to remove. Two
-constraints on the record's own text, both refused before anything is written:
-
-- **No line that is *nothing but* a `#A -> #B` chain.** Such a line is read as part of the epic's
-  declaration wherever it sits in the body, so the record would declare an order nobody decided. Quote
-  the order inside backticks, or put it in a fenced block; either is accepted.
-- **The record must say something, and the path must be readable.** An empty file is refused, and so is
-  `--decision-file` with no usable path — otherwise the insertion lands, no record is written anywhere,
-  and the command still exits 0.
-
-Answers about children the epic already tracks cannot use this flag; `SKILL.md` → "Recording a
-decision" says what to do instead.
-
-**Its sibling runs before the filing, not after it: `pnpm josh issue:scout "<title>"`.** That command
-answers the same epic question for an issue that does not exist yet — this decision, called rather
-than restated — and beside it the one thing this one deliberately refuses: whether the work has
-already been filed, from a title comparison. **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:
+--decision-file <path|->`.** It appends to the epic's `## Decisions` and comments the same text on
+each child added. **Never hand-edit the epic body to add the entry.** Refused before anything is
+written:
+
+- **A line that is *nothing but* a `#A -> #B` chain** — it would be read as a declaration. Quote the
+  order in backticks or a fenced block.
+- **An empty record, or `--decision-file` with no usable path.**
+
+For children the epic already tracks: `SKILL.md` → "Recording a decision".
+
+**Its sibling runs before the filing: `pnpm josh issue:scout "<title>"`** — the same epic question for
+an issue not yet filed, plus whether the work is already filed. **Both run**: `pnpm josh issue:file`
+runs the scout before creating the issue and `epic:bundle` after. 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
-not. An order **nobody declared is not invented**.
+on an addition as much as on a new epic. An order **nobody declared is not invented**.