@joshuafolkken/kit 1.3044.0 → 1.3092.0

package/scripts/issue/defect-rate-cli.ts

@@ -1,7 +1,9 @@
 import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { z } from 'zod'
 import { defect_rate, type DefectRate } from './defect-rate'
 import { issue_search } from './issue-search'
+import { issue_search_count } from './issue-search-count'
 
 const MS_PER_MINUTE = 60_000
 const CACHE_TTL_MINUTES = 15
@@ -25,23 +27,22 @@ async function measure_uncached(
 	repo: string,
 	days: number,
 	since: string,
+	now_ms: number,
 ): Promise<DefectRate | undefined> {
 	const [filed, completed] = await Promise.all([
-		issue_search.search(defect_rate.filed_query(repo, since)),
-		issue_search.search(defect_rate.completed_query(repo, since)),
+		issue_search.search_complete(defect_rate.filed_query(repo, since), now_ms),
+		issue_search_count.count(defect_rate.completed_query(repo, since)),
 	])
 
 	if (filed === undefined || completed === undefined) return undefined
 
-	const is_capped = filed.is_capped || completed.is_capped
-
-	return defect_rate.measure({
+	return {
 		days,
 		since,
-		filed: filed.issues,
-		completed: completed.issues,
-		is_capped,
-	})
+		defects: filed.issues.filter((issue) => defect_rate.is_defect(issue)).length,
+		enhancements: completed,
+		is_capped: filed.is_capped,
+	}
 }
 
 // The rate over a window, or `undefined` when either search could not be read. `backlog:next` asks it.
@@ -54,10 +55,15 @@ async function measure_window(
 	const since = defect_rate.window_start(now_ms, days)
 	const key = [repo, String(days), since].join(' ')
 
-	return await shared_cache.remember(
-		{ slot: RATE_CACHE, key, schema: defect_rate_schema },
-		async () => await measure_uncached(repo, days, since),
-		now_ms,
+	return await run_startup.phase(
+		'defect rate',
+		async () =>
+			await shared_cache.remember(
+				{ slot: RATE_CACHE, key, schema: defect_rate_schema },
+				async () => await measure_uncached(repo, days, since, now_ms),
+				now_ms,
+			),
+		{ edge_of: (value) => (value === undefined ? 'failed' : 'done') },
 	)
 }
 

package/scripts/issue/issue-file-batch.ts

@@ -71,9 +71,13 @@ async function planned_of(
 async function scout_all(
 	planned: ReadonlyArray<Planned>,
 ): Promise<ReadonlyArray<ScoutOutcome | undefined>> {
-	const outcomes = await Promise.all(
-		planned.map(async ({ argv }) => await issue_file_cli.scout(argv)),
-	)
+	const outcomes: Array<ScoutOutcome | undefined> = []
+
+	for (const { argv } of planned) {
+		// eslint-disable-next-line no-await-in-loop -- scouts temporarily share GH_REPO
+		outcomes.push(await issue_file_cli.scout(argv))
+	}
+
 	const sections = planned.map(({ entry }, index) => {
 		const report = outcomes[index]?.report ?? SCOUT_UNANSWERED
 

package/scripts/issue/issue-file-cli.ts

@@ -26,6 +26,7 @@ import { issue_file_pass, type Filing } from './issue-file-pass'
 import { issue_file_worker } from './issue-file-worker'
 import { has_label_name, has_parked_label, RUN_SOLO_LABEL } from './issue-labels'
 import { issue_priority } from './issue-priority'
+import { issue_publication_state } from './issue-publication-state'
 import { issue_release_cli } from './issue-release-cli'
 import { issue_run_verdict } from './issue-run-verdict'
 import type { ScoutOutcome } from './issue-scout-cli'
@@ -79,8 +80,11 @@ async function create(filing: Filing, labels: ReadonlyArray<string>): Promise<st
 	)
 	const request = git_gh_issue_write.issue_create_request({
 		title: filing.args.title,
-		body: filing.body,
-		labels,
+		...issue_publication_state.creation(
+			filing.body,
+			labels,
+			filing.args.is_prepared === true || has_label_name(labels, 'route:split'),
+		),
 		repo: filing.target,
 	})
 
@@ -326,7 +330,9 @@ async function file_issue(
 ): Promise<string | undefined> {
 	const filing = await parsed_filing(argv)
 
-	return filing === undefined ? undefined : await file({ ...filing, scouted })
+	return filing === undefined
+		? undefined
+		: await issue_file_pass.with_repository_restored(async () => await file({ ...filing, scouted }))
 }
 
 // The scout `file_issue` would run, for `issue:file --batch` to run for every filing before the first.
@@ -334,16 +340,23 @@ async function scout(argv: ReadonlyArray<string>): Promise<ScoutOutcome | undefi
 	const args = issue_file.parse(argv)
 	const filing = args === undefined ? undefined : await filing_of(args)
 
-	return typeof filing === 'object' ? await issue_file_pass.scout_filing(filing) : undefined
+	return typeof filing === 'object'
+		? await issue_file_pass.with_repository_restored(
+				async () => await issue_file_pass.scout_filing(filing),
+			)
+		: undefined
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const filing = await parsed_filing(argv)
 
 	if (filing === undefined) return FAILURE_EXIT_CODE
-	if (filing.args.is_check) return await check(filing)
 
-	return (await file(filing)) === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	return await issue_file_pass.with_repository_restored(async () => {
+		if (filing.args.is_check) return await check(filing)
+
+		return (await file(filing)) === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	})
 }
 
 const issue_file_cli = {

package/scripts/issue/issue-file-main.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { issue_file_batch } from './issue-file-batch'
 import { issue_file_cli } from './issue-file-cli'
+import { issue_publication } from './issue-publication'
 
 // The `josh issue:file` entry, kept apart from `issue-file-cli.ts` because `upstream:interrupt` imports
 // that one: a bundle is one file, so a main guard there would fire for every command that carries it
@@ -13,5 +14,9 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	const argv = process.argv.slice(ARGV_OFFSET)
 	const filing = issue_file_batch.is_batch(argv) ? issue_file_batch : issue_file_cli
 
-	process.exitCode = await filing.run(argv)
+	const is_publication = argv.some(
+		(argument) => argument === '--publish' || argument.startsWith('--publish='),
+	)
+
+	process.exitCode = await (is_publication ? issue_publication : filing).run(argv)
 }

package/scripts/issue/issue-file-pass.ts

@@ -25,6 +25,22 @@ import { size_estimate } from './size-estimate'
 // scout and `epic:bundle` make at the target repository rather than at this checkout.
 const GH_REPO_VARIABLE = 'GH_REPO'
 
+function restore_repository(original: string | undefined): void {
+	if (original === undefined) Reflect.deleteProperty(process.env, GH_REPO_VARIABLE)
+	else process.env[GH_REPO_VARIABLE] = original
+}
+
+// Keep the target available through placement, then restore the caller's exact environment.
+async function with_repository_restored<Result>(action: () => Promise<Result>): Promise<Result> {
+	const original = process.env[GH_REPO_VARIABLE]
+
+	try {
+		return await action()
+	} finally {
+		restore_repository(original)
+	}
+}
+
 interface Filing {
 	args: FileArguments
 	body: string
@@ -243,6 +259,7 @@ const issue_file_pass = {
 	GH_REPO_VARIABLE,
 	labels_in_one_pass,
 	scout_filing,
+	with_repository_restored,
 }
 
 export { issue_file_pass }

package/scripts/issue/issue-file.ts

@@ -56,6 +56,7 @@ interface FileArguments {
 	is_blocking_finder: boolean
 	// `--check`: every filing step runs and prints its verdict, and nothing is created on GitHub.
 	is_check: boolean
+	is_prepared?: boolean
 }
 
 const OPTIONS = {
@@ -71,6 +72,7 @@ const OPTIONS = {
 	release: { type: 'boolean' },
 	'blocks-finder': { type: 'boolean' },
 	check: { type: 'boolean' },
+	prepare: { type: 'boolean' },
 } as const
 
 // The label a `--route` value names, or `undefined` when it names none — read against the route
@@ -157,6 +159,7 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		is_release: values.release === true,
 		is_blocking_finder: values['blocks-finder'] === true,
 		is_check: values.check === true,
+		is_prepared: values.prepare === true,
 	}
 }
 

package/scripts/issue/issue-not-before.ts

@@ -1,4 +1,5 @@
 import { issue_body_keys } from './issue-body-keys'
+import { issue_observation_gate } from './issue-observation-gate'
 import { issue_sample_gate } from './issue-sample-gate'
 import { markdown_section } from './markdown-section'
 import { measure_declaration } from './measure-declaration'
@@ -73,7 +74,11 @@ function is_date_due(body: string | undefined, now: number): boolean {
 
 // Whether the issue may start: its declared time has arrived and its declared samples are recorded.
 function is_due(body: string | undefined, now: number = Date.now()): boolean {
-	return is_date_due(body, now) && issue_sample_gate.wait_of(body) === undefined
+	return (
+		is_date_due(body, now) &&
+		issue_sample_gate.wait_of(body) === undefined &&
+		issue_observation_gate.wait_of(body) === undefined
+	)
 }
 
 // The declared time as epoch milliseconds while it is still ahead, or `undefined` when it has arrived —
@@ -97,7 +102,9 @@ function waiting_reason(body: string | undefined, now: number = Date.now()): str
 
 	const wait = issue_sample_gate.wait_of(body)
 
-	return wait === undefined ? undefined : issue_sample_gate.reason_of(wait)
+	return wait === undefined
+		? issue_observation_gate.wait_of(body)?.reason
+		: issue_sample_gate.reason_of(wait)
 }
 
 function stray_heading_problems(body: string): ReadonlyArray<string> {

package/scripts/issue/issue-observation-gate.ts

@@ -0,0 +1,141 @@
+import { lane_early_push_count } from '#scripts/lane/lane-early-push-count'
+import { markdown_section } from './markdown-section'
+
+// The issue pins both the evidence comment and every required key. Removing a task from the
+// comment cannot release it. This is an explicit, evidence-backed attestation, not a stop-text guess.
+const PREFIX = '<!-- josh:observation-wait'
+const DECLARATION =
+	/^<!-- josh:observation-wait:v1 (?<url>https:\/\/github\.com\/(?<repo>[\w.-]+\/[\w.-]+)\/issues\/[1-9]\d*#issuecomment-(?<comment>[1-9]\d*)) (?<keys>[\w-]+(?:,[\w-]+)*) -->$/u
+// An optional ledger condition before the close releases the wait once the ledger holds that many
+// samples (joshuafolkken/kit#7503); any metric but these is an unknown condition.
+const LEDGER = / ledger:(?<metric>[\w-]+)>=(?<minimum>[1-9]\d*)(?= -->$)/u
+const METRICS: ReadonlySet<string> = new Set([lane_early_push_count.MULTI_SLOT_EARLY_PUSH])
+const EVIDENCE_HEADING = '## Observation evidence'
+const TASK = /^- \[(?<checked>[ xX])\] (?<key>[\w-]+): (?<description>.+)$/u
+const EVIDENCE = /\[evidence\]\(https:\/\/github\.com\/[\w./#?=&%-]+\)$/u
+
+interface ObservationSource {
+	url: string
+	repo: string
+	comment: string
+	keys: ReadonlyArray<string>
+	ledger?: LedgerCondition | undefined
+}
+
+interface LedgerCondition {
+	metric: string
+	minimum: number
+}
+
+interface ObservationWait {
+	reason: string
+	url?: string | undefined
+}
+
+const records = new Map<string, string | undefined>()
+const samples = new Map<string, number>()
+
+function is_evidenced(task: Partial<Record<string, string>> | undefined): boolean {
+	return task?.['checked']?.toLowerCase() === 'x' && EVIDENCE.test(task['description'] ?? '')
+}
+
+function declarations(body = ''): ReadonlyArray<string> {
+	return markdown_section.unfenced_lines(body).filter((line) => line.trimStart().startsWith(PREFIX))
+}
+
+function ledger_of(line: string): LedgerCondition | undefined {
+	const groups = LEDGER.exec(line)?.groups
+	if (groups === undefined) return undefined
+
+	return { metric: String(groups['metric']), minimum: Number(groups['minimum']) }
+}
+
+function is_known(ledger: LedgerCondition | undefined): boolean {
+	return ledger === undefined || METRICS.has(ledger.metric)
+}
+
+function source_of(line: string): ObservationSource | undefined {
+	const trimmed = line.trim()
+	const ledger = ledger_of(trimmed)
+	if (!is_known(ledger)) return undefined
+	const groups = DECLARATION.exec(trimmed.replace(LEDGER, ''))?.groups
+	if (groups === undefined) return undefined
+
+	return {
+		url: String(groups['url']),
+		repo: String(groups['repo']),
+		comment: String(groups['comment']),
+		keys: String(groups['keys']).split(','),
+		ledger,
+	}
+}
+
+function is_sampled(ledger: LedgerCondition | undefined): boolean {
+	if (ledger === undefined) return false
+
+	return (samples.get(ledger.metric) ?? 0) >= ledger.minimum
+}
+
+function sources(bodies: ReadonlyArray<string | undefined>): ReadonlyArray<ObservationSource> {
+	return bodies.flatMap((body) => declarations(body).flatMap((line) => source_of(line) ?? []))
+}
+
+function pending(source: ObservationSource, body: string): ReadonlyArray<string> {
+	const lines = markdown_section.section_lines(body, EVIDENCE_HEADING).join('\n')
+	const tasks = markdown_section.unfenced_lines(lines).map((line) => TASK.exec(line)?.groups)
+
+	return source.keys.filter((key) => {
+		const matches = tasks.filter((task) => task?.['key'] === key)
+		const [task] = matches
+
+		return matches.length !== 1 || !is_evidenced(task)
+	})
+}
+
+function wait_for(line: string): ObservationWait | undefined {
+	const source = source_of(line)
+
+	if (source === undefined) {
+		return {
+			reason: 'unknown observation condition; record a v1 evidence comment and required keys',
+		}
+	}
+
+	if (is_sampled(source.ledger)) return undefined
+	const body = records.get(source.url)
+
+	if (body === undefined) {
+		return { reason: `observation evidence unread: ${source.keys.join(', ')}`, url: source.url }
+	}
+
+	const missing = pending(source, body)
+
+	return missing.length === 0
+		? undefined
+		: { reason: `observation evidence required: ${missing.join(', ')}`, url: source.url }
+}
+
+function wait_of(body?: string): ObservationWait | undefined {
+	return declarations(body)
+		.map((line) => wait_for(line))
+		.find((wait) => wait !== undefined)
+}
+
+function record(url: string, body: string | undefined): void {
+	records.set(url, body)
+}
+
+// The ledger's current count of a declared metric, primed with the evidence comments.
+function record_sample(metric: string, count: number): void {
+	samples.set(metric, count)
+}
+
+function reset(): void {
+	records.clear()
+	samples.clear()
+}
+
+const issue_observation_gate = { sources, wait_of, record, record_sample, reset }
+
+export type { LedgerCondition, ObservationSource }
+export { issue_observation_gate }

package/scripts/issue/issue-observation-prime.ts

@@ -0,0 +1,83 @@
+import { gh_author_association } from '#scripts/gh/gh-author-association'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { lane_early_push_count } from '#scripts/lane/lane-early-push-count'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { z } from 'zod'
+import { issue_observation_gate, type ObservationSource } from './issue-observation-gate'
+
+const comment_schema = z.object({
+	...gh_author_association.author_fields_schema,
+	body: z.string(),
+	html_url: z.string(),
+})
+
+type ReadSource = (source: ObservationSource) => Promise<string | undefined>
+type ReadLedger = () => Promise<ReadonlyArray<LedgerEntry>>
+
+// A checkout with no ledger (outside a repository, or a test run) has no samples.
+async function read_ledger(): Promise<ReadonlyArray<LedgerEntry>> {
+	const path = await lane_ledger.target()
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+async function read(source: ObservationSource): Promise<string | undefined> {
+	const path = `${git_gh_api_path.issues_api_path(source.repo)}/comments/${source.comment}`
+	const raw = await git_gh_exec.exec_gh_api({ path })
+	const comment = parse_json.parse_json_object_or_undefined(raw, comment_schema)
+	if (comment?.html_url !== source.url) return undefined
+	const author = { ...gh_author_association.author_of(comment), repo: source.repo }
+
+	return (await gh_author_association.is_trusted(author)) ? comment.body : undefined
+}
+
+async function remember(source: ObservationSource, read_source: ReadSource): Promise<void> {
+	try {
+		issue_observation_gate.record(source.url, await read_source(source))
+	} catch {
+		issue_observation_gate.record(source.url, undefined)
+	}
+}
+
+// Only a declaration naming a ledger condition reads the ledger; a failed read counts nothing.
+async function sample(
+	sources: ReadonlyArray<ObservationSource>,
+	read_entries: ReadLedger,
+): Promise<void> {
+	if (sources.every((source) => source.ledger === undefined)) return
+	let entries: ReadonlyArray<LedgerEntry> = []
+
+	try {
+		entries = await read_entries()
+	} catch {
+		// An unreadable ledger holds no sample.
+	}
+
+	issue_observation_gate.record_sample(
+		lane_early_push_count.MULTI_SLOT_EARLY_PUSH,
+		lane_early_push_count.multi_slot_pushed(entries),
+	)
+}
+
+// Re-read even a satisfied comment: a later correction or failed read must withhold the next offer.
+async function prime(
+	bodies: ReadonlyArray<string | undefined>,
+	read_source: ReadSource = read,
+	read_entries: ReadLedger = read_ledger,
+): Promise<void> {
+	const sources = issue_observation_gate.sources(bodies)
+	const unique = new Map(sources.map((source) => [source.url, source]))
+
+	await Promise.all([
+		sample(sources, read_entries),
+		...[...unique.values()].map(async (source) => {
+			await remember(source, read_source)
+		}),
+	])
+}
+
+const issue_observation_prime = { prime }
+
+export { issue_observation_prime }

package/scripts/issue/issue-publication-state.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod'
+import { issue_auto_ok } from './issue-auto-ok'
+import { AUTO_OK_LABEL, has_label_name } from './issue-labels'
+
+// A body record survives process termination without adding a workflow label or a user prohibition.
+const PREFIX = '<!-- josh:publication '
+const PATTERN = /<!-- josh:publication (?<record>[^\n]*?) -->/u
+const schema = z.object({ labels: z.array(z.string()) })
+
+function is_pending(body: string | undefined): boolean {
+	return body?.includes(PREFIX) === true
+}
+
+function prepare(body: string, labels: ReadonlyArray<string>): string {
+	if (is_pending(body)) throw new Error('Issue already contains a publication record')
+
+	return `${body}\n\n${PREFIX}${JSON.stringify({ labels })} -->\n`
+}
+
+function public_body(body: string): string {
+	return body.replace(PATTERN, '').trimEnd()
+}
+
+function intended_labels(body = ''): ReadonlyArray<string> {
+	const record = PATTERN.exec(body)?.groups?.['record']
+
+	return schema.parse(JSON.parse(record ?? 'null')).labels
+}
+
+function labels_of(
+	body: string | undefined,
+	current: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const intended = intended_labels(body)
+	const labels = current.filter((label) => !has_label_name([label], AUTO_OK_LABEL))
+	const decision = issue_auto_ok.decide({
+		is_opted_out: !has_label_name(intended, AUTO_OK_LABEL),
+		is_cross_repository: false,
+		body: public_body(body ?? ''),
+		labels,
+	})
+
+	return decision.is_applied ? [...labels, AUTO_OK_LABEL] : labels
+}
+
+function creation(
+	body: string,
+	labels: ReadonlyArray<string>,
+	is_prepared: boolean,
+): { body: string; labels: ReadonlyArray<string> } {
+	if (!is_prepared) return { body, labels }
+
+	return {
+		body: prepare(body, labels),
+		labels: labels.filter((label) => !has_label_name([label], AUTO_OK_LABEL)),
+	}
+}
+
+const issue_publication_state = { is_pending, prepare, public_body, labels_of, creation }
+
+export { issue_publication_state }

package/scripts/issue/issue-publication.ts

@@ -0,0 +1,144 @@
+import { repo_party } from '#scripts/discovery/repo-party'
+import type { EpicChild, IssueReference } from '#scripts/epic/epic-graph'
+import { epic_live } from '#scripts/epic/epic-live'
+import { epic_parse } from '#scripts/epic/epic-parse'
+import { epic_validate } from '#scripts/epic/epic-validate'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_memo } from '#scripts/gh/git-gh-issue-memo'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { has_label_name, PLANNED_LABEL } from './issue-labels'
+import { issue_number_shape } from './issue-number-shape'
+import { issue_publication_state } from './issue-publication-state'
+import { session_cite } from './session-cite'
+
+interface PreparedChild {
+	child: EpicChild
+	blockers: ReadonlyArray<IssueReference>
+}
+
+async function read_child(number: number, repo: string): Promise<PreparedChild> {
+	return {
+		child: await epic_live.child(number, repo),
+		blockers: await epic_live.blockers(number, repo),
+	}
+}
+
+function has_unrecorded_dependencies(prepared: PreparedChild, epic: EpicChild): boolean {
+	const { child, blockers } = prepared
+	const required = epic_parse
+		.parse_dependency_links(epic.body)
+		.filter((link) => link.blocked === child.number)
+
+	return required.some((link) =>
+		blockers.every((blocker) => blocker.repo !== child.repo || blocker.number !== link.blocker),
+	)
+}
+
+function validate_child(prepared: PreparedChild, epic: EpicChild): void {
+	const { child } = prepared
+	if (!issue_publication_state.is_pending(child.body)) return
+
+	const cited = session_cite.issue(child.number)
+	const is_planned = child.state === 'OPEN' && has_label_name(child.labels, PLANNED_LABEL)
+
+	if (!is_planned) {
+		throw new Error(`Publication withheld: ${cited} needs its recorded plan`)
+	}
+
+	if (has_unrecorded_dependencies(prepared, epic)) {
+		throw new Error(`Publication withheld: ${cited} has unrecorded dependencies`)
+	}
+
+	issue_publication_state.labels_of(child.body, child.labels)
+}
+
+async function publish_child({ child }: PreparedChild): Promise<void> {
+	const body = child.body ?? ''
+	if (!issue_publication_state.is_pending(body)) return
+
+	try {
+		await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.issue_api_path(String(child.number), child.repo),
+			method: 'PATCH',
+			body: JSON.stringify({
+				body: issue_publication_state.public_body(body),
+				labels: issue_publication_state.labels_of(body, child.labels),
+			}),
+		})
+	} finally {
+		git_gh_issue_memo.forget()
+	}
+}
+
+function require_first_party(repo: string): void {
+	const party = repo_party.classify(repo_party.current_owner(), repo_party.target_owner(repo))
+
+	if (party !== repo_party.FIRST_PARTY) {
+		throw new Error('Publication requires a known first-party tracker')
+	}
+}
+
+// Validate the entire batch before the first atomic body+labels publication. An interrupted batch
+// can be retried: published children are skipped, pending children still require all checks.
+async function publish(epic_number: number, repo: string): Promise<void> {
+	require_first_party(repo)
+	const epic = await epic_live.child(epic_number, repo)
+	const checks = epic_validate.validate_epic({ ...epic, body: epic.body })
+
+	if (!epic_validate.is_epic_valid(checks)) {
+		throw new Error('Publication withheld: epic is incomplete')
+	}
+
+	const children = await Promise.all(
+		epic_parse
+			.parse_task_list_issue_numbers(epic.body)
+			.map(async (number) => await read_child(number, repo)),
+	)
+	for (const child of children) validate_child(child, epic)
+
+	for (const child of children) {
+		// eslint-disable-next-line no-await-in-loop -- each atomic publish can be retried independently
+		await publish_child(child)
+	}
+}
+
+function epic_number_of(argv: ReadonlyArray<string>): string | undefined {
+	const parsed = cli_flags.arguments_of(argv, { publish: { type: 'string' } })
+	if (parsed === undefined || parsed.positionals.length > 0) return undefined
+	const number = parsed.values.publish
+
+	if (number === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(number)) {
+		return undefined
+	}
+
+	return number
+}
+
+async function publish_here(number: string): Promise<void> {
+	const repo = await git_gh_command.repo_get_name_with_owner()
+	if (repo === undefined) throw new Error('Cannot resolve publication repository')
+	await publish(Number(number), repo)
+	console.info(`Published prepared children of ${session_cite.issue(number)}`)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const number = epic_number_of(argv)
+	if (number === undefined) return 1
+
+	try {
+		await publish_here(number)
+
+		return 0
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return 1
+	}
+}
+
+const issue_publication = { publish, run }
+
+export { issue_publication }