@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,43 +1,36 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { issue_label_schema } 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 { issue_cite } from '#scripts/issue/issue-cite'
 import { session_cite } from '#scripts/issue/session-cite'
 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 {
-	epic_bundle,
-	type BacklogIssue,
-	type BundleAction,
-	type BundleDecision,
-	type MembershipContext,
-} from './epic-bundle'
-import { epic_bundle_evidence } from './epic-bundle-evidence'
+import { epic_bundle, type BacklogIssue, type MembershipContext } from './epic-bundle'
+import { epic_bundle_apply } from './epic-bundle-apply'
+import { epic_bundle_format } from './epic-bundle-format'
 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'
-import { format_dependency_links, type IssueReference } from './epic-reference'
+import type { IssueReference } from './epic-reference'
 
 // `josh epic:bundle <N>` — after an issue is filed, look at the open backlog and say whether it
 // belongs with something already there.
 //
 // The machine finds the candidates; the decision to bundle is the caller's. This command prints what
-// it found and what it recommends, and writes nothing.
+// it found and what it recommends, and writes nothing — unless `--apply` asks it to write the answers
+// whose placement is settled (`epic-bundle-apply.ts`).
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // The open backlog was 13 issues when this was written. Scanning all of them is instant, so there is
 // no index and no cache; add one when the number makes it necessary, not before.
 const BACKLOG_LIMIT = 200
-const USAGE = 'Usage: josh epic:bundle <issue-number>'
+const APPLY_FLAG = '--apply'
+const USAGE = 'Usage: josh epic:bundle <issue-number> [--apply]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the backlog cannot be keyed by repository — check `gh auth status` and that this is a checkout with an `origin` remote.'
 
@@ -202,23 +195,7 @@ async function fetch_backlog(
 	}
 }
 
-const ACTION_LINES: Readonly<Record<string, string>> = {
-	add_to_epic: 'Add it to the epic that already tracks a related issue (Tier A — do it).',
-	create_epic: 'Create an epic for these (Tier A — do it).',
-	ask: 'Related issues sit in more than one epic: choose the one you recommend, add it, and record why (Tier A — do it).',
-	none: 'Nothing to bundle.',
-}
-
-// `Nothing to bundle.` is right when nothing was found, and wrong when an epic already tracks the
-// issue — there the answer is actionable: a caller looking for somewhere to put a prerequisite adds
-// it to *that* epic rather than creating a second one.
-const ALREADY_TRACKED_LINE = 'Already in an epic — add to that one, do not create a second.'
-
-function headline(decision: BundleDecision): string {
-	if (decision.action === 'none' && decision.epics.length > 0) return ALREADY_TRACKED_LINE
-
-	return ACTION_LINES[decision.action] ?? ''
-}
+const { format_decision } = epic_bundle_format
 
 // The epics currently open, at this command's own listing limit. A failed read stays `undefined` and
 // is reported: without the list, an issue an epic already tracks is told to create a second one —
@@ -227,72 +204,6 @@ async function fetch_epics(): Promise<FetchedEpics | undefined> {
 	return await epic_index.fetch_epics(BACKLOG_LIMIT)
 }
 
-function format_numbers(numbers: ReadonlyArray<number>): string {
-	return numbers.map((issue_number) => issue_cite.plain(issue_number)).join(', ')
-}
-
-// The order to record alongside the bundle. Bundling without it records the batch and loses the
-// reason it is a batch, so the recommendation carries it rather than leaving it to be remembered.
-function format_links(links: ReadonlyArray<{ blocker: number; blocked: number }>): string {
-	if (links.length === 0) return '  Order: none declared — do not invent one'
-
-	return `  Order: ${format_dependency_links(links)}`
-}
-
-function format_order(
-	decision: BundleDecision,
-	subject: BacklogIssue,
-	backlog: ReadonlyArray<BacklogIssue>,
-): Array<string> {
-	if (decision.action !== 'add_to_epic' && decision.action !== 'create_epic') return []
-	const members = backlog.filter((issue) => decision.candidates.includes(issue.number))
-	const children = epic_bundle.bundle_children(subject, members)
-
-	// The evidence goes under the order rather than beside the verdict: what it explains is the
-	// order, and a reader checking one reads straight on into the other.
-	return [
-		`  Children: ${format_numbers(children)}`,
-		format_links(epic_bundle.bundle_dependency_links(subject, members)),
-		...epic_bundle_evidence.format_evidence(subject, members),
-	]
-}
-
-// The verdicts that put the subject into an epic. Each one asserts that no epic already tracks it —
-// `create_epic` asserts as much about the candidates too — and that negative is exactly what a cut
-// epic listing cannot establish. `none` is absent on purpose: it either
-// names the epic it *found* tracking the subject, which a cut cannot unseat, or reports no candidate
-// at all, which says nothing about epics.
-const PLACING_ACTIONS: ReadonlySet<BundleAction> = new Set<BundleAction>([
-	'add_to_epic',
-	'create_epic',
-	'ask',
-])
-
-// `is_membership_established` is what separates "no epic tracks these" from "their epics were never
-// read".
-function format_decision(
-	decision: BundleDecision,
-	subject: BacklogIssue,
-	backlog: ReadonlyArray<BacklogIssue>,
-	is_membership_established: boolean,
-): string {
-	if (!is_membership_established && PLACING_ACTIONS.has(decision.action)) {
-		return epic_bundle_gaps.unconfirmed_membership(format_numbers(decision.candidates)).join('\n')
-	}
-
-	const lines = [headline(decision), `  ${decision.reason}`]
-
-	if (decision.candidates.length > 0) {
-		lines.push(`  Related: ${format_numbers(decision.candidates)}`)
-	}
-
-	if (decision.epics.length > 1) {
-		lines.push(`  Epics involved: ${format_numbers(decision.epics)}`)
-	}
-
-	return [...lines, ...format_order(decision, subject, backlog)].join('\n')
-}
-
 // The open backlog and the epics tracking it, read once.
 async function read_backlog(repo: string, options?: BacklogOptions): Promise<FetchedBacklog> {
 	const open_epics = await fetch_epics()
@@ -366,7 +277,13 @@ function warn_about_gaps(backlog: FetchedBacklog): void {
 	warn_cutoff(epic_bundle_gaps.epic_gap(backlog.epic_cutoff ?? NO_CUTOFF, BACKLOG_LIMIT))
 }
 
-function report_decision(subject: BacklogIssue, backlog: FetchedBacklog, repo: string): number {
+// The report always prints; `--apply` then writes what it settled (`epic-bundle-apply.ts`).
+async function report_decision(
+	subject: BacklogIssue,
+	backlog: FetchedBacklog,
+	repo: string,
+	is_apply: boolean,
+): Promise<number> {
 	const others = backlog.issues.filter((issue) => issue.number !== subject.number)
 	const is_established = epic_bundle_gaps.is_membership_established(backlog.epic_cutoff)
 	const decision = epic_bundle.decide_bundle(subject, others)
@@ -376,8 +293,14 @@ function report_decision(subject: BacklogIssue, backlog: FetchedBacklog, repo: s
 	const report = format_decision(decision, subject, others, is_established)
 
 	console.info(issue_citation.linkify(report, repo))
-
-	return SUCCESS_EXIT_CODE
+	if (!is_apply) return SUCCESS_EXIT_CODE
+
+	return await epic_bundle_apply.apply_decision({
+		decision,
+		subject,
+		members: epic_bundle_format.members_of(decision, others),
+		is_membership_established: is_established,
+	})
 }
 
 // Widen, report what the read could not cover, then decide. Split out of `report_for`, which is
@@ -386,12 +309,13 @@ async function report_widened(
 	subject: BacklogIssue,
 	backlog: FetchedBacklog,
 	repo: string,
+	is_apply: boolean,
 ): Promise<number> {
 	const widened = await widen_with_referenced(subject, backlog)
 
 	warn_about_gaps(widened)
 
-	return report_decision(subject, widened, repo)
+	return await report_decision(subject, widened, repo, is_apply)
 }
 
 // The recommendation for one issue, from the open backlog around it. `options` is the poll a caller
@@ -400,6 +324,7 @@ async function report_for(
 	issue_number: number,
 	repo: string,
 	options?: PollOptions,
+	is_apply = false,
 ): Promise<number> {
 	const backlog = await epic_bundle_poll.read_until_listed(
 		async () => await read_backlog(repo),
@@ -423,11 +348,12 @@ async function report_for(
 		return FAILURE_EXIT_CODE
 	}
 
-	return await report_widened(subject, backlog, repo)
+	return await report_widened(subject, backlog, repo, is_apply)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const issue_number = epic_issue.parse_epic_number(argv[0])
+	const raw_issue = argv.find((argument) => argument !== APPLY_FLAG)
+	const issue_number = epic_issue.parse_epic_number(raw_issue)
 
 	if (issue_number === undefined) {
 		console.error(USAGE)
@@ -448,25 +374,14 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await report_for(issue_number, repo)
-}
-
-// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
-// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains. This
-// command's answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
-// is in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
+	return await report_for(issue_number, repo, undefined, argv.includes(APPLY_FLAG))
 }
 
 const epic_bundle_cli = {
 	USAGE,
 	BACKLOG_LIMIT,
-	ACTION_LINES,
-	ALREADY_TRACKED_LINE,
+	...epic_bundle_format,
 	build_epic_index,
-	format_numbers,
-	format_order,
 	unreadable_backlog_message,
 	read_backlog,
 	report_for,
@@ -474,11 +389,7 @@ const epic_bundle_cli = {
 	fetch_backlog,
 	widen_with_referenced,
 	warn_about_gaps,
-	format_decision,
 	run,
-	main,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { epic_bundle_cli }

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

@@ -0,0 +1,116 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import {
+	epic_bundle,
+	type BacklogIssue,
+	type BundleAction,
+	type BundleDecision,
+} from './epic-bundle'
+import { epic_bundle_evidence } from './epic-bundle-evidence'
+import { epic_bundle_gaps } from './epic-bundle-gaps'
+import { format_dependency_links } from './epic-reference'
+
+// How `josh epic:bundle` words its verdict. Split out of `epic-bundle-cli.ts`, which reads the backlog,
+// when `--apply` pushed that file past its line ceiling; the wording has no reads of its own.
+
+const ACTION_LINES: Readonly<Record<string, string>> = {
+	add_to_epic: 'Add it to the epic that already tracks a related issue (Tier A — do it).',
+	create_epic: 'Create an epic for these (Tier A — do it).',
+	ask: 'Related issues sit in more than one epic: choose the one you recommend, add it, and record why (Tier A — do it).',
+	none: 'Nothing to bundle.',
+}
+
+// `Nothing to bundle.` is right when nothing was found, and wrong when an epic already tracks the
+// issue — there the answer is actionable: a caller looking for somewhere to put a prerequisite adds
+// it to *that* epic rather than creating a second one.
+const ALREADY_TRACKED_LINE = 'Already in an epic — add to that one, do not create a second.'
+
+function headline(decision: BundleDecision): string {
+	if (decision.action === 'none' && decision.epics.length > 0) return ALREADY_TRACKED_LINE
+
+	return ACTION_LINES[decision.action] ?? ''
+}
+
+function format_numbers(numbers: ReadonlyArray<number>): string {
+	return numbers.map((issue_number) => issue_cite.plain(issue_number)).join(', ')
+}
+
+// The backlog rows of the verdict's candidates — what the printed order and `--apply` both read.
+function members_of(
+	decision: BundleDecision,
+	backlog: ReadonlyArray<BacklogIssue>,
+): Array<BacklogIssue> {
+	return backlog.filter((issue) => decision.candidates.includes(issue.number))
+}
+
+// The order to record alongside the bundle. Bundling without it records the batch and loses the
+// reason it is a batch, so the recommendation carries it rather than leaving it to be remembered.
+function format_links(links: ReadonlyArray<{ blocker: number; blocked: number }>): string {
+	if (links.length === 0) return '  Order: none declared — do not invent one'
+
+	return `  Order: ${format_dependency_links(links)}`
+}
+
+function format_order(
+	decision: BundleDecision,
+	subject: BacklogIssue,
+	backlog: ReadonlyArray<BacklogIssue>,
+): Array<string> {
+	if (decision.action !== 'add_to_epic' && decision.action !== 'create_epic') return []
+	const members = members_of(decision, backlog)
+	const children = epic_bundle.bundle_children(subject, members)
+
+	// The evidence goes under the order rather than beside the verdict: what it explains is the
+	// order, and a reader checking one reads straight on into the other.
+	return [
+		`  Children: ${format_numbers(children)}`,
+		format_links(epic_bundle.bundle_dependency_links(subject, members)),
+		...epic_bundle_evidence.format_evidence(subject, members),
+	]
+}
+
+// The verdicts that put the subject into an epic. Each one asserts that no epic already tracks it —
+// `create_epic` asserts as much about the candidates too — and that negative is exactly what a cut
+// epic listing cannot establish. `none` is absent on purpose: it either
+// names the epic it *found* tracking the subject, which a cut cannot unseat, or reports no candidate
+// at all, which says nothing about epics.
+const PLACING_ACTIONS: ReadonlySet<BundleAction> = new Set<BundleAction>([
+	'add_to_epic',
+	'create_epic',
+	'ask',
+])
+
+// `is_membership_established` is what separates "no epic tracks these" from "their epics were never
+// read".
+function format_decision(
+	decision: BundleDecision,
+	subject: BacklogIssue,
+	backlog: ReadonlyArray<BacklogIssue>,
+	is_membership_established: boolean,
+): string {
+	if (!is_membership_established && PLACING_ACTIONS.has(decision.action)) {
+		return epic_bundle_gaps.unconfirmed_membership(format_numbers(decision.candidates)).join('\n')
+	}
+
+	const lines = [headline(decision), `  ${decision.reason}`]
+
+	if (decision.candidates.length > 0) {
+		lines.push(`  Related: ${format_numbers(decision.candidates)}`)
+	}
+
+	if (decision.epics.length > 1) {
+		lines.push(`  Epics involved: ${format_numbers(decision.epics)}`)
+	}
+
+	return [...lines, ...format_order(decision, subject, backlog)].join('\n')
+}
+
+const epic_bundle_format = {
+	ACTION_LINES,
+	ALREADY_TRACKED_LINE,
+	format_numbers,
+	format_order,
+	format_decision,
+	members_of,
+}
+
+export { epic_bundle_format }

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

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { epic_bundle_cli } from './epic-bundle-cli'
+
+// The `josh epic:bundle` entry, kept apart from `epic-bundle-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+//
+// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
+// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains. This
+// command's answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
+// is in `scripts/cost-runtime/cost-main.ts`, which met the truncation first.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await epic_bundle_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/epic/epic-busy.ts

@@ -1,12 +1,7 @@
 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 {
-	ALREADY_DONE_LABEL,
-	has_any_label,
-	IN_PROGRESS_LABEL,
-	NEEDS_DECISION_LABEL,
-} from '#scripts/issue/issue-labels'
+import { has_any_label, IN_PROGRESS_LABEL, PARKED_LABELS } from '#scripts/issue/issue-labels'
 import { session_cite } from '#scripts/issue/session-cite'
 
 // How much of a repository's parallelism is already spoken for — asked of the *repository*, never of
@@ -34,12 +29,10 @@ const LISTING_LIMIT = 100
 // Read through `has_any_label` rather than compared directly, for the casing reason
 // `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
 //
-// `already-done` joins `needs-decision` here for the same reason it joins it in
-// `epic_classify.local_category`: the run that applied it committed
-// nothing, so the checkout it ran in is clean and there is no uncommitted work for the next child to
-// start on top of. That is exactly what separates both from `needs-human-review`, which is
-// deliberately not parked because its work is still sitting in the tree.
-const PARKED_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
+// The park labels (`PARKED_LABELS`): `already-done` and `run:stalled` join `needs-decision` here for
+// the same reason they join it in `epic_classify.local_category`: the run that applied one leaves no
+// uncommitted work for the next child to start on top of. That is exactly what separates them from
+// `needs-human-review`, which is deliberately not parked because its work is still sitting in the tree.
 
 // What one repository answered. `unreadable` is kept apart from `idle` because reading a failed
 // read as an empty listing is a confident absence

package/scripts/epic/epic-classify.ts

@@ -1,9 +1,5 @@
-import {
-	ALREADY_DONE_LABEL,
-	has_label_name,
-	IN_PROGRESS_LABEL,
-	NEEDS_DECISION_LABEL,
-} from '#scripts/issue/issue-labels'
+import { has_label_name, has_parked_label, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 import { epic_nested } from './epic-nested'
 import {
@@ -48,14 +44,18 @@ function has_label(child: EpicChild, label: string): boolean {
 	return has_label_name(child.labels, label)
 }
 
-// The labels that put a child in `human` on their own. `needs-decision` waits for an answer nobody
-// has given; `already-done` has its answer — the work is merged, and the close that is left is Tier C
-// and so a person's. Neither is resolved by waiting, which is what separates
-// them from `in-progress` below.
-const HUMAN_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
-
+// The park labels (`PARKED_LABELS`) put a child in `human` on their own. `needs-decision` waits for an
+// answer nobody has given; `already-done` has its answer — the work is merged, and the close that is
+// left is Tier C and so a person's; `run:stalled` waits on a person fixing a mechanical cause. None is
+// resolved by waiting, which is what separates them from `in-progress` below.
 function has_human_label(child: EpicChild): boolean {
-	return HUMAN_LABELS.some((label) => has_label(child, label))
+	return has_parked_label(child.labels)
+}
+
+// A child someone else's session is finishing, or one held until its declared start time
+// (joshuafolkken/kit#4007). Either way waiting resolves it.
+function is_waiting(child: EpicChild): boolean {
+	return has_label(child, IN_PROGRESS_LABEL) || !issue_not_before.is_due(child.body)
 }
 
 // What a child is before its dependencies are considered. A parked child is `human` whatever blocks
@@ -71,7 +71,7 @@ function has_human_label(child: EpicChild): boolean {
 function local_category(child: EpicChild): ChildCategory | undefined {
 	if (child.state === CLOSED) return 'done'
 	if (epic_nested.is_nested_epic(child) || has_human_label(child)) return 'human'
-	if (has_label(child, IN_PROGRESS_LABEL)) return 'time'
+	if (is_waiting(child)) return 'time'
 
 	return undefined
 }
@@ -117,8 +117,16 @@ function reset_reported(): void {
 	reported.clear()
 }
 
+// Silenced for a process that draws the withheld blocker itself: `run:board` leads its row with 🙋
+// (joshuafolkken/kit#4292), so the notice would only scribble over the board.
+const silence = { is_muted: false }
+
+function mute_notices(): void {
+	silence.is_muted = true
+}
+
 function report_notice(notice: OutsideNotice): void {
-	if (reported.has(notice.key)) return
+	if (silence.is_muted || reported.has(notice.key)) return
 
 	reported.add(notice.key)
 	console.warn(notice.message)
@@ -282,6 +290,7 @@ function classify_children(
 
 const epic_classify = {
 	resolve_by_state,
+	mute_notices,
 	reset_reported,
 	local_category,
 	classify_children,

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

@@ -1,4 +1,5 @@
 import type { ParseArgsOptionsConfig } from 'node:util'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 
 // The argument reading every `josh epic` form shares, on top of `cli_flags`.
@@ -32,9 +33,9 @@ interface FormFlags {
 	value_flags?: ReadonlyArray<string>
 }
 
-type OptionEntry = [string, ParseArgsOptionsConfig[string]]
-
 function options_of(form: FormFlags): ParseArgsOptionsConfig {
+	type OptionEntry = [string, ParseArgsOptionsConfig[string]]
+
 	const entries: Array<OptionEntry> = [
 		...form.switches.map((flag): OptionEntry => [cli_flags.option_name(flag), SWITCH_OPTION]),
 		...(form.value_flags ?? []).map((flag): OptionEntry => [
@@ -94,7 +95,37 @@ function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
 	)
 }
 
+// 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> {
+	const numbers = raw_children
+		.filter((raw) => issue_number_shape.is_issue_number(raw))
+		.map(Number)
+		.filter((value) => Number.isSafeInteger(value))
+
+	return [...new Set(numbers)]
+}
+
+// `<E> <N1> <N2> …` — the shape `--promote`, `--add` and `--decide` share: an existing issue, then at
+// least one child other than itself.
+function read_epic_children(
+	parsed: EpicArgv,
+): { epic_number: number; children: Array<number> } | undefined {
+	const [raw_epic, ...raw_children] = parsed.positionals
+
+	if (raw_epic === undefined || !issue_number_shape.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)
+
+	return children.length === 0 ? undefined : { epic_number, children }
+}
+
 const epic_cli_argv = {
+	to_child_numbers,
+	read_epic_children,
 	read_form,
 	positionals_of,
 	read_flag_value,

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

@@ -0,0 +1,42 @@
+import { epic_cli_argv, type FormFlags } from './epic-cli-argv'
+
+// `josh epic --decide <E> <N...> --decision-file <path|->`'s argument rules — a decision about children
+// the epic already tracks, which `--add --decision-file` refuses as an insertion with nothing to add.
+//
+// Its own module for the reason `--remove` has one: `epic-cli.ts` sits at its line ceiling.
+
+const DECIDE_FLAG = '--decide'
+const DECISION_FLAG = '--decision-file'
+const DECIDE_FORM: FormFlags = { switches: [DECIDE_FLAG], value_flags: [DECISION_FLAG] }
+
+interface DecideArguments {
+	epic_number: number
+	children: Array<number>
+	decision_path: string
+}
+
+// Whether the invocation records a decision rather than creating, promoting or editing the epic.
+function is_decision_entry(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(DECIDE_FLAG)
+}
+
+// The record is the whole point of the form, so a missing or unusable `--decision-file` refuses it
+// rather than reading as "nothing to record".
+function parse_decide_arguments(argv: ReadonlyArray<string>): DecideArguments | undefined {
+	if (epic_cli_argv.is_value_unusable(argv, DECISION_FLAG)) return undefined
+	const parsed = epic_cli_argv.read_form(argv, DECIDE_FORM)
+	if (parsed === undefined) return undefined
+	const subject = epic_cli_argv.read_epic_children(parsed)
+	const decision_path = epic_cli_argv.read_flag_value(parsed, DECISION_FLAG)
+	if (subject === undefined || decision_path === undefined) return undefined
+
+	return { ...subject, decision_path }
+}
+
+const epic_cli_decide = {
+	is_decision_entry,
+	parse_decide_arguments,
+}
+
+export { epic_cli_decide, DECIDE_FLAG }
+export type { DecideArguments }