@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/gh/git-pr-checks-watch.ts

@@ -16,18 +16,18 @@ import {
 	type RollupCheck,
 } from './git-pr-checks-parse'
 
-// The bounded look at a pull request's checks that `gh pr checks <branch> --watch` used to give.
+// The bounded look at a pull request's checks that `gh pr checks <branch> --watch` gives.
 //
 // **`--watch` is a streaming call and REST has no counterpart** — it holds the connection open and
-// redraws a table as each check settles, which no sequence of `gh api` requests reproduces
-// (joshuafolkken/kit#1022). What it is *used* for does have one: `git-pr-followup.ts` discards its
+// redraws a table as each check settles, which no sequence of `gh api` requests reproduces.
+// What it is *used* for does have one: `git-pr-followup.ts` discards its
 // result entirely, so the answer its one caller needs is "did the checks settle within two minutes",
 // which the poll loop in `git-pr-checks.ts` already computes. No new loop is written here; this is
-// that loop with a two-minute budget (joshuafolkken/kit#1028).
+// that loop with a two-minute budget.
 //
-// **`git-pr.ts` was the second caller until joshuafolkken/kit#1232.** It read only `timed_out`, and
-// `followup` restarted the same wait the moment it returned — so the watch there was the same answer
-// waited for twice, and `pnpm josh git` now returns as soon as the pull request is open.
+// **`git-pr.ts` does not call this.** It would read only `timed_out`, and `followup` restarts the
+// same wait the moment it returns — the same answer waited for twice — so `pnpm josh git` returns as
+// soon as the pull request is open.
 //
 // **What is lost is the live table.** `gh` printed each check's name and state as it changed; the
 // poll prints `Checking PR status… (n/N)` instead. The trade is accepted because the display was
@@ -49,12 +49,12 @@ interface WatchResult {
 
 // **The watch asks a weaker question than the merge gate, and that difference is load-bearing.**
 // `evaluate_pr_state` answers `success` only for a pull request that is *mergeable*: `CLEAN` merge
-// state, every required check green, no change request standing. `gh pr checks --watch` knew nothing
-// about any of that — it waited for the checks and exited non-zero if one failed. Handing the watch
+// state, every required check green, no change request standing. `gh pr checks --watch` knows
+// nothing about any of that — it waits for the checks and exits non-zero if one fails. Handing the watch
 // the merge gate's verdict would break it on a repository that requires an approving review, where
 // `mergeable_state` is `blocked`: the watch could never succeed, so it would report "CI still
 // running" over a green build, and a standing change request would end it non-zero on something the
-// old watch ignored outright.
+// `--watch` ignores outright.
 //
 // **An empty rollup is `pending`, not `failure`** — deliberately, and it is the one place the watch
 // answers differently on the first poll than at the end. `followup` starts this right after the
@@ -62,12 +62,12 @@ interface WatchResult {
 // there would end the run red on a perfectly healthy one. Whether the branch really has no checks is
 // asked once, after the budget runs out — see `pr_checks_watch`.
 
-// Temporary (kit#753): CodeRabbit blocks nothing end to end, so a look-ahead that waits on it waits
+// Temporary: CodeRabbit blocks nothing end to end, so a look-ahead that waits on it waits
 // for something no verdict downstream reads. Its commit status posts `Review queued` within seconds
-// of the pull request opening and stays pending for the whole review — thirteen minutes on PR #1211
-// — so counting it as pending spent the entire two-minute budget on **every** run and then ended in
-// the timeout note, before the merge gate applied kit#753's exemption and merged anyway
-// (joshuafolkken/kit#1217). The name comes from `is_coderabbit_check`, the one predicate the merge
+// of the pull request opening and stays pending for the whole review, often well past the budget —
+// so counting it as pending would spend the entire two-minute budget on **every** run and end in the
+// timeout note, before the merge gate merges anyway under the CodeRabbit non-blocking exemption.
+// The name comes from `is_coderabbit_check`, the one predicate the merge
 // gate's exemption is also written in terms of, so the two cannot drift apart.
 //
 // **Only the *pending* reading is dropped.** A CodeRabbit check that has already failed still makes
@@ -114,7 +114,7 @@ function describe_checks_failure(snapshot: PrStateSnapshot): string {
 
 // **The watch never reads `review_decision`**, so the poll must not spend a request fetching it. It
 // is the same difference `evaluate_checks_settled` is written for, said to the fetcher instead of to
-// the verdict: three requests a poll rather than four (joshuafolkken/kit#1043).
+// the verdict: three requests a poll rather than four.
 function should_never_read_review_decision(): boolean {
 	return false
 }
@@ -141,7 +141,7 @@ async function watch_until_settled(branch_name: string): Promise<void> {
 
 // `gh pr checks` exited non-zero for a branch with no checks at all just as it did for a failed one,
 // and `git-pr-followup.ts` relies on that to fail rather than spend its whole 32-minute budget on a
-// required check that is *missing* rather than pending (joshuafolkken/kit#999). Asking after the
+// required check that is *missing* rather than pending. Asking after the
 // budget rather than on every poll is what keeps a pull request whose checks have not registered yet
 // from failing on the first read: two minutes is the grace, and an empty rollup at the end of them
 // is the answer `gh` gave immediately.

package/scripts/gh/git-pr-checks.ts

@@ -24,9 +24,9 @@ const CHECK_WAIT_INTERVAL_MS = 10_000
 // needs (2), so 27 minutes is the longest run that workflow permits, and five minutes of
 // runner-queue headroom goes on top. A unit test walks the `needs` graph of the distributed
 // workflows and fails if any declared budget outgrows this value; a job that declares no cap is a
-// gap the number cannot promise to cover rather than a reason to inflate it. Waiting longer costs nothing on a fast project: polling returns as
-// soon as the checks settle, and a failed check throws immediately rather than waiting out the
-// budget. See joshuafolkken/kit#851.
+// gap the number cannot promise to cover rather than a reason to inflate it. Waiting longer costs
+// nothing on a fast project: polling returns as soon as the checks settle, and a failed check throws
+// immediately rather than waiting out the budget.
 const DEFAULT_TIMEOUT_SECONDS = 1920
 
 // The poll loop sleeps between attempts and not after the last one, so spanning a budget takes one
@@ -51,14 +51,13 @@ const DEFAULT_STABLE_READS = 2
 // One authoritative gate poll is enough once `pr_checks_watch` has already seen every check finish:
 // the watch is the first confirmation, so the poll that follows need only agree once. The two reads
 // exist for the pending→settled window a bare poll opens on, and the watch has itself already spanned
-// that window — so waiting a second interval after it merely re-proves what the watch established
-// (joshuafolkken/kit#2029).
+// that window — so waiting a second interval after it merely re-proves what the watch established.
 const WATCH_CONFIRMED_STABLE_READS = 1
 
 // **A read that failed is not a verdict.** The loop reads every ten seconds, so a dropped connection,
 // a rate limit or one request over its budget is the kind of failure the *next* poll answers — and
-// ending a 32-minute wait on one of them costs the whole run again. Before joshuafolkken/kit#1077
-// every one of them rejected straight out of the loop, because the fetch had no `catch` at all.
+// ending a 32-minute wait on one of them costs the whole run again, so the fetch catches them rather
+// than rejecting straight out of the loop.
 //
 // **The cap is what keeps "ask again" from becoming "wait out the budget in silence".** Three
 // consecutive failures and the wait ends carrying the failure that caused it, so an endpoint that has
@@ -68,12 +67,12 @@ const WATCH_CONFIRMED_STABLE_READS = 1
 //
 // **The loop's own budget is unchanged**, so nothing here can extend a wait: a fetch that never
 // succeeds still runs out of attempts. And a failed read never counts as a passing one — it resets
-// the stable-read window, the same direction joshuafolkken/kit#925 / #950 / #973 / #1048 take.
+// the stable-read window, so an unread state is never taken as a settled answer.
 const MAX_CONSECUTIVE_READ_FAILURES = 3
 
 // The wait's own timeout, named so a caller can tell it apart from a failing check. The bounded
 // watch in `git-pr-checks-watch.ts` answers `timed_out` for one and rethrows the other, and matching
-// on prose is the only distinction the loop offers (joshuafolkken/kit#1028).
+// on prose is the only distinction the loop offers.
 const PR_CHECKS_TIMEOUT_MESSAGE = 'Timed out while waiting for PR checks to complete.'
 
 function is_pr_checks_timeout(error: unknown): boolean {
@@ -82,11 +81,10 @@ function is_pr_checks_timeout(error: unknown): boolean {
 
 // Whether this poll has to read the review listing, asked of the snapshot *without* one. It is a
 // question about the current poll rather than a cache key: answering `false` skips one request now
-// and nothing is carried into the next poll (joshuafolkken/kit#1043).
+// and nothing is carried into the next poll.
 type ReviewDecisionPredicate = (snapshot: PrStateSnapshot) => boolean
 
-// The conservative answer, and the one every evaluator that does not say gets: read it every poll,
-// which is what all of them did before the predicate existed.
+// The conservative answer, and the one every evaluator that does not say gets: read it every poll.
 function should_always_read_review_decision(): boolean {
 	return true
 }
@@ -98,12 +96,12 @@ type PrStateFetcher = (
 
 // What the loop asks of each snapshot, and what it says when the answer is `failure`.
 //
-// The loop used to hard-code the merge gate's own verdict, which is the strictest question anyone
-// asks of a pull request: mergeable *and* every required check green *and* no change request
-// standing. `gh pr checks --watch` asked a much weaker one — have the checks finished? — and the
-// conversion in joshuafolkken/kit#1028 gave the watch the strict verdict by accident: on a repository
-// whose `mergeable_state` is `blocked`, the watch could never succeed, and a standing change request
-// made it *throw* out of `pnpm josh git`. Naming the question is what keeps the two apart.
+// The merge gate's own verdict is the strictest question anyone asks of a pull request: mergeable
+// *and* every required check green *and* no change request standing. `gh pr checks --watch` asks a
+// much weaker one — have the checks finished? Hard-coding the strict verdict in the loop would hand
+// it to the watch too: on a repository whose `mergeable_state` is `blocked`, the watch could never
+// succeed, and a standing change request would make it *throw*. Naming the question is what keeps
+// the two apart.
 //
 // **`should_read_review_decision` is part of the same question.** An evaluator that never reads
 // `review_decision` must not make the fetcher pay for it, and one that does must get a value read in
@@ -190,7 +188,7 @@ interface PollAttemptResult {
 
 // The two things one poll can come back with, kept apart so that only the *read* is retried. The
 // throw `classify_poll_result` raises on a `failure` verdict is an answer — the checks are red — and
-// retrying it would undo the fast fail joshuafolkken/kit#990 added.
+// retrying it would undo the fast fail on a red check.
 type SnapshotRead =
 	{ kind: 'read'; snapshot: PrStateSnapshot } | { kind: 'unreadable'; cause: unknown }
 
@@ -289,14 +287,13 @@ async function wait_for_pr_success(options: WaitForPrSuccessOptions): Promise<Pr
 }
 
 // The snapshot module rather than `git-gh-command`, which is deliberate: `git-gh-command` also
-// exposes the watch, and the watch now polls through this file (joshuafolkken/kit#1028). Naming the
+// exposes the watch, and the watch now polls through this file. Naming the
 // one read it actually needs keeps that from closing into an import cycle.
 //
 // **Three requests, and a fourth only where it can change the answer.** The pull request detail and
 // the two commit listings are read every poll because `mergeable_state` and the rollup both move
 // while CI runs; the review listing is read when the predicate says this poll's verdict turns on it.
-// A `followup` that waits out its whole 32-minute budget went from about 800 requests to about 600
-// (joshuafolkken/kit#1043).
+// A `followup` that waits out its whole 32-minute budget went from about 800 requests to about 600.
 async function default_fetch_pr_state(
 	branch_name: string,
 	should_read_review_decision: ReviewDecisionPredicate = should_always_read_review_decision,
@@ -327,7 +324,7 @@ async function wait_for_pr_success_default(
 	})
 }
 
-// Where a pull request GitHub merges on its own stands (joshuafolkken/kit#2497). `failed` is what
+// Where a pull request GitHub merges on its own stands. `failed` is what
 // auto-merge never fires under — a red required check, a conflict, a requested change — so a wait on
 // it ends now rather than at the budget; a red check outside the required list is not among them
 // (`is_auto_merge_blocked`). A read that failed answers `waiting`, so a poll asks again.

package/scripts/gh/git-pr-coderabbit.ts

@@ -20,7 +20,7 @@ interface PullComment {
 }
 
 // `undefined` when the listing could not be read, which is not the same as a pull request with no
-// line comments (joshuafolkken/kit#973).
+// line comments.
 function parse_pull_comments(raw_json: string | undefined): Array<PullComment> | undefined {
 	if (raw_json === undefined) return undefined
 
@@ -58,13 +58,14 @@ function log_unresolved_coderabbit(urls: ReadonlyArray<string>): void {
 	}
 }
 
-// Temporary (kit#753): unresolved CodeRabbit line comments no longer block the merge. They are
+// Temporary: unresolved CodeRabbit line comments do not block the merge. They are
 // logged, returned as audit notes for the completion notification, and — when an ignore reason is
-// supplied — still documented on the PR. Revert together with kit#752.
+// supplied — still documented on the PR. Revert together with the rest of the temporary CodeRabbit
+// non-blocking policy.
 // Unreadable is reported, never blocked — the opposite of the AI review gate's handling of the same
-// gap, and for the reason kit#753 gave: CodeRabbit does not block the merge at all right now, so an
+// gap, and for the policy's own reason: CodeRabbit does not block the merge at all right now, so an
 // unreadable CodeRabbit listing cannot either. What it must not do is pass as "nothing unresolved",
-// which is what the reader's old `'[]'` made of it (joshuafolkken/kit#973).
+// which is what reading it as `'[]'` would make of it.
 const UNREADABLE_CR_NOTE =
 	'CodeRabbit line comments could not be read; unresolved findings were not checked (kit#753).'
 
@@ -87,7 +88,8 @@ async function report_unreadable_cr(input: {
 }
 
 // Documented on the pull request when a reason was given, logged when it was not. Either way the
-// finding is recorded rather than dropped — kit#753 removed the block, not the audit trail.
+// finding is recorded rather than dropped — the non-blocking policy removes the block, not the
+// audit trail.
 async function record_unresolved_cr(input: {
 	branch_name: string
 	ignore_reason: string | undefined

package/scripts/gh/git-pr-confirmation.ts

@@ -1,7 +1,7 @@
 import { telegram_notify, type TelegramSendInput } from '#scripts/notify/telegram-notify'
 
-// What to type when the confirmation notification itself could not be delivered
-// (joshuafolkken/kit#1564). The `--body-file` spelling rather than `--body`, because the body names
+// What to type when the confirmation notification itself could not be delivered.
+// The `--body-file` spelling rather than `--body`, because the body names
 // commands and a backtick inside shell double quotes is evaluated before the command runs.
 const CONFIRMATION_RECOVERY =
 	'send it by hand — `pnpm josh notify --task-type confirmation --issue-url <url> ' +
@@ -28,7 +28,7 @@ function build_confirmation_input(input: {
 	}
 }
 
-// **The tolerant send** (joshuafolkken/kit#1564). What stops the run is the blocker this
+// **The tolerant send**. What stops the run is the blocker this
 // notification is *about*, and it is raised by the caller — so a failed send must not replace that
 // diagnosis with a Telegram error. It is reported and the caller's own stop still happens.
 //
@@ -47,8 +47,8 @@ function has_ignore_reason(reason: string | undefined): reason is string {
 	return reason !== undefined && reason.trim().length > 0
 }
 
-// Shared by every `followup` gate that can stop the run — the AI review scan and, since
-// joshuafolkken/kit#1578, the managed config-file gate. They ask the same two questions (was a reason
+// Shared by every `followup` gate that can stop the run — the AI review scan and the managed
+// config-file gate. They ask the same two questions (was a reason
 // given, and how is the confirmation sent), and a second copy of either answer is what lets the two
 // gates drift apart.
 const git_pr_confirmation = {

package/scripts/gh/git-pr-managed-config.ts

@@ -27,18 +27,16 @@ function build_report(hits: ReadonlyArray<ManagedHit>): Array<string> {
 	return [REPORT_HEADING, REPORT_PATHS_HEADING, managed_config_scope.format_hits(hits)]
 }
 
-// **This reports; it does not stop the merge** (joshuafolkken/kit#1592). joshuafolkken/kit#1578 made
-// it a confirmation gate that exited non-zero ahead of the CI wait, and in kit the condition it tests
-// is nearly always true: kit is the distribution source, so every change to `CLAUDE.md`, to
-// `prompts/`, to `.claude/skills/` or to the distributed part of `docs/` is by definition a change to
-// a distributed path. Measured on `epicrun #1413`, **two of three children stopped here** — and in
-// both the distributed file was what the Issue's own acceptance criteria had ordered changed. The
-// gate was not catching an unintended edit; it was stopping the work.
+// **This reports; it does not stop the merge**. In kit the condition it tests is nearly always
+// true: kit is the distribution source, so every change to `CLAUDE.md`, to `prompts/`, to
+// `.claude/skills/` or to the distributed part of `docs/` is by definition a change to a distributed
+// path, usually one the Issue's own acceptance criteria ordered changed. A gate that exits non-zero
+// here would not catch an unintended edit; it would stop the work.
 //
 // **There is deliberately no branch on which repository this is.** The alternative — stop in a
 // consumer, where editing a distributed file really is the mistake `CLAUDE.md` → "Route
-// distributed-doc / config changes upstream to kit" names, and stay quiet in kit — was weighed and
-// rejected on joshuafolkken/kit#1592: it needs a distribution-source test this package does not have,
+// distributed-doc / config changes upstream to kit" names, and stay quiet in kit — is rejected: it
+// needs a distribution-source test this package does not have,
 // no case is recorded of the gate saving a consumer's work, and the report below reaches a consumer's
 // reader just as well. `managed_config_scope` matches both ends of every mapping and distinguishes no
 // repository, and that property is kept rather than worked around.

package/scripts/gh/git-pr-messages.ts

@@ -1,5 +1,5 @@
 // What `pnpm josh git` prints once the pull request is open. It no longer claims anything about the
-// checks: this command returns before they have run (joshuafolkken/kit#1232), and the old
+// checks: this command returns before they have run, and the old
 // "All checks passed successfully." was printed on the strength of a watch whose verdict decided
 // nothing. Naming `pnpm josh followup` here is the whole replacement — it is what waits, and what
 // merges.

package/scripts/gh/git-pr.ts

@@ -1,14 +1,17 @@
 import { pr_classification, type ReleaseClassification } from '#scripts/ci/pr-classification'
 import type { IssueInfo } from '#scripts/git/git-issue'
 import { pr_info_schema } from '#scripts/git/git-schemas'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
 import { animation_helpers, type AnimationOptions } from '#scripts/lib/animation-helpers'
+import { json_value } from '#scripts/lib/json-value'
 import { git_gh_command } from './git-gh-command'
 import { git_pr_error } from './git-pr-error'
 import { git_pr_messages } from './git-pr-messages'
 
 // **Answers the new pull request's URL, and `undefined` when one already existed.** `pr_create`
 // filters its REST response to `.html_url`, so the address is in hand the moment the call returns —
-// which matters now that nothing waits before reporting it (joshuafolkken/kit#1232). `pr_get_url`
+// which matters now that nothing waits before reporting it. `pr_get_url`
 // resolves the branch through the `?head=…` listing, and that listing is eventually consistent: read
 // in the same instant the pull request was created it can answer nothing, and `pr_get_url` folds
 // "not there yet" and "the read failed" into the same `undefined`. The five-second sleep used to
@@ -49,8 +52,8 @@ async function display_pr_url_if_available(branch_name: string): Promise<void> {
 	}
 }
 
-// **This command stops at "the pull request is open"; it does not wait for the checks**
-// (joshuafolkken/kit#1232). It used to sleep five seconds and then watch the rollup on a two-minute
+// **This command stops at "the pull request is open"; it does not wait for the checks**.
+// It used to sleep five seconds and then watch the rollup on a two-minute
 // budget — measured at 119.8 seconds of one 1555-second run, 7.7% of it — and the answer decided
 // nothing: only `timed_out` was read, and only to pick which message to print. What actually blocks
 // a merge is `pnpm josh followup`, whose `wait_for_pr_success` asks a stricter question (CLEAN merge
@@ -89,17 +92,11 @@ async function create_and_report(
 }
 
 function parse_pr_state(pr_info_json: string): string | undefined {
-	try {
-		const result = pr_info_schema.safeParse(JSON.parse(pr_info_json))
-
-		return result.success ? result.data.state : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(pr_info_json, pr_info_schema)?.state
 }
 
 // A read that failed throws rather than answering `undefined`: "no state" is read as "not merged",
-// which would write onto a pull request that already merged (joshuafolkken/kit#3263).
+// which would write onto a pull request that already merged.
 async function get_pr_state(branch_name: string): Promise<string | undefined> {
 	const pr_info_json = await git_gh_command.pr_view(branch_name)
 
@@ -113,7 +110,7 @@ function is_pr_state_merged(pr_state: string | undefined): boolean {
 }
 
 // A body the caller supplied is written onto the pull request that is already open, rather than
-// dropped with the create that did not happen (joshuafolkken/kit#2446): a rerun carrying the
+// dropped with the create that did not happen: a rerun carrying the
 // live-execution evidence is how a merge `followup` refused for lacking it is recovered.
 async function report_existing_pr(
 	body: string,
@@ -164,11 +161,11 @@ async function create(
 }
 
 function build_title(issue_info: IssueInfo): string {
-	return `${issue_info.title} #${issue_info.number}`
+	return `${issue_info.title} ${issue_cite.plain(issue_info.number)}`
 }
 
 function build_body(issue_info: IssueInfo, extra_body?: string): string {
-	const closes = `closes #${issue_info.number}`
+	const closes = `closes ${issue_cite.plain(issue_info.number)}`
 
 	if (extra_body === undefined) return closes
 
@@ -199,7 +196,7 @@ async function create_for_issue(
 }
 
 // The label the pull request is opened with — also asked by `git-preflight.ts` before the commit, so
-// a missing classification is reported beside the other unmet preconditions (joshuafolkken/kit#2817).
+// a missing classification is reported beside the other unmet preconditions.
 async function release_classification(
 	issue_number: string,
 	branch_name: string,
@@ -211,7 +208,9 @@ async function release_classification(
 	const issue_json = await git_gh_command.issue_view_json(issue_number, 'labels,body')
 
 	if (issue_json === undefined) {
-		throw new Error(`Could not read issue #${issue_number} for release classification`)
+		throw new Error(
+			`Could not read issue ${session_cite.issue(issue_number)} for release classification`,
+		)
 	}
 
 	return pr_classification.select_issue_classification(issue_json)

package/scripts/gh/github-issue-url.ts

@@ -1,10 +1,9 @@
 // Reading a GitHub issue or pull-request URL as an identity: which repository it is in, and which
 // number. `josh notify` resolves the repository a notification is *about* this way, because the
 // working directory answers a different question — which repository the session happens to be
-// running in. A notification filed about another repository used to carry that repository's URL
-// under this repository's name (joshuafolkken/kit#903), and the same mismatch survived for a
-// notification carrying only a pull-request URL until joshuafolkken/kit#994 added the second form
-// here rather than beside it.
+// running in; reading it instead would file a notification about another repository under this
+// repository's name. Both the issue and the pull-request form live here, so a notification carrying
+// only a pull-request URL resolves the same way.
 //
 // Two other modules read a URL for something narrower and keep their own patterns. `epic-parse`
 // scans an epic body for task-list rows, so its regex is anchored to the row marker and runs
@@ -21,9 +20,9 @@ const REPOSITORY_SOURCE = `^${GITHUB_URL_PREFIX_SOURCE}([^/]+)/([^/]+)`
 // caller's fallback is the working directory, which is a visibly wrong answer rather than a
 // plausible one. A trailing `#anchor` or `?query` still parses, since neither is a word character.
 const ISSUE_URL_PATTERN = new RegExp(String.raw`${REPOSITORY_SOURCE}/issues/(\d+)\b`, 'u')
-// The same shape for a pull request. `git-pr-followup` used to carry its own copy of this, anchored
-// to the end of the string; reading `.../pull/12/files` now yields the repository it names instead
-// of nothing, which is the better answer for every caller (joshuafolkken/kit#994).
+// The same shape for a pull request, not anchored to the end of the string: reading
+// `.../pull/12/files` yields the repository it names instead of nothing, which is the better answer
+// for every caller.
 const PULL_URL_PATTERN = new RegExp(String.raw`${REPOSITORY_SOURCE}/pull/(\d+)\b`, 'u')
 
 // What both forms answer: which repository the URL names.
@@ -40,7 +39,7 @@ interface RepoIdentity {
 // The two forms carry their number under different names on purpose. A pull target is then not
 // assignable where an issue target is expected, so handing a PR number to a reader that asks the
 // issue endpoint is a compile error rather than a notification carrying an unrelated issue's title
-// — the joshuafolkken/kit#903 mismatch class, which this module exists to close.
+// — the mismatch class this module exists to close.
 interface IssueUrlTarget extends RepoIdentity {
 	issue_number: string
 }
@@ -91,7 +90,7 @@ function parse(issue_url: string | undefined): IssueUrlTarget | undefined {
 
 // A pull-request URL names the same repository an issue URL does. `josh notify` reads it when it was
 // given no `--issue-url`, so a completion notification carrying only a PR link stops being filed
-// under the working directory's repository (joshuafolkken/kit#994).
+// under the working directory's repository.
 function parse_pull(pull_url: string | undefined): PullUrlTarget | undefined {
 	const parsed = parse_with(PULL_URL_PATTERN, pull_url)
 	if (parsed === undefined) return undefined

package/scripts/git/base-tree.ts

@@ -0,0 +1,66 @@
+import { mkdtemp, rm, symlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { git_worktree } from './git-worktree'
+
+// A throwaway tree at one commit, for a command that has to run something on a tree other than the
+// caller's — `josh test:red` runs the new tests on the merge-base, `josh metrics` measures it.
+//
+// **It is a detached worktree, never the caller's checkout**: the caller's tree and index are neither
+// read back nor written. The worktree borrows this checkout's `node_modules` through a symlink rather
+// than installing its own: what is asked about is the source at that commit, and an install would add
+// seconds and a network dependency to every run.
+
+const TREE_NAME = 'tree'
+const NODE_MODULES = 'node_modules'
+
+interface BaseTree {
+	// The temp directory holding the tree — a file written here sits beside the tree, never in it.
+	parent: string
+	tree: string
+}
+
+async function prepare(tree: string, commit: string): Promise<void> {
+	await git_worktree.worktree_add_detached(tree, commit)
+	await symlink(path.resolve(NODE_MODULES), path.join(tree, NODE_MODULES), 'dir')
+}
+
+// Best effort: a removal that fails leaves a registration `worktree prune` drops once the directory is
+// gone, so the cleanup never replaces the caller's answer with its own error.
+async function remove(base_tree: BaseTree): Promise<void> {
+	try {
+		await git_worktree.worktree_remove(base_tree.tree)
+	} catch {
+		// The directory is deleted below and the prune drops the stale registration.
+	}
+
+	await rm(base_tree.parent, { force: true, recursive: true })
+
+	try {
+		await git_worktree.worktree_prune()
+	} catch {
+		// A failed prune leaves a stale registration the next prune drops; the answer stands.
+	}
+}
+
+async function with_tree<T>(
+	prefix: string,
+	commit: string,
+	use: (base_tree: BaseTree) => Promise<T>,
+): Promise<T> {
+	const parent = await mkdtemp(path.join(tmpdir(), prefix))
+	const base_tree = { parent, tree: path.join(parent, TREE_NAME) }
+
+	try {
+		await prepare(base_tree.tree, commit)
+
+		return await use(base_tree)
+	} finally {
+		await remove(base_tree)
+	}
+}
+
+const base_tree = { NODE_MODULES, with_tree }
+
+export type { BaseTree }
+export { base_tree }

package/scripts/git/change-base.ts

@@ -1,6 +1,7 @@
 import { git_command } from './git-command'
+import { git_spawn } from './git-spawn'
 
-// **The change base as a commit, or nothing — never a ref name** (joshuafolkken/kit#1537).
+// **The change base as a commit, or nothing — never a ref name**.
 //
 // `git_command.change_base` degrades to the default-branch *name* when `merge-base` cannot answer,
 // and a name moves. Any reader that stores one reading and compares it against a later one — the
@@ -21,6 +22,45 @@ async function resolved(): Promise<string | undefined> {
 	}
 }
 
-const change_base = { resolved }
+const MERGE_BASE_COMMAND = 'merge-base'
+const MERGE_HEAD = 'MERGE_HEAD'
+const LINE_BREAK = '\n'
+
+// Where the side a merge in progress brings in left the default branch — `undefined` where no merge
+// is in progress, which is every ordinary run.
+async function incoming_base(): Promise<string | undefined> {
+	try {
+		const reference = await git_command.default_branch_reference()
+
+		return await git_spawn.read([MERGE_BASE_COMMAND, reference, MERGE_HEAD])
+	} catch {
+		return undefined
+	}
+}
+
+// `--independent` drops every commit another one listed reaches, so of two commits on the default
+// branch's history it keeps the later.
+async function later_of(base: string, incoming: string): Promise<string> {
+	const kept = await git_spawn.read([MERGE_BASE_COMMAND, '--independent', base, incoming])
+	const [later = base] = kept.split(LINE_BREAK)
+
+	return later
+}
+
+// **The base of the tree, not of `HEAD`, while a merge is in progress.** A merge of the default
+// branch that stopped on a conflict has already put the default branch's files in the work tree, but
+// `HEAD` is still the commit before it — so `resolved` answers the old merge-base and everything the
+// default branch brought in reads as this branch's own change. The commit the merge is about to make
+// has both parents, and its merge-base is the later of theirs; that is the commit a reader measuring
+// the *tree* has to hold it to, and the one `resolved` answers by itself once the merge is committed.
+async function resolved_through_merge(): Promise<string | undefined> {
+	const [base, incoming] = await Promise.all([resolved(), incoming_base()])
+
+	if (base === undefined || incoming === undefined) return base
+
+	return await later_of(base, incoming)
+}
+
+const change_base = { resolved, resolved_through_merge }
 
 export { change_base }

package/scripts/git/changed-file-scope.ts

@@ -5,11 +5,11 @@ import { git_command } from './git-command'
 // The narrowing every scoped re-check shares: which files a check was narrowed by, or why it could
 // not be narrowed at all.
 //
-// joshuafolkken/kit#1257 gave the unit suite this shape and joshuafolkken/kit#1298 gave lint the
-// same one. The two differ only in which extensions they can read and in the words they print;
-// everything else — where the changed files come from, dropping what the tree no longer holds,
-// telling an unreadable change list apart from one that narrowed to nothing, and listing what was
-// narrowed by — was identical, so it lives here once rather than in each command.
+// The unit suite and lint share this shape. The two differ only in which extensions they can read
+// and in the words they print; everything else — where the changed files come from, dropping what
+// the tree no longer holds, telling an unreadable change list apart from one that narrowed to
+// nothing, and listing what was narrowed by — is identical, so it lives here once rather than in
+// each command.
 //
 // **A narrowed run is added in front of the whole check, never in place of it.** Both fallbacks
 // therefore end at the whole check, and each says which of the two it was: the one thing this must

package/scripts/git/changed-paths.ts

@@ -3,8 +3,7 @@ import { git_command } from './git-command'
 // The set of changed paths a mechanical, path-driven decision is made from.
 //
 // `josh review:level` asks this same question of the same tree (which level to review at), and a
-// second copy would let a caller disagree about what "changed" means. joshuafolkken/kit#907: sharing
-// this reading is the moment it stopped being one command's private helper.
+// second copy would let a caller disagree about what "changed" means.
 
 function to_paths(raw: string): Array<string> {
 	return raw

package/scripts/git/constants.ts

@@ -7,12 +7,12 @@ const SEPARATOR_LINE = '──────────────────
 const GIT_COMMAND_UNIX = '/usr/bin/git'
 // git's machine-readable output, asked for by the readers that parse rather than display. It lives
 // here rather than beside either of them because `status` and `worktree_list` now sit in different
-// modules (joshuafolkken/kit#1640) and a copy in each is a second answer to one question.
+// modules 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 another module's own reading cannot drift from it.
 const UNTRACKED_FILES_FLAG = '--untracked-files=all'
-// The git binary a spawn runs in place of the platform's own (joshuafolkken/kit#3234). The spawn path
+// The git binary a spawn runs in place of the platform's own. The spawn path
 // is absolute, so a `git` placed in front on `PATH` never stands in for it: the unit suite's network
 // guard shimmed `git` that way, and `josh ship`'s tests fetched and merged the default branch into the
 // checkout they ran in without the guard ever seeing the call. The guard names its shim here instead.

package/scripts/git/git-branch.ts

@@ -135,7 +135,7 @@ const git_branch = {
 	check_and_create_branch,
 	is_mismatch,
 	// Exported so a lane's branch name can be checked against the real matcher rather than against a
-	// second copy of the pattern (joshuafolkken/kit#1497). A copy is what let `lane/<N>` ship: nothing
+	// second copy of the pattern. 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,