@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/.claude/agents/investigator.md

@@ -2,6 +2,7 @@
 name: investigator
 description: Read-only investigation unit for the pre-implementation reading — finds out how an Issue's subject currently works and returns the conclusion with its `file:line` citations, never the file text. Dispatch it when `pnpm josh investigation:guard` asks for a delegated unit, or when `pnpm josh delegate investigation` answers `delegate`.
 tools: Read, Grep, Glob, Bash
+model: sonnet
 effort: low
 ---
 

package/.claude/settings.json

@@ -10,6 +10,10 @@
 			"Bash(gh repo archive*)",
 			"Bash(gh pr close*)",
 			"Read(./.env)",
+			"Read(./.env.*)",
+			"Read(!.env.example)",
+			"Read(!.env.test)",
+			"Read(./.dev.vars)",
 			"Bash(git push --force*)",
 			"Bash(git push -f*)",
 			"Bash(git push *--force*)",

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

@@ -1,11 +1,11 @@
 ---
 name: dependency-update
-description: The verification procedure that runs after `pnpm update`, `josh latest`, `pnpm josh overrides` or any other dependency-update command — how to confirm the `overrides` entries in both `pnpm-workspace.yaml` and `package.json` survived, and which single `devEngines` change is the expected one rather than a violation. Read it before reporting that a dependency update left the pins intact, and whenever a bump has to be resolved forward or pinned back.
+description: Checks after `pnpm update`, `josh latest`, `pnpm josh overrides` or any dependency update — the `overrides` survived, the one expected `devEngines` change. Read it before reporting the pins intact or pinning a bump back.
 ---
 
 # After a dependency-update command
 
-`CLAUDE.md` keeps the two prohibitions resident — never touch `overrides`
+`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`, `pnpm josh overrides`,
@@ -65,7 +65,9 @@ intent.
 **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`.
+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.
 
 ## 4. When the bump breaks something — fix forward
 

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

@@ -1,14 +1,15 @@
 ---
 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 when `epic:bundle` places a filed issue (anything but `Nothing to bundle.`).
+description: Procedures for `josh epic:audit`, `epic:next` and `epic:bundle`. Read it before running one, before an epic tracks a child in another repository, when `epic:bundle` places a filed issue, and when recording a decision on a `needs-decision` child.
 ---
 
 # 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**, and the history behind the rules is `docs/maintainers/epic-commands-rationale.md` (joshuafolkken/kit#2892).
+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`, `backlogrun` — live in the
+The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `prrun`, `backlogrun` — live in the
 `workflow-commands` skill.
 
 ## The order they run in
@@ -36,19 +37,16 @@ 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`
   — `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 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.
+  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**.
 
 ```md
 ## Decisions
 
 ### <the point that was decided>
 
-- 対象: #101, #102
+- 対象: #<N1>, #<N2>
 - 採用: <the option taken>
 - 却下: <the option rejected>
 - 理由: <why the taken option is clearly better>
@@ -74,9 +72,7 @@ reasons and the history: `docs/maintainers/epic-commands-rationale.md` → "Crea
 
 ## `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.
+`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.
@@ -87,38 +83,27 @@ 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 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 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) |
+| 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 |
 | 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. The first check fires on a
-legitimate forward reference as readily as on a real missing dependency; failing on both would make
-design notes unwritable, so the reader judges and the machine only keeps it from being missed. A
-forward reference the other child *already depends on* is not reported at all. Acceptance criteria
-that require what a child free to run later produces cannot be met however anyone decides, which is
-why that check is an error.
-
-**A pair with either child closed is a warning, not an error.** What makes an undeclared order a
-contradiction is that the criteria's child *can run first*, and one end closing is enough to make
-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). **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 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.
 
 **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 the exception, because neither is a contradiction.** They are
-about the search itself rather than about anything the children say (joshuafolkken/kit#1033):
+about the search itself rather than about anything the children say:
 
 - `✖ 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
@@ -140,55 +125,44 @@ History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why
 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-backlog.md` → "`josh epic:next`" carries the worked form.
+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, 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.
+from that repository's own `in-progress` listing — never from anything the session remembers — 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.
+
+**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.
 
 Children that are not runnable are sorted by **whether waiting helps**, never by label:
 
@@ -198,17 +172,13 @@ 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 |
 
-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
+**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
@@ -216,6 +186,8 @@ Two things stop the command rather than being worked around: a **circular depend
 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.
 
+Why it orders and counts as it does: `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
@@ -227,34 +199,29 @@ to implement.
 - **The epic auto-closes only when every cross-repository child's state could actually be read.** One
   unreadable child leaves it open, exactly as before.
 - **An epic in another repository must be referenced as `owner/repo#N`** — `backlogrun
-  joshuafolkken/kit#858 --only`, `epic:next joshuafolkken/kit#858 --repo joshuafolkken/app-kit`. A
+  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 joshuafolkken/kit#869's
+- **`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: 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.
+**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** (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. A
-manifest read that fails (rather than answering 404) is told apart by HTTP status and still waits.
+**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 consumer several releases behind would otherwise be satisfied by
-a publish that predates the change. **A child no longer bumps the version** (joshuafolkken/kit#1486):
-the version moves only when `pnpm josh release` runs, so the target is the release that includes the
-blocker, and the default branch's version just after its merge is the previous release, which would
-satisfy the wait at once. The publish check shares `josh propagate`'s implementation; it is not
-defined twice. History: `docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
+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".
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
@@ -276,4 +243,6 @@ run it by hand only when that step printed `⚠`. **It recommends; it writes not
 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".
+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".

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

@@ -5,60 +5,40 @@ or a choice between epics — or when the answer is one the summary in the `epic
 (`SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with one already filed?") does not
 settle. `Nothing to bundle.` needs neither.
 
-"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`.
+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. Reported as a gap it puts `⚠ Could not read #N.` above the verdict, and the could-not-answer rule
-(`prompts/review.md` → "Three-way disposition after the cap") stops an unattended run on exactly that, for a reference that never existed (joshuafolkken/kit#957). **The two
-are told apart by HTTP status, never by `gh`'s wording**: 404 is nothing at that number, 403 and 429
-are a rate limit. GitHub answers 404 for an issue the token may not see as well, so as not to leak
-its existence — which does not reach this command, because it probes the repository whose open issues
-it has just listed. The probe costs one REST request and runs **only** when a read has already
-failed, and only on the path that needs the distinction: the backlog's own relation reads, up to two
-hundred of them, never pay it, and the referenced-number reads are capped at twenty. **Only the
-subject's own body is followed** — the reverse direction would scan every closed issue, and a
-follow-up already names its parent. The reference parsing is the same implementation as
-`epic:audit`'s implicit-dependency check, applied to the backlog instead of one epic. The open backlog
-is small enough to scan whole, so there is no index or cache.
+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**
-(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 that reads a warning as "could not answer" (`prompts/review.md` → "Three-way
-disposition after the cap") is written for one above
-`Nothing to bundle.`, so it never reached this verdict. Acted on as Tier A, that is a **second epic
-over an already-tracked issue**, which the auto-close and `epic:next` cannot both be right about
-(joshuafolkken/kit#943). The verdict now says so itself:
+**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:
 
 ```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
+  Related: #<N>
 ```
 
 **The children and the order are deliberately absent** — they are the recipe for the placement that
@@ -66,31 +46,26 @@ line says not to make. The exit code stays `0`, as it does for every other "do n
 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.
 
-**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.
+**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.**
+
+**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.
 
 **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:
+--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
@@ -105,10 +80,10 @@ 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 (joshuafolkken/kit#1252). **Both run**, and neither
-replaces the other: `pnpm josh issue:file` runs the scout before it creates the issue, and
-`epic:bundle` afterwards, from the real number and the relations recorded against it.
-Full behavior: `docs/josh-commands-backlog.md` → "`josh issue:file`".
+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:
+`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