@joshuafolkken/kit 1.872.0

package/scripts/git/github-issue-url.ts

@@ -0,0 +1,105 @@
+// Reading a GitHub issue or pull-request URL as an identity: which repository it is in, and which
+// number. `josh notify` resolves the repository a notification is *about* this way, because the
+// working directory answers a different question — which repository the session happens to be
+// running in. A notification filed about another repository used to carry that repository's URL
+// under this repository's name (joshuafolkken/kit#903), and the same mismatch survived for a
+// notification carrying only a pull-request URL until joshuafolkken/kit#994 added the second form
+// here rather than beside it.
+//
+// Two other modules read a URL for something narrower and keep their own patterns. `git-epic-parse`
+// scans an epic body for task-list rows, so its regex is anchored to the row marker and runs
+// globally over a document; `propagate-steps` takes the trailing number of whatever URL
+// `gh issue create` just printed, where the repository is already known. This one is for a caller
+// holding a single URL and needing the repository it names.
+const NAME_WITH_OWNER_SEPARATOR = '/'
+const GITHUB_URL_PREFIX = 'https://github.com/'
+// The prefix as regex source, so the host is written once and the two patterns below cannot drift
+// apart from it or from each other. Only the dots need escaping in a URL of this shape.
+const GITHUB_URL_PREFIX_SOURCE = GITHUB_URL_PREFIX.replaceAll('.', String.raw`\.`)
+const REPOSITORY_SOURCE = `^${GITHUB_URL_PREFIX_SOURCE}([^/]+)/([^/]+)`
+// `\b` after the number, so `.../issues/431x` is refused rather than read as issue 431 — the
+// caller's fallback is the working directory, which is a visibly wrong answer rather than a
+// plausible one. A trailing `#anchor` or `?query` still parses, since neither is a word character.
+const ISSUE_URL_PATTERN = new RegExp(String.raw`${REPOSITORY_SOURCE}/issues/(\d+)\b`, 'u')
+// The same shape for a pull request. `git-pr-followup` used to carry its own copy of this, anchored
+// to the end of the string; reading `.../pull/12/files` now yields the repository it names instead
+// of nothing, which is the better answer for every caller (joshuafolkken/kit#994).
+const PULL_URL_PATTERN = new RegExp(String.raw`${REPOSITORY_SOURCE}/pull/(\d+)\b`, 'u')
+
+// What both forms answer: which repository the URL names.
+interface RepoIdentity {
+	owner: string
+	repo: string
+	// `owner/repo`, the form a repository-scoped REST path takes — kept beside the parts so no caller
+	// re-joins them.
+	name_with_owner: string
+	// `https://github.com/owner/repo`, so a caller building a sibling URL does not rebuild the host.
+	base_url: string
+}
+
+// The two forms carry their number under different names on purpose. A pull target is then not
+// assignable where an issue target is expected, so handing a PR number to a reader that asks the
+// issue endpoint is a compile error rather than a notification carrying an unrelated issue's title
+// — the joshuafolkken/kit#903 mismatch class, which this module exists to close.
+interface IssueUrlTarget extends RepoIdentity {
+	issue_number: string
+}
+
+interface PullUrlTarget extends RepoIdentity {
+	pull_number: string
+}
+
+// `undefined` for anything that is not a github.com issue URL, including an absent one: every
+// caller's fallback is the same either way, so a thrown error would only move the branch.
+//
+// The destructuring defaults in `build_target` are unreachable — a match fills all three groups —
+// and exist because `noUncheckedIndexedAccess` types them as optional.
+interface ParsedUrl {
+	target: RepoIdentity
+	number: string
+}
+
+function build_target(match: RegExpExecArray): ParsedUrl {
+	const [, owner = '', repo = '', number = ''] = match
+
+	const name_with_owner = `${owner}${NAME_WITH_OWNER_SEPARATOR}${repo}`
+
+	return {
+		target: {
+			owner,
+			repo,
+			name_with_owner,
+			base_url: `${GITHUB_URL_PREFIX}${name_with_owner}`,
+		},
+		number,
+	}
+}
+
+function parse_with(pattern: RegExp, url: string | undefined): ParsedUrl | undefined {
+	const match = pattern.exec(url ?? '')
+	if (match === null) return undefined
+
+	return build_target(match)
+}
+
+function parse(issue_url: string | undefined): IssueUrlTarget | undefined {
+	const parsed = parse_with(ISSUE_URL_PATTERN, issue_url)
+	if (parsed === undefined) return undefined
+
+	return { ...parsed.target, issue_number: parsed.number }
+}
+
+// A pull-request URL names the same repository an issue URL does. `josh notify` reads it when it was
+// given no `--issue-url`, so a completion notification carrying only a PR link stops being filed
+// under the working directory's repository (joshuafolkken/kit#994).
+function parse_pull(pull_url: string | undefined): PullUrlTarget | undefined {
+	const parsed = parse_with(PULL_URL_PATTERN, pull_url)
+	if (parsed === undefined) return undefined
+
+	return { ...parsed.target, pull_number: parsed.number }
+}
+
+const github_issue_url = { parse, parse_pull }
+
+export { github_issue_url }
+export type { IssueUrlTarget, RepoIdentity }

package/scripts/git/gone-branch.ts

@@ -0,0 +1,113 @@
+import { git_spawn } from './git-spawn'
+
+// The local branches `josh ms` removes after it syncs (joshuafolkken/kit#2504). The repository
+// deletes a pull request's remote branch at the merge, and nothing removed the local copy: measured on
+// 2026-09-24, 212 of the primary checkout's 244 local branches tracked an upstream that was `[gone]`.
+//
+// **A branch is removed only when all three hold** — its upstream is gone, it is merged into the
+// default branch, and no work tree has it checked out. Gone alone is not enough: a branch whose remote
+// was deleted by hand before its work merged still holds the only copy of it. A branch with no
+// upstream at all is never gone, so a local-only branch stays.
+//
+// **One `for-each-ref` read carries the work-tree answer too** — `%(worktreepath)` is git's own
+// record of which tree holds the branch, so no `git worktree list` parse is repeated here.
+
+const FIELD_SEPARATOR = '\t'
+const GONE_TRACK = '[gone]'
+// `lstrip=2` rather than `short`: `short` prints `heads/<name>` for a branch whose name a tag shares,
+// and `git branch -d` would then be handed a name it cannot find.
+const BRANCH_NAME = '%(refname:lstrip=2)'
+const RECORD_FORMAT = [BRANCH_NAME, '%(upstream:track)', '%(upstream)', '%(worktreepath)'].join(
+	FIELD_SEPARATOR,
+)
+const LOCAL_HEADS = 'refs/heads'
+const REMOTE_HEADS = 'refs/remotes/'
+const FOR_EACH_REF = 'for-each-ref'
+const NAME_FIELD = 0
+const TRACK_FIELD = 1
+const UPSTREAM_FIELD = 2
+const WORKTREE_FIELD = 3
+
+interface BranchRecord {
+	name: string
+	is_gone: boolean
+	is_checked_out: boolean
+}
+
+interface PruneResult {
+	deleted: Array<string>
+	failed: Array<string>
+}
+
+function non_empty_lines(output: string): Array<string> {
+	return output.split('\n').filter((line) => line.trim() !== '')
+}
+
+function parse_record(line: string): BranchRecord {
+	const fields = line.split(FIELD_SEPARATOR)
+
+	return {
+		name: fields[NAME_FIELD] ?? '',
+		is_gone:
+			fields[TRACK_FIELD] === GONE_TRACK && (fields[UPSTREAM_FIELD] ?? '').startsWith(REMOTE_HEADS),
+		is_checked_out: (fields[WORKTREE_FIELD] ?? '') !== '',
+	}
+}
+
+function parse_records(output: string): Array<BranchRecord> {
+	return non_empty_lines(output).map((line) => parse_record(line))
+}
+
+function select_prunable(
+	records: ReadonlyArray<BranchRecord>,
+	merged: ReadonlySet<string>,
+	default_branch: string,
+): Array<string> {
+	return records
+		.filter((record) => record.is_gone && !record.is_checked_out && merged.has(record.name))
+		.map((record) => record.name)
+		.filter((name) => name !== default_branch)
+}
+
+async function read_candidates(default_branch: string): Promise<Array<string>> {
+	const records = await git_spawn.read([FOR_EACH_REF, `--format=${RECORD_FORMAT}`, LOCAL_HEADS])
+	const merged = await git_spawn.read([
+		FOR_EACH_REF,
+		`--merged=refs/heads/${default_branch}`,
+		`--format=${BRANCH_NAME}`,
+		LOCAL_HEADS,
+	])
+
+	return select_prunable(parse_records(records), new Set(non_empty_lines(merged)), default_branch)
+}
+
+// `-d` rather than `-D` is the second net under the merged check: git refuses a branch it does not
+// itself see as merged, so a disagreement between the two reads leaves the branch rather than a lost
+// commit. One refusal does not stop the rest, and is reported rather than thrown.
+async function delete_each(names: ReadonlyArray<string>): Promise<PruneResult> {
+	const result: PruneResult = { deleted: [], failed: [] }
+
+	for (const name of names) {
+		try {
+			await git_spawn.read(['branch', '-d', name])
+			result.deleted.push(name)
+		} catch {
+			result.failed.push(name)
+		}
+	}
+
+	return result
+}
+
+// `fetch --prune` first, because `[gone]` is read from the remote-tracking refs and those outlive the
+// remote branch until something prunes them.
+async function prune(default_branch: string): Promise<PruneResult> {
+	await git_spawn.read(['fetch', '--prune'])
+
+	return await delete_each(await read_candidates(default_branch))
+}
+
+const gone_branch = { parse_records, prune, select_prunable }
+
+export type { BranchRecord, PruneResult }
+export { gone_branch }

package/scripts/git/issue-labels.ts

@@ -0,0 +1,279 @@
+// The workflow label names, defined once. The epic auto-close, the epic validator, the issue-prep
+// labeler and the next-issues display all key on these exact strings, and a drifted copy would
+// fail silently — an epic filtered on the wrong name is simply never closed or never excluded.
+const EPIC_LABEL = 'epic'
+const IN_PROGRESS_LABEL = 'in-progress'
+// Parks a child that cannot advance without a person deciding something. `epic:next` is what reads
+// it: a parked child is why a run reports "nothing left that time will fix" rather than waiting
+// forever (joshuafolkken/kit#860).
+const NEEDS_DECISION_LABEL = 'needs-decision'
+// Opts one issue outside any epic into unattended execution (joshuafolkken/kit#906). **Only a
+// person applies it.** `epicrun #<E>` approves the merges inside `#<E>`; this label is the only way
+// a person extends that approval past the epic's edge, so a label an AI could apply to itself would
+// let an unattended run widen its own authorization — which is not a guard at all.
+const AUTO_OK_LABEL = 'auto-ok'
+// Degrades one issue's run to a `halfrun`-shaped stop: it is implemented and taken through the
+// verification gate, and then nothing is committed, pushed, opened as a pull request or merged
+// (joshuafolkken/kit#1125). **Only a person applies it**, exactly as strongly as `auto-ok` — a mark a
+// run could clear for itself is not a mark.
+//
+// It is the opposite of `auto-ok` in what it does and its twin in who may apply it: one widens
+// unattended execution past an epic's edge, the other withholds the last step of it. `auto-ok`
+// answers "may this run at all", this one answers "may its result ship without a person looking".
+//
+// **Not `needs-decision`, and the difference is what the two sets below encode.** A parked issue is
+// one a run must not *start*; this one is started, and only its ending is withheld. So it stays out
+// of `NOT_DIRECTLY_RUNNABLE_LABELS` — an issue nobody would ever offer cannot be implemented — and
+// out of `epic-busy.ts`'s parked set, because a stopped child leaves uncommitted work in the
+// checkout and must go on holding the repository. Read as parked in either place, the next child
+// would start on top of that work.
+const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
+// Marks an issue whose work a run verified is **already merged** (joshuafolkken/kit#1679). Closing
+// an Issue is Tier C, so a run that reaches that conclusion may not act on it — and before this
+// label there was no exit that was not Tier C: `fullrun #1656` verified the work was already in
+// `main` from joshuafolkken/kit#1623 and closed the Issue itself.
+//
+// **It is not `needs-decision`, and the difference is the whole reason it exists.** A parked issue
+// waits for an answer nobody has given; this one has its answer already — the work is done, and all
+// that is left is the close, which is a person's. Parked, it goes back into the offer the moment a
+// person clears the label, and the next run repeats the same investigation.
+//
+// **Only a person removes it, by closing the issue.** A run applies it; nothing in the workflow
+// takes it off, because taking it off asserts the work is *not* done, which is the same claim in
+// reverse and is no more a run's to make.
+const ALREADY_DONE_LABEL = 'already-done'
+
+// The four labels that mean an open issue must not be handed to a run as it stands: an `epic`
+// tracks a batch and is never run directly (its children are), `in-progress` is already claimed by
+// a running workflow, `needs-decision` was parked precisely because it cannot advance without a
+// person, and `already-done` names work that is already merged. Held here rather than in either
+// caller because both the next-issues display and the `auto-ok` pickup ask the same question, and
+// two copies would answer it differently the first time one of them gained another label.
+//
+// **`needs-human-review` is deliberately not among them.** It withholds the end of a run, not its
+// start: an issue carrying it is implemented and verified like any other and only stops before the
+// commit. Excluded here it would never be offered, so the work it asks a person to look at would
+// never be produced — the label would silently become a second `needs-decision`.
+const NOT_DIRECTLY_RUNNABLE_LABELS: ReadonlySet<string> = new Set([
+	EPIC_LABEL,
+	IN_PROGRESS_LABEL,
+	NEEDS_DECISION_LABEL,
+	ALREADY_DONE_LABEL,
+])
+
+// joshuafolkken/kit#1083: filing-route labels, applied at filing time so the backlog's composition —
+// a review-cap carry-forward vs a split child vs a Tier A in-implementation filing — is countable
+// with `gh api "repos/{owner}/{repo}/issues?labels=<route>"` instead of grepping issue bodies by
+// hand, which is how the 2026-08-30 breakdown was produced and why it did not reproduce. Purely
+// informational: unlike the three above, a route label says nothing about whether an issue may run,
+// so none of them joins NOT_DIRECTLY_RUNNABLE_LABELS. The names are duplicated as literals in the
+// filing procedures (prose cannot import this module); `scripts/rules/filing-route-label.test.ts` keys the
+// docs to these constants so a filing command that drops the label fails rather than drifting.
+//
+// joshuafolkken/kit#1518 added a fourth: an interrupt is a defect found in *this* repository that
+// does not block the run that found it, and which the WIP cap would otherwise push into the
+// discretionary exit — the route joshuafolkken/kit#1517 took, surviving only as a comment on another
+// issue. It is not `route:tier-a`: that one is a filing the run is blocked by (an upstream defect or
+// a prerequisite), and reading the two as one is what lost #1517.
+const INTERRUPT_ROUTE_LABEL = 'route:interrupt'
+const REVIEW_CAP_ROUTE_LABEL = 'route:review-cap'
+const SPLIT_ROUTE_LABEL = 'route:split'
+const TIER_A_ROUTE_LABEL = 'route:tier-a'
+
+// The route labels with the metadata `gh api ... labels` needs, in one place so a repository is
+// provisioned from the single source rather than from scattered creation commands. Applying one at
+// issue-creation time already auto-creates a missing label (REST, with a generated color and no
+// description); creating them here first is what gives each its stable color and description.
+const FILING_ROUTE_LABELS: ReadonlyArray<{
+	name: string
+	color: string
+	description: string
+}> = [
+	{
+		name: INTERRUPT_ROUTE_LABEL,
+		// Not `5319e7`, which is the `epic` label's purple: in a listing an interrupt would render as
+		// an epic, and the two are read at a glance rather than by name.
+		color: '1d76db',
+		// Keyed to the tests rather than to severity. "A serious defect" is the self-assessment
+		// `wip-cap.md` bans as a criterion, and this string is what a person reads in `gh label list`.
+		description: 'Filed past the WIP cap — meets one of the three interrupt tests (wip-cap.md)',
+	},
+	{
+		name: REVIEW_CAP_ROUTE_LABEL,
+		color: 'eab308',
+		description:
+			"Filed by the review round cap's carry-forward (prompts/review.md → Review round cap)",
+	},
+	{
+		name: SPLIT_ROUTE_LABEL,
+		color: '0e8a16',
+		description: 'A child issue created by a split (split-assessment.md)',
+	},
+	{
+		name: TIER_A_ROUTE_LABEL,
+		color: 'd93f0b',
+		description: 'Filed Tier A during implementation — an upstream defect or a prerequisite',
+	},
+]
+
+// joshuafolkken/kit#1729: the depth of an issue's subject, recorded as a label at filing time.
+//
+// **The definition is not here.** `.claude/skills/workflow-commands/observation-filing.md` → "The depth test",
+// is the single source: depth 0 is what a consumer of this package touches, depth 1 the run
+// orchestration that executes an Issue, depth 2 what measures a run. These constants are the
+// recording of that table, never a second copy of it — a label whose description restated the rule
+// would be the clone `CLAUDE.md` prohibits, and the descriptions below therefore name the section
+// rather than paraphrase it.
+//
+// **Why a label at all.** joshuafolkken/kit#1698 set a measurable target — the share of open issues
+// at depth 0 — and left nothing that records a depth, so the share could only be obtained by reading
+// every open issue's body by hand. Two hand counts a day apart disagreed on the denominator and were
+// therefore not comparable, which is the failure a recorded label removes.
+//
+// **The depth is read off the subject, so a run applies it.** Unlike `auto-ok` and
+// `needs-human-review` this is not a person's judgement about authorization; it is the same reading
+// §2i already asks a run to make before it files, and none of the three withholds or widens anything
+// a run may do.
+const DEPTH_0_LABEL = 'depth:0'
+const DEPTH_1_LABEL = 'depth:1'
+const DEPTH_2_LABEL = 'depth:2'
+
+// Ordered shallowest first, which is what makes `depth_label_of` deterministic: an issue carrying
+// more than one depth label counts as the **lowest** depth present, the one closest to the consumer.
+// Without a fixed tie-break the same listing measured twice could answer differently, which is the
+// whole defect joshuafolkken/kit#1729 was filed for.
+const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL, DEPTH_2_LABEL]
+
+// The metadata `gh api ... labels` needs, in the shape `FILING_ROUTE_LABELS` above uses and for the
+// same reason: applying a label at issue-creation auto-creates it with a generated color and no
+// description, so provisioning from here is what gives each one a stable color a reader can scan by.
+// Green, amber and pale blue, so the consumer-facing depth is the one that stands out in a listing.
+//
+// **The provisioning command lives in `observation-filing.md`**, because prose cannot import this module —
+// the same split `FILING_ROUTE_LABELS` above lives with. `scripts/rules/issue-depth-label.test.ts` keys
+// those three command lines to this array, so a color changed here without the document fails.
+const DEPTH_LABELS: ReadonlyArray<{
+	name: string
+	color: string
+	description: string
+}> = [
+	{
+		name: DEPTH_0_LABEL,
+		color: '0e8a16',
+		description: 'Depth 0 — what a consumer of this package touches (SKILL.md §2i)',
+	},
+	{
+		name: DEPTH_1_LABEL,
+		color: 'fbc02d',
+		description: 'Depth 1 — the run orchestration that executes an Issue (SKILL.md §2i)',
+	},
+	{
+		name: DEPTH_2_LABEL,
+		color: 'c5def5',
+		description: 'Depth 2 — what measures a run (SKILL.md §2i)',
+	},
+]
+
+// The shape `gh issue list --json labels` returns; narrowed here so the predicate below takes any
+// listing row without importing a schema.
+interface LabelReference {
+	name: string
+}
+
+// GitHub keeps the casing a label was created with and treats `Epic` and `epic` as one label, so a
+// repository that predates these scripts can answer with either spelling — every membership test
+// lowercases, which is why the comparison lives here rather than at each call site.
+function has_any_label(
+	labels: ReadonlyArray<LabelReference> | undefined,
+	wanted: ReadonlySet<string>,
+): boolean {
+	return (labels ?? []).some((label) => wanted.has(label.name.toLowerCase()))
+}
+
+// **The spelling GitHub actually stored**, matched by the same case-insensitive comparison every
+// membership test above uses, or `undefined` where the issue does not carry the label at all.
+//
+// A membership test answers whether the label is there; a *removal* has to name it, and
+// `DELETE …/issues/<N>/labels/<name>` names it in the path. Lowercasing the wanted name and sending
+// that would be a second comparison — GitHub's, on a spelling we did not read — so the removal reads
+// the stored one and sends it back (joshuafolkken/kit#1794).
+function label_name_of(labels: ReadonlyArray<string>, wanted: string): string | undefined {
+	const target = wanted.toLowerCase()
+
+	return labels.find((label) => label.toLowerCase() === target)
+}
+
+// The same comparison for a caller holding label *names* rather than listing rows. `EpicChild.labels`
+// is an array of strings (`scripts/epic/epic-graph.ts`), which is the one shape `has_any_label` cannot
+// take — so `epic-classify.ts` and `git-epic-validate.ts` each grew a raw case-sensitive
+// `Array.includes` instead, and an `Epic`-cased label walked past both. Kept here beside the rule it
+// implements rather than at either call site, for the reason the comment above gives.
+//
+// Expressed through `label_name_of` rather than repeating its `.toLowerCase()` loop: one comparison,
+// so a membership test and a removal can never disagree about what counts as the same label.
+function has_label_name(labels: ReadonlyArray<string>, wanted: string): boolean {
+	return label_name_of(labels, wanted) !== undefined
+}
+
+// The depth recorded on one listing row, or `undefined` where none is — the reading every share
+// measurement makes. Lowercased through the same comparison as every other membership test above,
+// because GitHub keeps the casing a label was created with and `Depth:0` is the same label.
+function depth_label_of(labels: ReadonlyArray<LabelReference> | undefined): string | undefined {
+	const names = new Set((labels ?? []).map((label) => label.name.toLowerCase()))
+
+	return DEPTH_LABEL_ORDER.find((name) => names.has(name))
+}
+
+// Every workflow label this package manages. The label-reference scan
+// (`scripts/document/label-reference.test.ts`, joshuafolkken/kit#1923) reads this to check that no
+// document operates on a label name that does not exist here — a stale or mistyped `labels[]=…`
+// otherwise fails silently at run time. One source, so a label added above joins the scan without a
+// second edit.
+// Applied to an Issue whose second review round was skipped, so the condition stays auditable
+// (`prompts/review.md` → "When round 2 is skipped entirely, and when it is not"). Provisioned inline
+// by the run that applies it rather than through `FILING_ROUTE_LABELS`, but still a managed label the
+// documents operate on, so the label-reference scan has to know it.
+const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
+
+const ALL_LABELS: ReadonlySet<string> = new Set([
+	EPIC_LABEL,
+	IN_PROGRESS_LABEL,
+	NEEDS_DECISION_LABEL,
+	AUTO_OK_LABEL,
+	NEEDS_HUMAN_REVIEW_LABEL,
+	ALREADY_DONE_LABEL,
+	INTERRUPT_ROUTE_LABEL,
+	REVIEW_CAP_ROUTE_LABEL,
+	REVIEW_ROUND2_SKIPPED_LABEL,
+	SPLIT_ROUTE_LABEL,
+	TIER_A_ROUTE_LABEL,
+	DEPTH_0_LABEL,
+	DEPTH_1_LABEL,
+	DEPTH_2_LABEL,
+])
+
+export {
+	ALL_LABELS,
+	ALREADY_DONE_LABEL,
+	AUTO_OK_LABEL,
+	depth_label_of,
+	DEPTH_0_LABEL,
+	DEPTH_1_LABEL,
+	DEPTH_2_LABEL,
+	DEPTH_LABEL_ORDER,
+	DEPTH_LABELS,
+	EPIC_LABEL,
+	FILING_ROUTE_LABELS,
+	has_any_label,
+	has_label_name,
+	IN_PROGRESS_LABEL,
+	INTERRUPT_ROUTE_LABEL,
+	label_name_of,
+	NEEDS_DECISION_LABEL,
+	NEEDS_HUMAN_REVIEW_LABEL,
+	NOT_DIRECTLY_RUNNABLE_LABELS,
+	REVIEW_CAP_ROUTE_LABEL,
+	REVIEW_ROUND2_SKIPPED_LABEL,
+	SPLIT_ROUTE_LABEL,
+	TIER_A_ROUTE_LABEL,
+}

package/scripts/git/listing-cutoff.ts

@@ -0,0 +1,51 @@
+import { MAX_SCANNED } from './git-gh-issue-list'
+
+// Why an open-issue listing stopped short of the end of the backlog, or that it did not
+// (joshuafolkken/kit#1067).
+//
+// Every caller of `issue_list` asks this same question, and before this the answer was written
+// out again at each of them — `rows.length >= LIMIT` in `epic:bundle` and the `auto-ok` pickup, a
+// near-identical `cutoff_of` in `epic:audit`, and nothing at all in the two that most needed it. One
+// definition instead, so a caller cannot quietly disagree with the others about what "I saw
+// everything" means.
+//
+// The two cutoffs are told apart because they cite different numbers and send a reader to different
+// knobs: `row_limit` is the caller's own `limit`, which it can raise, and `page_ceiling` is the
+// paging's `MAX_PAGES`, which it cannot.
+type ScanCutoff = 'none' | 'row_limit' | 'page_ceiling'
+
+// The two are mutually exclusive by construction — the paging stops as soon as `limit` rows have
+// been selected, so a listing that filled `limit` never reached the ceiling — and `row_limit` is
+// checked first so that stays true even if the paging changes.
+//
+// Exactly `limit` rows answers `row_limit` though nothing may have been missed, and exactly
+// `MAX_SCANNED` open items answers `page_ceiling` for the same boundary reason
+// `git-gh-issue-list.ts` records. Erring toward "I may not have seen everything" is the safe
+// direction for every caller here; the alternative spends a request on each capped run to rule out
+// one boundary.
+function cutoff_of(row_count: number, limit: number, is_capped: boolean): ScanCutoff {
+	if (row_count >= limit) return 'row_limit'
+
+	return is_capped ? 'page_ceiling' : 'none'
+}
+
+// What the page ceiling cut off, said once. Each caller words its own *consequence* — an epic past
+// the cut hides something different from a backlog issue past it — but the cause is one fact, and a
+// second spelling of it would cite a number that does not match `MAX_SCANNED`.
+const PAGE_CEILING_CAUSE = `stopped at the ${String(MAX_SCANNED)}-issue page ceiling`
+
+// Why this listing stopped, as a phrase to drop into the caller's own sentence — or `undefined` when
+// it ran out and there is nothing to say.
+//
+// `row_limit_cause` is passed rather than built here because the noun differs at every call site: an
+// issue cap, an epic cap, a match cap. What is shared is the *dispatch* — which of the two numbers a
+// reader has to be given — and writing it out at each caller is what let one of them cite the wrong
+// one.
+function cutoff_cause(cutoff: ScanCutoff, row_limit_cause: string): string | undefined {
+	if (cutoff === 'row_limit') return row_limit_cause
+
+	return cutoff === 'page_ceiling' ? PAGE_CEILING_CAUSE : undefined
+}
+
+export type { ScanCutoff }
+export { cutoff_of, cutoff_cause, PAGE_CEILING_CAUSE }