@joshuafolkken/kit 1.1178.0 → 1.1229.0

package/scripts/epic/epic-cli.ts

@@ -1,6 +1,6 @@
 import { cli_body } from '#scripts/josh/cli-body'
 import type { InsertKind, InsertPosition } from './epic-chains'
-import { epic_cli_argv, ISSUE_NUMBER_PATTERN } from './epic-cli-argv'
+import { epic_cli_argv, ISSUE_NUMBER_PATTERN, type EpicArgv, type FormFlags } from './epic-cli-argv'
 import { epic_cli_remove } from './epic-cli-remove'
 import { epic_parse, type ExternalChild } from './epic-parse'
 
@@ -27,25 +27,22 @@ const ORDER_AFTER_FLAG = '--order-after'
 // from a file, or from stdin as `-`. The text is a judgement, so the caller writes it; what the command
 // contributes is placing it in the epic's `## Decisions` and on each child (joshuafolkken/kit#1350).
 const DECISION_FLAG = '--decision-file'
-// Which flags consume the argument after them — per parser, for the reason `epic-cli-argv.ts` gives.
-const VALUE_FLAGS: ReadonlySet<string> = new Set([RATIONALE_FLAG, ORIGIN_FLAG])
-const ADD_VALUE_FLAGS: ReadonlySet<string> = new Set([
-	BEFORE_FLAG,
-	AFTER_FLAG,
-	ORDER_BEFORE_FLAG,
-	ORDER_AFTER_FLAG,
-	DECISION_FLAG,
-])
-const ADD_KNOWN_FLAGS: ReadonlySet<string> = new Set([
-	ADD_FLAG,
-	BEFORE_FLAG,
-	AFTER_FLAG,
-	ORDER_BEFORE_FLAG,
-	ORDER_AFTER_FLAG,
-	DECISION_FLAG,
-])
+// Which flags each form knows, and which of them consume the argument after them — per form, for the
+// reason `epic-cli-argv.ts` gives.
+const CREATE_FORM: FormFlags = {
+	switches: [ORDERED_FLAG],
+	value_flags: [RATIONALE_FLAG, ORIGIN_FLAG],
+}
+const PROMOTE_FORM: FormFlags = { ...CREATE_FORM, switches: [PROMOTE_FLAG, ORDERED_FLAG] }
+const RECONCILE_FORM: FormFlags = { switches: [RECONCILE_FLAG] }
+const CHECK_FORM: FormFlags = { switches: [] }
+const ADD_FORM: FormFlags = {
+	switches: [ADD_FLAG],
+	value_flags: [BEFORE_FLAG, AFTER_FLAG, ORDER_BEFORE_FLAG, ORDER_AFTER_FLAG, DECISION_FLAG],
+}
 
-const { count_flag, is_value_unusable, read_flag_value } = epic_cli_argv
+const { count_flag, is_switch_set, is_value_unusable, positionals_of, read_flag_value, read_form } =
+	epic_cli_argv
 
 interface CreateArguments {
 	title: string
@@ -65,13 +62,6 @@ interface PromoteArguments {
 	origin?: string | undefined
 }
 
-function to_positional_arguments(
-	argv: ReadonlyArray<string>,
-	value_flags: ReadonlySet<string> = VALUE_FLAGS,
-): Array<string> {
-	return epic_cli_argv.to_positional_arguments(argv, value_flags)
-}
-
 // Deduplicated because a repeated number would render a duplicate task-list row, and with
 // `--ordered` would ask GitHub to make an issue block itself.
 function to_child_numbers(raw_children: ReadonlyArray<string>): Array<number> {
@@ -83,22 +73,33 @@ function to_child_numbers(raw_children: ReadonlyArray<string>): Array<number> {
 	return [...new Set(numbers)]
 }
 
-// The title comes first so the children can stay a bare list of numbers, which is how they are
-// written down when the split is made.
-function parse_create_arguments(argv: ReadonlyArray<string>): CreateArguments | undefined {
-	const [title, ...raw_children] = to_positional_arguments(argv)
+// The flags a creation and a promotion share, read the same way for both.
+function read_batch_flags(
+	parsed: EpicArgv,
+): Pick<CreateArguments, 'is_ordered' | 'rationale_path' | 'origin'> {
+	return {
+		is_ordered: is_switch_set(parsed, ORDERED_FLAG),
+		rationale_path: read_flag_value(parsed, RATIONALE_FLAG),
+		origin: read_flag_value(parsed, ORIGIN_FLAG),
+	}
+}
+
+function to_create_arguments(parsed: EpicArgv): CreateArguments | undefined {
+	const [title, ...raw_children] = parsed.positionals
 	if (title === undefined || title.length === 0) return undefined
 
 	const children = to_child_numbers(raw_children)
 	if (children.length === 0) return undefined
 
-	return {
-		title,
-		children,
-		is_ordered: argv.includes(ORDERED_FLAG),
-		rationale_path: read_flag_value(argv, RATIONALE_FLAG),
-		origin: read_flag_value(argv, ORIGIN_FLAG),
-	}
+	return { title, children, ...read_batch_flags(parsed) }
+}
+
+// The title comes first so the children can stay a bare list of numbers, which is how they are
+// written down when the split is made.
+function parse_create_arguments(argv: ReadonlyArray<string>): CreateArguments | undefined {
+	const parsed = read_form(argv, CREATE_FORM)
+
+	return parsed === undefined ? undefined : to_create_arguments(parsed)
 }
 
 // Whether the invocation is a promotion rather than a creation.
@@ -118,7 +119,7 @@ interface ReconcileArguments {
 // The epic to reconcile. The number after `--reconcile` is the only subject; there are no children
 // and no position — the repair reads what the epic already records rather than being told an order.
 function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArguments | undefined {
-	const [raw_epic] = to_positional_arguments(argv)
+	const [raw_epic] = positionals_of(argv, RECONCILE_FORM)
 	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
 
 	return { epic_number: Number(raw_epic) }
@@ -127,20 +128,20 @@ function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArgume
 // The promoted issue and its children. The number after `--promote` is the epic; everything else
 // positional is a child. Refused when the epic would also be listed as its own child, which would
 // have it block itself under `--ordered`.
-function parse_promote_arguments(argv: ReadonlyArray<string>): PromoteArguments | undefined {
-	const [raw_epic, ...raw_children] = to_positional_arguments(argv)
+function to_promote_arguments(parsed: EpicArgv): PromoteArguments | undefined {
+	const [raw_epic, ...raw_children] = parsed.positionals
 	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
 	const epic_number = Number(raw_epic)
 	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
 	if (children.length === 0) return undefined
 
-	return {
-		epic_number,
-		children,
-		is_ordered: argv.includes(ORDERED_FLAG),
-		rationale_path: read_flag_value(argv, RATIONALE_FLAG),
-		origin: read_flag_value(argv, ORIGIN_FLAG),
-	}
+	return { epic_number, children, ...read_batch_flags(parsed) }
+}
+
+function parse_promote_arguments(argv: ReadonlyArray<string>): PromoteArguments | undefined {
+	const parsed = read_form(argv, PROMOTE_FORM)
+
+	return parsed === undefined ? undefined : to_promote_arguments(parsed)
 }
 
 // `--add <E> <N...> [--before <M> | --after <M> | --order-before <M> | --order-after <M>]`: the epic
@@ -195,36 +196,33 @@ const POSITION_FLAGS: ReadonlyArray<PositionFlag> = [
 // of each direction, or a dependency-writing flag beside an order-only one. `read_flag_value` would
 // answer with the first, which is a silent choice rather than a refusal — and here the silent choice
 // would decide whether a `blocked-by` is written at all.
-function is_position_ambiguous(argv: ReadonlyArray<string>): boolean {
-	return POSITION_FLAGS.reduce((total, entry) => total + count_flag(argv, entry.flag), 0) > 1
+function count_position_flags(parsed: EpicArgv): number {
+	return POSITION_FLAGS.reduce((total, entry) => total + count_flag(parsed, entry.flag), 0)
 }
 
 interface PositionTarget extends PositionFlag {
 	raw: string
 }
 
-function to_position_target(
-	argv: ReadonlyArray<string>,
-	entry: PositionFlag,
-): PositionTarget | undefined {
-	const raw = read_flag_value(argv, entry.flag)
+function to_position_target(parsed: EpicArgv, entry: PositionFlag): PositionTarget | undefined {
+	const raw = read_flag_value(parsed, entry.flag)
 
 	return raw === undefined ? undefined : { ...entry, raw }
 }
 
-function read_position_target(argv: ReadonlyArray<string>): PositionTarget | undefined {
-	if (is_position_ambiguous(argv)) return undefined
+function read_position_target(parsed: EpicArgv): PositionTarget | undefined {
+	if (count_position_flags(parsed) > 1) return undefined
 
-	return POSITION_FLAGS.map((entry) => to_position_target(argv, entry)).find(
+	return POSITION_FLAGS.map((entry) => to_position_target(parsed, entry)).find(
 		(found) => found !== undefined,
 	)
 }
 
 // A target that is not an issue number is refused for the same reason two flags are: guessing would
 // insert somewhere.
-function parse_position(argv: ReadonlyArray<string>): PositionOutcome {
-	const has_flag = POSITION_FLAGS.some((entry) => argv.includes(entry.flag))
-	const target = read_position_target(argv)
+function parse_position(parsed: EpicArgv): PositionOutcome {
+	const has_flag = count_position_flags(parsed) > 0
+	const target = read_position_target(parsed)
 	if (target === undefined) return has_flag ? REFUSED_POSITION : NO_POSITION
 	if (!ISSUE_NUMBER_PATTERN.test(target.raw)) return REFUSED_POSITION
 
@@ -235,10 +233,6 @@ function parse_position(argv: ReadonlyArray<string>): PositionOutcome {
 	}
 }
 
-function has_unknown_flag(argv: ReadonlyArray<string>): boolean {
-	return epic_cli_argv.has_unknown_flag(argv, ADD_KNOWN_FLAGS)
-}
-
 // Whether *this* is why the insertion could not be read, so the refusal can say so. Without it the
 // caller prints the generic requirements line, and a shell that expanded `--decision-file $REC` to
 // nothing is answered with "an epic number and at least one child issue number are required" — advice
@@ -248,9 +242,9 @@ function is_decision_path_unusable(argv: ReadonlyArray<string>): boolean {
 }
 
 function read_add_subject(
-	argv: ReadonlyArray<string>,
+	parsed: EpicArgv,
 ): { epic_number: number; children: Array<number> } | undefined {
-	const [raw_epic, ...raw_children] = to_positional_arguments(argv, ADD_VALUE_FLAGS)
+	const [raw_epic, ...raw_children] = parsed.positionals
 	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
 	const epic_number = Number(raw_epic)
 	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
@@ -258,21 +252,28 @@ function read_add_subject(
 	return children.length === 0 ? undefined : { epic_number, children }
 }
 
-function parse_add_arguments(argv: ReadonlyArray<string>): AddArguments | undefined {
-	if (has_unknown_flag(argv) || is_decision_path_unusable(argv)) return undefined
-	const subject = read_add_subject(argv)
+function to_add_arguments(parsed: EpicArgv): AddArguments | undefined {
+	const subject = read_add_subject(parsed)
 	if (subject === undefined) return undefined
-	const outcome = parse_position(argv)
+	const outcome = parse_position(parsed)
 	if (outcome.is_refused) return undefined
 
 	return {
 		...subject,
 		position: outcome.position,
 		is_order_only: outcome.is_order_only,
-		decision_path: read_flag_value(argv, DECISION_FLAG),
+		decision_path: read_flag_value(parsed, DECISION_FLAG),
 	}
 }
 
+// An unknown flag is refused by the strict read: a mistyped positioning flag would otherwise leave its
+// value positional, so it becomes a child and the edit lands somewhere else (joshuafolkken/kit#890).
+function parse_add_arguments(argv: ReadonlyArray<string>): AddArguments | undefined {
+	const parsed = is_decision_path_unusable(argv) ? undefined : read_form(argv, ADD_FORM)
+
+	return parsed === undefined ? undefined : to_add_arguments(parsed)
+}
+
 // The one refusal `--add` has to explain rather than merely report. `into owner/repo#N` is a legal
 // thing for a person to type, and this command cannot serve it: it reads and edits issues in the
 // repository it is run from. Falling through to the usage line would read as "that form does not
@@ -288,7 +289,7 @@ interface CrossRepoAddTarget {
 // problem, and
 // a suggestion built from it would drop or mangle what the person typed.
 function find_cross_repo_add_target(argv: ReadonlyArray<string>): CrossRepoAddTarget | undefined {
-	const [raw_epic] = to_positional_arguments(argv, ADD_VALUE_FLAGS)
+	const [raw_epic] = positionals_of(argv, ADD_FORM)
 	if (raw_epic === undefined) return undefined
 	const epic = epic_parse.parse_external_reference(raw_epic)
 	if (epic === undefined) return undefined
@@ -351,7 +352,7 @@ function format_cross_repo_refusal(found: CrossRepoAddTarget): string {
 }
 
 function parse_check_argument(argv: ReadonlyArray<string>): number | undefined {
-	const [raw] = to_positional_arguments(argv)
+	const [raw] = positionals_of(argv, CHECK_FORM)
 	if (raw === undefined || !ISSUE_NUMBER_PATTERN.test(raw)) return undefined
 
 	return Number(raw)

package/scripts/epic/epic-close-comment.ts

@@ -1,6 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { rest_comment_schema, type RestCommentData } from '#scripts/git/git-schemas'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import { rest_comment_schema, type RestCommentData } from '#scripts/git/schemas'
 import { epic_parse, type ExternalChild } from './epic-parse'
 
 // The comment the epic auto-close announces itself with, and how a run recognizes the one a previous

package/scripts/epic/epic-close.ts

@@ -1,10 +1,10 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { epic_child_schema, epic_issue_schema, type EpicChildData } from '#scripts/git/git-schemas'
 import { cutoff_cause, cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import {
 	parse_json_array_or_undefined,
 	parse_json_object_safe,
 } from '#scripts/git/parse-json-array'
-import { epic_child_schema, epic_issue_schema, type EpicChildData } from '#scripts/git/schemas'
 import { EPIC_LABEL } from '#scripts/issue/issue-labels'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_close_comment } from './epic-close-comment'

package/scripts/epic/epic-cross-repo.ts

@@ -2,6 +2,7 @@ import { repo_map_logic } from '#scripts/discovery/repo-map-logic'
 import { repo_origin } from '#scripts/discovery/repo-origin'
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { propagate_publish } from '#scripts/propagate/propagate-publish'
 import { derive_versions_endpoint } from '#scripts/version/version-command-config'
 import { load } from 'js-yaml'
@@ -69,7 +70,6 @@ function is_published(repo: string, version: string): boolean {
 	return propagate_publish.is_version_published(versions, version)
 }
 
-const GH_TIMEOUT_MS = 20_000
 // The manifest arrives base64-encoded in the API's `content` field; `jq` decodes and reads it.
 const VERSION_JQ = '.content | @base64d | fromjson | {version, private, workspaces} | tojson'
 const PNPM_WORKSPACE_FILE = 'pnpm-workspace.yaml'
@@ -145,7 +145,7 @@ function pnpm_workspace_path(repo: string): string {
 
 // A read that failed for any reason other than a missing file leaves the layout unknown.
 function classify_workspace_failure(repo: string): WorkspaceCheck {
-	const status = git_gh_exec.exec_gh_api_status_sync(pnpm_workspace_path(repo), GH_TIMEOUT_MS)
+	const status = git_gh_exec.exec_gh_api_status_sync(pnpm_workspace_path(repo), GH_API_TIMEOUT_MS)
 
 	return status === NOT_FOUND_STATUS ? 'single' : 'unreadable'
 }
@@ -154,7 +154,7 @@ function read_pnpm_workspace(repo: string): WorkspaceCheck {
 	const stdout = git_gh_exec.read_gh_api_sync({
 		path: pnpm_workspace_path(repo),
 		jq_filter: WORKSPACE_JQ,
-		timeout_ms: GH_TIMEOUT_MS,
+		timeout_ms: GH_API_TIMEOUT_MS,
 	})
 	if (stdout === undefined) return classify_workspace_failure(repo)
 
@@ -229,7 +229,7 @@ function to_manifest(repo: string, stdout: string): ManifestAnswer {
 // here is trustworthy in a way a registry 404 is not: the repository's issues are already being read,
 // so access is established and what is missing is the file.
 function classify_manifest_failure(repo: string): ManifestAnswer {
-	const status = git_gh_exec.exec_gh_api_status_sync(manifest_path(repo), GH_TIMEOUT_MS)
+	const status = git_gh_exec.exec_gh_api_status_sync(manifest_path(repo), GH_API_TIMEOUT_MS)
 
 	return { kind: status === NOT_FOUND_STATUS ? 'absent' : 'unreadable' }
 }
@@ -238,7 +238,7 @@ function fetch_manifest(repo: string): ManifestAnswer {
 	const stdout = git_gh_exec.read_gh_api_sync({
 		path: manifest_path(repo),
 		jq_filter: VERSION_JQ,
-		timeout_ms: GH_TIMEOUT_MS,
+		timeout_ms: GH_API_TIMEOUT_MS,
 	})
 
 	return stdout === undefined ? classify_manifest_failure(repo) : to_manifest(repo, stdout)

package/scripts/epic/epic-graph.ts

@@ -121,7 +121,7 @@ function find_stuck_children(children: ReadonlyArray<EpicChild>): Array<string>
 	const index = index_children(children)
 	const remaining = new Set(children.map((child) => key_of(child)))
 
-	const peel = (): number => {
+	function peel(): number {
 		const ready = [...remaining].filter((node) => !has_remaining_blocker(index, node, remaining))
 
 		for (const node of ready) remaining.delete(node)

package/scripts/epic/epic-index.ts

@@ -1,7 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
-import type { OpenIssueData } from '#scripts/git/schemas'
 import { EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 import { z } from 'zod'
 import { epic_parse } from './epic-parse'

package/scripts/epic/epic-issue.ts

@@ -1,6 +1,6 @@
 import { git_gh_issue_rest } from '#scripts/gh/git-gh-issue-rest'
+import { blocked_by_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
-import { blocked_by_schema } from '#scripts/git/schemas'
 import { z } from 'zod'
 import type { IssueReference } from './epic-reference'
 
@@ -29,11 +29,7 @@ const PULL_REQUEST_SEGMENT = '/pull/'
 const epic_issue_schema = z.object({
 	number: z.number(),
 	title: z.string().default(''),
-	body: z
-		.string()
-		.nullable()
-		.default('')
-		.transform((value) => value ?? ''),
+	body: z.union([z.string(), z.null().transform(() => '')]).default(''),
 	state: z.string().default(UNKNOWN_STATE),
 	// The issue endpoint answers for a pull request as readily as for an issue, and nothing in the
 	// other fields separates them — an open PR reports `state: OPEN`, a merged one `MERGED`. The URL

package/scripts/epic/epic-lane-offer.ts

@@ -187,10 +187,10 @@ function solo_offer(
 	read: BusyRead,
 	request: LaneRequest,
 ): LaneOffer {
-	const { offered, notice } = epic_solo.select(answer.children, read, request.repo)
+	const { offered, notice = '' } = epic_solo.select(answer.children, read, request.repo)
 
 	if (offered.length === NO_LANES && answer.children.length > NO_LANES) {
-		return { children: [], verdict: WAIT_VERDICT, notice: notice ?? '' }
+		return { children: [], verdict: WAIT_VERDICT, notice }
 	}
 
 	return { ...answer, children: offered, notice: offered_notice(offered, read, request) }

package/scripts/epic/epic-next.ts

@@ -5,6 +5,7 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_classify } from './epic-classify'
 import { epic_cross_repo } from './epic-cross-repo'
@@ -31,12 +32,10 @@ import { epic_report, type EpicNextResult } from './epic-report'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const REPO_FLAG = '--repo'
-// Asking for every free lane is opt-in, so the answer stays one token for a caller that has not been
-// changed. `--repo` alone still prints exactly one number — what joshuafolkken/kit#1491 changed for
-// it is *when* that number appears, not how many arrive (joshuafolkken/kit#1491).
-const LANES_FLAG = '--lanes'
-const FLAG_PREFIX = '--'
+// Asking for every free lane (`--lanes`) is opt-in, so the answer stays one token for a caller that
+// has not been changed. `--repo` alone still prints exactly one number — what joshuafolkken/kit#1491
+// changed for it is *when* that number appears, not how many arrive (joshuafolkken/kit#1491).
+const OPTIONS = { repo: { type: 'string' }, lanes: { type: 'boolean' } } as const
 const USAGE =
 	'Usage: josh epic:next <epic-number|owner/repo#number>... [--repo <owner/repo>] [--lanes]'
 // A repository that could not be read is refused rather than stood in for. Since
@@ -66,30 +65,6 @@ interface NextOptions {
 	usage?: string
 }
 
-// A value that is itself a flag is no value at all. `--repo --lanes` used to narrow to a repository
-// literally named `--lanes` and report `No runnable child in --lanes` with exit 0; refused here, it
-// reaches the usage line instead — the caller meant a repository and named none.
-function parse_repo(rest: ReadonlyArray<string>): string | undefined {
-	const flag_index = rest.indexOf(REPO_FLAG)
-	const value = flag_index === -1 ? undefined : rest[flag_index + 1]
-
-	return value?.startsWith(FLAG_PREFIX) === true ? undefined : value
-}
-
-// The leading arguments are epic references and everything from the first flag on is options. Split
-// on the flag rather than taking a fixed count, so `epic:next 858 909 --repo X` reads two epics and
-// `epic:next 858 --repo X` still reads one (joshuafolkken/kit#1493).
-function split_at_flag(argv: ReadonlyArray<string>): {
-	head: ReadonlyArray<string>
-	rest: ReadonlyArray<string>
-} {
-	const flag_at = argv.findIndex((entry) => entry.startsWith(FLAG_PREFIX))
-
-	return flag_at === -1
-		? { head: argv, rest: [] }
-		: { head: argv.slice(0, flag_at), rest: argv.slice(flag_at) }
-}
-
 // Every leading entry, or nothing. One entry that does not parse fails the whole read rather than
 // being dropped: a mistyped second epic would otherwise run the first one alone and report nothing
 // at all about the one that was missed — an unattended run silently doing half of what was asked.
@@ -106,21 +81,34 @@ function parse_references(head: ReadonlyArray<string>): ReadonlyArray<EpicRefere
 	return references.length === 0 ? undefined : references
 }
 
+function with_repo(
+	references: ReadonlyArray<EpicReference>,
+	values: { repo?: string; lanes?: boolean },
+): NextOptions {
+	const { repo, lanes: is_all_lanes = false } = values
+
+	if (repo === undefined) return is_all_lanes ? { usage: USAGE } : { references }
+
+	return { references, repo, is_all_lanes }
+}
+
+// The positional arguments are epic references and the flags are options, so `epic:next 858 909 --repo
+// X` reads two epics and `epic:next 858 --repo X` still reads one (joshuafolkken/kit#1493). The read is
+// strict: an unknown flag reaches the usage line rather than being ignored, and a value that is itself
+// a flag is no value at all — `--repo --lanes` used to narrow to a repository literally named
+// `--lanes` and report `No runnable child in --lanes` with exit 0.
+//
 // `--lanes` without `--repo` is refused rather than ignored: the lane count is a property of one
 // repository, so the aggregate listing has nothing to apply it to, and a flag that silently does
-// nothing is a caller believing it asked for something.
+// nothing is a caller believing it asked for something. An empty name (`--repo=` from an unset
+// variable) is no repository either: narrowed to it, the answer is `No runnable child in .` and exit 0.
 function parse_options(argv: ReadonlyArray<string>): NextOptions {
-	const { head, rest } = split_at_flag(argv)
-	const references = parse_references(head)
-	if (references === undefined) return { usage: USAGE }
-	const repo = parse_repo(rest)
-	const is_all_lanes = rest.includes(LANES_FLAG)
-
-	if (repo === undefined) {
-		return is_all_lanes || rest.includes(REPO_FLAG) ? { usage: USAGE } : { references }
-	}
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return { usage: USAGE }
+	const references = parse_references(parsed.positionals)
+	if (references === undefined || parsed.values.repo === '') return { usage: USAGE }
 
-	return { references, repo, is_all_lanes }
+	return with_repo(references, parsed.values)
 }
 
 // The answer for one epic, from an already-fetched snapshot. Split from the fetch so the whole
@@ -446,7 +434,6 @@ const epic_next = {
 	is_order_declared,
 	repo_verdict,
 	UNCHECKED_EXCLUSION,
-	split_at_flag,
 	parse_options,
 	refuse_reads,
 	views_of,

package/scripts/epic/epic-solo-stale.ts

@@ -1,5 +1,5 @@
 import { setTimeout as sleep } from 'node:timers/promises'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { has_any_label, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { lane_await } from '#scripts/lane/lane-await'
 import { lane_registry } from '#scripts/lane/lane-registry'

package/scripts/epic/epic-triage.ts

@@ -20,12 +20,16 @@ type TriageVerdict = 'triage'
 
 const TRIAGE_VERDICT: TriageVerdict = 'triage'
 
-function is_triaged(child: EpicChild): boolean {
-	const { labels } = child
-
+// Read off a bare label list too, so `josh issue:file` refuses an untriaged `auto-ok` filing by the
+// same answer the offer paths withhold it by (joshuafolkken/kit#3313).
+function has_triage_label(labels: ReadonlyArray<string>): boolean {
 	return has_label_name(labels, RUN_SOLO_LABEL) || has_label_name(labels, RUN_LANE_LABEL)
 }
 
+function is_triaged(child: EpicChild): boolean {
+	return has_triage_label(child.labels)
+}
+
 // The candidates nobody has judged, in the order they were given.
 function untriaged(children: ReadonlyArray<EpicChild>): ReadonlyArray<EpicChild> {
 	return children.filter((child) => !is_triaged(child))
@@ -41,7 +45,7 @@ function message(children: ReadonlyArray<EpicChild>, repo: string): string {
 	)
 }
 
-const epic_triage = { TRIAGE_VERDICT, is_triaged, message, untriaged }
+const epic_triage = { TRIAGE_VERDICT, has_triage_label, is_triaged, message, untriaged }
 
 export type { TriageVerdict }
 export { epic_triage }

package/scripts/epic/epic-validate.ts

@@ -1,5 +1,5 @@
+import { epic_subject_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
-import { epic_subject_schema } from '#scripts/git/schemas'
 import { EPIC_LABEL, has_label_name } from '#scripts/issue/issue-labels'
 import { epic_parse, type DeclarationState } from './epic-parse'
 

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

@@ -1,8 +1,8 @@
 import { git_next_issues } from '#scripts/issue/git-next-issues'
 import { review_attest } from '#scripts/review/review-attest'
 import { review_stamps } from '#scripts/review/review-stamps'
-import { run_hold } from '#scripts/run/run-hold'
-import { run_progress_clock } from '#scripts/run/run-progress-clock'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_progress_clock } from '#scripts/run/progress/run-progress-clock'
 import { parse_completed_issue_number } from './followup-issue-number'
 import { git_followup_cleanup, type CleanupStep } from './git-followup-cleanup'
 import { git_followup_pending } from './git-followup-pending'

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

@@ -1,6 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
-import { issue_label_schema } from '#scripts/git/schemas'
 import { IN_PROGRESS_LABEL, label_name_of } from '#scripts/issue/issue-labels'
 import { z } from 'zod'
 
@@ -19,7 +19,7 @@ import { z } from 'zod'
 // No procedure covered the ordinary ending: merged, closed, and still marked as running.
 
 // The `number,labels,body` read answers labels as objects, and this is the one field of it this
-// step needs. The element shape is `schemas.ts`'s rather than a second spelling of it; the wrapper
+// step needs. The element shape is `git-schemas.ts`'s rather than a second spelling of it; the wrapper
 // is local because a read's *field list* is what multiplies helpers when it is shared
 // (`git-gh-issue-read.ts`).
 const labels_read_schema = z.object({ labels: z.array(issue_label_schema).optional() })

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

@@ -66,8 +66,8 @@ function is_posted_since(comment: IssueComment, merged_at: string): boolean {
 	return Date.parse(comment.created_at) >= Date.parse(merged_at)
 }
 
-function parse_comments(comments_json: string | undefined): Array<IssueComment> {
-	const parsed = COMMENTS_SCHEMA.safeParse(json_value.parse_or_undefined(comments_json ?? ''))
+function parse_comments(comments_json: string | undefined = ''): Array<IssueComment> {
+	const parsed = COMMENTS_SCHEMA.safeParse(json_value.parse_or_undefined(comments_json))
 
 	return parsed.success ? parsed.data : []
 }