@joshuafolkken/kit 1.1136.0 → 1.1178.0

package/scripts/document/document-byte-budget.ts

@@ -65,15 +65,19 @@ function block_ceiling(size: number): number {
 // unreached file, so the definition cannot rot as documents move on or off the execution path.
 const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/dependency-update/SKILL.md', bytes: 8192 },
-	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 36_864 },
+	// joshuafolkken/kit#3173 split the waves and the `epic:bundle` detail into lazily read references.
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 20_480 },
+	{ path: '.claude/skills/epic-commands/epic-bundle.md', bytes: 12_288 },
+	{ path: '.claude/skills/epic-commands/execution-waves.md', bytes: 12_288 },
 	{ path: '.claude/skills/verify-ui/SKILL.md', bytes: 8192 },
-	{ path: '.claude/skills/workflow-commands/followup-reference.md', bytes: 16_384 },
 	{ path: '.claude/skills/workflow-commands/fullrun-steps.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/into-target.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/issue-comments.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/issue-fold-existing.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/needs-human-review.md', bytes: 8192 },
-	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 24_576 },
+	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 12_288 },
+	// joshuafolkken/kit#3176 moved the ledger out of `observation-filing.md`, read only when it appends.
+	{ path: '.claude/skills/workflow-commands/observation-ledger.md', bytes: 12_288 },
 	// `pre-gate-cut.md` left this per-document budget in joshuafolkken/kit#2289: it became a point-of-use
 	// document, so its bytes are now held by every entry's total read (`entry-read-budget.ts`) and the
 	// two budgets must not hold it twice — the reachability line moved it from `unreached` to
@@ -82,34 +86,44 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
 	// joshuafolkken/kit#2998 split the reference: the developer commands stay, the rest moved out.
-	{ path: 'docs/josh-commands-automation.md', bytes: 155_648 },
+	// joshuafolkken/kit#3175 raised it: the supervisor, provider-table and answer-to-budget prose moved
+	// here out of `backlogrun-steps.md`, so a run reads it only when it asks about those commands.
+	{ path: 'docs/josh-commands-automation.md', bytes: 159_744 },
 	{ path: 'docs/josh-commands.md', bytes: 36_864 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 8192 },
-	// #2662 adds the feature and compatibility declarations to the canonical filing procedure.
-	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 16_384 },
-	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 16_384 },
-	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 8192 },
-	{ path: 'prompts/collaboration-workflow/plan-comment.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 4096 },
+	// #3178 left the template and the judgement tables; the epic commands moved to `epic-commands`, the by-hand fallback stayed.
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 12_288 },
+	// #3177 moved the rationale to `docs/maintainers/output-bounds-rationale.md`.
+	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 4096 },
+	// #3178 replaced the review-chain restatement with a pointer to `chain-rule.md`.
+	{ path: 'prompts/collaboration-workflow/plan-comment.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/principles.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/proposal-request.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 45_056 },
-	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 20_480 },
+	// #3178 dropped the restatements `report:lint` and `chain-rule.md` already carry.
+	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 16_384 },
+	// #3177 cut it to the four questions; the history and lists moved to `docs/maintainers/residency-rationale.md`.
+	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 8192 },
+	// #3186 moved the hook wiring and history to `docs/maintainers/rule-delivery-rationale.md`;
+	// #3179 adds the `index-mutation` / `destructive-command` / `protected-file` entries.
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 8192 },
+	// #3177 moved the measurements and rejected mechanisms to `docs/maintainers/turn-batching-rationale.md`.
+	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 16_384 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 12_288 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
-	{ path: 'prompts/review-rubric.md', bytes: 20_480 },
-	{ path: 'prompts/review.md', bytes: 20_480 },
+	// #3180 moved the history and the lint-settled proofs to `docs/maintainers/`.
+	{ path: 'prompts/review-rubric.md', bytes: 16_384 },
+	{ path: 'prompts/review.md', bytes: 16_384 },
 	{ path: 'prompts/sonar-hotspot-handling.md', bytes: 8192 },
-	{ path: 'prompts/testing-guide.md', bytes: 24_576 },
+	{ path: 'prompts/testing-guide.md', bytes: 20_480 },
 ]
 
 // The recorded ceiling for one path, or undefined when it carries no budget entry.

package/scripts/document/entry-read-budget.ts

@@ -57,7 +57,7 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// block in joshuafolkken/kit#2317 when `backlogrun-child.md`'s outage section recorded the
 	// session-resume re-dispatch and the outage-fold window.
 	// Raised in joshuafolkken/kit#2328 when `retrospective.md` joined the point-of-use set and `SKILL.md`
-	// grew by §2j: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
+	// grew by `retrospective.md`: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
 	// and the new section crossed a block for each. The lane child is exempt — it never runs the
 	// retrospective (`run:step` answers `stop` for a child at the stop position), so it skips both.
 	// joshuafolkken/kit#2335 recorded the drain-time firing with the operational detail in
@@ -70,8 +70,8 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// list, so its ~48KB read crossed a block downward and the recorded ceiling drops to the block multiple
 	// the stale-ratchet message named. The other entries still read it, so their rows hold.
 	// joshuafolkken/kit#2345 added the `implementation-unit` delegation row (full fan-out procedure in
-	// `docs/josh-commands-automation.md` → "`josh fanout`"); `SKILL.md` §2b gained only a one-clause mention and a
-	// pointer, folded into the existing enumeration and offset by tightening §2b prose, so every entry
+	// `docs/josh-commands-automation.md` → "`josh fanout`"); `delegation.md` gained only a one-clause mention and a
+	// pointer, folded into the existing enumeration and offset by tightening `delegation.md` prose, so every entry
 	// stayed within its block (kickoff has no block of headroom — its pre-#2294 ceiling is the next
 	// multiple, which the downward ratchet holds shut).
 	// joshuafolkken/kit#2353 wired the watcher-guard note into `backlogrun-progress.md` (read by the three
@@ -92,12 +92,24 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// `backlogrun-*` phase documents it never opens. Each total now counts only what its path reaches.
 	// joshuafolkken/kit#3077 trimmed non-resident rule bodies from `CLAUDE.md`, lowering fullrun, prrun
 	// and backlogrun one block each.
-	{ entry: 'kickoff', bytes: 65_536 },
-	{ entry: 'fullrun', bytes: 126_976 },
-	{ entry: 'halfrun', bytes: 106_496 },
-	{ entry: 'prrun', bytes: 131_072 },
-	{ entry: 'backlogrun', bytes: 212_992 },
-	{ entry: LANE_CHILD, bytes: 77_824 },
+	// Lowered in joshuafolkken/kit#3172: the heartbeat left `backlogrun-progress.md` for its own
+	// `progress-watcher.md`, and `pre-gate-cut.md` became the lane child's alone, so fullrun, halfrun
+	// and prrun stop paying for ~50KB of batch and lane procedure; backlogrun lost the moved prose.
+	// Lowered in joshuafolkken/kit#3174: `SKILL.md` was cut to a manifest (~21KB → ~11KB) and the entry
+	// sequence `fullrun`, `halfrun` and `prrun` shared moved into one `entry-sequence.md`.
+	// Lowered in joshuafolkken/kit#3175: the loop became the driver's hand-backs, the supervisor and
+	// provider prose moved to `docs/josh-commands-automation.md`, and the failure-only sections moved to
+	// `backlogrun-recovery.md`, which the parent's reach still charges whole.
+	// joshuafolkken/kit#3171 cut `CLAUDE.md` to triggers and pointers (~12 KB), lowering every entry.
+	{ entry: 'kickoff', bytes: 45_056 },
+	// Raised in joshuafolkken/kit#3177: #3173, #3181 and #3183 merged in parallel and together tipped
+	// fullrun 12 bytes over its block; none of #3177's documents are in its read set.
+	// Lowered back in joshuafolkken/kit#3180: the history and lint-settled proofs left its read set.
+	{ entry: 'fullrun', bytes: 57_344 },
+	{ entry: 'halfrun', bytes: 57_344 },
+	{ entry: 'prrun', bytes: 61_440 },
+	{ entry: 'backlogrun', bytes: 176_128 },
+	{ entry: LANE_CHILD, bytes: 57_344 },
 ]
 
 function byte_size(root: string, relative_path: string): number {

package/scripts/document/lane-child-read-set.ts

@@ -19,19 +19,12 @@ const LANE_CHILD = 'lane-child'
 const FULLRUN = 'fullrun'
 
 // **The `SKILL.md` sections a dispatched lane child never uses**, read at the section level rather
-// than in full. A child is handed one issue to run, so it never files a new one with an `into`
-// target (§2a), never delegates its own pre-implementation reading (§2b), never names a repository or
-// scouts for a duplicate at its entry (§2c, §2e), returns an observation to the parent rather than
-// filing it (§2i), and never edits these documents (§3). Its dispatch is already an explicit workflow
-// invocation, so §0 cannot decide anything for it either. Review delegation remains in chain-rule.md.
+// than in full. A child never edits these documents (§3), and its dispatch is already an explicit
+// workflow invocation, so §0 cannot decide anything for it either. The other rules it never uses — the
+// `into` target, delegation, the repository prefix, the scout, observation filing, the retrospective —
+// are single rows of §2's table since joshuafolkken/kit#3174, so no section of them is left to trim.
 const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 	'0. The rule that fires before any of them — explicit invocation',
-	'2a. The `into <target>` suffix — where the new Issue lands',
-	'2b. Delegating a step to a cheaper tier',
-	'2c. The `owner/repo#` prefix — which repository the run acts on',
-	'2e. Before filing a new Issue — `pnpm josh issue:scout`',
-	'2i. An observation worth filing is filed without asking',
-	'2j. The end-of-run retrospective — read when `run:step` prints it',
 	'3. What stays resident, and what is read from here',
 ]
 
@@ -49,10 +42,12 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 // list — what one invocation approves, the named-issue order, the session-cut record, the loop and the
 // once-per-session tail — none of which a leaf child performs. Every reference to it lives in a
 // document the child never reads (`backlogrun.md`, `backlogrun-progress.md`, `retrospective.md`) or in a
-// `SKILL.md` section the child trims (§0's session-cut note, §2b, §2i, §2j), so the child has no path
+// `SKILL.md` section the child trims (§0's session-cut note), so the child has no path
 // that opens it. It was the child's single largest read — ~16,000 tokens read whole — charged for a
 // document it never reaches, so dropping it is a correction of an over-count, not a loss of any rule the
 // child needs. The parent still reads it in full.
+// **`progress-watcher.md` is the parent's too** (joshuafolkken/kit#3172): a dispatched child is refused
+// a watcher by its `JOSH_LANE_CHILD` mark, so it never opens the watcher's document.
 const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'backlogrun-child.md',
 	'backlogrun-lanes.md',
@@ -61,13 +56,16 @@ const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'delegation.md',
 	'issue-scout.md',
 	'latest-gate.md',
+	'progress-watcher.md',
 	'retrospective.md',
 ])
 
 // **A child that parks reads `backlogrun-park.md`** (`SKILL.md` §1, "A lane child that parks"), a
 // document a standalone `fullrun`'s path never names — so the child's reach adds it to its base
-// entry's (joshuafolkken/kit#3078).
-const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['backlogrun-park.md'])
+// entry's (joshuafolkken/kit#3078). **`pre-gate-cut.md` is the child's alone** (joshuafolkken/kit#3172):
+// only a lane child resumes or takes the pre-gate cut, so `fullrun.md` stopped naming it and the
+// child's reach carries it instead.
+const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['backlogrun-park.md', 'pre-gate-cut.md'])
 
 function costed(root: string): ReadSetCost {
 	return read_set_trim.costed(root, {

package/scripts/document/read-set-cli.ts

@@ -48,15 +48,15 @@ const POINT_OF_USE_LABEL = '-- read at the point of use, not at the entry --'
 const LANE_CHILD_NOTE: ReadonlyArray<string> = [
 	'  a dispatched lane child (`JOSH_LANE_CHILD`) reads this trimmed set:',
 	'  - skips the point-of-use documents the parent owns — child dispatch, lane opening, the progress watcher and the hand-off',
-	'  - omits SKILL.md §0/§2a/§2b/§2c/§2e/§2i/§3 — dispatch already authorized the run and a leaf child never uses them',
+	'  - omits SKILL.md §0/§3 — dispatch already authorized the run and a leaf child edits no rule',
 ]
 // **The `backlogrun` parent reads a trimmed set of its own** — a scheduler that never implements, so
 // the implementer-only `SKILL.md` sections are read section by section rather than whole
-// (joshuafolkken/kit#2256). A *different* trim from the lane child's: the parent keeps §0/§2b/§2c/§2e/
-// §2i, which are the scheduler's own, and drops no point-of-use document.
+// (joshuafolkken/kit#2256). A *different* trim from the lane child's: the parent keeps §0, which is the
+// scheduler's own, and drops no point-of-use document.
 const BACKLOGRUN_PARENT_NOTE: ReadonlyArray<string> = [
 	'  the backlogrun parent (scheduler) reads this trimmed set:',
-	'  - omits SKILL.md §2a/§2f/§2g/§3 — the parent never implements, so it claims no tree and files no `into` target',
+	'  - omits SKILL.md §3 — the parent edits no rule mid-run',
 	'  - keeps every point-of-use document — the parent is the one dispatching children and running lanes',
 ]
 const FETCH_RULE =

package/scripts/document/read-set-point-of-use.ts

@@ -15,7 +15,7 @@
 // is joshuafolkken/kit#1856's addition**: it governs the `/code-review` → `followup` chain, which in
 // `fullrun` / `queue` / `epicrun` / `backlogrun` runs *after* the first edit, so its 7,396 tokens
 // were resident from the entry for no run that had yet reached a review.
-// **`background-commands.md` is joshuafolkken/kit#1873's**: it was §2h's resident body, governing the
+// **`background-commands.md` is joshuafolkken/kit#1873's**: it was `background-commands.md`'s resident body, governing the
 // background execution of the gate, the push and the merge tail — all after the first edit — so it
 // left `SKILL.md` for the point-of-use list. `SKILL.md` → §1, "Four documents are read at the point
 // of use", is the single source.
@@ -32,18 +32,26 @@
 // cut, a step every implementing run — and every dispatched lane child — reaches after the entry, so
 // its read is a point-of-use read the count was silently omitting. Measured on the backlogrun of
 // 2026-09-21, the lane children read it 21 times across 13 runs — the largest single document read,
-// and the one the point-of-use list had no row for.
+// and the one the point-of-use list had no row for. Only a lane child reaches it (joshuafolkken/kit#3172):
+// `fullrun.md` no longer names it, so it is charged to the lane child's role alone.
+// **`progress-watcher.md` joins them** (joshuafolkken/kit#3172): the heartbeat every implementing run
+// starts once its hold is claimed, split out of `backlogrun-progress.md` so a single-issue run stops
+// paying for the batch's hand-off and waiting procedure to read it.
 const POINT_OF_USE_FILES: ReadonlySet<string> = new Set([
 	'latest-gate.md',
 	'followup.md',
 	'chain-rule.md',
 	'background-commands.md',
 	'pre-gate-cut.md',
+	'progress-watcher.md',
 	'backlogrun-child.md',
 	'backlogrun-lanes.md',
 	'backlogrun-progress.md',
 	'backlogrun-park.md',
 	'backlogrun-steps.md',
+	// Read only when a delegated unit goes silent or a lane's pull request conflicts with `main` — a
+	// failure path, so a run in which nothing fails never reads it (joshuafolkken/kit#3175).
+	'backlogrun-recovery.md',
 	// Read only when `run:step` prints `pnpm josh retrospective` at a run's stop position — the very
 	// end of a run, never the entry (joshuafolkken/kit#2328). Kept out of every entry's read for the
 	// same reason the phase documents above are: no run that never drains its backlog reaches it.

package/scripts/document/resident-budget.ts

@@ -0,0 +1,47 @@
+import { document_reachability } from './document-reachability'
+
+// The byte budget of the always-resident document — `CLAUDE.md`, loaded on every request. It is held
+// here rather than in `document-byte-budget.ts` because a resident document is covered by every entry
+// total and must not carry a per-document block entry as well (joshuafolkken/kit#2257); it is held here
+// rather than inside `workflow-skills.test.ts` so `josh bytes CLAUDE.md` counts against the same number
+// the suite enforces (joshuafolkken/kit#3171). Loosening any of the three constants is Tier C —
+// `prompts/collaboration-workflow/residency.md`.
+
+// The documents sat at ~83 KB each before the joshuafolkken/kit#854 split, crept back to ~56 KB, and
+// were cut below 30 KB by joshuafolkken/kit#1924. joshuafolkken/kit#3171 cut `CLAUDE.md` to ~14 KB —
+// triggers and pointers only — and lowered this ceiling with it, so the document cannot creep back. It
+// is a guard against re-inlining, not a budget to tune prose against.
+const RESIDENT_CEILING_BYTES = 18_000
+
+// joshuafolkken/kit#951: the ceiling alone stops the wrong thing. Reached, it does not block the
+// next rule — it makes that rule pay for itself by deleting a neighboring sentence, and the
+// sentence chosen is whichever one no marker pinned rather than whichever one matters least. A
+// required margin turns "at the limit" into a failure while there is still room to write the fix,
+// which is the only point at which moving a procedure into a skill is still a choice.
+const RESIDENT_HEADROOM_BYTES = 2000
+
+// joshuafolkken/kit#1275: a floor under the room left once the procedures are out, so a wholesale
+// re-inlining fails by name instead of silently returning the document to a few bytes of headroom.
+const RE_INLINE_GUARD_HEADROOM_BYTES = 1000
+
+const EFFECTIVE_CEILING_BYTES = RESIDENT_CEILING_BYTES - RESIDENT_HEADROOM_BYTES
+
+// The size a resident document must stay below — the effective ceiling minus the re-inline floor. The
+// suite fails at it, and `josh bytes` counts the headroom against it.
+const RESIDENT_LIMIT_BYTES = EFFECTIVE_CEILING_BYTES - RE_INLINE_GUARD_HEADROOM_BYTES
+
+// The limit for a resident document, or undefined for any other path.
+function limit_bytes_for(relative_path: string): number | undefined {
+	return document_reachability.RESIDENT_BASE.includes(relative_path)
+		? RESIDENT_LIMIT_BYTES
+		: undefined
+}
+
+const resident_budget = {
+	EFFECTIVE_CEILING_BYTES,
+	RE_INLINE_GUARD_HEADROOM_BYTES,
+	RESIDENT_LIMIT_BYTES,
+	limit_bytes_for,
+}
+
+export { resident_budget }

package/scripts/epic/epic-shape.ts

@@ -5,7 +5,7 @@ import { to_issue_reference } from './epic-reference'
 // Whether an issue is an epic this repository's writers may edit, and why it is not when it is not.
 //
 // Both `josh epic --add` and `josh epic --remove` ask exactly this before they compute anything: the
-// label, the absence of a cross-repository child, a task list to place rows in, and a declaration
+// label, a task list to place rows in, and a declaration
 // their edit can be relative to. It lives in one module rather than in each of them, because the two
 // commands must refuse the same inputs for the same reasons — a second copy is where one comes to
 // accept an epic the other refuses (joshuafolkken/kit#1712).
@@ -40,18 +40,15 @@ function promote_remedy(epic_number: number): string {
 // The label and the task list are checked separately from the declaration because they fail
 // differently: without rows there is nowhere to put a new one, and without a declaration there is
 // nothing for an edit to be relative to.
-function find_epic_shape_error(subject: EpicShapeSubject, body: string): string | undefined {
-	const reference = to_issue_reference(subject.epic_number)
-
-	if (!subject.labels.includes(EPIC_LABEL)) {
-		return `${reference} does not carry the \`${EPIC_LABEL}\` label, so it is not an epic. ${promote_remedy(subject.epic_number)}`
-	}
-
-	if (epic_parse.has_external_task_list_entry(body)) {
-		return `${reference} tracks a child in another repository; editing the declared order of a cross-repository epic is joshuafolkken/kit#864's scope, not this command's.`
-	}
+//
+// **A child in another repository is not a refusal** (joshuafolkken/kit#3161). The declaration names
+// bare numbers only, so neither command can write an order across repositories — such an order lives
+// in the native relations alone (`epic_graph.child_links`), which these edits never read or drop — and
+// the rewrite leaves a row it does not recognize exactly where it stood.
+function find_epic_shape_error(subject: EpicShapeSubject): string | undefined {
+	if (subject.labels.includes(EPIC_LABEL)) return undefined
 
-	return undefined
+	return `${to_issue_reference(subject.epic_number)} does not carry the \`${EPIC_LABEL}\` label, so it is not an epic. ${promote_remedy(subject.epic_number)}`
 }
 
 function find_subject_error(
@@ -60,7 +57,7 @@ function find_subject_error(
 ): string | undefined {
 	const reference = to_issue_reference(subject.epic_number)
 	if (subject.body === undefined) return `Could not read the body of ${reference}.`
-	const shape_error = find_epic_shape_error(subject, subject.body)
+	const shape_error = find_epic_shape_error(subject)
 	if (shape_error !== undefined) return shape_error
 
 	if (tracked.length === 0) {

package/scripts/epic/epic-solo.ts

@@ -6,7 +6,7 @@ import { epic_report, type EpicNextResult } from './epic-report'
 
 // The `run:solo` gate on what a run is offered (joshuafolkken/kit#2776).
 //
-// `wip-cap.md`'s run-alone section says an issue whose defect reaches the verification path runs
+// `backlogrun-lanes.md`'s run-alone rule says an issue whose defect reaches the verification path runs
 // alone, and until this gate that was a judgement made at dispatch — the offer handed such an issue
 // out beside others and `backlog:drive` launched every number it was given. The label records the
 // judgement once; this applies it to every ask, so it holds without an agent in the loop.

package/scripts/exports/unused-members-cli.ts

@@ -9,7 +9,11 @@ const CHECK = 'exports'
 const FAIL_EXIT_CODE = 1
 // A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
 // `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
-const CONSUMER_SKIP_REASON = 'checks only the kit repository itself, not a consumer project'
+//
+// **Not a skip notice** (joshuafolkken/kit#3162). `SKIP_MARKER` means "a check passed without running",
+// and the gate withholds its green record on it — so a consumer, where this notice prints on every
+// run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
+const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — nothing to check in a consumer project.`
 
 function format_member(root: string, member: NamespaceMember): string {
 	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
@@ -26,7 +30,7 @@ function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
 
 async function run_unused_members(root: string): Promise<number> {
 	if (doctor_consumer.is_kit_consumer(root)) {
-		console.info(project_checks.skip_notice(CHECK, CONSUMER_SKIP_REASON))
+		console.info(CONSUMER_NOTICE)
 
 		return 0
 	}
@@ -48,6 +52,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_unused_members(project_checks.project_root(process.cwd()))
 }
 
-const unused_members_cli = { run_unused_members }
+const unused_members_cli = { run_unused_members, CONSUMER_NOTICE }
 
 export { unused_members_cli }

package/scripts/followup/git-followup-stages.ts

@@ -1,3 +1,4 @@
+import { PrConflictError } from '#scripts/gh/git-pr-checks-eval'
 import { time_format } from '#scripts/time-runtime/time-format'
 
 // Where `pnpm josh followup` spends its own wall clock (joshuafolkken/kit#1349).
@@ -73,8 +74,15 @@ const STAGE = {
 	// blocker and on a red check, and those are the runs whose wait is longest — reporting nothing for
 	// them would leave the measurement blind to exactly the invocations worth measuring.
 	interrupted: 'interrupted',
+	// The interrupted lap when the wait failed on a merge conflict (joshuafolkken/kit#3221), so the
+	// stage block names the cause a resumed session used to look up with `gh pr view`.
+	conflict: 'conflict',
 } as const
 
+function stopped_lap(error: unknown): string {
+	return error instanceof PrConflictError ? STAGE.conflict : STAGE.interrupted
+}
+
 interface FollowupStage {
 	name: string
 	duration_ms: number
@@ -143,6 +151,7 @@ const git_followup_stages = {
 	total_ms,
 	format_stages,
 	print_stages,
+	stopped_lap,
 }
 
 export type { FollowupStage, StageLog }

package/scripts/followup/git-pr-followup.ts

@@ -437,7 +437,7 @@ async function run(input: FollowupInput): Promise<string | undefined> {
 	try {
 		return await run_stages(input, log)
 	} catch (error) {
-		lap(log, STAGE.interrupted)
+		lap(log, git_followup_stages.stopped_lap(error))
 
 		throw error
 	} finally {

package/scripts/gh/git-gh-api-path.ts

@@ -97,10 +97,17 @@ function tag_reference_api_path(tag: string, repo?: string): string {
 	return `${repo_api_path(repo)}/git/ref/tags/${tag}`
 }
 
+// The GitHub Release published for one tag. REST answers 404 until `publish.yml`'s `create-release`
+// job has run, which is what the release command's progress watch asks (joshuafolkken/kit#3193).
+function release_by_tag_api_path(tag: string, repo?: string): string {
+	return `${repo_api_path(repo)}/releases/tags/${tag}`
+}
+
 const git_gh_api_path = {
 	FULL_PAGE_QUERY,
 	repo_api_path,
 	tag_ref_api_path: tag_reference_api_path,
+	release_by_tag_api_path,
 	issues_api_path,
 	issue_api_path,
 	blocked_by_api_path,

package/scripts/gh/git-gh-issue.ts

@@ -26,8 +26,10 @@ const SUMMARY_FIELDS = 'number,title,labels,createdAt'
 // `SUMMARY_FIELDS` on purpose: a listing carries no `blockedBy`, so the field is answered from each
 // row's own dependencies endpoint, and asking for it on the shared list would put that request
 // behind the next-issues display too — where a refused one becomes a failure with no message at all,
-// since the listing swallows the error (joshuafolkken/kit#996, joshuafolkken/kit#1025).
-const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy`
+// since the listing swallows the error (joshuafolkken/kit#996, joshuafolkken/kit#1025). `body` costs
+// no request — the REST listing row already carries it — and is what the backlog offer reads for
+// the restructures each issue declares (joshuafolkken/kit#3221).
+const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body`
 
 // Every listing below goes through the one REST invocation in `git-gh-issue-list.ts`. It kept the
 // `json_fields` / `limit` contract it had as a `gh issue list` wrapper, so these callers changed
@@ -111,7 +113,7 @@ async function issue_list_by_label(label: string, limit: number): Promise<IssueL
 }
 
 // The same filter with the fields the `auto-ok` pickup needs (joshuafolkken/kit#906): it orders by
-// `createdAt` and re-checks `labels` client-side, so bodies would be fetched and thrown away. A
+// `createdAt`, re-checks `labels` client-side and reads each body for its declared restructures. A
 // label that does not exist in the repository is not an error — the listing comes back empty, which
 // is exactly "nobody has opted anything in".
 // `json_fields` overrides the pickup's list. Its only caller is the probe that runs *after* a failed

package/scripts/gh/git-gh-pr-read.ts

@@ -2,6 +2,7 @@ import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { git_gh_helpers } from './git-gh-helpers'
 import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
+import { to_gh_state } from './git-gh-rest-state'
 
 // Reading pull requests through REST, in the answers `gh pr view` used to give.
 //
@@ -81,6 +82,8 @@ interface PullMergeState {
 	is_merged: boolean
 	merged_at: string | undefined
 	head_sha: string | undefined
+	// `josh ship` reads `DIRTY` here to re-merge a conflicting pull request (joshuafolkken/kit#3221).
+	merge_state_status: string | undefined
 }
 
 type PullNumberRead =
@@ -234,6 +237,7 @@ async function pr_get_merge_state(branch_name: string): Promise<PullMergeState |
 		is_merged: git_gh_pr_rest.is_merged(pull),
 		merged_at: pull.merged_at ?? undefined,
 		head_sha: pull.head?.sha,
+		merge_state_status: to_gh_state(pull.mergeable_state),
 	}
 }
 

package/scripts/gh/git-pr-checks-eval.ts

@@ -240,7 +240,14 @@ function is_auto_merge_blocked(snapshot: PrStateSnapshot): boolean {
 	)
 }
 
+// A failed wait whose cause is a merge conflict (joshuafolkken/kit#3221), so `followup` names its last
+// lap `conflict` rather than `interrupted` and the cause is read from the stage block, not looked up.
+class PrConflictError extends Error {
+	override name = 'PrConflictError'
+}
+
 export {
+	PrConflictError,
 	evaluate_pr_state,
 	is_auto_merge_blocked,
 	is_review_decision_decisive,
@@ -251,5 +258,6 @@ export {
 	REQUIRED_CHECKS,
 	CODERABBIT_CHECK_NAME,
 	is_required_check,
+	is_merge_conflict,
 }
 export type { PrEvaluation }

package/scripts/gh/git-pr-checks.ts

@@ -6,7 +6,9 @@ import {
 	describe_pr_failure,
 	evaluate_pr_state,
 	is_auto_merge_blocked,
+	is_merge_conflict,
 	is_review_decision_decisive,
+	PrConflictError,
 	type PrEvaluation,
 } from './git-pr-checks-eval'
 import { parse_pr_state_snapshot, read_string, type PrStateSnapshot } from './git-pr-checks-parse'
@@ -142,6 +144,12 @@ function advance_stable_count(previous: number, state: PrEvaluation): number {
 	return state === 'success' ? previous + 1 : 0
 }
 
+function failure_error(message: string, snapshot: PrStateSnapshot): Error {
+	return is_merge_conflict(snapshot.merge_state_status)
+		? new PrConflictError(message)
+		: new Error(message)
+}
+
 function classify_poll_result(input: {
 	snapshot: PrStateSnapshot
 	stable_count: number
@@ -150,7 +158,9 @@ function classify_poll_result(input: {
 }): { is_done: boolean; next_stable_count: number } {
 	const state = input.evaluator.evaluate(input.snapshot)
 
-	if (state === 'failure') throw new Error(input.evaluator.describe(input.snapshot))
+	if (state === 'failure') {
+		throw failure_error(input.evaluator.describe(input.snapshot), input.snapshot)
+	}
 
 	const next_stable_count = advance_stable_count(input.stable_count, state)
 

package/scripts/git/constants.ts

@@ -12,6 +12,11 @@ const PORCELAIN_FLAG = '--porcelain'
 // The untracked-files mode every porcelain status reading passes (`git-command.ts` carries why it is
 // passed and why it is `all`), shared so another module's own reading cannot drift from it.
 const UNTRACKED_FILES_FLAG = '--untracked-files=all'
+// The git binary a spawn runs in place of the platform's own (joshuafolkken/kit#3234). The spawn path
+// is absolute, so a `git` placed in front on `PATH` never stands in for it: the unit suite's network
+// guard shimmed `git` that way, and `josh ship`'s tests fetched and merged the default branch into the
+// checkout they ran in without the guard ever seeing the call. The guard names its shim here instead.
+const GIT_BINARY_KEY = 'JOSH_GIT_BINARY'
 
 function get_git_command(): string {
 	if (platform() === 'win32') {
@@ -22,6 +27,10 @@ function get_git_command(): string {
 }
 
 function get_git_command_for_spawn(): string {
+	const binary = process.env[GIT_BINARY_KEY]
+
+	if (binary !== undefined && binary !== '') return binary
+
 	if (platform() === 'win32') {
 		return String.raw`C:\Program Files\Git\cmd\git.exe`
 	}
@@ -35,6 +44,7 @@ const git_utilities = {
 }
 
 export {
+	GIT_BINARY_KEY,
 	REQUIRED_STATUS_LENGTH,
 	STAGED_STATUS_INDEX,
 	UNTRACKED_FILE_PREFIX,