@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/notify/telegram-test.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
 import { git_error } from '#scripts/git/git-error'
+import { session_cite } from '#scripts/issue/session-cite'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { telegram_notify } from './telegram-notify'
@@ -12,36 +12,44 @@ import { telegram_test_logic, type CliValues, type ResolvedContext } from './tel
 
 const REPO_NAME_SEPARATOR = '/'
 const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE =
+	'Usage: josh notify [--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]'
 
 // The free-text values a caller writes, often opening with a Markdown `-` bullet.
 const FREE_TEXT_FLAGS = ['--body', '--issue-title']
 
-function parse_cli_arguments(): CliValues {
-	const { values } = parseArgs({
-		args: [...cli_flags.attach_values(process.argv.slice(ARGV_OFFSET), FREE_TEXT_FLAGS)],
-		options: {
-			'task-type': { type: 'string' },
-			'repo-name': { type: 'string' },
-			'issue-title': { type: 'string' },
-			body: { type: 'string' },
-			'body-file': { type: 'string' },
-			'issue-url': { type: 'string' },
-			'pr-url': { type: 'string' },
-		},
-	})
-
-	return values
+const OPTIONS = {
+	'task-type': { type: 'string' },
+	'repo-name': { type: 'string' },
+	'issue-title': { type: 'string' },
+	body: { type: 'string' },
+	'body-file': { type: 'string' },
+	'issue-url': { type: 'string' },
+	'pr-url': { type: 'string' },
+} as const
+
+// `undefined` for a line nobody can read — an unknown flag, or a flag given no value.
+function parse_cli_arguments(): CliValues | undefined {
+	return cli_flags.values_of(
+		cli_flags.attach_values(process.argv.slice(ARGV_OFFSET), FREE_TEXT_FLAGS),
+		OPTIONS,
+	)
+}
+
+// A refused line sends nothing: the notification a misspelled flag would have produced is not the one
+// the caller wrote, and the non-zero exit is what tells a workflow it never went out.
+function refuse_usage(): void {
+	console.error(USAGE)
+	process.exitCode = FAILURE_EXIT_CODE
 }
 
 // The repository this notification is about, for the Telegram header.
 //
-// joshuafolkken/kit#1063: this used to spawn `gh repo view --json nameWithOwner` through a
-// promisified `execFile`, which is why joshuafolkken/kit#1022's survey never counted it — the
-// callee was not `execa` and the file was not `scripts/`. `gh repo view` goes through GraphQL and
-// is answered 403 in a cloud session, so the header simply lost its repository name there.
-//
-// The same fact is already read over REST by `git_gh_repo`, whose failure contract is the
-// `undefined` this caller was already handling, so it is read from there rather than from a second
+// Not `gh repo view`: it goes through GraphQL and is answered 403 in a cloud session, which would
+// lose the header's repository name there. The same fact is already read over REST by
+// `git_gh_repo`, whose failure contract is the `undefined` this caller handles, so it is read from
+// there rather than from a second
 // spawn (`CLAUDE.md` → "No clones").
 async function fetch_repo_name(): Promise<string | undefined> {
 	const name_with_owner = await git_gh_repo.repo_get_name_with_owner()
@@ -53,8 +61,7 @@ async function fetch_repo_name(): Promise<string | undefined> {
 
 // The title is read from the repository the URL names, through the same reader every other
 // cross-repository read goes through. Read unqualified, `gh` would answer with the issue of that
-// number in the working directory's repository — a different issue with a different title
-// (joshuafolkken/kit#903).
+// number in the working directory's repository — a different issue with a different title.
 //
 // A repository the token cannot read answers the same `undefined` as an issue that does not exist,
 // and the notification would then go out with no title line at all. Say so, so the gap is visible
@@ -65,7 +72,9 @@ async function fetch_issue_title(target: IssueUrlTarget | undefined): Promise<st
 	const title = await git_gh_issue_read.issue_get_title(target.issue_number, target.name_with_owner)
 
 	if (title === undefined) {
-		console.warn(`⚠️  Could not read ${target.name_with_owner}#${target.issue_number}.`)
+		console.warn(
+			`⚠️  Could not read ${session_cite.issue(target.issue_number, undefined, target.name_with_owner)}.`,
+		)
 	}
 
 	return title
@@ -90,9 +99,8 @@ async function resolve_issue_title(
 //
 // `--issue-url` outranks `--pr-url` because it identifies the issue the title is read from as well
 // as the repository. A pull URL answers the repository half only, which is why it is read for
-// `repo_name` and not passed to `resolve_issue_title` — a completion notification carrying only a
-// PR link used to go out under the working directory's repository while its link pointed elsewhere
-// (joshuafolkken/kit#994).
+// `repo_name` and not passed to `resolve_issue_title` — otherwise a completion notification carrying
+// only a PR link goes out under the working directory's repository while its link points elsewhere.
 async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 	const target = github_issue_url.parse(values['issue-url'])
 	const pull_target = github_issue_url.parse_pull(values['pr-url'])
@@ -105,13 +113,20 @@ async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 async function main(): Promise<void> {
 	josh_environment_file.load_environment_file()
 	const values = parse_cli_arguments()
+
+	if (values === undefined) {
+		refuse_usage()
+
+		return
+	}
+
 	const context = await resolve_context(values)
 	const input = telegram_test_logic.build_input({ values, context })
 
 	await telegram_notify.send(input)
 }
 
-// **A notification nobody received must not read as success** (joshuafolkken/kit#1564). This command
+// **A notification nobody received must not read as success**. This command
 // *is* the notification, so a failed send is its result and the exit code has to say so — the state
 // that Issue measured was three lost messages, each printing a warning and exiting 0.
 //

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

@@ -7,10 +7,10 @@ import { observation_ledger_migrate } from './observation-ledger-migrate'
 
 // Where the observation ledger is read and written, whichever work tree a command runs in.
 //
-// **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
+// **The ledger lives in the work tree the command runs in — a lane's in a lane**.
+// Resolved to the primary checkout from every lane, a lane's lines would wait there for a batch-end
+// flush; another run's stash of that checkout would take them, the flush would read `git status` and
+// find nothing, and the lines would be lost. Each run 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.
@@ -21,8 +21,7 @@ function ledger_root(cwd: string = process.cwd()): string {
 	return cwd
 }
 
-// **Resolving the directory migrates the single-file ledgers first** (joshuafolkken/kit#2724,
-// joshuafolkken/kit#2919). Every reader and writer asks here — `review:record --check`,
+// **Resolving the directory migrates the single-file ledgers first**. 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.
@@ -52,6 +51,12 @@ async function current_branch(cwd: string): Promise<string> {
 	}
 }
 
+// The `<YYYY-MM-DD>` a ledger line carries, and the name of a date file — one spelling for every
+// writer, so a line and the file it lands in never disagree about the day.
+function ledger_date(now: Date): string {
+	return now.toISOString().slice(0, DATE_END)
+}
+
 // **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
@@ -59,7 +64,7 @@ async function current_branch(cwd: string): Promise<string> {
 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)
+	return file_path(issue ?? ledger_date(now), cwd)
 }
 
 // A file whose last line has no newline would otherwise run into the next file's first line.
@@ -104,7 +109,7 @@ async function read(cwd: string = process.cwd()): Promise<string | undefined> {
 
 // 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).
+// into existence there.
 async function append(target: string, lines: ReadonlyArray<string>): Promise<void> {
 	if (lines.length === 0) return
 
@@ -115,6 +120,7 @@ async function append(target: string, lines: ReadonlyArray<string>): Promise<voi
 const observation_ledger_home = {
 	append,
 	issue_path,
+	ledger_date,
 	ledger_root,
 	read,
 	writer_path,

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

@@ -1,8 +1,8 @@
 // The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-ledger.md`)
 // is fixed — `- k:<slug> | d<n> | <YYYY-MM-DD> | <where> | <what>` — but the path was collected in
 // `observation-ledger.ts` without a line ever being parsed, so a malformed append rode a flush
-// through unremarked. This validates a ledger entry line and reports why a broken one is broken
-// (joshuafolkken/kit#2123). The grammar is the single source's, pinned by the document test.
+// through unremarked. This validates a ledger entry line and reports why a broken one is broken.
+// The grammar is the single source's, pinned by the document test.
 
 const KEY_PREFIX = '- k:'
 const FIELD_SEPARATOR = ' | '
@@ -96,6 +96,7 @@ function missing_lines(candidates: ReadonlyArray<string>, ledger: string): Array
 const observation_ledger_line = {
 	broken_ledger_lines,
 	is_ledger_entry_line,
+	line_reason,
 	missing_lines,
 }
 

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

@@ -19,9 +19,8 @@ import {
 } from './observation-ledger'
 import { observation_ledger_line } from './observation-ledger-line'
 
-// 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
+// Moves the ledger's lines from its old single files into the directory, 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.
@@ -164,7 +163,7 @@ function legacy_directory_names(directory: string): ReadonlyArray<string> {
 	}
 }
 
-// **The old directory moves file by file into the same names** (joshuafolkken/kit#3341), so an
+// **The old directory moves file by file into the same names**, so an
 // issue's lines stay in that issue's file; the emptied directory is removed when nothing else is left.
 function migrate_directory(root: string): boolean {
 	const legacy_directory = path.join(root, LEGACY_OBSERVATION_LEDGER_DIRECTORY)

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

@@ -1,12 +1,12 @@
 import { observation_ledger_home } from './observation-ledger-home'
 import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
 
-// **What has to hold before a ledger line is committed, asked by every path that commits one**
-// (joshuafolkken/kit#2763): `pnpm josh observations:flush`, the run's own commit in
+// **What has to hold before a ledger line is committed, asked by every path that commits one**:
+// `pnpm josh observations:flush`, the run's own commit in
 // `scripts/git/git-staging.ts` and `pnpm josh followup`'s pre-merge ledger commit. Lines still on an
-// old path are moved first (joshuafolkken/kit#2724, joshuafolkken/kit#2919), so the commit carries the
+// old path are moved first, 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.
+// — 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.

package/scripts/observations/observation-ledger.ts

@@ -1,20 +1,20 @@
 // The observation ledger's one location, named here rather than inside any of the places that act on
-// it (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
+// it. `git-staging.ts` stages it with the run's own commit when its grammar
+// holds, `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 outside `docs/`** (joshuafolkken/kit#3341): its files are machine-written data lines, not
-// documents a person reads, and at about forty new files a day they were most of `docs/`.
+// **It sits outside `docs/`**: its files are machine-written data lines, not
+// documents a person reads, and at about forty new files a day they would be most of `docs/`.
 //
-// **It is a directory of one file per issue, not one file** (joshuafolkken/kit#2919). One file every
-// run appended to made two lanes' pull requests conflict at its tail, so lanes parked their lines in
-// the primary checkout for a batch-end flush — and another run's stash took them from there, and the
-// flush never saw them. A run now appends to `<issue>.md` in its own work tree and merges it with its
-// own pull request: parallel lanes write different files, so nothing conflicts and nothing waits.
+// **It is a directory of one file per issue, not one file**. One file every run appends to makes two
+// lanes' pull requests conflict at its tail, and parking the lines in the primary checkout for a
+// batch-end flush lets another run's stash take them before the flush sees them. A run appends to
+// `<issue>.md` in its own work tree and merges it with its own pull request: parallel lanes write
+// different files, so nothing conflicts and nothing waits.
 const OBSERVATION_LEDGER_DIRECTORY = '.josh/observations'
 
-// Where the directory lived until joshuafolkken/kit#3341, a migration source for the same reasons as
+// The directory's previous location, a migration source for the same reasons as
 // the single-file ledgers below: each `<name>.md` in it moves to the same name in the directory.
 const LEGACY_OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
 
@@ -29,10 +29,9 @@ const LEDGER_FILE_EXTENSION = '.md'
 // lost to the split.
 const LEGACY_LEDGER_FILE = `legacy${LEDGER_FILE_EXTENSION}`
 
-// Where the ledger lived as one file — `docs/observations.md` before joshuafolkken/kit#2724 and
-// `docs/maintainers/observations.md` until joshuafolkken/kit#2919 — kept as migration sources rather
-// than forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
-// existing ledger all write there, and `observation-ledger-migrate.ts` moves what it finds into the
+// The single-file ledger paths, `docs/observations.md` and `docs/maintainers/observations.md`, kept
+// as migration sources rather than forgotten: a run still on the old code, a stash cut before the
+// move and a consumer repository's existing ledger all write there, and `observation-ledger-migrate.ts` moves what it finds into the
 // directory. Every place that recognizes the ledger recognizes them, so a line on either path is never
 // staged into an ordinary commit. Remove them once every repository holding a ledger has migrated.
 const LEGACY_OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
@@ -105,7 +104,7 @@ function ledger_paths(status_output: string): ReadonlyArray<string> {
 
 // **The one place that answers "does this working tree hold a pending observation append?"**
 // `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-merge ledger commit
-// both ask it (joshuafolkken/kit#1810), so a literal in each would be the clone the header above
+// both ask it, so a literal in each would be the clone the header above
 // warns against. A blank porcelain line carries no ledger path, so `is_ledger_line` answers false for
 // it and no filtering is needed.
 function has_pending_append(status_output: string): boolean {

package/scripts/observations/observation-record-cli.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { observation_ledger_home } from './observation-ledger-home'
+import {
+	observation_record,
+	REFUSED_VERDICT,
+	type ObservationEntry,
+	type RecordResult,
+} from './observation-record'
+
+// `josh observation:record <key> <depth> <where> <what>` — count the key's earlier sightings, append
+// this one, and answer what the run does next. Exactly one token on stdout:
+// `file` on the second sighting, which the promotion rule files; `ledger` on any other, which the line
+// alone records. The earlier sightings and the file written go to stderr, so the Issue a `file` answer
+// opens can quote the first sighting's date from them.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const ENTRY_FIELDS = 4
+const USAGE = 'Usage: josh observation:record <key> <depth> <where> <what> [--checkout <path>]'
+const OPTIONS = { checkout: { type: 'string' } } as const
+
+interface RecordArguments {
+	entry: ObservationEntry
+	checkout: string
+}
+
+function entry_of(fields: ReadonlyArray<string>): ObservationEntry {
+	const [slug = '', depth = '', where = '', what = ''] = fields
+
+	return { slug, depth, where, what }
+}
+
+function parse_arguments(argv: ReadonlyArray<string>): RecordArguments | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed?.positionals.length !== ENTRY_FIELDS) return undefined
+
+	const { checkout } = parsed.values
+
+	return {
+		entry: entry_of(parsed.positionals),
+		checkout: checkout ?? observation_ledger_home.ledger_root(),
+	}
+}
+
+function report(result: RecordResult): number {
+	if (result.verdict === REFUSED_VERDICT) {
+		console.error(`Refused: ${result.reason}\n${USAGE}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const sighting = `${String(result.earlier.length)} earlier sighting(s); appended to ${result.target}`
+
+	console.error([sighting, ...result.earlier].join('\n'))
+	console.info(result.verdict)
+
+	return 0
+}
+
+async function run(argv: ReadonlyArray<string>, now: Date): Promise<number> {
+	const parsed = parse_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return report(await observation_record.record({ ...parsed, now }))
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv, new Date())
+}
+
+const observation_record_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { observation_record_cli }

package/scripts/observations/observation-record.ts

@@ -0,0 +1,91 @@
+import { observation_ledger_home } from './observation-ledger-home'
+import { observation_ledger_line } from './observation-ledger-line'
+
+// The count, the append and the promotion verdict of one observation-ledger sighting, as one command.
+// They were a `cat | grep -c … || true` a run typed by hand, an append it
+// wrote itself, and a "does the count answer exactly 1" it judged — three steps whose answers are
+// fixed, now read off the ledger rather than re-derived in every run. The grammar and the promotion
+// rule are `.claude/skills/workflow-commands/observation-ledger.md`'s.
+
+const FILE_VERDICT = 'file'
+const LEDGER_VERDICT = 'ledger'
+const REFUSED_VERDICT = 'refused'
+// The sample line in `observation-ledger.md` carries it, so a real sighting under it would be counted
+// against the sample.
+const RESERVED_SLUG = 'example'
+const RESERVED_REASON = '`k:example` is reserved for the sample in observation-ledger.md'
+// The one earlier sighting that makes this one the second — a higher count means the sighting that
+// answered `1` already filed the Issue.
+const PROMOTING_COUNT = 1
+
+interface ObservationEntry {
+	slug: string
+	depth: string
+	where: string
+	what: string
+}
+
+interface RecordRequest {
+	entry: ObservationEntry
+	checkout: string
+	now: Date
+}
+
+type RecordResult =
+	| { verdict: typeof REFUSED_VERDICT; reason: string }
+	| {
+			verdict: typeof FILE_VERDICT | typeof LEDGER_VERDICT
+			earlier: ReadonlyArray<string>
+			line: string
+			target: string
+	  }
+
+function entry_line(entry: ObservationEntry, date: string): string {
+	return `- k:${entry.slug} | ${entry.depth} | ${date} | ${entry.where} | ${entry.what}`
+}
+
+function refusal_of(entry: ObservationEntry, line: string): string | undefined {
+	if (entry.slug === RESERVED_SLUG) return RESERVED_REASON
+
+	return observation_ledger_line.line_reason(line)
+}
+
+// Every ledger line already carrying the key, across every file — a recurrence is a recurrence
+// whichever issue's file each sighting sits in. No ledger at all is a first sighting.
+function sightings(ledger: string | undefined, slug: string): ReadonlyArray<string> {
+	const prefix = `- k:${slug} |`
+
+	return (ledger ?? '').split('\n').filter((line) => line.startsWith(prefix))
+}
+
+// The count is read before the append, so it is the sightings *before* this one.
+async function record(request: RecordRequest): Promise<RecordResult> {
+	const date = observation_ledger_home.ledger_date(request.now)
+	const line = entry_line(request.entry, date)
+	const reason = refusal_of(request.entry, line)
+
+	if (reason !== undefined) return { verdict: REFUSED_VERDICT, reason }
+
+	const earlier = sightings(
+		await observation_ledger_home.read(request.checkout),
+		request.entry.slug,
+	)
+	const target = await observation_ledger_home.writer_path(request.now, request.checkout)
+
+	await observation_ledger_home.append(target, [line])
+
+	const verdict = earlier.length === PROMOTING_COUNT ? FILE_VERDICT : LEDGER_VERDICT
+
+	return { verdict, earlier, line, target }
+}
+
+const observation_record = { record }
+
+export {
+	FILE_VERDICT,
+	LEDGER_VERDICT,
+	observation_record,
+	REFUSED_VERDICT,
+	type ObservationEntry,
+	type RecordResult,
+}

package/scripts/observations/observations-flush-cli.ts

@@ -9,7 +9,7 @@ const FAILURE_EXIT_CODE = 1
 // as a stack: "this checkout is on a feature branch" and "the tree holds somebody else's work" are
 // both things the person fixes in one step, and a trace hides the sentence that says which.
 //
-// **It acts on the checkout it runs in** (joshuafolkken/kit#2919). A lane's ledger lines merge with
+// **It acts on the checkout it runs in**. A lane's ledger lines merge with
 // the lane's own pull request, so a lane has nothing to flush and is refused like any feature branch.
 async function main(): Promise<void> {
 	try {

package/scripts/observations/observations-flush-landing.ts

@@ -1,12 +1,13 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { OpenPull } from '#scripts/gh/git-gh-pr-auto-merge'
 import { git_pr_checks } from '#scripts/gh/git-pr-checks'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
 
-// **A flush pull request lands whether or not the flush that opened it is still alive**
-// (joshuafolkken/kit#2497). The merge used to happen only inside the flush's own wait, so a session
-// cut or a killed process left a green pull request open with nobody to merge it — and once a later
-// flush appended to the same ledger tail, it conflicted and could not land at all. Auto-merge moves
+// **A flush pull request lands whether or not the flush that opened it is still alive**.
+// A merge only inside the flush's own wait would let a session cut or a killed process leave a green
+// pull request open with nobody to merge it — and once a later flush appended to the same ledger
+// tail, it would conflict and could not land at all. Auto-merge moves
 // the merge to GitHub, and the wait that remains is only for fast-forwarding the local default
 // branch.
 
@@ -18,7 +19,7 @@ const MERGE_FAILED_REASON =
 	'a required check failed or the branch conflicts, so auto-merge will not land the pull request'
 
 // **Best-effort, and the answer says which wait to use.** GraphQL — the only way to enable auto-merge
-// — can be refused in a cloud session (joshuafolkken/kit#1022), and that loses the safety net rather
+// — can be refused in a cloud session, and that loses the safety net rather
 // than the flush: the in-process wait-and-merge still runs, exactly as before auto-merge existed.
 async function request_auto_merge(branch_name: string): Promise<boolean> {
 	try {
@@ -49,7 +50,7 @@ async function wait_for_landing(branch_name: string, is_auto_merge: boolean): Pr
 }
 
 function describe_pull(pull: OpenPull): string {
-	return `#${String(pull.number)} (\`${pull.head_ref}\`)`
+	return `${issue_cite.plain(pull.number)} (\`${pull.head_ref}\`)`
 }
 
 // **Landing means GitHub will merge it with nobody watching**: auto-merge is on and the merge gate has