@joshuafolkken/kit 1.957.0 → 1.978.0

package/scripts/git/git-staging.ts

@@ -2,6 +2,7 @@ import {
 	observation_ledger,
 	OBSERVATION_LEDGER_PATHS,
 } from '#scripts/observations/observation-ledger'
+import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { git_command } from './git-command'
 import { git_prompt } from './git-prompt'
 import { git_status } from './git-status'
@@ -67,18 +68,26 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 	for (const file of files) console.info(`   + ${file}`)
 }
 
-// **The observation ledger is never staged by an ordinary commit** (joshuafolkken/kit#1756). A
-// parent session appends to it in the primary checkout and nothing there commits it, so the next
-// `pnpm josh git` run in that checkout swept the line into a pull request about something else
-// entirely — a diff a reviewer has no reason to question. Excluding it here covers every entry
-// point, because this is the one staging step all of them go through;
-// `pnpm josh observations:flush` is what commits it, on a branch of its own.
-// Both of its paths are excluded (joshuafolkken/kit#2724): a run on the old code still appends at
-// the old one until `observation-ledger-migrate.ts` moves it.
-const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = OBSERVATION_LEDGER_PATHS
-
-function is_stageable(file_path: string): boolean {
-	return !observation_ledger.is_ledger_path(file_path)
+// **The observation ledger rides the run's own commit** (joshuafolkken/kit#2763). It used to be
+// excluded here (joshuafolkken/kit#1756) and committed afterwards by `pnpm josh observations:flush` as
+// a pull request of its own — a second branch, CI wait and merge behind every run that appended a
+// line, 144 of them in one month. Staged with the run instead, the lines are reviewed and merged with
+// the pull request whose run recorded them, while CI for that pull request is the only wait.
+//
+// **A line that breaks the grammar keeps the old exclusion** (joshuafolkken/kit#2123): the commit
+// goes ahead without the ledger, and `pnpm josh observations:flush` — which refuses the same line and
+// names it — is where it is repaired. The migration is run first, as the flush runs it, so a line
+// still on the old path (joshuafolkken/kit#2724) is committed at the new one. A lane has no ledger
+// line of its own to carry: its writers append to the primary checkout's.
+async function ledger_exclusions(): Promise<ReadonlyArray<string>> {
+	const broken = await observation_ledger_prepare.prepare(await git_command.repository_root())
+
+	return broken.length > 0 ? OBSERVATION_LEDGER_PATHS : []
+}
+
+// A migration claim is a copy mid-move, never the ledger itself, so it is never staged.
+function is_stageable(file_path: string, excluded: ReadonlyArray<string>): boolean {
+	return !observation_ledger.is_migration_claim(file_path) && !excluded.includes(file_path)
 }
 
 // **Said out loud, because the alternative is an unexplained failure.** With the ledger the only
@@ -89,27 +98,31 @@ function is_stageable(file_path: string): boolean {
 // **The paths are parsed rather than matched as substrings**: `docs/maintainers/observations.md.bak` contains the
 // ledger's path, and a hint naming a file the exclusion never touched is a hint that teaches the
 // reader to ignore it.
-function report_excluded_paths(status_output: string): void {
-	const excluded = status_output
+function report_excluded_paths(status_output: string, excluded: ReadonlyArray<string>): void {
+	const left_out = status_output
 		.split('\n')
 		.filter((line) => line.trim().length > 0)
 		.map((line) => observation_ledger.status_path(line))
-		.filter((file_path) => !is_stageable(file_path))
+		.filter((file_path) => excluded.includes(file_path))
 
-	for (const file_path of excluded) {
-		console.info(`💡 ${file_path} is not staged; commit it with \`pnpm josh observations:flush\`.`)
+	for (const file_path of left_out) {
+		console.info(
+			`💡 ${file_path} is not staged: a ledger line breaks the grammar; \`pnpm josh observations:flush\` names it.`,
+		)
 	}
 }
 
+// The status is read after the migration, so an old-path ledger it moved is not staged by its old name.
 async function stage_tracked_files(): Promise<void> {
+	const excluded = await ledger_exclusions()
 	const status_output = await git_command.status()
 	const untracked = git_status
 		.list_untracked_files(status_output)
-		.filter((file_path) => is_stageable(file_path))
+		.filter((file_path) => is_stageable(file_path, excluded))
 
-	await git_command.add_tracked(PATHS_EXCLUDED_FROM_STAGING)
+	await git_command.add_tracked(excluded)
 	console.info('💡 Auto-staged tracked modified files (git add -u).')
-	report_excluded_paths(status_output)
+	report_excluded_paths(status_output, excluded)
 	await stage_untracked_files(untracked)
 }
 

package/scripts/git/issue-labels.ts

@@ -10,6 +10,15 @@ const IN_PROGRESS_LABEL = 'in-progress'
 // it: a parked child is why a run reports "nothing left that time will fix" rather than waiting
 // forever (joshuafolkken/kit#860).
 const NEEDS_DECISION_LABEL = 'needs-decision'
+// Marks an issue whose defect reaches the verification path, so it runs with nothing beside it
+// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `wip-cap.md`;
+// `backlog:next` enforces it (`backlog-solo.ts`), so the rule no longer rests on a judgement at
+// dispatch time.
+const RUN_SOLO_LABEL = 'run:solo'
+// The other half of the same judgement: an issue a run read and found safe to run beside others
+// (joshuafolkken/kit#2779). Without it an issue lacking `run:solo` could mean "judged parallel" or
+// "never judged", and `backlog:next` withholds the second (`epic-triage.ts`).
+const RUN_LANE_LABEL = 'run:lane'
 // Opts one issue outside any epic into unattended execution (joshuafolkken/kit#906). **Only a
 // person applies it.** `epicrun #<E>` approves the merges inside `#<E>`; this label is the only way
 // a person extends that approval past the epic's edge, so a label an AI could apply to itself would
@@ -177,24 +186,71 @@ const DEPTH_LABELS: ReadonlyArray<{
 	},
 ]
 
-// What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
-// applies with its intended color (joshuafolkken/kit#2197). The `epic` and `in-progress` metadata is
-// the one the workflow documents create them with; the labels only a person applies are left out.
-const WORKFLOW_LABELS: ReadonlyArray<{
+interface LabelDefinition {
 	name: string
 	color: string
 	description: string
-}> = [
+}
+
+// What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
+// applies with its intended color (joshuafolkken/kit#2197). The `epic` and `in-progress` metadata is
+// the one the workflow documents create them with; the labels only a person applies are left out.
+const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 	{
 		name: EPIC_LABEL,
 		color: '5319e7',
 		description: 'Tracks a batch of child issues from one split',
 	},
 	{ name: IN_PROGRESS_LABEL, color: '0075ca', description: 'Work is actively in progress' },
+	{
+		name: RUN_SOLO_LABEL,
+		color: 'b60205',
+		description: 'Runs alone in a backlogrun: nothing starts beside it',
+	},
+	{
+		name: RUN_LANE_LABEL,
+		color: '0e8a16',
+		description: 'Judged safe to run beside others in a backlogrun',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
 
+// The pull request release classifications `pr-classification.yml` requires exactly one of
+// (joshuafolkken/kit#2797). The check is distributed by `josh sync`, so the labels it asks for are
+// provisioned from this same list — a repository that never had them would otherwise fail the check
+// on every pull request that is not an `enhancement`.
+const BUGFIX_LABEL = 'bugfix'
+const OTHER_CHANGE_LABEL = 'other-change'
+const IGNORE_FOR_RELEASE_LABEL = 'ignore-for-release'
+const RELEASE_CLASSIFICATION_NAMES = [
+	BREAKING_CHANGE_LABEL,
+	ENHANCEMENT_LABEL,
+	BUGFIX_LABEL,
+	OTHER_CHANGE_LABEL,
+	IGNORE_FOR_RELEASE_LABEL,
+] as const
+type ReleaseClassification = (typeof RELEASE_CLASSIFICATION_NAMES)[number]
+
+const RELEASE_CLASSIFICATION_METADATA: Readonly<
+	Record<ReleaseClassification, Omit<LabelDefinition, 'name'>>
+> = {
+	[BREAKING_CHANGE_LABEL]: { color: 'd93f0b', description: 'Release: a breaking change (major)' },
+	[ENHANCEMENT_LABEL]: { color: '84b6eb', description: 'Release: a new feature (minor)' },
+	[BUGFIX_LABEL]: { color: 'd73a4a', description: 'Release: a bug fix (patch)' },
+	[OTHER_CHANGE_LABEL]: { color: 'c2e0c6', description: 'Release: any other change (patch)' },
+	[IGNORE_FOR_RELEASE_LABEL]: { color: 'cfd3d7', description: 'Release: left out of the notes' },
+}
+
+const RELEASE_CLASSIFICATION_LABELS: ReadonlyArray<LabelDefinition> =
+	RELEASE_CLASSIFICATION_NAMES.map((name) => ({ name, ...RELEASE_CLASSIFICATION_METADATA[name] }))
+
+// Every label kit provisions on a repository — `josh start` on a new one, `josh sync` on every run.
+const REPOSITORY_LABELS: ReadonlyArray<LabelDefinition> = [
+	...WORKFLOW_LABELS,
+	...RELEASE_CLASSIFICATION_LABELS,
+]
+
 // The shape `gh issue list --json labels` returns; narrowed here so the predicate below takes any
 // listing row without importing a schema.
 interface LabelReference {
@@ -269,18 +325,25 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
+	RUN_LANE_LABEL,
+	RUN_SOLO_LABEL,
 	SPLIT_ROUTE_LABEL,
 	TIER_A_ROUTE_LABEL,
 	DEPTH_0_LABEL,
 	DEPTH_1_LABEL,
 	DEPTH_2_LABEL,
+	BUGFIX_LABEL,
+	OTHER_CHANGE_LABEL,
+	IGNORE_FOR_RELEASE_LABEL,
 ])
 
+export type { LabelDefinition, ReleaseClassification }
 export {
 	ALL_LABELS,
 	ALREADY_DONE_LABEL,
 	AUTO_OK_LABEL,
 	BUG_LABEL,
+	BUGFIX_LABEL,
 	BREAKING_CHANGE_LABEL,
 	depth_label_of,
 	DEPTH_0_LABEL,
@@ -293,14 +356,21 @@ export {
 	FILING_ROUTE_LABELS,
 	has_any_label,
 	has_label_name,
+	IGNORE_FOR_RELEASE_LABEL,
 	IN_PROGRESS_LABEL,
 	INTERRUPT_ROUTE_LABEL,
 	label_name_of,
 	NEEDS_DECISION_LABEL,
 	NEEDS_HUMAN_REVIEW_LABEL,
 	NOT_DIRECTLY_RUNNABLE_LABELS,
+	OTHER_CHANGE_LABEL,
+	RELEASE_CLASSIFICATION_LABELS,
+	RELEASE_CLASSIFICATION_NAMES,
+	REPOSITORY_LABELS,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
+	RUN_LANE_LABEL,
+	RUN_SOLO_LABEL,
 	SPLIT_ROUTE_LABEL,
 	TIER_A_ROUTE_LABEL,
 	WORKFLOW_LABELS,

package/scripts/hooks/stop-guard.ts

@@ -78,6 +78,7 @@ async function build_context(
 		headless_refusals: stop_rules.count_headless_refusals(tail),
 		lane_child: lane_child_marker.is_child_of(process.cwd()),
 		background_pending: lane_background.pending_background_ids(tail).length > 0,
+		agent_pending: lane_background.pending_agent_ids(tail).length > 0,
 		session_lang: session_lang(),
 	}
 }

package/scripts/init/init-bootstrap.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import { z } from 'zod'
+import { init_install, type InstallStep } from './init-install'
+import { init_logic_workspace } from './init-logic-workspace'
+
+const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
+const NODE_MODULES = 'node_modules'
+const PACKAGE_JSON = 'package.json'
+// The static template lists exactly the build scripts kit's own dependency tree carries, which is
+// what installing kit alone needs approved (joshuafolkken/kit#2785).
+const KIT_BUILDS_TEMPLATE = 'templates/pnpm-workspace.static.yaml'
+const HANDOFF_FAILURE = 'josh init from the project-installed kit failed — see the output above'
+// Set on the handed-off run, so a kit that still does not find itself installed in the project — pnpm
+// put it somewhere else — stops instead of installing and handing off again without end.
+const HANDOFF_ENV = 'JOSH_INIT_HANDED_OFF'
+const REPEATED_HANDOFF = `the kit this project installed is not at ${NODE_MODULES}/${KIT_PACKAGE_NAME} — run \`pnpm exec josh init\` where it is`
+
+const dependency_fields_schema = z.looseObject({
+	dependencies: z.record(z.string(), z.string()).optional(),
+	devDependencies: z.record(z.string(), z.string()).optional(),
+})
+
+function real_directory(directory: string): string | undefined {
+	return existsSync(directory) ? realpathSync(directory) : undefined
+}
+
+// A `pnpm dlx` (or global) run executes whatever kit its cache held, which may be days behind the
+// registry — and `init` pins the kit it runs as, so a stale cache used to leave its version and its
+// templates in the project for good (joshuafolkken/kit#2794). Only the kit the project itself installs
+// does the setup. Compared by real path, so a global virtual store shared with the project still
+// reads as the project's own kit.
+function is_project_kit(package_directory: string, project_root: string): boolean {
+	const installed = real_directory(path.join(project_root, NODE_MODULES, KIT_PACKAGE_NAME))
+
+	return installed !== undefined && installed === real_directory(package_directory)
+}
+
+function kit_build_flags(template: string): Array<string> {
+	return [...init_logic_workspace.template_build_values(template)]
+		.filter(([, value]) => value === 'true')
+		.map(([name]) => `--allow-build=${name}`)
+}
+
+function has_kit_dependency(project_root: string): boolean {
+	const manifest_path = path.join(project_root, PACKAGE_JSON)
+	if (!existsSync(manifest_path)) return false
+	const parsed: unknown = JSON.parse(readFileSync(manifest_path, 'utf8'))
+	const manifest = dependency_fields_schema.parse(parsed)
+	const names = Object.keys({ ...manifest.dependencies, ...manifest.devDependencies })
+
+	return names.includes(KIT_PACKAGE_NAME)
+}
+
+// A project that already lists kit keeps the version it chose; otherwise pnpm picks it, under the
+// project's own `minimumReleaseAge`, so the version installed is never the cache's decision.
+function kit_install_step(has_kit: boolean, template: string): InstallStep {
+	if (has_kit) return { label: 'pnpm install', command: 'pnpm', args: ['install'] }
+	const args = ['add', '-D', ...kit_build_flags(template), KIT_PACKAGE_NAME]
+
+	return { label: `pnpm ${args.join(' ')}`, command: 'pnpm', args }
+}
+
+function handoff_step(args: ReadonlyArray<string>): InstallStep {
+	const handoff_args = ['exec', 'josh', 'init', ...args]
+
+	return {
+		label: `pnpm ${handoff_args.join(' ')}`,
+		command: 'pnpm',
+		args: handoff_args,
+		env: { [HANDOFF_ENV]: '1' },
+	}
+}
+
+// Returns the failure to report, or undefined once the project-installed kit finished the setup.
+function hand_off(
+	package_directory: string,
+	project_root: string,
+	args: ReadonlyArray<string>,
+): string | undefined {
+	if (process.env[HANDOFF_ENV] !== undefined) return REPEATED_HANDOFF
+	console.info('\n🚀 Installing @joshuafolkken/kit into the project, then running its josh init')
+	const template = readFileSync(path.join(package_directory, KIT_BUILDS_TEMPLATE), 'utf8')
+	const install = kit_install_step(has_kit_dependency(project_root), template)
+	if (!init_install.did_step_succeed(install, project_root)) return `${install.label} failed`
+	if (!init_install.did_step_succeed(handoff_step(args), project_root)) return HANDOFF_FAILURE
+
+	return undefined
+}
+
+const init_bootstrap = { is_project_kit, kit_build_flags, hand_off }
+export { init_bootstrap }

package/scripts/init/init-install.ts

@@ -0,0 +1,67 @@
+import { execaSync } from 'execa'
+
+interface InstallStep {
+	label: string
+	command: string
+	args: ReadonlyArray<string>
+	env?: Readonly<Record<string, string>>
+}
+
+interface InstallRequest {
+	is_install: boolean
+	rest: ReadonlyArray<string>
+}
+
+const NO_INSTALL_FLAG = '--no-install'
+const INSTALL_STEP: InstallStep = { label: 'pnpm install', command: 'pnpm', args: ['install'] }
+const FORMAT_STEP: InstallStep = {
+	label: 'pnpm josh format',
+	command: 'pnpm',
+	args: ['exec', 'josh', 'format'],
+}
+const INSTALL_FAILURE = [
+	`${INSTALL_STEP.label} failed — fix the cause above,`,
+	`then run it manually: ${INSTALL_STEP.label} && ${FORMAT_STEP.label}`,
+].join(' ')
+const FORMAT_WARNING = [
+	`  ⚠ ${FORMAT_STEP.label} left problems it could not fix in the project's own files —`,
+	`the setup itself succeeded; fix them, then run: ${FORMAT_STEP.label}`,
+].join(' ')
+
+// The flag is peeled off before the `--profile` pair is parsed, so the profile parser stays the one
+// `josh start` shares.
+function split_install_flag(args: ReadonlyArray<string>): InstallRequest {
+	return {
+		is_install: !args.includes(NO_INSTALL_FLAG),
+		rest: args.filter((argument) => argument !== NO_INSTALL_FLAG),
+	}
+}
+
+function did_step_succeed(step: InstallStep, project_root: string): boolean {
+	console.info(`\n$ ${step.label}`)
+	const result = execaSync(step.command, step.args, {
+		cwd: project_root,
+		env: step.env ?? {},
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode === 0
+}
+
+// Returns the failure to report, or undefined once the install passed. A failed install stops
+// there: `josh format` runs prettier and the kit itself, both of which the install provides. A failed
+// format does not fail `init` — in a node project it also runs `eslint --fix`, which exits non-zero on
+// the project's own unfixable errors, and those are the project's result, not the setup's (the
+// reason `josh gate` is left out of `init` too).
+function run_post_init_steps(project_root: string): string | undefined {
+	console.info('\nDependencies:')
+	if (!did_step_succeed(INSTALL_STEP, project_root)) return INSTALL_FAILURE
+	if (!did_step_succeed(FORMAT_STEP, project_root)) console.warn(FORMAT_WARNING)
+
+	return undefined
+}
+
+const init_install = { NO_INSTALL_FLAG, split_install_flag, did_step_succeed, run_post_init_steps }
+export { init_install }
+export type { InstallStep }

package/scripts/init/init-logic-workspace.ts

@@ -138,6 +138,6 @@ function merge_workspace_yaml(existing: string, template: string): string {
 	return append_user_blocks(cleaned, new_keys, template)
 }
 
-const init_logic_workspace = { merge_workspace_yaml }
+const init_logic_workspace = { merge_workspace_yaml, template_build_values }
 
 export { init_logic_workspace }

package/scripts/init/init.ts

@@ -15,11 +15,13 @@ import { execaSync } from 'execa'
 import { z } from 'zod'
 import { init_actions, PRETTIER_CONFIG_JS, type FileAction } from './init-actions'
 import { init_ai_copy } from './init-ai-copy'
+import { init_bootstrap } from './init-bootstrap'
+import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
 import { init_static } from './init-static'
 import { plugin_install_hint_module } from './plugin-install-hint'
-import { project_profile, type ProjectShape } from './project-profile'
+import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
 const PACKAGE_JSON = 'package.json'
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
@@ -28,6 +30,7 @@ const SAMPLE_INDENT_WIDTH = 4
 const ARGUMENT_START_INDEX = 2
 const SAMPLE_INDENT = ' '.repeat(SAMPLE_INDENT_WIDTH)
 const INSTALL_HINT = '→ run `pnpm install` to install what package.json lists'
+const INIT_USAGE = 'josh init [--profile static|node] [--no-install]'
 
 function write_new_file(action: FileAction, destination_path: string): void {
 	mkdirSync(path.dirname(destination_path), { recursive: true })
@@ -218,14 +221,10 @@ function merge_project_package_json(shape: ProjectShape): void {
 
 	writeFileSync(package_json_path, merged)
 	console.info(`  ✔ ${is_existing ? 'updated' : 'created'}   package.json`)
-	// `init` writes the manifest but installs nothing, so a tool it just listed is absent until the
-	// user installs it — and `josh lint` then fails on it rather than skipping it
-	// (joshuafolkken/kit#2709). Saying so here is what tells the user the next step.
-	console.info(`    ${INSTALL_HINT}`)
 }
 
-// A fresh project runs `init` before its first `pnpm install`, so lefthook — added to devDependencies
-// above — is not there yet; the `prepare` script installs the hooks once it is.
+// Under `--no-install` a fresh project has no lefthook yet — added to devDependencies above — so the
+// `prepare` script of the user's own `pnpm install` installs the hooks once it is.
 function install_lefthook(project_root: string = PROJECT_ROOT): void {
 	console.info('\nLefthook:')
 	const bin = resolve_local_bin(project_root, LEFTHOOK_BIN)
@@ -285,8 +284,6 @@ function run_ai_file_actions(shape: ProjectShape): void {
 	// resolved, so `gh repo view` runs once; the position is the pre-existing one.
 	const name_with_owner = init_ai_copy.run_ai_copies(shape)
 
-	if (shape.has_git && shape.profile === 'node') install_lefthook()
-
 	if (shape.has_github) report_repository_settings(name_with_owner)
 
 	if (shape.profile === 'node') plugin_install_hint_module.report_plugin_install_hint()
@@ -302,19 +299,67 @@ function initialize_project(shape: ProjectShape): void {
 
 	run_ai_file_actions(shape)
 	if (shape.profile === 'node') project_config.sync_project_config(PROJECT_ROOT)
+}
+
+// A tool `init` just listed is absent until the user installs it — and `josh lint` then fails on it
+// rather than skipping it (joshuafolkken/kit#2709). Saying so is what tells the user the next step.
+function report_manual_install(shape: ProjectShape): void {
+	console.info(`\nDependencies:\n  ${INSTALL_HINT}`)
+	if (shape.has_git && shape.profile === 'node') install_lefthook()
+}
+
+// The install runs the `prepare` script, which installs the git hooks. A failure is thrown rather
+// than printed, so `josh start` — which calls this entry point — stops before its first commit.
+function finish_dependencies(shape: ProjectShape, is_install: boolean): void {
+	if (!is_install) {
+		report_manual_install(shape)
+
+		return
+	}
+
+	const failure = init_install.run_post_init_steps(PROJECT_ROOT)
+	if (failure !== undefined) throw new Error(failure)
+}
+
+// A kit run from outside the project — `pnpm dlx`, a global install — sets nothing up itself: it
+// installs the project's kit and hands the whole run to that one (joshuafolkken/kit#2794). Under
+// `--no-install` nothing is installed, so the running kit does the setup as before.
+function did_hand_off(args: ReadonlyArray<string>): boolean {
+	if (init_bootstrap.is_project_kit(PACKAGE_DIR, PROJECT_ROOT)) return false
+	const failure = init_bootstrap.hand_off(PACKAGE_DIR, PROJECT_ROOT, args)
+	if (failure !== undefined) throw new Error(failure)
+
+	return true
+}
+
+function set_up_project(requested: ProjectProfile | undefined, is_install: boolean): void {
+	const shape = project_profile.inspect_project(PROJECT_ROOT, requested)
+
+	initialize_project(shape)
+	finish_dependencies(shape, is_install)
 	console.info('\n✅ Done.\n')
 }
 
 function main(args: ReadonlyArray<string> = []): void {
 	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
-	const requested = project_profile.requested_profile(args)
-	const shape = project_profile.inspect_project(PROJECT_ROOT, requested)
+	const { is_install, rest } = init_install.split_install_flag(args)
+	// Validated before the hand-off, so a malformed invocation is refused before kit is installed.
+	const requested = project_profile.requested_profile(rest, INIT_USAGE)
 
-	initialize_project(shape)
+	if (!is_install || !did_hand_off(args)) set_up_project(requested, is_install)
+}
+
+function run_cli(args: ReadonlyArray<string>): void {
+	try {
+		main(args)
+	} catch (error) {
+		console.error(`\n✖ ${error instanceof Error ? error.message : String(error)}\n`)
+		process.exitCode = 1
+	}
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	main(process.argv.slice(ARGUMENT_START_INDEX))
+	run_cli(process.argv.slice(ARGUMENT_START_INDEX))
 }
 
 const init = {

package/scripts/init/start-plan.ts

@@ -46,7 +46,7 @@ const STEP_LABELS: Readonly<Record<StartStep, string>> = {
 	initialize: 'Initialize kit (the same setup as josh init)',
 	commit: 'Commit every file as the initial commit',
 	repository: 'Create the GitHub repository and push main',
-	labels: 'Add the workflow labels the repository is missing',
+	labels: 'Add the workflow and release-classification labels the repository is missing',
 }
 
 function refused(refusal: string): StepPlan {

package/scripts/init/start-steps.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
-import { WORKFLOW_LABELS } from '#scripts/git/issue-labels'
+import { repository_labels } from '#scripts/repo/repository-labels'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { execaSync } from 'execa'
 import { main as init_main } from './init'
@@ -14,10 +14,7 @@ interface StepContext {
 	visibility: Visibility
 }
 
-type WorkflowLabel = (typeof WORKFLOW_LABELS)[number]
-
 const DEFAULT_BRANCH = 'main'
-const LABELS_ENDPOINT = 'repos/{owner}/{repo}/labels'
 const GH_INSTALL_HINT =
 	'GitHub CLI (gh) is not installed. Install it from https://cli.github.com/, run gh auth login, then run josh start again. Nothing was changed.'
 const GH_AUTH_HINT =
@@ -100,29 +97,10 @@ function create_github_repository(context: StepContext): void {
 	run('gh', ['repo', 'create', name, visibility, ...source], context.root)
 }
 
-// Labels already present are left as they are — only the missing ones are created, so a repository
-// that recolored a label keeps its choice. GitHub compares label names case-insensitively.
-function missing_workflow_labels(existing: ReadonlyArray<string>): ReadonlyArray<WorkflowLabel> {
-	const names = new Set(existing.map((name) => name.toLowerCase()))
-
-	return WORKFLOW_LABELS.filter((label) => !names.has(label.name))
-}
-
-function create_label(label: WorkflowLabel, root: string): void {
-	const fields = [`name=${label.name}`, `color=${label.color}`, `description=${label.description}`]
-
-	run('gh', ['api', LABELS_ENDPOINT, ...fields.flatMap((field) => ['-f', field]), '--silent'], root)
-	console.info(`  ✔ label ${label.name}`)
-}
-
-function add_missing_labels(context: StepContext): void {
-	const listing = execaSync('gh', ['api', '--paginate', LABELS_ENDPOINT, '--jq', '.[].name'], {
-		...git_gh_exec.direct_environment(),
-		cwd: context.root,
-	})
-	const existing = listing.stdout.split('\n').filter((name) => name.length > 0)
-
-	for (const label of missing_workflow_labels(existing)) create_label(label, context.root)
+// The repository was created by the step before, so `gh` resolves the placeholder from the
+// directory `josh start` runs in, which is the root.
+function add_missing_labels(): void {
+	repository_labels.ensure_labels('{owner}/{repo}')
 }
 
 const STEP_ACTIONS: Readonly<Record<StartStep, (context: StepContext) => void>> = {
@@ -160,7 +138,6 @@ const start_steps = {
 	read_git_state,
 	github_cli_refusal,
 	self_run_refusal,
-	missing_workflow_labels,
 	run_steps,
 }
 export { start_steps }