@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/issue/issue-template-section.ts

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { package_path } from '#scripts/init/init-paths'
+import { markdown_section } from './markdown-section'
+
+// One section of the Issue body template, cut from the fenced template in `issue-template.md` — its
+// single source — so a refusal for a missing heading can print the section to paste back in rather than
+// sending the filer to reopen the document (joshuafolkken/kit#5206).
+const TEMPLATE_PATH = 'prompts/collaboration-workflow/issue-template.md'
+const TEMPLATE_FENCE = '````'
+
+// The lines inside the document's four-backtick template fence; an empty array when it has none.
+function template_lines(document: string): ReadonlyArray<string> {
+	const lines = markdown_section.lines_of(document)
+	const start = lines.findIndex((line) => line.startsWith(TEMPLATE_FENCE))
+	const end = lines.findIndex((line, index) => index > start && line.trim() === TEMPLATE_FENCE)
+
+	if (start === -1 || end === -1) return []
+
+	return lines.slice(start + 1, end)
+}
+
+// The heading and its template lines, trailing blank lines dropped; `undefined` when the template has no
+// such section.
+function section_of(document: string, heading: string): string | undefined {
+	const template = template_lines(document).join('\n')
+
+	if (!markdown_section.has_line(template, heading)) return undefined
+
+	return [heading, ...markdown_section.section_lines(template, heading)].join('\n').trimEnd()
+}
+
+// A package without the template prints the bare problem rather than failing the lint.
+function section(heading: string): string | undefined {
+	const template_path = package_path(TEMPLATE_PATH)
+
+	if (!existsSync(template_path)) return undefined
+
+	return section_of(readFileSync(template_path, 'utf8'), heading)
+}
+
+const issue_template_section = { section, section_of }
+
+export { issue_template_section }

package/scripts/issue/issue-watch-diff.ts

@@ -21,6 +21,12 @@ import { z } from 'zod'
 // body withheld, costing one `josh issue:ack` rather than a missed correction, and its marker is not
 // trusted.
 //
+// **A body edit is a person's update only when the issue's author has write access.** GitHub does not
+// say who edited a body, and its author can always edit it, so a body under an author without write
+// access is never handed to a run as an update: its edit becomes a notice with the text withheld,
+// which asks for nothing and holds no merge. A `MEMBER` / `COLLABORATOR` author whose lookup failed
+// is treated like their comment: the edit is announced with its text withheld and stays pending.
+//
 // **Comment edits are out of scope.** A new comment carries an id above the baseline's; an edited
 // one keeps its id and is not seen. The body is compared whole, so its edits are.
 
@@ -33,6 +39,8 @@ const UNKNOWN_TIME = '(undated)'
 const UNVERIFIED_BODY =
 	"(body withheld — the author's write access could not be checked; read it with `josh issue:read`)"
 
+const WITHHELD_BODY_EDIT = `The body of this run's issue was edited, but its author is not ${gh_author_association.TRUSTED_LIST}, so the edit is withheld: it is not an instruction to this run and holds nothing — carry on.`
+
 const BODY_HEADING = 'Body edited:'
 const REMOVED_PREFIX = '- '
 const ADDED_PREFIX = '+ '
@@ -62,6 +70,8 @@ interface WatchComment {
 
 interface WatchSnapshot {
 	body: string
+	// Whether the issue's author has write access — `undefined` when the lookup failed.
+	is_body_trusted: boolean | undefined
 	comments: ReadonlyArray<WatchComment>
 }
 
@@ -171,9 +181,20 @@ function new_person_comments(
 	)
 }
 
+function is_body_edited(baseline: WatchBaseline, snapshot: WatchSnapshot): boolean {
+	return to_lf(baseline.body) !== to_lf(snapshot.body)
+}
+
+function unread_body(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	if (snapshot.is_body_trusted === true) return body_section(baseline.body, snapshot.body)
+	if (snapshot.is_body_trusted === false || !is_body_edited(baseline, snapshot)) return undefined
+
+	return `${BODY_HEADING}${LINE_SEPARATOR}${UNVERIFIED_BODY}`
+}
+
 // The unread update as the text a run is shown, or `undefined` when a person changed nothing.
 function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
-	const body = body_section(baseline.body, snapshot.body)
+	const body = unread_body(baseline, snapshot)
 	const comments = new_person_comments(baseline, snapshot).map((comment) =>
 		comment_section(comment),
 	)
@@ -182,11 +203,20 @@ function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string |
 	return sections.length === 0 ? undefined : sections.join(SECTION_SEPARATOR)
 }
 
+// The notice for a body edit `unread_diff` withholds, or `undefined` when there is none.
+function withheld_notice(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	if (snapshot.is_body_trusted !== false || !is_body_edited(baseline, snapshot)) return undefined
+
+	return WITHHELD_BODY_EDIT
+}
+
 const issue_watch_diff = {
 	RUN_MARKER,
+	WITHHELD_BODY_EDIT,
 	baseline_of,
 	parse_comments,
 	unread_diff,
+	withheld_notice,
 }
 
 export type { WatchBaseline, WatchComment, WatchSnapshot }

package/scripts/issue/issue-watch-hook.ts

@@ -22,7 +22,16 @@ const POLL_INTERVAL_MS = 180_000
 const POLL_TIMEOUT_MS = 5000
 
 function is_new_to_run(record: WatchRecord | undefined): record is WatchRecord {
-	return record?.pending !== undefined && record.pending !== record.shown
+	const news = record === undefined ? undefined : issue_watch.news_of(record)
+
+	return news !== undefined && news !== record?.shown
+}
+
+// A withheld body edit is shown as its own notice: it asks for no `josh issue:ack`.
+function message_of(record: WatchRecord): string {
+	return record.pending === undefined
+		? (record.notice ?? '')
+		: issue_watch_gate.unread_message(record)
 }
 
 async function new_update_reason(now: Date): Promise<string | undefined> {
@@ -36,7 +45,7 @@ async function new_update_reason(now: Date): Promise<string | undefined> {
 
 	issue_watch.mark_shown(record)
 
-	return issue_watch_gate.unread_message(record)
+	return message_of(record)
 }
 
 async function watch_reason(now: Date = new Date()): Promise<string | undefined> {

package/scripts/issue/issue-watch.ts

@@ -1,3 +1,4 @@
+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_conditional } from '#scripts/gh/git-gh-conditional'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
@@ -30,10 +31,18 @@ const record_schema = z.object({
 	checked_at: z.string(),
 	etag: z.string().optional(),
 	pending: z.string().optional(),
+	// A body edit withheld from the run (`issue_watch_diff.withheld_notice`) — shown, never a hold.
+	notice: z.string().optional(),
 	shown: z.string().optional(),
 })
 
-const issue_schema = z.looseObject({ body: z.string().nullish(), state: z.string() })
+const issue_schema = z.looseObject({
+	body: z.string().nullish(),
+	state: z.string(),
+	...gh_author_association.author_fields_schema,
+})
+
+type IssueRead = z.infer<typeof issue_schema>
 
 type WatchRecord = z.infer<typeof record_schema>
 
@@ -71,17 +80,28 @@ interface FetchRequest {
 	timeout_ms?: number | undefined
 }
 
-async function read_snapshot(
+async function read_comments(
 	request: FetchRequest,
-	body: string,
-	etag: string | undefined,
-): Promise<Fetched> {
-	const comments = await issue_watch_diff.parse_comments(
+): Promise<WatchSnapshot['comments'] | undefined> {
+	return await issue_watch_diff.parse_comments(
 		await git_gh_issue_read.issue_list_comments(request.issue, request.timeout_ms),
 		request.timeout_ms,
 	)
+}
+
+async function read_snapshot(
+	request: FetchRequest,
+	issue: IssueRead,
+	etag: string | undefined,
+): Promise<Fetched> {
+	const [comments, is_body_trusted] = await Promise.all([
+		read_comments(request),
+		gh_author_association.trust_of(gh_author_association.author_of(issue, request.timeout_ms)),
+	])
 
-	return comments === undefined ? UNREADABLE : { kind: 'read', snapshot: { body, comments }, etag }
+	if (comments === undefined) return UNREADABLE
+
+	return { kind: 'read', snapshot: { body: issue.body ?? '', is_body_trusted, comments }, etag }
 }
 
 async function fetch_issue(request: FetchRequest): Promise<Fetched> {
@@ -98,7 +118,7 @@ async function fetch_issue(request: FetchRequest): Promise<Fetched> {
 	if (fields === undefined) return UNREADABLE
 	if (fields.state === CLOSED_STATE) return { kind: 'closed' }
 
-	return await read_snapshot(request, fields.body ?? '', read.etag)
+	return await read_snapshot(request, fields, read.etag)
 }
 
 // `acknowledged_at` is when a person's update was last taken in — the baseline's own read, or an
@@ -115,6 +135,20 @@ function fresh_record(
 	return { issue, ...baseline, acknowledged_at, checked_at, etag: fetched.etag }
 }
 
+// The previous `acknowledged_at` when a re-read of the same issue takes nothing in, so a `josh
+// run:entry` re-run keeps a review briefed before it valid; `undefined` (now) otherwise.
+function kept_acknowledgement(
+	previous: WatchRecord | undefined,
+	issue: string,
+	fetched: Extract<Fetched, { kind: 'read' }>,
+): string | undefined {
+	if (previous?.issue !== issue) return undefined
+
+	const diff = issue_watch_diff.unread_diff(previous, fetched.snapshot)
+
+	return diff === undefined ? previous.acknowledged_at : undefined
+}
+
 // Called by `josh run:entry` once it has printed the issue. `false` when the issue could not be read,
 // which leaves no record — a watch with no baseline would call the whole issue unread.
 async function record_baseline(
@@ -126,7 +160,9 @@ async function record_baseline(
 
 	if (fetched.kind !== 'read') return false
 
-	write_record(fresh_record(issue, fetched, now), root)
+	const acknowledged_at = kept_acknowledgement(read_record(root), issue, fetched)
+
+	write_record(fresh_record(issue, fetched, now, acknowledged_at), root)
 
 	return true
 }
@@ -145,8 +181,9 @@ function with_fetched(record: WatchRecord, fetched: Fetched, checked_at: string)
 	if (fetched.kind !== 'read') return { ...record, checked_at }
 
 	const pending = issue_watch_diff.unread_diff(record, fetched.snapshot)
+	const notice = issue_watch_diff.withheld_notice(record, fetched.snapshot)
 
-	return { ...record, checked_at, etag: fetched.etag, pending }
+	return { ...record, checked_at, etag: fetched.etag, pending, notice }
 }
 
 interface PollOptions {
@@ -191,9 +228,14 @@ async function poll(options: PollOptions, root?: string): Promise<WatchRecord |
 	return await refresh(record, options, now, root)
 }
 
-// Marks a pending update shown, so the hook stops once per update rather than on every call.
+// What the hook shows: a pending update, else a withheld edit's notice.
+function news_of(record: WatchRecord): string | undefined {
+	return record.pending ?? record.notice
+}
+
+// Marks the news shown, so the hook stops once per update rather than on every call.
 function mark_shown(record: WatchRecord, root?: string): WatchRecord {
-	return write_record({ ...record, shown: record.pending }, root)
+	return write_record({ ...record, shown: news_of(record) }, root)
 }
 
 interface Acknowledged {
@@ -230,6 +272,7 @@ const issue_watch = {
 	clear,
 	clear_here,
 	mark_shown,
+	news_of,
 	poll,
 	read_record,
 	record_baseline,

package/scripts/issue/markdown-section.ts

@@ -94,6 +94,7 @@ const markdown_section = {
 	section_lines,
 	section_lines_matching,
 	fence_free_lines,
+	lines_of,
 	unfenced_lines,
 	has_line,
 	has_unfenced_line,

package/scripts/issue/measure-declaration.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4621: a follow-up measurement ("measure K merges after #N") took a lane for 20–40
+// minutes to run one command and compare its value with a bound — work `backlog:drive` can do itself.
+// The body declares that command and the bound once, under the background heading, so the drive runs
+// it when the issue comes due and closes it on a pass; only a miss or an unreadable value takes a lane.
+//
+// **The value is the command's last non-empty output line, read as one number.** Anything else — a
+// unit, a sentence, a failure — is unreadable, so a person never relies on how a free-text line parses.
+
+const BACKGROUND_HEADING = '## 背景'
+const PREFIX = '- 計測宣言:'
+// joshuafolkken/kit#5144: a follow-up whose value no one command prints (an Actions record, an external
+// service) says why under the same heading instead, so it files without a declaration.
+const ABSENT_PREFIX = '- 計測宣言なし:'
+const ABSENT = `${ABSENT_PREFIX} <理由>`
+const DECLARATION = `${PREFIX} \`<command>\` <=|<|>=|> <number>`
+const VALUE_PATTERN =
+	/^`(?<command>[^`\s][^`]*)`\s*(?<operator><=|>=|<|>)\s*(?<threshold>-?\d+(?:\.\d+)?)$/u
+const NUMBER_PATTERN = /^-?\d+(?:\.\d+)?$/u
+// The refusal ends in a line ready to paste (joshuafolkken/kit#5225).
+const EXAMPLE = `${PREFIX} \`pnpm josh lane:net 5168\` <= 40`
+const MALFORMED = `\`${PREFIX}\` must be written ${DECLARATION}\n${EXAMPLE}`
+const declaration_schema = z.object({
+	command: z.string().trim(),
+	operator: z.enum(['<=', '<', '>=', '>']),
+	threshold: z.coerce.number(),
+})
+
+type MeasureDeclaration = z.infer<typeof declaration_schema>
+type Operator = MeasureDeclaration['operator']
+type MeasureVerdict = { kind: 'pass' | 'fail'; value: number } | { kind: 'unreadable' }
+
+const COMPARE: Readonly<Record<Operator, (value: number, threshold: number) => boolean>> = {
+	'<=': (value, threshold) => value <= threshold,
+	'<': (value, threshold) => value < threshold,
+	'>=': (value, threshold) => value >= threshold,
+	'>': (value, threshold) => value > threshold,
+}
+
+// The value after `prefix` under the background heading, or `undefined` when the body has no such line.
+function background_value(body: string, prefix: string): string | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const line = markdown_section
+		.unfenced_lines(background)
+		.map((text) => text.trim())
+		.find((text) => text.startsWith(prefix))
+
+	return line?.slice(prefix.length).trim()
+}
+
+function declared_value(body: string): string | undefined {
+	return background_value(body, PREFIX)
+}
+
+// Whether the body writes a declaration line — a malformed one is `problems`' refusal — or says why it
+// has none; an empty reason says nothing.
+function is_stated(body: string): boolean {
+	if (declared_value(body) !== undefined) return true
+
+	return (background_value(body, ABSENT_PREFIX) ?? '').length > 0
+}
+
+function parsed(value: string): MeasureDeclaration | undefined {
+	const read = declaration_schema.safeParse(VALUE_PATTERN.exec(value)?.groups)
+
+	return read.success ? read.data : undefined
+}
+
+// The declaration, or `undefined` when there is none or it does not parse — `issue:file` refuses a
+// malformed one, and the drive hands an issue it cannot read to a lane as before.
+function parse(body: string): MeasureDeclaration | undefined {
+	const value = declared_value(body)
+
+	return value === undefined ? undefined : parsed(value)
+}
+
+function problems(body: string): ReadonlyArray<string> {
+	const value = declared_value(body)
+
+	return value === undefined || parsed(value) !== undefined ? [] : [MALFORMED]
+}
+
+function value_of(output: string): number | undefined {
+	const last = output
+		.split('\n')
+		.map((line) => line.trim())
+		.findLast((line) => line.length > 0)
+
+	return last !== undefined && NUMBER_PATTERN.test(last) ? Number(last) : undefined
+}
+
+function judge(declaration: MeasureDeclaration, output: string): MeasureVerdict {
+	const value = value_of(output)
+
+	if (value === undefined) return { kind: 'unreadable' }
+
+	const is_pass = COMPARE[declaration.operator](value, declaration.threshold)
+
+	return { kind: is_pass ? 'pass' : 'fail', value }
+}
+
+function format(declaration: MeasureDeclaration): string {
+	return `\`${declaration.command}\` ${declaration.operator} ${String(declaration.threshold)}`
+}
+
+const measure_declaration = {
+	ABSENT,
+	DECLARATION,
+	EXAMPLE,
+	PREFIX,
+	format,
+	is_stated,
+	judge,
+	parse,
+	problems,
+}
+
+export type { MeasureDeclaration, MeasureVerdict }
+export { measure_declaration }

package/scripts/issue/measure-rerun-cli.ts

@@ -1,65 +1,33 @@
 #!/usr/bin/env tsx
-import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { gh_author_association } from '#scripts/gh/gh-author-association'
-import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
-import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
-import { error_text } from '#scripts/lib/error-message'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
-import { z } from 'zod'
 import { baseline_measure, type Baseline } from './baseline-measure'
-import { session_cite } from './session-cite'
+import { trusted_measure } from './trusted-measure'
 
 // `josh measure:rerun <N>` — read a behavior-change Issue body after merge, re-run each baseline
 // command, and print the before/after pair. A value that did not move means
 // the premise the rule rested on is refuted, so a line is appended to the observation ledger — reusing
 // that append-only, same-key mechanism rather than a second one.
 //
-// **The baseline is shell, and the body is written by whoever filed the Issue**.
-// A baseline needs pipes and loops (`git log … | wc -l`, `for d in $(ls …)`), so an allow-list of
-// commands cannot make it safe; what can is who wrote it. The input is therefore the Issue number, not
-// a file, so the author's `author_association` arrives with the body from the same REST read, and only
-// a body written by someone with write access to the repository is run.
+// The baseline is shell, so only a body whose author can write to the repository is run
+// (`trusted-measure.ts`).
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_FIELDS = 'body,author_association,user'
-const UNKNOWN_ASSOCIATION = 'unknown'
 const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
 const DATE_END = 10
-// One baseline command's budget — the same minute `josh-harness.ts` gives one command it spawns. A
-// baseline is a count or a digest that answers in seconds, so a command still running after a minute
-// is stuck, and without a bound it would hold the whole re-measurement open with nothing printed.
-const MEASURE_TIMEOUT_MS = 60_000
-const issue_schema = z.object({
-	body: z.string().nullish(),
-	author_association: z.string().nullish(),
-	user: z.looseObject({ login: z.string() }).nullish(),
-})
-
-type IssueFields = z.infer<typeof issue_schema>
-type BodyRead = { kind: 'trusted'; body: string } | { kind: 'refused'; reason: string }
-
-// The command's stdout, trimmed to one value. A failing or timed-out command yields its message so the
-// pair still prints and the remaining baselines still run, rather than aborting the whole
-// re-measurement.
-function measure(command: string): string {
-	try {
-		return execSync(command, { encoding: 'utf8', timeout: MEASURE_TIMEOUT_MS }).trim()
-	} catch (error) {
-		return `(command failed: ${error_text.message_of(error)})`
-	}
-}
 
 interface Outcome {
 	pair: string
 	ledger_line: string | undefined
 }
 
+// A failing or timed-out command yields its message so the pair still prints and the remaining
+// baselines still run, rather than aborting the whole re-measurement.
 function rerun_one(baseline: Baseline, date: string): Outcome {
-	const after = measure(baseline.command)
+	const after = trusted_measure.text_of(trusted_measure.run_command(baseline.command))
 	const is_unchanged = baseline_measure.is_no_change(baseline.value, after)
 
 	return {
@@ -83,37 +51,6 @@ function today(now: Date): string {
 	return now.toISOString().slice(0, DATE_END)
 }
 
-async function read_issue(issue_number: string): Promise<IssueFields | undefined> {
-	const json = await git_gh_issue_read.issue_view_json(issue_number, ISSUE_FIELDS)
-
-	return json === undefined ? undefined : parse_json_object_or_undefined(json, issue_schema)
-}
-
-function untrusted(issue_number: string, issue: IssueFields): BodyRead {
-	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
-
-	return {
-		kind: 'refused',
-		reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author (${association}) is not ${gh_author_association.TRUSTED_LIST}`,
-	}
-}
-
-// The body, only when its author can write to the repository. A read that fails is refused as well:
-// an unknown author is not a trusted one.
-async function read_trusted_body(issue_number: string): Promise<BodyRead> {
-	const issue = await read_issue(issue_number)
-
-	if (issue === undefined) {
-		return { kind: 'refused', reason: `could not read issue ${session_cite.issue(issue_number)}` }
-	}
-
-	const author = { login: issue.user?.login, association: issue.author_association }
-
-	if (!(await gh_author_association.is_trusted(author))) return untrusted(issue_number, issue)
-
-	return { kind: 'trusted', body: issue.body ?? '' }
-}
-
 async function rerun(body: string, now: Date): Promise<number> {
 	const baselines = baseline_measure.parse_baselines(body)
 
@@ -141,7 +78,7 @@ async function run(issue_number: string | undefined, now: Date): Promise<number>
 		return FAILURE_EXIT_CODE
 	}
 
-	const read = await read_trusted_body(issue_number)
+	const read = await trusted_measure.read_trusted_body(issue_number)
 
 	if (read.kind === 'refused') {
 		console.error(read.reason)

package/scripts/issue/plan-consumers-section.ts

@@ -50,6 +50,27 @@ function refusal_of(plan: string): string | undefined {
 	return is_bare_none(entries) ? BARE_NONE : undefined
 }
 
-const plan_consumers_section = { HEADING, refusal_of }
+// The lines `[start, end)` the section spans in `visible`, or `undefined` when the plan has none.
+function section_range(visible: ReadonlyArray<string>): [number, number] | undefined {
+	const start = visible.findIndex((line) => line.trim() === HEADING)
+
+	if (start === -1) return undefined
+	const end = visible.slice(start + 1).findIndex((line) => ANY_HEADING.test(line.trim()))
+
+	return [start, end === -1 ? visible.length : start + 1 + end]
+}
+
+// `plan` with the section, heading included, removed — its entries name the files that read what the
+// plan changes, not the files it edits (joshuafolkken/kit#4923).
+function without(plan: string): string {
+	const range = section_range(markdown_section.unfenced_lines(plan))
+
+	if (range === undefined) return plan
+	const lines = markdown_section.lines_of(plan)
+
+	return [...lines.slice(0, range[0]), ...lines.slice(range[1])].join('\n')
+}
+
+const plan_consumers_section = { HEADING, refusal_of, without }
 
 export { plan_consumers_section }

package/scripts/issue/reproduction-measure.ts

@@ -10,6 +10,8 @@ const REPRODUCTION_HEADING = '## 再現'
 // A backticked command span on a line that is not inside a fenced block. `- `grep …`` and a bare
 // `` `grep …` `` both match; prose with no backticked command does not.
 const COMMAND_SPAN = /`[^`]+`/u
+// A template placeholder span (a backticked `<...>`) the filer never replaced — not a command.
+const PLACEHOLDER_SPAN = /`<[^`]*>`/gu
 // A fenced code block boundary — a backtick or tilde fence. The actual output goes between an opening
 // and a closing fence, so a valid reproduction carries at least two of these lines. Tilde is accepted
 // so the template can show the block without nesting a backtick fence inside its own ```md example.
@@ -28,7 +30,7 @@ function has_command_line(lines: ReadonlyArray<string>): boolean {
 	const first_fence = lines.findIndex((line) => FENCE_LINE.test(line))
 	const open_lines = first_fence === -1 ? lines : lines.slice(0, first_fence)
 
-	return open_lines.some((line) => COMMAND_SPAN.test(line))
+	return open_lines.some((line) => COMMAND_SPAN.test(line.replaceAll(PLACEHOLDER_SPAN, '')))
 }
 
 // An opened-and-closed output block is two fence lines, so counting them is enough — a section with a

package/scripts/issue/size-estimate.ts

@@ -0,0 +1,90 @@
+import { split_assess, type SizeMeasurement } from '#scripts/split/split-assess'
+import { z } from 'zod'
+import { SPLIT_ROUTE_LABEL } from './issue-labels'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4675: a request clearly over the split guide reached a lane as one Issue because
+// nothing asked for its size when it was filed, and a split is cheapest at filing time. Every filing
+// declares its estimate under the background heading, so it stays on the Issue; one over the guide is
+// refused unless it is filed as a split or says why it stays one Issue.
+//
+// **The guide is `split_assess`'s, never a copy** — the measured diff and the declared estimate are
+// judged by one `verdict_for`. An epic (a body carrying `## Split rationale`) declares no estimate:
+// its children do.
+
+const BACKGROUND_HEADING = '## 背景'
+const EPIC_HEADING = '## Split rationale'
+const PREFIX = '- 規模見積もり:'
+const { REASON_PREFIX } = split_assess
+const DECLARATION = `${PREFIX} 約 <N> ファイル / <M> 行（テスト除く）`
+// Full- or half-width parentheses alike: the two read the same to the person typing the line.
+const VALUE_PATTERN =
+	/^約\s*(?<files>\d+)\s*ファイル\s*\/\s*(?<lines>\d+)\s*行\s*[（(]テスト除く[）)]$/u
+const MISSING = `missing size estimate: declare \`${DECLARATION}\` under ${BACKGROUND_HEADING}`
+// The refusal ends in a line ready to paste (joshuafolkken/kit#5225).
+const EXAMPLE = `${PREFIX} 約 3 ファイル / 60 行（テスト除く）`
+const MALFORMED = `\`${PREFIX}\` must be written ${DECLARATION}\n${EXAMPLE}`
+const estimate_schema = z.object({ files: z.coerce.number(), lines: z.coerce.number() })
+
+function declared(body: string, prefix: string): string | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const line = markdown_section
+		.unfenced_lines(background)
+		.map((text) => text.trim())
+		.find((text) => text.startsWith(prefix))
+
+	return line?.slice(prefix.length).trim()
+}
+
+function is_epic(body: string): boolean {
+	return markdown_section.has_line(body, EPIC_HEADING)
+}
+
+// The declared estimate judged against the guide, or `undefined` when there is none or it does not parse.
+function parse(body: string): SizeMeasurement | undefined {
+	const read = estimate_schema.safeParse(VALUE_PATTERN.exec(declared(body, PREFIX) ?? '')?.groups)
+
+	if (!read.success) return undefined
+	const { files, lines } = read.data
+
+	return { files, lines, verdict: split_assess.verdict_for(files, lines) }
+}
+
+// The shape check `issue:lint` makes: the declaration is there and parses. The guide needs the route,
+// which only `issue:file` knows, so it is `guide_problem`'s.
+function problems(body: string): ReadonlyArray<string> {
+	if (is_epic(body)) return []
+	if (declared(body, PREFIX) === undefined) return [MISSING]
+
+	return parse(body) === undefined ? [MALFORMED] : []
+}
+
+// A split filing, or one that declares why it stays one Issue, passes over the guide.
+function is_excused(body: string, route: string | undefined): boolean {
+	return route === SPLIT_ROUTE_LABEL || (declared(body, REASON_PREFIX) ?? '') !== ''
+}
+
+function refusal(estimate: SizeMeasurement): string {
+	const counted = `size estimate ${String(estimate.files)} file(s) / ${String(estimate.lines)} line(s) exceeds the guide (${String(split_assess.FILE_GUIDE)} files / ${String(split_assess.LINE_GUIDE)} lines)`
+
+	return `${counted} — file it split (\`--route split\`) or declare \`${REASON_PREFIX} <理由>\`; split-assessment.md → "${split_assess.QUESTION_SECTION}"`
+}
+
+// The filing refusal for an estimate over the guide; `undefined` under it, on a split filing, or with
+// the reason declared. A missing or malformed estimate is `problems`' refusal, not this one.
+function guide_problem(body: string, route: string | undefined): string | undefined {
+	const estimate = parse(body)
+
+	if (estimate?.verdict !== split_assess.SPLIT_VERDICT) return undefined
+
+	return is_excused(body, route) ? undefined : refusal(estimate)
+}
+
+// The declared file count, or `undefined` when there is no estimate or it does not parse.
+function declared_files(body: string): number | undefined {
+	return parse(body)?.files
+}
+
+const size_estimate = { declared_files, guide_problem, problems }
+
+export { size_estimate }