@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/release/release-publish-run.ts

@@ -0,0 +1,39 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { json_value } from '#scripts/lib/json-value'
+import { github_release_runs, type RunSource } from './github-release-runs'
+import { release_tag } from './release-tag'
+
+// The tag's Publish run as `pnpm josh release` sees it through `gh`, so the npm wait can end the
+// moment that run fails instead of waiting out its timeout for a version that will never appear.
+
+const PUBLISH_WORKFLOW = 'publish.yml'
+
+function gh_run_source(): RunSource {
+	return {
+		read: async (api_path) =>
+			json_value.parse_or_undefined(
+				await git_gh_exec.exec_gh_api({ path: `${git_gh_api_path.repo_api_path()}${api_path}` }),
+			),
+		workflow: PUBLISH_WORKFLOW,
+		jobs: [],
+		release_run_workflow: undefined,
+	}
+}
+
+// A repository without the workflow, or a read that fails, tells nothing about the run, so the npm
+// wait goes on as it did before the run was asked about.
+async function failed_run_id(version: string): Promise<number | undefined> {
+	try {
+		const tag = release_tag.tag_name(version)
+		const run = await github_release_runs.publish_run(gh_run_source(), PUBLISH_WORKFLOW, tag)
+
+		return run && github_release_runs.run_state(run) === 'failed' ? run.id : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const release_publish_run = { failed_run_id }
+
+export { release_publish_run }

package/scripts/release/release-publish.ts

@@ -1,10 +1,12 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { git_pr_checks } from '#scripts/gh/git-pr-checks'
+import { git_pr_merge_checked } from '#scripts/gh/git-pr-merge-checked'
 import { git_command } from '#scripts/git/git-command'
 import { git_remote_branch } from '#scripts/git/git-remote-branch'
 import { repository_lock } from '#scripts/git/repository-lock'
+import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { write_version } from '#scripts/version/bump-version'
-import { version_targets } from '#scripts/version/version-targets'
+import { release_approval_prune } from './release-approval-prune'
 import { release_issue_close } from './release-issue-close'
 import type { ReleasePlan } from './release-plan'
 import { release_progress } from './release-progress'
@@ -19,10 +21,8 @@ import { release_worktree } from './release-worktree'
 // weakening it for a release commit would open exactly the "merge without green CI" path the issue's
 // closing note prohibits.
 
-const { PACKAGE_JSON } = version_targets
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const IGNORE_FOR_RELEASE_LABEL = 'ignore-for-release'
 const RELEASE_LOCK_PREFIX = 'josh-release-lock-'
 // A release waits on CI for minutes, so a second run refuses rather than queueing behind it.
 const RELEASE_LOCK_MAX_WAIT_MS = 0
@@ -109,6 +109,7 @@ async function clear_the_way(branch_name: string): Promise<void> {
 async function commit_release(plan: ReleasePlan): Promise<string> {
 	write_version(plan.next_version)
 	await git_command.add_path(PACKAGE_JSON)
+	await release_approval_prune.prune()
 	await git_command.commit(commit_message(plan.next_version))
 	await git_command.push()
 	const pr_url = await git_gh_command.pr_create(
@@ -136,8 +137,7 @@ async function merge_and_tag(
 	branch_name: string,
 	pr_url: string,
 ): Promise<number> {
-	await git_pr_checks.wait_for_pr_success(branch_name)
-	await git_gh_command.pr_merge(branch_name)
+	await git_pr_merge_checked.merge_when_green(branch_name)
 	console.info(release_progress.pr_merged_line(pr_url))
 
 	const is_tagged = await release_tag.wait_for_tag(plan.next_version)

package/scripts/release/release-scope-cli.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_followup_pending } from '#scripts/followup/git-followup-pending'
 import { path_decision } from '#scripts/josh/path-decision'
 import { release_plan } from './release-plan'
@@ -22,7 +20,6 @@ import { release_plan } from './release-plan'
 // The flag parse and the printing come from `path_decision`, the contract every mechanically-decided
 // command here shares. Only its `parse_options` / `run_path_decision` are path-specific, and this
 // decision is not made from changed paths, so those two are the ones left alone.
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh release:scope [--json]'
 const JSON_KEY = 'scope'
 // Not `path_decision.KNOWN_FLAGS`: that set carries `--staged`, which means nothing here, and a
@@ -76,13 +73,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return SUCCESS_EXIT_CODE
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const release_scope_cli = {
 	decide,
-	main,
 	run,
 	JSON_KEY,
 	NOTHING_PENDING_REASON,
@@ -94,7 +86,5 @@ const release_scope_cli = {
 	USAGE,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { Decision }
 export { release_scope_cli }

package/scripts/release/release-scope-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { release_scope_cli } from './release-scope-cli'
+
+// The `josh release:scope` entry, kept apart from `release-scope-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await release_scope_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/repo/repo-setting.ts

@@ -1,5 +1,6 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { json_value } from '#scripts/lib/json-value'
 
 // The shared half of every "report a GitHub repository setting kit cannot write" check.
 //
@@ -49,13 +50,9 @@ function query_repo_api(api_path: string): RepoApiResult {
 function parse_payload(exit_code: number, stdout: string): object | undefined {
 	if (exit_code !== 0) return undefined
 
-	try {
-		const parsed: unknown = JSON.parse(stdout)
+	const parsed = json_value.parse_or_undefined(stdout)
 
-		return typeof parsed === 'object' && parsed !== null ? parsed : undefined
-	} catch {
-		return undefined
-	}
+	return typeof parsed === 'object' && parsed !== null ? parsed : undefined
 }
 
 // Read one field off a parsed body. `Reflect.get` rather than an index signature: the body is

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

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { yaml_document } from '#scripts/lib/yaml-document'
 import { z } from 'zod'
 
@@ -21,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'] },
 ]
@@ -88,17 +92,7 @@ function expected_checks(read_workflow: (workflow: string) => string | undefined
 	})
 }
 
-function parse_json(stdout: string): unknown {
-	try {
-		return JSON.parse(stdout)
-	} catch {
-		return undefined
-	}
-}
-
-function status_check_rules(payload: unknown): Array<BranchRule> {
-	if (!Array.isArray(payload)) return []
-
+function status_check_rules(payload: ReadonlyArray<unknown>): Array<BranchRule> {
 	return payload.flatMap((entry: unknown) => {
 		const parsed = branch_rule_schema.safeParse(entry)
 
@@ -110,8 +104,8 @@ function status_check_rules(payload: unknown): Array<BranchRule> {
 // rulesets. The contexts of all of them are combined, since each is enforced; the first ruleset is the
 // one `--apply` writes to. No `required_status_checks` rule at all reads as `none`.
 function parse_branch_rules(stdout: string | undefined): RequiredSource {
-	const payload = stdout === undefined ? undefined : parse_json(stdout)
-	if (!Array.isArray(payload)) return { kind: 'unreadable' }
+	const payload = stdout === undefined ? undefined : json_value.parse_array(stdout)
+	if (payload === undefined) return { kind: 'unreadable' }
 	const rules = status_check_rules(payload)
 	const [first] = rules
 	if (first === undefined) return { kind: 'none' }
@@ -132,7 +126,7 @@ function parse_protection(read: ApiRead): RequiredSource {
 		return { kind: read.status === NOT_FOUND_STATUS ? 'none' : 'unreadable' }
 	}
 
-	const parsed = protection_schema.safeParse(parse_json(read.stdout))
+	const parsed = protection_schema.safeParse(json_value.parse_or_undefined(read.stdout))
 
 	return parsed.success
 		? { kind: 'protection', contexts: parsed.data.contexts }
@@ -175,7 +169,7 @@ function ruleset_update_body(
 	ruleset_stdout: string,
 	missing: ReadonlyArray<string>,
 ): string | undefined {
-	const parsed = ruleset_schema.safeParse(parse_json(ruleset_stdout))
+	const parsed = ruleset_schema.safeParse(json_value.parse_or_undefined(ruleset_stdout))
 	if (!parsed.success) return undefined
 
 	return JSON.stringify({

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

@@ -9,17 +9,33 @@ const SUMMARY_RULES_HEADING = '作業前サマリはいつ・どう出すか'
 const SUMMARY_TEMPLATE_HEADING = '作業前サマリ（セッション向け・`JOSH_SESSION_LANG` の言語）'
 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,
 	REPORT_FORMAT_PATH,
 	SUMMARY_RULES_HEADING,
 	SUMMARY_TEMPLATE_HEADING,

package/scripts/report/report-labels.ts

@@ -0,0 +1,166 @@
+import { session_language } from '#scripts/josh/session-language'
+
+// The labels of the work summary and the completion report, in the two languages the workflow is
+// written in. **This table is their single source**: `report:template` prints the skeletons from it
+// and `report:lint` checks a summary against it, so a session that translates its labels by the
+// table passes the lint in any language. `report-format.md` names the command, never a copy.
+
+interface ReportLabels {
+	overview: string
+	now: string
+	change: string
+	check: string
+	details: string
+	target: string
+	approach: string
+	out_of_scope: string
+	changes: string
+	cases: string
+	case_vocabulary: ReadonlyArray<string>
+	if_it_breaks: string
+	not_applicable: string
+	never_breaks: string
+	completion: string
+	cause: string
+	fix: string
+	result: string
+	changed_files: string
+	test_results: string
+	evidence: string
+	caught_by: string
+	remaining: string
+	handoff: HandoffLabels
+}
+
+// The hand-off report's labels (`run:report --handoff`) — a fourth kind of stop, so it carries none of
+// the completion report's `cause` / `fix` / `result`.
+interface HandoffLabels {
+	title: string
+	done: string
+	remaining: string
+	why_stopped: string
+	next_command: string
+	measurement: string
+	handover: string
+	handover_text: string
+	parked: string
+	pool: string
+	none: string
+}
+
+const JAPANESE_HANDOFF_LABELS: HandoffLabels = {
+	title: '■ 区切り',
+	done: '終わったこと',
+	remaining: '残っていること',
+	why_stopped: '止めた理由',
+	next_command: '次に打つコマンド',
+	measurement: '計測',
+	handover: '引き継ぎ',
+	handover_text: '状態は GitHub とラン記録にあり、会話には何も無い',
+	parked: 'park 済み',
+	pool: '残りの auto-ok プール',
+	none: 'なし',
+}
+
+const ENGLISH_HANDOFF_LABELS: HandoffLabels = {
+	title: '■ Hand-off',
+	done: 'Done',
+	remaining: 'Remaining',
+	why_stopped: 'Why it stopped',
+	next_command: 'Next command',
+	measurement: 'Measurement',
+	handover: 'Handover',
+	handover_text: 'The state is on GitHub and in the run record; nothing is in the conversation',
+	parked: 'parked',
+	pool: 'the rest of the auto-ok pool',
+	none: 'none',
+}
+
+const JAPANESE_LABELS: ReportLabels = {
+	overview: '■ 概要',
+	now: '今こうなっている',
+	change: 'こう直す',
+	check: '確かめ方',
+	details: '技術詳細',
+	target: '対象',
+	approach: '方針',
+	out_of_scope: '副作用 / スコープ外',
+	changes: '変更とテスト',
+	cases: 'ケース',
+	case_vocabulary: ['正常', '空・0件', '1件', '多数', '境界', '不正入力', '重複', '順序', 'null'],
+	if_it_breaks: '壊れるとしたら',
+	not_applicable: '該当なし',
+	never_breaks: 'どう呼ばれても壊れない',
+	completion: '■ 完了報告',
+	cause: '原因',
+	fix: '対応',
+	result: '結果',
+	changed_files: '変更ファイル',
+	test_results: 'テスト結果',
+	evidence: '実行証跡',
+	caught_by: '捕まえられた検証',
+	remaining: '残課題',
+	handoff: JAPANESE_HANDOFF_LABELS,
+}
+
+const ENGLISH_LABELS: ReportLabels = {
+	overview: '■ Overview',
+	now: 'Now',
+	change: 'Change',
+	check: 'Check',
+	details: 'Details',
+	target: 'Target',
+	approach: 'Approach',
+	out_of_scope: 'Side effects / out of scope',
+	changes: 'Changes and tests',
+	cases: 'Cases',
+	case_vocabulary: [
+		'normal',
+		'empty',
+		'one',
+		'many',
+		'boundary',
+		'invalid input',
+		'duplicate',
+		'order',
+		'null',
+	],
+	if_it_breaks: 'If it breaks',
+	// Never `N/A`: the lint splits a case line on `/`, which would cut the marker in two.
+	not_applicable: 'not applicable',
+	never_breaks: 'never breaks however it is called',
+	completion: '■ Completion report',
+	cause: 'Cause',
+	fix: 'Fix',
+	result: 'Result',
+	changed_files: 'Changed files',
+	test_results: 'Test results',
+	evidence: 'Execution evidence',
+	caught_by: 'Caught by',
+	remaining: 'Remaining',
+	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
+}
+
+function session_labels(): ReportLabels {
+	return labels_for(session_language.resolve_session_lang().lang)
+}
+
+const report_labels = {
+	CHILD_SUMMARY_MAX_LINES,
+	ENGLISH_LABELS,
+	JAPANESE_LABELS,
+	labels_for,
+	session_labels,
+}
+
+export type { HandoffLabels, ReportLabels }
+export { report_labels }

package/scripts/report/report-lint-child-summary.ts

@@ -0,0 +1,94 @@
+import { markdown_shape } from './markdown-shape'
+import { report_format_reference } from './report-format-reference'
+import { report_labels, type ReportLabels } from './report-labels'
+
+// A lane child's closing summary carries only what GitHub does not, in a bounded length
+// (`backlogrun-child.md` → "What the summary carries, and how long it may be"). This checks the half a
+// machine can: the line bound, the cause / fix / result labels, and no changed-file list — a run of
+// bullets that are a path and nothing else. What else belongs in it stays the writer's judgement.
+
+// Two path-only bullets in a row already read as a list; one alone may be the one file a finding names.
+const MIN_FILE_LIST_RUN = 2
+const LIST_ITEM_PREFIX = /^\s*(?:\d+\.|[-*])\s+/u
+const PATH_CHARACTERS = /^[\w.@/-]+$/u
+const FILE_EXTENSION = /\.[a-z]+$/iu
+const BACKTICK = '`'
+// A label opens its line — after an optional list marker and bold marker — so a longer word ending
+// in the label, or `Fix the parser` inside a sentence, does not stand in for a missing label.
+const LABEL_LEAD = /^\s*(?:(?:\d+\.|[-*])\s+)?(?:\*\*)?/u
+const LETTER_PATTERN = /^\p{L}/u
+
+function opens_with_label(line: string, label: string): boolean {
+	const rest = line.replace(LABEL_LEAD, '')
+
+	return rest.startsWith(label) && !LETTER_PATTERN.test(rest.slice(label.length))
+}
+
+// A bullet whose whole text, backticks aside, is one path — a slash segment or a file name.
+function is_path_item(line: string): boolean {
+	if (!LIST_ITEM_PREFIX.test(line)) return false
+
+	const item = line.replace(LIST_ITEM_PREFIX, '').replaceAll(BACKTICK, '').trim()
+
+	return PATH_CHARACTERS.test(item) && (item.includes('/') || FILE_EXTENSION.test(item))
+}
+
+function path_item_runs(lines: ReadonlyArray<string>): ReadonlyArray<ReadonlyArray<string>> {
+	const runs: Array<Array<string>> = [[]]
+
+	for (const line of lines) {
+		if (is_path_item(line)) runs.at(-1)?.push(line)
+		else runs.push([])
+	}
+
+	return runs.filter((run) => run.length >= MIN_FILE_LIST_RUN)
+}
+
+function length_violation(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	const max = report_labels.CHILD_SUMMARY_MAX_LINES
+	if (lines.length <= max) return []
+
+	return [`✖ ${String(lines.length)} lines — the summary holds at most ${String(max)}`]
+}
+
+function label_violations(
+	lines: ReadonlyArray<string>,
+	labels: ReportLabels,
+): ReadonlyArray<string> {
+	return [labels.cause, labels.fix, labels.result]
+		.filter((label) => lines.every((line) => !opens_with_label(line, label)))
+		.map((label) => `✖ missing label: ${label}`)
+}
+
+function file_list_violations(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	return path_item_runs(lines).map(
+		(run) =>
+			`✖ changed-file list (${String(run.length)} path-only items) — GitHub carries it: ${run[0]?.trim() ?? ''}`,
+	)
+}
+
+// Every violation, in a fixed order; an empty array is a clean summary.
+function lint_child_summary(
+	summary: string,
+	labels: ReportLabels = report_labels.session_labels(),
+): ReadonlyArray<string> {
+	const lines = markdown_shape.content_lines(summary)
+
+	return [
+		...length_violation(lines),
+		...label_violations(lines, labels),
+		...file_list_violations(lines),
+	]
+}
+
+// The violations followed by one line naming where the summary's shape is written; a clean summary
+// stays empty, so `ok` is still the only output of a pass.
+function with_reference(violations: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (violations.length === 0) return violations
+
+	return [...violations, `→ the shape: ${report_format_reference.child_summary_pointer()}`]
+}
+
+const report_lint_child_summary = { lint_child_summary, with_reference }
+
+export { report_lint_child_summary }

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

@@ -1,25 +1,40 @@
 #!/usr/bin/env tsx
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { report_lint } from './report-lint'
+import { report_lint_child_summary } from './report-lint-child-summary'
 
 // `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.
+// mechanical violations one per line, exiting non-zero so it works as a gate. `--child-summary`
+// checks a lane child's closing summary instead.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const OK_MESSAGE = 'ok'
+const CHILD_SUMMARY_FLAG = '--child-summary'
+const ARGV_OFFSET = 2
 const NO_INPUT_MESSAGE =
-	'✖ nothing on stdin — pipe the work summary in, e.g. `pnpm josh report:lint < summary.md`'
+	'✖ nothing on stdin — pipe the summary in, e.g. `pnpm josh report:lint < summary.md`'
 
-function run(summary: string): number {
+function lint(summary: string, is_child_summary: boolean): ReadonlyArray<string> {
+	if (is_child_summary) {
+		return report_lint_child_summary.with_reference(
+			report_lint_child_summary.lint_child_summary(summary),
+		)
+	}
+
+	return report_lint.with_reference(report_lint.lint_report(summary))
+}
+
+function run(summary: string, argv: ReadonlyArray<string>): number {
 	if (summary.trim().length === 0) {
 		console.error(NO_INPUT_MESSAGE)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const violations = report_lint.lint_report(summary)
+	const violations = lint(summary, argv.includes(CHILD_SUMMARY_FLAG))
 
 	if (violations.length === 0) {
 		console.info(OK_MESSAGE)
@@ -27,19 +42,26 @@ function run(summary: string): number {
 		return SUCCESS_EXIT_CODE
 	}
 
-	console.error(report_lint.with_reference(violations).join('\n'))
+	console.error(violations.join('\n'))
 
 	return FAILURE_EXIT_CODE
 }
 
 async function read_and_run(): Promise<number> {
-	if (process.stdin.isTTY) return run('')
+	const argv = process.argv.slice(ARGV_OFFSET)
+	if (process.stdin.isTTY) return run('', argv)
 
-	return run(await text(process.stdin))
+	return run(await text(process.stdin), argv)
 }
 
+// `.env` is read here, on the command path alone, so the labels follow the session language.
 async function main(): Promise<void> {
+	josh_environment_file.load_environment_file()
 	process.exitCode = await read_and_run()
 }
 
+const report_lint_cli = { run }
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { report_lint_cli }