@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,463 @@
+---
+name: epic-commands
+description: The procedures for the `josh epic:*` commands that make an epic runnable without a person watching — `epic:audit` (find contradictions across the children), `epic:next` (what is runnable, per repository), and `epic:bundle` (does a newly filed issue belong with one already in the backlog). Also how an epic spans repositories and why a cross-repository dependency waits for a publish. Read this before running any of those commands, before writing an epic that tracks a child in another repository, and right after filing an issue.
+---
+
+# The `josh epic:*` commands
+
+These three commands are what turn an epic from a list of issue numbers into something a run can
+execute unattended. The canonical extended reference is `prompts/collaboration-workflow/` — `epic-bundle.md`, `epic-audit.md` and `cross-repo-epic.md` between them; this
+skill is the operational procedure, and the two must agree.
+
+The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `backlogrun` — live in the
+`workflow-commands` skill.
+
+## The order they run in
+
+```
+epic:audit → find contradictions across the children, and fix what it finds (Tier A)
+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 the decisions — now `backlogrun`'s
+
+`epic:plan` once printed every child as one JSON document so a person could answer every
+`needs-decision` in one batch before the run started. That front-loading is retired as a command of
+its own (joshuafolkken/kit#1965): **`backlogrun` does it at the start of every run**, and
+`backlogrun-steps.md` → "Resolve what the plan can resolve, before starting" is its single source. A
+`backlogrun #E --only`'s only pre-check is `epic:audit` below, run without being asked.
+
+**A decision is still 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".
+
+- **A decision taken *as* a child joins the epic** goes through `pnpm josh epic --add … --decision-file`
+  — the `epic:bundle` section below 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 joshuafolkken/kit#1162 adds an entry point for already-tracked
+  children, 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** — the
+  entry going unwritten is how two of the four most recent placements in joshuafolkken/kit#1262 ended
+  up with a child comment and nothing on the epic.
+
+```md
+## Decisions
+
+### <the point that was decided>
+
+- 対象: #101, #102
+- 採用: <the option taken>
+- 却下: <the option rejected>
+- 理由: <why the taken option is clearly better>
+- 決定日: <YYYY-MM-DD>
+```
+
+## `josh epic:audit <E>` — contradictions across the children
+
+`epic:check` verifies one epic's *format*. Nothing verified that the children agree, and a hand audit
+of a real epic found two contradictions that would have stalled the implementation while
+`epic:check` reported every requirement as passing.
+
+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:
+
+| 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 (joshuafolkken/kit#1128 — such an order only became recordable with joshuafolkken/kit#1126, so an error would stop every epic written before it). 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 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 (joshuafolkken/kit#1476) |
+| 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.** The first check fires on a legitimate forward reference as readily as on a
+real missing dependency; failing on both would make design notes unwritable. A forward reference the
+other child *already depends on* is not reported at all.
+
+**A pair with either child closed is a warning, not an error.** What makes an undeclared order a
+contradiction is that the criteria's child *can run first*, and one end closing is enough to make
+that false: a closed naming child has already run, and a closed named child has already delivered
+what the criteria ask for — so an epic that once forgot to declare an order would otherwise fail its
+audit forever, which stops every future run of that epic at the first step. It is demoted rather than
+dropped because dropping it hands the same pair to the first check, which reports it as an implicit
+dependency instead: the same one line, minus the detail that the name is in the acceptance criteria
+(joshuafolkken/kit#1010, widened from both-closed to either-closed by joshuafolkken/kit#1597 after a
+closed child citing an open sibling **as evidence** held an epic red at step one).
+
+**Fixing what it finds is Tier A** — re-pointing a dependency or correcting prose is reversible and
+will otherwise stall the work. Park with `needs-decision` only when the contradiction is a design
+choice nobody has made.
+
+**The two `orphan search` findings are the exception, because neither is a contradiction.** They are
+about the search itself rather than about anything the children say (joshuafolkken/kit#1033):
+
+- `✖ 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/git/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
+(joshuafolkken/kit#1491).
+
+**It takes more than one epic, and they answer as one** (joshuafolkken/kit#1493). 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**: dependency
+depth does not compare across graphs, since depth is measured inside one epic and there is no
+relation between two epics to normalize against, while argument order is the one ranking a person
+typed and can change. **Inside one epic the order is that epic's own task list**
+(joshuafolkken/kit#1583): 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. It was the lowest issue number until then, on the premise that number order is split order —
+false for any epic that gains children as work is found.
+**`pnpm josh epic --add <E> <N> --order-before <M>` is what moves that row**
+(joshuafolkken/kit#1738): 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.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
+two sessions counting to the limit in their own memory would double it — and what is left of
+`JOSH_LANE_LIMIT` (**default 6**) 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. It is an advisory guard
+rather than a mutex: the label is applied after the read, so what it closes is the window that
+actually occurs — a lane holding the label for minutes.
+
+**A child that is itself an epic is never offered** (joshuafolkken/kit#1476). An epic is not a unit of
+work, so a run handed one has nothing to implement — before this the row fell through to the
+dependency reading, which makes anything unblocked runnable, and `backlogrun` passed the epic to
+`fullrun` as an ordinary issue. 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.
+
+Children that are not runnable are sorted by **whether waiting helps**, never by label:
+
+| Bucket | Caller does |
+| --- | --- |
+| Runnable | Run it |
+| Waiting on time | Wait and ask again |
+| Waiting on a person | Stop and report |
+
+Reading labels instead fails in an ordinary state: when one repository's child has closed and
+another's is waiting for a release to publish, nothing carries `in-progress` or `needs-decision` —
+and a label-based reading calls that "done" in the one moment it must wait.
+
+**A blocker outside every named epic is weighed, not ignored** (joshuafolkken/kit#1943). 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 1936 1931`, or `backlog:next`, whose set is the whole opted-in backlog. The table is
+`docs/josh-commands.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.
+
+## Execution waves — parallel, then one alone, then the rest
+
+**A wave is not a mechanism, and there is nothing to add for one.** "Run #A, #B and #C together, then
+#D by itself, then the rest together" is already expressible with the dependency declaration this
+skill has described above, and wanting it only became common once parallel lanes
+(joshuafolkken/kit#1170) let several children run at once. What was missing was never the mechanism —
+it was that nobody had written down how to build one, or when not to (joshuafolkken/kit#1584).
+
+### The shape
+
+**A wave boundary is drawn by chaining every child of the later wave to every child of the earlier
+one.** Wave 1 `{#A, #B, #C}` → wave 2 `{#D}` → wave 3 `{#X, #Y, #Z}` is written in the epic's
+`## Dependencies` as three chain lines:
+
+```
+#A -> #D -> #X
+#B -> #D -> #Y
+#C -> #D -> #Z
+```
+
+- **#A #B #C are blocked by nobody, so they start together** — as many at once as there are free lanes.
+- **#D is `time` until all three have closed**, and becomes runnable the moment the last one does.
+- **#X #Y #Z are blocked by #D, so #D necessarily runs alone.**
+- **#D closing releases wave 3**, which again runs as wide as the lanes allow.
+
+**The block above is an illustration, not something to paste.** `parse_dependency_chains` strips
+fenced blocks before it matches, so a `## Dependencies` section whose chains sit inside a fence reads
+as **no declaration at all** rather than as an error — and `#A` / `#B` are not issue numbers anyway.
+The lines go into the epic body unfenced, with real numbers.
+
+**Deleting a declared order is `pnpm josh epic --remove <E> <M> <N> [<N2> …]`, and never a hand edit
+either** (joshuafolkken/kit#1712). The arguments are a path, so each consecutive pair is one order and
+a whole chain goes in one call; the body's declaration and the `blocked-by` relations are written from
+that one input, exactly as `--add` writes them. **The ends are never reconnected** — `#A -> #B -> #C`
+minus `#B -> #C` leaves `#A -> #B`, and taking out a middle child's two links leaves `#A` and `#C`
+unordered rather than declaring `#A -> #C`. Deleting the last link writes the unordered sentence, so
+the section never ends up with no machine-readable declaration. Pass `--decision-file` to record why;
+the record lands on the epic's `## Decisions` and on both ends of every deleted order. Doing either
+half by hand is the `declaration_mismatch` below, arrived at from the other direction.
+
+**Write the boundary with `pnpm josh epic --add`, not by hand.** A declared link with no recorded
+`blocked-by` relation is the `declaration_mismatch` that `find_anomalies` reports, and it stops
+`epic:next` and the run that consumes it outright; the rule further down — record the order in `blocked-by` **and**
+in `Dependencies` — is what a wave has to satisfy, and editing the body alone satisfies half of it.
+**`--before <hub>` and `--after <hub>` are both refused while the hub sits in more than one chain
+with nothing after it** — which is exactly what a hub is the moment the earlier wave has been chained
+into it. `chains_containing` finds several indices; `is_branching_after` does not hold, because it
+requires a successor in **every** chain naming the target and a hub has none in any of them; so
+`ambiguous_position_error` is raised (`scripts/git/git-epic-chains.ts`). **The first child of the
+next wave therefore goes into the declaration by hand**, with its `blocked-by` recorded to match.
+Once the hub has a successor, `--after <hub>` branches a new line and the rest of that wave goes in
+with it.
+
+**Nothing in the parsing or the consistency check forbids this.** `DECLARED_CHAIN_LINE` in `scripts/git/git-epic-parse.ts`
+asks only that a line be *nothing but* a chain, so there may be any number of chain lines and **one
+child may be an endpoint of several of them** — `parse_dependency_links` expands each line
+independently and flattens the result, dropping only self-loops. `find_anomalies` in
+`scripts/epic/epic-graph.ts` rejects exactly two things, a **cycle** and a **disagreement between the
+declaration and the recorded `blocked-by`**; a fan-in and a fan-out are neither.
+
+**The number of lines is the size of the widest wave**, because a one-child wave is a hub and the
+chains through it collapse into one line each. Where both sides of a boundary hold several children
+the count grows — and that is the moment to ask whether the boundary is real, rather than to go
+looking for a shorter notation.
+
+### Running one child alone is a wave of one
+
+**There is no `solo` mechanism, and none is needed.** "This one must not run beside anything" is the
+shape above with a wave of size one: chain into it every child that must not overlap it, and out of
+it every child that must not precede it. Adding a third axis — an exclusivity label, an
+`## Exclusive` section — would put a second way to say what the dependency declaration already says,
+and a second consistency check to keep the two agreeing.
+
+### When a wave may be declared
+
+**Declare a boundary only where the later wave needs the earlier wave's artifact.** That is the whole
+condition, and it is narrower than it sounds:
+
+- **A mere preference of order is not a dependency.** Wanting one child to go first — to see its
+  result early, to get the risky one out of the way — is presentation order, and joshuafolkken/kit#1583
+  is where that belongs. Substituting a dependency for it buys the order and pays with the stall below.
+  **Write it with `--order-before <M>` / `--order-after <M>`** (joshuafolkken/kit#1738), which move the
+  task-list row and declare nothing; `--before` / `--after` are for an order that really is a
+  dependency. Neither of the order-only flags helps at a **wave boundary**, which is a dependency by
+  definition — the hub case below stays what it is.
+- **Two children that would edit the same file** are the case with no better answer today: separating
+  them into different waves is how it is done, and the price — a fixed order, plus the stall — is
+  accepted knowingly rather than by default.
+- **No reason to wait means no declaration.** An epic whose children are mostly independent says so in
+  prose and leaves the graph empty.
+
+### What a jam does, and how it is cleared
+
+**Declare a boundary and one stuck child in the earlier wave stops every wave behind it.**
+`from_blockers` in `scripts/epic/epic-classify.ts` propagates `human`: a wave-1 child labelled
+`needs-decision` makes every child behind it "waiting on a person" rather than "waiting on time".
+
+**The park itself is not the halt, and reading it as one hides how the cost arrives.** `backlogrun` parks
+that child and goes on running the rest of wave 1 exactly as it always does; the session stops once
+those close and nothing is runnable, because every later wave has been classified `human`. So a
+boundary is paid for at the *end* of the wave rather than at the moment one child parks — which is
+what makes one easy to declare and expensive to have declared. **Clearing it is removing that child's
+`needs-decision`** once the decision has been recorded — the removal recording a decision already
+requires — after which the waves behind it become runnable on the next round.
+
+This is why the answer to "how do I build waves" is a paragraph rather than a feature. **A wave is
+declared for a real wait and removed when the wait ends; it is not the standing shape of an epic.**
+
+### The worked example — joshuafolkken/kit#1474
+
+That epic has grown to **46 children while its declared chains have stayed at three**, and its body
+says why:
+
+> **鎖として宣言していない。** 19 件はほぼ独立しており、順序を依存として宣言すると 1 件詰まっただけ
+> で残り全部が止まる。以下は推奨であって制約ではない。
+
+The nineteen that paragraph was written about are ordered in **prose — a group, not a graph** — so a
+reader gets the intent and no run is stopped by it, and none of the children added since has needed a
+chain either. joshuafolkken/kit#1262 is the same lesson from the other
+side: **24 false dependencies invented by `epic --add` have been removed from it**, each one an order
+nobody needed that could have stopped everything behind it.
+
+## 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.
+
+- **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
+  joshuafolkken/kit#858 --only`. A bare `#N` resolves to *this* repository's issue of that number.
+
+**A dependency that crosses a repository is not satisfied by the blocking issue closing.** Merging
+does not publish: the merge, the auto-tag and the publish run one after another, so a consumer told
+it may start at that moment installs the previous release or fails outright — "it breaks sometimes",
+the hardest kind to diagnose. 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** (joshuafolkken/kit#1129). 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 rather than waiting until the run's own eight-hour
+timeout with nothing an operator can edit to clear it. The answer is read from the blocker
+repository's own manifest and never from the registry: a registry 404 also means "this token may not
+see it", so resolving on one would start a consumer child before its blocker's release existed.
+
+**The evaluation is an AND in that order.** While the blocker is open the registry is never
+consulted, so a run never stalls on a publish from the moment it starts. The target is that exact
+version, never "something newer" — a consumer several releases behind would otherwise be satisfied by
+a publish that predates the change.
+
+## `josh epic:bundle <N>` — does this new issue belong with one already filed?
+
+Run it right after an issue is filed: by `kickoff` / `fullrun` / `halfrun`, or by any Tier A filing
+mid-implementation, including inside a `backlogrun`. **It recommends; it writes nothing.**
+
+"Two or more always means an epic" only fires when one request is split on the spot. Two issues filed
+days apart that turn out to be the front and back of one job are executed separately, in whatever
+order, with the reasoning recorded nowhere.
+
+**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 search is not limited to the open backlog.** Every issue number the subject's body names is read
+on its own, whatever its state — otherwise the command answers correctly only in the minutes between
+a follow-up issue being filed and its parent closing (joshuafolkken/kit#947). 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. Reported as a gap it puts `⚠ Could not read #N.` above the verdict, and the rule below stops an
+unattended run on exactly that, for a reference that never existed (joshuafolkken/kit#957). **The two
+are told apart by HTTP status, never by `gh`'s wording**: 404 is nothing at that number, 403 and 429
+are a rate limit. GitHub answers 404 for an issue the token may not see as well, so as not to leak
+its existence — which does not reach this command, because it probes the repository whose open issues
+it has just listed. The probe costs one REST request and runs **only** when a read has already
+failed, and only on the path that needs the distinction: the backlog's own relation reads, up to two
+hundred of them, never pay it.
+
+| Candidates | Do | Tier |
+| --- | --- | --- |
+| **The new issue itself already has an epic** | Nothing — an issue belongs to at most one | — |
+| Already a child of an epic | Add to **that** epic; do not create a second | A |
+| Spread across an epic and its **own parent** | Add to the inner epic — the parent already contains it | A |
+| Spread across **different** epics | **Choose the one you recommend, add to it, and record why** | **A** |
+| In no epic, two or more counting the new issue | Create an epic | A |
+| No strong signal | Nothing | — |
+| **The epic listing was cut short** | **Nothing** — every placing row above is withheld | — |
+
+**Every row that *places* the issue asserts a negative, so a cut epic listing withholds all of them**
+(joshuafolkken/kit#1697). "No epic already tracks this issue" — which `create_epic` asserts about the
+candidates too — is only as good as the listing it was read from, and an epic past the cut tracks its
+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 cut was already on standard error
+(`⚠ The epic listing …`) while standard output went on printing an executable
+instruction such as `Create an epic for these (Tier A — do it).` — and the rule below that reads a warning as "could not answer" is written for one above
+`Nothing to bundle.`, so it never reached this verdict. Acted on as Tier A, that is a **second epic
+over an already-tracked issue**, which the auto-close and `epic:next` cannot both be right about
+(joshuafolkken/kit#943). The verdict now says so itself:
+
+```text
+Could not confirm which epic already tracks these — do not place this issue in one.
+  the epics were not read in full, so an epic already tracking one of these may never have been seen
+  Related: #1662
+```
+
+**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 first row above names the epic it read
+tracking the issue, and epics past the cut cannot unseat it.
+
+**Placing an issue is not merging epics, and reading it as one is what used to stop runs.** 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.**
+
+**An epic and its own parent no longer produce the spread verdict at all** (joshuafolkken/kit#1079).
+They were never two peers to choose between — the parent already contains the child — so the pair is
+narrowed to the inner epic and the issue is added there. The verdict had recorded three such false
+positives, one of which stopped a whole batch over an issue whose implementation was finished and
+whose pull request was mergeable. **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.** Skipping it is not a shortcut past a
+formality — it is the half that makes an unattended choice auditable, and without it the run has
+simply taken a decision nobody can find afterwards.
+
+**Write both halves in the one call that places the issue: `pnpm josh epic --add <E> <N...>
+--decision-file <path|->`** (joshuafolkken/kit#1350). It appends the record to the epic's
+`## Decisions` inside the body edit the insertion already makes — so the epic half costs no round trip
+— 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, and paying for it by hand is why the entry got
+skipped. 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; the "Front-loading the
+decisions" section above 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 (joshuafolkken/kit#1252). **Both run**, and neither
+replaces the other: the scout is what a `new` entry point asks before `gh api … issues`, and
+`epic:bundle` is what it asks afterwards, from the real number and the relations recorded against it.
+Full behavior: `docs/josh-commands.md` → "`josh issue:scout`".
+
+**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**.

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

@@ -0,0 +1,96 @@
+---
+name: verify-ui
+description: Close the UI verification gate on a change that alters the rendered screen — capture a screenshot of the affected route through this project's own screenshot command, look at it, and report whether it matches the intent. Use it before reporting any UI, layout, styling, copy, visible-state or interaction change as done. It reports that the project has no screenshot command rather than passing when it cannot capture anything.
+argument-hint: '[route] [route...]'
+---
+
+# Verify the rendered screen
+
+The completion gate in `CLAUDE.md` says a change that affects the rendered UI is not done until
+someone has looked at the rendered result. Passing unit and E2E tests are not that look: they stay
+green while spacing, layout and styling are visibly broken. This skill is the look.
+
+## 1. Decide which routes to capture
+
+In order:
+
+1. The routes given as arguments (`/verify-ui / /blog`).
+2. Otherwise, derive the candidates with `pnpm josh ui:routes` (alias `josh uir`): it reads the
+   change (the branch diff, or the staged diff with `--staged`) and lists the routes it touches,
+   tracing a changed shared component to the routes that render it. From that list **pick the ones a
+   reader would notice** — that narrowing is the judgement the command leaves to you.
+3. If it derives no route — it prints that plainly rather than guessing — ask which screen to look
+   at. Do not guess.
+
+State the list before capturing, so a wrong route is caught before the build.
+
+## 2. Find this project's screenshot command
+
+The command belongs to the application layer, not to this package, and it differs per project type.
+Look for it in this order and stop at the first hit:
+
+1. `pnpm josh-app shot` — the SvelteKit application toolkit (`@joshuafolkken/app-kit`).
+2. `pnpm josh-game shot` — the game toolkit (`@joshuafolkken/game-kit`).
+3. A project-local script named `shot`, `screenshot` or `verify:ui` in `package.json`.
+
+Option 1 exists: `shot` shipped in app-kit 0.86.0 (joshuafolkken/app-kit#200). Option 2 does not
+yet — game-kit carries no `shot` — so a game project still lands on option 3 or the fallback below.
+Neither statement is a substitute for the check in the next paragraph: both are true of a version,
+and the version a project has installed is the only thing that decides.
+
+**Decide by the printed command list, not by whether the toolkit is installed.** Run the toolkit
+with no subcommand (`pnpm josh-app`) and read the usage line it prints; `shot` exists only if that
+list names it. An unknown subcommand exits non-zero with the same usage line, so a toolkit that is
+present but has no `shot` command and a toolkit that is absent are told apart by reading the list,
+not by whether the invocation succeeded.
+
+### When there is no screenshot command
+
+The gate still has to be met, so fall back in this order.
+
+**Capture through the project's own E2E suite.** If it has Playwright specs, add a
+`await page.screenshot({ path: … })` to the spec that already covers the affected screen — or a new
+spec if none does — and run it. This is a real capture and it is committed test code, which is why
+it is a fallback and not a workaround: it leaves the project with a screenshot the next run can take
+again.
+
+**Otherwise stop and say so.** Report, in the session language:
+
+- that this project has neither a screenshot command nor an E2E suite to capture through, naming
+  what you looked for;
+- that the UI verification gate is therefore **not** closed by this run;
+- that the change needs a human to look at the screen, and ask the user to do it.
+
+Never report the gate as satisfied on tests alone. Never stand up a preview server by hand and drive
+it from a throwaway script left outside the repository: server lifecycle is what the toolkit command
+owns, and an improvised one leaves a process running and nothing the next run can reuse. If the
+project should have the command and does not, that is an issue to file against the application
+toolkit.
+
+## 3. Capture
+
+Run the command once for every route in a single invocation (`pnpm josh-app shot / /blog`). One
+invocation is what keeps the build and the preview server to one start and one stop. Wait for it to
+finish and note the output directory it prints. On the E2E fallback, run the spec and note where its
+`path` option wrote the images.
+
+If it exits non-zero, report the failure as the result. A failed capture is not a passed gate.
+
+## 4. Look at the images
+
+Read every produced image with the Read tool. Actually look at each one — the point of the gate is
+the look, and a run that captures files without opening them has done nothing the tests did not
+already do.
+
+Check what the change was supposed to do to the screen: the element is present, in the right place,
+at the right size, with the intended spacing, color and text; nothing that used to be there has
+disappeared or moved; the layout is not broken at the captured viewport.
+
+## 5. Report
+
+- **Matches the intent**: say what you looked at, route by route, and what you checked on each. Name
+  the image paths so the user can open the same files.
+- **Does not match**: for each mismatch give the route, what the change was supposed to produce,
+  what the image actually shows, and the image path. Then fix and capture again. Do not report the
+  work as done with a known mismatch outstanding.
+- **Could not capture**: the report from step 2 or step 3, unchanged. This is not a pass.