@joshuafolkken/kit 1.872.0

package/scripts/git/main-merge-guard.ts

@@ -0,0 +1,134 @@
+import { git_spawn } from './git-spawn'
+
+// What `josh main:merge` refuses before it merges, and what it tells the run to do instead
+// (joshuafolkken/kit#2445).
+//
+// **A dirty tree is not refused as such.** The chain runs `main:merge` before the commit, over the
+// uncommitted implementation, and git carries uncommitted changes through a merge that touches none of
+// them. What goes wrong is the two states git itself cannot merge over — a path both sides changed, and
+// an index still holding unresolved paths. Git's own refusal there names no way forward, and the way a
+// lane child found was a stash round trip around the merge, whose reapply left `UU` in the index and a
+// run asking a person for `git add`. The refusal here is the same condition with the sanctioned way out.
+
+// `XY <path>` — two status letters and a space before the path.
+const STATUS_CODE_LENGTH = 2
+const STATUS_PREFIX_LENGTH = STATUS_CODE_LENGTH + 1
+const RENAME_SEPARATOR = ' -> '
+const UNMERGED_CODES = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'])
+// The index column of a line whose path has nothing staged — unchanged, untracked, or ignored.
+const UNSTAGED_INDEX_CODES = new Set([' ', '?', '!'])
+const DIRECTORY_SUFFIX = '/'
+const COMMIT_COMMAND = '`pnpm josh git -y`'
+const PROCEDURE_POINTER =
+	'`.claude/skills/workflow-commands/chain-rule.md` → "origin/main is merged in before the gate"'
+
+function status_lines(status: string): Array<string> {
+	return status.split('\n').filter((line) => line.length > STATUS_PREFIX_LENGTH)
+}
+
+// A rename line names both sides; either one is a path the merge could collide with.
+function line_paths(line: string): Array<string> {
+	return line.slice(STATUS_PREFIX_LENGTH).split(RENAME_SEPARATOR)
+}
+
+function unmerged_paths(status: string): Array<string> {
+	return status_lines(status)
+		.filter((line) => UNMERGED_CODES.has(line.slice(0, STATUS_CODE_LENGTH)))
+		.flatMap((line) => line_paths(line))
+}
+
+// Git's ort strategy refuses a merge whenever the index differs from HEAD, whatever paths the staged
+// changes touch — a stash reapply that conflicted leaves its merged half staged in exactly this way.
+function staged_paths(status: string): Array<string> {
+	return status_lines(status)
+		.filter((line) => !UNSTAGED_INDEX_CODES.has(line.charAt(0)))
+		.flatMap((line) => line_paths(line))
+}
+
+// An untracked directory is reported as `dir/`, so it covers every incoming path beneath it.
+function covers(uncommitted: string, incoming: string): boolean {
+	if (uncommitted.endsWith(DIRECTORY_SUFFIX)) return incoming.startsWith(uncommitted)
+
+	return uncommitted === incoming
+}
+
+function overlapping_paths(status: string, incoming: ReadonlyArray<string>): Array<string> {
+	const uncommitted = status_lines(status).flatMap((line) => line_paths(line))
+
+	return uncommitted.filter((path) => incoming.some((changed) => covers(path, changed)))
+}
+
+function unmerged_message(paths: ReadonlyArray<string>): string {
+	return (
+		`main:merge: the index still holds unresolved paths (${paths.join(', ')}). Remove the conflict ` +
+		`markers, then finish through ${COMMIT_COMMAND} — it stages and commits them, so no \`git add\` ` +
+		`permission is needed, and inside a lane this is Tier A. Rerun \`pnpm josh main:merge\` after it ` +
+		`(${PROCEDURE_POINTER}).`
+	)
+}
+
+function staged_message(paths: ReadonlyArray<string>): string {
+	return (
+		`main:merge: the index holds staged changes (${paths.join(', ')}), which git refuses to merge ` +
+		`over. Commit them first through ${COMMIT_COMMAND}, then rerun \`pnpm josh main:merge\` ` +
+		`(${PROCEDURE_POINTER}).`
+	)
+}
+
+function overlap_message(default_branch: string, paths: ReadonlyArray<string>): string {
+	return (
+		`main:merge: uncommitted changes touch files origin/${default_branch} also changed ` +
+		`(${paths.join(', ')}). Commit the work first through ${COMMIT_COMMAND}, then rerun ` +
+		`\`pnpm josh main:merge\`. Never stash around the merge — a stash reapplied over it leaves the ` +
+		`conflict half-recorded in the index (${PROCEDURE_POINTER}).`
+	)
+}
+
+// Appended to git's own report when the merge itself stops on a conflict.
+const CONFLICT_HINT =
+	`main:merge: finish a conflicted merge by removing the conflict markers, then ${COMMIT_COMMAND} ` +
+	`records the merge commit — no \`git add\` permission is needed (${PROCEDURE_POINTER}).`
+
+function refusal(
+	status: string,
+	incoming: ReadonlyArray<string>,
+	default_branch: string,
+): string | undefined {
+	const unmerged = unmerged_paths(status)
+
+	if (unmerged.length > 0) return unmerged_message(unmerged)
+	// Nothing incoming means git answers "Already up to date" whatever the index holds.
+	if (incoming.length === 0) return undefined
+
+	const staged = staged_paths(status)
+
+	if (staged.length > 0) return staged_message(staged)
+
+	const overlap = overlapping_paths(status, incoming)
+
+	return overlap.length > 0 ? overlap_message(default_branch, overlap) : undefined
+}
+
+// The paths the default branch changed since this branch left it — what the merge would bring in.
+// `--no-renames` lists both sides of a rename, so an edit to the old name still counts as an overlap.
+async function incoming_paths(default_branch: string): Promise<Array<string>> {
+	const output = await git_spawn.read([
+		'diff',
+		'--name-only',
+		'--no-renames',
+		`HEAD...origin/${default_branch}`,
+	])
+
+	return output.split('\n').filter((line) => line !== '')
+}
+
+const main_merge_guard = {
+	CONFLICT_HINT,
+	incoming_paths,
+	overlapping_paths,
+	refusal,
+	staged_paths,
+	unmerged_paths,
+}
+
+export { main_merge_guard }

package/scripts/git/main-merge.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { extract_issue_number } from '#scripts/hooks/check-commit-message'
+import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { git_command } from './git-command'
+import { main_merge_guard } from './main-merge-guard'
+
+// `josh main:merge` (`josh mm`) — bring the default branch into the branch this checkout is on
+// (joshuafolkken/kit#1659).
+//
+// **It stopped being a `git pull` because `git pull` cannot decide anything on a diverged branch.**
+// With neither `pull.rebase` nor `pull.ff` set — the state of a checkout nobody has configured — git
+// refuses the moment the two sides have each moved:
+//
+//     fatal: Need to specify how to reconcile divergent branches
+//
+// Divergence is not the edge case here; it is the entire reason to type this command. A lane whose
+// branch has fallen behind `origin/<default>` has its own commits on it by definition, so **the one
+// state the command exists for was the one state it could not run in.**
+//
+// The strategy is therefore named by this file rather than read out of whoever's git configuration
+// happens to be in force: **fetch, then merge `origin/<default>` into the current branch.** Merging
+// rather than rebasing is joshuafolkken/kit#1446's decision and not a fresh one — a rebase rewrites
+// commits that are already pushed, so it needs a force push, which `.claude/settings.json` denies.
+//
+// `git_command.merge_fast_forward` is deliberately not reused: it passes `--ff-only`, which fails
+// loudly on exactly the divergence this command has to absorb.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const COMMAND_NAME = 'main:merge'
+
+// git's default merge message carries no `#N`, so on an issue branch the `commit-msg` hook refuses
+// it and leaves the index mid-merge (joshuafolkken/kit#2439). The number is read with the hook's
+// own parser, so the message this writes is exactly the one that hook accepts; a branch without a
+// number keeps git's default.
+function merge_message(default_branch: string, current_branch: string): string | undefined {
+	const issue_number = extract_issue_number(current_branch)
+
+	if (issue_number === undefined) return undefined
+
+	return `Merge ${default_branch} into ${current_branch} #${issue_number}`
+}
+
+// The refusal is read after the fetch, so the incoming paths are the ones the merge would bring in
+// (joshuafolkken/kit#2445).
+async function merge_refusal(default_branch: string): Promise<string | undefined> {
+	const status = await git_command.status()
+	const incoming = await main_merge_guard.incoming_paths(default_branch)
+
+	return main_merge_guard.refusal(status, incoming, default_branch)
+}
+
+// A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
+// the sanctioned commit rather than a request for `git add`.
+async function merge_with_hint(default_branch: string, message: string | undefined): Promise<void> {
+	try {
+		await git_command.merge_branch(default_branch, message)
+	} catch (error) {
+		console.error(main_merge_guard.CONFLICT_HINT)
+		throw error
+	}
+}
+
+// The fetch is what makes `origin/<default>` current before the merge reads it. `git pull` did the
+// two together, which is the only thing it was doing here that is worth keeping.
+async function merge_default_branch(): Promise<number> {
+	const default_branch = await git_command.get_default_branch()
+	const current_branch = await git_command.branch()
+
+	await git_command.fetch_branch(default_branch)
+
+	const refusal = await merge_refusal(default_branch)
+
+	if (refusal !== undefined) {
+		console.error(refusal)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	await merge_with_hint(default_branch, merge_message(default_branch, current_branch))
+	console.info(default_branch)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// The argument refusal is kept even though this is no longer an `sh -c` entry: the message is the
+// same one every composite prints, and silently discarding a flag is what it exists to prevent.
+async function dispatch(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) {
+		console.error(composite_arguments.format_rejection(COMMAND_NAME, []))
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	return await merge_default_branch()
+}
+
+// A git failure — a merge conflict, a remote that cannot be reached — is reported as a message
+// rather than a stack trace, matching every other josh CLI.
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	try {
+		return await dispatch(argv)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const main_merge = { COMMAND_NAME, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { main_merge }

package/scripts/git/main-sync.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { git_command } from './git-command'
+import { gone_branch, type PruneResult } from './gone-branch'
+
+// `josh main:sync` (`josh ms`) — return this checkout to the default branch and pull
+// (joshuafolkken/kit#1535), then prune the local branches whose merged remote branch is gone
+// (joshuafolkken/kit#2504; the rule for which ones is `gone-branch.ts`).
+//
+// **It refuses inside a linked work tree, and that refusal is the reason this stopped being a
+// one-line `sh -c` entry.** The default branch is a *branch*: advancing it means checking it out
+// somewhere, and git allows one branch in one work tree at a time. Run from a lane, `git checkout
+// <default>` therefore does two things nobody asked for — measured on 2026-09-07 while five lanes
+// were open:
+//
+// 1. **The lane stops being a lane.** `lane:list` matches on the branch name, so the work tree drops
+//    out of the listing, `lane:close` can no longer reach it, and the port seat its `.env` holds is
+//    never reclaimed.
+// 2. **Every other lane's `josh ms` then fails**, with `fatal: '<default>' is already used by
+//    worktree at '<the hijacked lane>'` — one lane's tidy-up step breaks the other four.
+//
+// A lane's terminal step is `pnpm josh lane:close <issue-number>`; the refusal says so. Nothing about
+// the main work tree's behavior changes.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const COMMAND_NAME = 'main:sync'
+
+// `git_directories()` returns `[--absolute-git-dir, --git-common-dir]`. They are the same path in the
+// main work tree and differ in a linked one, which is git's own definition of the distinction rather
+// than a guess from a directory name.
+const OWN_GIT_DIRECTORY = 0
+const COMMON_GIT_DIRECTORY = 1
+
+// The refusal covers every linked work tree, not lanes alone, because the hijack is a property of
+// the work tree rather than of what opened it. It names both ways out for that reason.
+const LANE_REFUSAL = [
+	`josh ${COMMAND_NAME} cannot run inside a linked work tree.`,
+	'Checking the default branch out here takes it from whichever work tree holds it, and a lane that loses its own branch drops out of `josh lane:list` with its port seat still allocated.',
+	'Run `pnpm josh ms` in the primary checkout instead; a lane is finished with `pnpm josh lane:close <issue-number>`.',
+].join('\n')
+
+async function is_linked_work_tree(): Promise<boolean> {
+	const directories = await git_command.git_directories()
+
+	return directories[OWN_GIT_DIRECTORY] !== directories[COMMON_GIT_DIRECTORY]
+}
+
+// The count rather than the names: the first run on a long-lived checkout removes hundreds. A branch
+// `git branch -d` refused is named, because that one is left for a person to look at.
+function report_prune(result: PruneResult): void {
+	if (result.deleted.length > 0) {
+		console.info(`pruned ${String(result.deleted.length)} merged branch(es) whose remote is gone`)
+	}
+
+	for (const name of result.failed) console.error(`kept ${name}: git branch -d refused it`)
+}
+
+// The sync has already succeeded when the prune runs, so a prune that cannot finish — a fetch that
+// loses the network, a git too old for `%(worktreepath)` — is reported and does not turn the exit code
+// into the one a failed checkout or pull gives.
+async function prune_quietly(default_branch: string): Promise<void> {
+	try {
+		report_prune(await gone_branch.prune(default_branch))
+	} catch (error) {
+		console.error(`branch prune skipped: ${error instanceof Error ? error.message : String(error)}`)
+	}
+}
+
+async function synchronize(): Promise<number> {
+	const default_branch = await git_command.get_default_branch()
+
+	await git_command.checkout(default_branch)
+	await git_command.pull_fast_forward()
+	await prune_quietly(default_branch)
+	console.info(default_branch)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// The argument refusal is kept even though this is no longer an `sh -c` entry: the message is the
+// same one every composite prints, and silently discarding a flag is what it exists to prevent.
+async function dispatch(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) {
+		console.error(composite_arguments.format_rejection(COMMAND_NAME, []))
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	if (await is_linked_work_tree()) {
+		console.error(LANE_REFUSAL)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await synchronize()
+}
+
+// A git failure — a dirty tree the checkout refuses to leave, a pull that cannot reach the remote —
+// is reported as a message rather than a stack trace, matching every other josh CLI.
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	try {
+		return await dispatch(argv)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const main_sync = { COMMAND_NAME, LANE_REFUSAL, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { main_sync }

package/scripts/git/parse-json-array.ts

@@ -0,0 +1,102 @@
+import type { z } from 'zod'
+
+// Marks input that is not JSON at all, letting each caller pick its own empty value. Schema
+// mismatches are deliberately not folded in here: those rethrow, so a shape change stays visible
+// instead of silently degrading to a fallback.
+const MALFORMED_JSON = Symbol('malformed-json')
+
+function parse_json_loose(raw_json: string): unknown {
+	try {
+		return JSON.parse(raw_json)
+	} catch (error) {
+		if (error instanceof SyntaxError) return MALFORMED_JSON
+		throw error
+	}
+}
+
+/**
+ * Parse a JSON string into an array validated by the given element schema.
+ * Malformed JSON yields undefined, so a caller can tell it apart from an empty listing.
+ *
+ * `parse_json_array_safe` answers `[]` for both, which reads as "there is nothing" — and a command
+ * that acts on that reports a confident absence built on a response it could not parse
+ * (joshuafolkken/kit#950).
+ */
+function parse_json_array_or_undefined<T>(
+	raw_json: string,
+	element_schema: z.ZodType<T>,
+): Array<T> | undefined {
+	const value = parse_json_loose(raw_json)
+	// Not an array at all — `gh` answering `{"message":"API rate limit exceeded"}` rather than a
+	// listing. That is the same kind of gap as unparseable output, not a change in the shape of the
+	// elements, so it reads as unreadable instead of throwing out of the command.
+	if (value === MALFORMED_JSON || !Array.isArray(value)) return undefined
+
+	return element_schema.array().parse(value)
+}
+
+// What one listing read produced. The two gaps are deliberately apart: JSON that is not a listing at
+// all is an access or connectivity problem, while elements the schema rejects mean the tool's fields
+// changed — and those send a reader to two different places (joshuafolkken/kit#996). A caller that
+// treats them the same still reads them from here rather than writing the try/catch again.
+type ListingRead<T> =
+	{ kind: 'read'; rows: Array<T> } | { kind: 'unreadable' } | { kind: 'unexpected_shape' }
+
+/**
+ * Parse a listing, telling the two gaps apart.
+ *
+ * The rethrow `parse_json_array_or_undefined` performs is the whole point, and every caller that
+ * wants both gaps named was catching it itself — the `auto-ok` pickup and `epic:next`'s
+ * repository-level busy check wrote the same six lines (joshuafolkken/kit#925).
+ */
+function read_json_listing<T>(raw_json: string, element_schema: z.ZodType<T>): ListingRead<T> {
+	try {
+		const rows = parse_json_array_or_undefined(raw_json, element_schema)
+
+		return rows === undefined ? { kind: 'unreadable' } : { kind: 'read', rows }
+	} catch {
+		return { kind: 'unexpected_shape' }
+	}
+}
+
+/**
+ * Parse a JSON string into an array validated by the given element schema.
+ * Malformed JSON yields an empty array.
+ *
+ * Deliberately **not** `parse_json_array_or_undefined(...) ?? []`, near-identical though the bodies
+ * are. The two differ on the branch that matters: valid JSON that is not an array throws here, so a
+ * `gh` field that changed shape stays visible, while the variant above reads it as a gap. Folding
+ * them together silences that throw for every existing caller (joshuafolkken/kit#950).
+ */
+function parse_json_array_safe<T>(raw_json: string, element_schema: z.ZodType<T>): Array<T> {
+	const value = parse_json_loose(raw_json)
+	if (value === MALFORMED_JSON) return []
+
+	return element_schema.array().parse(value)
+}
+
+/**
+ * Parse a JSON string into a single object validated by the given schema.
+ * Malformed JSON yields undefined.
+ */
+function parse_json_object_safe<T>(raw_json: string, schema: z.ZodType<T>): T | undefined {
+	const value = parse_json_loose(raw_json)
+	if (value === MALFORMED_JSON) return undefined
+
+	return schema.parse(value)
+}
+
+const parse_json = {
+	parse_json_array_safe,
+	parse_json_array_or_undefined,
+	parse_json_object_safe,
+	read_json_listing,
+}
+
+export {
+	parse_json,
+	parse_json_array_or_undefined,
+	parse_json_array_safe,
+	parse_json_object_safe,
+	read_json_listing,
+}

package/scripts/git/schemas.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod'
+
+const package_name_schema = z.object({ name: z.string().min(1) })
+
+const rollup_item_schema = z.looseObject({
+	// eslint-disable-next-line @typescript-eslint/naming-convention -- GraphQL field name from GitHub API
+	__typename: z.string().optional(),
+	state: z.string().optional(),
+	status: z.string().optional(),
+	conclusion: z.string().optional(),
+	name: z.string().optional(),
+	context: z.string().optional(),
+})
+
+const pr_raw_schema = z.object({
+	statusCheckRollup: z.array(rollup_item_schema).optional(),
+	mergeStateStatus: z.string().optional(),
+	reviewDecision: z.string().optional(),
+})
+
+const pull_comment_schema = z.object({
+	body: z.string().optional(),
+	html_url: z.string().optional(),
+	user: z.object({ login: z.string().optional() }).optional(),
+})
+
+const ai_review_pull_comment_schema = z.object({
+	body: z.string().optional(),
+	url: z.string().optional(),
+	author: z.object({ login: z.string().optional() }).optional(),
+})
+
+const pr_info_schema = z.object({
+	mergeable: z.union([z.boolean(), z.string()]).nullable().optional(),
+	mergeStateStatus: z.string().nullable().optional(),
+	state: z.string().optional(),
+})
+
+const epic_issue_schema = z.object({
+	number: z.number(),
+	body: z.string().optional(),
+})
+
+// One blocker as `gh` reports it inside the `blockedBy` connection. `state` comes back with the
+// number, so telling a resolved blocker from a standing one costs no extra request
+// (joshuafolkken/kit#996).
+// `number` is **required**. Relaxing it looks harmless and is not: `epic_issue.blockers_of` maps the
+// nodes to their numbers, so an optional one turns a `blockedBy` shape change from a failed parse —
+// which marks the child unreadable — into an empty blocker list, and `epic:next` then hands a
+// dependent to an unattended run before its prerequisite. Fail-safe is the direction that matters
+// here (joshuafolkken/kit#1005).
+//
+// `repository_url` is the repository the blocker lives in, as REST names it
+// (`https://api.github.com/repos/<owner>/<repo>`). Carried since joshuafolkken/kit#1126: a
+// `blocked-by` relation may cross a repository, and a reader that keeps only the number resolves it
+// against the blocked child's own repository — a different issue, or none. Optional because a
+// caller that only wants numbers must not be made to fail on a response shape it never reads.
+const blocking_issue_schema = z.object({
+	number: z.number(),
+	state: z.string().optional(),
+	repository_url: z.string().optional(),
+})
+
+// The blocker relations arrive as a connection — `{ nodes, totalCount }` — not a bare array.
+// Measured against a real issue rather than assumed (joshuafolkken/kit#860). `gh issue view`
+// answered the connection itself; since joshuafolkken/kit#1024 REST serves a bare array from the
+// issue's own `dependencies/blocked_by` endpoint and `git-gh-issue-rest.ts` maps it back into this
+// shape, so every reader below is unchanged.
+//
+// **One definition, every reader.** The same connection was written out three times — twice here and
+// once in `scripts/epic/epic-issue.ts` — each naming only the fields its own caller happened to want,
+// so a shape change had three places to reach and one of them would not be noticed. That is the
+// duplication joshuafolkken/kit#862 removed from the epic commands, reintroduced by the readers that
+// came after (joshuafolkken/kit#1005).
+//
+// `nodes` is a page — `blockedBy(first:50)` under GraphQL, one unpaged `per_page=100` request under
+// REST — while `totalCount` is exact, read from the issue's own dependency summary. A reader that
+// compares them can tell a complete page from a truncated one, with one exception: where GitHub
+// reports no summary at all the count falls back to the page's own size, and a truncated page then
+// reads as complete. Every issue the reads go through carries one, so that is a guard rather than
+// a case. **Only the `auto-ok` pickup compares them**; the epic readers judge from the page they
+// were given, so an epic child declaring more blockers than one page holds is read from the first
+// page. Carried here so the field is available, not because every reader consults it
+// (joshuafolkken/kit#1005).
+const blocked_by_schema = z
+	.object({
+		nodes: z.array(blocking_issue_schema).default([]),
+		totalCount: z.number().optional(),
+	})
+	.optional()
+
+const epic_child_schema = z.object({
+	state: z.string().optional(),
+	blockedBy: blocked_by_schema,
+})
+
+// One conversation comment as `repos/{owner}/{repo}/issues/{N}/comments` serves it — the listing
+// both the AI-review scan and the epic auto-close read.
+//
+// Carried here rather than beside either reader: the pull request's conversation comments and an
+// epic's are the *same endpoint* answering the same objects, so a second declaration of this shape
+// would be the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1039). `ai_review_pull_comment_schema`
+// above is the `gh --json` spelling the scan reads after the mapping, not this one.
+const rest_comment_schema = z.looseObject({
+	body: z.string().nullish(),
+	html_url: z.string().optional(),
+	user: z.looseObject({ login: z.string().optional() }).nullish(),
+})
+
+// The `number,state,labels,body` read, for the epic check and the `--add` closed-epic refusal.
+// Labels come back as objects, so the name is picked out here rather than at every call site.
+const issue_label_schema = z.object({ name: z.string() })
+
+// `state` is optional because most readers ignore it — only `git-epic-add.ts` consults it, to refuse
+// adding a child to a closed epic (joshuafolkken/kit#2337). A reader that never asks the state field
+// still parses cleanly.
+const epic_subject_schema = z.object({
+	number: z.number(),
+	state: z.string().optional(),
+	labels: z.array(issue_label_schema).optional(),
+	body: z.string().optional(),
+})
+
+// One row of an open-issue listing, under the field names `gh issue list --json` answered with.
+// Three readers parse a listing through this shape: the next-issues display printed when a workflow
+// completes (#821), the `auto-ok` pickup (joshuafolkken/kit#906), and the per-repository busy check
+// `epic:next` makes before it offers a child (joshuafolkken/kit#925).
+//
+// The row is *assembled* under those names rather than returned under them. Since
+// joshuafolkken/kit#1025 the listing is REST, and `blockedBy` is not part of a listing response at
+// all: `git-gh-issue-list.ts` reads the relations from each row's own dependencies endpoint, and
+// only for the pickup, which is the one caller whose field list names `blockedBy` at all.
+//
+// So `blockedBy` is optional for the reason it is absent in practice — the display and the busy
+// check never ask for it, and a field that was not asked for is left out of the mapped row rather
+// than filled in.
+const open_issue_schema = z.object({
+	number: z.number(),
+	title: z.string(),
+	labels: z.array(issue_label_schema).optional(),
+	createdAt: z.string(),
+	blockedBy: blocked_by_schema,
+})
+
+type RollupItemData = z.infer<typeof rollup_item_schema>
+type EpicChildData = z.infer<typeof epic_child_schema>
+type OpenIssueData = z.infer<typeof open_issue_schema>
+type RestCommentData = z.infer<typeof rest_comment_schema>
+
+export {
+	package_name_schema,
+	rollup_item_schema,
+	pr_raw_schema,
+	pull_comment_schema,
+	rest_comment_schema,
+	ai_review_pull_comment_schema,
+	pr_info_schema,
+	epic_issue_schema,
+	issue_label_schema,
+	epic_child_schema,
+	epic_subject_schema,
+	open_issue_schema,
+	blocking_issue_schema,
+	blocked_by_schema,
+}
+export type { RollupItemData, EpicChildData, OpenIssueData, RestCommentData }