@joshuafolkken/kit 1.1435.0 → 1.1453.0

package/scripts/init/start-steps.ts

@@ -15,6 +15,7 @@ import { start_exec } from './start-exec'
 import { start_plan, type GitState, type StartStep, type Visibility } from './start-plan'
 import { start_setup_pr } from './start-setup-pr'
 import { workflow_mark } from './workflow-mark'
+import { working_tree } from './working-tree'
 
 interface StepContext {
 	root: string
@@ -83,6 +84,17 @@ function git_identity_refusal(steps: ReadonlyArray<StartStep>, root: string): st
 		: undefined
 }
 
+// A repository with a history receives the setup as a commit, and the user's own uncommitted change to
+// a file kit also writes would land in it, so the tree must be clean before the first write (#3835).
+// The setup branch a failed commit or push left checked out is the exception: what is uncommitted
+// there is that run's own output, which the re-run resumes with. Without a commit there is nothing to
+// keep apart — the initial commit takes every file.
+function uncommitted_refusal(root: string, state: GitState): string | undefined {
+	if (!state.has_commits || start_setup_pr.is_setup_branch(state.branch)) return undefined
+
+	return working_tree.dirty_tree_refusal(root, 'josh start')
+}
+
 // `josh init` refuses to run inside the kit source repository by printing and setting the exit code
 // rather than throwing, so its step would pass and the later steps would commit and publish the
 // source repository. The same check is raised before the first write instead.
@@ -141,7 +153,9 @@ async function open_setup_pull_request(context: RunContext): Promise<void> {
 // What was already changed before the setup ran, read whenever a setup pull request will follow, so
 // it can tell the setup's files from the user's own (#2872). Kit's own `josh init` needs it as much as
 // a caller's command: its `josh format` rewrites the project's own sources, which kit cannot name, and
-// leaving them out failed the pull request's Prettier check.
+// leaving them out failed the pull request's Prettier check. On `main` it is empty, since a dirty tree
+// is refused there (#3835); it is kept for the setup branch a failed commit left, where the earlier
+// run's output is already uncommitted when the re-run starts.
 function baseline_of(
 	steps: ReadonlyArray<StartStep>,
 	context: StepContext,
@@ -239,6 +253,7 @@ const start_steps = {
 	github_cli_refusal,
 	git_identity_refusal,
 	self_run_refusal,
+	uncommitted_refusal,
 	run_steps,
 }
 export { start_steps }

package/scripts/init/start.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { error_text } from '#scripts/lib/error-message'
-import { project_profile, type ProjectProfile } from './project-profile'
+import { init_dry_run } from './init-dry-run'
+import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
+import { start_dry_run } from './start-dry-run'
 import {
 	start_plan,
 	type Consent,
@@ -15,13 +17,14 @@ 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] [--init-command <command>] [--push-preflight-command <command>]'
+	'josh start [--profile basic|full] [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]'
 const INIT_COMMAND_FLAG = '--init-command'
 const PUSH_PREFLIGHT_COMMAND_FLAG = '--push-preflight-command'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
-const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG])
+const { DRY_RUN_FLAG } = init_dry_run
+const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG, DRY_RUN_FLAG])
 
 interface Prepared {
 	steps: ReadonlyArray<StartStep>
@@ -67,6 +70,7 @@ function parse_start_options(args: ReadonlyArray<string>): StartOptions {
 		profile: project_profile.requested_profile(profile_args, START_USAGE),
 		is_yes: rest.includes(YES_FLAG),
 		is_github: rest.includes(GITHUB_FLAG),
+		is_dry_run: rest.includes(DRY_RUN_FLAG),
 		visibility: rest.includes(PUBLIC_FLAG) ? 'public' : 'private',
 		init_command: init.command,
 		push_preflight_command,
@@ -94,34 +98,34 @@ async function resolve_profile(
 	return await start_prompt.confirm_choices(choices)
 }
 
+function planned_steps(root: string, shape: ProjectShape): ReadonlyArray<StartStep> {
+	const state = start_steps.read_git_state(root, shape)
+	const plan = start_plan.plan_steps(state)
+
+	stop_on(plan.refusal)
+	stop_on(start_steps.uncommitted_refusal(root, state))
+
+	return plan.steps
+}
+
 // Every refusal is raised here, before the first write, so a run that stops here changed nothing.
 function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Prepared {
 	stop_on(start_steps.self_run_refusal(root))
 	const options = parse_start_options(args)
 	const interaction = settle(start_plan.interaction_of(options, is_tty))
 	const shape = project_profile.inspect_project(root, options.profile)
-	const plan = start_plan.plan_steps(start_steps.read_git_state(root, shape))
-
-	stop_on(plan.refusal)
-	const consent: Consent = settle(start_plan.github_consent(plan.steps, options, interaction))
+	const steps = planned_steps(root, shape)
+	const consent: Consent = settle(start_plan.github_consent(steps, options, interaction))
 
 	stop_on(start_steps.github_cli_refusal(root))
-	stop_on(start_steps.git_identity_refusal(plan.steps, root))
+	stop_on(start_steps.git_identity_refusal(steps, root))
 
-	return {
-		steps: plan.steps,
-		interaction,
-		choices: { options, shape, consent, root, steps: plan.steps },
-	}
+	return { steps, interaction, choices: { options, shape, consent, root, steps } }
 }
 
-async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
-	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
-
+async function run_steps({ steps, interaction, choices }: Prepared): Promise<void> {
 	const { root, options } = choices
 	const { visibility, init_command, push_preflight_command } = options
-
-	console.info(start_plan.plan_summary(steps, start_plan.step_labels(init_command)))
 	const profile = await resolve_profile(choices, interaction)
 	const context = { root, profile, visibility, init_command, push_preflight_command }
 
@@ -129,6 +133,22 @@ async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void>
 	console.info(`\n${READY_MESSAGE}`)
 }
 
+// A dry run stops after the plan, adding what each step would create, before the first write.
+async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
+	const prepared = prepare(args, is_tty, process.cwd())
+	const { steps, choices } = prepared
+
+	console.info(start_plan.plan_summary(steps, start_plan.step_labels(choices.options.init_command)))
+
+	if (choices.options.is_dry_run) {
+		console.info(start_dry_run.report(choices))
+
+		return
+	}
+
+	await run_steps(prepared)
+}
+
 async function run(args: ReadonlyArray<string>, is_tty: boolean): Promise<number> {
 	try {
 		await main(args, is_tty)

package/scripts/init/working-tree.ts

@@ -0,0 +1,116 @@
+import { git_location_environment } from '#scripts/git/git-location-environment'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { start_exec } from './start-exec'
+
+const UNTRACKED_ARGUMENTS = ['ls-files', '--others', '--exclude-standard']
+// `--relative` keeps the listing to the project and its paths relative to it, the way `ls-files`
+// already reads them, for a project that sits below its repository's top level.
+const MODIFIED_ARGUMENTS = ['diff', '--name-only', '--relative', 'HEAD']
+// Under an unborn HEAD every indexed file is uncommitted, so the index itself is the listing.
+const INDEXED_ARGUMENTS = ['ls-files', '--cached']
+const HISTORY_ARGUMENTS = ['rev-list', '--max-count=1', '--all']
+const UNBORN_HEAD_EXIT_CODE = 1
+const NOT_A_REPOSITORY = 'not a git repository'
+
+// What a project's working tree holds that is not committed, read one way for every setup command:
+// the setup pull request tells the setup's files from the user's own with it, and `josh init` refuses
+// to write over it.
+
+// 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.git_read([...args, '-z'], root))
+}
+
+// Untracked files the ignore rules let through, plus tracked files changed since HEAD, staged or not
+// — two plain listings, so nothing has to be parsed out of `git status`.
+function changed_paths(root: string): Array<string> {
+	const untracked = listing(UNTRACKED_ARGUMENTS, root)
+	const modified = listing(MODIFIED_ARGUMENTS, root)
+
+	return [...untracked, ...modified]
+}
+
+// A read that failed is thrown rather than read as an empty listing: the refusal guards the user's
+// work, so a git that did not answer must never pass for a clean tree.
+function strict_listing(args: ReadonlyArray<string>, root: string): Array<string> {
+	const output = start_exec.git_read([...args, '-z'], root)
+
+	if (output === undefined) throw new Error(`git ${args.join(' ')} failed in ${root}`)
+
+	return paths_of(output)
+}
+
+type HeadState = 'born' | 'unborn' | 'absent'
+
+// Asked of git rather than of a `.git` beside the project, so a project below its repository's top
+// level is still found. `--verify --quiet` exits 1 for an unborn HEAD, and only `not a git repository`
+// (read under the C locale) proves there is no repository; any other failure is an unanswered
+// question, not a missing commit.
+function head_state(root: string): HeadState {
+	const { exit_code, stderr } = git_spawn_sync.run(['rev-parse', '--verify', '--quiet', 'HEAD'], {
+		cwd: root,
+		env: { ...git_spawn_sync.C_LOCALE, ...git_location_environment.location_free_environment() },
+	})
+
+	if (exit_code === 0) return 'born'
+	if (stderr.includes(NOT_A_REPOSITORY)) return 'absent'
+	if (exit_code === UNBORN_HEAD_EXIT_CODE) return 'unborn'
+	throw new Error(`git rev-parse could not read HEAD in ${root}`)
+}
+
+// An unborn HEAD is either the repository `josh start` has yet to make its first commit in, or an
+// orphan branch (`git checkout --orphan`) whose index still holds another branch's files — told
+// apart by whether any ref reaches a commit.
+function has_history(root: string): boolean {
+	const output = start_exec.git_read(HISTORY_ARGUMENTS, root)
+
+	if (output === undefined) throw new Error(`git ${HISTORY_ARGUMENTS.join(' ')} failed in ${root}`)
+
+	return output.trim().length > 0
+}
+
+// What the tracked files are compared with, or undefined when there is nothing to tell the user's
+// work from — a directory outside any repository, or a repository without any commit.
+function tracked_arguments(root: string): ReadonlyArray<string> | undefined {
+	const state = head_state(root)
+
+	if (state === 'born') return MODIFIED_ARGUMENTS
+	if (state === 'unborn' && has_history(root)) return INDEXED_ARGUMENTS
+
+	return undefined
+}
+
+function uncommitted_paths(root: string): Array<string> {
+	const tracked = tracked_arguments(root)
+
+	if (tracked === undefined) return []
+
+	const untracked = strict_listing(UNTRACKED_ARGUMENTS, root)
+	const modified = strict_listing(tracked, root)
+
+	return [...untracked, ...modified]
+}
+
+// The refusal a setup command stops with before its first write, or undefined when nothing is
+// uncommitted: what kit then writes would land in the same files as the user's own work, and
+// `git diff` could no longer tell the two apart.
+function dirty_tree_refusal(root: string, command: string): string | undefined {
+	const paths = uncommitted_paths(root)
+
+	if (paths.length === 0) return undefined
+
+	return [
+		`${command} refuses to run: the working tree has uncommitted changes.`,
+		...paths.map((listed) => `  ${listed}`),
+		`Commit them, or stash them with \`git stash push -u -- .\`, then run ${command} again.`,
+	].join('\n')
+}
+
+const working_tree = { listing, changed_paths, uncommitted_paths, dirty_tree_refusal }
+
+export { working_tree }

package/scripts/issue/issue-auto-ok.ts

@@ -1,34 +1,30 @@
-import { git_branch } from '#scripts/git/git-branch'
-import { git_command } from '#scripts/git/git-command'
-import { run_carry } from '#scripts/run/carry/run-carry'
-import { issue_file } from './issue-file'
-import { AUTO_OK_LABEL, has_label_name, RELEASE_LABEL } from './issue-labels'
-import { issue_state_cli } from './issue-state-cli'
-
-// Whether `josh issue:file` applies `auto-ok` to the Issue it files. So that work found during an
-// unattended run does not wait in the backlog until a person labels it, the filing computes the
-// answer instead of leaving it to the agent's memory: an Issue filed while a
-// `backlogrun` carry record is live, or from a branch whose Issue carries `auto-ok`, is opted in by
-// default. `--no-auto-ok` is the one exception, declared for an Issue that needs a person's judgement
-// (a Tier B toss-up or a Tier C action). A filing to another repository is never opted in: that
-// repository's own `backlogrun` would implement and merge it though nobody opted that repository in.
-// A `release` Issue is never opted in either: a release is Tier C, so only a
-// person applies `auto-ok` to it, whatever the carry record or the branch's Issue says.
-// `--requested` withholds the default the same way: a person asked for this filing (a `new` entry, or
-// a request in conversation), so the run's own opt-in does not speak for them — `auto-ok` comes only
-// from their own `--label auto-ok`. A filing without the declaration — an observation, a
-// retrospective, a routed filing — keeps the default above.
-
-interface AutoOkSignals {
+import {
+	BREAKING_CHANGE_LABEL,
+	DEFERRED_LABEL,
+	EPIC_LABEL,
+	has_label_name,
+	NEEDS_HUMAN_REVIEW_LABEL,
+	RELEASE_LABEL,
+} from './issue-labels'
+import { markdown_section } from './markdown-section'
+
+// Whether `josh issue:file` applies `auto-ok` to the Issue it files, judged against the criteria
+// `docs/how-to/run-backlog.md` records rather than the context the filing happens in, so a filing a
+// person asked for (`kickoff new`) is judged the same as one an agent makes on its own. The answer is
+// a pure reading of the filing — its labels, its body and its target — so `backlogrun`'s judgement
+// of an Issue already open reuses `exclusion_of` rather than a second list (joshuafolkken/kit#3854).
+// The order: `--no-auto-ok`, a filing to another repository (whose own `backlogrun` would implement
+// and merge it though nobody opted that repository in), a label that keeps a person in the loop, and
+// last the body's judgement declaration (`JUDGEMENT_NEEDED` / `JUDGEMENT_NOT_NEEDED`): whether a
+// policy decision, an external account or a human visual check is needed.
+
+interface AutoOkFiling {
+	// `--no-auto-ok`: the filer declared the Issue needs a person's judgement.
 	is_opted_out: boolean
-	// `--requested`: a person asked for the filing, so neither the carry record nor the branch speaks.
-	is_requested: boolean
-	// The filing carries the `release` label.
-	is_release: boolean
-	is_carried: boolean
-	// The labels of the Issue the current branch names; `undefined` when the branch names none or the
-	// Issue could not be read.
-	branch_labels: ReadonlyArray<string> | undefined
+	is_cross_repository: boolean
+	// Every label the filing carries, including the ones the body's declarations add.
+	labels: ReadonlyArray<string>
+	body: string
 }
 
 interface AutoOkDecision {
@@ -36,98 +32,71 @@ interface AutoOkDecision {
 	reason: string
 }
 
+const BACKGROUND_HEADING = '## 背景'
+const JUDGEMENT_NOT_NEEDED = '- 人の判断: 不要'
+const JUDGEMENT_NEEDED = '- 人の判断: 要'
+const DECLARATION_PROBLEM = `declare under \`${BACKGROUND_HEADING}\` whether a person's judgement (a policy decision, an external account, a human visual check) is needed: \`${JUDGEMENT_NOT_NEEDED}\` or \`${JUDGEMENT_NEEDED}（<which one>）\` — exactly one (\`issue-template.md\`)`
+
 const OPTED_OUT: AutoOkDecision = { is_applied: false, reason: '--no-auto-ok declared' }
 const CROSS_REPOSITORY: AutoOkDecision = {
 	is_applied: false,
 	reason: 'the Issue is filed to another repository',
 }
-const RELEASE: AutoOkDecision = {
-	is_applied: false,
-	reason: `a ${RELEASE_LABEL} Issue is opted in by a person only`,
-}
-const REQUESTED: AutoOkDecision = {
+const JUDGEMENT: AutoOkDecision = {
 	is_applied: false,
-	reason: 'a person asked for this filing; auto-ok only when they declare it',
+	reason: `the body declares \`${JUDGEMENT_NEEDED}\``,
 }
-const CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
-const BRANCH_OPTED_IN: AutoOkDecision = {
+const APPLIED: AutoOkDecision = {
 	is_applied: true,
-	reason: 'the Issue this branch works on carries auto-ok',
-}
-const NOT_OPTED_IN: AutoOkDecision = {
-	is_applied: false,
-	reason: 'no backlogrun carry record is live and the branch names no auto-ok Issue',
-}
-
-// What the filing itself declares: `--no-auto-ok` and `--requested`.
-type AutoOkDeclared = Pick<AutoOkSignals, 'is_opted_out' | 'is_requested'>
-type Withholding = AutoOkDeclared & Pick<AutoOkSignals, 'is_release'>
-
-// The three signals that withhold `auto-ok` before any other is read, or `undefined` when none holds.
-function withheld(signals: Withholding): AutoOkDecision | undefined {
-	if (signals.is_opted_out) return OPTED_OUT
-	if (signals.is_release) return RELEASE
-	if (signals.is_requested) return REQUESTED
-
-	return undefined
+	reason: 'no exclusion holds and the body declares no judgement is needed',
 }
 
-// The opt-out, the `release` label and `--requested` win over every signal, then the carry record,
-// then the branch's Issue.
-function decide(signals: AutoOkSignals): AutoOkDecision {
-	const decision = withheld(signals)
+// The labels that keep a person in the loop, each with the reason it withholds `auto-ok`. A
+// `breaking-change` declared in the body arrives here as its label, added before the decision.
+const EXCLUDED_LABELS: ReadonlyArray<readonly [string, string]> = [
+	[RELEASE_LABEL, 'a release is Tier C'],
+	[BREAKING_CHANGE_LABEL, 'a breaking change needs a person to accept the migration'],
+	[DEFERRED_LABEL, 'the Issue is deferred'],
+	[NEEDS_HUMAN_REVIEW_LABEL, 'a person reviews the change before it lands'],
+	[EPIC_LABEL, 'an epic is opted in by a person, and that opts in every descendant'],
+]
 
-	if (decision !== undefined) return decision
-	if (signals.is_carried) return CARRIED
-	if (has_label_name(signals.branch_labels ?? [], AUTO_OK_LABEL)) return BRANCH_OPTED_IN
+// The first label that withholds `auto-ok`, or `undefined` when none of them is present.
+function exclusion_of(labels: ReadonlyArray<string>): AutoOkDecision | undefined {
+	const found = EXCLUDED_LABELS.find(([label]) => has_label_name(labels, label))
 
-	return NOT_OPTED_IN
-}
+	if (found === undefined) return undefined
 
-function line_of(decision: AutoOkDecision): string {
-	return `auto-ok: ${decision.is_applied ? 'applied' : 'not applied'} — ${decision.reason}`
+	return { is_applied: false, reason: `a \`${found[0]}\` Issue — ${found[1]}` }
 }
 
-// Read from the common git directory, so a lane sees the record its batch wrote in the main tree.
-async function is_carried(): Promise<boolean> {
-	const directory = await run_carry.repository_directory()
+// `true` / `false` for a declared need, `undefined` when the background declares neither or both.
+function judgement_of(body: string): boolean | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const lines = markdown_section.unfenced_lines(background).map((line) => line.trim())
+	const is_not_needed = lines.some((line) => line.startsWith(JUDGEMENT_NOT_NEEDED))
+	const is_needed = lines.some((line) => line.startsWith(JUDGEMENT_NEEDED))
 
-	if (directory === undefined) return false
-
-	return run_carry.read_carry(run_carry.carry_path(directory)).kind === 'carried'
+	return is_not_needed === is_needed ? undefined : is_needed
 }
 
-// An unreadable Issue is read as no labels: the filing goes on without `auto-ok` rather than failing.
-// The branch names an Issue of `current`, read there by name: a filing to another repository has
-// already pointed `GH_REPO` at its target, which would otherwise answer with the target's Issue.
-async function branch_labels(current: string): Promise<ReadonlyArray<string> | undefined> {
-	const issue_number = git_branch.issue_from_branch(await git_command.branch())
+// Why the filing is refused for its declaration, or `undefined` when it declares exactly one answer.
+function declaration_problem(body: string): string | undefined {
+	return judgement_of(body) === undefined ? DECLARATION_PROBLEM : undefined
+}
 
-	if (issue_number === undefined) return undefined
-	const read = await issue_state_cli.read_issue(String(issue_number), current)
+function decide(filing: AutoOkFiling): AutoOkDecision {
+	if (filing.is_opted_out) return OPTED_OUT
+	if (filing.is_cross_repository) return CROSS_REPOSITORY
 
-	return read.kind === 'state' ? read.state.labels : undefined
+	return exclusion_of(filing.labels) ?? (judgement_of(filing.body) === false ? APPLIED : JUDGEMENT)
 }
 
-// Each read is skipped once an earlier signal has already decided the answer; a cross-repository
-// filing is refused before any signal is read. `labels` are the ones the filing declares.
-async function resolve(
-	declared: AutoOkDeclared,
-	target: string,
-	current: string,
-	labels: ReadonlyArray<string> = [],
-): Promise<AutoOkDecision> {
-	const withholding = { ...declared, is_release: has_label_name(labels, RELEASE_LABEL) }
-	const decision = withheld(withholding)
-
-	if (decision !== undefined) return decision
-	if (!issue_file.is_same_repository(target, current)) return CROSS_REPOSITORY
-	if (await is_carried()) return CARRIED
-
-	return decide({ ...withholding, is_carried: false, branch_labels: await branch_labels(current) })
+function line_of(decision: AutoOkDecision): string {
+	return `auto-ok: ${decision.is_applied ? 'applied' : 'not applied'} — ${decision.reason}`
 }
 
-const issue_auto_ok = { decide, line_of, resolve }
+const issue_auto_ok = { declaration_problem, decide, exclusion_of, line_of }
 
-export type { AutoOkDeclared, AutoOkDecision, AutoOkSignals }
+export type { AutoOkDecision, AutoOkFiling }
 export { issue_auto_ok }

package/scripts/issue/issue-file-cli.ts

@@ -24,7 +24,7 @@ import { issue_scout_cli } from './issue-scout-cli'
 import { issue_wip } from './issue-wip'
 
 // `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
-// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]` — file an Issue
+// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]` — file an Issue
 // with every filing step run in order: the third-party refusal, the body
 // lint, the `## Origin` check for another repository, the `auto-ok` decision
 // with the run label it owes, the fold question against the run's earlier
@@ -37,7 +37,7 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
-	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]'
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
 const THIRD_PARTY_MESSAGE =
@@ -74,10 +74,13 @@ function is_third_party(target: string): boolean {
 // the filing may go on to the scout.
 function refusals_of(filing: Filing): ReadonlyArray<string> {
 	if (is_third_party(filing.target)) return [THIRD_PARTY_MESSAGE]
-	const problems = issue_lint_cli.problems(filing.body).map((problem) => `✖ ${problem}`)
-	const origin = issue_file.origin_problem(filing.body, filing.target, filing.current)
+	const problems = [
+		...issue_lint_cli.problems(filing.body),
+		issue_auto_ok.declaration_problem(filing.body),
+		issue_file.origin_problem(filing.body, filing.target, filing.current),
+	]
 
-	return origin === undefined ? problems : [...problems, `✖ ${origin}`]
+	return problems.filter((problem) => problem !== undefined).map((problem) => `✖ ${problem}`)
 }
 
 function unacknowledged_message(numbers: ReadonlyArray<number>): string {
@@ -143,18 +146,15 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 }
 
 // Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label.
-// Decided before the WIP count and the scout, so a refusal costs no listing.
-async function labels_of(filing: Filing): Promise<ReadonlyArray<string> | undefined> {
-	const declared = {
+// Decided before the WIP count and the scout, so a refusal costs no listing. The decision reads the
+// labels the body's declarations add, so a declared breaking change is excluded like its label.
+function labels_of(filing: Filing): ReadonlyArray<string> | undefined {
+	const auto_ok = issue_auto_ok.decide({
 		is_opted_out: filing.args.is_auto_ok_opted_out,
-		is_requested: filing.args.is_requested,
-	}
-	const auto_ok = await issue_auto_ok.resolve(
-		declared,
-		filing.target,
-		filing.current,
-		filing.args.labels,
-	)
+		is_cross_repository: !issue_file.is_same_repository(filing.target, filing.current),
+		labels: issue_file.labels_of(filing.args, filing.body),
+		body: filing.body,
+	})
 
 	console.info(issue_auto_ok.line_of(auto_ok))
 	const labels = issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied)
@@ -271,7 +271,7 @@ async function is_clear(filing: Filing): Promise<boolean> {
 
 async function file(filing: Filing): Promise<number> {
 	if (!is_admitted(filing)) return FAILURE_EXIT_CODE
-	const labels = await labels_of(filing)
+	const labels = labels_of(filing)
 
 	if (labels === undefined || !(await is_clear(filing))) return FAILURE_EXIT_CODE
 

package/scripts/issue/issue-file.ts

@@ -41,9 +41,6 @@ interface FileArguments {
 	is_over_cap: boolean
 	// `--no-auto-ok`: the Issue needs a person's judgement, so `auto-ok` is not applied (`issue-auto-ok.ts`).
 	is_auto_ok_opted_out: boolean
-	// `--requested`: a person asked for this filing, so `auto-ok` is applied only when a `--label` names
-	// it (`issue-auto-ok.ts`).
-	is_requested: boolean
 	// `--release`: the change reaches a consumer only once published, so the Issue is linked to the
 	// repository's release Issue as a blocker (`issue-release-cli.ts`).
 	is_release: boolean
@@ -58,7 +55,6 @@ const OPTIONS = {
 	distinct: { type: 'string', multiple: true },
 	'over-cap': { type: 'boolean' },
 	'no-auto-ok': { type: 'boolean' },
-	requested: { type: 'boolean' },
 	release: { type: 'boolean' },
 } as const
 
@@ -129,7 +125,6 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		repo: values.repo,
 		is_over_cap: values['over-cap'] === true,
 		is_auto_ok_opted_out: values['no-auto-ok'] === true,
-		is_requested: values.requested === true,
 		is_release: values.release === true,
 	}
 }
@@ -151,7 +146,7 @@ function is_undeclared_classification(label: string, body: string): boolean {
 
 // Every label the filing carries: the depth, the route when there is one, the classification labels
 // the body declares (`issue_classification.labels_for`, which merges case-insensitively), then any
-// extra `--label`, then `auto-ok` when the filing opted in (`issue-auto-ok.ts`) and no `--label`
+// extra `--label`, then `auto-ok` when the filing is judged in (`issue-auto-ok.ts`) and no `--label`
 // already named it. One request applies them all, so no label is a separate step to forget.
 function labels_of(args: FileArguments, body: string, is_auto_ok = false): ReadonlyArray<string> {
 	const extra = args.labels.filter((label) => !is_undeclared_classification(label, body))

package/scripts/issue/issue-labels.ts

@@ -67,9 +67,12 @@ const ALREADY_DONE_LABEL = 'already-done'
 // Marks the Issue that tracks a repository's next release. An Issue whose
 // change reaches a consumer only once published is linked to it as a `blocked_by` blocker
 // (`josh issue:release`), so "merged but not yet released" is visible in the backlog. A run applies
-// it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` refuses the default for it on every path,
-// since a release is Tier C — and only a person opts it into unattended execution.
+// it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` excludes it, since a release is Tier C —
+// and only a person opts it into unattended execution.
 const RELEASE_LABEL = 'release'
+// A person's mark for work set aside for now; `issue-auto-ok.ts` reads it as an exclusion. Applied by
+// hand and never provisioned, so it is not in `REPOSITORY_LABELS`.
+const DEFERRED_LABEL = 'deferred'
 // Applied to an Issue whose second review round was skipped, so the condition stays auditable
 // (`prompts/review.md` → "When round 2 is skipped entirely, and when it is not").
 const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
@@ -402,6 +405,7 @@ export {
 	BUG_LABEL,
 	BUGFIX_LABEL,
 	BREAKING_CHANGE_LABEL,
+	DEFERRED_LABEL,
 	depth_label_of,
 	DEPTH_0_LABEL,
 	DEPTH_1_LABEL,