@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/lint/rename-identifier.ts

@@ -0,0 +1,192 @@
+import type ts from 'typescript'
+
+// The rewrite behind `josh rename` (joshuafolkken/kit#5236): one identifier and, optionally, one import
+// specifier, renamed through the TypeScript parse tree rather than a pattern.
+//
+// **Only a binding is renamed, never a key.** `obj.old`, `{ old: 1 }` and `{ old: x } = obj` name a
+// property of some other value, so they stay; a shorthand `{ old }` keeps its key and becomes
+// `{ old: new }`. Strings and comments are not identifiers to the parser, so the walk never reaches
+// them — a specifier is rewritten only where the module system reads it.
+
+type TypeScriptApi = typeof ts
+
+interface RenameRequest {
+	old_name: string
+	new_name: string
+	specifier?: readonly [string, string] | undefined
+}
+
+interface Replacement {
+	start: number
+	end: number
+	text: string
+}
+
+// `is_taken`: the new name is already a binding here, so the rename could shadow or merge with it —
+// the rename matches by spelling, not by scope.
+interface RenameResult {
+	text: string
+	count: number
+	is_taken: boolean
+}
+
+// Calls whose first argument is a module specifier the test runner resolves like an import.
+const MODULE_CALLS: ReadonlySet<string> = new Set([
+	'vi.mock',
+	'vi.doMock',
+	'vi.importActual',
+	'vi.importMock',
+])
+const NAME_KEY = 'name'
+
+// The parents whose `name` is a property key rather than a binding.
+function key_parent_kinds(api: TypeScriptApi): ReadonlySet<ts.SyntaxKind> {
+	const kind = api.SyntaxKind
+
+	return new Set([
+		kind.PropertyAccessExpression,
+		kind.PropertyAssignment,
+		kind.PropertyDeclaration,
+		kind.PropertySignature,
+		kind.MethodDeclaration,
+		kind.MethodSignature,
+		kind.GetAccessor,
+		kind.SetAccessor,
+		kind.EnumMember,
+		kind.JsxAttribute,
+	])
+}
+
+function is_key_position(api: TypeScriptApi, node: ts.Identifier): boolean {
+	const { parent } = node
+
+	if (api.isQualifiedName(parent)) return parent.right === node
+	if (api.isBindingElement(parent)) return parent.propertyName === node
+
+	return key_parent_kinds(api).has(parent.kind) && Reflect.get(parent, NAME_KEY) === node
+}
+
+// A shorthand key is also the property's name, so the key is spelled out to keep it.
+function keeps_key(api: TypeScriptApi, node: ts.Identifier): boolean {
+	const { parent } = node
+
+	if (api.isShorthandPropertyAssignment(parent)) return true
+
+	return (
+		api.isBindingElement(parent) &&
+		parent.propertyName === undefined &&
+		parent.dotDotDotToken === undefined &&
+		api.isObjectBindingPattern(parent.parent)
+	)
+}
+
+function identifier_replacement(
+	api: TypeScriptApi,
+	node: ts.Identifier,
+	request: RenameRequest,
+): Replacement | undefined {
+	if (node.text !== request.old_name || is_key_position(api, node)) return undefined
+	const text = keeps_key(api, node) ? `${node.text}: ${request.new_name}` : request.new_name
+
+	return { start: node.getStart(), end: node.getEnd(), text }
+}
+
+function is_module_call(
+	api: TypeScriptApi,
+	call: ts.CallExpression,
+	node: ts.StringLiteral,
+): boolean {
+	if (call.arguments.indexOf(node) !== 0) return false
+
+	return (
+		call.expression.kind === api.SyntaxKind.ImportKeyword ||
+		MODULE_CALLS.has(call.expression.getText())
+	)
+}
+
+function is_module_specifier(api: TypeScriptApi, node: ts.StringLiteral): boolean {
+	const { parent } = node
+
+	if (api.isImportDeclaration(parent) || api.isExportDeclaration(parent)) {
+		return parent.moduleSpecifier === node
+	}
+
+	if (api.isCallExpression(parent)) return is_module_call(api, parent, node)
+
+	return api.isLiteralTypeNode(parent) && api.isImportTypeNode(parent.parent)
+}
+
+function specifier_replacement(
+	api: TypeScriptApi,
+	node: ts.StringLiteral,
+	specifier: RenameRequest['specifier'],
+): Replacement | undefined {
+	if (specifier?.[0] !== node.text || !is_module_specifier(api, node)) return undefined
+	const start = node.getStart()
+	const quote = node.getSourceFile().text.charAt(start)
+
+	return { start, end: node.getEnd(), text: `${quote}${specifier[1]}${quote}` }
+}
+
+function replacement_at(
+	api: TypeScriptApi,
+	node: ts.Node,
+	request: RenameRequest,
+): Replacement | undefined {
+	if (api.isIdentifier(node)) return identifier_replacement(api, node, request)
+	if (api.isStringLiteral(node)) return specifier_replacement(api, node, request.specifier)
+
+	return undefined
+}
+
+// `forEachChild` never descends into JSDoc, so a name inside a doc comment stays as written.
+function collect(
+	api: TypeScriptApi,
+	node: ts.Node,
+	request: RenameRequest,
+	into: Array<Replacement>,
+): void {
+	const replacement = replacement_at(api, node, request)
+
+	if (replacement !== undefined) into.push(replacement)
+	api.forEachChild(node, (child) => {
+		collect(api, child, request, into)
+	})
+}
+
+// Applied from the end of the file backwards, so an earlier offset is never moved by a later edit.
+function apply(text: string, replacements: ReadonlyArray<Replacement>): string {
+	const backwards = replacements.toSorted((first, second) => second.start - first.start)
+	let result = text
+
+	for (const edit of backwards) {
+		result = `${result.slice(0, edit.start)}${edit.text}${result.slice(edit.end)}`
+	}
+
+	return result
+}
+
+function rewrite(
+	api: TypeScriptApi,
+	file_name: string,
+	text: string,
+	request: RenameRequest,
+): RenameResult {
+	const source = api.createSourceFile(file_name, text, api.ScriptTarget.Latest, true)
+	const replacements: Array<Replacement> = []
+	const existing: Array<Replacement> = []
+
+	collect(api, source, request, replacements)
+	collect(api, source, { old_name: request.new_name, new_name: request.new_name }, existing)
+
+	return {
+		text: apply(text, replacements),
+		count: replacements.length,
+		is_taken: existing.length > 0,
+	}
+}
+
+const rename_identifier = { rewrite }
+
+export type { RenameRequest, RenameResult, TypeScriptApi }
+export { rename_identifier }

package/scripts/lint/type-only-imports.ts

@@ -0,0 +1,58 @@
+import type ts from 'typescript'
+
+// The module specifiers a file names only for their types: an `import type` or an
+// `export type … from` declaration, which the transpiler drops whole, so the test runner's module graph
+// never holds the edge (joshuafolkken/kit#5368). An `import { type A }` is left out: under
+// `verbatimModuleSyntax` it stays as a side-effect import. A declaration is matched to the reference
+// `preProcessFile` reports by where its specifier sits, never by its text, so a value import of the
+// same module keeps its edge whichever declarations `preProcessFile` lists.
+type TypeScript = typeof ts
+type ModuleDeclaration = ts.ImportDeclaration | ts.ExportDeclaration
+
+function declaration_of(
+	typescript: TypeScript,
+	statement: ts.Statement,
+): ModuleDeclaration | undefined {
+	if (typescript.isImportDeclaration(statement)) return statement
+	if (typescript.isExportDeclaration(statement)) return statement
+
+	return undefined
+}
+
+function is_type_only(typescript: TypeScript, declaration: ModuleDeclaration): boolean {
+	if (typescript.isExportDeclaration(declaration)) return declaration.isTypeOnly
+
+	return declaration.importClause?.phaseModifier === typescript.SyntaxKind.TypeKeyword
+}
+
+// Where the specifier's literal starts, its opening quote — the `pos` `preProcessFile` reports.
+function type_only_position(
+	typescript: TypeScript,
+	source: ts.SourceFile,
+	statement: ts.Statement,
+): number | undefined {
+	const declaration = declaration_of(typescript, statement)
+	if (declaration === undefined || !is_type_only(typescript, declaration)) return undefined
+	const specifier = declaration.moduleSpecifier
+	if (specifier === undefined || !typescript.isStringLiteral(specifier)) return undefined
+
+	return specifier.getStart(source)
+}
+
+// The specifiers `preProcessFile` finds less the type-only declarations': the edges the test runner
+// follows.
+function runtime_specifiers(typescript: TypeScript, file: string, content: string): Array<string> {
+	const source = typescript.createSourceFile(file, content, typescript.ScriptTarget.Latest)
+	const type_only = new Set(
+		source.statements.map((statement) => type_only_position(typescript, source, statement)),
+	)
+
+	return typescript
+		.preProcessFile(content, true, true)
+		.importedFiles.filter((reference) => !type_only.has(reference.pos))
+		.map((reference) => reference.fileName)
+}
+
+const type_only_imports = { runtime_specifiers }
+
+export { type_only_imports }

package/scripts/notify/telegram-notify.ts

@@ -1,5 +1,6 @@
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { timed_fetch } from '#scripts/lib/timed-fetch'
+import { token_shape } from '#scripts/lib/token-shape'
 import { z } from 'zod'
 import { confirmation_options, type ConfirmationOptions } from './confirmation-options'
 import { notify_opt_in } from './notify-opt-in'
@@ -230,6 +231,14 @@ function build_text(input: TelegramSendInput): string {
 	return join_blocks({ ...input, body: `${head_of(input.body, kept)}${BODY_TRUNCATION_MARK}` })
 }
 
+// The text to send, refused when it holds a credential: the whole text is read, before the cut could
+// leave a head no shape matches.
+function outbound_text(input: TelegramSendInput): string {
+	token_shape.refuse(join_blocks(input), 'The Telegram message')
+
+	return build_text(input)
+}
+
 async function post_message(config: TelegramConfig, text: string): Promise<void> {
 	const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`
 	const response = await timed_fetch(url, {
@@ -271,7 +280,7 @@ async function send(input: TelegramSendInput): Promise<void> {
 	}
 
 	const config = load_config()
-	const text = build_text(input)
+	const text = outbound_text(input)
 
 	try {
 		await post_message(config, text)
@@ -283,7 +292,7 @@ async function send(input: TelegramSendInput): Promise<void> {
 }
 
 // **The tolerant form**, for a caller whose job is something other than the notification.
-// `followup` sends the completion message on its way to the merge, and a gateway timeout at
+// `followup` sends the completion message beside the merge, and a gateway timeout at
 // Telegram is not a reason to leave a reviewed, green pull request unmerged. So the failure is
 // reported and the run carries on.
 //
@@ -298,7 +307,7 @@ async function send(input: TelegramSendInput): Promise<void> {
 //
 // **Not routed through `git_followup_cleanup`**, which is that Issue's mechanism: it guards the
 // steps a merge has already earned and says "failed after the merge" in its own wording, while this
-// send happens *before* the merge. Borrowing it would print a sentence that is not true.
+// send never happens *after* the merge. Borrowing it would print a sentence that is not true.
 function report_send_failure(error: unknown, recovery: string | undefined): void {
 	console.error('')
 	console.error(`❗ ${describe_symptom(error)}`)

package/scripts/observations/observation-record.ts

@@ -31,17 +31,32 @@ interface RecordRequest {
 	now: Date
 }
 
-type RecordResult =
-	| { verdict: typeof REFUSED_VERDICT; reason: string }
-	| {
-			verdict: typeof FILE_VERDICT | typeof LEDGER_VERDICT
-			earlier: ReadonlyArray<string>
-			line: string
-			target: string
-	  }
+interface Refusal {
+	verdict: typeof REFUSED_VERDICT
+	reason: string
+}
+
+interface Assessment {
+	verdict: typeof FILE_VERDICT | typeof LEDGER_VERDICT
+	earlier: ReadonlyArray<string>
+	line: string
+}
+
+type AssessResult = Refusal | Assessment
+
+type RecordResult = Refusal | (Assessment & { target: string })
+
+// Prettier's markdown pass collapses a whitespace run in a list item (only the whitespace is settled
+// here; emphasis markers in a field are not), so a line keeping one (vitest's
+// padded test names, joshuafolkken/kit#5303) fails a later gate's style check on a file it never wrote.
+// Collapsed before the grammar check, so whitespace around a `|` that Prettier would turn into a
+// separator is refused like a `|` already standing as one.
+function collapsed(field: string): string {
+	return field.replaceAll(/\s+/gu, ' ').trim()
+}
 
 function entry_line(entry: ObservationEntry, date: string): string {
-	return `- k:${entry.slug} | ${entry.depth} | ${date} | ${entry.where} | ${entry.what}`
+	return `- k:${entry.slug} | ${entry.depth} | ${date} | ${collapsed(entry.where)} | ${collapsed(entry.what)}`
 }
 
 function refusal_of(entry: ObservationEntry, line: string): string | undefined {
@@ -58,8 +73,9 @@ function sightings(ledger: string | undefined, slug: string): ReadonlyArray<stri
 	return (ledger ?? '').split('\n').filter((line) => line.startsWith(prefix))
 }
 
-// The count is read before the append, so it is the sightings *before* this one.
-async function record(request: RecordRequest): Promise<RecordResult> {
+// The line, the earlier sightings and the verdict, with nothing appended — for a caller that keeps the
+// line somewhere other than the tree (`followup-failed-tests.ts` posts it on the issue).
+async function assess(request: RecordRequest): Promise<AssessResult> {
 	const date = observation_ledger_home.ledger_date(request.now)
 	const line = entry_line(request.entry, date)
 	const reason = refusal_of(request.entry, line)
@@ -70,22 +86,32 @@ async function record(request: RecordRequest): Promise<RecordResult> {
 		await observation_ledger_home.read(request.checkout),
 		request.entry.slug,
 	)
-	const target = await observation_ledger_home.writer_path(request.now, request.checkout)
+	const verdict = earlier.length === PROMOTING_COUNT ? FILE_VERDICT : LEDGER_VERDICT
 
-	await observation_ledger_home.append(target, [line])
+	return { verdict, earlier, line }
+}
 
-	const verdict = earlier.length === PROMOTING_COUNT ? FILE_VERDICT : LEDGER_VERDICT
+// The count is read before the append, so it is the sightings *before* this one.
+async function record(request: RecordRequest): Promise<RecordResult> {
+	const assessment = await assess(request)
+
+	if (assessment.verdict === REFUSED_VERDICT) return assessment
+
+	const target = await observation_ledger_home.writer_path(request.now, request.checkout)
+
+	await observation_ledger_home.append(target, [assessment.line])
 
-	return { verdict, earlier, line, target }
+	return { ...assessment, target }
 }
 
-const observation_record = { record }
+const observation_record = { assess, record }
 
 export {
 	FILE_VERDICT,
 	LEDGER_VERDICT,
 	observation_record,
 	REFUSED_VERDICT,
+	type AssessResult,
 	type ObservationEntry,
 	type RecordResult,
 }

package/scripts/observations/observations-flush.ts

@@ -3,6 +3,7 @@ import { git_command } from '#scripts/git/git-command'
 import { main_sync } from '#scripts/git/main-sync'
 import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { error_text } from '#scripts/lib/error-message'
+import { review_comment_carry } from '#scripts/review/review-comment-carry'
 import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
 import type { BrokenLine } from './observation-ledger-line'
 import { observation_ledger_prepare } from './observation-ledger-prepare'
@@ -12,7 +13,8 @@ import { observations_flush_landing } from './observations-flush-landing'
 // a lane's included — commits its appended lines with its own pull request (`scripts/git/
 // git-staging.ts`), and `pnpm josh followup` commits a
 // line appended after that commit before it merges, so what is left here is a line written on the
-// default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves.
+// default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves —
+// and the closed issues' comment rounds no lane carries (`flush` below).
 //
 // **The shape is `scripts/release/release-publish.ts`'s, deliberately.** Both open a pull request of
 // their own over one path, wait on the same required checks every other pull request waits on, and
@@ -393,6 +395,27 @@ async function prepare_ledger(): Promise<void> {
 	if (broken.length > 0) throw new Error(broken_lines_message(broken))
 }
 
+// The checkout made safe and caught up: a carried file an earlier flush left uncommitted is discarded
+// first, since it would make git refuse the fast-forward (`review-comment-carry.ts`).
+async function ready_default_branch(status_output: string): Promise<string> {
+	const default_branch = await refuse_unsafe_flush(status_output)
+
+	review_comment_carry.discard_uncommitted(status_output, process.cwd())
+	await catch_up_default(default_branch)
+
+	return default_branch
+}
+
+// **The closed issues' comment rounds are carried only once a flush will go ahead**
+// (joshuafolkken/kit#5326): a lane child leaves them to this flush, so the carried files ride its pull
+// request, and the status is read again so a carry alone is a change to flush. A carry left behind by
+// a later stop is discarded by the next flush's `ready_default_branch`.
+async function carried_status(): Promise<string> {
+	await review_comment_carry.carry_reported(process.cwd())
+
+	return await git_command.status()
+}
+
 // **Nothing pulls in front of the branch, and that is deliberate.** The ledger is dirty by
 // definition at this point, so `git pull --ff-only` aborts on it in exactly the case a pull would
 // have been for — an upstream flush that already advanced the ledger — and reports a failure about
@@ -401,19 +424,19 @@ async function prepare_ledger(): Promise<void> {
 // only where git can do it without touching the ledger: a default branch
 // that predates another merged flush still stops here — before a branch is cut — rather than opening
 // a pull request that cannot merge. An earlier flush pull request still open is checked for the same
-// reason: a branch cut beside it conflicts with it at the ledger's tail.
+// reason: a branch cut beside it conflicts with it at the ledger's tail. So the order is: ready the
+// default branch, defer to an open flush, carry, then check, prepare and land.
 async function flush(now: Date): Promise<string> {
-	const status_output = await git_command.status()
-	const default_branch = await refuse_unsafe_flush(status_output)
-
-	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
-
-	await prepare_ledger()
+	const default_branch = await ready_default_branch(await git_command.status())
 
 	const deferred = await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX)
 	if (deferred !== undefined) return deferred
 
-	await catch_up_default(default_branch)
+	const status_output = await carried_status()
+
+	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
+
+	await prepare_ledger()
 
 	const branch_name = branch_name_for(timestamp_for(now))
 

package/scripts/overrides/overrides-check.ts

@@ -13,6 +13,7 @@ import { fileURLToPath } from 'node:url'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { file_reader } from '#scripts/lib/read-file'
 import { overrides_snapshot_schema } from '#scripts/lib/schemas'
+import { development_engines_verdict } from '#scripts/version/development-engines-verdict'
 import { overrides_files } from './overrides-files'
 import { overrides_check, type OverridesDiff } from './overrides-logic'
 
@@ -71,6 +72,13 @@ function run_overrides_check(should_save: boolean): void {
 	console.info(`✔ overrides unchanged (${summary}).`)
 }
 
+// The `devEngines` verdict rides on every check, whatever the overrides answer, so it is printed
+// before the overrides comparison can exit.
+function run_check(should_save: boolean): void {
+	development_engines_verdict.report()
+	run_overrides_check(should_save)
+}
+
 // A line nobody can read is refused before the snapshot is read or written: a misspelled `--save` that
 // fell through would compare against the record the caller meant to replace.
 function refuse_usage(): never {
@@ -83,7 +91,7 @@ function main(argv: ReadonlyArray<string>): void {
 	const values = cli_flags.values_of(argv, OPTIONS)
 
 	if (values === undefined) refuse_usage()
-	run_overrides_check(values.save)
+	run_check(values.save)
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))

package/scripts/release/release-approval-prune.ts

@@ -8,11 +8,17 @@ import { git_spawn } from '#scripts/git/git-spawn'
 // no verdict. `--ignore-unmatch` makes a repository with no approvals a no-op.
 
 const APPROVAL_DIRECTORY = '.josh/metrics-accepted'
+const APPROVAL_PREFIX = `${APPROVAL_DIRECTORY}/`
 
 async function prune(): Promise<void> {
 	await git_spawn.read(['rm', '-r', '-q', '--ignore-unmatch', '--', APPROVAL_DIRECTORY])
 }
 
-const release_approval_prune = { APPROVAL_DIRECTORY, prune }
+// A repository-relative path under the approval directory.
+function is_approval(file: string): boolean {
+	return file.startsWith(APPROVAL_PREFIX)
+}
+
+const release_approval_prune = { APPROVAL_DIRECTORY, is_approval, prune }
 
 export { release_approval_prune }

package/scripts/repo/required-checks-logic.ts

@@ -22,7 +22,10 @@ const REQUIRED_STATUS_CHECKS = 'required_status_checks'
 const NOT_FOUND_STATUS = 404
 
 const DISTRIBUTED_CHECKS: ReadonlyArray<WorkflowChecks> = [
-	{ workflow: CI_WORKFLOW, checks: ['Checks', 'Detect E2E', 'E2E', 'Security Audit'] },
+	{
+		workflow: CI_WORKFLOW,
+		checks: ['Checks', 'Detect E2E', 'E2E', 'Secret Scan', 'Security Audit'],
+	},
 	{ workflow: SONAR_WORKFLOW, checks: ['SonarQube'] },
 	{ workflow: CLASSIFICATION_WORKFLOW, checks: ['Release classification'] },
 ]

package/scripts/repo/ruleset-check.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { gh_failure } from '#scripts/gh/git-gh-failure'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
@@ -37,7 +38,7 @@ function read_default_branch(repo: string): string | undefined {
 function read_protection(repo: string, branch: string): ApiRead {
 	try {
 		const stdout = git_gh_exec.exec_gh_api_sync({
-			path: `repos/${repo}/branches/${branch}/protection/required_status_checks`,
+			path: git_gh_api_path.branch_protection_checks_api_path(branch, repo),
 			cwd: PROJECT_ROOT,
 			timeout_ms: repo_setting.GH_TIMEOUT_MS,
 		})
@@ -52,7 +53,7 @@ function read_protection(repo: string, branch: string): ApiRead {
 // there rather than letting protection alone pass for the whole answer.
 function read_source(repo: string, branch: string): RequiredSource {
 	const from_rules = required_checks_logic.parse_branch_rules(
-		read_api(`repos/${repo}/rules/branches/${branch}`),
+		read_api(git_gh_api_path.branch_rules_api_path(branch, repo)),
 	)
 	if (from_rules.kind === 'unreadable') return from_rules
 	const from_protection = required_checks_logic.parse_protection(read_protection(repo, branch))
@@ -95,7 +96,7 @@ function apply_to_ruleset(repo: string, ruleset_id: number, missing: ReadonlyArr
 
 function apply_to_protection(repo: string, branch: string, missing: ReadonlyArray<string>): void {
 	git_gh_exec.exec_gh_api_sync({
-		path: `repos/${repo}/branches/${branch}/protection/required_status_checks/contexts`,
+		path: `${git_gh_api_path.branch_protection_checks_api_path(branch, repo)}/contexts`,
 		method: 'POST',
 		body: required_checks_logic.protection_update_body(missing),
 		cwd: PROJECT_ROOT,

package/scripts/report/markdown-shape.ts

@@ -0,0 +1,28 @@
+// The shape checks the fixed-shape linters share — `report:lint`, its `--child-summary` mode and
+// `review:lint` — kept in one place so the fence rule and the line count read the same in all three.
+
+const FENCE_MARKER = '```'
+
+// The non-blank lines: what a line bound counts and what the first-line checks read.
+function content_lines(text: string): ReadonlyArray<string> {
+	return text.split('\n').filter((line) => line.trim().length > 0)
+}
+
+function first_content_line(text: string): string {
+	return content_lines(text)[0]?.trim() ?? ''
+}
+
+function is_fenced(text: string): boolean {
+	return first_content_line(text).startsWith(FENCE_MARKER)
+}
+
+// `subject` names the artifact in the message: `summary`, `review`.
+function fence_violation(text: string, subject: string): ReadonlyArray<string> {
+	return is_fenced(text)
+		? [`✖ the ${subject} is wrapped in a code fence — write it as plain markdown`]
+		: []
+}
+
+const markdown_shape = { content_lines, first_content_line, fence_violation }
+
+export { markdown_shape }

package/scripts/report/report-format-reference.ts

@@ -10,15 +10,29 @@ const SUMMARY_TEMPLATE_HEADING = '作業前サマリ（セッション向け・`
 const COMPLETION_REPORT_HEADING = '完了報告（セッション向け）'
 const ACCEPTANCE_MAP_HEADING = 'PR 本文の受け入れ条件の対応表'
 const REMOVED_TESTS_HEADING = 'PR 本文の消えたテストの処置'
+// The lane child's summary is shaped in the backlogrun child's document, not in `report-format.md`.
+const CHILD_SUMMARY_PATH = '.claude/skills/workflow-commands/backlogrun-child.md'
+const CHILD_SUMMARY_HEADING = 'What the summary carries, and how long it may be'
 
 // The heading goes in single quotes in the runnable form: the template heading carries backticks,
 // which a double-quoted shell argument would run as a command substitution.
+function section_pointer(path: string, heading: string): string {
+	return `${path} → "${heading}" (read it: pnpm josh doc:section ${path} '${heading}')`
+}
+
 function pointer(heading: string): string {
-	return `${REPORT_FORMAT_PATH} → "${heading}" (read it: pnpm josh doc:section ${REPORT_FORMAT_PATH} '${heading}')`
+	return section_pointer(REPORT_FORMAT_PATH, heading)
+}
+
+function child_summary_pointer(): string {
+	return section_pointer(CHILD_SUMMARY_PATH, CHILD_SUMMARY_HEADING)
 }
 
 const report_format_reference = {
 	ACCEPTANCE_MAP_HEADING,
+	CHILD_SUMMARY_HEADING,
+	CHILD_SUMMARY_PATH,
+	child_summary_pointer,
 	COMPLETION_REPORT_HEADING,
 	pointer,
 	REMOVED_TESTS_HEADING,

package/scripts/report/report-labels.ts

@@ -141,6 +141,11 @@ const ENGLISH_LABELS: ReportLabels = {
 	handoff: ENGLISH_HANDOFF_LABELS,
 }
 
+// A lane child's summary holds at most this many non-blank lines — the bound
+// `backlogrun-child.md` → "What the summary carries, and how long it may be" states and
+// `report:lint --child-summary` checks, beside the `cause` / `fix` / `result` labels above.
+const CHILD_SUMMARY_MAX_LINES = 25
+
 function labels_for(lang: string): ReportLabels {
 	return session_language.is_japanese(lang) ? JAPANESE_LABELS : ENGLISH_LABELS
 }
@@ -149,7 +154,13 @@ function session_labels(): ReportLabels {
 	return labels_for(session_language.resolve_session_lang().lang)
 }
 
-const report_labels = { ENGLISH_LABELS, JAPANESE_LABELS, labels_for, session_labels }
+const report_labels = {
+	CHILD_SUMMARY_MAX_LINES,
+	ENGLISH_LABELS,
+	JAPANESE_LABELS,
+	labels_for,
+	session_labels,
+}
 
 export type { HandoffLabels, ReportLabels }
 export { report_labels }