@joshuafolkken/kit 1.953.0 → 1.972.0

package/scripts/init/start-prompt.ts

@@ -0,0 +1,55 @@
+import path from 'node:path'
+import { stdin as input, stdout as output } from 'node:process'
+import { createInterface, type Interface } from 'node:readline/promises'
+import { ask_yes_no_simple } from '#scripts/git/git-prompt'
+import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
+import type { Consent, StartOptions } from './start-plan'
+
+interface Choices {
+	options: StartOptions
+	shape: ProjectShape
+	consent: Consent
+	root: string
+}
+
+const DECLINED =
+	'Stopped before creating the GitHub repository. Nothing was changed. Run josh init to set up without GitHub.'
+
+// The detected profile is the default, so pressing Enter accepts it; the reason is shown because an
+// ambiguous project is exactly the case this question exists for.
+async function ask_profile(prompt: Interface, shape: ProjectShape): Promise<ProjectProfile> {
+	const question = `Profile — static or node [${shape.profile}, ${shape.reason}]: `
+	const raw_answer = await prompt.question(question)
+	const answer = raw_answer.trim()
+	if (answer.length === 0) return shape.profile
+
+	return project_profile.requested_profile(['--profile', answer]) ?? shape.profile
+}
+
+async function ask_repository(prompt: Interface, choices: Choices): Promise<void> {
+	const name = path.basename(choices.root)
+	const question = `Create a ${choices.options.visibility} GitHub repository "${name}" and push main? (y/n): `
+
+	if (!(await ask_yes_no_simple(prompt, question))) throw new Error(DECLINED)
+}
+
+async function ask_choices(prompt: Interface, choices: Choices): Promise<ProjectProfile> {
+	const profile = choices.options.profile ?? (await ask_profile(prompt, choices.shape))
+	if (choices.consent === 'ask') await ask_repository(prompt, choices)
+
+	return profile
+}
+
+async function confirm_choices(choices: Choices): Promise<ProjectProfile> {
+	const prompt = createInterface({ input, output })
+
+	try {
+		return await ask_choices(prompt, choices)
+	} finally {
+		prompt.close()
+	}
+}
+
+const start_prompt = { confirm_choices }
+export { start_prompt }
+export type { Choices }

package/scripts/init/start-steps.ts

@@ -0,0 +1,167 @@
+import path from 'node:path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { WORKFLOW_LABELS } from '#scripts/git/issue-labels'
+import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
+import { execaSync } from 'execa'
+import { main as init_main } from './init'
+import { PACKAGE_DIR } from './init-paths'
+import type { ProjectProfile, ProjectShape } from './project-profile'
+import { start_plan, type GitState, type StartStep, type Visibility } from './start-plan'
+
+interface StepContext {
+	root: string
+	profile: ProjectProfile
+	visibility: Visibility
+}
+
+type WorkflowLabel = (typeof WORKFLOW_LABELS)[number]
+
+const DEFAULT_BRANCH = 'main'
+const LABELS_ENDPOINT = 'repos/{owner}/{repo}/labels'
+const GH_INSTALL_HINT =
+	'GitHub CLI (gh) is not installed. Install it from https://cli.github.com/, run gh auth login, then run josh start again. Nothing was changed.'
+const GH_AUTH_HINT =
+	'GitHub CLI is not signed in. Run gh auth login, then run josh start again. Nothing was changed.'
+
+function succeeds(command: string, args: ReadonlyArray<string>, root: string): boolean {
+	return execaSync(command, args, { cwd: root, reject: false }).exitCode === 0
+}
+
+function read_output(
+	command: string,
+	args: ReadonlyArray<string>,
+	root: string,
+): string | undefined {
+	const result = execaSync(command, args, { cwd: root, reject: false })
+
+	return result.exitCode === 0 ? result.stdout.trim() : undefined
+}
+
+// Every step spawned here dials GitHub directly, past a scanner's loopback proxy, the same as every
+// other `gh` spawn under scripts/ (joshuafolkken/kit#2436); a local `git` step is unaffected by it.
+function run(command: string, args: ReadonlyArray<string>, root: string): void {
+	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
+}
+
+function read_git_state(root: string, shape: ProjectShape): GitState {
+	const { has_git, has_github } = shape
+
+	if (!has_git) {
+		return { has_git, has_github, has_origin: false, branch: undefined, has_commits: false }
+	}
+
+	const has_origin = succeeds('git', ['remote', 'get-url', 'origin'], root)
+	const branch = read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
+	const has_commits = succeeds('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], root)
+
+	return { has_git, has_github, has_origin, branch, has_commits }
+}
+
+// Every step talks to GitHub, so the CLI is checked before the first write rather than at the step
+// that needs it — a missing `gh` then leaves the directory exactly as it was.
+function github_cli_refusal(root: string): string | undefined {
+	if (!succeeds('gh', ['--version'], root)) return GH_INSTALL_HINT
+	if (!succeeds('gh', ['auth', 'status'], root)) return GH_AUTH_HINT
+
+	return undefined
+}
+
+// `josh init` refuses to run inside the kit source repository by printing and setting the exit code
+// rather than throwing, so its step would pass and the later steps would commit and publish the
+// source repository. The same check is raised before the first write instead.
+function self_run_refusal(root: string): string | undefined {
+	return self_sync_guard.self_sync_refusal(PACKAGE_DIR, root)
+}
+
+function create_git_repository(context: StepContext): void {
+	run('git', ['init', `--initial-branch=${DEFAULT_BRANCH}`], context.root)
+}
+
+// The same setup `josh init` runs, called rather than copied, with the profile the user confirmed.
+function initialize(context: StepContext): void {
+	init_main(['--profile', context.profile])
+}
+
+function commit_all(context: StepContext): void {
+	run('git', ['add', '--all'], context.root)
+	// The first commit of a new repository has no branch to come from, so the hook that keeps commits
+	// off main — installed by the initialize step in a node project — would refuse the only commit
+	// that has to land there.
+	run('git', ['commit', '--no-verify', '--message', 'Initial commit'], context.root)
+	// A repository created by an older `git init` may name its unborn branch `master`.
+	run('git', ['branch', '--move', '--force', DEFAULT_BRANCH], context.root)
+}
+
+function create_github_repository(context: StepContext): void {
+	const name = path.basename(context.root)
+	const visibility = `--${context.visibility}`
+	const source = ['--source', '.', '--remote', 'origin', '--push']
+
+	run('gh', ['repo', 'create', name, visibility, ...source], context.root)
+}
+
+// Labels already present are left as they are — only the missing ones are created, so a repository
+// that recolored a label keeps its choice. GitHub compares label names case-insensitively.
+function missing_workflow_labels(existing: ReadonlyArray<string>): ReadonlyArray<WorkflowLabel> {
+	const names = new Set(existing.map((name) => name.toLowerCase()))
+
+	return WORKFLOW_LABELS.filter((label) => !names.has(label.name))
+}
+
+function create_label(label: WorkflowLabel, root: string): void {
+	const fields = [`name=${label.name}`, `color=${label.color}`, `description=${label.description}`]
+
+	run('gh', ['api', LABELS_ENDPOINT, ...fields.flatMap((field) => ['-f', field]), '--silent'], root)
+	console.info(`  ✔ label ${label.name}`)
+}
+
+function add_missing_labels(context: StepContext): void {
+	const listing = execaSync('gh', ['api', '--paginate', LABELS_ENDPOINT, '--jq', '.[].name'], {
+		...git_gh_exec.direct_environment(),
+		cwd: context.root,
+	})
+	const existing = listing.stdout.split('\n').filter((name) => name.length > 0)
+
+	for (const label of missing_workflow_labels(existing)) create_label(label, context.root)
+}
+
+const STEP_ACTIONS: Readonly<Record<StartStep, (context: StepContext) => void>> = {
+	git_init: create_git_repository,
+	initialize,
+	commit: commit_all,
+	repository: create_github_repository,
+	labels: add_missing_labels,
+}
+
+function run_step(
+	step: StartStep,
+	context: StepContext,
+	completed: ReadonlyArray<StartStep>,
+): void {
+	try {
+		STEP_ACTIONS[step](context)
+	} catch (error) {
+		const cause = error instanceof Error ? error.message : String(error)
+
+		throw new Error(start_plan.progress_report(step, completed, cause), { cause: error })
+	}
+}
+
+function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext): void {
+	for (const [index, step] of steps.entries()) {
+		const position = `${String(index + 1)}/${String(steps.length)}`
+
+		console.info(`\n[${position}] ${start_plan.STEP_LABELS[step]}`)
+		run_step(step, context, steps.slice(0, index))
+	}
+}
+
+const start_steps = {
+	read_git_state,
+	github_cli_refusal,
+	self_run_refusal,
+	missing_workflow_labels,
+	run_steps,
+}
+export { start_steps }
+export type { StepContext }

package/scripts/init/start.ts

@@ -1,30 +1,106 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { main as init_main } from './init'
-import { project_profile, type ProjectShape } from './project-profile'
+import { project_profile, type ProjectProfile } from './project-profile'
+import {
+	start_plan,
+	type Consent,
+	type Interaction,
+	type StartOptions,
+	type StartStep,
+} from './start-plan'
+import { start_prompt, type Choices } from './start-prompt'
+import { start_steps } from './start-steps'
 
 const ARGUMENT_START_INDEX = 2
+const READY_MESSAGE = 'GitHub workflow ready. Use kickoff new in your assistant to plan an Issue.'
+const START_USAGE = 'josh start [--profile static|node] [--yes] [--github] [--public]'
+const YES_FLAG = '--yes'
+const GITHUB_FLAG = '--github'
+const PUBLIC_FLAG = '--public'
+const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG])
 
-function prerequisite(shape: ProjectShape): string | undefined {
-	if (!shape.has_git) return 'josh start requires Git. Run git init, or use josh init without Git.'
-	if (!shape.has_github) return 'josh start requires a GitHub origin. Add one, or use josh init.'
+interface Prepared {
+	steps: ReadonlyArray<StartStep>
+	interaction: Interaction
+	choices: Choices
+}
+
+// The switches are peeled off first, so what remains is exactly the `--profile` pair `josh init`
+// accepts — one parser for the profile in both commands.
+function parse_start_options(args: ReadonlyArray<string>): StartOptions {
+	const profile_args = args.filter((argument) => !SWITCHES.has(argument))
+
+	return {
+		profile: project_profile.requested_profile(profile_args, START_USAGE),
+		is_yes: args.includes(YES_FLAG),
+		is_github: args.includes(GITHUB_FLAG),
+		visibility: args.includes(PUBLIC_FLAG) ? 'public' : 'private',
+	}
+}
+
+function settle<T>(verdict: { value: T | undefined; refusal: string | undefined }): T {
+	if (verdict.value === undefined) throw new Error(verdict.refusal)
 
-	return undefined
+	return verdict.value
 }
 
-function main(args: ReadonlyArray<string> = []): void {
-	// --profile uses the same override as josh init.
-	const requested = project_profile.requested_profile(args)
-	const shape = project_profile.inspect_project(process.cwd(), requested)
-	const message = prerequisite(shape)
-	if (message !== undefined) throw new Error(message)
-	init_main(args)
-	console.info('GitHub workflow ready. Use kickoff in your assistant to plan an Issue.')
+function stop_on(refusal: string | undefined): void {
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+// An unattended run already holds every answer: `--profile` or the detected one, and a consent that
+// `github_consent` only grants when `--github` was given.
+async function resolve_profile(
+	choices: Choices,
+	interaction: Interaction,
+): Promise<ProjectProfile> {
+	if (interaction === 'unattended') return choices.options.profile ?? choices.shape.profile
+
+	return await start_prompt.confirm_choices(choices)
+}
+
+// Every refusal is raised here, before the first write, so a run that stops here changed nothing.
+function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Prepared {
+	stop_on(start_steps.self_run_refusal(root))
+	const options = parse_start_options(args)
+	const interaction = settle(start_plan.interaction_of(options, is_tty))
+	const shape = project_profile.inspect_project(root, options.profile)
+	const plan = start_plan.plan_steps(start_steps.read_git_state(root, shape))
+
+	stop_on(plan.refusal)
+	const consent: Consent = settle(start_plan.github_consent(plan.steps, options, interaction))
+
+	stop_on(start_steps.github_cli_refusal(root))
+
+	return { steps: plan.steps, interaction, choices: { options, shape, consent, root } }
+}
+
+async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
+	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
+
+	console.info(start_plan.plan_summary(steps))
+	const profile = await resolve_profile(choices, interaction)
+	const { root, options } = choices
+
+	start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
+	console.info(`\n${READY_MESSAGE}`)
+}
+
+async function run(args: ReadonlyArray<string>, is_tty: boolean): Promise<number> {
+	try {
+		await main(args, is_tty)
+
+		return 0
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return 1
+	}
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	main(process.argv.slice(ARGUMENT_START_INDEX))
+	process.exitCode = await run(process.argv.slice(ARGUMENT_START_INDEX), process.stdin.isTTY)
 }
 
-const start = { prerequisite }
+const start = { run, parse_start_options }
 export { start }

package/scripts/issue/issue-closing-pr.ts

@@ -0,0 +1,93 @@
+import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
+import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_repo } from '#scripts/git/git-gh-repo'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// **The merged pull request that closes an issue GitHub left open** (joshuafolkken/kit#2769). A
+// `backlogrun` child whose pull request merged while GitHub did not apply its `closes #N`
+// (joshuafolkken/kit#2770) came back OPEN, and `run:merge` counted it a failure and parked it — the
+// work had landed, only the issue's close had not.
+//
+// **A merged reference is not enough; the body must close this issue.** A merged pull request that
+// merely mentions the issue — a follow-up, a sibling in the same epic — cross-references it too, and
+// closing on that would close unfinished work. So the pull request counts only when its body's
+// `closes #N` names this issue, read through the one parser every `closes #N` reader shares.
+//
+// **Only references after the last reopen count.** A reopened issue whose earlier attempt merged
+// still carries that pull request's reference, and reading it would close the reopened work — the
+// same reason `issue-merged.ts` reads the last closed/reopened event.
+//
+// **Only a pull request in this repository counts.** A bare `closes #N` names an issue in the pull
+// request's own repository, so a merged pull request elsewhere whose `closes #N` carries the same
+// number closes a different issue — its cross-reference here is a mention, not a close.
+
+const LINE_SEPARATOR = '\n'
+// One compact JSON object per merged pull request that cross-references the issue, and a
+// `{"reopened":true}` marker per reopen, in timeline order.
+const TIMELINE_FILTER = [
+	'.[]',
+	'| if .event == "cross-referenced" and .source.issue.pull_request.merged_at != null',
+	'then {url: .source.issue.html_url, repo: .source.issue.repository.full_name, body: (.source.issue.body // "")}',
+	'elif .event == "reopened" then {reopened: true}',
+	'else empty end',
+].join(' ')
+
+const reference_schema = z.object({ url: z.string(), repo: z.string(), body: z.string() })
+const reopen_schema = z.object({ reopened: z.literal(true) })
+const row_schema = z.union([reference_schema, reopen_schema])
+
+type MergedReference = z.infer<typeof reference_schema>
+type TimelineRow = z.infer<typeof row_schema>
+
+function is_reference(row: TimelineRow): row is MergedReference {
+	return 'url' in row
+}
+
+function parse_references(raw: string): Array<MergedReference> {
+	const rows = raw
+		.split(LINE_SEPARATOR)
+		.map((line) => parse_json_object_safe(line, row_schema))
+		.filter((row) => row !== undefined)
+	const last_reopen = rows.findLastIndex((row) => !is_reference(row))
+
+	return rows.slice(last_reopen + 1).filter((row) => is_reference(row))
+}
+
+function pick_closing_pr(
+	references: ReadonlyArray<MergedReference>,
+	issue: string,
+	repo: string,
+): string | undefined {
+	return references.find(
+		(reference) =>
+			reference.repo === repo &&
+			git_closes_keyword.parse_closes_issue_number(reference.body) === issue,
+	)?.url
+}
+
+// Every doubt falls to `undefined` — an unreadable timeline or repository name leaves the child
+// judged as it was, never closed on a guess.
+async function read_closing_pr(issue: string): Promise<string | undefined> {
+	try {
+		const [raw, repo] = await Promise.all([
+			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,
+			}),
+			git_gh_repo.repo_get_name_with_owner(),
+		])
+
+		if (repo === undefined) return undefined
+
+		return pick_closing_pr(parse_references(raw), issue, repo)
+	} catch {
+		return undefined
+	}
+}
+
+const issue_closing_pr = { parse_references, pick_closing_pr, read_closing_pr }
+
+export { issue_closing_pr }

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

@@ -449,10 +449,11 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "init": [
-      "[--profile static|node]",
+      "[--profile static|node] [--no-install]",
       "developer",
       [
         "files",
+        "network",
         "processes",
       ],
     ],
@@ -1103,12 +1104,13 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "start": [
-      "[--profile static|node]",
+      "[--profile static|node] [--yes] [--github] [--public]",
       "developer",
       [
         "files",
         "git",
         "network",
+        "processes",
       ],
     ],
     "stash:pop": [

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

@@ -14,15 +14,23 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 	},
 	start: {
 		script: 'scripts/init/start.ts',
-		description: 'Initialize a project for the GitHub Issue workflow',
+		description: 'Create a new project for the GitHub Issue workflow, from git init to labels',
 		category: 'Project',
-		reference: [PROFILE_ARGUMENTS, 'developer', ['files', 'git', 'network']],
+		reference: [
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public]`,
+			'developer',
+			['files', 'git', 'network', 'processes'],
+		],
 	},
 	init: {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',
 		category: 'Project',
-		reference: [PROFILE_ARGUMENTS, 'developer', ['files', 'processes']],
+		reference: [
+			`${PROFILE_ARGUMENTS} [--no-install]`,
+			'developer',
+			['files', 'network', 'processes'],
+		],
 	},
 	sync: {
 		script: 'scripts/sync/sync.ts',

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

@@ -52,9 +52,9 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
-	// The observation ledger's only commit path (joshuafolkken/kit#1756). `pnpm josh git` excludes the
-	// ledger from what it stages, so without this command a parent's appended line has no route to the
-	// default branch at all — and the recurrence count the promotion rule reads is a count of main.
+	// The observation ledger's commit path for the lines no run's own commit carried
+	// (joshuafolkken/kit#1756, joshuafolkken/kit#2763): a lane's lines sit in the primary checkout, which
+	// its commit cannot see, and the recurrence count the promotion rule reads is a count of main.
 	'observations:flush': {
 		script: 'scripts/observations/observations-flush-cli.ts',
 		description: 'Commit the observation ledger as a pull request of its own, and merge it',

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

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
+import { observation_ledger_migrate } from './observation-ledger-migrate'
+
+// **What has to hold before a ledger line is committed, asked by both of the paths that commit one**
+// (joshuafolkken/kit#2763): `pnpm josh observations:flush` and the run's own commit in
+// `scripts/git/git-staging.ts`. Lines still on the old path are moved first (joshuafolkken/kit#2724),
+// so the commit carries the move and the lines together, and every entry line is then parsed against
+// the grammar (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
+//
+// **A ledger that is not there has no line to break** — the change a status saw is then its deletion,
+// and a commit carries that like any other change to it.
+async function read_ledger(root: string): Promise<string> {
+	try {
+		return await readFile(path.join(root, OBSERVATION_LEDGER_PATH), 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+async function prepare(root: string): Promise<ReadonlyArray<BrokenLine>> {
+	observation_ledger_migrate.migrate(root)
+
+	return observation_ledger_line.broken_ledger_lines(await read_ledger(root))
+}
+
+const observation_ledger_prepare = { prepare }
+
+export { observation_ledger_prepare }

package/scripts/observations/observation-ledger.ts

@@ -1,9 +1,8 @@
 // The observation ledger's one path, named here rather than inside any of the places that act on it
-// (joshuafolkken/kit#1756). `git-staging.ts` excludes it from every ordinary commit,
-// `hook-gate-reuse.ts` excludes it from what a hook calls a carried tree, and
-// `observations-flush.ts` is the only thing that stages it — so a literal in each would be three
-// answers to one question, and a rename reaching only some of them would silently restore the
-// contamination the exclusion exists to prevent.
+// (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
+// holds (joshuafolkken/kit#2763), `hook-gate-reuse.ts` excludes it from what a hook calls a carried
+// tree, and `observations-flush.ts` commits what no run carried — so a literal in each would be three
+// answers to one question, and a rename reaching only some of them would silently split them.
 //
 // **It sits under `docs/maintainers/`, apart from the reader-facing documents** (joshuafolkken/kit#2724).
 const OBSERVATION_LEDGER_PATH = 'docs/maintainers/observations.md'
@@ -70,6 +69,7 @@ const observation_ledger = {
 	has_pending_append,
 	is_ledger_line,
 	is_ledger_path,
+	is_migration_claim,
 	ledger_paths,
 	status_path,
 }

package/scripts/observations/observations-flush.ts

@@ -1,17 +1,15 @@
-import { readFile } from 'node:fs/promises'
 import { git_command } from '#scripts/git/git-command'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { main_sync } from '#scripts/git/main-sync'
 import { observation_ledger, OBSERVATION_LEDGER_PATH } from './observation-ledger'
-import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
-import { observation_ledger_migrate } from './observation-ledger-migrate'
+import type { BrokenLine } from './observation-ledger-line'
+import { observation_ledger_prepare } from './observation-ledger-prepare'
 import { observations_flush_landing } from './observations-flush-landing'
 
-// The commit path the observation ledger did not have (joshuafolkken/kit#1756). The parent session
-// that appends a line never runs `pnpm josh git`; a child runs it inside a lane work tree, which
-// cannot see the parent's checkout at all; and in the primary checkout `git add -u` swept the line
-// into whatever unrelated pull request that run was opening. So the ledger is excluded from ordinary
-// staging (`scripts/git/git-staging.ts`) and this is the one thing that stages it.
+// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). A run in
+// the primary checkout commits its appended lines with its own pull request (`scripts/git/
+// git-staging.ts`, joshuafolkken/kit#2763), so what is left here is a lane's lines — they sit in the
+// primary checkout, which a lane's commit cannot see — and whatever was appended after a commit.
 //
 // **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
@@ -57,7 +55,7 @@ function branch_name_for(stamp: string): string {
 // single issue, and the ledger's own lines say where each one was seen.
 function pull_request_body(): string {
 	return [
-		`Appended observations from \`${OBSERVATION_LEDGER_PATH}\`, which \`pnpm josh git\` never stages.`,
+		`Appended observations from \`${OBSERVATION_LEDGER_PATH}\` that no run's own commit carried.`,
 		'',
 		'The ledger is append-only, and a second line under one key is what promotes an observation to an issue — so this pull request adds lines and changes none.',
 		'',
@@ -373,31 +371,14 @@ function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 
 // **A malformed line is refused before a branch is cut, not after.** The ledger path was collected
 // without a line ever being parsed (joshuafolkken/kit#2123), so a broken append could ride a flush
-// through; validating here keeps the committed ledger to its grammar.
-//
-// **A ledger that is not there has no line to break** — the change the status saw is then its
-// deletion, and a flush commits that like any other change to it.
-async function read_ledger(): Promise<string> {
-	try {
-		return await readFile(OBSERVATION_LEDGER_PATH, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-async function refuse_broken_ledger(): Promise<void> {
-	const broken = observation_ledger_line.broken_ledger_lines(await read_ledger())
+// through; validating here keeps the committed ledger to its grammar. The migration and the parse are
+// `observation-ledger-prepare.ts`'s, shared with the run's own commit (joshuafolkken/kit#2763).
+async function prepare_ledger(): Promise<void> {
+	const broken = await observation_ledger_prepare.prepare(process.cwd())
 
 	if (broken.length > 0) throw new Error(broken_lines_message(broken))
 }
 
-// Lines still on the ledger's old path are moved before anything is validated or staged
-// (joshuafolkken/kit#2724), so the flush commits the move and the lines together.
-async function prepare_ledger(): Promise<void> {
-	observation_ledger_migrate.migrate(process.cwd())
-	await refuse_broken_ledger()
-}
-
 // **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