@joshuafolkken/kit 1.1514.0 → 1.2114.0

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,16 +80,28 @@ interface FetchRequest {
 	timeout_ms?: number | undefined
 }
 
+async function read_comments(
+	request: FetchRequest,
+): 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,
-	body: string,
+	issue: IssueRead,
 	etag: string | undefined,
 ): Promise<Fetched> {
-	const comments = issue_watch_diff.parse_comments(
-		await git_gh_issue_read.issue_list_comments(request.issue, request.timeout_ms),
-	)
+	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> {
@@ -97,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
@@ -114,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(
@@ -125,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
 }
@@ -144,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 {
@@ -190,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 {
@@ -229,6 +272,7 @@ const issue_watch = {
 	clear,
 	clear_here,
 	mark_shown,
+	news_of,
 	poll,
 	read_record,
 	record_baseline,

package/scripts/issue/issue-wip.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { INTERRUPT_ROUTE_LABEL, SPLIT_ROUTE_LABEL, TIER_A_ROUTE_LABEL } from './issue-labels'
 
 // The WIP cap at the call that files. `josh issue:file` reads the count and asks the exemption
@@ -55,13 +56,7 @@ function count_line(count: number, repo: string, verdict: WipVerdict): string {
 // The listing's JSON is an array of rows; anything else is unreadable rather than zero, because zero
 // would pass every filing as within the cap.
 function count_of(json: string): number | undefined {
-	try {
-		const parsed: unknown = JSON.parse(json)
-
-		return Array.isArray(parsed) ? parsed.length : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_array(json)?.length
 }
 
 const issue_wip = { WIP_CAP, HELD, HELD_MESSAGE, UNREAD_MESSAGE, verdict_of, count_line, count_of }

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,64 +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'
-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(),
-})
-
-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 {
@@ -82,33 +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)
-}
-
-// 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 association = issue.author_association ?? UNKNOWN_ASSOCIATION
-
-	if (!gh_author_association.is_trusted(association)) {
-		return {
-			kind: 'refused',
-			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${gh_author_association.TRUSTED_LIST}`,
-		}
-	}
-
-	return { kind: 'trusted', body: issue.body ?? '' }
-}
-
 async function rerun(body: string, now: Date): Promise<number> {
 	const baselines = baseline_measure.parse_baselines(body)
 
@@ -136,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-cli.ts

@@ -0,0 +1,39 @@
+import { plan_consumers } from '#scripts/issue/plan-consumers'
+
+// `josh plan:consumers <identifier...>` — prints each identifier's existing references and the draft
+// of a plan's existing-consumers section (`plan-consumers.ts`). A flag is refused rather than searched
+// for, since an identifier never starts with `-`.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh plan:consumers <identifier...>'
+
+function identifiers_of(argv: ReadonlyArray<string>): Array<string> | undefined {
+	const identifiers = [...new Set(argv.map((argument) => argument.trim()))]
+
+	if (identifiers.length === 0) return undefined
+
+	return identifiers.some((identifier) => identifier === '' || identifier.startsWith('-'))
+		? undefined
+		: identifiers
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const identifiers = identifiers_of(argv)
+
+	if (identifiers === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const { text, has_failed } = await plan_consumers.report(identifiers)
+
+	console.info(text)
+
+	return has_failed ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+const plan_consumers_cli = { USAGE, run }
+
+export { plan_consumers_cli }

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { plan_consumers_cli } from './plan-consumers-cli'
+
+// The `josh plan:consumers` entry, kept apart from `plan-consumers-cli.ts` so a bundle carrying that
+// module never fires this guard (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await plan_consumers_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -0,0 +1,76 @@
+import { markdown_section } from '#scripts/issue/markdown-section'
+
+// A plan's existing-consumers section (`HEADING`) — the existing code, prompts and documents that
+// read or write each state, command, label, file or process the plan adds or changes, and what this
+// issue does with each. A concept added without it shipped while its readers still assumed the old
+// world (joshuafolkken/kit#4270, #4265 after `lane:pause`), so `issue:plan` refuses a plan that omits
+// it.
+//
+// **"None" is an answer only with its reason** (`NONE_WITH_REASON`), since a bare "none" cannot be
+// told from a section filled in to get past the check.
+
+const HEADING = '### 影響を受ける既存の利用者'
+const ANY_HEADING = /^#{1,6}\s/u
+const LIST_MARKER = /^(?:[-*+]|\d+\.)\s+/u
+const NONE_WORD = 'なし'
+const NONE_WITH_REASON = /^なし\s*[（(]\s*\S.*[）)]$/u
+const MISSING = `The plan has no \`${HEADING}\` section: list, for each state, command, label, file or process it adds or changes, the existing places that read or write it and what this issue does with each (\`pnpm josh plan:consumers <identifier...>\` drafts it), or write \`なし（<reason>）\`.`
+const EMPTY = `The plan's \`${HEADING}\` section is empty: list the existing consumers, or write \`なし（<reason>）\`.`
+const BARE_NONE = `The plan's \`${HEADING}\` section says \`なし\` without a reason: write \`なし（<reason>）\`.`
+
+// The section runs to the next heading of any level, since the plan's own sections are `###`. Fenced
+// lines are blanked first, so a `# comment` in a code block neither ends the section nor is an entry.
+function section_entries(plan: string): ReadonlyArray<string> | undefined {
+	if (!markdown_section.has_line(plan, HEADING)) return undefined
+	const raw = markdown_section.section_lines(plan, HEADING).join('\n')
+	const lines = markdown_section.fence_free_lines(raw)
+	const end = lines.findIndex((line) => ANY_HEADING.test(line.trim()))
+	const body = end === -1 ? lines : lines.slice(0, end)
+
+	return body.map((line) => line.trim().replace(LIST_MARKER, '')).filter((line) => line !== '')
+}
+
+// "None" answers for the whole section, so only a section that opens with it is read as one — a "none"
+// nested under a consumer entry is that entry's note. A reason wrapped onto later lines is joined back.
+function is_bare_none(entries: ReadonlyArray<string>): boolean {
+	const [first = ''] = entries
+
+	if (!first.startsWith(NONE_WORD) || NONE_WITH_REASON.test(first)) return false
+
+	return !NONE_WITH_REASON.test(entries.join(' '))
+}
+
+// The refusal for a plan whose section is missing, empty or a reasonless "none"; `undefined` passes.
+function refusal_of(plan: string): string | undefined {
+	const entries = section_entries(plan)
+
+	if (entries === undefined) return MISSING
+	if (entries.length === 0) return EMPTY
+
+	return is_bare_none(entries) ? BARE_NONE : undefined
+}
+
+// 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/plan-consumers.ts

@@ -0,0 +1,127 @@
+import { git_grep_hits, type Hit } from '#scripts/git/git-grep-hits'
+import { plan_consumers_section } from '#scripts/issue/plan-consumers-section'
+
+// `josh plan:consumers <identifier...>` — where each identifier a plan adds or changes is already
+// read or written, so its existing-consumers section names them rather than leaving them for the
+// next incident to find. Every reference in the tracked tree — a CI workflow or a settings file reads
+// a name as surely as code does — grouped by kind, then a draft of the section for the plan to finish.
+// `.josh/` is left out: its observations and metrics record past runs rather than read the name.
+//
+// **Unlike `run:prep`'s code locations it keeps every line and every kind** — a prompt that tells a
+// run to count a label is as much a consumer of it as the code that does — but caps each kind, so one
+// common name cannot bury the rest.
+
+type Kind = 'code' | 'config' | 'doc' | 'prompt' | 'test'
+
+interface Consumers {
+	identifier: string
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+const PATHSPECS = [':(exclude).josh']
+const KINDS: ReadonlyArray<readonly [Kind, string]> = [
+	['code', 'code'],
+	['config', 'config and workflows'],
+	['prompt', 'prompts and skills'],
+	['doc', 'docs'],
+	['test', 'tests'],
+]
+const TEST_PATH = /(?:\.test\.ts|\.e2e\.ts|\.snap)$/u
+const CODE_PATH = /\.(?:ts|js|mjs|cjs|svelte|sh)$/u
+const PROMPT_ROOTS = ['prompts/', '.claude/']
+const MAX_HITS_PER_KIND = 20
+const MAX_DRAFT_FILES = 8
+const INDENT = '  '
+const HIT_INDENT = `${INDENT}${INDENT}`
+const HIT_SEPARATOR = '  '
+const NO_REFERENCE = ' — no reference in the tracked tree'
+const SEARCH_FAILED = ' — git grep failed; not searched'
+const DRAFT_ACTION = '<直す | 影響なし | 別 Issue>'
+const DRAFT_NO_REFERENCE = 'no existing reference'
+
+// Markdown under `prompts/` or `.claude/` instructs a run and other Markdown is read by people; the
+// rest that is neither code nor a test — workflows, settings, JSON and YAML data — is configuration.
+function markdown_kind(path: string): Kind {
+	return PROMPT_ROOTS.some((root) => path.startsWith(root)) ? 'prompt' : 'doc'
+}
+
+function kind_of(path: string): Kind {
+	if (TEST_PATH.test(path)) return 'test'
+	if (CODE_PATH.test(path)) return 'code'
+
+	return path.endsWith('.md') ? markdown_kind(path) : 'config'
+}
+
+function more_line(count: number): Array<string> {
+	return count > MAX_HITS_PER_KIND
+		? [`${HIT_INDENT}… +${String(count - MAX_HITS_PER_KIND)} more`]
+		: []
+}
+
+function format_kind(hits: ReadonlyArray<Hit>, kind: Kind, label: string): Array<string> {
+	const of_kind = hits.filter((hit) => kind_of(hit.path) === kind)
+
+	if (of_kind.length === 0) return []
+	const lines = of_kind
+		.slice(0, MAX_HITS_PER_KIND)
+		.map((hit) => `${HIT_INDENT}${hit.path}:${hit.line}${HIT_SEPARATOR}${hit.excerpt}`)
+
+	return [`${INDENT}${label}`, ...lines, ...more_line(of_kind.length)]
+}
+
+function format_consumers(consumers: Consumers): string {
+	if (consumers.has_failed) return `${consumers.identifier}${SEARCH_FAILED}`
+	if (consumers.hits.length === 0) return `${consumers.identifier}${NO_REFERENCE}`
+	const kinds = KINDS.flatMap(([kind, label]) => format_kind(consumers.hits, kind, label))
+
+	return [consumers.identifier, ...kinds].join('\n')
+}
+
+// Tests are left out of the draft: a test follows the code it covers, so it is never the consumer a
+// plan has to decide about.
+function kind_rank(path: string): number {
+	return KINDS.findIndex(([kind]) => kind === kind_of(path))
+}
+
+// Code first, in `KINDS` order, so the cap drops docs before the code a plan most has to decide on.
+function draft_files(hits: ReadonlyArray<Hit>): Array<string> {
+	const paths = [...new Set(hits.map((hit) => hit.path))]
+		.filter((path) => kind_of(path) !== 'test')
+		.toSorted((left, right) => kind_rank(left) - kind_rank(right))
+	const shown = paths.slice(0, MAX_DRAFT_FILES).map((path) => `\`${path}\``)
+	const rest = paths.length - shown.length
+
+	return rest > 0 ? [...shown, `+${String(rest)} more`] : shown
+}
+
+function draft_entry(consumers: Consumers): string {
+	const files = draft_files(consumers.hits)
+
+	if (files.length === 0) return `- \`${consumers.identifier}\`: ${DRAFT_NO_REFERENCE}`
+
+	return `- \`${consumers.identifier}\`: ${files.join(', ')} — ${DRAFT_ACTION}`
+}
+
+function format_draft(all: ReadonlyArray<Consumers>): string {
+	const entries = all.map((consumers) => draft_entry(consumers))
+
+	return ['draft:', plan_consumers_section.HEADING, '', ...entries].join('\n')
+}
+
+async function find(identifier: string): Promise<Consumers> {
+	return { identifier, ...(await git_grep_hits.search(identifier, [], PATHSPECS)) }
+}
+
+async function report(
+	identifiers: ReadonlyArray<string>,
+): Promise<{ text: string; has_failed: boolean }> {
+	const all = await Promise.all(identifiers.map(async (identifier) => await find(identifier)))
+	const sections = [...all.map((consumers) => format_consumers(consumers)), format_draft(all)]
+
+	return { text: sections.join('\n\n'), has_failed: all.some((consumers) => consumers.has_failed) }
+}
+
+const plan_consumers = { kind_of, report }
+
+export { plan_consumers }

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