@joshuafolkken/kit 1.1010.0 → 1.1050.0

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

@@ -27,7 +27,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<message>', 'automation', ['git']],
 	},
 	epic: {
-		script: 'scripts-ai/epic.ts',
+		script: 'scripts/epic/epic.ts',
 		description: 'Create an epic issue from its child issue numbers',
 		category: 'AI tools',
 		reference: ['<title> <issue...> [--ordered]', 'automation', ['network']],
@@ -51,7 +51,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<epic>', 'automation', ['network']],
 	},
 	'epic:check': {
-		script: 'scripts-ai/epic-check.ts',
+		script: 'scripts/epic/epic-check.ts',
 		description: 'Check an epic issue against the tracking requirements',
 		category: 'AI tools',
 		reference: ['<epic>', 'automation', ['network']],

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

@@ -19,7 +19,7 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Collapse a backlogrun loop-head event into one call: read backlog:next, ask backlog:budget, return the verdict and any issues to start',
 		category: 'AI tools',
-		reference: ['[options]', 'automation', ['network']],
+		reference: ['[options]', 'automation', ['files', 'network', 'processes']],
 	},
 	'backlog:drive': {
 		script: 'scripts/backlog/backlog-drive-cli.ts',

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

@@ -57,7 +57,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			"Print each delivered rule's unaided compliance — runs reached, kept rate, refusals",
 		category: 'AI tools',
-		reference: ['', 'developer', ['none']],
+		reference: ['[--refresh]', 'developer', ['files']],
 	},
 	format: {
 		script: 'scripts/lint/format.ts',
@@ -66,7 +66,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['files', 'processes']],
 	},
 	'format:edited': {
-		script: 'scripts/hooks/format-edited-file.ts',
+		script: 'scripts/hooks/format-edited-cli.ts',
 		description: 'Claude Code hook: format the file just edited (reads the tool call on stdin)',
 		category: 'Development',
 		reference: ['', 'automation', ['files', 'processes']],
@@ -85,7 +85,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		// node's own `--env-file` parser with node's own precedence.
 	},
 	'pretool:guard': {
-		script: 'scripts/hooks/pretool-guard.ts',
+		script: 'scripts/hooks/pretool-guard-cli.ts',
 		description:
 			'Claude Code hook: the batch, investigation and rule guards in one process (reads the tool call on stdin)',
 		category: 'Development',

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

@@ -17,7 +17,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public]`,
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>]`,
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],

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

@@ -1,6 +1,6 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
-const GIT_WORKFLOW_SCRIPT = 'scripts-ai/git-workflow.ts'
+const GIT_WORKFLOW_SCRIPT = 'scripts/git/git-workflow.ts'
 const GIT_MESSAGE_ARGUMENTS = '[-y] <message>'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -27,7 +27,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// session, and `followup` with them the merge step of every `fullrun` there. `doctor` was moved to
 	// this form for the same reason in joshuafolkken/kit#869.
 	//
-	// Nothing is lost by relaxing it: both scripts already call `load_optional_environment()`
+	// Nothing is lost by relaxing it: both scripts already load `.env` through `josh_environment_file`
 	// themselves, so the file is read either way and node's precedence — an existing environment
 	// variable wins over the file — is node's own in both spellings.
 	//
@@ -35,7 +35,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
 	// `josh notify` exits non-zero instead of warning and answering 0.
 	followup: {
-		script: 'scripts-ai/git-followup-workflow.ts',
+		script: 'scripts/git/git-followup-workflow.ts',
 		description: 'Follow-up git workflow',
 		category: 'Workflow',
 		reference: [
@@ -46,7 +46,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
 	notify: {
-		script: 'scripts-ai/telegram-test.ts',
+		script: 'scripts/git/telegram-test.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],

package/scripts/lane/lane-child-marker.ts

@@ -19,6 +19,15 @@ import { lane_paths } from './lane-paths'
 // `.claude/skills/workflow-commands/pre-gate-cut.md`.
 const KEY = 'JOSH_LANE_CHILD'
 
+// **A dispatched child also asks for the five-minute prompt-cache TTL** (joshuafolkken/kit#2944). A
+// headless `claude -p` session on a subscription defaults to the one-hour TTL, whose writes bill at 2x
+// the input rate against 1.25x for five minutes. A replay of 1,953 lane transcripts (about 57,000
+// requests) found 0.3% of request gaps over five minutes, so the shorter TTL — re-writing the prefix on
+// those few gaps — still costs 12-13% less. Every launcher of a child composes its environment here,
+// so this is the one place the choice is made.
+const CACHE_TTL_KEY = 'CLAUDE_CODE_PROMPT_CACHE_TTL'
+const CACHE_TTL = '5m'
+
 type MarkerSource = Readonly<Record<string, string | undefined>>
 
 // The environment fragment that marks a child dispatched for `#<issue>`. Composed from a digits-only
@@ -27,7 +36,7 @@ type MarkerSource = Readonly<Record<string, string | undefined>>
 function environment_for(issue: string): Record<string, string> {
 	run_issue_number.require_issue_number(issue)
 
-	return { [KEY]: issue }
+	return { [KEY]: issue, [CACHE_TTL_KEY]: CACHE_TTL }
 }
 
 // The issue a child was dispatched for, or `undefined` when the mark is absent or malformed. A blank
@@ -52,7 +61,12 @@ function is_child_of(directory: string, source: MarkerSource = process.env): boo
 	return marked !== undefined && marked === lane_paths.lane_issue_of(directory, { ...source })
 }
 
-const lane_child_marker = { KEY, env_for: environment_for, is_child_of, marked_issue }
+const lane_child_marker = {
+	KEY,
+	env_for: environment_for,
+	is_child_of,
+	marked_issue,
+}
 
 export type { MarkerSource }
 export { lane_child_marker }

package/scripts/lane/lane-cli.ts

@@ -2,6 +2,9 @@
 import { fileURLToPath } from 'node:url'
 import { epic_busy } from '#scripts/epic/epic-busy'
 import { git_gh_command } from '#scripts/git/git-gh-command'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+import { error_text } from '#scripts/lib/error-message'
 import { run_carry } from '#scripts/run/run-carry'
 import { lane_await } from './lane-await'
 import { lane_close, type CloseOutcome, type SweepOutcome } from './lane-close'
@@ -149,10 +152,10 @@ function report_sweep(outcome: SweepOutcome): number {
 
 // `none` on standard output for the empty case as well, so `lane:list` keeps the contract the rest
 // of the commands follow — the prose belongs on standard error with every other explanation.
-function report_lanes(lanes: ReadonlyArray<LaneInfo>): number {
+function report_lanes(lanes: ReadonlyArray<LaneInfo>, cite: IssueCiter): number {
 	if (lanes.length === 0) console.error(lane_report.NO_LANES)
 
-	console.info(lanes.length === 0 ? NONE_TOKEN : lane_report.describe_lanes(lanes))
+	console.info(lanes.length === 0 ? NONE_TOKEN : lane_report.describe_lanes(lanes, cite))
 
 	return SUCCESS_EXIT_CODE
 }
@@ -191,23 +194,39 @@ const OCCUPANCY_UNREADABLE =
 // The `in-progress` issues this repository shows running, read the way `epic:next` reads lane
 // occupancy — never rebuilt (joshuafolkken/kit#2235). A read that could not see the whole listing is
 // `undefined`, so the difference is skipped rather than computed against a set known to be partial.
-async function to_holder_numbers(repo: string): Promise<ReadonlyArray<number> | undefined> {
+async function to_holders(repo: string): Promise<ReadonlyArray<OpenIssueData> | undefined> {
 	const read = await epic_busy.read_repository(repo)
 	if (read.kind === 'idle') return []
 
-	return read.kind === 'busy' ? read.issues.map((issue) => issue.number) : undefined
+	return read.kind === 'busy' ? read.issues : undefined
 }
 
-async function read_in_progress(): Promise<ReadonlyArray<number> | undefined> {
+// The repository and its running issues, read once: the listing cites each lane from the titles here
+// (joshuafolkken/kit#2943) and the occupancy check compares against the same set.
+interface InProgress {
+	repo: string | undefined
+	holders: ReadonlyArray<OpenIssueData> | undefined
+}
+
+async function read_in_progress(): Promise<InProgress> {
 	try {
 		const repo = await git_gh_command.repo_get_name_with_owner()
 
-		return repo === undefined ? undefined : await to_holder_numbers(repo)
+		return { repo, holders: repo === undefined ? undefined : await to_holders(repo) }
 	} catch {
-		return undefined
+		return { repo: undefined, holders: undefined }
 	}
 }
 
+function citer_of(in_progress: InProgress): IssueCiter {
+	const holders = in_progress.holders ?? []
+
+	return issue_cite.citer(
+		in_progress.repo,
+		new Map(holders.map((issue) => [String(issue.number), issue.title])),
+	)
+}
+
 // A stranded lane's work tree is gone, so it holds no issue: it counts as no lane rather than a live
 // one, which is what turns its surviving `in-progress` label into a `stopped` anomaly.
 function live_lane_issues(lanes: ReadonlyArray<LaneInfo>): Array<number> {
@@ -216,16 +235,15 @@ function live_lane_issues(lanes: ReadonlyArray<LaneInfo>): Array<number> {
 
 // The lane/label difference, printed to standard error beside the listing. Wrapped so a GitHub read
 // that fails skips only this section — `lane:list`'s job is to list the lanes it already read.
-async function report_occupancy(lanes: ReadonlyArray<LaneInfo>): Promise<void> {
-	const in_progress = await read_in_progress()
-
-	if (in_progress === undefined) {
+function report_occupancy(lanes: ReadonlyArray<LaneInfo>, in_progress: InProgress): void {
+	if (in_progress.holders === undefined) {
 		console.error(OCCUPANCY_UNREADABLE)
 
 		return
 	}
 
-	const report = lane_occupancy.classify(in_progress, {
+	const holders = in_progress.holders.map((issue) => issue.number)
+	const report = lane_occupancy.classify(holders, {
 		kind: 'lanes',
 		issues: live_lane_issues(lanes),
 	})
@@ -238,9 +256,10 @@ async function list_command(rest: ReadonlyArray<string>): Promise<number> {
 	if (rest.length > 0) return report_usage()
 
 	const lanes = await lane_registry.list_lanes()
-	const code = report_lanes(lanes)
+	const in_progress = await read_in_progress()
+	const code = report_lanes(lanes, citer_of(in_progress))
 
-	await report_occupancy(lanes)
+	report_occupancy(lanes, in_progress)
 
 	return code
 }
@@ -384,7 +403,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return await dispatch(argv)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/lane/lane-open.ts

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { file_reader } from '#scripts/lib/read-file'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
 import { lane_install, type InstallResult } from './lane-install'
@@ -52,7 +53,7 @@ const SEAT_LOCK_PREFIX = 'seat-'
 function read_root_environment(repository_root: string): string {
 	const file = path.join(repository_root, ENV_FILE_NAME)
 
-	return existsSync(file) ? readFileSync(file, 'utf8') : ''
+	return file_reader.read_file_or_empty(file)
 }
 
 function build_lane(

package/scripts/lane/lane-registry.ts

@@ -1,10 +1,11 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { file_reader } from '#scripts/lib/read-file'
 import { lane_environment } from './lane-environment'
 import { lane_paths } from './lane-paths'
 
@@ -105,11 +106,7 @@ function held_seat(content: string | undefined): SeatPorts {
  * a state the report shows rather than a state anything falls back from.
  */
 function read_environment(directory: string): string | undefined {
-	try {
-		return readFileSync(path.join(directory, ENV_FILE_NAME), 'utf8')
-	} catch {
-		return undefined
-	}
+	return file_reader.read_if_readable(path.join(directory, ENV_FILE_NAME))
 }
 
 // A lane is identified by its branch rather than by where it sits, so nothing here compares two

package/scripts/lane/lane-report.ts

@@ -1,4 +1,5 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 import { run_liveness } from '#scripts/run/run-liveness'
 import type { LaneInfo } from './lane-registry'
 
@@ -48,9 +49,14 @@ function event_column(lane: LaneInfo): string {
 	return state ?? 'agent -'
 }
 
-function describe_lane(lane: LaneInfo): string {
+// The plain `#N`, for a caller that could not read the repository the issue would link into.
+const PLAIN_CITE: IssueCiter = issue_cite.citer(undefined, new Map())
+
+// The issue leads as a citation (joshuafolkken/kit#2943): a lane status report copies this row, and a
+// bare `#N` copied into it is what the Stop guard sends back.
+function describe_lane(lane: LaneInfo, cite: IssueCiter = PLAIN_CITE): string {
 	return [
-		`#${lane.issue}`,
+		cite(lane.issue),
 		`seat ${value_or_unknown(lane.seat)}`,
 		`dev ${value_or_unknown(lane.development_port)}`,
 		`preview ${value_or_unknown(lane.preview_port)}`,
@@ -63,10 +69,10 @@ function describe_lane(lane: LaneInfo): string {
 	].join(COLUMN_SEPARATOR)
 }
 
-function describe_lanes(lanes: ReadonlyArray<LaneInfo>): string {
+function describe_lanes(lanes: ReadonlyArray<LaneInfo>, cite: IssueCiter = PLAIN_CITE): string {
 	if (lanes.length === 0) return NO_LANES
 
-	return lanes.map((lane) => describe_lane(lane)).join('\n')
+	return lanes.map((lane) => describe_lane(lane, cite)).join('\n')
 }
 
 function describe_ports(lane: LaneInfo): string {

package/scripts/lib/cli-flags.ts

@@ -1,4 +1,6 @@
-// Argument refusal for the small flag-only commands.
+import { parseArgs, type ParseArgsConfig } from 'node:util'
+
+// Argument reading for the commands under `scripts/`.
 //
 // Reject anything not on the list rather than ignoring it: a misspelled `--dryrun` that fell through
 // would run the real write path. `josh propagate` and `josh adopt` both write into working trees, so
@@ -16,4 +18,20 @@ function refuse_unknown_flags(
 	return `Unknown argument(s): ${unknown.join(' ')}\n${usage}`
 }
 
-export { refuse_unknown_flags }
+// `parseArgs`, answering `undefined` where it would throw — an unknown flag, a missing option value,
+// or a positional the config does not allow. Each caller turns that into its usage line and a failure
+// exit rather than a stack trace, on commands whose output a workflow reads; eleven of them had begun
+// to carry a copy of the same try/catch each (joshuafolkken/kit#2902), and this is the one copy.
+function parse_or_undefined<T extends ParseArgsConfig>(
+	config: T,
+): ReturnType<typeof parseArgs<T>> | undefined {
+	try {
+		return parseArgs(config)
+	} catch {
+		return undefined
+	}
+}
+
+const cli_flags = { refuse_unknown_flags, parse_or_undefined }
+
+export { cli_flags }

package/scripts/lib/error-message.ts

@@ -0,0 +1,9 @@
+// The one place a caught value becomes the text a report shows: an `Error` contributes its own message,
+// anything else thrown is stringified as it stands.
+function message_of(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+const error_text = { message_of }
+
+export { error_text }

package/scripts/lib/read-file.ts

@@ -1,16 +1,40 @@
 import { readFileSync } from 'node:fs'
 
+const ABSENT_CODE = 'ENOENT'
+
+function is_absent(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === ABSENT_CODE
+}
+
+// An absent file is an answer ("nothing declared here"); any other failure — a permission error, a
+// directory where a file was expected — is not, and is thrown so it cannot pass for an empty file.
+function read_optional(path: string): string | undefined {
+	try {
+		return readFileSync(path, 'utf8')
+	} catch (error) {
+		if (is_absent(error)) return undefined
+
+		throw error
+	}
+}
+
 // Several readers treat an absent file as "nothing declared" rather than an error: a project may
 // carry no lockfile yet, and either overrides location may be missing entirely. Empty content is
 // the shared stand-in, so the callers do not each re-implement the try/catch.
 function read_file_or_empty(path: string): string {
+	return read_optional(path) ?? ''
+}
+
+// For a reader whose contract is to never fail — a hook running after a write already succeeded, a
+// report that states "unreadable" itself — every failure to read, not only absence, is `undefined`.
+function read_if_readable(path: string): string | undefined {
 	try {
 		return readFileSync(path, 'utf8')
 	} catch {
-		return ''
+		return undefined
 	}
 }
 
-const file_reader = { read_file_or_empty }
+const file_reader = { read_optional, read_file_or_empty, read_if_readable }
 
 export { file_reader }

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

@@ -1,40 +1,105 @@
-import { appendFile, mkdir } from 'node:fs/promises'
+import { appendFile, mkdir, readdir, readFile } 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 { git_branch } from '#scripts/git/git-branch'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } 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).
+// Where the observation ledger is read and written, whichever work tree a command runs in.
 //
-// **The ledger lives in the primary checkout, never in a lane.** A lane is a linked work tree that is
-// closed once its branch merges, and the ledger is excluded from ordinary staging — so a line appended
-// in a lane had no route to the default branch: `pnpm josh followup`'s flush needs `pnpm josh ms`,
-// which a lane refuses, and `lane:close` does not carry the file. Resolving the ledger to the primary
-// checkout at every reader and writer puts the line where the flush already works, rather than adding
-// a second route that moves it there afterwards.
-//
-// The primary checkout is `repo_discovery.main_worktree`'s answer, reused rather than spelled again;
-// in an ordinary checkout it is the given directory itself, so nothing outside a lane changes.
+// **The ledger lives in the work tree the command runs in — a lane's in a lane** (joshuafolkken/kit#2919).
+// It used to resolve to the primary checkout from every lane (joshuafolkken/kit#2419), so a lane's
+// lines waited there for a batch-end flush; another run's stash of that checkout took them, the flush
+// read `git status` and found nothing, and the lines were lost. Each run now appends to its own
+// issue's file in its own tree, `git-staging.ts` commits it with the run, and `pnpm josh followup`
+// commits whatever was appended after that commit before it merges — so a lane's lines reach the
+// default branch with the lane's own pull request, and the primary checkout holds none of them.
 
-function ledger_root(cwd: string = process.cwd()): string {
-	return repo_discovery.main_worktree(cwd)
-}
+const DATE_END = 10
 
-function is_lane(cwd: string = process.cwd()): boolean {
-	return path.resolve(ledger_root(cwd)) !== path.resolve(cwd)
+function ledger_root(cwd: string = process.cwd()): string {
+	return 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 {
+// **Resolving the directory migrates the single-file ledgers first** (joshuafolkken/kit#2724,
+// joshuafolkken/kit#2919). 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 a
+// directory without the lines that still sit at an old path, which for the review-record check would
+// answer `missing` for a round recorded before the move.
+function ledger_directory(cwd: string = process.cwd()): string {
 	const root = ledger_root(cwd)
 
 	observation_ledger_migrate.migrate(root)
 
-	return path.join(root, OBSERVATION_LEDGER_PATH)
+	return path.join(root, OBSERVATION_LEDGER_DIRECTORY)
+}
+
+function file_path(name: number | string, cwd: string): string {
+	ledger_directory(cwd)
+
+	return path.join(ledger_root(cwd), observation_ledger.ledger_file(name))
+}
+
+function issue_path(issue: number, cwd: string = process.cwd()): string {
+	return file_path(issue, cwd)
+}
+
+async function current_branch(cwd: string): Promise<string> {
+	try {
+		return await git_spawn.read(['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'])
+	} catch {
+		return ''
+	}
+}
+
+// **The file a writer that names no issue appends to** — the issue the checked-out branch leads with
+// (`2919-lane`, `2919-store-the-ledger`), so a lane's lines land in its own issue's file; or the date,
+// for a line written on the default branch outside any issue's run, which `pnpm josh
+// observations:flush` commits.
+async function writer_path(now: Date, cwd: string = process.cwd()): Promise<string> {
+	const issue = git_branch.issue_from_branch(await current_branch(cwd))
+
+	return file_path(issue ?? now.toISOString().slice(0, DATE_END), cwd)
+}
+
+// A file whose last line has no newline would otherwise run into the next file's first line.
+async function read_file(target: string): Promise<string> {
+	try {
+		const content = await readFile(target, 'utf8')
+
+		return content.length === 0 || content.endsWith('\n') ? content : `${content}\n`
+	} catch {
+		return ''
+	}
+}
+
+async function ledger_files(directory: string): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		const names = await readdir(directory)
+
+		return names
+			.filter((name) => observation_ledger.is_ledger_file_name(name))
+			.toSorted((left, right) => left.localeCompare(right))
+	} catch {
+		return undefined
+	}
+}
+
+// **Every file in the directory, read as one ledger**, in name order so the answer is stable. Readers
+// count across all of them — a recurrence is a recurrence whichever issue's file each line sits in.
+// `undefined` when there is no directory: a checkout that keeps no ledger, which `review:record
+// --check` turns into `not-required`.
+async function read(cwd: string = process.cwd()): Promise<string | undefined> {
+	const directory = ledger_directory(cwd)
+	const files = await ledger_files(directory)
+
+	if (files === undefined) return undefined
+
+	const contents = await Promise.all(
+		files.map(async (name) => await read_file(path.join(directory, name))),
+	)
+
+	return contents.join('')
 }
 
 // The one append every ledger writer goes through. A consumer that does not keep the ledger has no
@@ -47,6 +112,13 @@ async function append(target: string, lines: ReadonlyArray<string>): Promise<voi
 	await appendFile(target, `${lines.join('\n')}\n`, 'utf8')
 }
 
-const observation_ledger_home = { append, is_lane, ledger_path, ledger_root }
+const observation_ledger_home = {
+	append,
+	issue_path,
+	ledger_directory,
+	ledger_root,
+	read,
+	writer_path,
+}
 
 export { observation_ledger_home }

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

@@ -1,18 +1,20 @@
 import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import {
-	LEGACY_OBSERVATION_LEDGER_PATH,
+	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
-	OBSERVATION_LEDGER_PATH,
+	OBSERVATION_LEDGER_DIRECTORY,
 } from './observation-ledger'
 import { observation_ledger_line } from './observation-ledger-line'
 
-// Moves the ledger's lines from the path it had before joshuafolkken/kit#2724 to the one it has now
-// (`observation-ledger.ts` carries why both are recognized). Changing the constant alone split the
-// appends across two files: a run still on the old code recreated `docs/observations.md`, and a
-// consumer repository's existing ledger stayed where nothing read it. So resolving the ledger's path
-// migrates first (`observation-ledger-home.ts`), and whatever reached the old path lands at the tail
-// of the new one before anything reads or appends.
+// Moves the ledger's lines from the single files it was before joshuafolkken/kit#2919 into the
+// directory it is now, as `legacy.md` (`observation-ledger.ts` carries why the old paths are still
+// recognized). Changing a constant alone splits the appends: a run still on the old code recreates the
+// old file, and a consumer repository's existing ledger stays where nothing reads it. So resolving the
+// ledger migrates first (`observation-ledger-home.ts`), and whatever reached an old path lands in the
+// directory before anything reads or appends.
 //
 // **The old file is claimed with a rename before it is read.** Two sessions resolving the ledger at
 // once would otherwise both read it and both copy its lines — and a repeated line under one key is
@@ -83,14 +85,6 @@ function terminated(content: string): string {
 	return content.length === 0 || content.endsWith(NEWLINE) ? content : `${content}${NEWLINE}`
 }
 
-function read_or_undefined(file_path: string): string | undefined {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return undefined
-	}
-}
-
 // What of the claimed file goes to the ledger's tail: all of it, verbatim, when there is no ledger yet,
 // and otherwise only the lines the ledger does not already hold. **The old file can come back after
 // its lines were moved** — `git restore`, `git reset --hard` or a stash without `-u` restores a
@@ -108,7 +102,11 @@ function carried(content: string, ledger: string | undefined): string {
 // Moves one claimed file's lines to the tail of the ledger, then removes the claim.
 function absorb(claimed: string, target: string): void {
 	mkdirSync(path.dirname(target), { recursive: true })
-	appendFileSync(target, carried(readFileSync(claimed, 'utf8'), read_or_undefined(target)), 'utf8')
+	appendFileSync(
+		target,
+		carried(readFileSync(claimed, 'utf8'), file_reader.read_if_readable(target)),
+		'utf8',
+	)
 	rmSync(claimed)
 }
 
@@ -127,10 +125,7 @@ function absorb_stale(legacy: string, target: string): number {
 	return count
 }
 
-// Returns whether anything was moved. `root` is the checkout the ledger lives in.
-function migrate(root: string): boolean {
-	const legacy = path.join(root, LEGACY_OBSERVATION_LEDGER_PATH)
-	const target = path.join(root, OBSERVATION_LEDGER_PATH)
+function migrate_one(legacy: string, target: string): boolean {
 	const recovered = absorb_stale(legacy, target)
 	const claimed = claim_path(legacy)
 
@@ -141,6 +136,16 @@ function migrate(root: string): boolean {
 	return true
 }
 
+// Returns whether anything was moved. `root` is the checkout the ledger lives in. Every old path is
+// tried — `map` before `some`, so one that moved does not leave the next one where it was.
+function migrate(root: string): boolean {
+	const target = path.join(root, OBSERVATION_LEDGER_DIRECTORY, LEGACY_LEDGER_FILE)
+
+	return LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) =>
+		migrate_one(path.join(root, legacy), target),
+	).some(Boolean)
+}
+
 const observation_ledger_migrate = { claim_path, migrate }
 
 export { observation_ledger_migrate }