@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import type { IssueRead } from '#scripts/git/git-gh-issue-read'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+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).
+//
+// 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.
+//
+// **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
+// for while still exiting zero. **A number that resolves to nothing, or a read that failed, is named
+// as a failure line** rather than silently missing — the reader is told which numbers have no citation
+// instead of subtracting the printed lines from what was asked.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+// The same bound `issue:read` puts on its batch read: every read is a `gh` process, and an unbounded
+// fan-out is answered with secondary rate limiting rather than with titles.
+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 title_schema = z.looseObject({ title: z.string() })
+
+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()
+
+		return title === '' ? undefined : title
+	} catch {
+		return undefined
+	}
+}
+
+// A read's outcome as one line: the citation on success, the matching failure line otherwise. The
+// classification is the reader's own — `missing` will not change on a retry, `unreadable` may.
+function to_line(target: CiteTarget, slug: string, read: IssueRead): LineResult {
+	if (read.kind === 'missing') return { kind: 'fail', line: issue_cite.missing_line(target) }
+	if (read.kind !== 'read') return { kind: 'fail', line: issue_cite.unreadable_line(target) }
+
+	const title = parse_title(read.json)
+	if (title === undefined) return { kind: 'fail', line: issue_cite.unreadable_line(target) }
+
+	return { kind: 'ok', line: issue_cite.citation_line(slug, target.number, title) }
+}
+
+// The repository the link names: the target's own when it is qualified, the local one otherwise. A
+// bare number with no local repository has no link to build, so it fails rather than citing a
+// repository it could not read.
+async function cite_target(
+	target: CiteTarget,
+	local_slug: string | undefined,
+): Promise<LineResult> {
+	const slug = target.repo ?? local_slug
+	if (slug === undefined) return { kind: 'fail', line: issue_cite.no_repo_line(target) }
+
+	const read = await git_gh_command.issue_view_json_classified(
+		target.number,
+		TITLE_FIELD,
+		target.repo,
+	)
+
+	return to_line(target, slug, read)
+}
+
+// Every positional as a target, or `undefined` if any one of them is not a number — the invocation is
+// refused whole so a mistyped argument never silently loses its citation.
+function parse_targets(
+	positionals: ReadonlyArray<string>,
+	default_repo: string | undefined,
+): ReadonlyArray<CiteTarget> | undefined {
+	const targets: Array<CiteTarget> = []
+
+	for (const token of positionals) {
+		const target = issue_cite.parse_target(token, default_repo)
+		if (target === undefined) return undefined
+		targets.push(target)
+	}
+
+	return targets.length === 0 ? undefined : targets
+}
+
+// The local `owner/repo`, read once and only when a bare target needs it: a run that names every
+// target with a repository never makes the request.
+async function local_slug_for(targets: ReadonlyArray<CiteTarget>): Promise<string | undefined> {
+	const has_bare_target = targets.some((target) => target.repo === undefined)
+
+	return has_bare_target ? await git_gh_command.repo_get_name_with_owner() : undefined
+}
+
+// Citations to stdout so the block stays paste-ready; failures to stderr so each unanswered number is
+// named without landing in what gets pasted. A failure sets a non-zero exit.
+function report(results: ReadonlyArray<LineResult>): number {
+	const lines = results.filter((result) => result.kind === 'ok').map((result) => result.line)
+	const failures = results.filter((result) => result.kind === 'fail').map((result) => result.line)
+
+	if (lines.length > 0) console.info(lines.join(LINE_SEPARATOR))
+	for (const failure of failures) console.error(failure)
+
+	return failures.length === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+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)
+
+	if (targets === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const local_slug = await local_slug_for(targets)
+	const results = await bounded_pool.bounded_map(
+		targets,
+		READ_CONCURRENCY,
+		async (target) => await cite_target(target, local_slug),
+	)
+
+	return report(results)
+}
+
+async function main(args: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(args)
+}
+
+const issue_cite_cli = {
+	USAGE,
+	main,
+	parse_targets,
+	parse_title,
+	report,
+	run,
+	to_line,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_cite_cli }

package/scripts/issue/issue-cite.ts

@@ -0,0 +1,102 @@
+// 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).
+//
+// **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
+// as `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <summary>`, and assembling that by hand
+// means reading each Issue's title first — a per-Issue round trip that lands exactly where several
+// Issues are named at once (a backlog listing, a lane status report), which is where the bare `#N`
+// falls out. This command makes the cheap path and the correct path the same one.
+//
+// **The summary is the Issue's own title, fetched, not a translation of it.** A script cannot
+// 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.
+
+const GITHUB_URL_PREFIX = 'https://github.com/'
+const ISSUE_PATH = '/issues/'
+const SUMMARY_SEPARATOR = ' — '
+
+// `owner/repo#N`, so a citation can name another repository's Issue; the two segment classes exclude a
+// slash and a `#` so the split between the repository and the number is unambiguous.
+const REPO_QUALIFIED = /^([^\s/#]+\/[^\s/#]+)#(\d+)$/u
+// A bare number, with the `#` optional: the source is usually a `#N` copied out of prose, and refusing
+// the `#` would make the command reject exactly what it exists to correct.
+const BARE_NUMBER = /^#?(\d+)$/u
+
+// `repo` is `owner/repo`, or `undefined` for the repository the command runs in — the same contract
+// the reads underneath take, so a bare number and a qualified one flow through one path.
+interface CiteTarget {
+	number: string
+	repo: string | undefined
+}
+
+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}`
+}
+
+function qualified_target(token: string): CiteTarget | undefined {
+	const match = REPO_QUALIFIED.exec(token)
+	if (match === null) return undefined
+
+	const [, repo = '', number = ''] = match
+
+	return { number, repo }
+}
+
+function bare_target(token: string, default_repo: string | undefined): CiteTarget | undefined {
+	const match = BARE_NUMBER.exec(token)
+	if (match === null) return undefined
+
+	const [, number = ''] = match
+
+	return { number, repo: default_repo }
+}
+
+// `undefined` for a token that is neither a bare number nor an `owner/repo#N` — the caller refuses the
+// whole invocation rather than dropping it, so a mistyped argument never silently loses its citation.
+function parse_target(token: string, default_repo: string | undefined): CiteTarget | undefined {
+	return qualified_target(token) ?? bare_target(token, default_repo)
+}
+
+// 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}`
+}
+
+// A number that resolves to nothing, told apart from a read that failed: this one will not change on a
+// retry, so it names the number and the repository rather than suggesting a wait.
+function missing_line(target: CiteTarget): string {
+	return `✖ ${label(target)}: issue does not resolve — check the number and the repository`
+}
+
+// A read that failed over something the number is not responsible for — a rate limit, expired auth, a
+// dropped connection — so the same call a moment later may succeed.
+function unreadable_line(target: CiteTarget): string {
+	return `✖ ${label(target)}: could not be read — a rate limit, expired auth, or a dropped connection`
+}
+
+// The repository itself could not be read, so a bare number has no `owner/repo` to build a link from.
+function no_repo_line(target: CiteTarget): string {
+	return `✖ ${label(target)}: could not read this repository — check gh auth and the origin remote`
+}
+
+const issue_cite = {
+	SUMMARY_SEPARATOR,
+	citation_line,
+	issue_url,
+	label,
+	missing_line,
+	no_repo_line,
+	parse_target,
+	unreadable_line,
+}
+
+export type { CiteTarget }
+export { issue_cite }

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { cli_body } from '#scripts/josh/cli-body'
+
+// `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).
+//
+// **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` /
+// `issue:scout`, but a comment was posted by hand — and `gh`'s two path spellings differ by one
+// character: `-F` / `--field` reads the file, `-f` / `--raw-field` sends the literal `@<path>`, and
+// `gh` exits 0 with a URL either way. One command removes the choice: the body travels by path through
+// `cli-body.ts` (shared with `notify` / `followup`), so no shell evaluates it and the wrong-flag
+// misfire has nowhere left to happen.
+
+const SUCCESS_EXIT_CODE = 0
+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 {
+	issue_number: string
+	body: string
+}
+
+// The value after a flag word, or `undefined` when the flag is absent. `cli_body.resolve` owns the
+// both-flags-at-once refusal and the file read, so this stays the one narrow job of finding the token.
+function flag_value(argv: ReadonlyArray<string>, flag: string): string | undefined {
+	const index = argv.indexOf(flag)
+
+	return index === -1 ? undefined : argv[index + 1]
+}
+
+// The number is the first argument, and it must be a real issue number: a missing or malformed one
+// refuses the whole call rather than posting to some other issue. `resolve` may throw when both body
+// flags are given, which `run` reports — the message names the two flags a caller must pick between.
+function parse_request(argv: ReadonlyArray<string>): CommentRequest | undefined {
+	const [issue_number] = argv
+
+	if (issue_number === undefined || !ISSUE_NUMBER_PATTERN.test(issue_number)) return undefined
+
+	const body = cli_body.resolve({
+		inline: flag_value(argv, BODY_FLAG),
+		file_path: flag_value(argv, BODY_FILE_FLAG),
+		inline_flag: BODY_FLAG,
+		file_flag: BODY_FILE_FLAG,
+	})
+
+	if (body === undefined || body.length === 0) return undefined
+
+	return { issue_number, body }
+}
+
+// A both-flags refusal and a file-read failure both surface as an `Error` from `resolve`, and its
+// message already names the flags or the resolved path — so it is printed as-is and `USAGE` is
+// withheld. `undefined` is the other refusal: a bad number or an empty body, which `USAGE` explains.
+function resolve_request(argv: ReadonlyArray<string>): CommentRequest | undefined {
+	try {
+		const request = parse_request(argv)
+
+		if (request === undefined) console.error(USAGE)
+
+		return request
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return undefined
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = resolve_request(argv)
+
+	if (request === undefined) return FAILURE_EXIT_CODE
+
+	const url = await git_gh_command.issue_comment(request.issue_number, request.body)
+
+	console.info(url)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_comment_cli = { USAGE, main, parse_request, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_comment_cli }

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

@@ -0,0 +1,104 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { git_command } from '#scripts/git/git-command'
+import { path_decision } from '#scripts/josh/path-decision'
+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).
+//
+// 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
+// separability stays the judgement it is at the entry — presumed here, and overridden with
+// `--not-separable` when the findings are really one deliverable. The verdict logic is in
+// `issue-fold.ts`; everything here is the invocation.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh issue:fold "<title>" "<title>" … [--not-separable] [--json]'
+const JSON_KEY = 'fold'
+const FAILURE_EXIT_CODE = 1
+
+const REASONS: Record<FoldVerdict, string> = {
+	fold: 'fold — file one Issue covering these findings; the split guide is not cleared, so they are one Issue however separable',
+	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',
+}
+
+interface FoldArguments {
+	titles: Array<string>
+	is_separable: boolean
+	is_json: boolean
+}
+
+function parse_arguments(argv: ReadonlyArray<string>): FoldArguments {
+	const { values, positionals } = parseArgs({
+		args: [...argv],
+		options: { json: { type: 'boolean' }, 'not-separable': { type: 'boolean' } },
+		allowPositionals: true,
+	})
+
+	return {
+		titles: positionals,
+		is_separable: values['not-separable'] !== true,
+		is_json: values.json === true,
+	}
+}
+
+// An unknown flag makes `parseArgs` throw. Caught so the answer is the usage line rather than a stack
+// trace, on a command whose output a workflow reads.
+function read_arguments(argv: ReadonlyArray<string>): FoldArguments | undefined {
+	try {
+		return parse_arguments(argv)
+	} catch {
+		return 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> {
+	try {
+		return split_assess.assess(await git_command.diff_main_numstat()).verdict
+	} catch {
+		return split_assess.SINGLE_VERDICT
+	}
+}
+
+// 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> {
+	if (args.titles.length < issue_fold.MIN_CANDIDATES) return split_assess.SINGLE_VERDICT
+
+	return await size_verdict()
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const args = read_arguments(argv)
+
+	if (args === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const size = await size_for(args)
+	const verdict = issue_fold.fold_verdict(args.titles.length, args.is_separable, size)
+
+	path_decision.print_decision(JSON_KEY, verdict, REASONS[verdict], args.is_json)
+
+	return 0
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_fold_cli = { JSON_KEY, USAGE, REASONS, read_arguments, size_verdict, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_fold_cli }

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { z } from 'zod'
+import { issue_fold_existing } from './issue-fold-existing'
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const SUCCESS_EXIT_CODE = 0
+const USAGE = 'Usage: josh issue:fold-existing <assessment.json> [--json]'
+
+const assessment_schema = z.object({
+	content: z.enum(['duplicate', 'compatible', 'separate', 'unknown']),
+	is_open: z.boolean().optional(),
+	is_unstarted: z.boolean().optional(),
+	has_pull_request: z.boolean().optional(),
+	has_complete_read: z.boolean(),
+	has_dependency_conflict: z.boolean().optional(),
+	is_separable: z.boolean().optional(),
+	size_verdict: z.enum(['split', 'single']).optional(),
+	existing_body: z.string(),
+	draft_body: z.string().trim().min(1),
+	verification: z.string().trim().min(1),
+})
+
+function print_assessment(input: z.infer<typeof assessment_schema>, should_json: boolean): void {
+	const verdict = issue_fold_existing.decide(input)
+	const body =
+		verdict === 'fold'
+			? issue_fold_existing.append_requirements(
+					input.existing_body,
+					input.draft_body,
+					input.verification,
+				)
+			: undefined
+
+	if (should_json) {
+		console.info(JSON.stringify({ verdict, body }))
+
+		return
+	}
+
+	console.info(`Fold: ${verdict}`)
+	if (body !== undefined) console.info(body)
+}
+
+async function assess(path: string, should_json: boolean): Promise<number> {
+	try {
+		const input = assessment_schema.parse(JSON.parse(await readFile(path, 'utf8')))
+
+		print_assessment(input, should_json)
+
+		return SUCCESS_EXIT_CODE
+	} catch {
+		console.error('Could not read a complete assessment; no fold recommendation was made.')
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [path, option, extra] = argv
+
+	if (path !== undefined && extra === undefined && (option === undefined || option === '--json')) {
+		return await assess(path, option === '--json')
+	}
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_fold_existing_cli = { run, main, USAGE }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_fold_existing_cli }

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

@@ -0,0 +1,73 @@
+import type { SplitVerdict } from '#scripts/split/split-assess'
+import { issue_fold } from './issue-fold'
+
+type ExistingVerdict = 'duplicate' | 'fold' | 'separate' | 'inspect'
+type ContentVerdict = 'duplicate' | 'compatible' | 'separate' | 'unknown'
+const FOLD_CANDIDATE_COUNT = 2
+
+interface ExistingAssessment {
+	content: ContentVerdict
+	is_open?: boolean | undefined
+	is_unstarted?: boolean | undefined
+	has_pull_request?: boolean | undefined
+	has_complete_read: boolean
+	has_dependency_conflict?: boolean | undefined
+	is_separable?: boolean | undefined
+	size_verdict?: SplitVerdict | undefined
+}
+
+function has_unknown_facts(facts: ExistingAssessment): boolean {
+	const required = [
+		facts.is_open,
+		facts.is_unstarted,
+		facts.has_pull_request,
+		facts.has_dependency_conflict,
+		facts.is_separable,
+		facts.size_verdict,
+	]
+
+	return facts.content === 'unknown' || !facts.has_complete_read || required.includes(undefined)
+}
+
+function has_active_conflict(facts: ExistingAssessment): boolean {
+	return (
+		facts.is_open === false ||
+		facts.is_unstarted === false ||
+		facts.has_pull_request === true ||
+		facts.has_dependency_conflict === true
+	)
+}
+
+function fold_or_separate(facts: ExistingAssessment): ExistingVerdict {
+	const verdict = issue_fold.fold_verdict(
+		FOLD_CANDIDATE_COUNT,
+		facts.is_separable ?? false,
+		facts.size_verdict ?? 'split',
+	)
+
+	return verdict === issue_fold.FOLD ? 'fold' : 'separate'
+}
+
+function decide(facts: ExistingAssessment): ExistingVerdict {
+	if (has_unknown_facts(facts)) return 'inspect'
+	if (facts.content === 'separate') return 'separate'
+	if (facts.content === 'duplicate') return 'duplicate'
+	if (has_active_conflict(facts)) return 'separate'
+
+	return fold_or_separate(facts)
+}
+
+function append_requirements(
+	existing_body: string,
+	draft_body: string,
+	verification: string,
+): string {
+	const addition = `## 追加要件\n\n${draft_body.trim()}\n\n### 検証方法\n\n${verification.trim()}`
+
+	return `${existing_body.trimEnd()}\n\n${addition}\n`
+}
+
+const issue_fold_existing = { decide, append_requirements }
+
+export type { ExistingAssessment, ExistingVerdict }
+export { issue_fold_existing }

package/scripts/issue/issue-fold.ts

@@ -0,0 +1,42 @@
+import { split_assess, type SplitVerdict } from '#scripts/split/split-assess'
+
+// The filing-time counterpart to the split assessment (joshuafolkken/kit#2213).
+//
+// `split-assessment.md` → "The question" decides whether *one request* is really several
+// deliverables; this decides whether *several findings filed from one session* fold into one Issue or
+// stay apart. **Both read the same two questions** — are the pieces separable, and does the whole
+// clearly exceed what one verification gate confirms in one pass — so the criterion is single-sourced,
+// never restated: the size half is `split_assess`'s own verdict, and `separate` needs both halves in
+// the same conjunction `split` does.
+//
+// **The default is `fold`.** Separability alone never separates — it is necessary, not sufficient —
+// and a size that does not clear the split guide folds however separable the findings are. That is
+// why an unmeasurable size is treated by the caller as under the guide: tipping the doubt toward
+// `separate` would reproduce the every-finding-its-own-Issue behavior this exists to end.
+
+type FoldVerdict = 'fold' | 'separate' | 'no-fold-needed'
+
+const FOLD: FoldVerdict = 'fold'
+const SEPARATE: FoldVerdict = 'separate'
+const NO_FOLD_NEEDED: FoldVerdict = 'no-fold-needed'
+
+// One finding is nothing to fold: the question only arises once a session holds two or more.
+const MIN_CANDIDATES = 2
+
+// The same two questions as the split assessment, in the same conjunction: `separate` only when the
+// findings are separable **and** their combined size clears the split guide. Either half alone folds,
+// and fewer than two candidates is not a fold question at all.
+function fold_verdict(
+	candidate_count: number,
+	is_separable: boolean,
+	size_verdict: SplitVerdict,
+): FoldVerdict {
+	if (candidate_count < MIN_CANDIDATES) return NO_FOLD_NEEDED
+
+	return is_separable && size_verdict === split_assess.SPLIT_VERDICT ? SEPARATE : FOLD
+}
+
+const issue_fold = { FOLD, SEPARATE, NO_FOLD_NEEDED, MIN_CANDIDATES, fold_verdict }
+
+export type { FoldVerdict }
+export { issue_fold }