@joshuafolkken/kit 1.1035.0 → 1.1050.0

package/scripts/hooks/pretool-guard.ts

@@ -1,10 +1,8 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
-import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
+import type { GuardOutcome } from '#scripts/josh/hook-decision'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
 import { batch_outcome } from './batch-guard'
 
@@ -71,26 +69,27 @@ function pretool_outcome(raw_payload: string): GuardOutcome {
 // as `combine_outcomes` orders them, and the watcher's refusal fills a clear verdict rather than
 // overriding one. It fires once per run itself (`run-watcher-hook.ts`), so a stale watcher refuses the
 // first call but not the `pnpm josh run:progress --wait` that fixes it.
+//
+// **The parent hand-off guard is the second asynchronous rule, asked after the watcher's**
+// (joshuafolkken/kit#2947). It reads the carry record to tell the `backlogrun` parent apart, so it sits
+// beside the watcher rather than among the synchronous rows; a stale watcher is the cheaper fix and is
+// surfaced first.
+async function async_reason(raw_payload: string): Promise<string | undefined> {
+	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
+
+	return watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+}
+
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {
 	const base = pretool_outcome(raw_payload)
 
 	if (!is_clear(base)) return base
 
-	const reason = await run_watcher_hook.watcher_hook_reason(raw_payload)
+	const reason = await async_reason(raw_payload)
 
 	return reason === undefined ? base : { reason, notice: undefined, fault: undefined }
 }
 
 const pretool_guard = { combine_outcomes, pretool_outcome, pretool_outcome_async }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
-	else {
-		const raw_payload = await text(process.stdin)
-
-		hook_decision.load_environment_file()
-		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
-	}
-}
-
 export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/init/start-exec.ts

@@ -23,6 +23,12 @@ function run(command: string, args: ReadonlyArray<string>, root: string): void {
 	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
 }
 
-const start_exec = { succeeds, read_output, run }
+// A caller's own initialize command stands in for the in-process `josh init`, so it keeps the
+// environment that setup would have had — its install goes through a scanner's proxy as usual.
+function run_local(command: string, args: ReadonlyArray<string>, root: string): void {
+	execaSync(command, args, { cwd: root, stdio: 'inherit' })
+}
+
+const start_exec = { succeeds, read_output, run, run_local }
 
 export { start_exec }

package/scripts/init/start-plan.ts

@@ -8,6 +8,7 @@ interface StartOptions {
 	is_yes: boolean
 	is_github: boolean
 	visibility: Visibility
+	init_command: string | undefined
 }
 
 type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels' | 'setup_pr'
@@ -137,20 +138,31 @@ function github_consent(
 	}
 }
 
+// A run whose initialize step was handed to a caller's command names that command wherever the step
+// is printed, so the plan, the progress and a failure all say what actually runs (#2872).
+function step_labels(init_command: string | undefined): Readonly<Record<StartStep, string>> {
+	if (init_command === undefined) return STEP_LABELS
+
+	return { ...STEP_LABELS, initialize: `Initialize with ${init_command}` }
+}
+
 // What a failed run prints, so the user can tell how far it got before deciding how to resume.
 function progress_report(
 	failed: StartStep,
 	completed: ReadonlyArray<StartStep>,
 	cause: string,
+	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
 ): string {
-	const done =
-		completed.length === 0 ? 'nothing' : completed.map((step) => STEP_LABELS[step]).join('; ')
+	const done = completed.length === 0 ? 'nothing' : completed.map((step) => labels[step]).join('; ')
 
-	return `josh start stopped at: ${STEP_LABELS[failed]}\nCompleted: ${done}\nCause: ${cause}`
+	return `josh start stopped at: ${labels[failed]}\nCompleted: ${done}\nCause: ${cause}`
 }
 
-function plan_summary(steps: ReadonlyArray<StartStep>): string {
-	const lines = steps.map((step, index) => `  ${String(index + 1)}. ${STEP_LABELS[step]}`)
+function plan_summary(
+	steps: ReadonlyArray<StartStep>,
+	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
+): string {
+	const lines = steps.map((step, index) => `  ${String(index + 1)}. ${labels[step]}`)
 
 	return ['josh start will:', ...lines].join('\n')
 }
@@ -161,6 +173,7 @@ const start_plan = {
 	github_consent,
 	progress_report,
 	plan_summary,
+	step_labels,
 	STEP_LABELS,
 }
 export { start_plan }

package/scripts/init/start-setup-pr.ts

@@ -12,15 +12,22 @@ import { start_exec } from './start-exec'
 const SETUP_TITLE = `Set up ${KIT_PACKAGE_NAME}`
 const SETUP_BODY = [
 	`Adds the files \`josh start\` wrote while setting up ${KIT_PACKAGE_NAME}, so main carries the`,
-	'rules, settings and workflows every later Issue is run with. Only the files kit wrote are in the',
-	'pull request; anything else in the working tree is left as it was.',
+	'rules, settings and workflows every later Issue is run with. Only the files the setup wrote are in',
+	'the pull request; anything else in the working tree is left as it was.',
 ].join('\n')
+const NAME_ONLY = '--name-only'
 const NOTHING_TO_COMMIT = 'The kit setup has no changes to commit, so no pull request was opened.'
 const OPEN_SETUP_ISSUES_QUERY = `?state=open&labels=${IGNORE_FOR_RELEASE_LABEL}&per_page=100`
 const FIRST_SETUP_ISSUE_FILTER = `[.[] | select(.title == "${SETUP_TITLE}") | .number][0] // empty`
 
-function lines_of(output: string | undefined): Array<string> {
-	return (output ?? '').split('\n').filter((line) => line.length > 0)
+// Listings are read NUL-separated (`-z`), so a path is never quoted — a name a caller's initialize
+// command wrote need not be ASCII the way kit's own are (#2872).
+function paths_of(output: string | undefined): Array<string> {
+	return (output ?? '').split('\0').filter((listed) => listed.length > 0)
+}
+
+function listing(args: ReadonlyArray<string>, root: string): Array<string> {
+	return paths_of(start_exec.read_output('git', [...args, '-z'], root))
 }
 
 function setup_issue(issue_number: string): IssueInfo {
@@ -42,17 +49,18 @@ function is_setup_branch(branch: string | undefined): boolean {
 }
 
 // Untracked files the ignore rules let through, plus tracked files the setup changed — two plain
-// listings, so nothing has to be parsed out of `git status`. Every kit path is ASCII, so git's
-// quoting of other names never hides one.
+// listings, so nothing has to be parsed out of `git status`.
 function changed_paths(root: string): Array<string> {
-	const untracked = start_exec.read_output(
-		'git',
-		['ls-files', '--others', '--exclude-standard'],
-		root,
-	)
-	const modified = start_exec.read_output('git', ['diff', '--name-only', 'HEAD'], root)
-
-	return [...lines_of(untracked), ...lines_of(modified)]
+	const untracked = listing(['ls-files', '--others', '--exclude-standard'], root)
+	const modified = listing(['diff', NAME_ONLY, 'HEAD'], root)
+
+	return [...untracked, ...modified]
+}
+
+// On the setup branch a failed commit left, that run's `git add` already staged its files, so they
+// read as changed before this run's command ran — the staged ones count as setup output (#2872).
+function carried_paths(root: string, current: string | undefined): Array<string> {
+	return is_setup_branch(current) ? listing(['diff', NAME_ONLY, '--cached'], root) : []
 }
 
 // The Issue carries the release classification the pull request is opened with, so the PR step finds
@@ -113,10 +121,30 @@ function commit_kit_paths(paths: ReadonlyArray<string>, issue: IssueInfo, root:
 	start_exec.run('git', ['commit', '--message', issue.commit_message, '--', ...paths], root)
 }
 
-// Issue → branch → only kit's files committed → push → pull request. The merge is left to a person:
-// it is the one step that changes main.
-async function open(root: string): Promise<void> {
-	const paths = kit_written_paths.select(changed_paths(root))
+// A caller's initialize command writes files kit cannot name, so with a `baseline` — what was already
+// changed before that command ran — everything changed since joins kit's own files, while a change
+// the user had made before the run still stays out (#2872).
+function setup_paths(
+	root: string,
+	baseline: ReadonlyArray<string> | undefined,
+	current: string | undefined,
+): Array<string> {
+	const changed = changed_paths(root)
+	const kit_paths = kit_written_paths.select(changed)
+
+	if (baseline === undefined) return kit_paths
+
+	const carried = carried_paths(root, current)
+	const written = changed.filter((path) => !baseline.includes(path) || carried.includes(path))
+
+	return [...new Set([...kit_paths, ...written])]
+}
+
+// Issue → branch → only the setup's files committed → push → pull request. The merge is left to a
+// person: it is the one step that changes main.
+async function open(root: string, baseline?: ReadonlyArray<string>): Promise<void> {
+	const current = start_exec.read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
+	const paths = setup_paths(root, baseline, current)
 
 	if (paths.length === 0) {
 		console.info(NOTHING_TO_COMMIT)
@@ -124,7 +152,6 @@ async function open(root: string): Promise<void> {
 		return
 	}
 
-	const current = start_exec.read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
 	const issue = resolve_issue(current)
 
 	switch_to(issue.branch_name, current, root)

package/scripts/init/start-steps.ts

@@ -2,6 +2,7 @@ import path from 'node:path'
 import { error_text } from '#scripts/lib/error-message'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
+import { parseCommandString } from 'execa'
 import { main as init_main } from './init'
 import { PACKAGE_DIR } from './init-paths'
 import { kit_setup_state } from './kit-setup-state'
@@ -14,6 +15,11 @@ interface StepContext {
 	root: string
 	profile: ProjectProfile
 	visibility: Visibility
+	init_command: string | undefined
+}
+
+interface RunContext extends StepContext {
+	baseline: ReadonlyArray<string> | undefined
 }
 
 const DEFAULT_BRANCH = 'main'
@@ -22,7 +28,7 @@ const GH_INSTALL_HINT =
 const GH_AUTH_HINT =
 	'GitHub CLI is not signed in. Run gh auth login, then run josh start again. Nothing was changed.'
 
-const { succeeds, read_output, run } = start_exec
+const { succeeds, read_output, run, run_local } = start_exec
 
 function read_git_state(root: string, shape: ProjectShape): GitState {
 	const { has_git, has_github } = shape
@@ -67,8 +73,19 @@ function create_git_repository(context: StepContext): void {
 }
 
 // The same setup `josh init` runs, called rather than copied, with the profile the user confirmed.
+// A toolkit that layers its files over kit's (`josh-app init`) names its own setup instead, so every
+// other step and guard stays here rather than in a copy of this command (#2872). That command runs
+// without a shell, is given the same profile, and a non-zero exit stops the run before the commit.
 function initialize(context: StepContext): void {
-	init_main(['--profile', context.profile])
+	if (context.init_command === undefined) {
+		init_main(['--profile', context.profile])
+
+		return
+	}
+
+	const [command = '', ...args] = parseCommandString(context.init_command)
+
+	run_local(command, [...args, '--profile', context.profile], context.root)
 }
 
 function commit_all(context: StepContext): void {
@@ -97,11 +114,22 @@ function add_missing_labels(): void {
 
 // Main already has a history here, so the setup reaches it the way every other change does: through
 // an Issue and a pull request a person merges (joshuafolkken/kit#2816).
-async function open_setup_pull_request(context: StepContext): Promise<void> {
-	await start_setup_pr.open(context.root)
+async function open_setup_pull_request(context: RunContext): Promise<void> {
+	await start_setup_pr.open(context.root, context.baseline)
 }
 
-type StepAction = (context: StepContext) => void | Promise<void>
+// What was already changed before a caller's initialize command ran, read only when the setup pull
+// request will need to tell that command's files from the user's own (#2872).
+function baseline_of(
+	steps: ReadonlyArray<StartStep>,
+	context: StepContext,
+): ReadonlyArray<string> | undefined {
+	if (context.init_command === undefined || !steps.includes('setup_pr')) return undefined
+
+	return start_setup_pr.changed_paths(context.root)
+}
+
+type StepAction = (context: RunContext) => void | Promise<void>
 
 const STEP_ACTIONS: Readonly<Record<StartStep, StepAction>> = {
 	git_init: create_git_repository,
@@ -114,24 +142,28 @@ const STEP_ACTIONS: Readonly<Record<StartStep, StepAction>> = {
 
 async function run_step(
 	step: StartStep,
-	context: StepContext,
+	context: RunContext,
 	completed: ReadonlyArray<StartStep>,
 ): Promise<void> {
 	try {
 		await STEP_ACTIONS[step](context)
 	} catch (error) {
 		const cause = error_text.message_of(error)
+		const labels = start_plan.step_labels(context.init_command)
 
-		throw new Error(start_plan.progress_report(step, completed, cause), { cause: error })
+		throw new Error(start_plan.progress_report(step, completed, cause, labels), { cause: error })
 	}
 }
 
 async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext): Promise<void> {
+	const labels = start_plan.step_labels(context.init_command)
+	const run_context: RunContext = { ...context, baseline: baseline_of(steps, context) }
+
 	for (const [index, step] of steps.entries()) {
 		const position = `${String(index + 1)}/${String(steps.length)}`
 
-		console.info(`\n[${position}] ${start_plan.STEP_LABELS[step]}`)
-		await run_step(step, context, steps.slice(0, index))
+		console.info(`\n[${position}] ${labels[step]}`)
+		await run_step(step, run_context, steps.slice(0, index))
 	}
 }
 

package/scripts/init/start.ts

@@ -14,7 +14,9 @@ import { start_steps } from './start-steps'
 
 const ARGUMENT_START_INDEX = 2
 const READY_MESSAGE = 'GitHub workflow ready. Use kickoff new in your assistant to plan an Issue.'
-const START_USAGE = 'josh start [--profile basic|full] [--yes] [--github] [--public]'
+const START_USAGE =
+	'josh start [--profile basic|full] [--yes] [--github] [--public] [--init-command <command>]'
+const INIT_COMMAND_FLAG = '--init-command'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
@@ -26,16 +28,42 @@ interface Prepared {
 	choices: Choices
 }
 
-// The switches are peeled off first, so what remains is exactly the `--profile` pair `josh init`
-// accepts — one parser for the profile in both commands.
+interface InitCommandSplit {
+	init_command: string | undefined
+	rest: ReadonlyArray<string>
+}
+
+// A value that is blank or another flag means the command itself was left out, which would otherwise
+// swallow the next switch or hand the initialize step nothing to run.
+function is_command_value(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== '' && !value.startsWith('-')
+}
+
+// The command arrives as the one argument after its flag and is removed together with it.
+function split_init_command(args: ReadonlyArray<string>): InitCommandSplit {
+	const index = args.indexOf(INIT_COMMAND_FLAG)
+
+	if (index === -1) return { init_command: undefined, rest: args }
+
+	const value = args[index + 1]
+
+	if (!is_command_value(value)) throw new Error(`Usage: ${START_USAGE}`)
+
+	return { init_command: value, rest: args.filter((_, at) => at !== index && at !== index + 1) }
+}
+
+// The switches and the initialize command are peeled off first, so what remains is exactly the
+// `--profile` pair `josh init` accepts — one parser for the profile in both commands.
 function parse_start_options(args: ReadonlyArray<string>): StartOptions {
-	const profile_args = args.filter((argument) => !SWITCHES.has(argument))
+	const { init_command, rest } = split_init_command(args)
+	const profile_args = rest.filter((argument) => !SWITCHES.has(argument))
 
 	return {
 		profile: project_profile.requested_profile(profile_args, START_USAGE),
-		is_yes: args.includes(YES_FLAG),
-		is_github: args.includes(GITHUB_FLAG),
-		visibility: args.includes(PUBLIC_FLAG) ? 'public' : 'private',
+		is_yes: rest.includes(YES_FLAG),
+		is_github: rest.includes(GITHUB_FLAG),
+		visibility: rest.includes(PUBLIC_FLAG) ? 'public' : 'private',
+		init_command,
 	}
 }
 
@@ -83,11 +111,13 @@ function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Pr
 async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
 	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
 
-	console.info(start_plan.plan_summary(steps))
-	const profile = await resolve_profile(choices, interaction)
 	const { root, options } = choices
+	const { visibility, init_command } = options
+
+	console.info(start_plan.plan_summary(steps, start_plan.step_labels(init_command)))
+	const profile = await resolve_profile(choices, interaction)
 
-	await start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
+	await start_steps.run_steps(steps, { root, profile, visibility, init_command })
 	console.info(`\n${READY_MESSAGE}`)
 }
 

package/scripts/issue/issue-cite.ts

@@ -40,6 +40,23 @@ function citation_line(slug: string, number: string, summary: string): string {
 	return `[#${number}](${issue_url(slug, number)})${SUMMARY_SEPARATOR}${summary}`
 }
 
+// How a listing names one issue, given what it already holds (joshuafolkken/kit#2943). A progress
+// command's output is copied into a report verbatim, so the line it prints is the citation the report
+// carries: the full form when the title is in hand, the bare number-link when only the repository is,
+// and the plain `#N` only when the repository could not be read at all.
+type IssueCiter = (number: string) => string
+
+function citer(slug: string | undefined, titles: ReadonlyMap<string, string>): IssueCiter {
+	return function cite(number: string): string {
+		if (slug === undefined) return `#${number}`
+		const title = titles.get(number)
+
+		return title === undefined
+			? `[#${number}](${issue_url(slug, number)})`
+			: citation_line(slug, number, title)
+	}
+}
+
 function qualified_target(token: string): CiteTarget | undefined {
 	const match = REPO_QUALIFIED.exec(token)
 	if (match === null) return undefined
@@ -90,6 +107,7 @@ function no_repo_line(target: CiteTarget): string {
 const issue_cite = {
 	SUMMARY_SEPARATOR,
 	citation_line,
+	citer,
 	issue_url,
 	label,
 	missing_line,
@@ -98,5 +116,5 @@ const issue_cite = {
 	unreadable_line,
 }
 
-export type { CiteTarget }
+export type { CiteTarget, IssueCiter }
 export { issue_cite }

package/scripts/josh/josh-command-map.ts

@@ -38,8 +38,6 @@ const ALIASES: Record<string, string> = {
 	ln: 'lines',
 	by: 'bytes',
 	f: 'format',
-	fd: 'format:edited',
-	bg: 'batch:guard',
 	sd: 'cspell:dot',
 	bh: 'behavior',
 	t: 'test',
@@ -48,8 +46,6 @@ const ALIASES: Record<string, string> = {
 	td: 'test:declared',
 	trd: 'test:red',
 	te: 'test:e2e',
-	er: 'e2e:retry-check',
-	sl: 'session:lang',
 	c: 'check',
 	pt: 'port',
 	i: 'init',
@@ -57,19 +53,12 @@ const ALIASES: Record<string, string> = {
 	st: 'start',
 	sy: 'sync',
 	rmi: 'registry:migrate',
-	sys: 'sync:scope',
 	g: 'git',
 	gp: 'pr',
-	prc: 'pr:classification',
-	fu: 'followup',
-	nf: 'notify',
-	obf: 'observations:flush',
-	mrr: 'measure:rerun',
 	ms: 'main:sync',
 	mm: 'main:merge',
 	bp: 'bump',
 	re: 'release',
-	res: 'release:scope',
 	v: 'version',
 	r: 'ranges',
 	dr: 'doctor',
@@ -77,107 +66,16 @@ const ALIASES: Record<string, string> = {
 	ad: 'adopt',
 	ov: 'overrides',
 	a: 'audit',
-	ap: 'audit:provision',
 	rt: 'reconcile-templates',
 	u: 'latest',
-	lg: 'latest:guard',
 	lc: 'latest:corepack',
 	lu: 'latest:update',
-	ls: 'latest:scope',
-	pm: 'prevent-main-commit',
-	cm: 'check-commit-message',
-	ss: 'secretlint-scan',
-	ppu: 'pre-push-unit',
-	rer: 'reserved-run',
-	ptc: 'pre-commit-type-check',
-	ird: 'issue:read',
-	ist: 'issue:state',
-	isc: 'issue:scout',
-	ifl: 'issue:file',
-	isf: 'issue:fold',
-	isfe: 'issue:fold-existing',
-	dfr: 'defect:rate',
-	ici: 'issue:cite',
-	icm: 'issue:comment',
-	pks: 'pkg:scout',
-	iln: 'issue:lint',
-	ibl: 'issue:backlinks',
-	rl: 'report:lint',
-	ep: 'epic',
-	ec: 'epic:check',
-	en: 'epic:next',
-	ea: 'epic:audit',
-	eb: 'epic:bundle',
-	ao: 'auto-ok:next',
-	bl: 'backlog:next',
-	blo: 'backlog:offer',
-	bld: 'backlog:drive',
-	blp: 'backlog:plan',
-	bls: 'backlog:stalled',
-	bb: 'backlog:budget',
-	co: 'cost',
-	ds: 'doc:section',
-	rs: 'read:set',
-	dcr: 'doc:read',
-	rf: 'read:files',
-	ef: 'edit:files',
-	rfs: 'refactor:scan',
 	tm: 'time',
 	tmd: 'time:density',
 	rtr: 'retrospective',
-	rb: 'review:brief',
-	r2: 'review:round2',
-	ra: 'review:attest',
-	rvr: 'review:record',
 	rvf: 'review:findings',
-	dp: 'disposition',
-	dg: 'delegate',
-	fo: 'fanout',
-	rh: 'run:hold',
-	rr: 'run:release',
-	rc: 'run:carry',
-	rtd: 'run:tidy',
-	rw: 'run:wake',
-	rct: 'run:cut',
-	rv: 'run:liveness',
-	red: 'run:ending',
-	rg: 'run:progress',
-	rp: 'run:prep',
-	ren: 'run:entry',
-	rtl: 'run:tail',
-	shp: 'ship',
-	rst: 'run:status',
-	rn: 'run:next',
-	rsp: 'run:step',
-	rpy: 'repo:party',
-	rmg: 'run:merge',
-	rrp: 'run:report',
-	rrv: 'run:review',
-	rev: 'run:event',
-	sp: 'stash:pop',
-	lno: 'lane:open',
-	lnc: 'lane:close',
-	lnl: 'lane:list',
-	lnp: 'lane:prune',
-	lnv: 'lane:output',
-	lnd: 'lane:dispatch',
-	lna: 'lane:await',
-	lnla: 'lane:launch',
-	rwg: 'run:watcher:guard',
-	rsd: 'run:stranded',
-	ig: 'investigation:guard',
-	drg: 'duplicate-read:guard',
-	rug: 'rule:guard',
 	ruv: 'rule:value',
-	ptg: 'pretool:guard',
-	sg: 'stop:guard',
 	ev: 'eval',
-	ol: 'oracle:list',
-	sa: 'split:assess',
-	shs: 'sonar:hotspots',
-	uir: 'ui:routes',
-	cs: 'clone:scan',
-	ca: 'cases',
 }
 
 // The canonical name of a `josh` subcommand: an alias expands, and anything else passes through

package/scripts/josh/josh-commands-development.ts

@@ -66,7 +66,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['files', 'processes']],
 	},
 	'format:edited': {
-		script: 'scripts/hooks/format-edited-file.ts',
+		script: 'scripts/hooks/format-edited-cli.ts',
 		description: 'Claude Code hook: format the file just edited (reads the tool call on stdin)',
 		category: 'Development',
 		reference: ['', 'automation', ['files', 'processes']],
@@ -85,7 +85,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		// node's own `--env-file` parser with node's own precedence.
 	},
 	'pretool:guard': {
-		script: 'scripts/hooks/pretool-guard.ts',
+		script: 'scripts/hooks/pretool-guard-cli.ts',
 		description:
 			'Claude Code hook: the batch, investigation and rule guards in one process (reads the tool call on stdin)',
 		category: 'Development',

package/scripts/josh/josh-commands-project.ts

@@ -17,7 +17,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public]`,
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>]`,
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],

package/scripts/lane/lane-child-marker.ts

@@ -19,6 +19,15 @@ import { lane_paths } from './lane-paths'
 // `.claude/skills/workflow-commands/pre-gate-cut.md`.
 const KEY = 'JOSH_LANE_CHILD'
 
+// **A dispatched child also asks for the five-minute prompt-cache TTL** (joshuafolkken/kit#2944). A
+// headless `claude -p` session on a subscription defaults to the one-hour TTL, whose writes bill at 2x
+// the input rate against 1.25x for five minutes. A replay of 1,953 lane transcripts (about 57,000
+// requests) found 0.3% of request gaps over five minutes, so the shorter TTL — re-writing the prefix on
+// those few gaps — still costs 12-13% less. Every launcher of a child composes its environment here,
+// so this is the one place the choice is made.
+const CACHE_TTL_KEY = 'CLAUDE_CODE_PROMPT_CACHE_TTL'
+const CACHE_TTL = '5m'
+
 type MarkerSource = Readonly<Record<string, string | undefined>>
 
 // The environment fragment that marks a child dispatched for `#<issue>`. Composed from a digits-only
@@ -27,7 +36,7 @@ type MarkerSource = Readonly<Record<string, string | undefined>>
 function environment_for(issue: string): Record<string, string> {
 	run_issue_number.require_issue_number(issue)
 
-	return { [KEY]: issue }
+	return { [KEY]: issue, [CACHE_TTL_KEY]: CACHE_TTL }
 }
 
 // The issue a child was dispatched for, or `undefined` when the mark is absent or malformed. A blank
@@ -52,7 +61,12 @@ function is_child_of(directory: string, source: MarkerSource = process.env): boo
 	return marked !== undefined && marked === lane_paths.lane_issue_of(directory, { ...source })
 }
 
-const lane_child_marker = { KEY, env_for: environment_for, is_child_of, marked_issue }
+const lane_child_marker = {
+	KEY,
+	env_for: environment_for,
+	is_child_of,
+	marked_issue,
+}
 
 export type { MarkerSource }
 export { lane_child_marker }