@joshuafolkken/kit 1.1010.0 → 1.1035.0

package/scripts/{git/git-epic-validate.ts → epic/epic-validate.ts}

@@ -1,19 +1,19 @@
-import { git_epic_parse, type DeclarationState } from './git-epic-parse'
-import { EPIC_LABEL, has_label_name } from './issue-labels'
-import { parse_json_object_safe } from './parse-json-array'
-import { epic_subject_schema } from './schemas'
+import { EPIC_LABEL, has_label_name } from '#scripts/git/issue-labels'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { epic_subject_schema } from '#scripts/git/schemas'
+import { epic_parse, type DeclarationState } from './epic-parse'
 
 // The four requirements an epic has to satisfy are otherwise enforced only by an agent reading the
 // procedure carefully, and three of the four fail silently: a missing label or a bare `#N` child
-// list makes `git-epic-close.ts` skip the epic forever, and prose dependencies make the batch read
+// list makes `epic-close.ts` skip the epic forever, and prose dependencies make the batch read
 // as unordered so a skipped `--add-blocked-by` is never reported. Checking them here reuses
-// `git-epic-parse.ts` rather than restating the patterns, so "what the auto-close can read" and
+// `epic-parse.ts` rather than restating the patterns, so "what the auto-close can read" and
 // "what this check accepts" are one definition instead of two that can drift.
 
 interface EpicSubject {
 	number: number
 	// The epic's own state, as GitHub returned it (`OPEN` / `CLOSED`, casing unnormalized). Only
-	// `git-epic-add.ts` reads it — to refuse adding a child to a closed epic — so it is optional: a read
+	// `epic-add.ts` reads it — to refuse adding a child to a closed epic — so it is optional: a read
 	// that came back without the field leaves it undefined, which the refusal treats as "not confirmed
 	// closed" rather than blocking (joshuafolkken/kit#2337).
 	state?: string | undefined
@@ -65,7 +65,7 @@ function format_children(children: ReadonlyArray<number>): string {
 }
 
 function check_task_list(subject: EpicSubject): CheckResult {
-	const children = git_epic_parse.parse_task_list_issue_numbers(subject.body)
+	const children = epic_parse.parse_task_list_issue_numbers(subject.body)
 	const is_passing = children.length > 0
 
 	return {
@@ -94,11 +94,11 @@ function describe_dependencies(state: DeclarationState): string {
 // each of them. The literal is compared against the constant the generator emits, and the chain
 // against the one the link reader parses, so no two of them can drift into disagreement.
 function check_dependencies(subject: EpicSubject): CheckResult {
-	const state = git_epic_parse.read_declaration(subject.body)
+	const state = epic_parse.read_declaration(subject.body)
 
 	return {
 		name: 'dependencies section',
-		is_passing: git_epic_parse.is_declaration_readable(state),
+		is_passing: epic_parse.is_declaration_readable(state),
 		detail: describe_dependencies(state),
 	}
 }
@@ -107,7 +107,7 @@ function check_dependencies(subject: EpicSubject): CheckResult {
 // deliberately leaves such an epic open. Reporting it here is what turns "stayed open silently"
 // into "was told to close it manually".
 function check_external_children(subject: EpicSubject): CheckResult {
-	const has_external = git_epic_parse.has_external_task_list_entry(subject.body)
+	const has_external = epic_parse.has_external_task_list_entry(subject.body)
 
 	return {
 		name: 'auto-close eligibility',
@@ -144,12 +144,12 @@ function format_check_report(epic_number: number, results: ReadonlyArray<CheckRe
 	return [...lines, '', summary].join('\n')
 }
 
-const git_epic_validate = {
+const epic_validate = {
 	parse_epic_subject,
 	validate_epic,
 	is_epic_valid,
 	format_check_report,
 }
 
-export { git_epic_validate }
+export { epic_validate }
 export type { CheckResult, EpicSubject }

package/{scripts-ai → scripts/epic}/epic.ts

@@ -2,19 +2,20 @@
 /**
  * Create an epic Issue that satisfies every requirement the auto-close and the order warning read.
  *
- * Usage: tsx scripts-ai/epic.ts "<title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->]
+ * Usage: tsx scripts/epic/epic.ts "<title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->]
  *                                                       [--origin <owner/repo#N>]
- *        tsx scripts-ai/epic.ts --promote <N> <N1> <N2> ... [same flags]
- *        tsx scripts-ai/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
+ *        tsx scripts/epic/epic.ts --promote <N> <N1> <N2> ... [same flags]
+ *        tsx scripts/epic/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
  *                                                      [--decision-file <path|->]
- *        tsx scripts-ai/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
+ *        tsx scripts/epic/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
  */
-import { git_epic_add, type AddChildrenInput } from '../scripts/git/git-epic-add'
-import { git_epic_reconcile } from '../scripts/git/git-epic-reconcile'
-import { git_epic_remove } from '../scripts/git/git-epic-remove'
-import { git_epic_run } from '../scripts/git/git-epic-run'
-import { git_gh_command } from '../scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { error_text } from '#scripts/lib/error-message'
+import { epic_add, type AddChildrenInput } from './epic-add'
 import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'
+import { epic_reconcile } from './epic-reconcile'
+import { epic_remove } from './epic-remove'
+import { epic_run } from './epic-run'
 
 const ARGV_OFFSET = 2
 const FLAGS = '[--ordered] [--rationale-file <path|->] [--origin <owner/repo#N>]'
@@ -37,7 +38,7 @@ async function run_promotion(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_run.promote_epic({
+	return await epic_run.promote_epic({
 		epic_number: parsed.epic_number,
 		children: parsed.children,
 		rationale: epic_cli.read_rationale(parsed.rationale_path),
@@ -67,7 +68,7 @@ function to_add_input(parsed: AddArguments): AddChildrenInput {
 async function run_qualified_addition(found: CrossRepoAddTarget): Promise<number> {
 	const local = epic_cli.resolve_local_add(found, await git_gh_command.repo_get_name_with_owner())
 
-	if (local !== undefined) return await git_epic_add.add_children(to_add_input(local))
+	if (local !== undefined) return await epic_add.add_children(to_add_input(local))
 
 	console.error(epic_cli.format_cross_repo_refusal(found))
 
@@ -109,7 +110,7 @@ async function run_addition(argv: ReadonlyArray<string>): Promise<number> {
 
 	if (parsed === undefined) return await refuse_addition(argv)
 
-	return await git_epic_add.add_children(to_add_input(parsed))
+	return await epic_add.add_children(to_add_input(parsed))
 }
 
 // Deleting a declared order. No position and no `--ordered`: the path itself says which orders go,
@@ -126,7 +127,7 @@ async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_remove.remove_order({
+	return await epic_remove.remove_order({
 		epic_number: parsed.epic_number,
 		path: parsed.path,
 		decision: epic_cli.read_decision(parsed.decision_path),
@@ -144,7 +145,7 @@ async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number>
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_reconcile.reconcile_epic(parsed.epic_number)
+	return await epic_reconcile.reconcile_epic(parsed.epic_number)
 }
 
 async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
@@ -156,7 +157,7 @@ async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_run.create_epic({
+	return await epic_run.create_epic({
 		title: parsed.title,
 		children: parsed.children,
 		rationale: epic_cli.read_rationale(parsed.rationale_path),
@@ -187,6 +188,6 @@ async function main(): Promise<void> {
 try {
 	await main()
 } catch (error) {
-	console.error(`✖ ${error instanceof Error ? error.message : String(error)}`)
+	console.error(`✖ ${error_text.message_of(error)}`)
 	process.exit(FAILURE_EXIT_CODE)
 }

package/scripts/gh/fix-gh-packages.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
 import { z } from 'zod'
 import { fix_gh_packages_logic, type LockfilePackage } from './fix-gh-packages-logic'
 import { gh_cli_token } from './gh-cli-token'
@@ -19,7 +20,7 @@ const npm_packument_schema = z.looseObject({
 type ParsedPackages = Record<string, LockfilePackage>
 
 function read_file(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(file_path)
 }
 
 // Resolution order: NODE_AUTH_TOKEN → a literal token in the project .npmrc → `gh auth token`.

package/scripts/gh/gh-spawn.ts

@@ -1,27 +1,29 @@
 import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { execaSync } from 'execa'
 
 // The synchronous twin of `git_gh_repo.repo_get_name_with_owner`: same fact, read the same way, but
-// through `execaSync` because `josh init` / `josh sync` / `josh doctor` decide before they can await.
+// synchronously because `josh init` / `josh sync` / `josh doctor` decide before they can await.
 // It asks REST for the same reason — `gh repo view` goes through GraphQL, which a cloud session is
 // refused (403), and a repository that reads as unresolved makes `init` / `sync` skip
 // `sonar-project.properties` outright (joshuafolkken/kit#1023). The path comes from the shared
 // builder rather than being spelled out again here.
 //
-// `timeout` is spread in rather than passed as `undefined`: execa's options type does not admit an
-// undefined value for it, and an explicit `undefined` would not mean "no timeout" anyway.
+// An unbounded lookup asks for `NO_BUDGET`, execa's own "no timeout": the shared layer otherwise
+// applies its default budget, which would change what `init` / `sync` wait for.
+const NO_BUDGET = 0
+
 function fetch_repo_name(timeout_ms: number | undefined): string | undefined {
-	const result = execaSync('gh', ['api', git_gh_api_path.repo_api_path(), '--jq', '.full_name'], {
-		...git_gh_exec.direct_environment(),
+	const stdout = git_gh_exec.read_gh_api_sync({
+		path: git_gh_api_path.repo_api_path(),
+		jq_filter: '.full_name',
 		cwd: PROJECT_ROOT,
-		reject: false,
-		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+		timeout_ms: timeout_ms ?? NO_BUDGET,
 	})
-	if (result.exitCode !== 0 || !result.stdout) return undefined
 
-	return result.stdout.trim() || undefined
+	const name = stdout?.trim()
+
+	return name === '' ? undefined : name
 }
 
 // The unbounded lookup, for callers whose *writes* depend on the answer. A timeout would surface as

package/scripts/git/constants.ts

@@ -10,7 +10,7 @@ const GIT_COMMAND_UNIX = '/usr/bin/git'
 // modules (joshuafolkken/kit#1640) and a copy in each is a second answer to one question.
 const PORCELAIN_FLAG = '--porcelain'
 // The untracked-files mode every porcelain status reading passes (`git-command.ts` carries why it is
-// passed and why it is `all`), shared so `run-carry-flush.ts`'s own reading cannot drift from it.
+// passed and why it is `all`), shared so another module's own reading cannot drift from it.
 const UNTRACKED_FILES_FLAG = '--untracked-files=all'
 
 function get_git_command(): string {

package/scripts/git/git-branch.ts

@@ -75,7 +75,7 @@ async function pull_latest(): Promise<void> {
 	)
 }
 
-const ISSUE_PREFIX_PATTERN = /^\d+-/u
+const ISSUE_PREFIX_PATTERN = /^(\d+)-/u
 
 function has_same_issue_prefix(branch_a: string, branch_b: string): boolean {
 	const prefix_a = ISSUE_PREFIX_PATTERN.exec(branch_a)?.[0]
@@ -84,6 +84,14 @@ function has_same_issue_prefix(branch_a: string, branch_b: string): boolean {
 	return prefix_a !== undefined && prefix_a === prefix_b
 }
 
+// The issue a branch names, or `undefined` when it does not lead with one — `1937-lane` and
+// `1937-add-a-scope` both read 1937, while `main` reads nothing.
+function issue_from_branch(branch: string): number | undefined {
+	const digits = ISSUE_PREFIX_PATTERN.exec(branch)?.[1]
+
+	return digits === undefined ? undefined : Number(digits)
+}
+
 // The one rule `check_and_create_branch` refuses on, kept pure so `git-preflight.ts` asks it before
 // anything is pulled, switched or staged.
 function is_mismatch(
@@ -133,6 +141,7 @@ const git_branch = {
 	// second copy of the pattern (joshuafolkken/kit#1497). A copy is what let `lane/<N>` ship: nothing
 	// asserted that the name `lane:open` writes is one this function accepts.
 	has_same_issue_prefix,
+	issue_from_branch,
 }
 
 export { git_branch }

package/scripts/git/git-command.ts

@@ -411,7 +411,7 @@ async function push(): Promise<void> {
 // the same thing: it is on the default branch, bringing it up to date before doing something else —
 // `main-sync.ts` for `josh ms`, `release-cli.ts` / `release-publish.ts` around the release pull
 // request, `scripts-ai/prep.ts` before it snapshots the overrides, and `git-branch.ts` →
-// `pull_latest` — reached from `scripts-ai/git-workflow.ts`, so it runs on every `josh git` /
+// `pull_latest` — reached from `git-workflow.ts`, so it runs on every `josh git` /
 // `josh pr` started from the default branch, which makes it the hottest of the five rather than a
 // dormant one. **None of them is
 // asking to absorb divergence**, so `merge_branch`'s reasoning inverts here: a default branch that

package/scripts/git/git-error.ts

@@ -1,9 +1,6 @@
+import { error_text } from '#scripts/lib/error-message'
 import { has_stderr_field } from './git-gh-exec'
 
-function get_error_message(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 function get_stderr_from_error(cause: Error): string | undefined {
 	if (!has_stderr_field(cause)) return undefined
 
@@ -46,7 +43,7 @@ function display_error_details(cause: unknown): void {
 }
 
 function handle(error: unknown): void {
-	const error_message = get_error_message(error)
+	const error_message = error_text.message_of(error)
 
 	console.error('')
 	console.error('❌ Error:', error_message)

package/{scripts-ai → scripts/git}/git-followup-finish.ts

@@ -1,11 +1,11 @@
-import { git_followup_cleanup, type CleanupStep } from '../scripts/git/git-followup-cleanup'
-import { git_followup_pending } from '../scripts/git/git-followup-pending'
-import { git_next_issues } from '../scripts/git/git-next-issues'
-import { review_attest } from '../scripts/review/review-attest'
-import { review_stamps } from '../scripts/review/review-stamps'
-import { run_hold } from '../scripts/run/run-hold'
-import { run_progress_clock } from '../scripts/run/run-progress-clock'
+import { review_attest } from '#scripts/review/review-attest'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { run_hold } from '#scripts/run/run-hold'
+import { run_progress_clock } from '#scripts/run/run-progress-clock'
 import { parse_completed_issue_number } from './followup-issue-number'
+import { git_followup_cleanup, type CleanupStep } from './git-followup-cleanup'
+import { git_followup_pending } from './git-followup-pending'
+import { git_next_issues } from './git-next-issues'
 
 // **The count of unreleased merges, not the project version** (joshuafolkken/kit#1486). This line
 // used to read the local `package.json` and was read as "the version this run just shipped"; children

package/scripts/git/git-followup-flush.ts

@@ -1,62 +1,88 @@
 import { observation_ledger } from '#scripts/observations/observation-ledger'
-import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { observations_flush } from '#scripts/observations/observations-flush'
 import { git_command } from './git-command'
-import { git_followup_cleanup } from './git-followup-cleanup'
-import { main_sync } from './main-sync'
+import { git_spawn } from './git-spawn'
 
 // The residual commit path for the observation ledger (joshuafolkken/kit#1810). A run's appended lines
-// ride its own commit (joshuafolkken/kit#2763), so after the merge the ledger is usually clean and this
-// short-circuits; what it still catches is a line appended after the commit — a second review round's
-// record — which would otherwise stay in the working tree until a person remembered to flush it. This
-// wires the flush into `pnpm josh followup`, the one step that knows the merge has landed.
+// ride its own commit (joshuafolkken/kit#2763), so the ledger is usually clean by now and this
+// short-circuits; what it still catches is a line appended after that commit — a second review round's
+// record — which would otherwise stay in the working tree after the merge.
 //
-// **It runs before the working-tree hold is released** (`scripts-ai/git-followup-finish.ts`, whose
-// `finish()` runs after `git_pr_followup.run()` returns), because a flush switches branches, and a
-// hold released first would let another run grab the tree mid-switch.
-
-const MAIN_SYNC_SUCCESS = 0
-const FLUSH_RECOVERY = 'pnpm josh observations:flush'
-const SYNC_FAILURE_MESSAGE =
-	'Could not return to the default branch to flush the observation ledger; `pnpm josh ms` printed the reason above.'
-
-// `observations_flush.flush` requires the default branch, so the checkout is returned to it first.
-// `main_sync.run` catches its own errors and answers with an exit code rather than throwing, so a
-// checkout it could not move is turned into the throw the guarded step below reports.
-async function sync_and_flush(): Promise<void> {
-	if ((await main_sync.run([])) !== MAIN_SYNC_SUCCESS) throw new Error(SYNC_FAILURE_MESSAGE)
-
-	console.info(await observations_flush.flush(new Date()))
+// **It commits onto the pull request's own branch, before the merge** (joshuafolkken/kit#2919). It used
+// to flush after the merge from the default branch, which a lane cannot reach, so a lane's lines
+// waited in the primary checkout for a batch-end flush and were lost there to another run's stash.
+// Committed to the branch instead, the lines merge with the pull request — in a lane as anywhere — and
+// the CI wait `pnpm josh followup` runs next covers the pushed commit like any other push.
+
+const COMMIT_MESSAGE_PREFIX = 'Record observation ledger entries'
+
+function commit_message(issue_number: string | undefined): string {
+	return issue_number === undefined
+		? COMMIT_MESSAGE_PREFIX
+		: `${COMMIT_MESSAGE_PREFIX} #${issue_number}`
 }
 
-// **Short-circuits when the ledger holds no pending append.** That is every run that recorded no
-// observation, so the ordinary run pays nothing. Guarded like its sibling tail steps (joshuafolkken/kit#1539): past the merge a flush
-// failure is reported, never allowed to take the merge, the epic close and the hold release with it.
-//
-// **A lane skips it outright** (joshuafolkken/kit#2419). Its ledger is the primary checkout's
-// (`observation-ledger-home.ts`), which this step cannot flush — `main_sync` refuses in a linked work
-// tree — so the line waits in the primary checkout and the `backlogrun` commits every lane's lines at
-// once through `pnpm josh run:carry --end` (joshuafolkken/kit#2492).
-async function flush_ledger_step(should_merge: boolean): Promise<void> {
-	if (
-		!should_merge ||
-		observation_ledger_home.is_lane() ||
-		!observation_ledger.has_pending_append(await git_command.status())
-	) {
-		return
+// **A broken line refuses the merge rather than riding it** (joshuafolkken/kit#2123): the branch's
+// ledger file goes away with the lane, so a line left behind here is a line lost.
+async function assert_grammar(): Promise<void> {
+	const broken = await observation_ledger_prepare.prepare(await git_command.repository_root())
+
+	if (broken.length > 0) throw new Error(observations_flush.broken_lines_message(broken))
+}
+
+// **A push that fails takes its commit back**, leaving the lines staged: the next `pnpm josh followup`
+// then finds them pending and retries. Left committed, they would read as clean and the merge would
+// go ahead without them, the lines stranded in a local commit no reader sees.
+async function push_or_undo_commit(): Promise<void> {
+	try {
+		await git_command.push()
+	} catch (error) {
+		await git_spawn.read(['reset', '--soft', 'HEAD~1'])
+		throw error
 	}
+}
+
+// Only the ledger paths are staged — whatever else the tree holds is the run's to commit, not this
+// step's — and `-A` takes a migration's deletion of an old path with it.
+async function commit_and_push(
+	paths: ReadonlyArray<string>,
+	issue_number: string | undefined,
+): Promise<void> {
+	await git_spawn.read(['add', '-A', '--', ...paths])
+	await git_command.commit(commit_message(issue_number))
+	await push_or_undo_commit()
+}
+
+// **Short-circuits when the ledger holds no pending append**, which is every run that recorded nothing
+// after its commit, and on a `--no-merge` run, which has no merge for the lines to ride.
+async function commit_ledger_step(
+	should_merge: boolean,
+	issue_number: string | undefined,
+): Promise<void> {
+	if (!should_merge) return
+
+	const status_output = await git_command.status()
+
+	if (!observation_ledger.has_pending_append(status_output)) return
+
+	await assert_grammar()
+
+	// Read again: the grammar check migrated any old-path ledger, which changes what is to be staged.
+	const paths = observation_ledger
+		.ledger_paths(await git_command.status())
+		.filter((file_path) => !observation_ledger.is_migration_claim(file_path))
+
+	// A live run's migration claim alone is pending, not a line: with no path, `git add -A --` would
+	// stage the whole tree.
+	if (paths.length === 0) return
 
-	// `should_merge` is always true past the early return; it is passed on as `run_guarded_step`'s
-	// guard flag rather than a literal `true` so this step stays identical to its sibling tail steps —
-	// hardcoding `true` would turn the guard on for a `--no-merge` run if the early return were ever
-	// dropped (the trap `in_progress_step` warns of).
-	await git_followup_cleanup.run_guarded_step(should_merge, {
-		label: 'The observation ledger flush',
-		recovery: FLUSH_RECOVERY,
-		run: sync_and_flush,
-	})
+	await commit_and_push(paths, issue_number)
+	console.info(
+		`💡 Committed ${String(paths.length)} observation ledger path(s) to the pull request.`,
+	)
 }
 
-const git_followup_flush = { flush_ledger_step }
+const git_followup_flush = { COMMIT_MESSAGE_PREFIX, commit_ledger_step }
 
 export { git_followup_flush }

package/scripts/git/git-followup-issue-close.ts

@@ -1,6 +1,6 @@
+import { epic_parse } from '#scripts/epic/epic-parse'
 import { poll, type PollOptions } from '#scripts/lib/poll'
 import { z } from 'zod'
-import { git_epic_parse } from './git-epic-parse'
 import { git_gh_command } from './git-gh-command'
 import { parse_json_object_safe } from './parse-json-array'
 
@@ -28,7 +28,7 @@ async function is_issue_closed(issue_number: string): Promise<boolean> {
 	const raw = await git_gh_command.issue_get_state_and_relations(issue_number)
 	const parsed = raw === undefined ? undefined : parse_json_object_safe(raw, state_read_schema)
 
-	return git_epic_parse.is_state_closed(parsed?.state)
+	return epic_parse.is_state_closed(parsed?.state)
 }
 
 const FOLLOWUP_CLOSER = 'pnpm josh followup'

package/scripts/git/git-followup-label.ts

@@ -46,7 +46,7 @@ async function read_label_names(issue_number: string): Promise<ReadonlyArray<str
 // **An issue that does not carry it is never written to**, which is what keeps the step silent on a
 // run whose issue was never labelled — a `404` swallowed into a warning would report a failure where
 // there was nothing to do. The read itself is always paid: one `number,labels,body` call per merged
-// run, which is the read `git-epic-read.ts` already makes rather than a field list of its own.
+// run, which is the read `epic-read.ts` already makes rather than a field list of its own.
 //
 // A run whose pull request named no issue has nothing to strip, so it returns rather than throwing:
 // the number is recovered from the `closes #N` keyword, and its absence is already reported where

package/scripts/git/git-followup-pending.ts

@@ -21,7 +21,7 @@ import { git_command } from './git-command'
 // there cannot include this run's own merge, and a bare number would be understated by exactly one.
 // Saying so is the honest form of the same measurement. The console line printed after the merge
 // passes `false` and carries no note, because by then the merge is on the remote and the fetch below
-// brings it in; `scripts-ai/git-followup-finish.ts` is that caller, so **both branches of this flag
+// brings it in; `git-followup-finish.ts` is that caller, so **both branches of this flag
 // are live**. What a run *does* about the count is `pnpm josh release:scope`, asked after the merge,
 // which reads `read_pending` below rather than this line (joshuafolkken/kit#1582).
 const MERGE_PENDING_NOTE = "— this run's merge is not counted; it lands next"

package/{scripts-ai → scripts/git}/git-followup-workflow.ts

@@ -1,18 +1,19 @@
 #!/usr/bin/env tsx
 import { parseArgs } from 'node:util'
-import { git_branch } from '../scripts/git/git-branch'
-import { git_error } from '../scripts/git/git-error'
-import { git_notify, type GitNotifyConfig } from '../scripts/git/git-notify'
-import { git_pr_followup } from '../scripts/git/git-pr-followup'
-import { cli_body } from '../scripts/josh/cli-body'
-import { live_evidence } from '../scripts/review/live-evidence'
-import { review_attest } from '../scripts/review/review-attest'
-import { review_record } from '../scripts/review/review-record'
-import { load_optional_environment } from './environment-loader'
+import { cli_body } from '#scripts/josh/cli-body'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { live_evidence } from '#scripts/review/live-evidence'
+import { review_attest } from '#scripts/review/review-attest'
+import { review_record } from '#scripts/review/review-record'
 import { parse_issue_number_from_text } from './followup-issue-number'
+import { git_branch } from './git-branch'
+import { git_error } from './git-error'
 import { git_followup_finish } from './git-followup-finish'
+import { git_followup_flush } from './git-followup-flush'
+import { git_notify, type GitNotifyConfig } from './git-notify'
+import { git_pr_followup } from './git-pr-followup'
 
-load_optional_environment()
+josh_environment_file.load_environment_file()
 
 // cspell:words coderabbit
 
@@ -202,6 +203,17 @@ async function assert_merge_gates(
 	await assert_live_evidence(should_merge, branch_name)
 }
 
+// After the gates, before the CI wait: a line appended since the run's commit rides the pull request
+// itself, so it merges with it — a lane's included (joshuafolkken/kit#2919).
+async function prepare_merge(
+	should_merge: boolean,
+	issue_number: string | undefined,
+	branch_name: string,
+): Promise<void> {
+	await assert_merge_gates(should_merge, issue_number, branch_name)
+	await git_followup_flush.commit_ledger_step(should_merge, issue_number)
+}
+
 async function main(): Promise<void> {
 	const cli = parse_cli_arguments()
 
@@ -216,7 +228,7 @@ async function main(): Promise<void> {
 	const should_merge = is_merge_resolved(cli.values)
 	const branch_name = await resolve_branch_name(cli.values.branch)
 
-	await assert_merge_gates(should_merge, issue_number, branch_name)
+	await prepare_merge(should_merge, issue_number, branch_name)
 	// **The number the run reports on is the one it used**, which is the number the pull request
 	// closes where the invocation named none (joshuafolkken/kit#1539). Recovered inside `run`, so the
 	// tail records a run the command line could not identify rather than silently skipping it.