@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

@@ -1,19 +1,20 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { IssueRead } from '#scripts/gh/git-gh-issue-read'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { issue_cite, type CiteTarget } from './issue-cite'
 
 // `josh issue:cite <N> [<N> ...] [--repo <owner/repo>]` — the paste-ready citation line for every
-// Issue named, in one call (joshuafolkken/kit#2220).
+// Issue named, in one call.
 //
-// It answers the cost that made the bare `#N` cheaper than the correct citation: the title each line
-// needs used to be a per-Issue `gh api` read, and naming several Issues at once — a backlog listing, a
-// lane status report — meant several round trips before a single correct line could be written. The
-// numbers go in together and the titles come back together, so the correct form is now the cheap one.
+// It answers the cost that makes the bare `#N` cheaper than the correct citation: a per-Issue
+// `gh api` read for each title means several round trips before a single correct line of a backlog
+// listing or lane status report can be written. The numbers go in together and the titles come back
+// together, so the correct form is the cheap one.
 //
 // **A token that is not a number refuses the whole invocation**, exactly as `issue:read` does: an
 // argument the parser cannot read is a mistake, and dropping it answers fewer Issues than were asked
@@ -30,6 +31,7 @@ const READ_CONCURRENCY = 8
 const TITLE_FIELD = 'title'
 const LINE_SEPARATOR = '\n'
 const USAGE = 'Usage: josh issue:cite <issue-number|owner/repo#N> [ ... ] [--repo <owner/repo>]'
+const OPTIONS = { repo: { type: 'string' } } as const
 
 const title_schema = z.looseObject({ title: z.string() })
 
@@ -38,13 +40,9 @@ type LineResult = { kind: 'ok'; line: string } | { kind: 'fail'; line: string }
 // The title out of the one-field read, or `undefined` for an empty or unparseable one — an empty title
 // is not a summary, so it is reported as a read that produced nothing rather than cited as a blank.
 function parse_title(json: string): string | undefined {
-	try {
-		const title = title_schema.parse(JSON.parse(json)).title.trim()
+	const title = json_value.parse_with(json, title_schema)?.title.trim()
 
-		return title === '' ? undefined : title
-	} catch {
-		return undefined
-	}
+	return title === '' ? undefined : title
 }
 
 // A read's outcome as one line: the citation on success, the matching failure line otherwise. The
@@ -115,13 +113,17 @@ function report(results: ReadonlyArray<LineResult>): number {
 	return failures.length === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
+// The targets the command line names, or `undefined` for a line nobody can read — an unknown flag and
+// a `--repo` given no value are refused with the same usage a non-numeric token is.
+function read_targets(args: ReadonlyArray<string>): ReadonlyArray<CiteTarget> | undefined {
+	const parsed = cli_flags.arguments_of(args, OPTIONS)
+	if (parsed === undefined) return undefined
+
+	return parse_targets(parsed.positionals, parsed.values.repo)
+}
+
 async function run(args: ReadonlyArray<string>): Promise<number> {
-	const parsed = parseArgs({
-		args: [...args],
-		options: { repo: { type: 'string' } },
-		allowPositionals: true,
-	})
-	const targets = parse_targets(parsed.positionals, parsed.values.repo)
+	const targets = read_targets(args)
 
 	if (targets === undefined) {
 		console.error(USAGE)

package/scripts/issue/issue-cite.ts

@@ -1,5 +1,5 @@
 // The paste-ready citation line `josh issue:cite` prints, kept apart from the reading and the
-// printing so the shape of the line is decided by one pure function (joshuafolkken/kit#2220).
+// printing so the shape of the line is decided by one pure function.
 //
 // **It exists because the correct citation form has a cost the bare `#N` does not.** `CLAUDE.md` and
 // `prompts/collaboration-workflow/issue-citation.md` require session-facing output to cite an Issue
@@ -12,7 +12,7 @@
 // translate deterministically, and an LLM call per Issue would defeat the point of a cheap citation
 // helper and make the output untestable; the title already says what the Issue does, which is all the
 // rule asks of the summary — knowing what it does is enough. The reader adapts it to the session
-// language when it matters, without the round trip that used to be needed to learn the title at all.
+// language when it matters, without a round trip to learn the title at all.
 
 const GITHUB_URL_PREFIX = 'https://github.com/'
 const ISSUE_PATH = '/issues/'
@@ -32,27 +32,36 @@ interface CiteTarget {
 	repo: string | undefined
 }
 
+// The plain `#N`, or `owner/repo#N` when a repository is named — the one place the bare form is
+// assembled. It is for text GitHub renders or a program reads: an Issue or PR
+// body, a comment, a commit message, a pattern, a key. GitHub links that text itself, so it needs no
+// link of its own; what a session reads goes through `session_cite.issue` instead, and the scan in
+// `session-cite-scan.test.ts` refuses a bare `#${…}` assembled anywhere else.
+function plain(number: number | string, repo = ''): string {
+	return `${repo}#${String(number)}`
+}
+
 function issue_url(slug: string, number: string): string {
 	return `${GITHUB_URL_PREFIX}${slug}${ISSUE_PATH}${number}`
 }
 
 function citation_line(slug: string, number: string, summary: string): string {
-	return `[#${number}](${issue_url(slug, number)})${SUMMARY_SEPARATOR}${summary}`
+	return `[${plain(number)}](${issue_url(slug, number)})${SUMMARY_SEPARATOR}${summary}`
 }
 
-// How a listing names one issue, given what it already holds (joshuafolkken/kit#2943). A progress
+// How a listing names one issue, given what it already holds. A progress
 // command's output is copied into a report verbatim, so the line it prints is the citation the report
 // carries: the full form when the title is in hand, the bare number-link when only the repository is,
 // and the plain `#N` only when the repository could not be read at all.
 type IssueCiter = (number: string) => string
 
 // One issue, named from what the caller holds — the single decision every listing's citation goes
-// through (joshuafolkken/kit#3099), so a renderer holding one title never re-derives the fallback.
+// through, so a renderer holding one title never re-derives the fallback.
 function reference(slug: string | undefined, number: string, title: string | undefined): string {
-	if (slug === undefined) return `#${number}`
+	if (slug === undefined) return plain(number)
 
 	return title === undefined
-		? `[#${number}](${issue_url(slug, number)})`
+		? `[${plain(number)}](${issue_url(slug, number)})`
 		: citation_line(slug, number, title)
 }
 
@@ -89,7 +98,7 @@ function parse_target(token: string, default_repo: string | undefined): CiteTarg
 // How a target is named in a failure line: `owner/repo#N` when it names another repository, `#N`
 // otherwise — the form the reader typed, so the line points back at the argument it is about.
 function label(target: CiteTarget): string {
-	return target.repo === undefined ? `#${target.number}` : `${target.repo}#${target.number}`
+	return plain(target.number, target.repo)
 }
 
 // A number that resolves to nothing, told apart from a read that failed: this one will not change on a
@@ -116,6 +125,7 @@ const issue_cite = {
 	missing_line,
 	no_repo_line,
 	parse_target,
+	plain,
 	reference,
 	unreadable_line,
 }

package/scripts/issue/issue-closing-pr.ts

@@ -2,12 +2,12 @@ import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
-import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
-// **The merged pull request that closes an issue GitHub left open** (joshuafolkken/kit#2769). A
+// **The merged pull request that closes an issue GitHub left open**. A
 // `backlogrun` child whose pull request merged while GitHub did not apply its `closes #N`
-// (joshuafolkken/kit#2770) came back OPEN, and `run:merge` counted it a failure and parked it — the
+// came back OPEN, and `run:merge` counted it a failure and parked it — the
 // work had landed, only the issue's close had not.
 //
 // **A merged reference is not enough; the body must close this issue.** A merged pull request that
@@ -48,7 +48,7 @@ function is_reference(row: TimelineRow): row is MergedReference {
 function parse_references(raw: string): Array<MergedReference> {
 	const rows = raw
 		.split(LINE_SEPARATOR)
-		.map((line) => parse_json_object_safe(line, row_schema))
+		.map((line) => parse_json_object_or_undefined(line, row_schema))
 		.filter((row) => row !== undefined)
 	const last_reopen = rows.findLastIndex((row) => !is_reference(row))
 

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

@@ -1,12 +1,13 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_body } from '#scripts/josh/cli-body'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 
 // `josh issue:comment <N> --body <text> | --body-file <path>` — post one comment to an issue (a PR
-// comment is an issue comment over REST) and print the comment URL (joshuafolkken/kit#2304).
+// comment is an issue comment over REST) and print the comment URL.
 //
 // **The write side had no command, so every park, decision record and plan comment fell to a raw
 // `gh api … body=@<path>`.** The read side already had `issue:read` / `issue:state` / `issue:cite` /
@@ -21,7 +22,6 @@ const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const BODY_FLAG = '--body'
 const BODY_FILE_FLAG = '--body-file'
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = `Usage: josh issue:comment <issue-number> ${BODY_FLAG} <text> | ${BODY_FILE_FLAG} <path>`
 
 interface CommentRequest {
@@ -29,7 +29,7 @@ interface CommentRequest {
 	body: string
 }
 
-// The read is strict (joshuafolkken/kit#3261): an unknown flag refuses the call rather than being
+// The read is strict: an unknown flag refuses the call rather than being
 // ignored. `cli_body.resolve` owns the both-flags-at-once refusal and the file read.
 const OPTIONS = { body: { type: 'string' }, 'body-file': { type: 'string' } } as const
 
@@ -39,7 +39,9 @@ function single_issue_number(positionals: ReadonlyArray<string>): string | undef
 	const [issue_number, ...rest] = positionals
 	const is_single = rest.length === 0 && issue_number !== undefined
 
-	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? issue_number : undefined
+	return is_single && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
+		? issue_number
+		: undefined
 }
 
 // `resolve` may throw when both body flags are given, which `run` reports — the message names the two

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

@@ -11,26 +11,33 @@ import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { error_text } from '#scripts/lib/error-message'
 import type { PollOptions } from '#scripts/lib/poll'
 import { repository_labels } from '#scripts/repo/repository-labels'
+import { run_event_filed } from '#scripts/run/event/run-event-filed'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { issue_auto_ok } from './issue-auto-ok'
+import { issue_cite } from './issue-cite'
 import { issue_file, type FileArguments } from './issue-file'
+import { issue_file_fold } from './issue-file-fold'
 import { issue_lint_cli } from './issue-lint-cli'
+import { issue_release_cli } from './issue-release-cli'
 import { issue_scout_cli } from './issue-scout-cli'
 import { issue_wip } from './issue-wip'
 
 // `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
-// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]` — file an Issue with every
-// filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body lint, the
-// `## Origin` check for another repository, the `auto-ok` decision (joshuafolkken/kit#3213) with the
-// run label it owes (joshuafolkken/kit#3313), the WIP cap count (joshuafolkken/kit#3181), the duplicate
-// scout, the missing workflow labels created (joshuafolkken/kit#3176), the create call carrying every
-// label, and `epic:bundle` after it.
+// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]` — file an Issue
+// with every filing step run in order: the third-party refusal, the body
+// lint, the `## Origin` check for another repository, the `auto-ok` decision
+// with the run label it owes, the fold question against the run's earlier
+// filings, the WIP cap count, the
+// duplicate scout, the missing workflow labels created, the create call
+// carrying every label, the release link on `--release`, and `epic:bundle`.
 // A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
-	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]'
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
 const THIRD_PARTY_MESSAGE =
@@ -39,7 +46,7 @@ const THIRD_PARTY_MESSAGE =
 // scout and `epic:bundle` make at the target repository rather than at this checkout.
 const GH_REPO_VARIABLE = 'GH_REPO'
 // The open listing `epic:bundle` reads trails the create call, so the issue just filed is looked for
-// again for up to ten seconds before the placement is given up (joshuafolkken/kit#3332).
+// again for up to ten seconds before the placement is given up.
 const FRESH_ISSUE_POLL: PollOptions = { attempts: 6, interval_ms: 2000 }
 
 interface Filing {
@@ -135,13 +142,18 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 	return open.length === 0
 }
 
-// Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label
-// (joshuafolkken/kit#3313). Decided before the WIP count and the scout, so a refusal costs no listing.
+// Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label.
+// Decided before the WIP count and the scout, so a refusal costs no listing.
 async function labels_of(filing: Filing): Promise<ReadonlyArray<string> | undefined> {
+	const declared = {
+		is_opted_out: filing.args.is_auto_ok_opted_out,
+		is_requested: filing.args.is_requested,
+	}
 	const auto_ok = await issue_auto_ok.resolve(
-		filing.args.is_auto_ok_opted_out,
+		declared,
 		filing.target,
 		filing.current,
+		filing.args.labels,
 	)
 
 	console.info(issue_auto_ok.line_of(auto_ok))
@@ -177,10 +189,30 @@ async function create(filing: Filing, labels: ReadonlyArray<string>): Promise<st
 	}
 }
 
+function issue_number_of(url: string): number {
+	return Number(github_issue_url.parse(url)?.issue_number)
+}
+
+// `--release`: the filed Issue blocks the target's release Issue. Reported,
+// never failed, for the reason `place` gives. The re-run hint names the target through `GH_REPO`:
+// `issue:release` links in the repository `gh` resolves, which is not the target on a `--repo` filing.
+async function link_release(url: string, filing: Filing): Promise<void> {
+	if (!filing.args.is_release) return
+	const issue_number = issue_number_of(url)
+	const is_linked =
+		Number.isSafeInteger(issue_number) &&
+		(await issue_release_cli.link(issue_number, filing.target))
+
+	if (is_linked) return
+	console.error(
+		`⚠ the release link did not complete for ${url} — run \`${GH_REPO_VARIABLE}=${filing.target} pnpm josh issue:release <N>\`.`,
+	)
+}
+
 // The Issue exists once `create` returns, so a failed placement is reported rather than failed: a
 // non-zero exit would read as "not filed" and invite the second filing the scout exists to stop.
 async function place(url: string, target: string): Promise<void> {
-	const issue_number = Number(github_issue_url.parse(url)?.issue_number)
+	const issue_number = issue_number_of(url)
 	const exit_code = Number.isSafeInteger(issue_number)
 		? await epic_bundle_cli.report_for(issue_number, target, FRESH_ISSUE_POLL)
 		: FAILURE_EXIT_CODE
@@ -190,6 +222,22 @@ async function place(url: string, target: string): Promise<void> {
 	}
 }
 
+// Every filing lands on the run's event stream: this is the one filing path, so
+// one append here reaches `run:board` from every route. A filing outside a run lands too and is left
+// out by the board's own scope to the invocation; the append is best-effort, as every emit is.
+async function record(url: string, filing: Filing, labels: ReadonlyArray<string>): Promise<void> {
+	const number = String(issue_number_of(url))
+	const reference = issue_cite.plain(
+		number,
+		issue_file_fold.reference_prefix(filing.target, filing.current),
+	)
+	const found_during = await issue_file_fold.finder()
+	const kind = run_event_filed.kind_of(labels)
+	const text = run_event_filed.text_of({ reference, kind, title: filing.args.title, found_during })
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.FILED, text)
+}
+
 function is_admitted(filing: Filing): boolean {
 	const refusals = refusals_of(filing)
 
@@ -204,17 +252,28 @@ async function send(filing: Filing, labels: ReadonlyArray<string>): Promise<numb
 
 	if (url === undefined) return FAILURE_EXIT_CODE
 	console.info(url)
+	await record(url, filing, labels)
+	await link_release(url, filing)
 	await place(url, filing.target)
 
 	return SUCCESS_EXIT_CODE
 }
 
+// The holds that read the run and the backlog, in the order they cost: the fold reads the local event
+// stream and diff, the WIP count one listing, the scout a search.
+async function is_clear(filing: Filing): Promise<boolean> {
+	const prefix = issue_file_fold.reference_prefix(filing.target, filing.current)
+
+	if (!(await issue_file_fold.is_fold_clear(prefix, filing.args))) return false
+
+	return (await is_wip_clear(filing)) && (await is_scout_clear(filing))
+}
+
 async function file(filing: Filing): Promise<number> {
 	if (!is_admitted(filing)) return FAILURE_EXIT_CODE
 	const labels = await labels_of(filing)
 
-	if (labels === undefined) return FAILURE_EXIT_CODE
-	if (!(await is_wip_clear(filing)) || !(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+	if (labels === undefined || !(await is_clear(filing))) return FAILURE_EXIT_CODE
 
 	return await send(filing, labels)
 }
@@ -255,8 +314,9 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_file_cli = { FRESH_ISSUE_POLL, THIRD_PARTY_MESSAGE, run }
+const issue_file_cli = { FRESH_ISSUE_POLL, THIRD_PARTY_MESSAGE, record, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
 export { issue_file_cli }
+export type { Filing }

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

@@ -0,0 +1,155 @@
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { run_event_filed, type Filed } from '#scripts/run/event/run-event-filed'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { issue_file } from './issue-file'
+import { issue_fold, type FoldVerdict } from './issue-fold'
+import { issue_fold_cli } from './issue-fold-cli'
+import { SPLIT_ROUTE_LABEL } from './issue-labels'
+import { issue_state_cli } from './issue-state-cli'
+
+// The fold question asked by `josh issue:file` itself, as the scout and
+// `epic:bundle` already are. A separate `pnpm josh issue:fold` would cost two or three round trips per
+// filing, for a question whose every input the command can read: the run's earlier filings are the `filed` events
+// it appends to the event stream itself, and the size is `issue:fold`'s own reading of the diff.
+//
+// **The verdict is `issue_fold.fold_verdict`, called rather than restated**, with separability
+// presumed as `issue:fold` presumes it. Only `fold` holds the filing; `undetermined` — no diff that
+// measures the findings' size — files, the size then being the whole request's estimate the filer
+// already made.
+
+const REFERENCE_NUMBER = /#(?<number>\d+)$/u
+const CLOSED_STATE = 'CLOSED'
+
+// What the fold reads off the filing's arguments.
+interface FoldArguments {
+	route: string | undefined
+	distinct: ReadonlyArray<number>
+}
+
+function number_of(reference: string): number {
+	return Number(REFERENCE_NUMBER.exec(reference)?.groups?.['number'])
+}
+
+// What a filed reference carries before `#<N>`: nothing for this repository's Issue, `<owner>/<repo>`
+// for one filed elsewhere. `issue:file` writes its references with it and the fold compares by it, so
+// a finding is never folded into another repository's Issue. Compared as the Origin check compares,
+// case-insensitively, so `--repo JoshuaFolkken/kit` and no `--repo` name one repository here too.
+function reference_prefix(target: string, current: string): string {
+	return issue_file.is_same_repository(target, current) ? '' : target
+}
+
+function prefix_of(reference: string): string {
+	return reference.slice(0, reference.lastIndexOf('#'))
+}
+
+// The Issue the checkout's branch names; a git read that fails names none.
+async function branch_issue(): Promise<number | undefined> {
+	try {
+		return git_branch.issue_from_branch(await git_command.branch())
+	} catch {
+		return undefined
+	}
+}
+
+// Whose work turned the finding up: the lane child's mark, else the Issue the checkout's branch names,
+// so a person's `fullrun` on `3423-x` is one finder across its filings just as a lane child is. A
+// checkout on no Issue's branch — a `backlogrun` parent on `main` — has none.
+async function finder(): Promise<string | undefined> {
+	const marked = lane_child_marker.marked_issue()
+
+	if (marked !== undefined) return marked
+	const issue = await branch_issue()
+
+	return issue === undefined ? undefined : String(issue)
+}
+
+// The events the fold reads. A finder's filings are its own wherever they fall on the stream, so they
+// are read whole — a person's run has no carry record to scope by. With no finder, the invocation the
+// carry record scopes is the run.
+async function events_of(found_during: string | undefined): Promise<ReadonlyArray<RunEvent>> {
+	if (found_during === undefined) return await run_event_stream_emit.current_events()
+
+	return await run_event_stream_emit.all_events()
+}
+
+// This run's earlier filings by the same finder — so a parallel lane's filing is never what this one
+// folds into — in the repository this filing targets. One the caller named in `--distinct` has been
+// declared a separate deliverable and is left out, the same declaration the scout's candidates take.
+function prior_filings(
+	events: ReadonlyArray<RunEvent>,
+	found_during: string | undefined,
+	prefix: string,
+	distinct: ReadonlyArray<number>,
+): ReadonlyArray<Filed> {
+	return events
+		.filter((event) => event.kind === run_event_stream.EVENT_KIND.FILED)
+		.flatMap((event) => run_event_filed.parse(event.text) ?? [])
+		.filter((filed) => filed.found_during === found_during && prefix_of(filed.reference) === prefix)
+		.filter((filed) => !distinct.includes(number_of(filed.reference)))
+}
+
+// Whether an earlier filing is still in the backlog. A finder's filings are read across invocations,
+// so one may have closed since — folding into it would take the finding out of the backlog. A state
+// that could not be read keeps the filing: a failed read is never taken as closed.
+async function is_open(filed: Filed, prefix: string): Promise<boolean> {
+	const repo = prefix === '' ? undefined : prefix
+	const read = await issue_state_cli.read_issue(String(number_of(filed.reference)), repo)
+
+	return read.kind !== 'state' || read.state.state !== CLOSED_STATE
+}
+
+// Through the shared pool at `issue:state`'s bound rather than a raw `Promise.all`, so a finder's
+// filings never draw the secondary rate limiting that reads back as `unreadable`.
+async function open_filings(
+	priors: ReadonlyArray<Filed>,
+	prefix: string,
+): Promise<ReadonlyArray<Filed>> {
+	const verdicts = await bounded_pool.bounded_map(
+		priors,
+		issue_state_cli.READ_CONCURRENCY,
+		async (filed) => await is_open(filed, prefix),
+	)
+
+	return priors.filter((_filed, index) => verdicts[index])
+}
+
+function references_of(priors: ReadonlyArray<Filed>): string {
+	return priors.map((filed) => filed.reference).join(', ')
+}
+
+function line_of(verdict: FoldVerdict, priors: ReadonlyArray<Filed>): string {
+	return `fold: ${issue_fold_cli.REASONS[verdict]} · filed earlier by this finder: ${references_of(priors)}`
+}
+
+function held_message(priors: ReadonlyArray<Filed>): string {
+	const listed = priors.map((filed) => String(number_of(filed.reference))).join(',')
+
+	return `✖ fold: add this finding to ${references_of(priors)} (its body or a comment) rather than filing it; a finding that is really a separate deliverable reissues with \`--distinct ${listed}\` (\`split-assessment.md\` → "The question").`
+}
+
+// Whether the filing may go on: `true` with no open earlier filing to fold with, and on every verdict
+// but `fold`. The verdict is printed whenever there was something to fold with. A split child is
+// exempt, as it is from the WIP cap: the split assessment already decided it is a separate deliverable.
+async function is_fold_clear(prefix: string, args: FoldArguments): Promise<boolean> {
+	if (args.route === SPLIT_ROUTE_LABEL) return true
+	const found_during = await finder()
+	const filings = prior_filings(await events_of(found_during), found_during, prefix, args.distinct)
+	const priors = await open_filings(filings, prefix)
+
+	if (priors.length === 0) return true
+	const size = await issue_fold_cli.size_verdict()
+	const verdict = issue_fold.fold_verdict(priors.length + 1, true, size)
+
+	console.info(line_of(verdict, priors))
+	if (verdict === issue_fold.FOLD) console.error(held_message(priors))
+
+	return verdict !== issue_fold.FOLD
+}
+
+const issue_file_fold = { finder, is_fold_clear, prior_filings, reference_prefix }
+
+export { issue_file_fold }

package/scripts/issue/issue-file.ts

@@ -15,11 +15,9 @@ import {
 } from './issue-labels'
 import { markdown_section } from './markdown-section'
 
-// The decisions behind `josh issue:file` (joshuafolkken/kit#2808), kept apart from the command that
-// reads the network so each one is a pure answer a test can pin. Every filing used to be a hand-built
-// `gh api …/issues` call beside five steps spread over as many documents, and joshuafolkken/kit#2805
-// ran two of them and skipped the lint and the labels. Here the steps are the command's arguments:
-// a label the filing owes is a required option rather than a line to remember.
+// The decisions behind `josh issue:file`, kept apart from the command that
+// reads the network so each one is a pure answer a test can pin. The filing steps are the command's
+// arguments: a label the filing owes is a required option rather than a line to remember.
 
 const DEPTH_PREFIX = 'depth:'
 const ROUTE_PREFIX = 'route:'
@@ -43,6 +41,12 @@ interface FileArguments {
 	is_over_cap: boolean
 	// `--no-auto-ok`: the Issue needs a person's judgement, so `auto-ok` is not applied (`issue-auto-ok.ts`).
 	is_auto_ok_opted_out: boolean
+	// `--requested`: a person asked for this filing, so `auto-ok` is applied only when a `--label` names
+	// it (`issue-auto-ok.ts`).
+	is_requested: boolean
+	// `--release`: the change reaches a consumer only once published, so the Issue is linked to the
+	// repository's release Issue as a blocker (`issue-release-cli.ts`).
+	is_release: boolean
 }
 
 const OPTIONS = {
@@ -54,6 +58,8 @@ const OPTIONS = {
 	distinct: { type: 'string', multiple: true },
 	'over-cap': { type: 'boolean' },
 	'no-auto-ok': { type: 'boolean' },
+	requested: { type: 'boolean' },
+	release: { type: 'boolean' },
 } as const
 
 // The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
@@ -123,6 +129,8 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		repo: values.repo,
 		is_over_cap: values['over-cap'] === true,
 		is_auto_ok_opted_out: values['no-auto-ok'] === true,
+		is_requested: values.requested === true,
+		is_release: values.release === true,
 	}
 }
 
@@ -156,7 +164,7 @@ function labels_of(args: FileArguments, body: string, is_auto_ok = false): Reado
 }
 
 // Why an `auto-ok` filing with neither `run:lane` nor `run:solo` is refused, or `undefined` when it is
-// not (joshuafolkken/kit#3313). The offer paths withhold every candidate while one opted-in Issue is
+// not. The offer paths withhold every candidate while one opted-in Issue is
 // untriaged, so a run's own filing without the judgement stopped every lane. No default is applied:
 // `run:solo` is the answer that keeps a verification defect from running beside others, and only a
 // reading of the Issue gives it (`backlogrun-lanes.md`).

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

@@ -7,7 +7,7 @@ import { split_assess, type SplitVerdict } from '#scripts/split/split-assess'
 import { issue_fold, type FoldVerdict } from './issue-fold'
 
 // `josh issue:fold "<title>" "<title>" …` — before a run files a second finding, answer whether the
-// findings this session holds fold into one Issue (joshuafolkken/kit#2213).
+// findings this session holds fold into one Issue.
 //
 // It is the filing-time counterpart to `split:assess`: the size half is that command's own verdict,
 // called rather than recomputed (the counting and the guide live in `split-assess.ts`), and
@@ -25,6 +25,8 @@ const REASONS: Record<FoldVerdict, string> = {
 	separate:
 		'separate — file these apart; they are separable and their combined size clears the split guide',
 	'no-fold-needed': 'no fold needed — a single candidate is filed on its own',
+	undetermined:
+		'undetermined — the diff measures no size, so the whole request\'s estimate decides (`split-assessment.md` → "The question")',
 }
 
 interface FoldArguments {
@@ -50,20 +52,23 @@ function read_arguments(argv: ReadonlyArray<string>): FoldArguments | undefined
 	}
 }
 
-// The size half, single-sourced from `split:assess` (joshuafolkken/kit#2183): the same counting, the
-// same guide. A diff that cannot be read — no base, not a checkout — measures as empty, which
-// `split_assess` reads as `single`, so an unanswerable size folds rather than tipping to `separate`.
-async function size_verdict(): Promise<SplitVerdict> {
+// The size half, single-sourced from `split:assess`: the same counting, the
+// same guide. `undefined` when the diff says nothing about size — no changed non-test file, or a diff
+// that cannot be read (no base, not a checkout) — which `fold_verdict` answers as `undetermined`
+// rather than folding on no evidence. `issue:file` asks it too.
+async function size_verdict(): Promise<SplitVerdict | undefined> {
 	try {
-		return split_assess.assess(await git_command.diff_main_numstat()).verdict
+		const measurement = split_assess.assess(await git_command.diff_main_numstat())
+
+		return measurement.files === 0 ? undefined : measurement.verdict
 	} catch {
-		return split_assess.SINGLE_VERDICT
+		return undefined
 	}
 }
 
 // The size question is only asked once there is something to fold; a lone candidate is answered
 // without measuring anything.
-async function size_for(args: FoldArguments): Promise<SplitVerdict> {
+async function size_for(args: FoldArguments): Promise<SplitVerdict | undefined> {
 	if (args.titles.length < issue_fold.MIN_CANDIDATES) return split_assess.SINGLE_VERDICT
 
 	return await size_verdict()
@@ -90,7 +95,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_fold_cli = { read_arguments, size_verdict, run }
+const issue_fold_cli = { REASONS, read_arguments, size_verdict, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))