@joshuafolkken/kit 1.872.0

package/scripts/issue/issue-scout.ts

@@ -0,0 +1,244 @@
+// Duplicate candidates for an issue nobody has filed yet.
+//
+// `epic:bundle` answers "does this belong with something" for an issue that already exists, from two
+// strong signals: the two issues citing each other in prose, or a `blocked-by` recorded between them.
+// Neither reaches a draft — it has no number, so nothing can cite it and nothing can be recorded
+// against it — and the question a filing entry actually asks first is a different one: has somebody
+// already filed this? (joshuafolkken/kit#1252)
+//
+// So this is a second signal rather than a change to that threshold. `epic:bundle` deliberately
+// refuses title resemblance as grounds for *bundling*, because "related" expands without limit; the
+// output here is not a bundle but a short list to read before filing, where a false positive costs
+// one issue read and a false negative costs a duplicate nobody notices for days.
+
+// Words that sit in issue titles whatever the issue is about. Left in, they lift every pair's score
+// together — which does not reorder the candidates, but does drag unrelated ones over the threshold.
+const STOP_WORDS: ReadonlySet<string> = new Set([
+	'a',
+	'an',
+	'and',
+	'are',
+	'as',
+	'at',
+	'be',
+	'but',
+	'by',
+	'can',
+	'do',
+	'for',
+	'from',
+	'has',
+	'have',
+	'in',
+	'into',
+	'is',
+	'it',
+	'its',
+	'no',
+	'not',
+	'of',
+	'on',
+	'or',
+	'so',
+	'than',
+	'that',
+	'the',
+	'then',
+	'this',
+	'to',
+	'was',
+	'when',
+	'which',
+	'with',
+	'without',
+])
+
+// Everything that is not a letter or a digit separates tokens, so backticks, hyphens, colons and the
+// `#` of an issue reference all fall away — `josh epic:bundle` reads as `josh`, `epic`, `bundle`.
+const TOKEN_SEPARATOR = /[^a-z\d]+/u
+
+// A single character is a fragment rather than a word: it survives as the tail of a split identifier
+// far more often than it carries meaning.
+const MIN_TOKEN_LENGTH = 2
+
+// Dice: twice the shared tokens over the two sizes together.
+const DICE_NUMERATOR_FACTOR = 2
+
+// Titles are compared by which words they use, not by their spelling. Two issues about one job are
+// written months apart by different sessions and share vocabulary, not word order — which is what
+// rules out whole-string edit distance, and with it the maintained packages built on it.
+//
+// The threshold is what keeps the answer honest when there is nothing to report. It was set against
+// this repository's own backlog: at 0.35 a draft's title has to share roughly a third of its
+// significant words with an existing one, which admits genuine restatements and leaves pairs that
+// merely share a subsystem below the line.
+const SIMILARITY_THRESHOLD = 0.35
+
+// One shared word is a coincidence — most often a subsystem name every second title carries. Two is
+// the smallest number that can describe a subject rather than name a neighborhood.
+const MIN_SHARED_TOKENS = 2
+
+// The list is read by a person or an agent about to file. Past a handful it stops being read at all,
+// and the ranking already puts the strongest first.
+const MAX_CANDIDATES = 5
+
+// An issue as the duplicate search sees it. `title` is optional for the same reason it is on
+// `BacklogIssue`: an issue read one at a time by reference carries none, and one with no title simply
+// scores nothing rather than failing the scan.
+interface ScoutIssue {
+	number: number
+	title?: string
+	// The epic tracking it, printed beside the candidate: where similar work already lives is the
+	// other half of what a filing entry is about to decide.
+	epic?: number
+	// An epic is a container, never a duplicate of a deliverable. Reported as one it reads as "this is
+	// already filed as #<E>", and the caller is sent to run an epic that has no implementation of its
+	// own. `epic_bundle.is_strong_signal` excludes them from the other half for the same reason.
+	is_epic?: boolean
+	// A closed issue is a candidate, and the two are not interchangeable to whoever reads the list
+	// (joshuafolkken/kit#1679): an open one says "somebody is already tracking this", a closed one
+	// says "this may already be done". So the state travels with the row rather than being inferred
+	// from which listing it came out of, which the ranking mixes together.
+	is_closed?: boolean
+}
+
+interface DuplicateCandidate {
+	number: number
+	title: string
+	score: number
+	is_referenced?: boolean
+	epic?: number
+	is_closed?: boolean
+}
+
+// What the scan found: the candidates worth reading, and how many cleared the bar in total. The two
+// differ once more than `MAX_CANDIDATES` match, and a caller that prints only the first number is
+// reporting a truncation as a complete answer.
+interface DuplicateSearch {
+	candidates: Array<DuplicateCandidate>
+	total: number
+}
+
+function is_significant(word: string): boolean {
+	return word.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(word)
+}
+
+function tokenize(text: string): Set<string> {
+	const words = text.toLowerCase().split(TOKEN_SEPARATOR)
+
+	return new Set(words.filter((word) => is_significant(word)))
+}
+
+function shared_tokens(left: ReadonlySet<string>, right: ReadonlySet<string>): number {
+	return [...left].filter((token) => right.has(token)).length
+}
+
+function dice_similarity(left: ReadonlySet<string>, right: ReadonlySet<string>): number {
+	const total = left.size + right.size
+
+	if (total === 0) return 0
+
+	return (DICE_NUMERATOR_FACTOR * shared_tokens(left, right)) / total
+}
+
+// The score, or nothing when it does not clear both bars. Both are required rather than either: the
+// count keeps a two-word title from scoring 1.0 on one shared word, and the ratio keeps a long title
+// from qualifying on two words out of twenty.
+function qualifying_score(
+	query: ReadonlySet<string>,
+	tokens: ReadonlySet<string>,
+): number | undefined {
+	if (shared_tokens(query, tokens) < MIN_SHARED_TOKENS) return undefined
+
+	const score = dice_similarity(query, tokens)
+
+	return score < SIMILARITY_THRESHOLD ? undefined : score
+}
+
+function to_epic_field(epic: number | undefined): { epic?: number } {
+	return epic === undefined ? {} : { epic }
+}
+
+function to_closed_field(is_closed: boolean | undefined): { is_closed?: boolean } {
+	return is_closed === true ? { is_closed: true } : {}
+}
+
+function candidate_score(
+	query: ReadonlySet<string>,
+	issue: ScoutIssue,
+	references: ReadonlySet<number>,
+): number | undefined {
+	const score = qualifying_score(query, tokenize(issue.title ?? ''))
+
+	if (score !== undefined) return score
+
+	return references.has(issue.number) ? 0 : undefined
+}
+
+function to_reference_field(is_referenced: boolean): { is_referenced?: boolean } {
+	return is_referenced ? { is_referenced: true } : {}
+}
+
+function to_candidate(
+	query: ReadonlySet<string>,
+	issue: ScoutIssue,
+	references: ReadonlySet<number>,
+): DuplicateCandidate | undefined {
+	if (issue.is_epic === true) return undefined
+
+	const score = candidate_score(query, issue, references)
+
+	if (score === undefined) return undefined
+
+	return {
+		number: issue.number,
+		title: issue.title ?? '',
+		score,
+		...to_reference_field(references.has(issue.number)),
+		...to_epic_field(issue.epic),
+		...to_closed_field(issue.is_closed),
+	}
+}
+
+function compare_candidates(left: DuplicateCandidate, right: DuplicateCandidate): number {
+	const reference_order = Number(right.is_referenced === true) - Number(left.is_referenced === true)
+
+	return reference_order || right.score - left.score
+}
+
+// The issues whose titles look like this one, strongest first.
+//
+// Every row is scored — no prefix, no early exit. The issue this search exists to catch is the one
+// another session filed minutes ago, and where that one sits in the listing is the single thing
+// nobody controls (joshuafolkken/kit#1252). Since joshuafolkken/kit#1679 the rows may be closed as
+// well as open, and the two rank together: a run about to file has to be shown the strongest match
+// there is, and which listing it came out of says nothing about how well it matches.
+function find_duplicates(
+	title: string,
+	issues: ReadonlyArray<ScoutIssue>,
+	referenced_numbers: ReadonlyArray<number> = [],
+): DuplicateSearch {
+	const query = tokenize(title)
+	const references = new Set(referenced_numbers)
+	const matched = issues
+		.flatMap((issue) => to_candidate(query, issue, references) ?? [])
+		.toSorted(compare_candidates)
+
+	// `total` rather than the shown list's length: a caller printing only what it was handed would
+	// report a truncation as a complete answer, which is the one gap in this feature that nothing else
+	// reports — every other one the command has goes through `warn_about_gaps`.
+	return { candidates: matched.slice(0, MAX_CANDIDATES), total: matched.length }
+}
+
+const issue_scout = {
+	SIMILARITY_THRESHOLD,
+	MIN_SHARED_TOKENS,
+	MAX_CANDIDATES,
+	tokenize,
+	shared_tokens,
+	dice_similarity,
+	find_duplicates,
+}
+
+export type { DuplicateCandidate, DuplicateSearch, ScoutIssue }
+export { issue_scout }

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

@@ -0,0 +1,260 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { issue_state, type IssueState } from './issue-state'
+
+// `josh issue:state <N> [<N> ...]` — print each issue's state and labels, in the spelling the
+// documents compare against (joshuafolkken/kit#1054; several numbers in one call,
+// joshuafolkken/kit#1302).
+//
+// The numbers are read concurrently and reported together because the callers that need more than
+// one need them all: `diag`'s ranking table reads a state per row, and one process start plus one
+// round trip per row cost 1.6 seconds each — about 8 seconds of a five-row table spent on nothing
+// but the states.
+//
+// It replaces the two reads the workflow documents told an agent to type — `gh issue view <N> --json
+// state --jq .state` and `gh issue view <N> --json state,labels --jq …` — with one call that answers
+// both. Those go through GraphQL, which a cloud session is refused, and that read is `epic-child`'s
+// verifier: the whole reason a child of an epic may be delegated at all is that the parent re-reads
+// the child's state from GitHub rather than trusting the unit's summary. A verifier that 403s leaves
+// the delegation running with nothing checking it.
+//
+// **A failed read is never printed as a state.** `gh issue view` exited non-zero with nothing on
+// stdout for a rate limit and for a number that does not exist alike, and a loop that read the empty
+// answer as "not CLOSED" would report a child as failed because nobody could reach GitHub. The two
+// are told apart here and neither is a state.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const REPO_FLAG = '--repo'
+const FLAG_PREFIX = '-'
+const INLINE_REPO_FLAG = `${REPO_FLAG}=`
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const USAGE = 'Usage: josh issue:state <issue-number> [<issue-number> ...] [--repo <owner/repo>]'
+// A blank line between the blocks of a multi-number report, so a person sees where one issue ends
+// while a reader matching `issue: ` still finds each block by its first line.
+const BLOCK_SEPARATOR = '\n\n'
+// The same bound `epic:bundle` puts on its reference lookup, for the same reason: every read is a
+// `gh` process, and an unbounded fan-out is answered with secondary rate limiting rather than with
+// states.
+const READ_CONCURRENCY = 8
+// The two fields, under the names `gh issue view --json` gave them. `git-gh-issue-rest.ts` maps them
+// back from REST, which is what keeps `OPEN` / `CLOSED` / `MERGED` out of this file.
+const STATE_FIELDS = 'state,labels'
+
+interface StateRequest {
+	issue_numbers: ReadonlyArray<string>
+	repo?: string
+}
+
+// The two failure kinds a read can end in, kept apart all the way to the report: `missing` is the
+// number resolving to nothing and `unreadable` is a read that failed, and the documents ask a
+// caller to report the two differently. Folding them together to simplify the batch would destroy
+// exactly that distinction.
+type ReadFailureKind = 'missing' | 'unreadable'
+
+// One issue's state, or the failure kind. Named for export because `run:prep` reads the state beside
+// the body and the dependency-update scope (joshuafolkken/kit#1978), reusing this read rather than a
+// second one that would drift from the `human_review` decision `parse_issue_state` owns.
+type StateRead = { kind: 'state'; state: IssueState } | { kind: ReadFailureKind }
+
+interface IssueReport {
+	issue_number: string
+	result: StateRead
+}
+
+// `absent` and "given but with nothing usable after it" are different answers. Falling back to the
+// session's repository on the second would print a confident state for a *different* issue of the
+// same number, which is the exact misread the `--repo` argument exists to prevent.
+//
+// A named flag carries the argv positions it actually occupied, never the token text it matched
+// (joshuafolkken/kit#1355). Removing tokens by value removes every token that happens to look like
+// one of them — a second `--repo`, a repeated `owner/repo` — and a token removed is a token nobody
+// is told about, which is the whole failure this file refuses elsewhere.
+type RepoFlag =
+	| { kind: 'absent' }
+	| { kind: 'named'; repo: string; consumed: ReadonlyArray<number> }
+	| { kind: 'incomplete' }
+
+// Both spellings gh itself accepts. `--repo=owner/repo` falling through to the separate-word branch
+// would read as no repository at all, which is the fall back to the session's repository above.
+function read_inline_repo(argv: ReadonlyArray<string>): RepoFlag | undefined {
+	const inline = argv.find((argument) => argument.startsWith(INLINE_REPO_FLAG))
+
+	if (inline === undefined) return undefined
+
+	const repo = inline.slice(INLINE_REPO_FLAG.length)
+
+	if (repo.length === 0) return { kind: 'incomplete' }
+
+	return { kind: 'named', repo, consumed: [argv.indexOf(inline)] }
+}
+
+function read_separate_repo(argv: ReadonlyArray<string>): RepoFlag {
+	const index = argv.indexOf(REPO_FLAG)
+
+	if (index === -1) return { kind: 'absent' }
+
+	const value_index = index + 1
+	const repo = argv[value_index]
+
+	if (repo === undefined || repo.startsWith(FLAG_PREFIX)) return { kind: 'incomplete' }
+
+	return { kind: 'named', repo, consumed: [index, value_index] }
+}
+
+function read_repo_flag(argv: ReadonlyArray<string>): RepoFlag {
+	return read_inline_repo(argv) ?? read_separate_repo(argv)
+}
+
+// The argv positions the repository flag occupied, and nothing else. Everything outside this set was
+// offered as an issue number, whatever it looks like — so a flag nobody recognizes reaches the check
+// below and refuses the call instead of vanishing from it (joshuafolkken/kit#1355).
+function consumed_indices(repo_flag: RepoFlag): ReadonlySet<number> {
+	return new Set(repo_flag.kind === 'named' ? repo_flag.consumed : [])
+}
+
+function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
+	const repo_flag = read_repo_flag(argv)
+
+	if (repo_flag.kind === 'incomplete') return undefined
+
+	// The repository is read first, flag word and value together, so neither is ever mistaken for an
+	// issue number — and nothing else is removed here. Every remaining token is one the caller offered
+	// as an issue number, whatever it looks like.
+	const consumed = consumed_indices(repo_flag)
+	const rest = argv.filter((_argument, index) => !consumed.has(index))
+	const numbers = rest.filter((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+
+	// A token that is not a number refuses the whole invocation rather than being dropped. Dropping
+	// it answers fewer numbers than were asked for and still exits zero — and with one number left,
+	// the surviving block prints in the single-number shape, so nothing in the output says a number
+	// went unanswered. `#1262` copied out of a `diag` table is exactly that token.
+	//
+	// An unrecognized flag reaches this same check rather than a lenient one of its own
+	// (joshuafolkken/kit#1355). `--rep=owner/repo` used to be discarded for starting with a dash, so
+	// the call fell back to the session's repository and printed a confident state for a *different*
+	// repository's issue of that number — the misread `incomplete` already exists to prevent.
+	if (numbers.length === 0 || numbers.length !== rest.length) return undefined
+
+	// In the order they were typed, with a repeat dropped: repeating a number would spend a second
+	// read on an answer already in hand, and print a second block a caller counting rows counts twice.
+	const issue_numbers = [...new Set(numbers)]
+
+	return repo_flag.kind === 'named' ? { issue_numbers, repo: repo_flag.repo } : { issue_numbers }
+}
+
+// A number that resolves to nothing is an answer — a typo, or another repository's number quoted in
+// prose — and it is reported as one. Everything else is a gap, and the message says so, because the
+// caller's next move differs: a gap is retried, an answer is not.
+function report_failure(kind: ReadFailureKind, issue_number: string): void {
+	if (kind === 'missing') {
+		console.error(`✖ issue #${issue_number} does not resolve — check the number and the repository`)
+	} else {
+		console.error(
+			`✖ could not read issue #${issue_number} — a rate limit, expired auth, or a dropped connection. This is not "the issue is open"`,
+		)
+	}
+}
+
+// One number's read, reduced to what the report needs and nothing printed yet. Separating the two
+// is what lets the whole batch be in flight at once: the numbers are independent, so reading them
+// one after the other spends a round trip per number for no reason.
+async function read_issue(issue_number: string, repo?: string): Promise<StateRead> {
+	const read = await git_gh_command.issue_view_json_classified(issue_number, STATE_FIELDS, repo)
+
+	if (read.kind !== 'read') return { kind: read.kind }
+
+	const parsed = issue_state.parse_issue_state(read.json)
+
+	return parsed === undefined ? { kind: 'unreadable' } : { kind: 'state', state: parsed }
+}
+
+// Through the shared pool rather than a raw `Promise.all`: each read spawns a `gh` process, and a
+// whole epic's children fired at once draws GitHub's secondary rate limiting — which comes back as
+// `unreadable` for issues that exist and are perfectly readable. Same bound `epic:bundle`'s
+// reference lookup uses, and the pool is shared rather than spelled out again here.
+async function read_all(request: StateRequest): Promise<ReadonlyArray<IssueReport>> {
+	return await bounded_pool.bounded_map(
+		request.issue_numbers,
+		READ_CONCURRENCY,
+		async (issue_number) => ({
+			issue_number,
+			result: await read_issue(issue_number, request.repo),
+		}),
+	)
+}
+
+// `[]` for a number that produced no state, so one unresolvable number costs the others nothing.
+// The heading is withheld for a single number: `.claude/skills/workflow-commands/SKILL.md` §2z and
+// `.claude/skills/diag/SKILL.md` read that report's three lines verbatim.
+function state_blocks(report: IssueReport, should_attribute: boolean): ReadonlyArray<string> {
+	if (report.result.kind !== 'state') return []
+
+	const { state } = report.result
+
+	if (!should_attribute) return [issue_state.format_issue_state(state)]
+
+	return [issue_state.format_attributed_issue_state(report.issue_number, state)]
+}
+
+function print_states(reports: ReadonlyArray<IssueReport>): void {
+	// Derived from what was asked for rather than from what came back: a call for two numbers whose
+	// first resolves to nothing must still name the number the surviving block belongs to.
+	const should_attribute = reports.length > 1
+	const blocks = reports.flatMap((report) => state_blocks(report, should_attribute))
+
+	if (blocks.length === 0) return
+
+	console.info(blocks.join(BLOCK_SEPARATOR))
+}
+
+function report_one_failure(report: IssueReport): boolean {
+	if (report.result.kind === 'state') return false
+
+	report_failure(report.result.kind, report.issue_number)
+
+	return true
+}
+
+// Every number that produced no state is named, so a caller is told which ones it has no answer for
+// rather than being left to subtract the printed blocks from what it asked. A single failure still
+// makes the exit code non-zero, exactly as it did when only one number could be passed.
+function report_failures(reports: ReadonlyArray<IssueReport>): number {
+	let has_failure = false
+
+	for (const report of reports) {
+		has_failure = report_one_failure(report) || has_failure
+	}
+
+	return has_failure ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reports = await read_all(request)
+
+	print_states(reports)
+
+	return report_failures(reports)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_state_cli = { STATE_FIELDS, USAGE, main, parse_request, read_issue, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { StateRead }
+export { issue_state_cli }

package/scripts/issue/issue-state.ts

@@ -0,0 +1,109 @@
+import { has_any_label, NEEDS_HUMAN_REVIEW_LABEL } from '#scripts/git/issue-labels'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// The answer `josh issue:state` prints, kept apart from the reading and the printing so the shape of
+// the report is decided by one pure function (joshuafolkken/kit#1054).
+//
+// The command exists because the *instructions* needed one. `gh issue view <N> --json state` is what
+// an unattended epic run was told to type to confirm a delegated child, and gh answers that call
+// over GraphQL — which a cloud session is refused (403). The REST endpoint is served normally, but
+// it reports `open` / `closed` in lower case, so writing the REST call into the documents would have
+// copied the casing rule out of `git-gh-rest-state.ts` and into prose. Routing the instruction
+// through a command keeps that rule in the one place joshuafolkken/kit#1024 put it.
+
+const NO_LABELS = '(none)'
+const LABEL_SEPARATOR = ', '
+const STATE_LABEL = 'state: '
+const LABELS_LABEL = 'labels: '
+// Whether this issue is one a run must stop on before committing. Printed as its own line rather than
+// left to a reader matching `needs-human-review` against the `labels:` line above
+// (joshuafolkken/kit#1132): GitHub keeps the spelling a label was created with and treats
+// `Needs-Human-Review` as the same label, so an eye comparing against the lowercase string misses it —
+// and a missed one is a run that does not stop and an artifact that ships, which is the whole thing
+// the label exists to prevent. Every other workflow label already reaches its decision through
+// `has_any_label`, which lowercases; this gives that one the same footing.
+const HUMAN_REVIEW_LABEL_LINE = 'human_review: '
+const YES = 'yes'
+const NO = 'no'
+// The number a block belongs to, printed above it when several were asked for
+// (joshuafolkken/kit#1302). A block carries its own number rather than being matched by position,
+// because a batch read drops the numbers that resolve to nothing — a `diag` table mixes closed
+// issues and numbers that never existed — and a positional reading then attributes every block
+// after the gap to the wrong issue.
+const ISSUE_LABEL = 'issue: '
+
+const HUMAN_REVIEW_LABELS: ReadonlySet<string> = new Set([NEEDS_HUMAN_REVIEW_LABEL])
+
+// `state` and `labels` as `git_gh_issue_read` answers them — the field names and the casing
+// `gh issue view --json` used, not REST's. A response missing `state` is not a state report, so it
+// fails the parse rather than printing an empty verdict.
+const label_schema = z.looseObject({ name: z.string() })
+
+const issue_state_schema = z.looseObject({
+	state: z.string(),
+	labels: label_schema.array().optional(),
+})
+
+interface IssueState {
+	state: string
+	labels: ReadonlyArray<string>
+	// Decided here rather than by the caller, so the casing rule lives with the labels it is about.
+	is_human_review: boolean
+}
+
+// `undefined` for anything that is not a state report — malformed JSON, and equally a well-formed
+// response carrying something else (`{"message":"API rate limit exceeded"}`). The shared parser
+// throws on the second so a changed `gh` field stays visible to its other callers; here the two are
+// the same answer, because printing either as a state is what this command exists to prevent.
+function parse_issue_state(json: string): IssueState | undefined {
+	try {
+		const parsed = parse_json_object_safe(json, issue_state_schema)
+
+		if (parsed === undefined) return undefined
+
+		const labels = parsed.labels ?? []
+
+		return {
+			state: parsed.state,
+			labels: labels.map((label) => label.name),
+			is_human_review: has_any_label(labels, HUMAN_REVIEW_LABELS),
+		}
+	} catch {
+		return undefined
+	}
+}
+
+// `(none)` rather than an empty tail: the caller reads this to tell a parked child from a failed one,
+// and a line that simply stops after `labels:` is indistinguishable from a truncated answer.
+function format_labels(labels: ReadonlyArray<string>): string {
+	return labels.length === 0 ? NO_LABELS : labels.join(LABEL_SEPARATOR)
+}
+
+function format_issue_state(state: IssueState): string {
+	const human_review = `${HUMAN_REVIEW_LABEL_LINE}${state.is_human_review ? YES : NO}`
+
+	return `${STATE_LABEL}${state.state}\n${LABELS_LABEL}${format_labels(state.labels)}\n${human_review}`
+}
+
+// The same three lines, under the number they belong to. Kept as a separate function rather than a
+// flag on the one above, so the single-number report has no branch that could ever prepend a fourth
+// line to it: `.claude/skills/workflow-commands/SKILL.md` §2z and `.claude/skills/diag/SKILL.md`
+// read those three verbatim, and §2z's `needs-human-review` stop is decided from them.
+function format_attributed_issue_state(issue_number: string, state: IssueState): string {
+	return `${ISSUE_LABEL}${issue_number}\n${format_issue_state(state)}`
+}
+
+const issue_state = {
+	NO_LABELS,
+	STATE_LABEL,
+	LABELS_LABEL,
+	HUMAN_REVIEW_LABEL_LINE,
+	ISSUE_LABEL,
+	parse_issue_state,
+	format_issue_state,
+	format_attributed_issue_state,
+}
+
+export type { IssueState }
+export { issue_state }

package/scripts/issue/markdown-section.ts

@@ -0,0 +1,39 @@
+// The body lines that sit under one `## heading`, up to the next `## heading` or the end
+// (joshuafolkken/kit#2212). Both the firing-point check and the baseline parser read a section this
+// way, so the slicing lives in one place rather than being written twice.
+
+const HEADING_PREFIX = '## '
+
+function is_heading(line: string): boolean {
+	return line.trimStart().startsWith(HEADING_PREFIX)
+}
+
+function is_the_heading(line: string, heading: string): boolean {
+	return line.trim() === heading
+}
+
+// Whether some body line, trimmed, is exactly `text`. Both linters ask this — of a `## heading` and of
+// the behavior-change declaration line — so the trim-and-match lives here rather than being written in
+// each. A required token mentioned inside a sentence is not the token, so only an exact line matches.
+function has_line(body: string, text: string): boolean {
+	return body.split('\n').some((line) => line.trim() === text)
+}
+
+// The lines between `heading` and the next `## ` heading, trimmed of the heading line itself; an empty
+// array when the heading is absent. A heading matched inside a sentence is not the section heading, so
+// only a line that is exactly the heading opens the section.
+function section_lines(body: string, heading: string): ReadonlyArray<string> {
+	const lines = body.split('\n')
+	const start = lines.findIndex((line) => is_the_heading(line, heading))
+
+	if (start === -1) return []
+
+	const rest = lines.slice(start + 1)
+	const end = rest.findIndex((line) => is_heading(line))
+
+	return end === -1 ? rest : rest.slice(0, end)
+}
+
+const markdown_section = { section_lines, is_heading, has_line }
+
+export { markdown_section }