@joshuafolkken/kit 1.872.0

package/scripts/report/report-lint-cli.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { report_lint } from './report-lint'
+
+// `josh report:lint` — read a two-layer work summary candidate from stdin and print `ok`, or the
+// mechanical violations one per line, exiting non-zero so it works as a gate (joshuafolkken/kit#2123).
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const OK_MESSAGE = 'ok'
+const NO_INPUT_MESSAGE =
+	'✖ nothing on stdin — pipe the work summary in, e.g. `pnpm josh report:lint < summary.md`'
+
+function run(summary: string): number {
+	if (summary.trim().length === 0) {
+		console.error(NO_INPUT_MESSAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const violations = report_lint.lint_report(summary)
+
+	if (violations.length === 0) {
+		console.info(OK_MESSAGE)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	console.error(violations.join('\n'))
+
+	return FAILURE_EXIT_CODE
+}
+
+async function read_and_run(): Promise<number> {
+	if (process.stdin.isTTY) return run('')
+
+	return run(await text(process.stdin))
+}
+
+async function main(): Promise<void> {
+	process.exitCode = await read_and_run()
+}
+
+const report_lint_cli = { run, OK_MESSAGE }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { report_lint_cli }

package/scripts/report/report-lint.ts

@@ -0,0 +1,250 @@
+// The mechanical half of the two-layer work summary (`CLAUDE.md` Step 0, single-sourced in
+// `prompts/collaboration-workflow/report-format.md`) is a fixed shape, yet only an advisory echo in
+// the `UserPromptSubmit` hook ever mentions it and nothing reads the summary an agent actually
+// wrote. This checks the half a machine can: the labels are present, the overview lines stay inside
+// their length, nothing wraps the summary in a code fence, and no file path or CLI flag leaks into
+// the overview. The judgement half — whether the subject is concrete — is deliberately left out,
+// because a machine cannot answer it (joshuafolkken/kit#2123).
+
+// The session-facing labels are Japanese because that is the form the summary is written in
+// (`JOSH_SESSION_LANG` defaults to `ja`); `report-format.md`'s template is the single source and the
+// document test pins that these match it.
+const OVERVIEW_LABEL = '■ 概要'
+const OVERVIEW_ITEM_LABELS = ['今こうなっている', 'こう直す', '確かめ方'] as const
+const DETAILS_LABEL = '技術詳細'
+const CHANGES_LABEL = '変更とテスト'
+const REQUIRED_LABELS: ReadonlyArray<string> = [
+	OVERVIEW_LABEL,
+	...OVERVIEW_ITEM_LABELS,
+	DETAILS_LABEL,
+	CHANGES_LABEL,
+]
+
+// 80–100 chars is the guide; the ceiling is what a machine can enforce, so an overview sentence over
+// this many characters is the violation and the lower bound stays the writer's judgement.
+const MAX_OVERVIEW_CHARS = 100
+const ITEM_LINE_PREFIX = '- '
+// A file path (a slash segment, or a bare name with a source extension) or a long CLI flag — the
+// internal identifiers `report-format.md` bans from the overview. A function or type name cannot be
+// told from an ordinary word mechanically, so it is left to the judgement half.
+const PATH_SEGMENT_PATTERN = /[\w-]\/[\w-]/u
+const FILE_EXTENSION_PATTERN = /\.(?:ts|tsx|js|jsx|mjs|cjs|svelte|json|yaml|yml|css)\b/u
+const CLI_FLAG_PATTERN = /(?:^|\s)--[a-z]/u
+const BOLD_MARKER = '**'
+const LEADING_LABEL_PUNCTUATION = /^[\s:：]+/u
+
+// The case-based test declaration (joshuafolkken/kit#2246): the changes section carries a first tier
+// of fixed-vocabulary cases — each non-applicable one crossed out with a reason — and a second tier
+// of at-least-three "if it breaks" conditions. This checks the mechanical half: the two tier markers
+// are present, an N/A cross-out carries a reason, and the second tier holds enough conditions (or the
+// "never breaks" escape). Whether the cases are the right ones stays the judgement half.
+// `report-format.md` is the single source and the document test pins these against it.
+const CASE_LABEL = 'ケース'
+const CASE_VOCABULARY: ReadonlyArray<string> = [
+	'正常',
+	'空・0件',
+	'1件',
+	'多数',
+	'境界',
+	'不正入力',
+	'重複',
+	'順序',
+	'null',
+]
+const BREAK_LABEL = '壊れるとしたら'
+const NA_LABEL = '該当なし'
+const NO_BREAK_ESCAPE = 'どう呼ばれても壊れない'
+const MIN_BREAK_CONDITIONS = 3
+const LIST_ITEM_PATTERN = /^\s*(?:\d+\.|[-*])\s+/u
+const REASON_SEPARATORS = /^[\s:：—|、,.。-]+/u
+
+function first_content_line(summary: string): string {
+	return (
+		summary
+			.split('\n')
+			.find((line) => line.trim().length > 0)
+			?.trim() ?? ''
+	)
+}
+
+function is_fenced(summary: string): boolean {
+	return first_content_line(summary).startsWith('```')
+}
+
+function missing_labels(summary: string): ReadonlyArray<string> {
+	return REQUIRED_LABELS.filter((label) => !summary.includes(label))
+}
+
+function line_index_of(lines: ReadonlyArray<string>, label: string): number {
+	return lines.findIndex((line) => line.includes(label))
+}
+
+// The overview region is the lines between OVERVIEW_LABEL and DETAILS_LABEL; the length and intrusion
+// checks apply there alone, since the CHANGES_LABEL region legitimately carries file paths.
+function overview_lines(summary: string): ReadonlyArray<string> {
+	const lines = summary.split('\n')
+	const start = line_index_of(lines, OVERVIEW_LABEL)
+	if (start < 0) return []
+
+	const after = lines.slice(start + 1)
+	const end = line_index_of(after, DETAILS_LABEL)
+
+	return (end < 0 ? after : after.slice(0, end)).filter((line) => line.startsWith(ITEM_LINE_PREFIX))
+}
+
+// The sentence after `- **label**: ` — the text past the first bold pair's closing marker, with the
+// leading colon and spaces stripped. Only the label's own `**…**` is stripped, so inline emphasis
+// later in the sentence stays inside the checked text; a line with no bold pair falls back to `- `.
+function item_sentence(line: string): string {
+	const open = line.indexOf(BOLD_MARKER)
+	const close = open === -1 ? -1 : line.indexOf(BOLD_MARKER, open + BOLD_MARKER.length)
+	const raw =
+		close === -1 ? line.slice(ITEM_LINE_PREFIX.length) : line.slice(close + BOLD_MARKER.length)
+
+	return raw.replace(LEADING_LABEL_PUNCTUATION, '').trim()
+}
+
+function over_length_sentences(summary: string): ReadonlyArray<string> {
+	return overview_lines(summary)
+		.map((line) => item_sentence(line))
+		.filter((sentence) => sentence.length > MAX_OVERVIEW_CHARS)
+}
+
+function has_path_or_flag(sentence: string): boolean {
+	return (
+		PATH_SEGMENT_PATTERN.test(sentence) ||
+		FILE_EXTENSION_PATTERN.test(sentence) ||
+		CLI_FLAG_PATTERN.test(sentence)
+	)
+}
+
+function intruding_sentences(summary: string): ReadonlyArray<string> {
+	return overview_lines(summary)
+		.map((line) => item_sentence(line))
+		.filter((sentence) => has_path_or_flag(sentence))
+}
+
+function fence_violation(summary: string): ReadonlyArray<string> {
+	return is_fenced(summary)
+		? ['✖ the summary is wrapped in a code fence — write it as plain markdown']
+		: []
+}
+
+function label_violations(summary: string): ReadonlyArray<string> {
+	return missing_labels(summary).map((label) => `✖ missing label: ${label}`)
+}
+
+function length_violations(summary: string): ReadonlyArray<string> {
+	return over_length_sentences(summary).map(
+		(sentence) => `✖ overview line over ${String(MAX_OVERVIEW_CHARS)} chars: ${sentence}`,
+	)
+}
+
+function intrusion_violations(summary: string): ReadonlyArray<string> {
+	return intruding_sentences(summary).map(
+		(sentence) => `✖ file path or CLI flag in the overview: ${sentence}`,
+	)
+}
+
+// The changes region is every line after CHANGES_LABEL; the case checks apply there, since the two
+// tiers and their markers live under the changes section alone.
+function changes_region_lines(summary: string): ReadonlyArray<string> {
+	const lines = summary.split('\n')
+	const start = line_index_of(lines, CHANGES_LABEL)
+
+	return start < 0 ? [] : lines.slice(start + 1)
+}
+
+// The case checks run only when the section exists — a wholly missing section is already a missing
+// label, so gating here keeps one absence from printing as two violations.
+function has_changes_section(summary: string): boolean {
+	return summary.includes(CHANGES_LABEL)
+}
+
+// The text after the N/A marker in a segment, with separators stripped — empty means no reason given.
+function reason_after_na(segment: string): string {
+	return segment
+		.slice(segment.indexOf(NA_LABEL) + NA_LABEL.length)
+		.replace(REASON_SEPARATORS, '')
+		.trim()
+}
+
+// Cases are listed on one line separated by `/`, so each N/A cross-out is checked in its own segment
+// — a reasonless second cross-out on a line whose first one carries a reason must not escape.
+function line_has_reasonless_na(line: string): boolean {
+	return line
+		.split('/')
+		.some((segment) => segment.includes(NA_LABEL) && reason_after_na(segment).length === 0)
+}
+
+function na_lines_without_reason(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	return lines.filter((line) => line_has_reasonless_na(line))
+}
+
+function break_marker_index(lines: ReadonlyArray<string>): number {
+	return lines.findIndex((line) => line.includes(BREAK_LABEL))
+}
+
+// The count of list items after the second-tier marker. Over-counting a later change block's items
+// only relaxes the check, never fires a false violation, so the simple whole-tail count is enough.
+function break_condition_count(lines: ReadonlyArray<string>): number {
+	const start = break_marker_index(lines)
+	if (start < 0) return 0
+
+	return lines.slice(start + 1).filter((line) => LIST_ITEM_PATTERN.test(line)).length
+}
+
+function case_line_violations(summary: string): ReadonlyArray<string> {
+	if (!has_changes_section(summary)) return []
+	if (changes_region_lines(summary).some((line) => line.includes(CASE_LABEL))) return []
+
+	return [`✖ no case tier (${CASE_LABEL}:) in ${CHANGES_LABEL}`]
+}
+
+function na_reason_violations(summary: string): ReadonlyArray<string> {
+	if (!has_changes_section(summary)) return []
+
+	return na_lines_without_reason(changes_region_lines(summary)).map(
+		() => `✖ ${NA_LABEL} without a reason — say why the case does not apply`,
+	)
+}
+
+function break_violations(summary: string): ReadonlyArray<string> {
+	if (!has_changes_section(summary)) return []
+
+	const lines = changes_region_lines(summary)
+	if (lines.some((line) => line.includes(NO_BREAK_ESCAPE))) return []
+	if (break_marker_index(lines) < 0) return [`✖ no ${BREAK_LABEL} tier in ${CHANGES_LABEL}`]
+	if (break_condition_count(lines) >= MIN_BREAK_CONDITIONS) return []
+
+	return [
+		`✖ ${BREAK_LABEL} needs ${String(MIN_BREAK_CONDITIONS)} conditions or "${NO_BREAK_ESCAPE}"`,
+	]
+}
+
+// Every violation the mechanical checks find, in a fixed order; an empty array is a clean summary.
+function lint_report(summary: string): ReadonlyArray<string> {
+	return [
+		...fence_violation(summary),
+		...label_violations(summary),
+		...length_violations(summary),
+		...intrusion_violations(summary),
+		...case_line_violations(summary),
+		...na_reason_violations(summary),
+		...break_violations(summary),
+	]
+}
+
+const report_lint = {
+	lint_report,
+	REQUIRED_LABELS,
+	MAX_OVERVIEW_CHARS,
+	CASE_LABEL,
+	CASE_VOCABULARY,
+	BREAK_LABEL,
+	NA_LABEL,
+	NO_BREAK_ESCAPE,
+	MIN_BREAK_CONDITIONS,
+}
+
+export { report_lint }

package/scripts/retrospective/retrospective-cli.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { cost_run_report, type RunCostReport } from '#scripts/cost/cost-run-report'
+import { cost_run_tree } from '#scripts/cost/cost-run-tree'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { observation_ledger_line } from '#scripts/observations/observation-ledger-line'
+import { review_finding_ledger } from '#scripts/review/review-finding-ledger'
+import { run_carry } from '#scripts/run/run-carry'
+import { run_event_scope, type EventScope } from '#scripts/run/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+import { retrospective, type RetrospectiveInputs } from './retrospective'
+
+// `josh retrospective` — the end-of-run retrospective (joshuafolkken/kit#2328). It is the aggregation
+// half: it gathers the four measurements that already exist and prints the digest `retrospective.ts`
+// composes, so the retrospective step has one place to read the run it just finished. **When to run it
+// is the run driver's** — `run:step` prints it at the stop position, once per invocation — and **what to
+// file from it is `retrospective.md`'s**; this only reads and shapes.
+//
+// **Kit-only.** It reads kit's own development run — its transcript store, its review ledger, its event
+// stream — so it means nothing in a consumer project and is dropped from a consumer's help and refused
+// there, through the existing `is_kit_only` declaration rather than a new judgement.
+
+const SUCCESS_EXIT_CODE = 0
+// `read_from` returns every event past the given position, so zero is "the whole stream from the start".
+const STREAM_START = 0
+
+function read_cost(cwd: string): RunCostReport | undefined {
+	const tree = cost_run_tree.load(cwd, undefined)
+
+	if (tree === undefined) return undefined
+
+	return cost_run_report.build(tree.run_count, tree.unattributed_count, tree.nodes)
+}
+
+async function read_ledger(): Promise<string> {
+	try {
+		return await readFile(observation_ledger_home.ledger_path(), 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+function ledger_entries(content: string): Array<string> {
+	return content.split('\n').filter((line) => observation_ledger_line.is_ledger_entry_line(line))
+}
+
+interface RunRead {
+	events: ReadonlyArray<RunEvent>
+	scope: EventScope
+}
+
+// The stream and the scope that bounds it, read from the one directory the carry record and the event stream
+// share (joshuafolkken/kit#2395). The whole stream is read — `scoped_events` filters it to this invocation —
+// and an unresolvable directory has no record to scope with, which is the undetermined answer an absent
+// record gives.
+async function read_run(): Promise<RunRead> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return { events: [], scope: run_event_scope.UNKNOWN_EVENT_SCOPE }
+
+	const target = run_event_stream.target_of(directory)
+	const { events } = run_event_stream.read_from(target, STREAM_START)
+	const scope = run_event_scope.scope_of(run_carry.read_carry(run_carry.carry_path(directory)))
+
+	return { events, scope }
+}
+
+async function gather(cwd: string): Promise<RetrospectiveInputs> {
+	const ledger = await read_ledger()
+	const run_read = await read_run()
+
+	return {
+		cost: read_cost(cwd),
+		findings: review_finding_ledger.category_counts(ledger),
+		zero_rounds: review_finding_ledger.zero_round_count(ledger),
+		observations: ledger_entries(ledger),
+		events: run_read.events,
+		scope: run_read.scope,
+	}
+}
+
+async function run(cwd: string = process.cwd()): Promise<number> {
+	console.info(retrospective.compose(await gather(cwd)))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(): Promise<void> {
+	process.exitCode = await run()
+}
+
+const retrospective_cli = { gather, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { retrospective_cli }

package/scripts/retrospective/retrospective.ts

@@ -0,0 +1,127 @@
+import { cost_format } from '#scripts/cost-runtime/cost-format'
+import type { RunCostReport } from '#scripts/cost/cost-run-report'
+import type { RoleTotals } from '#scripts/cost/cost-run-roles'
+import type { CategoryCount } from '#scripts/review/review-finding-ledger'
+import { run_event_scope, type EventScope } from '#scripts/run/run-event-scope'
+import type { RunEvent } from '#scripts/run/run-event-stream'
+
+// The composition half of `josh retrospective` — the end-of-run retrospective's aggregation
+// (joshuafolkken/kit#2328). A run that drains its backlog has spent time and money that nobody reads;
+// this folds the four measurements that already exist — the run tree's cost and time
+// (`cost-run-report.ts`), the recurring review findings (`review-finding-ledger.ts`), the observation
+// ledger and the run's own event stream — into one digest, so the retrospective step has something to
+// weigh. It adds no new measurement, per the observation-filing rule against readerless numbers; every
+// input here is read from a command that was already keeping it.
+//
+// **It is a pure function of the four inputs.** The gathering — loading the run tree, reading the
+// ledger, opening the stream — is the CLI's; this shapes what they return and nothing else, so the
+// digest is unit-tested against fixed inputs rather than against a live store.
+
+const MS_PER_MINUTE = 60_000
+const PERCENT = 100
+// A role whose share of the run's wall clock runs this far ahead of its share of the cost is time the
+// run spent waiting rather than working — the disparity the retrospective exists to surface (the wake
+// role in the baseline sat at 52% of the time for 25% of the cost, a gap of 0.27).
+const WAITING_GAP = 0.2
+
+// The friction each event kind marks — a place the run did not run straight through — counted back
+// over the whole run. A plan, a child launch, a merge and a PR opening are the run working as intended,
+// so they are not friction and are left out.
+const FRICTION_KINDS = ['park', 'outage', 'cut', 'review-round'] as const
+
+interface RetrospectiveInputs {
+	cost: RunCostReport | undefined
+	findings: ReadonlyArray<CategoryCount>
+	zero_rounds: number
+	// The observation ledger's entry lines, already filtered to entries by the caller.
+	observations: ReadonlyArray<string>
+	events: ReadonlyArray<RunEvent>
+	// Which invocation the friction count covers (joshuafolkken/kit#2395). The stream is the repository's
+	// event log, not this run's, so a digest handed the whole of it would report a previous invocation's
+	// cut and park as this run's friction — the very numbers the retrospective weighs to file improvement
+	// issues. The scope is `run-event-scope.ts`'s, shared with `run:report` and `run:step`.
+	scope: EventScope
+}
+
+const CLOSING =
+	'Weigh these against retrospective.md: file the improvements worth carrying into the next run, and stack the rest in the observation ledger.'
+
+function minutes(ms: number): string {
+	return String(Math.round(ms / MS_PER_MINUTE))
+}
+
+function percent(share: number): string {
+	return `${String(Math.round(share * PERCENT))}%`
+}
+
+// A role's time share running ahead of its cost share is the run waiting rather than working, so it is
+// called out; a role that pays its way carries no note.
+function waiting_note(role: RoleTotals): string {
+	return role.elapsed_share - role.cost_share >= WAITING_GAP ? ' — waiting-heavy' : ''
+}
+
+function role_line(role: RoleTotals): string {
+	const spent = `${percent(role.cost_share)} cost, ${percent(role.elapsed_share)} time`
+
+	return `  ${role.role}: ${spent}${waiting_note(role)}`
+}
+
+function cost_lines(cost: RunCostReport | undefined): Array<string> {
+	if (cost === undefined) return ['Run cost & time: no run transcripts found']
+
+	const totals = `${String(cost.session_count)} session(s), ${minutes(cost.total_elapsed_ms)} min, ${cost_format.format_usd(cost.total_usd)}`
+
+	return [`Run cost & time: ${totals}`, ...cost.roles.map((role) => role_line(role))]
+}
+
+function findings_lines(
+	findings: ReadonlyArray<CategoryCount>,
+	zero_rounds: number,
+): Array<string> {
+	const denominator = `${String(zero_rounds)} zero-finding round(s)`
+
+	if (findings.length === 0) return [`Review findings: none recorded (${denominator})`]
+
+	const body = findings.map((entry) => `  ${entry.category}: ${String(entry.count)}`)
+
+	return [`Review findings (${denominator}):`, ...body]
+}
+
+function observation_lines(observations: ReadonlyArray<string>): Array<string> {
+	return [`Observation ledger: ${String(observations.length)} entry(ies) held`]
+}
+
+function friction_count(events: ReadonlyArray<RunEvent>, kind: string): number {
+	return events.filter((event) => event.kind === kind).length
+}
+
+// This invocation's friction, counted over its own events only. An undetermined scope falls to an empty
+// list rather than the whole stream (joshuafolkken/kit#2395): counting every invocation's friction as this
+// run's is the defect, so the safe fall is to attribute nothing that cannot be attributed.
+function friction_lines(events: ReadonlyArray<RunEvent>, scope: EventScope): Array<string> {
+	const scoped = run_event_scope.scoped_events(events, scope) ?? []
+	const counts = FRICTION_KINDS.map((kind) => `${kind} ${String(friction_count(scoped, kind))}`)
+
+	return [`Run events: ${counts.join(', ')}`]
+}
+
+// The four sections in a fixed order, separated by blank lines, closed by the pointer that hands the
+// judgement — which improvements are worth filing — to `retrospective.md`.
+function compose(inputs: RetrospectiveInputs): string {
+	return [
+		...cost_lines(inputs.cost),
+		'',
+		...findings_lines(inputs.findings, inputs.zero_rounds),
+		'',
+		...observation_lines(inputs.observations),
+		'',
+		...friction_lines(inputs.events, inputs.scope),
+		'',
+		CLOSING,
+	].join('\n')
+}
+
+const retrospective = { CLOSING, FRICTION_KINDS, WAITING_GAP, compose }
+
+export type { RetrospectiveInputs }
+export { retrospective }

package/scripts/review/disposition-cli.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { disposition } from './disposition-logic'
+
+// `josh disposition <path...>` — the machine half of the three-way review disposition
+// (joshuafolkken/kit#2181). It prints `runtime` when any named path reaches a runtime path — a
+// runtime code path, a distributed artifact a consumer reads, or the verification guarding either —
+// and `non-runtime` when every path is inert. `prompts/review.md` → "Three-way disposition after the
+// cap" leaves the run one judgement after this: whether the finding is a confirmed defect.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh disposition <path...>'
+const FAILURE_EXIT_CODE = 1
+
+function reason_line(paths: ReadonlyArray<string>): string {
+	const reaching = disposition.reaching_paths(paths)
+
+	return reaching.length === 0
+		? 'every path is inert — the finding cannot escape this repository'
+		: `reaches through: ${reaching.join(', ')}`
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	if (argv.length === 0) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	process.stdout.write(`${disposition.disposition_for(argv)}\n`)
+	process.stderr.write(`${reason_line(argv)}\n`)
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const disposition_cli = { USAGE, main, reason_line, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { disposition_cli }

package/scripts/review/disposition-logic.ts

@@ -0,0 +1,45 @@
+import { review_level } from './review-level'
+
+// Whether a review finding reaches a runtime path — the half of the three-way disposition a machine
+// can answer (joshuafolkken/kit#2181). `prompts/review.md` → "Three-way disposition after the cap"
+// routes a non-High finding to branch 2 (file it) only when it is a **confirmed defect that reaches a
+// runtime code path**. "Reaches" is read exactly as the review-level rubric reads it — a runtime code
+// path, a distributed artifact a consumer reads, or the verification guarding either — which is the
+// same question `review-level.ts`'s inert set answers by its complement.
+//
+// **The classifier is shared, not copied.** `is_inert` is the single source of "cannot escape this
+// repository", and this reuses it rather than re-listing the paths — a distinct answer from
+// `test-declared-logic.ts`'s `EXEMPT_*`, which asks whether an automated test could have caught the
+// defect and so keeps documentation exempt. Disposition asks whether the finding escapes, and a
+// distributed document does; that is why it shares the inert set and not the exempt one
+// (decision recorded on the issue, 2026-09-21).
+
+type Disposition = 'runtime' | 'non-runtime'
+
+const RUNTIME: Disposition = 'runtime'
+const NON_RUNTIME: Disposition = 'non-runtime'
+
+// A finding reaches a runtime path when any path it touches is non-inert. Every path inert means the
+// finding cannot escape — `non-runtime`. No path at all takes `runtime`, the file-eligible answer, for
+// the same reason `level_for` gives an empty diff the default level: a caller that failed to read the
+// finding's paths must not be handed the drop-eligible verdict as though it had.
+function disposition_for(paths: ReadonlyArray<string>): Disposition {
+	const named = paths.map((path) => path.trim()).filter((path) => path !== '')
+
+	if (named.length === 0) return RUNTIME
+
+	return named.every((path) => review_level.is_inert(path)) ? NON_RUNTIME : RUNTIME
+}
+
+// The non-inert paths that made the finding reach — so the answer can say why, mirroring
+// `review_level.deciding_paths`.
+function reaching_paths(paths: ReadonlyArray<string>): Array<string> {
+	return paths
+		.map((path) => path.trim())
+		.filter((path) => path !== '' && !review_level.is_inert(path))
+}
+
+const disposition = { NON_RUNTIME, RUNTIME, disposition_for, reaching_paths }
+
+export type { Disposition }
+export { disposition }

package/scripts/review/live-evidence.ts

@@ -0,0 +1,62 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { reproduction_measure } from '#scripts/issue/reproduction-measure'
+import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-logic'
+
+// joshuafolkken/kit#2446. "Done" meant lint, types and unit tests were green and the review found
+// nothing — proof the code is right in isolation, never that the feature works where it runs. The
+// recent defects (#2402, #2419, #2393) all came through that gap. **This is the seam where it closes**:
+// a runtime change merges only once its pull request carries the acceptance criteria run for real —
+// the command and the output it actually printed, in the evidence section `EVIDENCE_HEADING` names.
+//
+// **Two single sources, no new judgement.** Which change needs evidence is `josh test:declared`'s
+// runtime-path classification, read against the branch diff rather than the working tree (a followup
+// runs after the commit, when `git status` is empty). What counts as evidence is `issue:lint`'s
+// reproduction-section parser, so a prose "confirmed it works" is refused here exactly as it is there.
+
+const EVIDENCE_HEADING = '## 実機証跡'
+
+function verdict_for(paths: ReadonlyArray<string>, body: string | undefined): Verdict {
+	if (test_declared_logic.runtime_files(paths).length === 0) return 'exempt'
+
+	return reproduction_measure.has_command_output(body ?? '', EVIDENCE_HEADING)
+		? 'satisfied'
+		: 'required'
+}
+
+// The diff is this checkout's, so it answers for the named branch only when that is the one checked
+// out: a `followup --branch <lane>` run from `main` would read an empty diff as `exempt` and merge a
+// runtime change with no evidence. Refused rather than guessed.
+async function assert_checked_out(branch_name: string): Promise<void> {
+	const current = await git_command.branch()
+
+	if (current === branch_name) return
+
+	throw new Error(
+		`The ${EVIDENCE_HEADING} check reads this checkout's diff, which is ${current}, not ${branch_name}; run followup from ${branch_name}'s checkout.`,
+	)
+}
+
+async function check(branch_name: string): Promise<Verdict> {
+	await assert_checked_out(branch_name)
+
+	const [names, body] = await Promise.all([
+		git_command.diff_main_names(),
+		git_gh_command.pr_get_body(branch_name),
+	])
+
+	return verdict_for(names.split('\n'), body)
+}
+
+function refusal_message(): string {
+	return [
+		`Merge refused: this pull request changes runtime code but its body has no ${EVIDENCE_HEADING} section.`,
+		'Run the acceptance criteria for real, then add the section: a backticked command followed by a',
+		'fenced block holding the output it actually printed (prose such as "confirmed" is not accepted).',
+		'Update the body with `gh api -X PATCH repos/{owner}/{repo}/pulls/<N> -F body=@<path>`, then re-run.',
+	].join('\n')
+}
+
+const live_evidence = { EVIDENCE_HEADING, check, refusal_message, verdict_for }
+
+export { live_evidence }