@joshuafolkken/kit 1.953.0 → 1.972.0

package/scripts/git/git-pr-followup-wrapup.ts

@@ -1,6 +1,7 @@
 import { git_epic_close } from './git-epic-close'
 import { git_followup_cleanup } from './git-followup-cleanup'
 import { git_followup_flush } from './git-followup-flush'
+import { git_followup_issue_close } from './git-followup-issue-close'
 import { git_followup_label } from './git-followup-label'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
 import { git_gh_command } from './git-gh-command'
@@ -25,6 +26,9 @@ const IN_PROGRESS_RECOVERY = 'gh api -X DELETE repos/{owner}/{repo}/issues/<N>/l
 interface WrapupInput {
 	branch_name: string
 	issue_number: string | undefined
+	// The number the pull request body's `closes #N` names — the only issue the merge claimed to
+	// close, so the only one the merged-issue close may write to (joshuafolkken/kit#2770).
+	closes_number: string | undefined
 	notify_config: GitNotifyConfig | undefined
 	pr_url: string | undefined
 	should_merge: boolean
@@ -164,9 +168,30 @@ async function in_progress_step(input: WrapupInput): Promise<void> {
 	})
 }
 
+// **The merged issue's close, confirmed rather than assumed** (joshuafolkken/kit#2770): GitHub stopped
+// applying `closes #N` on some merges, and nothing noticed. The epic auto-close does not wait on it —
+// it already excludes the merged issue from its reads — so it runs beside the other steps. It acts on
+// the body's `closes #N` rather than the run's issue number: a pull request that closes nothing, or
+// another issue, never closes the one the invocation named.
+async function issue_close_step(input: WrapupInput): Promise<void> {
+	if (!input.should_merge) return
+
+	await git_followup_cleanup.run_guarded_step(input.should_merge, {
+		label: 'The merged issue close',
+		recovery: git_followup_issue_close.CLOSE_RECOVERY,
+		run: async () => {
+			await git_followup_issue_close.ensure_issue_closed({
+				issue_number: input.closes_number,
+				pr_url: input.pr_url,
+			})
+		},
+	})
+}
+
 // **The steps after the merge are issued together** (joshuafolkken/kit#1446). The completion
-// comment writes to the issue or the pull request, the auto-close reads the open epics, and the
-// label removal reads and writes the issue's labels; none needs another's answer, and measured
+// comment writes to the issue or the pull request, the auto-close reads the open epics, the label
+// removal reads and writes the issue's labels, and the merged-issue close reads and may close the
+// issue; none needs another's answer, and measured
 // serially the first two were 1.9 s and 3.1 s of `followup`'s own clock. Past the merge none can
 // reject another — `run_guarded_step` reports the failure and answers instead — so they settle
 // independently and the stage costs the longest of them rather than their sum.
@@ -178,9 +203,9 @@ async function in_progress_step(input: WrapupInput): Promise<void> {
 // (`git-followup-cleanup.ts`), which is easier to read as one sequence than as a settled set.
 //
 // **What the overlap costs, stated rather than glossed**: mutating requests now go out at once
-// against one repository — a comment write, an auto-close that comments on and closes epics, and a
-// label delete — which is what GitHub's secondary rate limit guidance is about. Past the merge all
-// of them are guarded, so the worst case is a cleanup reported as unfinished rather than a failed
+// against one repository — a comment write, an auto-close that comments on and closes epics, a label
+// delete, and the merged issue's close when GitHub did not apply it — which is what GitHub's
+// secondary rate limit guidance is about. Past the merge all of them are guarded, so the worst case is a cleanup reported as unfinished rather than a failed
 // run, and this is a handful of requests rather than a fan-out. **Their console output can
 // interleave too**: the guard's warning and its recovery line are printed as they happen, so an
 // auto-close progress line can land between them. The recovery line names its own command and stands
@@ -194,7 +219,12 @@ async function run_tail_steps(input: WrapupInput): Promise<void> {
 		return
 	}
 
-	await Promise.all([notify_step(input), epic_close_step(input), in_progress_step(input)])
+	await Promise.all([
+		notify_step(input),
+		epic_close_step(input),
+		in_progress_step(input),
+		issue_close_step(input),
+	])
 }
 
 async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {

package/scripts/git/git-pr-followup.ts

@@ -1,3 +1,4 @@
+import { git_closes_keyword } from './git-closes-keyword'
 import { git_followup_pending } from './git-followup-pending'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
 import { git_gh_command } from './git-gh-command'
@@ -15,10 +16,6 @@ import { telegram_notify, type TelegramSendInput, type TelegramTaskType } from '
 
 const { STAGE, lap } = git_followup_stages
 
-// Captures the number, so the one pattern answers both questions the run asks of a PR body: whether
-// the linked issue will auto-close, and — since joshuafolkken/kit#1539 — which issue that is when the
-// invocation did not say. A second pattern here would be two readings of "closes #N" to disagree.
-const CLOSES_PATTERN = /closes\s+#(\d+)/iu
 // Named so a test can pin the note without restating it (joshuafolkken/kit#999).
 const WATCH_FAILED_NOTE = 'pr checks --watch failed; falling through to polling'
 const REPO_NAME_SEPARATOR = '/'
@@ -69,11 +66,7 @@ interface FollowupInput {
 	should_merge: boolean
 }
 
-function parse_closes_issue_number(body: string | undefined): string | undefined {
-	if (body === undefined) return undefined
-
-	return CLOSES_PATTERN.exec(body)?.[1]
-}
+const { parse_closes_issue_number } = git_closes_keyword
 
 function has_closes_keyword(body: string | undefined): boolean {
 	return parse_closes_issue_number(body) !== undefined
@@ -234,6 +227,7 @@ async function read_issue_title(
 
 interface RunContext {
 	issue_number: string | undefined
+	closes_number: string | undefined
 	context: TelegramContext
 }
 
@@ -256,19 +250,17 @@ async function read_run_context(input: {
 	issue_number: string | undefined
 }): Promise<RunContext> {
 	const closes = warn_if_missing_closes(input.branch_name)
-	const owner = git_gh_command.repo_get_name_with_owner()
-	const url = git_gh_command.pr_get_url(input.branch_name)
-	const title = read_issue_title(input.issue_number, closes)
 	const [closes_number, name_with_owner, pr_url, issue_title] = await Promise.all([
 		closes,
-		owner,
-		url,
-		title,
+		git_gh_command.repo_get_name_with_owner(),
+		git_gh_command.pr_get_url(input.branch_name),
+		read_issue_title(input.issue_number, closes),
 	])
 	const issue_number = input.issue_number ?? closes_number
 
 	return {
 		issue_number,
+		closes_number,
 		context: {
 			repo_name: parse_repo_name(name_with_owner),
 			issue_title,
@@ -373,7 +365,7 @@ async function run_review_checks(
 // the epic close all name the same issue — and so the caller's own tail can record a run whose number
 // only the pull request knew.
 async function run_stages(input: FollowupInput, log: StageLog): Promise<string | undefined> {
-	const { issue_number, context } = await read_run_context(input)
+	const { issue_number, closes_number, context } = await read_run_context(input)
 
 	lap(log, STAGE.closes_and_context)
 	const checks = await run_review_checks(input, context, log)
@@ -385,6 +377,7 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 		{
 			branch_name: input.branch_name,
 			issue_number,
+			closes_number,
 			notify_config: input.notify_config,
 			pr_url: context.pr_url,
 			should_merge: input.should_merge,

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,6 +186,34 @@ 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<{
+	name: string
+	color: string
+	description: string
+}> = [
+	{
+		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 shape `gh issue list --json labels` returns; narrowed here so the predicate below takes any
 // listing row without importing a schema.
 interface LabelReference {
@@ -251,6 +288,8 @@ 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,
@@ -283,6 +322,9 @@ export {
 	NOT_DIRECTLY_RUNNABLE_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-install.ts

@@ -0,0 +1,64 @@
+import { execaSync } from 'execa'
+
+interface InstallStep {
+	label: string
+	command: string
+	args: ReadonlyArray<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,
+		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, run_post_init_steps }
+export { init_install }

package/scripts/init/init.ts

@@ -15,6 +15,7 @@ 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_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
 import { init_static } from './init-static'
@@ -28,6 +29,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 +220,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 +283,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 +298,50 @@ function initialize_project(shape: ProjectShape): void {
 
 	run_ai_file_actions(shape)
 	if (shape.profile === 'node') project_config.sync_project_config(PROJECT_ROOT)
-	console.info('\n✅ Done.\n')
+}
+
+// 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)
 }
 
 function main(args: ReadonlyArray<string> = []): void {
 	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
-	const requested = project_profile.requested_profile(args)
+	const { is_install, rest } = init_install.split_install_flag(args)
+	const requested = project_profile.requested_profile(rest, INIT_USAGE)
 	const shape = project_profile.inspect_project(PROJECT_ROOT, requested)
 
 	initialize_project(shape)
+	finish_dependencies(shape, is_install)
+	console.info('\n✅ Done.\n')
+}
+
+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/project-profile.ts

@@ -29,12 +29,16 @@ function parse_profile(value: unknown): ProjectProfile | undefined {
 	return undefined
 }
 
-function requested_profile(args: ReadonlyArray<string>): ProjectProfile | undefined {
-	if (args.length === 0) return undefined
+function is_profile_pair(args: ReadonlyArray<string>): boolean {
+	return args.length === PROFILE_ARG_LENGTH && args[0] === '--profile'
+}
 
-	if (args.length !== PROFILE_ARG_LENGTH || args[0] !== '--profile') {
-		throw new Error('Usage: josh init [--profile static|node]')
-	}
+function requested_profile(
+	args: ReadonlyArray<string>,
+	usage = 'josh init [--profile static|node]',
+): ProjectProfile | undefined {
+	if (args.length === 0) return undefined
+	if (!is_profile_pair(args)) throw new Error(`Usage: ${usage}`)
 
 	const profile = parse_profile(args[1])
 	if (profile !== undefined) return profile

package/scripts/init/start-plan.ts

@@ -0,0 +1,145 @@
+import type { ProjectProfile } from './project-profile'
+
+type Visibility = 'private' | 'public'
+
+interface StartOptions {
+	profile: ProjectProfile | undefined
+	is_yes: boolean
+	is_github: boolean
+	visibility: Visibility
+}
+
+type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels'
+
+interface GitState {
+	has_git: boolean
+	has_github: boolean
+	has_origin: boolean
+	branch: string | undefined
+	has_commits: boolean
+}
+
+interface StepPlan {
+	steps: ReadonlyArray<StartStep>
+	refusal: string | undefined
+}
+
+type Interaction = 'interactive' | 'unattended'
+type Consent = 'granted' | 'ask'
+
+interface Verdict<T> {
+	value: T | undefined
+	refusal: string | undefined
+}
+
+const DEFAULT_BRANCH = 'main'
+const FULL_STEPS: ReadonlyArray<StartStep> = [
+	'git_init',
+	'initialize',
+	'commit',
+	'repository',
+	'labels',
+]
+
+const STEP_LABELS: Readonly<Record<StartStep, string>> = {
+	git_init: 'Create a Git repository on main',
+	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',
+}
+
+function refused(refusal: string): StepPlan {
+	return { steps: [], refusal }
+}
+
+// A repository that already has a history keeps it: nothing is committed on the user's behalf, and
+// only `main` is pushed, because the Issue workflow branches from and merges into it.
+function existing_git_steps(state: GitState): StepPlan {
+	if (!state.has_commits) return { steps: FULL_STEPS.slice(1), refusal: undefined }
+
+	if (state.branch !== DEFAULT_BRANCH) {
+		return refused(
+			`josh start pushes ${DEFAULT_BRANCH}, but this repository is on ${state.branch ?? 'a detached HEAD'}. Switch to ${DEFAULT_BRANCH}, or run josh init to set up without GitHub.`,
+		)
+	}
+
+	return { steps: ['initialize', 'repository', 'labels'], refusal: undefined }
+}
+
+// An existing GitHub origin is never replaced or pushed to: only the additive steps run. Any other
+// origin is refused here, before the first write — `gh repo create --remote origin` cannot add a
+// remote that already exists, so the run would otherwise fail after initializing the directory.
+function plan_steps(state: GitState): StepPlan {
+	if (state.has_github) return { steps: ['initialize', 'labels'], refusal: undefined }
+
+	if (state.has_origin) {
+		return refused(
+			'josh start creates the GitHub repository as origin, but this repository already has an origin that is not on GitHub. Remove or rename it, or run josh init to set up without GitHub.',
+		)
+	}
+
+	if (state.has_git) return existing_git_steps(state)
+
+	return { steps: FULL_STEPS, refusal: undefined }
+}
+
+function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interaction> {
+	if (options.is_yes) return { value: 'unattended', refusal: undefined }
+	if (is_tty) return { value: 'interactive', refusal: undefined }
+
+	return {
+		value: undefined,
+		refusal:
+			'josh start needs a terminal to confirm its choices. Pass --yes to accept the detected profile, and --github to create the GitHub repository.',
+	}
+}
+
+// `--yes` accepts the detected defaults, never the creation of a public-facing resource: an
+// unattended run creates and pushes a repository only when `--github` asks for it by name.
+function github_consent(
+	steps: ReadonlyArray<StartStep>,
+	options: StartOptions,
+	interaction: Interaction,
+): Verdict<Consent> {
+	if (!steps.includes('repository') || options.is_github) {
+		return { value: 'granted', refusal: undefined }
+	}
+
+	if (interaction === 'interactive') return { value: 'ask', refusal: undefined }
+
+	return {
+		value: undefined,
+		refusal:
+			'josh start --yes does not create a GitHub repository or push. Add --github to create one, or run josh init to set up without GitHub.',
+	}
+}
+
+// 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,
+): string {
+	const done =
+		completed.length === 0 ? 'nothing' : completed.map((step) => STEP_LABELS[step]).join('; ')
+
+	return `josh start stopped at: ${STEP_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]}`)
+
+	return ['josh start will:', ...lines].join('\n')
+}
+
+const start_plan = {
+	plan_steps,
+	interaction_of,
+	github_consent,
+	progress_report,
+	plan_summary,
+	STEP_LABELS,
+}
+export { start_plan }
+export type { Consent, GitState, Interaction, StartOptions, StartStep, StepPlan, Visibility }