@joshuafolkken/kit 1.929.0 → 1.953.0

package/scripts/init/init-logic-workspace.ts

@@ -75,10 +75,61 @@ function answer_build_placeholders(existing: string, template: string): string {
 	})
 }
 
+const BUILD_ENTRY_KEY_PATTERN = /^[ \t]+(?<key>[^\s:#][^:#]*):/u
+
+function build_entry_key(line: string): string | undefined {
+	const key = BUILD_ENTRY_KEY_PATTERN.exec(line)?.groups?.['key']
+
+	return key === undefined ? undefined : unquote(key)
+}
+
+function build_entry_keys(block: string): Set<string> {
+	return new Set(block.split('\n').flatMap((line) => build_entry_key(line) ?? []))
+}
+
+// The key-level merge keeps an existing `allowBuilds` whole, and `pnpm add -D @joshuafolkken/kit`
+// before `josh init` always leaves one (esbuild's), so without this the template's other approvals
+// never landed and the first `pnpm install` failed on the next build script, e.g. unrs-resolver's
+// (joshuafolkken/kit#2710). Entries the project already answered keep their value.
+// Only a block mapping can take appended entry lines; a flow map (`allowBuilds: { … }`) is left whole.
+const BLOCK_MAPPING_HEADER_PATTERN = /^allowBuilds:[ \t]*(?:#[^\n]*)?(?:\n|$)/u
+const LEADING_INDENT_PATTERN = /^[ \t]+/u
+
+// Appended lines take the indent of the block's own entries: a mapping whose items start at
+// different columns is invalid YAML, so a four-space block must not gain two-space lines.
+function block_entry_indent(block: string): string | undefined {
+	const entry = block.split('\n').find((line) => build_entry_key(line) !== undefined)
+
+	return entry === undefined ? undefined : LEADING_INDENT_PATTERN.exec(entry)?.[0]
+}
+
+function reindent(line: string, indent: string | undefined): string {
+	return indent === undefined ? line : line.replace(LEADING_INDENT_PATTERN, () => indent)
+}
+
+function add_missing_build_entries(existing: string, template: string): string {
+	const block = extract_yaml_block(existing, 'allowBuilds')
+	if (!BLOCK_MAPPING_HEADER_PATTERN.test(block)) return existing
+	const present = build_entry_keys(block)
+	const indent = block_entry_indent(block)
+	const missing = extract_yaml_block(template, 'allowBuilds')
+		.split('\n')
+		.filter((line) => {
+			const key = build_entry_key(line)
+
+			return key !== undefined && !present.has(key)
+		})
+		.map((line) => reindent(line, indent))
+	if (missing.length === 0) return existing
+
+	return existing.replace(block, () => [block, ...missing].join('\n'))
+}
+
 function merge_workspace_yaml(existing: string, template: string): string {
 	if (!existing.trim()) return template
 	const normalized = existing.endsWith('\n') ? existing : `${existing}\n`
-	const cleaned = answer_build_placeholders(remove_deprecated_yaml_keys(normalized), template)
+	const answered = answer_build_placeholders(remove_deprecated_yaml_keys(normalized), template)
+	const cleaned = add_missing_build_entries(answered, template)
 	if (!cleaned.trim()) return template
 	const existing_keys = new Set(extract_yaml_top_level_keys(cleaned))
 	const new_keys = extract_yaml_top_level_keys(template).filter((k) => !existing_keys.has(k))

package/scripts/init/init-logic.ts

@@ -1,5 +1,6 @@
 import { json_format } from '#scripts/config-merge/json-format'
 import { vscode_settings_schema } from '#scripts/lib/schemas'
+import { safe_chain_preinstall } from '#scripts/safe-chain/preinstall-command'
 import { distributed_paths } from './distributed-paths'
 import { init_logic_deploy_vps } from './init-logic-deploy-vps'
 import { init_logic_json_merge } from './init-logic-json-merge'
@@ -27,7 +28,7 @@ const NPMRC_LINES: ReadonlyArray<string> = [
 const CSPELL_IMPORT = '@joshuafolkken/kit/cspell'
 
 const LEFTHOOK_INSTALL_CMD = 'lefthook install'
-const SAFE_CHAIN_CMD = 'pnpm dlx @aikidosec/safe-chain setup-ci'
+const { SAFE_CHAIN_CMD } = safe_chain_preinstall
 const FIX_GH_PACKAGES_CMD = 'tsx node_modules/@joshuafolkken/kit/scripts/gh/fix-gh-packages.ts'
 // Marker identifying a consumer script that already runs the fix-gh-packages command.
 const FIX_GH_PACKAGES_MARKER = 'fix-gh-packages'
@@ -90,6 +91,7 @@ const AI_COPY_FILES: ReadonlyArray<string> = [
 	'.github/workflows/auto-tag.yml',
 	'.github/workflows/production.yml',
 	'.github/workflows/sonar-qube.yml',
+	'.github/workflows/pr-classification.yml',
 	'.github/pull_request_template.md',
 	'.github/release.yml',
 	'.github/dependabot.yml',
@@ -228,9 +230,12 @@ const PRETTIER_PLUGIN_DEV_DEPS: Record<string, string> = {
 // format_json rather than JSON.stringify: it lays arrays out the way prettier does — inline while
 // they fit within printWidth, one element per line once they do not — so the file kit writes is
 // `prettier --check`-clean in the consumer whatever the entry count happens to be (#660).
+// TypeScript 6 defaults `types` to `[]`, so a node project sees no `process` global — not even in the
+// generated `playwright.config.ts` — until the Node types are named (joshuafolkken/kit#2710).
 function generate_tsconfig(): string {
 	return json_format.format_json({
 		extends: TSCONFIG_EXTENDS,
+		compilerOptions: { types: ['node'] },
 		[TSCONFIG_EXCLUDE_FIELD]: TSCONFIG_EXCLUDE,
 	})
 }

package/scripts/init/init.ts

@@ -27,6 +27,7 @@ const LEFTHOOK_BIN = 'lefthook'
 const SAMPLE_INDENT_WIDTH = 4
 const ARGUMENT_START_INDEX = 2
 const SAMPLE_INDENT = ' '.repeat(SAMPLE_INDENT_WIDTH)
+const INSTALL_HINT = '→ run `pnpm install` to install what package.json lists'
 
 function write_new_file(action: FileAction, destination_path: string): void {
 	mkdirSync(path.dirname(destination_path), { recursive: true })
@@ -77,12 +78,25 @@ function execute_file_action(action: FileAction): void {
 	merge_existing_file(action.merge, destination_path, action.dest)
 }
 
-function get_kit_package_manager(): string | undefined {
-	const { packageManager: package_manager } = with_package_manager_schema.parse(
-		init_actions.read_package_json(PACKAGE_JSON),
-	)
+const engine_pin_schema = z.looseObject({ name: z.string(), version: z.string() })
+
+const published_development_engines_schema = z.looseObject({
+	devEngines: z.looseObject({ packageManager: engine_pin_schema.optional() }).optional(),
+})
+
+// pnpm strips `packageManager` from a published manifest, so the kit a consumer installs carries its
+// pin only in `devEngines`. Falling back to that exact version keeps the consumer off the bare
+// `>=12.1.0` range, which every later `pnpm` call rejects as an invalid packageManager specification.
+function resolve_kit_package_manager(manifest: unknown): string | undefined {
+	const { packageManager: package_manager } = with_package_manager_schema.parse(manifest)
+	if (package_manager !== undefined && package_manager.length > 0) return package_manager
+	const pin = published_development_engines_schema.parse(manifest).devEngines?.packageManager
 
-	return package_manager !== undefined && package_manager.length > 0 ? package_manager : undefined
+	return pin === undefined ? undefined : `${pin.name}@${pin.version}`
+}
+
+function get_kit_package_manager(): string | undefined {
+	return resolve_kit_package_manager(init_actions.read_package_json(PACKAGE_JSON))
 }
 
 function get_kit_development_engines(): Record<string, unknown> {
@@ -97,21 +111,34 @@ function get_kit_self_dependency(): Record<string, string> {
 	return { [KIT_PACKAGE_NAME]: version }
 }
 
-function get_eslint_development_dependencies(): Record<string, string> {
+// Each config `init` generates runs a CLI or imports types the consumer has to resolve itself:
+// `prettier.config.js` → prettier, `cspell.config.yaml` → cspell, `playwright.config.ts` →
+// @types/node (with @playwright/test among the peers), `lefthook.yml` → lefthook. Without them the
+// first `josh gate` after `pnpm install` fails (joshuafolkken/kit#2710).
+const TOOL_DEVELOPMENT_DEPENDENCIES = ['prettier', 'cspell', '@types/node']
+const LEFTHOOK_DEVELOPMENT_DEPENDENCY = 'lefthook'
+
+function tool_dependency_names(has_git: boolean): ReadonlyArray<string> {
+	return has_git
+		? [...TOOL_DEVELOPMENT_DEPENDENCIES, LEFTHOOK_DEVELOPMENT_DEPENDENCY]
+		: TOOL_DEVELOPMENT_DEPENDENCIES
+}
+
+// Versions mirror kit's own devDependencies, so the consumer runs the toolchain kit is verified with.
+function get_toolchain_development_dependencies(has_git: boolean): Record<string, string> {
 	const manifest = z
 		.object({
 			peerDependencies: z.record(z.string(), z.string()),
 			devDependencies: z.record(z.string(), z.string()),
 		})
 		.parse(init_actions.read_package_json(PACKAGE_JSON))
-	const entries = Object.keys(manifest.peerDependencies)
-		.filter((name) => name !== '@playwright/test')
-		.map((name): [string, string] => {
-			const version = manifest.devDependencies[name]
-			if (version === undefined) throw new Error(`Missing development version for ${name}`)
+	const names = [...Object.keys(manifest.peerDependencies), ...tool_dependency_names(has_git)]
+	const entries = names.map((name): [string, string] => {
+		const version = manifest.devDependencies[name]
+		if (version === undefined) throw new Error(`Missing development version for ${name}`)
 
-			return [name, version]
-		})
+		return [name, version]
+	})
 
 	return Object.fromEntries(entries)
 }
@@ -126,11 +153,11 @@ function apply_dependency_merges(content: string, has_git = true): string {
 			: Object.fromEntries(Object.entries(suggested).filter(([key]) => key !== 'prepare')),
 	)
 	const with_prettier = init_logic.merge_prettier_plugin_development_deps(merged)
-	const with_eslint = init_logic.merge_development_dependencies(
+	const with_toolchain = init_logic.merge_development_dependencies(
 		with_prettier,
-		get_eslint_development_dependencies(),
+		get_toolchain_development_dependencies(has_git),
 	)
-	const with_secretlint = init_logic.merge_secretlint_development_deps(with_eslint)
+	const with_secretlint = init_logic.merge_secretlint_development_deps(with_toolchain)
 
 	return init_logic.merge_development_dependencies(with_secretlint, get_kit_self_dependency())
 }
@@ -191,12 +218,25 @@ function merge_project_package_json(shape: ProjectShape): void {
 
 	writeFileSync(package_json_path, merged)
 	console.info(`  ✔ ${is_existing ? 'updated' : 'created'}   package.json`)
+	// `init` writes the manifest but installs nothing, so a tool it just listed is absent until the
+	// user installs it — and `josh lint` then fails on it rather than skipping it
+	// (joshuafolkken/kit#2709). Saying so here is what tells the user the next step.
+	console.info(`    ${INSTALL_HINT}`)
 }
 
-function install_lefthook(): void {
+// A fresh project runs `init` before its first `pnpm install`, so lefthook — added to devDependencies
+// above — is not there yet; the `prepare` script installs the hooks once it is.
+function install_lefthook(project_root: string = PROJECT_ROOT): void {
 	console.info('\nLefthook:')
-	const bin = resolve_local_bin(PROJECT_ROOT, LEFTHOOK_BIN)
-	const result = execaSync(bin, ['install'], { cwd: PROJECT_ROOT, stdio: 'inherit', reject: false })
+	const bin = resolve_local_bin(project_root, LEFTHOOK_BIN)
+
+	if (!existsSync(bin)) {
+		console.info('  ℹ lefthook is not installed yet — `pnpm install` installs the git hooks')
+
+		return
+	}
+
+	const result = execaSync(bin, ['install'], { cwd: project_root, stdio: 'inherit', reject: false })
 
 	if (result.exitCode === undefined) {
 		console.warn('  ⚠ lefthook install failed — run it manually: lefthook install')
@@ -281,6 +321,7 @@ const init = {
 	copy_ai_file: init_ai_copy.copy_ai_file,
 	apply_package_json_merges,
 	install_lefthook,
+	resolve_kit_package_manager,
 }
 
 // `init` is the entry point; `main` is exported for its own unit test, the way `sync.ts` exports the

package/scripts/issue/issue-merged.ts

@@ -0,0 +1,75 @@
+import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+
+// Whether an issue was closed by a merge, read from its REST timeline (joshuafolkken/kit#2701). The
+// issue's own `state_reason` cannot tell: a pull request's `closes #N` and a person's "Close as
+// completed" both answer `completed`. What only a merge leaves is a merged pull request referencing
+// the issue, so the answer is the conjunction — closed now, as completed, and referenced by a merged
+// pull request. A manual "completed" close still reads as merged when a merged pull request also
+// references the issue — the one case the timeline cannot separate — and every other doubt falls to
+// `false`, because a sweep deletes work on this answer.
+
+const CLOSED_EVENT = 'closed'
+const REOPENED_EVENT = 'reopened'
+const MERGED_REFERENCE = 'merged-reference'
+// A close by a pull request's `closes #N` carries no reason in the timeline; a person's "Close as
+// completed" carries `completed`. Any other reason — `not_planned`, `duplicate` — is not a merge, and
+// neither is one GitHub adds later.
+const COMPLETED_REASONS: ReadonlySet<string> = new Set(['', 'completed'])
+const FIELD_SEPARATOR = '\t'
+const LINE_SEPARATOR = '\n'
+// One `<event>\t<state_reason>` line per closed/reopened event, and a `merged-reference` line per
+// merged pull request that cross-references the issue — the three kinds the answer reads.
+const TIMELINE_FILTER = [
+	'.[]',
+	'| if .event == "cross-referenced" and .source.issue.pull_request.merged_at != null',
+	String.raw`then "${MERGED_REFERENCE}\t"`,
+	`elif .event == "${CLOSED_EVENT}" or .event == "${REOPENED_EVENT}"`,
+	String.raw`then "\(.event)\t\(.state_reason // "")"`,
+	'else empty end',
+].join(' ')
+
+interface TimelineRow {
+	event: string
+	reason: string
+}
+
+function parse_rows(raw: string): Array<TimelineRow> {
+	return raw
+		.split(LINE_SEPARATOR)
+		.filter((line) => line !== '')
+		.map((line) => {
+			const [event = '', reason = ''] = line.split(FIELD_SEPARATOR)
+
+			return { event, reason }
+		})
+}
+
+// The last closed/reopened event is the issue's current state, so a reopened issue is not merged
+// even with a merged reference from an earlier attempt.
+function is_merged_close(rows: ReadonlyArray<TimelineRow>): boolean {
+	const last = rows.findLast((row) => row.event === CLOSED_EVENT || row.event === REOPENED_EVENT)
+
+	if (last?.event !== CLOSED_EVENT || !COMPLETED_REASONS.has(last.reason)) return false
+
+	return rows.some((row) => row.event === MERGED_REFERENCE)
+}
+
+async function read_merged(issue: string): Promise<boolean> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({
+			path: `${git_gh_api_path.issue_api_path(issue)}/timeline?per_page=100`,
+			should_paginate: true,
+			jq_filter: TIMELINE_FILTER,
+		})
+
+		return is_merged_close(parse_rows(raw))
+	} catch {
+		return false
+	}
+}
+
+const issue_merged = { is_merged_close, parse_rows, read_merged }
+
+export type { TimelineRow }
+export { issue_merged }

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { execSync } from 'node:child_process'
-import { appendFile, readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { baseline_measure, type Baseline } from './baseline-measure'
@@ -47,7 +47,7 @@ async function append_ledger(lines: ReadonlyArray<string>): Promise<void> {
 	// (joshuafolkken/kit#2419).
 	const ledger_path = observation_ledger_home.ledger_path()
 
-	await appendFile(ledger_path, `${lines.join('\n')}\n`, 'utf8')
+	await observation_ledger_home.append(ledger_path, lines)
 	console.info(`Recorded ${String(lines.length)} refuted premise(s) in ${ledger_path}.`)
 }
 

package/scripts/josh/__snapshots__/josh-command-map.test.ts.snap

@@ -116,6 +116,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
     "rsp": "run:step",
     "rst": "run:status",
     "rt": "reconcile-templates",
+    "rtd": "run:tidy",
     "rtl": "run:tail",
     "rtr": "retrospective",
     "rug": "rule:guard",
@@ -1041,6 +1042,15 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
         "network",
       ],
     ],
+    "run:tidy": [
+      "",
+      "automation",
+      [
+        "git",
+        "network",
+        "files",
+      ],
+    ],
     "run:wake": [
       "[options]",
       "automation",

package/scripts/josh/josh-command-map.ts

@@ -135,6 +135,7 @@ const ALIASES: Record<string, string> = {
 	rh: 'run:hold',
 	rr: 'run:release',
 	rc: 'run:carry',
+	rtd: 'run:tidy',
 	rw: 'run:wake',
 	rct: 'run:cut',
 	rv: 'run:liveness',

package/scripts/josh/josh-command-types.ts

@@ -69,8 +69,6 @@ interface CommandEntry {
 // (joshuafolkken/kit#914).
 const GATE_COMMAND = 'gate'
 
-const PE = ['pnpm', 'exec'] as const
-
 // joshuafolkken/kit#1256: three of the gate's four checks keep a content-addressed cache, so a
 // second run reads only what changed. eslint had one from the start; the type check and the spell
 // check rescanned the whole tree every time, which cost 10.5s of CPU against 2.8s cached.
@@ -219,7 +217,6 @@ export {
 	GATE_COMMAND,
 	IGNORED_CACHE_FILES,
 	OPTIONAL_ENV_FILE_FLAGS,
-	PE,
 	SHARED_CACHE_SPECS,
 	TS_BUILD_INFO_FILE,
 	TS_CACHE_FLAGS,

package/scripts/josh/josh-commands-ai.ts

@@ -147,6 +147,12 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[issue|--force]', 'automation', ['files']],
 		default_script_arguments: ['--release'],
 	},
+	'run:tidy': {
+		script: 'scripts/run/run-tidy-cli.ts',
+		description: 'Close merged lanes and drop stashes whose issues are all merged',
+		category: 'AI tools',
+		reference: ['', 'automation', ['git', 'network', 'files']],
+	},
 	'run:carry': {
 		script: 'scripts/run/run-carry-cli.ts',
 		description: 'Carry one invocation’s budget across its own session cuts',

package/scripts/josh/josh-commands-development.ts

@@ -1,4 +1,4 @@
-import { GATE_COMMAND, PE, TS_CACHE_FLAGS, type CommandEntry } from './josh-command-types'
+import { GATE_COMMAND, type CommandEntry } from './josh-command-types'
 
 const FILE_ARGUMENTS = '[files...]'
 const REQUIRED_FILE_ARGUMENTS = '<files...>'
@@ -22,7 +22,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	lint: {
 		script: 'scripts/lint/lint-parallel.ts',
-		description: 'Check code with prettier and eslint',
+		description: 'Check code with prettier and eslint (skips a tool a static project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 	},
@@ -61,7 +61,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	format: {
 		script: 'scripts/lint/format.ts',
-		description: 'Format code with prettier and eslint',
+		description: 'Format code with prettier and eslint (skips a tool a static project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['files', 'processes']],
 	},
@@ -182,8 +182,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		argument_targets: ['test:unit', 'test:e2e'],
 	},
 	check: {
-		shell: [...PE, 'tsc', '--noEmit', ...TS_CACHE_FLAGS],
-		description: 'Type-check TypeScript project',
+		script: 'scripts/gate/type-check-command.ts',
+		description: 'Type-check with tsc (skips a static project with no TypeScript to check)',
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
 	},

package/scripts/lint/lint-parallel.ts

@@ -34,18 +34,25 @@ function skipped(check: string, reason: string): BufferedProcessResult {
 	return { output: `${project_checks.skip_notice(check, reason)}\n`, exit_code: 0, elapsed_ms: 0 }
 }
 
-async function run_static_prettier(directory: string): Promise<BufferedProcessResult> {
+async function run_prettier(
+	directory: string,
+	prettier_args: ReadonlyArray<string>,
+): Promise<BufferedProcessResult> {
 	const reason = project_checks.prettier_skip_reason(directory)
 	if (reason !== undefined) return skipped('prettier', reason)
 
-	return await buffered_process.run_buffered_process(PRETTIER_ARGS)
+	return await buffered_process.run_buffered_process(prettier_args)
 }
 
-async function run_static_eslint(directory: string): Promise<BufferedProcessResult> {
+async function run_checked_eslint(
+	directory: string,
+	eslint_args: ReadonlyArray<string>,
+	cache_file: string,
+): Promise<BufferedProcessResult> {
 	const reason = project_checks.eslint_skip_reason(directory)
 	if (reason !== undefined) return skipped('eslint', reason)
 
-	return await run_eslint(ESLINT_ARGS, ESLINT_CACHE_FILE)
+	return await run_eslint(eslint_args, cache_file)
 }
 
 function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcessResult): number {
@@ -56,15 +63,19 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 
 // The two checks are run from here whether they were pointed at the whole tree or at one change's
 // files, so `josh lint:related` reaches prettier and eslint through the same buffering, the same
-// "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298).
+// "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298) —
+// and through the same static-project skip, so a narrowed run never reaches a tool the whole-tree
+// run would have skipped (joshuafolkken/kit#2709). The skip reasons answer nothing for a node
+// project, so the one path serves both profiles.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
 	eslint_cache_file: string = ESLINT_CACHE_FILE,
 ): Promise<number> {
+	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([
-		buffered_process.run_buffered_process(prettier_args),
-		run_eslint(eslint_args, eslint_cache_file),
+		run_prettier(directory, prettier_args),
+		run_checked_eslint(directory, eslint_args, eslint_cache_file),
 	])
 
 	write_output(prettier)
@@ -74,17 +85,7 @@ async function run_lint_checks(
 }
 
 async function run_lint_parallel_checks(): Promise<number> {
-	const directory = process.cwd()
-	if (!project_checks.is_static(directory)) return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS)
-	const [prettier, eslint] = await Promise.all([
-		run_static_prettier(directory),
-		run_static_eslint(directory),
-	])
-
-	write_output(prettier)
-	write_output(eslint)
-
-	return lint_exit_code(prettier, eslint)
+	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS)
 }
 
 // `process.exitCode` rather than `process.exit()`: both reports are buffered and written here in

package/scripts/observations/observation-ledger-home.ts

@@ -1,6 +1,8 @@
+import { appendFile, mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { observation_ledger_migrate } from './observation-ledger-migrate'
 
 // Where the observation ledger is read and written, whichever work tree a command runs in
 // (joshuafolkken/kit#2419).
@@ -23,10 +25,28 @@ function is_lane(cwd: string = process.cwd()): boolean {
 	return path.resolve(ledger_root(cwd)) !== path.resolve(cwd)
 }
 
+// **Resolving the path migrates the ledger first** (joshuafolkken/kit#2724). Every reader and writer
+// asks here — `review:record --check`, `review:findings`, the retrospective, the stash carry's
+// duplicate check — so none of them can read an empty new ledger while the lines still sit at the old
+// path, which for the review-record check would answer `not-required` for a round never recorded.
 function ledger_path(cwd: string = process.cwd()): string {
-	return path.join(ledger_root(cwd), OBSERVATION_LEDGER_PATH)
+	const root = ledger_root(cwd)
+
+	observation_ledger_migrate.migrate(root)
+
+	return path.join(root, OBSERVATION_LEDGER_PATH)
+}
+
+// The one append every ledger writer goes through. A consumer that does not keep the ledger has no
+// `docs/` at its root, so the parent is created first — the one write path that can bring the ledger
+// into existence there (joshuafolkken/kit#2402).
+async function append(target: string, lines: ReadonlyArray<string>): Promise<void> {
+	if (lines.length === 0) return
+
+	await mkdir(path.dirname(target), { recursive: true })
+	await appendFile(target, `${lines.join('\n')}\n`, 'utf8')
 }
 
-const observation_ledger_home = { is_lane, ledger_path, ledger_root }
+const observation_ledger_home = { append, is_lane, ledger_path, ledger_root }
 
 export { observation_ledger_home }

package/scripts/observations/observation-ledger-line.ts

@@ -83,10 +83,21 @@ function broken_ledger_lines(content: string): ReadonlyArray<BrokenLine> {
 		.filter((entry): entry is BrokenLine => entry.reason !== undefined)
 }
 
+// The lines of `candidates` the ledger does not already hold, in their order. The ledger is
+// append-only and the digest counts repeats, so every path that moves lines into it — the stash carry
+// (`run-tidy.ts`) and the old-path migration (`observation-ledger-migrate.ts`) — asks this rather than
+// appending blind: the same line arriving twice would read as a recurrence.
+function missing_lines(candidates: ReadonlyArray<string>, ledger: string): Array<string> {
+	const present = new Set(ledger.split('\n'))
+
+	return candidates.filter((line) => !present.has(line))
+}
+
 const observation_ledger_line = {
 	broken_ledger_lines,
 	is_ledger_entry_line,
 	line_reason,
+	missing_lines,
 }
 
 export type { BrokenLine }