@joshuafolkken/kit 1.1178.0 → 1.1229.0

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

@@ -14,20 +14,20 @@
 
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
 import { PACKAGE_DIR } from '#scripts/init/init-paths'
 import { bash_output_cap_reader } from './bash-output-cap'
-import { document_section, type Section } from './document-section'
+import { document_section } from './document-section'
+import { read_set_cost, type Cost } from './read-set-cost'
 import { read_set_point_of_use } from './read-set-point-of-use'
 
 const { POINT_OF_USE_FILES, POINT_OF_USE_BY_ENTRY, is_point_of_use, point_of_use_files } =
 	read_set_point_of_use
+const { cost_of, scoped_file_cost, total } = read_set_cost
 
 const SKILL_DIRECTORY = path.join('.claude', 'skills', 'workflow-commands')
 const SKILL_FILE = 'SKILL.md'
 const TABLE_SECTION = '1. Which file to read'
 const NOTHING = 0
-const ONE_LINE = 1
 
 // The point-of-use classification — which documents an entry names but reads only at a later step —
 // is its own concern, split into `read-set-point-of-use.ts` in joshuafolkken/kit#2289. This file
@@ -54,11 +54,6 @@ interface SectionReference {
 	heading: string
 }
 
-interface Cost {
-	bytes: number
-	tokens: number
-}
-
 interface SectionCost extends SectionReference {
 	cost: Cost
 	is_resolved: boolean
@@ -297,21 +292,6 @@ function read_set(root: string, entry: string): ReadSet {
 	return { entry, files, sections: sections_for(root, entry, files) }
 }
 
-function cost_of(text: string): Cost {
-	return { bytes: Buffer.byteLength(text, 'utf8'), tokens: cost_tokens.estimate(text) }
-}
-
-function total(costs: ReadonlyArray<Cost>): Cost {
-	const running = { bytes: NOTHING, tokens: NOTHING }
-
-	for (const cost of costs) {
-		running.bytes += cost.bytes
-		running.tokens += cost.tokens
-	}
-
-	return running
-}
-
 function section_cost(root: string, reference: SectionReference): SectionCost {
 	const found = document_section.section(read_document(root, reference.file), reference.heading)
 
@@ -334,74 +314,13 @@ function headings_for(sections: ReadonlyArray<SectionReference>, file: string):
 	return sections.filter((reference) => reference.file === file).map((one) => one.heading)
 }
 
-function add_range(charged: Set<number>, found: Section): void {
-	for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index)
-}
-
-// `undefined` the moment one heading does not resolve, because that reference is charged at its whole
-// file and there is then nothing to union.
-function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<number> | undefined {
-	const charged = new Set<number>()
-
-	for (const heading of headings) {
-		const found = document_section.section(markdown, heading)
-
-		if (found === undefined) return undefined
-
-		add_range(charged, found)
-	}
-
-	return charged
-}
-
-// **The union's charged lines are split into contiguous runs, and each run is costed on its own
-// natural text.** Joining non-adjacent lines with `\n` into one string fabricates a token boundary at
-// every gap the union skipped, so the estimate could drift a token *above* the per-reference sum even
-// with no real overlap — a false negative saving the measurement must never print
-// (joshuafolkken/kit#1934). A run is a maximal stretch of consecutive charged lines, which is exactly
-// the contiguous text a reader of that section actually reads, so summing the runs both mirrors the
-// real read and keeps `scoped` at or below the per-reference sum by construction.
-function extend_or_start(runs: Array<Array<number>>, index: number): void {
-	const current = runs.at(-1)
-
-	if (current?.at(-1) === index - ONE_LINE) current.push(index)
-	else runs.push([index])
-}
-
-function contiguous_runs(charged: ReadonlySet<number>): Array<Array<number>> {
-	const runs: Array<Array<number>> = []
-	const ascending = [...charged].toSorted((left, right) => left - right)
-
-	for (const index of ascending) extend_or_start(runs, index)
-
-	return runs
-}
-
-function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): string {
-	return run.map((index) => lines[index] ?? '').join('\n')
-}
-
-// **Charged per file over the union of the lines its references cover, never per reference.**
-// Summing the references instead double-counts the two ways one file can be cited twice — two
-// unresolved headings each charged at the whole file, and a `##` section cited beside one of its own
-// `###` children, which `section()` already returns inside the parent. Either one could push the
-// scoped figure above the whole one and print a *negative* saving, which is the single direction this
-// measurement must not be able to move (joshuafolkken/kit#1776 review round 1).
-function file_scoped_cost(root: string, file: string, headings: ReadonlyArray<string>): Cost {
-	const markdown = read_document(root, file)
-	const charged = charged_lines(markdown, headings)
-
-	if (charged === undefined) return cost_of(markdown)
-
-	const lines = markdown.split('\n')
-
-	return total(contiguous_runs(charged).map((run) => cost_of(run_text(lines, run))))
-}
-
+// The per-file union that keeps `scoped` at or below `whole` lives in `read-set-cost.ts`.
 function scoped_cost(root: string, sections: ReadonlyArray<SectionReference>): Cost {
 	const files = unique(sections.map((reference) => reference.file))
 
-	return total(files.map((file) => file_scoped_cost(root, file, headings_for(sections, file))))
+	return total(
+		files.map((file) => scoped_file_cost(read_document(root, file), headings_for(sections, file))),
+	)
 }
 
 function file_costs(root: string, names: ReadonlyArray<string>): Array<FileCost> {
@@ -491,5 +410,7 @@ const entry_read_set = {
 	total,
 }
 
-export type { Cost, FileCost, ReadSet, ReadSetCost, SectionCost, SectionReference }
+export type { FileCost, ReadSet, ReadSetCost, SectionCost, SectionReference }
 export { entry_read_set }
+
+export { type Cost } from './read-set-cost'

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

@@ -0,0 +1,98 @@
+import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
+import { document_section, type Section } from './document-section'
+
+// What a read costs, and the scoped union that charges one file's cited sections once — split out
+// of `entry-read-set.ts` when it reached its line limit (joshuafolkken/kit#3264). `entry_read_set`
+// re-exports `cost_of`, `total` and `Cost` under the names they always had, so the move changed no
+// call site.
+
+const NOTHING = 0
+const ONE_LINE = 1
+
+interface Cost {
+	bytes: number
+	tokens: number
+}
+
+function cost_of(text: string): Cost {
+	return { bytes: Buffer.byteLength(text, 'utf8'), tokens: cost_tokens.estimate(text) }
+}
+
+function total(costs: ReadonlyArray<Cost>): Cost {
+	const running = { bytes: NOTHING, tokens: NOTHING }
+
+	for (const cost of costs) {
+		running.bytes += cost.bytes
+		running.tokens += cost.tokens
+	}
+
+	return running
+}
+
+function add_range(charged: Set<number>, found: Section): void {
+	for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index)
+}
+
+// `undefined` the moment one heading does not resolve, because that reference is charged at its whole
+// file and there is then nothing to union.
+function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<number> | undefined {
+	const charged = new Set<number>()
+
+	for (const heading of headings) {
+		const found = document_section.section(markdown, heading)
+
+		if (found === undefined) return undefined
+
+		add_range(charged, found)
+	}
+
+	return charged
+}
+
+// **The union's charged lines are split into contiguous runs, and each run is costed on its own
+// natural text.** Joining non-adjacent lines with `\n` into one string fabricates a token boundary at
+// every gap the union skipped, so the estimate could drift a token *above* the per-reference sum even
+// with no real overlap — a false negative saving the measurement must never print
+// (joshuafolkken/kit#1934). A run is a maximal stretch of consecutive charged lines, which is exactly
+// the contiguous text a reader of that section actually reads, so summing the runs both mirrors the
+// real read and keeps `scoped` at or below the per-reference sum by construction.
+function extend_or_start(runs: Array<Array<number>>, index: number): void {
+	const current = runs.at(-1)
+
+	if (current?.at(-1) === index - ONE_LINE) current.push(index)
+	else runs.push([index])
+}
+
+function contiguous_runs(charged: ReadonlySet<number>): Array<Array<number>> {
+	const runs: Array<Array<number>> = []
+	const ascending = [...charged].toSorted((left, right) => left - right)
+
+	for (const index of ascending) extend_or_start(runs, index)
+
+	return runs
+}
+
+function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): string {
+	return run.map((index) => lines[index] ?? '').join('\n')
+}
+
+// **Charged per file over the union of the lines its references cover, never per reference.**
+// Summing the references instead double-counts the two ways one file can be cited twice — two
+// unresolved headings each charged at the whole file, and a `##` section cited beside one of its own
+// `###` children, which `section()` already returns inside the parent. Either one could push the
+// scoped figure above the whole one and print a *negative* saving, which is the single direction this
+// measurement must not be able to move (joshuafolkken/kit#1776 review round 1).
+function scoped_file_cost(markdown: string, headings: ReadonlyArray<string>): Cost {
+	const charged = charged_lines(markdown, headings)
+
+	if (charged === undefined) return cost_of(markdown)
+
+	const lines = markdown.split('\n')
+
+	return total(contiguous_runs(charged).map((run) => cost_of(run_text(lines, run))))
+}
+
+const read_set_cost = { cost_of, scoped_file_cost, total }
+
+export type { Cost }
+export { read_set_cost }

package/scripts/epic/epic-add-body.ts

@@ -147,6 +147,7 @@ function splice_declaration(
 		if (index === input.first) return [...input.rendered]
 		if (input.dropped.has(index)) return []
 
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- one return type (sonarjs/function-return-type)
 		return [line]
 	})
 }

package/scripts/epic/epic-audit-checks.ts

@@ -301,7 +301,7 @@ function reported_references(
 		.flatMap((reference) => {
 			const state = reported_state(states, reference)
 
-			return state === undefined ? [] : [{ reference, state }]
+			return state === undefined ? [] : { reference, state }
 		})
 }
 

package/scripts/epic/epic-audit-rationale.ts

@@ -73,9 +73,10 @@ function order_pairs(
 		const blocked = find_child(children, { repo: epic_repo, number: link.blocked })
 		if (blocker === undefined || blocked === undefined) return []
 
-		return is_open_local(blocker, current_repo) && is_open_local(blocked, current_repo)
-			? [{ blocker, blocked }]
-			: []
+		if (!is_open_local(blocker, current_repo) || !is_open_local(blocked, current_repo)) return []
+
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- one return type (sonarjs/function-return-type)
+		return [{ blocker, blocked }]
 	})
 }
 

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 = {