@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/backlog/backlog-stalled-cli.ts

@@ -3,8 +3,8 @@ import { fileURLToPath } from 'node:url'
 import { backlog_stalled } from './backlog-stalled'
 import { backlog_stalled_detect } from './backlog-stalled-detect'
 
-// `josh backlog:stalled` — read the three conditions once and print the verdict
-// (joshuafolkken/kit#2359). This is the manual and testable face of the detector `stop-guard.ts` runs
+// `josh backlog:stalled` — read the three conditions once and print the verdict.
+// This is the manual and testable face of the detector `stop-guard.ts` runs
 // on every stop; both call the one `detect_and_report`, so the command and the hook can never drift.
 //
 // **It reports, it never stops.** The exit code is always success — a stall is a state to surface, not

package/scripts/backlog/backlog-stalled-detect.ts

@@ -4,7 +4,7 @@ import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
 import { backlog_stalled, type StallReading, type StallVerdict } from './backlog-stalled'
 
-// The I/O half of the stall detector (joshuafolkken/kit#2359): it gathers the three counts the pure
+// The I/O half of the stall detector: it gathers the three counts the pure
 // judge in `backlog-stalled.ts` weighs, then — on a stall — leaves the marker and sends the one
 // notification. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary; the CLI
 // exposes the same call for a person to run by hand.
@@ -37,8 +37,8 @@ interface DetectPorts {
 }
 
 // The free-lane and runnable-issue reads are `backlog-ready.ts`'s — the watcher's ready line reads the
-// same two, so they live once there (joshuafolkken/kit#2452) — and a caller that reads them again after
-// this check hands its own ports in, so the two share one reading (joshuafolkken/kit#2472).
+// same two, so they live once there — and a caller that reads them again after
+// this check hands its own ports in, so the two share one reading.
 function ready_count_of(ready: ReadyPorts): () => Promise<number> {
 	return async function (): Promise<number> {
 		const issues = await ready.ready_issues()
@@ -48,7 +48,7 @@ function ready_count_of(ready: ReadyPorts): () => Promise<number> {
 }
 
 // One stall per episode, and the episode ends at a dispatch rather than at whatever event lands next
-// (joshuafolkken/kit#2464) — every parallel lane appends to this stream, so a newest-event dedup re-fired.
+// — every parallel lane appends to this stream, so a newest-event dedup re-fired.
 async function real_emit_stall(text: string): Promise<boolean> {
 	const { STALL, CHILD_LAUNCH } = run_event_stream.EVENT_KIND
 

package/scripts/backlog/backlog-stalled.ts

@@ -1,8 +1,9 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
-// When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks
-// (joshuafolkken/kit#2359). This is the mechanical judge of that state: three facts read, never
+// When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks.
+// This is the mechanical judge of that state: three facts read, never
 // weighed — is there runnable work, is there a free lane, and has nothing been dispatched for a while.
 // The verdict is a report, not a stop: a false positive costs one notification, never a halted run.
 //
@@ -86,8 +87,6 @@ function describe(reading: StallReading): string {
 	return `${String(reading.ready_count)} ready, ${String(reading.free_lanes)} free lane(s), ${String(minutes)}m since the last dispatch`
 }
 
-const NUMERIC_TOKEN = /^\d+$/u
-
 // The runnable issue numbers `backlog:next` printed: one token per line, a bare number per runnable
 // issue and a verdict word (`wait`, `stop`, …) when there is none — so the numeric lines are the ready
 // issues.
@@ -95,14 +94,14 @@ function ready_tokens(out: string): ReadonlyArray<string> {
 	return out
 		.split('\n')
 		.map((token) => token.trim())
-		.filter((token) => NUMERIC_TOKEN.test(token))
+		.filter((token) => issue_number_shape.is_issue_number(token))
 }
 
 function count_ready_tokens(out: string): number {
 	return ready_tokens(out).length
 }
 
-// Whether `backlog:next` answered `triage` (joshuafolkken/kit#2779): no number is runnable, yet a session
+// Whether `backlog:next` answered `triage`: no number is runnable, yet a session
 // has work — judging the untriaged issues — so a reader of the numeric lines alone would take it for an
 // empty pool.
 function needs_triage(out: string): boolean {

package/scripts/backlog/backlog-waves.ts

@@ -12,16 +12,16 @@ import {
 import { backlog_plan, type PlanContext } from './backlog-plan'
 import { backlog_rank, type GateScope } from './backlog-rank'
 
-// The order a `backlogrun` takes, wave by wave, before it starts (joshuafolkken/kit#2778).
+// The order a `backlogrun` takes, wave by wave, before it starts.
 //
 // `backlog:next` answers one ask — what may start now — and `backlog:plan` shows the pool that ask is
 // made from, so the order past the first answer was left for a person to work out by hand. This plays
 // the asks forward under one assumption: **every issue of a wave merges before the next wave starts**.
 //
 // **No rule is written twice.** The first wave is `backlog_rank.select` — rank, `run:solo` gate,
-// restructure separation, cap —
+// overlap separation, cap —
 // over the very candidates `backlog:next` resolves, asked of an idle repository — so it is what
-// `backlog:next` prints when nothing is running (joshuafolkken/kit#2928). Each later wave marks the earlier waves closed and re-classifies the same pool
+// `backlog:next` prints when nothing is running. Each later wave marks the earlier waves closed and re-classifies the same pool
 // through `epic_classify.classify_children` with the resolver `epic:next` sorted it with the first
 // time — `epic_cross_repo.resolve_cross_repo`, so a blocker in another repository still waits for its
 // release rather than counting as done on close — then puts the runnable set through
@@ -109,7 +109,7 @@ function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<Epi
 
 // Each wave is closed before the next is asked for; a wave that offers nothing ends the plan, which
 // the pool's size bounds because every wave closes at least one child. `scope` names the rows the
-// offer's cap bounds and the paths each issue restructures; left empty, no wave is capped or separated.
+// offer's cap bounds and the paths each issue declares; left empty, no wave is capped or separated.
 function build(result: EpicNextResult, repo: string, scope: GateScope = EMPTY_SCOPE): WavePlan {
 	const pool = pool_of(result, repo, scope)
 	const done = new Set<string>()

package/scripts/backlog/backlogrun-args.ts

@@ -0,0 +1,74 @@
+import type { AgentProvider } from '#scripts/agent/agent-role-profile'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { run_invocation } from '#scripts/run/run-invocation'
+
+// `josh backlogrun`'s arguments. `--agent claude|codex` picks the agent the run
+// is started in; everything else is the `backlogrun` invocation itself, read by `run-invocation.ts`'s
+// grammar — the one the carry record and the woken session read — so the launcher accepts exactly what a
+// typed `backlogrun` would carry, and the text the agent is handed is the grammar's rebuild of it.
+//
+// **A bare number is an issue.** A shell reads an unquoted `#3437` as a comment, so `3437` in the named
+// list is taken as `#3437`; a number after the first flag is that flag's value and is left alone.
+
+const AGENT_FLAG = '--agent'
+const BACKLOG_COMMAND = 'backlogrun'
+const ISSUE_PREFIX = '#'
+const FLAG_PREFIX = '-'
+const NOT_FOUND = -1
+const FLAG_AND_VALUE = 2
+const AGENTS: Readonly<Record<string, AgentProvider>> = { claude: 'anthropic', codex: 'openai' }
+const DEFAULT_AGENT = 'claude'
+
+interface BacklogrunArguments {
+	provider: AgentProvider
+	// The canonical `backlogrun …` text the agent is started with.
+	invocation: string
+	issues: ReadonlyArray<number>
+}
+
+type ArgumentsResult = { kind: 'args'; args: BacklogrunArguments } | { kind: 'refused' }
+
+interface AgentSplit {
+	agent: string | undefined
+	rest: ReadonlyArray<string>
+}
+
+// `--agent` and its value out of the list; a second `--agent` stays in and the grammar refuses it.
+function split_agent(argv: ReadonlyArray<string>): AgentSplit {
+	const at = argv.indexOf(AGENT_FLAG)
+
+	if (at === NOT_FOUND) return { agent: DEFAULT_AGENT, rest: argv }
+
+	const after = at + FLAG_AND_VALUE
+
+	return { agent: argv[at + 1], rest: [...argv.slice(0, at), ...argv.slice(after)] }
+}
+
+function issue_token(token: string): string {
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(token) ? `${ISSUE_PREFIX}${token}` : token
+}
+
+// The named list is the leading block before the first flag, as the grammar reads it.
+function normalized(rest: ReadonlyArray<string>): Array<string> {
+	const stop = rest.findIndex((token) => token.startsWith(FLAG_PREFIX))
+	const split_at = stop === NOT_FOUND ? rest.length : stop
+
+	return [...rest.slice(0, split_at).map((token) => issue_token(token)), ...rest.slice(split_at)]
+}
+
+function parse(argv: ReadonlyArray<string>): ArgumentsResult {
+	const { agent, rest } = split_agent(argv)
+	const provider = agent === undefined ? undefined : AGENTS[agent]
+	const invocation = run_invocation.rebuild([BACKLOG_COMMAND, ...normalized(rest)].join(' '))
+
+	if (provider === undefined || invocation === undefined) return { kind: 'refused' }
+
+	const issues = run_invocation.issue_numbers(invocation) ?? []
+
+	return { kind: 'args', args: { provider, invocation, issues } }
+}
+
+const backlogrun_args = { parse }
+
+export type { BacklogrunArguments }
+export { backlogrun_args }

package/scripts/backlog/backlogrun-cli.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { run_board_cli } from '#scripts/run/board/run-board-cli'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { backlogrun_args, type BacklogrunArguments } from './backlogrun-args'
+import { backlogrun_launch, type LaunchTarget, type StartResult } from './backlogrun-launch'
+
+// `josh backlogrun` — start a `backlogrun` from the terminal and watch it. A
+// run already going is never joined by a second one: the board is shown, and any issue named is pointed
+// at `run:add` rather than added behind the person's back. Otherwise the agent is started in the
+// background, its output to a log file, and the board takes over the terminal at once. Closing the
+// board closes only the board.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE =
+	'Usage: josh backlogrun [#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]'
+
+interface BacklogrunPorts {
+	repository_directory: () => Promise<string | undefined>
+	is_running: (git_directory: string) => boolean
+	start: (args: BacklogrunArguments, target: LaunchTarget) => StartResult
+	show_board: () => Promise<number>
+	write: (line: string) => void
+}
+
+const LIVE_PORTS: BacklogrunPorts = {
+	repository_directory: run_carry.repository_directory,
+	is_running: backlogrun_launch.is_running,
+	start: (args, target) => backlogrun_launch.start(args.invocation, args.provider, target),
+	show_board: async () => await run_board_cli.run([]),
+	write: (line) => process.stdout.write(`${line}\n`),
+}
+
+function running_notes(issues: ReadonlyArray<number>): Array<string> {
+	const additions = issues.map((issue) => `  pnpm josh run:add ${String(issue)}`)
+	const guidance = additions.length > 0 ? ['To add the named issues to it:', ...additions] : []
+
+	return ['backlogrun: a run is already going; showing its board.', ...guidance]
+}
+
+function launched_note(result: Extract<StartResult, { kind: 'launched' }>): string {
+	const { pid, session, log_path } = result.launched
+	const session_part = session === undefined ? '' : `, session ${session}`
+
+	return `backlogrun: started (pid ${String(pid)}${session_part}); log ${log_path}`
+}
+
+// The agent starts in the main checkout, the parent of the common git directory every record is keyed on.
+function target_of(git_directory: string): LaunchTarget {
+	return { worktree: path.dirname(git_directory), git_directory }
+}
+
+async function begin(
+	args: BacklogrunArguments,
+	git_directory: string,
+	ports: BacklogrunPorts,
+): Promise<number> {
+	if (ports.is_running(git_directory)) {
+		for (const note of running_notes(args.issues)) ports.write(note)
+
+		return await ports.show_board()
+	}
+
+	const result = ports.start(args, target_of(git_directory))
+
+	if (result.kind === 'failed') {
+		ports.write(`backlogrun: could not start: ${result.note}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	ports.write(launched_note(result))
+
+	return await ports.show_board()
+}
+
+async function run(
+	argv: ReadonlyArray<string>,
+	ports: BacklogrunPorts = LIVE_PORTS,
+): Promise<number> {
+	const parsed = backlogrun_args.parse(argv)
+
+	if (parsed.kind === 'refused') {
+		ports.write(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const git_directory = await ports.repository_directory()
+
+	if (git_directory === undefined) {
+		ports.write('backlogrun: not inside a git repository')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await begin(parsed.args, git_directory, ports)
+}
+
+const backlogrun_cli = { run }
+
+// `.env` is read inside the guard, as `run:board` reads it, so the board draws in the person's
+// `JOSH_SESSION_LANG` while the unit tests see no developer's `.env`.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	josh_environment_file.load_environment_file()
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+export type { BacklogrunPorts }
+export { backlogrun_cli }

package/scripts/backlog/backlogrun-launch.ts

@@ -0,0 +1,178 @@
+import { randomUUID } from 'node:crypto'
+import { agent_argv, type AgentArgvResult } from '#scripts/agent/agent-argv'
+import {
+	agent_role_profile,
+	type AgentEnvironment,
+	type AgentProvider,
+} from '#scripts/agent/agent-role-profile'
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
+import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
+import { run_headless } from '#scripts/run/run-headless'
+import { z } from 'zod'
+
+// How `josh backlogrun` starts a `backlogrun` parent in the background, and how
+// it tells one is already running so a second is never started beside it.
+//
+// **Running is two records, not one.** A parent claims the carry record a little after it starts, so
+// between the launch and the claim only the launch record this file writes says a run is coming; once
+// the claim is made the carry record's owner is what answers. Either one live is a run.
+//
+// **The agent is the person's choice, not the shell's.** The provider is resolved from an environment
+// with every agent-session key cleared and the choice handed in, so a command typed inside a Claude Code
+// session can still start a Codex parent. The same choice is handed to the parent as
+// `JOSH_AGENT_PROVIDER`, the key a detached child with no session of its own resolves from.
+
+const LAUNCH_PREFIX = 'josh-backlogrun-launch-'
+const LOG_PREFIX = 'josh-backlogrun-log-'
+const LOG_SUFFIX = '.log'
+
+const launch_schema = z.object({
+	pid: z.number(),
+	start: z.string().optional(),
+	session: z.string().optional(),
+})
+
+type LaunchRecord = z.infer<typeof launch_schema>
+
+interface LaunchTarget {
+	// The checkout the parent runs in, and its common git directory the records are keyed on.
+	worktree: string
+	git_directory: string
+}
+
+interface Launched {
+	pid: number
+	session: string | undefined
+	log_path: string
+}
+
+type StartResult = { kind: 'launched'; launched: Launched } | { kind: 'failed'; note: string }
+
+function launch_path(git_directory: string): string {
+	return stamp_file.stamp_path(LAUNCH_PREFIX, git_directory)
+}
+
+function log_path(git_directory: string): string {
+	return stamp_file.stamp_path(LOG_PREFIX, git_directory, LOG_SUFFIX)
+}
+
+function read_launch(target: string): LaunchRecord | undefined {
+	return json_value.parse_with(stamp_file.read_stamp_text(target) ?? '', launch_schema)
+}
+
+// The launched parent is still the process it was: a pid reused by another process is not a run.
+function is_launch_live(record: LaunchRecord | undefined): boolean {
+	if (record === undefined) return false
+
+	return process_identity.is_same_process(record.pid, record.start) !== false
+}
+
+function is_carry_live(read: CarryRead): boolean {
+	return read.kind === 'carried' && run_carry.is_owner_live(read.carry)
+}
+
+function is_running(git_directory: string): boolean {
+	if (is_carry_live(run_carry.read_carry(run_carry.carry_path(git_directory)))) return true
+
+	return is_launch_live(read_launch(launch_path(git_directory)))
+}
+
+// The environment the chosen provider resolves from, whatever session this command was typed in.
+function chosen_environment(
+	provider: AgentProvider,
+	environment: AgentEnvironment = process.env,
+): AgentEnvironment {
+	return {
+		...environment,
+		...agent_session_environment.removed_environment(environment),
+		[agent_role_profile.CODEX_SESSION_KEY]: undefined,
+		[agent_role_profile.HANDED_PROVIDER_KEY]: provider,
+	}
+}
+
+// Only a Claude parent takes a forced session id, so only it can be resumed by one later.
+function session_for(provider: AgentProvider): string | undefined {
+	return provider === 'anthropic' ? randomUUID() : undefined
+}
+
+function argv_of(
+	invocation: string,
+	provider: AgentProvider,
+	worktree: string,
+	session: string | undefined,
+): AgentArgvResult {
+	const environment = chosen_environment(provider)
+	const resolved = agent_role_profile.resolve(agent_role_profile.SCHEDULER, environment)
+
+	if (resolved.kind === 'rejected') return resolved
+
+	return agent_argv.with_profile_in(invocation, resolved.profile, worktree, session)
+}
+
+function note_to_stderr(note: string): void {
+	console.error(`backlogrun: ${note}`)
+}
+
+function record_launch(git_directory: string, pid: number, session: string | undefined): void {
+	const started = process_identity.read_start(pid)
+
+	stamp_file.replace_stamp(launch_path(git_directory), { pid, start: started, session })
+}
+
+// The headless mark holds the parent's turn open while its lanes run, as `run:wake`'s does. The launch
+// strips only Claude's session keys, so a Codex session this was typed in is cleared here too — inherited,
+// it would make the parent's own `josh` commands resolve the wrong provider.
+function spawn_parent(
+	argv: Extract<AgentArgvResult, { kind: 'argv' }>,
+	provider: AgentProvider,
+	target: LaunchTarget,
+): LaunchResult {
+	const environment = {
+		...run_headless.environment(),
+		[agent_role_profile.CODEX_SESSION_KEY]: undefined,
+		[agent_role_profile.HANDED_PROVIDER_KEY]: provider,
+	}
+	const log = log_path(target.git_directory)
+
+	return detached_launch.launch(
+		{
+			argv: argv.argv,
+			cwd: target.worktree,
+			env: environment,
+			log_path: log,
+			profile: argv.profile,
+		},
+		note_to_stderr,
+	)
+}
+
+function start(invocation: string, provider: AgentProvider, target: LaunchTarget): StartResult {
+	const session = session_for(provider)
+	const built = argv_of(invocation, provider, target.worktree, session)
+
+	if (built.kind === 'rejected') return { kind: 'failed', note: built.note }
+
+	const result = spawn_parent(built, provider, target)
+
+	if (result.kind === 'failed') return result
+
+	record_launch(target.git_directory, result.pid, session)
+
+	const launched = { pid: result.pid, session, log_path: log_path(target.git_directory) }
+
+	return { kind: 'launched', launched }
+}
+
+const backlogrun_launch = {
+	argv_of,
+	chosen_environment,
+	is_running,
+	start,
+}
+
+export type { Launched, LaunchTarget, StartResult }
+export { backlogrun_launch }

package/scripts/behavior/behavior-assertion.ts

@@ -4,15 +4,13 @@ import {
 } from '#scripts/time-runtime/time-transcript-line'
 
 // Verifying an agent's behavior against the transcripts every run already writes, with no live
-// Claude session and no model call (joshuafolkken/kit#2365).
+// Claude session and no model call.
 //
-// **The mechanism that measured behavior used to be the completion gate's own, and it was removed
-// for being slow rather than for being wrong.** joshuafolkken/kit#1922 took `josh eval`'s five
-// scenarios out of the gate because each starts a real Claude session, so the step never ran without
-// `JOSH_EVAL` and paid a prompt-and-report cost every run for nothing. What it left behind is a gate
-// that proves the *machinery* works — 8,000-odd unit tests — and nothing at all that proves the
-// agent *behaves*. This is the half worth keeping, separated from the half worth removing: an
-// assertion read off a recorded transcript is deterministic, re-runnable and never calls a model.
+// **`josh eval`'s scenarios stay out of the completion gate for being slow rather than for being
+// wrong**: each starts a real Claude session. Without them the gate would prove only that the
+// *machinery* works and nothing at all that the agent *behaves*. This module is the half of eval
+// worth keeping: an assertion read off a recorded transcript is deterministic, re-runnable and never
+// calls a model.
 //
 // **The reading is single-sourced, not re-implemented.** One transcript line is parsed by
 // `time-transcript-line.ts` — the reader the span walk and the guards already use — and the files are

package/scripts/behavior/behavior-cli.ts

@@ -6,7 +6,7 @@ import { behavior_assertion, type Violation } from './behavior-assertion'
 import { behavior_rules } from './behavior-rules'
 
 // `josh behavior` — check the current run's recorded transcript against the behavior assertions and
-// report where any broke (joshuafolkken/kit#2365). It runs inside `pnpm josh gate`, calls no model,
+// report where any broke. It runs inside `pnpm josh gate`, calls no model,
 // and reads one file: the session it is running in.
 //
 // **The scope is the current run, not the whole corpus.** The store holds thousands of transcripts

package/scripts/behavior/behavior-rules.ts

@@ -3,7 +3,7 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 import type { Block, TranscriptLine } from '#scripts/time-runtime/time-transcript-line'
 import type { Assertion, Finding } from './behavior-assertion'
 
-// The behavior assertions checked against recorded transcripts (joshuafolkken/kit#2365). This is the
+// The behavior assertions checked against recorded transcripts. This is the
 // **seed set** — the issue's own plan is to land one rule that is green across the recorded corpus,
 // then add more one at a time, each verified green before it joins. Starting with many would land a
 // wall of red that says nothing about which behavior actually regressed.
@@ -14,7 +14,7 @@ const COMMAND_KEY = 'command'
 const FIRST_POSITION_OFFSET = 1
 const TOOL_RESULT = 'tool_result'
 // The openings of the two results that mean a Bash call never ran: the permission layer's refusal,
-// and a PreToolUse hook's block (joshuafolkken/kit#3197). A PostToolUse hook error is deliberately
+// and a PreToolUse hook's block. A PostToolUse hook error is deliberately
 // absent — that hook fires after the command has already run.
 const DENIED_BASH_PREFIXES = [
 	'Permission to use Bash with command ',
@@ -65,7 +65,7 @@ function command_of(block: Block): string | undefined {
 // subcommand and is not a dry run. Each `;`/`&&`/`|`-separated segment is judged on its own, so a
 // mutation anywhere in a chain is caught while a mention inside another command's argument is not.
 //
-// Quoted spans are removed before the split (joshuafolkken/kit#2841): a `|` inside a quoted pattern —
+// Quoted spans are removed before the split: a `|` inside a quoted pattern —
 // `grep -E "commit|git add" file` — is not a separator, and cutting there synthesized a segment that
 // began with `git add` out of a read-only search. `unquoted` honors escapes and heredoc bodies, so a
 // stray `it's` cannot pair with a later quote and erase the real `git add` between them.

package/scripts/build/build-claude-md.ts

@@ -11,9 +11,9 @@ const BASIC_CLAUDE_FILENAME = 'CLAUDE.basic.md'
 const SOURCE_CLAUDE_MD = path.join(REPO_ROOT, 'CLAUDE.md')
 const DIST_CLAUDE_MD = path.join(DIST_ROOT, 'CLAUDE.md')
 const SOURCE_BASIC_CLAUDE_MD = path.join(REPO_ROOT, 'templates', BASIC_CLAUDE_FILENAME)
-// A basic project's `CLAUDE.md` imports the rules from dist/. One initialized before
-// joshuafolkken/kit#2829 imports them under the profile's old name until `josh init` is re-run
-// and migrates that import, so the same rules ship under both names.
+// A basic project's `CLAUDE.md` imports the rules from dist/. An older one imports them under the
+// profile's old name until `josh init` is re-run and migrates that import, so the same rules ship
+// under both names.
 const DIST_BASIC_CLAUDE_MDS: ReadonlyArray<string> = [
 	path.join(DIST_ROOT, BASIC_CLAUDE_FILENAME),
 	path.join(DIST_ROOT, 'CLAUDE.static.md'),
@@ -21,7 +21,7 @@ const DIST_BASIC_CLAUDE_MDS: ReadonlyArray<string> = [
 
 // Read kit's own CLAUDE.md and apply the distribution path transform. kit's source keeps relative
 // paths so it resolves inside the kit repository; the published copy rewrites them so every backtick
-// reference resolves in a consumer too (joshuafolkken/kit#1878). Pure — the guard test asserts the
+// reference resolves in a consumer too. Pure — the guard test asserts the
 // result carries no reference a consumer cannot open.
 function generate_distributed_claude_md(): string {
 	return init_logic.transform_distributed_paths(readFileSync(SOURCE_CLAUDE_MD, 'utf8'))

package/scripts/build/build-codex-hooks.ts

@@ -8,10 +8,10 @@ const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..
 const CLAUDE_SETTINGS = path.join(REPO_ROOT, '.claude', 'settings.json')
 const CODEX_HOOKS = path.join(REPO_ROOT, '.codex', 'hooks.json')
 
-// Regenerate `.codex/hooks.json` from `.claude/settings.json` (joshuafolkken/kit#2997). The output is
+// Regenerate `.codex/hooks.json` from `.claude/settings.json`. The output is
 // committed rather than gitignored: Codex reads it straight from a fresh clone of kit, before any
 // build has run, and `josh init` / `josh sync` copy it to consumers from the package. It is run by
-// hand, never from `pnpm build`, so a build never rewrites a committed file (joshuafolkken/kit#3324):
+// hand, never from `pnpm build`, so a build never rewrites a committed file:
 // `codex-project-config.test.ts` fails the gate when the committed copy has drifted.
 function build_codex_hooks(): string {
 	writeFileSync(CODEX_HOOKS, codex_hooks.codex_hooks_text(readFileSync(CLAUDE_SETTINGS, 'utf8')))

package/scripts/build/build-commands.ts

@@ -12,7 +12,7 @@ const OUT_DIR = path.join(PACKAGE_DIR, BUNDLED_COMMAND_DIRECTORY)
 
 // Each `is_bundled` command is pre-built to its own `dist/commands/<script basename>.js`, so a
 // consumer's `dist/josh.js` imports it under plain node instead of spawning tsx for its `.ts`
-// (joshuafolkken/kit#3328, `docs/maintainers/runtime-bundling.md`).
+// (`docs/maintainers/runtime-bundling.md`).
 //
 // **No code splitting, and that is why the import closure is checked.** Every entry is one
 // self-contained file, so every module it imports shares the entry's `import.meta.url`; a second

package/scripts/build/build-hooks.ts

@@ -25,7 +25,7 @@ const ANY_PATH = /.*/
 
 // Each Claude Code hook is bundled to its own `dist/hooks/<name>.js`, so a consumer (and kit itself)
 // invokes `node dist/hooks/<name>.js` directly — no `pnpm` launch and no `tsx` re-spawn from the
-// `dist/josh.js` dispatcher (joshuafolkken/kit#2023).
+// `dist/josh.js` dispatcher.
 //
 // **`splitting: true` is load-bearing, not an optimization.** Every hook module decides whether to
 // run its main from `process.argv[1] === fileURLToPath(import.meta.url)`. A single-file bundle would
@@ -35,7 +35,7 @@ const ANY_PATH = /.*/
 // splitting keeps every entry in its own file with its own `import.meta.url`, so an imported guard's
 // `import.meta.url` never equals `argv[1]` and only the file actually launched runs its main.
 //
-// **The flip side: an entry another entry imports loses its main** (joshuafolkken/kit#2922). Splitting
+// **The flip side: an entry another entry imports loses its main**. Splitting
 // moves a module two entries share into a chunk, so a launched hook whose own module is imported
 // elsewhere becomes a re-export stub that runs nothing. Each launched hook is therefore a `*-cli.ts`
 // file holding only the self-invoke, which no other module imports.
@@ -136,12 +136,12 @@ function place_build(out_directory: string, files: ReadonlyArray<OutputFile>, st
 }
 
 // With `splitting: true` every build emits freshly hashed `chunk-*.js` files, so without a cleanup
-// the chunks of every earlier build pile up beside the live ones and ship in any local pack
-// (joshuafolkken/kit#2885). The cleanup runs after the new files are in place rather than emptying
+// the chunks of every earlier build pile up beside the live ones and ship in any local pack.
+// The cleanup runs after the new files are in place rather than emptying
 // the directory first: this checkout's own settings.json launches `node dist/hooks/<name>.js` on
 // every tool call, and an emptied directory would make a hook launched mid-build fail to load and its
 // guard fail open. The source digest is placed last (`hook-bundle-stamp.ts`), so a launch only reads
-// the bundles as fresh once every one of them is in place (joshuafolkken/kit#2984).
+// the bundles as fresh once every one of them is in place.
 async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
 	const sources = new Map<string, Uint8Array>()
 	const { outputFiles: files } = await build({

package/scripts/build/build.ts

@@ -34,7 +34,7 @@ async function claude_md_step(): Promise<string> {
 	return build_claude_md()
 }
 
-// Every step `pnpm build` runs (joshuafolkken/kit#3324). The steps write disjoint paths under
+// Every step `pnpm build` runs. The steps write disjoint paths under
 // `dist/`, so they run concurrently from this one entry instead of eight serial `tsx` launches.
 // Nothing here writes a git-tracked file: `.codex/hooks.json` is regenerated by hand with
 // `tsx scripts/build/build-codex-hooks.ts`, and `codex-project-config.test.ts` fails the gate when