@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

package/scripts/observations/observations-flush.ts

@@ -7,9 +7,9 @@ import type { BrokenLine } from './observation-ledger-line'
 import { observation_ledger_prepare } from './observation-ledger-prepare'
 import { observations_flush_landing } from './observations-flush-landing'
 
-// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). Every run —
+// The commit path for the ledger lines no run's own commit carried. Every run —
 // a lane's included — commits its appended lines with its own pull request (`scripts/git/
-// git-staging.ts`, joshuafolkken/kit#2763, joshuafolkken/kit#2919), and `pnpm josh followup` commits a
+// git-staging.ts`), and `pnpm josh followup` commits a
 // line appended after that commit before it merges, so what is left here is a line written on the
 // default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves.
 //
@@ -17,7 +17,7 @@ import { observations_flush_landing } from './observations-flush-landing'
 // their own over one path, wait on the same required checks every other pull request waits on, and
 // merge — so this reuses the same primitives rather than growing a second answer to "how does a
 // josh command open and land a pull request". The one difference is that this pull request is handed
-// to GitHub's auto-merge as soon as it opens (joshuafolkken/kit#2497), so it lands even when the wait
+// to GitHub's auto-merge as soon as it opens, so it lands even when the wait
 // below does not survive — `observations-flush-landing.ts` carries why.
 
 const COMMIT_MESSAGE = 'Record observation ledger entries'
@@ -72,7 +72,7 @@ function status_paths(status_output: string): ReadonlyArray<string> {
 		.map((line) => observation_ledger.status_path(line))
 }
 
-// **Single-sourced with `pnpm josh followup`'s pre-flush short-circuit** (joshuafolkken/kit#1810):
+// **Single-sourced with `pnpm josh followup`'s pre-flush short-circuit**:
 // the ledger-change test lives in `observation-ledger.ts`, so the two callers cannot drift.
 function has_ledger_change(status_output: string): boolean {
 	return observation_ledger.has_pending_append(status_output)
@@ -89,17 +89,17 @@ function other_changed_paths(status_output: string): ReadonlyArray<string> {
 // is what the ordinary off-default refusal says — would abandon them without a word, so this branch
 // of the refusal says the opposite.
 //
-// **The exits it names are ones the caller can actually take** (joshuafolkken/kit#1785). It used to
-// say "finish or delete that branch", and both are closed to an agent: the distributed
+// **The exits it names are ones the caller can actually take**. "Finish or delete that branch" are
+// both closed to an agent: the distributed
 // `.claude/settings.json` denies `Bash(git commit*)` and `Bash(git branch -d*)`, and `pnpm josh git`
-// excludes the ledger from staging by design (joshuafolkken/kit#1756), so finishing through it is not
+// excludes the ledger from staging by design, so finishing through it is not
 // possible either. Pushing the branch and landing its pull request is the route that is open.
 function stranded_flush_message(current: string): string {
 	return `\`${current}\` is a flush branch an earlier \`pnpm josh observations:flush\` left behind, and its appended observations are committed only there. Land it before flushing again — \`git push -u origin ${current}\`, then open and merge its pull request; \`pnpm josh ms\` here would leave the only copy of those lines behind.`
 }
 
-// **A flush branch with no commit on it strands nothing, so it is told the opposite**
-// (joshuafolkken/kit#1785). The appended lines never left the working tree, which makes the "only
+// **A flush branch with no commit on it strands nothing, so it is told the opposite**.
+// The appended lines never left the working tree, which makes the "only
 // copy" premise above factually false here — and makes `pnpm josh ms` the correct exit, the very one
 // the other message forbids.
 function empty_flush_message(current: string): string {
@@ -120,9 +120,9 @@ function off_default_message(current: string, default_branch: string): string {
 }
 
 // **A branch cut from a default branch that predates another merged flush conflicts by
-// construction** (joshuafolkken/kit#1768). The ledger is append-only and every writer adds at the
+// construction**. The ledger is append-only and every writer adds at the
 // same tail, so a stale start point opens a pull request `wait_for_pr_success` waits on until it
-// exhausts its budget rather than merging. The flush fast-forwards first (joshuafolkken/kit#2462), so
+// exhausts its budget rather than merging. The flush fast-forwards first, so
 // this is printed only when that fast-forward was refused — the reason is git's own.
 function behind_default_message(default_branch: string, reason: string): string {
 	return `\`pnpm josh observations:flush\` cuts its branch from \`${default_branch}\`, which is behind \`origin/${default_branch}\` and could not be fast-forwarded (${reason}) — a branch cut here would open a pull request that cannot merge. Run \`pnpm josh ms\` first.`
@@ -183,7 +183,7 @@ async function refuse_off_default(current: string, default_branch: string): Prom
 }
 
 // **The start point's freshness is judged without moving the working tree**, which is the whole
-// point of doing it here rather than pulling (joshuafolkken/kit#1768). `git fetch` updates the
+// point of doing it here rather than pulling. `git fetch` updates the
 // remote-tracking ref and `git rev-list --count HEAD..origin/<default>` reads it — neither writes a
 // file, so the ledger, dirty by definition when this runs, is left exactly as it is.
 async function commits_behind_default(default_branch: string): Promise<number> {
@@ -192,8 +192,8 @@ async function commits_behind_default(default_branch: string): Promise<number> {
 	return await git_command.commit_count_beyond('HEAD', `origin/${default_branch}`)
 }
 
-// **A default branch that is only behind is brought forward rather than refused**
-// (joshuafolkken/kit#2462). A lane's flush acts on the primary checkout, whose default branch is
+// **A default branch that is only behind is brought forward rather than refused**.
+// A lane's flush acts on the primary checkout, whose default branch is
 // behind by the lane's own merge every time — so the refusal alone stopped every lane close. A
 // `--ff-only` merge moves no file the dirty ledger conflicts with: git refuses it, untouched, when an
 // incoming commit changes the ledger too, and only that case is still refused.
@@ -231,7 +231,7 @@ async function refuse_unsafe_flush(status_output: string): Promise<string> {
 // **Its exit code is read rather than discarded**: `run` catches its own errors and returns `1`, so a
 // checkout left on the flush branch would otherwise be reported as a completed flush.
 //
-// **The local default branch is fast-forwarded before it is checked out** (joshuafolkken/kit#2462).
+// **The local default branch is fast-forwarded before it is checked out**.
 // Lines appended while the pull request waited leave the ledger dirty, and git refuses to check out a
 // default branch whose ledger differs from the flush branch's. Once the merge is in, the fast-forwarded
 // default branch holds the same ledger the flush branch does, so the checkout carries those lines over.
@@ -266,9 +266,8 @@ async function push_and_open(branch_name: string): Promise<string> {
 	}
 }
 
-// **The side that created the branch is the side that rolls it back** (joshuafolkken/kit#1785). A
-// commit rejected by the pre-commit hook used to leave the branch behind with nothing on it, and the
-// refusal the next run printed named two exits an agent cannot take. Nothing is stranded at this
+// **The side that created the branch is the side that rolls it back**, so a commit rejected by the
+// pre-commit hook does not leave the branch behind with nothing on it. Nothing is stranded at this
 // point — the appended lines are still in the working tree, staged and uncommitted — so returning to
 // the default branch and removing the branch loses none of them.
 //
@@ -300,7 +299,7 @@ function rejection_message(
 	return roll_back_failure_message(branch_name, reason, roll_back_reason)
 }
 
-// **Every ledger path the status names is staged, not the one constant** (joshuafolkken/kit#2724).
+// **Every ledger path the status names is staged, not the one constant**.
 // After a migration the change is the new file together with the old one's deletion, and a commit
 // holding only the first would leave the deletion behind as a change no later flush could tell apart
 // from a fresh append.
@@ -342,8 +341,8 @@ async function open_pull_request(branch_name: string, default_branch: string): P
 // at any more. The next flush would read `has_ledger_change` as false and report `clean`, which is
 // the silent loss the refusals above exist to prevent. Left on the branch, the refusal fires.
 //
-// With auto-merge on, a failed wait no longer strands the lines for good — GitHub still merges once
-// the checks pass (joshuafolkken/kit#2497) — but the checkout stays on the branch all the same,
+// With auto-merge on, a failed wait does not strand the lines for good — GitHub still merges once
+// the checks pass — but the checkout stays on the branch all the same,
 // because only a merge this command has seen makes returning to the default branch safe.
 async function land(
 	branch_name: string,
@@ -380,9 +379,9 @@ function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 }
 
 // **A malformed line is refused before a branch is cut, not after.** The ledger path was collected
-// without a line ever being parsed (joshuafolkken/kit#2123), so a broken append could ride a flush
+// without a line ever being parsed, so a broken append could ride a flush
 // through; validating here keeps the committed ledger to its grammar. The migration and the parse are
-// `observation-ledger-prepare.ts`'s, shared with the run's own commit (joshuafolkken/kit#2763).
+// `observation-ledger-prepare.ts`'s, shared with the run's own commit.
 async function prepare_ledger(): Promise<void> {
 	const broken = await observation_ledger_prepare.prepare(process.cwd())
 
@@ -392,12 +391,12 @@ async function prepare_ledger(): Promise<void> {
 // **Nothing pulls in front of the branch, and that is deliberate.** The ledger is dirty by
 // definition at this point, so `git pull --ff-only` aborts on it in exactly the case a pull would
 // have been for — an upstream flush that already advanced the ledger — and reports a failure about
-// the wrong thing (joshuafolkken/kit#1756's second review round). So the freshness of the start
-// point is read from the remote first (joshuafolkken/kit#1768), and `catch_up_default` fast-forwards
-// only where git can do it without touching the ledger (joshuafolkken/kit#2462): a default branch
+// the wrong thing. So the freshness of the start
+// point is read from the remote first, and `catch_up_default` fast-forwards
+// only where git can do it without touching the ledger: a default branch
 // that predates another merged flush still stops here — before a branch is cut — rather than opening
 // a pull request that cannot merge. An earlier flush pull request still open is checked for the same
-// reason (joshuafolkken/kit#2497): a branch cut beside it conflicts with it at the ledger's tail.
+// reason: a branch cut beside it conflicts with it at the ledger's tail.
 async function flush(now: Date): Promise<string> {
 	const status_output = await git_command.status()
 	const default_branch = await refuse_unsafe_flush(status_output)

package/scripts/overrides/overrides-check.ts

@@ -10,11 +10,15 @@
  */
 import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { overrides_snapshot_schema } from '#scripts/lib/schemas'
 import { overrides_files } from './overrides-files'
 import { overrides_check, type OverridesDiff } from './overrides-logic'
 
+const ARGV_OFFSET = 2
+const OPTIONS = { save: { type: 'boolean', default: false } } as const
+const USAGE = cli_flags.usage_line(['--save'], 'overrides')
+
 function is_file_not_found(error: unknown): boolean {
 	return error instanceof Error && 'code' in error && error.code === 'ENOENT'
 }
@@ -70,15 +74,21 @@ function run_overrides_check(should_save: boolean): void {
 	console.info(`✔ overrides unchanged (${summary}).`)
 }
 
-function main(): void {
-	const { values } = parseArgs({
-		options: { save: { type: 'boolean', default: false } },
-		strict: true,
-	})
+// A line nobody can read is refused before the snapshot is read or written: a misspelled `--save` that
+// fell through would compare against the record the caller meant to replace.
+function refuse_usage(): never {
+	console.error(USAGE)
+
+	return process.exit(1)
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	const values = cli_flags.values_of(argv, OPTIONS)
 
+	if (values === undefined) refuse_usage()
 	run_overrides_check(values.save)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
 
-export { run_overrides_check }
+export { run_overrides_check, main }

package/scripts/package/package-scout-cli.ts

@@ -13,7 +13,7 @@ import { package_scout_format } from './package-scout-format'
 
 // `josh pkg:scout <keywords> [--size <n>]` — before the Package-First tier decision, rank the
 // candidate packages by measured metrics so "clearly best (Tier A)" and "genuine toss-up (Tier B)"
-// are read off the output rather than judged (joshuafolkken/kit#2216).
+// are read off the output rather than judged.
 //
 // The registry answers in three reads: one search for the candidates, then per candidate a downloads
 // point and the latest version metadata (bundled types, license, unpacked size). A per-candidate read

package/scripts/package/package-scout-format.ts

@@ -6,8 +6,8 @@ import {
 } from './package-scout'
 
 // The printed shape of `josh pkg:scout` — one line per candidate with each metric labelled, then a
-// verdict line that names whether the choice is a Tier A pick or a Tier B question
-// (joshuafolkken/kit#2216). Formatting is pure so the layout and the verdict wording are unit-tested
+// verdict line that names whether the choice is a Tier A pick or a Tier B question.
+// Formatting is pure so the layout and the verdict wording are unit-tested
 // without a registry.
 
 // The blank shown for a metric the registry did not report — a fact absent, never a zero measured.

package/scripts/package/package-scout.ts

@@ -1,6 +1,6 @@
 // The measured metrics behind `josh pkg:scout` — the ranking of package candidates and the near-tie
 // verdict that turns the Package-First "clearly best (Tier A) / genuine toss-up (Tier B)" branch from
-// an impression into a computed answer (joshuafolkken/kit#2216).
+// an impression into a computed answer.
 //
 // This module is the pure half: it takes candidates already gathered from the npm registry and
 // answers two things — the order they rank in, and whether the top two are close enough that the

package/scripts/propagate/propagate-git-failure.ts

@@ -7,7 +7,7 @@ import type { StepResult } from './propagate-run'
 // a failed spawn reports one exit code for all three. The run's report then appended "upgrade/sync
 // changes left uncommitted" to that code, which names the *first* of the three: so a consumer whose
 // pre-push hook refused the push was reported as a consumer whose sync never got committed, and the
-// reader went looking at a sync that had worked (joshuafolkken/kit#1417).
+// reader went looking at a sync that had worked.
 //
 // **Nothing here changes whether a push is blocked.** A consumer's pre-push gate refusing a push is
 // the gate doing its job, and the probes below are read-only. What is fixed is the sentence.

package/scripts/propagate/propagate-git.ts

@@ -10,7 +10,7 @@ import { GIT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 // Propagation commits and pushes. A consumer with uncommitted work would have that work swept into
 // the upgrade commit — `josh git` stages the whole tree — and a supplier repository that is behind
 // its remote would propagate the *previous* release, which is already published and would report
-// success (joshuafolkken/kit#863).
+// success.
 
 // The probes that talk to the remote get their own budget. Ten seconds is generous for a local
 // `rev-parse` and tight for an ssh handshake, and a probe that times out answers "no" — which for
@@ -27,7 +27,7 @@ interface TreeState {
 	reason?: string
 }
 
-// **`cwd` alone does not say which repository this is about** (joshuafolkken/kit#1515). `GIT_DIR` and
+// **`cwd` alone does not say which repository this is about**. `GIT_DIR` and
 // `GIT_WORK_TREE` beat it outright, and git exports both to every hook it runs — so under
 // `pnpm josh git`'s pre-push hook every probe below silently answered about the checkout the hook was
 // firing in rather than the path it was handed. The visible cost was in the unit suite, where
@@ -42,8 +42,8 @@ interface TreeState {
 // because every call below already passes the path this way and a second spelling of the same intent
 // is one more thing to keep in step.
 //
-// **The list itself moved to `#scripts/git/git-location-environment`** when joshuafolkken/kit#1530
-// found the same defect in a second file: three consumers now clear the same names, and a list kept
+// **The list itself lives in `#scripts/git/git-location-environment`**: three consumers clear the
+// same names, and a list kept
 // in one of them is a list the other two drift away from. It widened there past `GIT_DIR` /
 // `GIT_WORK_TREE` to the index and object-store variables, which redirect a *write* rather than a
 // lookup — inert for the read-only probes below, and required by the fixture that commits.
@@ -116,8 +116,8 @@ function commit_ahead(repository_path: string, default_name: string): string | u
 // remote-tracking ref: a push that was refused leaves no such ref behind, and neither does a branch
 // that was never pushed at all, so the ref cannot tell the two apart.
 //
-// **The arguments come from `git-ls-remote.ts`, which anchors the pattern at `refs/heads/`**
-// (joshuafolkken/kit#1732). Built here from the bare name, the query answered for any branch whose
+// **The arguments come from `git-ls-remote.ts`, which anchors the pattern at `refs/heads/`**.
+// Built here from the bare name, the query answered for any branch whose
 // ref ends in it — so a lane pushed as `wip/1641-lane` reported `1641-lane` as already on origin,
 // and propagation classified an unpushed branch as pushed.
 function has_remote_branch(repository_path: string, branch: string): boolean {
@@ -130,7 +130,7 @@ function has_remote_branch(repository_path: string, branch: string): boolean {
 // --git-path` does not. Without this the classification would name a hook on the strength of a dry
 // run alone, and **any** push failure that has cleared by the time the probe runs satisfies that: a
 // dropped ssh connection, a refreshed token, one 500 from GitHub. Naming a hook that does not exist
-// is the same misattribution joshuafolkken/kit#1417 was filed for, pointed the other way.
+// is the same misattribution as blaming the wrong push sub-step, pointed the other way.
 function hooks_directory(repository_path: string): string | undefined {
 	const configured = run_git(repository_path, ['config', '--get', 'core.hooksPath'])
 	if (configured !== undefined && configured !== '') return configured

package/scripts/propagate/propagate-plan.ts

@@ -3,7 +3,7 @@ import { propagate_run, type RunStep, type StepResult } from './propagate-run'
 import { propagate_steps, type Release, type ReleasePlan } from './propagate-steps'
 import { propagate_targets, type Manifest, type PropagateTarget } from './propagate-targets'
 
-// What one `josh propagate` run carries, decided from the repository it runs in (joshuafolkken/kit#2879).
+// What one `josh propagate` run carries, decided from the repository it runs in.
 //
 // The supplier is kit or any toolkit built on it — app-kit, game-kit — and a toolkit's propagation
 // carries the base packages under it too, at the versions that toolkit itself has installed and was
@@ -77,7 +77,7 @@ function pin_installed(project_root: string, release: Release): Release | undefi
 }
 
 // Why a declared base toolkit would fall out of the plan, naming it — either way `josh adopt` refuses
-// one for (joshuafolkken/kit#1540). A base left out is not merely left behind: every consumer that
+// one for. A base left out is not merely left behind: every consumer that
 // installs it would then read it as a toolkit above this one and be skipped.
 function incomplete_cause(project_root: string): string | undefined {
 	const misplaced = adopt_toolkits.misplaced_toolkits(project_root)

package/scripts/propagate/propagate-publish.ts

@@ -7,9 +7,8 @@ import { with_page_size } from '#scripts/version/version-remote'
 //
 // A merge is not a publish: kit's auto-tag and publish workflows run after the merge commit lands,
 // so a consumer told to upgrade the instant the PR merged resolves the previous release. The wait is
-// implemented once here because joshuafolkken/kit#864 resolves a cross-repository child on the same
-// condition — two implementations would drift, and the looser one would decide
-// (joshuafolkken/kit#863).
+// implemented once here because resolving a cross-repository epic child waits on the same
+// condition — two implementations would drift, and the looser one would decide.
 
 const VERSIONS_PAGE_SIZE = 100
 const NAMES_JQ = '[.[] | .name]'

package/scripts/propagate/propagate-run.ts

@@ -5,11 +5,11 @@ import type { PropagateTarget } from './propagate-targets'
 //
 // One consumer's failure never stops another: the whole point of the command is to leave the run
 // knowing which consumers took the release and which did not, and a run that aborts on the first
-// failure answers that for a prefix of them (joshuafolkken/kit#863).
+// failure answers that for a prefix of them.
 
 // The steps, in order, that carry a release into one consumer. `josh` here is the consumer's own
 // installed CLI, run from the consumer's directory — which is what keeps kit's self-sync guard
-// (joshuafolkken/kit#868) out of the way: the sync runs in a consumer project, where it belongs.
+// out of the way: the sync runs in a consumer project, where it belongs.
 const STEP_PRECHECK = 'working tree check'
 const STEP_UPGRADE = 'josh vu'
 const STEP_SYNC = 'josh sync'
@@ -44,8 +44,7 @@ interface StepResult {
 	// file, for instance. The sequence ends here as a skip rather than opening an empty pull request.
 	is_complete?: boolean
 	// What this failure actually left in the consumer, as the failing step measured it. Only the
-	// steps that can probe set it; for the rest the standing note below is what they always leave
-	// (joshuafolkken/kit#1417).
+	// steps that can probe set it; for the rest the standing note below is what they always leave.
 	leftover?: string
 }
 
@@ -89,9 +88,8 @@ function has_leftover_changes(steps: ReadonlyArray<StepResult>): boolean {
 
 // What to say the failure left behind. A step that measured it wins; the note above stands in only
 // where none did, which is every step before the commit — and there it is accurate, since nothing
-// has committed yet. Before joshuafolkken/kit#1417 it was appended to *every* failure after the
-// upgrade, including one whose commit had already been made, so a push refused by the consumer's
-// pre-push hook was reported as changes that were never committed.
+// has committed yet. Appended to *every* failure after the upgrade, it would report a push refused
+// by the consumer's pre-push hook as changes that were never committed.
 function leftover_of(result: StepResult, steps: ReadonlyArray<StepResult>): string | undefined {
 	if (!has_leftover_changes(steps)) return undefined
 

package/scripts/propagate/propagate-select.ts

@@ -1,7 +1,7 @@
 import { propagate_run } from './propagate-run'
 import type { PropagateTarget, TargetState } from './propagate-targets'
 
-// Narrowing a run to the one consumer `--target` names (joshuafolkken/kit#2755).
+// Narrowing a run to the one consumer `--target` names.
 //
 // Every other consumer stays in the list as `not_selected`, so the report still accounts for each
 // repository considered and says why it was left alone. A name that matches nothing — or matches a

package/scripts/propagate/propagate-steps.ts

@@ -1,6 +1,7 @@
 import { pr_classification } from '#scripts/ci/pr-classification'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { OTHER_CHANGE_LABEL } from '#scripts/issue/issue-labels'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { error_text } from '#scripts/lib/error-message'
@@ -18,11 +19,11 @@ import type { PropagateTarget } from './propagate-targets'
 // Kept out of the command module because two of the steps are not plain spawns: the pre-check is a
 // decision made from git probes, and the pull-request step needs the issue number the step before it
 // created. A closure carries that number instead of module-level state, so a run is self-contained
-// and the sequencing stays testable (joshuafolkken/kit#863).
+// and the sequencing stays testable.
 
 const SUCCESS_EXIT_CODE = 0
 // The consumer-side gate. `josh gate` is the same command the AI documents require of a person
-// (joshuafolkken/kit#914) — running the four checks concurrently and reporting every failure in one
+// — running the four checks concurrently and reporting every failure in one
 // pass — so the chain is not repeated here. It resolves in the consumer's directory, which by this
 // point has already been upgraded to the version being propagated, so the command is present.
 const VERIFY_SCRIPT = `pnpm josh ${GATE_COMMAND}`
@@ -37,12 +38,11 @@ const STEP_COMMANDS: Readonly<Record<string, ReadonlyArray<string>>> = {
 
 // kit's own CLI name. The sync is spelled through the *toolkit's* bin rather than hardcoded, because
 // `@joshuafolkken/app-kit` syncs with `josh-app` and `@joshuafolkken/game-kit` with `josh-game`; a
-// run that synced only `josh` would leave the other toolkit's managed files behind
-// (joshuafolkken/kit#1085).
+// run that synced only `josh` would leave the other toolkit's managed files behind.
 const JOSH_BIN = 'josh'
 
 // `pnpm <bin>` resolves the target's own installed CLI, never this checkout — which is what keeps
-// the sync a consumer-side sync and leaves kit's self-sync guard (joshuafolkken/kit#868) satisfied.
+// the sync a consumer-side sync and leaves kit's self-sync guard satisfied.
 function sync_command(bin_name: string): ReadonlyArray<string> {
 	return ['pnpm', bin_name, 'sync']
 }
@@ -67,9 +67,9 @@ const PROPAGATE_ORIGIN =
 	'Opened by `josh propagate` from the supplier repository after the release was published.'
 const RUN_NOTE =
 	'The upgrade, the managed-file sync and the verification gate have already run here.'
-// `josh git` refuses to open a pull request for an issue that declares no release classification
-// (joshuafolkken/kit#2666), so the upgrade issue declares one. A dependency upgrade changes no code of
-// the consumer's own, which is what `other-change` covers (joshuafolkken/kit#2858).
+// `josh git` refuses to open a pull request for an issue that declares no release classification,
+// so the upgrade issue declares one. A dependency upgrade changes no code of
+// the consumer's own, which is what `other-change` covers.
 const UPGRADE_CLASSIFICATION = OTHER_CHANGE_LABEL
 const EMPTY_PLAN_TITLE = 'Upgrade the installed toolkits'
 const LAST_SEPARATOR = ' and '
@@ -91,8 +91,8 @@ function release_names(releases: ReadonlyArray<Release>): string {
 }
 
 // Each release with its own version, for a plan whose releases disagree on one — a toolkit's
-// propagation carries the base packages at the versions that toolkit was verified with
-// (joshuafolkken/kit#2879), so one shared "to <version>" would name a version most of them are not.
+// propagation carries the base packages at the versions that toolkit was verified with,
+// so one shared "to <version>" would name a version most of them are not.
 function versioned_names(releases: ReadonlyArray<Release>): string {
 	const named = releases.map((release) => ({
 		...release,
@@ -181,9 +181,8 @@ function spawn_step(
 }
 
 // The same, keeping what the command printed. Only the pull-request step uses it: a consumer's
-// pre-push hook names the check that stopped it in its own last lines, and until
-// joshuafolkken/kit#1417 nothing in the run kept them — so the report had one exit code to attribute
-// three sub-steps with, and attributed it to the wrong one.
+// pre-push hook names the check that stopped it in its own last lines, and without them
+// the report has one exit code to attribute three sub-steps with, and can blame the wrong one.
 //
 // **This step's output is replayed when it finishes rather than printed as it runs**, and that is
 // the price of keeping it. A synchronous spawn gives one target per file descriptor, so `['inherit',
@@ -233,10 +232,10 @@ function precheck_step(target: PropagateTarget, step: string): StepResult {
 // rather than a branchless pull request that cannot be opened at all.
 //
 // It posts to REST instead of running `gh issue create`: that command goes through GraphQL, which a
-// cloud session is answered 403 for, while the REST endpoint is served normally
-// (joshuafolkken/kit#1022). This was the last `gh <noun> <verb>` spawn in kit's own code, and it was
+// cloud session is answered 403 for, while the REST endpoint is served normally.
+// This was the last `gh <noun> <verb>` spawn in kit's own code, and it was
 // missed by that epic's survey because the survey counted `exec_gh_command` call sites and this one
-// spawned gh directly (joshuafolkken/kit#1042).
+// spawned gh directly.
 //
 // The request is the one every issue creation builds, and the spawn is the synchronous twin of the
 // one the asynchronous writers use — so no second write layer exists to disagree with the first.
@@ -246,7 +245,7 @@ function precheck_step(target: PropagateTarget, step: string): StepResult {
 // gh's own output is the only thing that distinguishes a missing scope from disabled issues from a
 // repository that does not exist. Reporting `could not open an issue` alone hides all three, so the
 // whole message is kept — `to_gh_error` puts the stderr summary and the JSON body REST writes to
-// stdout on separate lines (joshuafolkken/kit#1029), and both carry the reason.
+// stdout on separate lines, and both carry the reason.
 //
 // **It is folded back onto one line here.** The run's report is one line per consumer, and
 // `failure_reason` appends the "changes left uncommitted" warning to the end of this text — so a
@@ -319,7 +318,7 @@ function issue_step(
 
 // Put the consumer back on its default branch. `josh git` leaves it on the feature branch, and the
 // next run's pre-check would refuse it for that — the consumer would silently stop receiving
-// releases (joshuafolkken/kit#863).
+// releases.
 function return_step(target: PropagateTarget, step: string): StepResult {
 	if (propagate_git.return_to_default_branch(target.path)) return { step, is_ok: true }
 
@@ -335,7 +334,7 @@ function pull_request_step(
 ): StepResult {
 	const number = issue_numbers.get(target.repo)
 	if (number === undefined) return { step, is_ok: false, detail: 'no issue number' }
-	const argument = `${plan_title(plan.releases)} #${number}`
+	const argument = `${plan_title(plan.releases)} ${issue_cite.plain(number)}`
 	const outcome = spawn_captured(target, step, ['pnpm', 'josh', 'git', '-y', argument])
 	if (outcome.result.is_ok) return outcome.result
 
@@ -352,7 +351,7 @@ interface Release {
 
 // What one run carries: the releases, and the sentence naming the command that opened the issue.
 // `josh propagate` always passes exactly one release; `josh adopt` passes every toolkit installed in
-// the repository it runs in (joshuafolkken/kit#1085). Only the upgrade and the sync repeat per
+// the repository it runs in. Only the upgrade and the sync repeat per
 // release — the pre-check, the verification gate, the issue, the pull request and the return to the
 // default branch happen once, which is why the step order itself is unchanged.
 interface ReleasePlan {