@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/epic/epic-bundle-cli.ts

@@ -4,6 +4,7 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
+import type { PollOptions } from '#scripts/lib/poll'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { z } from 'zod'
 import {
@@ -14,6 +15,7 @@ import {
 } from './epic-bundle'
 import { epic_bundle_evidence } from './epic-bundle-evidence'
 import { epic_bundle_gaps } from './epic-bundle-gaps'
+import { epic_bundle_poll } from './epic-bundle-poll'
 import { epic_bundle_referenced, type ReferencedContext } from './epic-bundle-referenced'
 import { epic_index, epic_schema, type FetchedEpics } from './epic-index'
 import { epic_issue } from './epic-issue'
@@ -393,9 +395,18 @@ async function report_widened(
 	return report_decision(subject, widened, repo)
 }
 
-// The recommendation for one issue, from the open backlog around it.
-async function report_for(issue_number: number, repo: string): Promise<number> {
-	const backlog = await read_backlog(repo)
+// The recommendation for one issue, from the open backlog around it. `options` is the poll a caller
+// holding a just-filed issue passes, since the listing trails the create call (`epic-bundle-poll.ts`).
+async function report_for(
+	issue_number: number,
+	repo: string,
+	options?: PollOptions,
+): Promise<number> {
+	const backlog = await epic_bundle_poll.read_until_listed(
+		async () => await read_backlog(repo),
+		issue_number,
+		options,
+	)
 
 	if (!backlog.is_readable) {
 		console.error(unreadable_backlog_message(backlog))

package/scripts/epic/epic-bundle-poll.ts

@@ -0,0 +1,41 @@
+import { poll, type PollOptions } from '#scripts/lib/poll'
+
+// **The open listing trails the create call** (joshuafolkken/kit#3332): `issue:file` asks
+// `epic:bundle` about the issue it has just filed, and the list endpoint had not shown it yet on every
+// filing of one run, so the placement was skipped each time. A caller that knows the issue is fresh
+// passes a poll and the listing is read again until it shows the issue. An unreadable listing is
+// final, since reading it again is not what would change it.
+
+// A number typed at the command line names an issue that exists already, so it is read once.
+const SINGLE_READ: PollOptions = { attempts: 1, interval_ms: 0 }
+
+interface Listing {
+	is_readable: boolean
+	issues: ReadonlyArray<{ number: number }>
+}
+
+function is_settled(listing: Listing, issue_number: number): boolean {
+	return !listing.is_readable || listing.issues.some((issue) => issue.number === issue_number)
+}
+
+async function read_until_listed<T extends Listing>(
+	read: () => Promise<T>,
+	issue_number: number,
+	options: PollOptions = SINGLE_READ,
+): Promise<T> {
+	const reads: Array<T> = []
+
+	await poll.poll_until(async () => {
+		const listing = await read()
+
+		reads.push(listing)
+
+		return is_settled(listing, issue_number)
+	}, options)
+
+	return reads.at(-1) ?? (await read())
+}
+
+const epic_bundle_poll = { read_until_listed }
+
+export { epic_bundle_poll }

package/scripts/epic/epic-busy.ts

@@ -1,6 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import {
 	ALREADY_DONE_LABEL,
 	has_any_label,

package/scripts/epic/epic-candidate-confirm.ts

@@ -70,11 +70,12 @@ function is_same_blockers(
 	left: ReadonlyArray<IssueReference>,
 	right: ReadonlyArray<IssueReference>,
 ): boolean {
-	const sorted = (blockers: ReadonlyArray<IssueReference>): string =>
-		blockers
+	function sorted(blockers: ReadonlyArray<IssueReference>): string {
+		return blockers
 			.map((blocker) => epic_graph.key_of(blocker))
 			.toSorted((first, second) => first.localeCompare(second))
 			.join(',')
+	}
 
 	return sorted(left) === sorted(right)
 }

package/scripts/epic/epic-classify.ts

@@ -217,7 +217,7 @@ function is_ready(node: string, context: ClassifyContext): boolean {
 function fill_memo(children: ReadonlyArray<EpicChild>, context: ClassifyContext): void {
 	const pending = new Set(children.map((child) => epic_graph.key_of(child)))
 
-	const peel = (): number => {
+	function peel(): number {
 		const ready = [...pending].filter((node) => is_ready(node, context))
 
 		for (const node of ready) {

package/scripts/epic/epic-cli-argv.ts

@@ -1,76 +1,108 @@
-// The argument-reading primitives every `josh epic` form shares.
+import type { ParseArgsOptionsConfig } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
+
+// The argument reading every `josh epic` form shares, on top of `cli_flags` (joshuafolkken/kit#3261).
 //
-// They were private to `epic-cli.ts` until `--remove` needed the same four (joshuafolkken/kit#1712),
+// They were private to `epic-cli.ts` until `--remove` needed the same readers (joshuafolkken/kit#1712),
 // at which point the choice was to copy them or to name them. Copying is what `CLAUDE.md` prohibits,
 // and the failure it would produce is specific: two readers disagreeing about what counts as a flag
 // value would have one form silently take a `--decision-file` path for an issue number.
+//
+// **Each form names its own flags, and the read is strict.** Which flags consume the argument after
+// them is per form: `--before` takes a value only under `--add`, and treating it as one everywhere had
+// `josh epic "T" 101 102 --after 103` silently drop #103 (joshuafolkken/kit#890). A flag the form does
+// not know refuses the invocation — a mistyped flag would otherwise leave its value positional, so it
+// becomes an issue number and the edit silently lands somewhere else.
 
-const FLAG_PREFIX = '--'
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+// Every value flag is read as a list so a repeat is visible rather than resolved to one of the two:
+// two `--decision-file` paths name two records, and two `--before` targets name two places.
+const VALUE_OPTION = { type: 'string', multiple: true } as const
+const SWITCH_OPTION = { type: 'boolean' } as const
+const SINGLE = 1
+
+type ParsedValue = string | boolean | Array<string | boolean> | undefined
+
+interface EpicArgv {
+	positionals: Array<string>
+	values: Readonly<Record<string, ParsedValue>>
+}
 
-function is_flag(argument: string): boolean {
-	return argument.startsWith(FLAG_PREFIX)
+interface FormFlags {
+	switches: ReadonlyArray<string>
+	value_flags?: ReadonlyArray<string>
 }
 
-function read_flag_value(argv: ReadonlyArray<string>, flag: string): string | undefined {
-	const index = argv.indexOf(flag)
-	if (index === -1) return undefined
+type OptionEntry = [string, ParseArgsOptionsConfig[string]]
 
-	return argv[index + 1]
+function options_of(form: FormFlags): ParseArgsOptionsConfig {
+	const entries: Array<OptionEntry> = [
+		...form.switches.map((flag): OptionEntry => [cli_flags.option_name(flag), SWITCH_OPTION]),
+		...(form.value_flags ?? []).map((flag): OptionEntry => [
+			cli_flags.option_name(flag),
+			VALUE_OPTION,
+		]),
+	]
+
+	return Object.fromEntries(entries)
 }
 
-// A value-taking flag's argument must not be mistaken for a child issue number, so the argument
-// directly after one is dropped along with the flag itself.
-function is_flag_value(
-	argv: ReadonlyArray<string>,
-	index: number,
-	value_flags: ReadonlySet<string>,
-): boolean {
-	return value_flags.has(argv[index - 1] ?? '')
+// Every value a flag was given, in order; empty when it was absent.
+function values_of_flag(parsed: EpicArgv, flag: string): ReadonlyArray<string> {
+	const given = parsed.values[cli_flags.option_name(flag)]
+	if (!Array.isArray(given)) return []
+
+	return given.filter((value): value is string => typeof value === 'string')
 }
 
-// **Which flags consume the argument after them is per parser, not module-wide**: `--before` takes a
-// value only under `--add`, and treating it as one everywhere had `josh epic "T" 101 102 --after 103`
-// silently drop #103 from the new epic instead of ignoring an unknown flag (joshuafolkken/kit#890).
-function to_positional_arguments(
-	argv: ReadonlyArray<string>,
-	value_flags: ReadonlySet<string>,
-): Array<string> {
-	return argv.filter(
-		(argument, index) => !is_flag(argument) && !is_flag_value(argv, index, value_flags),
-	)
+function count_flag(parsed: EpicArgv, flag: string): number {
+	return values_of_flag(parsed, flag).length
 }
 
-function count_flag(argv: ReadonlyArray<string>, flag: string): number {
-	return argv.filter((argument) => argument === flag).length
+function is_repeated(parsed: EpicArgv, flag: string): boolean {
+	return count_flag(parsed, flag) > SINGLE
 }
 
-// A value-taking flag given without a usable value: last on the line, or followed by another flag.
-// **Refused rather than read as "none was asked for"** — `--decision-file` is passed precisely because
-// the record has to exist, so a shell that ate the path would otherwise land the edit, write no
-// record, post no comment and exit 0: success reported for half the job. Repeated, it names two
-// records, which is refused for the reason two positioning flags are (joshuafolkken/kit#1350).
-function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
-	if (!argv.includes(flag)) return false
-	if (count_flag(argv, flag) > 1) return true
-	const value = read_flag_value(argv, flag)
+// The form's arguments, or `undefined` when a flag is unknown, a value is missing, or a value flag was
+// given twice — a repeat is refused rather than silently taking one of the two.
+function read_form(argv: ReadonlyArray<string>, form: FormFlags): EpicArgv | undefined {
+	const parsed = cli_flags.arguments_of(argv, options_of(form))
+	if (parsed === undefined) return undefined
 
-	return value === undefined || is_flag(value)
+	return (form.value_flags ?? []).some((flag) => is_repeated(parsed, flag)) ? undefined : parsed
 }
 
-// `--add` and `--remove` refuse a flag they do not know, unlike creation and promotion which ignore
-// one. A typo there costs a flag; here a mistyped flag would leave its value positional, so it
-// becomes an issue number and the edit silently lands somewhere else (joshuafolkken/kit#890).
-function has_unknown_flag(argv: ReadonlyArray<string>, known: ReadonlySet<string>): boolean {
-	return argv.some((argument) => is_flag(argument) && !known.has(argument))
+// The form's positional arguments, or none when the read refused the invocation.
+function positionals_of(argv: ReadonlyArray<string>, form: FormFlags): Array<string> {
+	return read_form(argv, form)?.positionals ?? []
+}
+
+function read_flag_value(parsed: EpicArgv, flag: string): string | undefined {
+	return values_of_flag(parsed, flag)[0]
+}
+
+function is_switch_set(parsed: EpicArgv, flag: string): boolean {
+	return parsed.values[cli_flags.option_name(flag)] === true
+}
+
+// A value-taking flag given without a usable value, or given twice. **Refused rather than read as "none
+// was asked for"** — `--decision-file` is passed precisely because the record has to exist, so a shell
+// that ate the path would otherwise land the edit, write no record, post no comment and exit 0: success
+// reported for half the job. Repeated, it names two records (joshuafolkken/kit#1350).
+function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
+	return (
+		cli_flags.given_values(argv, flag).length > SINGLE || cli_flags.is_value_unusable(argv, flag)
+	)
 }
 
 const epic_cli_argv = {
+	read_form,
+	positionals_of,
 	read_flag_value,
-	to_positional_arguments,
+	is_switch_set,
 	count_flag,
 	is_value_unusable,
-	has_unknown_flag,
 }
 
 export { epic_cli_argv, ISSUE_NUMBER_PATTERN }
+export type { EpicArgv, FormFlags }

package/scripts/epic/epic-cli-remove.ts

@@ -1,4 +1,4 @@
-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'
 
 // `josh epic --remove <E> <M> <N> …`'s argument rules (joshuafolkken/kit#1712).
 //
@@ -10,8 +10,7 @@ const REMOVE_FLAG = '--remove'
 const DECISION_FLAG = '--decision-file'
 // `--remove` takes no positioning flag: there is nothing for a removal to be relative to, and the
 // path itself says which orders go.
-const REMOVE_VALUE_FLAGS: ReadonlySet<string> = new Set([DECISION_FLAG])
-const REMOVE_KNOWN_FLAGS: ReadonlySet<string> = new Set([REMOVE_FLAG, DECISION_FLAG])
+const REMOVE_FORM: FormFlags = { switches: [REMOVE_FLAG], value_flags: [DECISION_FLAG] }
 // The shortest path that names an order at all: `<M> <N>`.
 const MINIMUM_PATH_LENGTH = 2
 
@@ -36,30 +35,23 @@ function to_path_numbers(raw_path: ReadonlyArray<string>): Array<number> | undef
 	return raw_path.length < MINIMUM_PATH_LENGTH ? undefined : raw_path.map(Number)
 }
 
-// A flag that makes the whole invocation unreadable, whatever the positional arguments say.
-function has_flag_refusal(argv: ReadonlyArray<string>): boolean {
-	return (
-		epic_cli_argv.has_unknown_flag(argv, REMOVE_KNOWN_FLAGS) ||
-		epic_cli_argv.is_value_unusable(argv, DECISION_FLAG)
-	)
-}
-
-function read_subject(
-	argv: ReadonlyArray<string>,
-): { epic_number: number; path: Array<number> } | undefined {
-	const [raw_epic, ...raw_path] = epic_cli_argv.to_positional_arguments(argv, REMOVE_VALUE_FLAGS)
+function read_subject(parsed: EpicArgv): { epic_number: number; path: Array<number> } | undefined {
+	const [raw_epic, ...raw_path] = parsed.positionals
 	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
 	const path = to_path_numbers(raw_path)
 
 	return path === undefined ? undefined : { epic_number: Number(raw_epic), path }
 }
 
+// An unknown flag, or a `--decision-file` a shell ate, makes the whole invocation unreadable whatever
+// the positional arguments say.
 function parse_remove_arguments(argv: ReadonlyArray<string>): RemoveArguments | undefined {
-	if (has_flag_refusal(argv)) return undefined
-	const subject = read_subject(argv)
-	if (subject === undefined) return undefined
+	if (epic_cli_argv.is_value_unusable(argv, DECISION_FLAG)) return undefined
+	const parsed = epic_cli_argv.read_form(argv, REMOVE_FORM)
+	const subject = parsed === undefined ? undefined : read_subject(parsed)
+	if (parsed === undefined || subject === undefined) return undefined
 
-	return { ...subject, decision_path: epic_cli_argv.read_flag_value(argv, DECISION_FLAG) }
+	return { ...subject, decision_path: epic_cli_argv.read_flag_value(parsed, DECISION_FLAG) }
 }
 
 const epic_cli_remove = {

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'