@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/init/init-logic.ts

@@ -7,6 +7,7 @@ import { init_logic_json_merge } from './init-logic-json-merge'
 import { init_logic_secretlint } from './init-logic-secretlint'
 import { init_logic_sonar } from './init-logic-sonar'
 import { init_logic_templates } from './init-logic-templates'
+import { init_logic_toolchain } from './init-logic-toolchain'
 import { init_logic_workspace } from './init-logic-workspace'
 import { init_logic_yaml_merge } from './init-logic-yaml-merge'
 
@@ -417,6 +418,7 @@ const init_logic = {
 	...init_logic_sonar,
 	...init_logic_json_merge,
 	...init_logic_secretlint,
+	...init_logic_toolchain,
 	...init_logic_yaml_merge,
 	...init_logic_deploy_vps,
 	...distributed_paths,

package/scripts/init/init.ts

@@ -23,7 +23,6 @@ import { init_file_action } from './init-file-action'
 import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
-import { kit_development_versions } from './kit-development-versions'
 import { kit_setup_state } from './kit-setup-state'
 import { package_manager_pin } from './package-manager-pin'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
@@ -71,27 +70,8 @@ function get_kit_self_dependency(): Record<string, string> {
 	return { [KIT_PACKAGE_NAME]: version }
 }
 
-// Each config `init` generates runs a CLI or imports types the consumer has to resolve itself:
-// `cspell.config.yaml` → cspell, `playwright.config.ts` → @types/node, `lefthook.yml` → lefthook.
-// Prettier, its preset plugins and @playwright/test come in as peers. Without them the first
-// `josh gate` after `pnpm install` fails.
-const TOOL_DEVELOPMENT_DEPENDENCIES = ['cspell', '@types/node']
-const LEFTHOOK_DEVELOPMENT_DEPENDENCY = 'lefthook'
-
-function tool_dependency_names(has_git: boolean): ReadonlyArray<string> {
-	return has_git
-		? [...TOOL_DEVELOPMENT_DEPENDENCIES, LEFTHOOK_DEVELOPMENT_DEPENDENCY]
-		: TOOL_DEVELOPMENT_DEPENDENCIES
-}
-
-// Versions mirror kit's own devDependencies, so the consumer runs the toolchain kit is verified with.
-function get_toolchain_development_dependencies(has_git: boolean): Record<string, string> {
-	return kit_development_versions.versions_of([
-		...kit_development_versions.peer_names(),
-		...tool_dependency_names(has_git),
-	])
-}
-
+// Each config `init` generates runs a CLI or imports types the consumer has to resolve itself, so
+// the toolchain is added here: without it the first `josh gate` after `pnpm install` fails.
 function apply_dependency_merges(content: string, has_git = true): string {
 	const migrated = init_logic.strip_managed_postinstall(content)
 	const suggested = init_logic.get_suggested_scripts_for_content(migrated)
@@ -103,7 +83,7 @@ function apply_dependency_merges(content: string, has_git = true): string {
 	)
 	const with_toolchain = init_logic.merge_development_dependencies(
 		merged,
-		get_toolchain_development_dependencies(has_git),
+		init_logic.get_toolchain_development_dependencies(has_git),
 	)
 	const with_secretlint = init_logic.merge_secretlint_development_deps(with_toolchain)
 
@@ -147,6 +127,7 @@ function merged_manifest(existing: string, shape: ProjectShape): string {
 	return init_basic.with_recorded_profile(
 		apply_package_json_merges(existing, shape.has_git),
 		shape.profile,
+		shape.has_workflow,
 	)
 }
 
@@ -325,6 +306,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 const init = {
 	copy_ai_file: init_ai_copy.copy_ai_file,
 	apply_package_json_merges,
+	merged_manifest,
 	install_lefthook,
 	resolve_kit_package_manager,
 }

package/scripts/init/project-profile.ts

@@ -4,6 +4,8 @@ import { repo_origin } from '#scripts/discovery/repo-origin'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { kit_written_paths } from './kit-written-paths'
+import { workflow_mark } from './workflow-mark'
 
 type ProjectProfile = 'basic' | 'full'
 
@@ -17,6 +19,8 @@ interface ProjectShape extends ProfileResult {
 	has_typescript: boolean
 	has_git: boolean
 	has_github: boolean
+	// Set up by `josh start` for the GitHub Issue workflow (`workflow-mark.ts`).
+	has_workflow: boolean
 }
 
 const IGNORED_DIRECTORIES = new Set(['.git', 'node_modules', 'dist', 'build', '.svelte-kit'])
@@ -136,18 +140,27 @@ function scan_directory(directory: string, pending: Array<string>): Array<string
 			.map((entry) => path.join(directory, entry.name)),
 	)
 
-	return entries.filter((entry) => entry.isFile()).map((entry) => path.extname(entry.name))
+	return entries.filter((entry) => entry.isFile()).map((entry) => path.join(directory, entry.name))
+}
+
+// A file kit wrote says nothing about the project: counted, the `.pnpmfile.mjs` of the first
+// `josh init` would read as the user's Web file on the second and bring Prettier in
+// (joshuafolkken/kit#3713).
+function is_project_file(root: string, file: string): boolean {
+	const relative_path = path.relative(root, file).split(path.sep).join(path.posix.sep)
+
+	return !kit_written_paths.is_kit_written(relative_path)
 }
 
 function file_extensions(root: string): Array<string> {
 	const pending = [root]
-	const extensions: Array<string> = []
+	const files: Array<string> = []
 
 	for (const directory of pending) {
-		extensions.push(...scan_directory(directory, pending))
+		files.push(...scan_directory(directory, pending))
 	}
 
-	return extensions
+	return files.filter((file) => is_project_file(root, file)).map((file) => path.extname(file))
 }
 
 function scan_files(root: string): { has_web: boolean; has_typescript: boolean } {
@@ -164,17 +177,33 @@ function has_github_remote(root: string): boolean {
 	return url !== undefined && repo_origin.parse_origin_url(url) !== undefined
 }
 
+function has_git(root: string): boolean {
+	return existsSync(path.join(root, '.git'))
+}
+
+// The run is asked first, so a `josh start` whose setup has not written `package.json` yet reads it.
+function has_workflow(root: string): boolean {
+	return workflow_mark.is_requested() || workflow_mark.is_recorded(read_manifest(root))
+}
+
 function inspect_project(root: string, requested?: ProjectProfile): ProjectShape {
 	const profile = resolve_profile(root, requested)
 	const files = scan_files(root)
-	const has_git = existsSync(path.join(root, '.git'))
-
-	return { ...profile, ...files, has_git, has_github: has_git && has_github_remote(root) }
+	const is_git = has_git(root)
+
+	return {
+		...profile,
+		...files,
+		has_git: is_git,
+		has_github: is_git && has_github_remote(root),
+		has_workflow: has_workflow(root),
+	}
 }
 
 const project_profile = {
 	parse_profile,
 	resolve_profile,
+	has_git,
 	inspect_project,
 	requested_profile,
 	with_legacy_profile_names,

package/scripts/init/start-exec.ts

@@ -1,6 +1,6 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_location_environment } from '#scripts/git/git-location-environment'
-import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { git_spawn_sync, type GitSyncOptions } from '#scripts/git/git-spawn-sync'
 import { COMMAND_TIMEOUT_MS, SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import type { Visibility } from './start-plan'
@@ -16,6 +16,8 @@ import type { Visibility } from './start-plan'
 // project's own commit and push hooks, which may run its whole suite, so it takes the suite budget:
 // long enough for that, short enough that a push that never answers ends the run.
 const SUCCESS_EXIT_CODE = 0
+const GIT_DIRECTORY = '.git'
+const IDENTITY_VARIABLES = ['GIT_AUTHOR_IDENT', 'GIT_COMMITTER_IDENT']
 
 function root_environment(): Record<string, string | undefined> {
 	return git_location_environment.location_free_environment()
@@ -29,6 +31,29 @@ function git_read(args: ReadonlyArray<string>, root: string): string | undefined
 	return git_spawn_sync.read(args, { cwd: root, env: root_environment() })
 }
 
+// Asked of git itself, so the answer is the one its commit would reach: config, the environment and
+// the identity git can detect all count (#3754).
+//
+// **Only an answer from git counts as a missing identity.** A git that could not be started or never
+// answered is a different failure, which the first step that runs git reports as what it is.
+function is_identity_refused(variable: string, options: GitSyncOptions): boolean {
+	const { exit_code } = git_spawn_sync.run(['var', variable], options)
+
+	return exit_code !== undefined && exit_code !== SUCCESS_EXIT_CODE
+}
+
+// A plan that creates the repository asks from where it will be: an identity given per directory
+// (`includeIf "gitdir:…"`) is matched against the git directory, which no `cwd` supplies before
+// `git init` has run. The path stays relative to `root` so git resolves it as its commit will — by
+// the path the user reached the directory through as well as the physical one, which is what a
+// `gitdir:` under a symlinked parent is written against.
+function lacks_git_identity(root: string, is_new_repository: boolean): boolean {
+	const location = is_new_repository ? { GIT_DIR: GIT_DIRECTORY } : {}
+	const options = { cwd: root, env: { ...root_environment(), ...location } }
+
+	return IDENTITY_VARIABLES.some((variable) => is_identity_refused(variable, options))
+}
+
 function git_run(args: ReadonlyArray<string>, root: string): void {
 	const options = { cwd: root, env: root_environment(), timeout: SUITE_TIMEOUT_MS }
 	const { exit_code } = git_spawn_sync.run(args, { ...options, stdio: 'inherit' })
@@ -86,6 +111,7 @@ const start_exec = {
 	git_succeeds,
 	git_read,
 	git_run,
+	lacks_git_identity,
 	is_gh_installed,
 	is_gh_signed_in,
 	create_github_repository,

package/scripts/init/start-plan.ts

@@ -58,6 +58,9 @@ const STEP_LABELS: Readonly<Record<StartStep, string>> = {
 // so they are also the steps a caller's push preflight guards (#3702).
 const GITHUB_WRITE_STEPS: ReadonlySet<StartStep> = new Set(['repository', 'setup_pr'])
 
+// The steps that create a commit, which git refuses without an author identity (#3754).
+const COMMIT_STEPS: ReadonlySet<StartStep> = new Set(['commit', 'setup_pr'])
+
 function refused(refusal: string): StepPlan {
 	return { steps: [], refusal }
 }
@@ -113,6 +116,10 @@ function has_push(steps: ReadonlyArray<StartStep>): boolean {
 	return steps.some((step) => GITHUB_WRITE_STEPS.has(step))
 }
 
+function has_commit(steps: ReadonlyArray<StartStep>): boolean {
+	return steps.some((step) => COMMIT_STEPS.has(step))
+}
+
 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 }
@@ -167,6 +174,12 @@ function preflight_report(command: string, cause: string): string {
 	return `josh start stopped before its first step: the push preflight (${command}) failed. Nothing was changed.\nCause: ${cause}`
 }
 
+// What a run prints when the scanner the pre-push audit needs could not be put in place: every push
+// the plan makes would be refused by that hook, so it stops while nothing has changed (#3755).
+function scanner_report(cause: string): string {
+	return `josh start stopped before its first step: osv-scanner, which the pre-push audit needs, is not installed and could not be fetched. Nothing was changed.\nCause: ${cause}\nInstall osv-scanner (https://google.github.io/osv-scanner/) or restore the network, then run josh start again.`
+}
+
 function plan_summary(
 	steps: ReadonlyArray<StartStep>,
 	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
@@ -179,10 +192,12 @@ function plan_summary(
 const start_plan = {
 	plan_steps,
 	has_push,
+	has_commit,
 	interaction_of,
 	github_consent,
 	progress_report,
 	preflight_report,
+	scanner_report,
 	plan_summary,
 	step_labels,
 	STEP_LABELS,

package/scripts/init/start-steps.ts

@@ -2,6 +2,8 @@ import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { error_text } from '#scripts/lib/error-message'
 import { repository_labels } from '#scripts/repo/repository-labels'
+import { security_audit } from '#scripts/security/security-audit'
+import { security_audit_provision } from '#scripts/security/security-audit-provision'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { parseCommandString } from 'execa'
 import { main as init_main } from './init'
@@ -12,6 +14,7 @@ import type { ProjectProfile, ProjectShape } from './project-profile'
 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'
 
 interface StepContext {
 	root: string
@@ -29,6 +32,12 @@ 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 =
 	'GitHub CLI is not signed in. Run gh auth login, then run josh start again. Nothing was changed.'
+const GIT_IDENTITY_HINT =
+	'Git has no author identity, which the commit josh start creates needs. Run git config --global user.name "Your Name" and git config --global user.email "you@example.com", then run josh start again. Nothing was changed.'
+// Printed before the scanner is looked for: a first run downloads tens of megabytes, and a terminal
+// that says nothing for minutes reads as a hang the user interrupts (#3755).
+const SCANNER_NOTICE =
+	'Checking for osv-scanner, which the pre-push audit needs. A first run downloads it, which can take a few minutes on a slow connection.'
 
 const { git_succeeds, git_read, run_local } = start_exec
 
@@ -63,6 +72,17 @@ function github_cli_refusal(root: string): string | undefined {
 	return undefined
 }
 
+// A machine Git was just installed on has no author identity, and the commit that needs one comes
+// after the repository and kit's files are written. It is asked for before the first write, and only
+// when the plan commits — a re-run with nothing left to commit is not stopped by it (#3754).
+function git_identity_refusal(steps: ReadonlyArray<StartStep>, root: string): string | undefined {
+	if (!start_plan.has_commit(steps)) return undefined
+
+	return start_exec.lacks_git_identity(root, steps.includes('git_init'))
+		? GIT_IDENTITY_HINT
+		: undefined
+}
+
 // `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.
@@ -85,7 +105,10 @@ function create_git_repository(context: StepContext): void {
 // 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.
+// Either one is told the project is set up for the GitHub Issue workflow (`workflow-mark.ts`).
 function initialize(context: StepContext): void {
+	workflow_mark.request()
+
 	if (context.init_command === undefined) {
 		init_main(['--profile', context.profile])
 
@@ -148,6 +171,27 @@ function run_push_preflight(steps: ReadonlyArray<StartStep>, context: StepContex
 	}
 }
 
+// The `full` profile installs kit's pre-push hook, whose audit refuses a push without osv-scanner. The
+// scanner is otherwise fetched at an agent's session start, which a first `josh start` from a terminal
+// has not had, so it is fetched here — forced, because a person asked for this run. A scanner that
+// still cannot be found stops the run before the first step rather than at the push (#3755).
+async function ensure_audit_scanner(
+	steps: ReadonlyArray<StartStep>,
+	context: StepContext,
+): Promise<void> {
+	if (context.profile !== 'full' || !start_plan.has_push(steps)) return
+
+	const { platform, arch } = process
+
+	console.info(`\n${SCANNER_NOTICE}`)
+	const outcome = await security_audit_provision.report(context.root, platform, arch, true)
+
+	console.info(outcome)
+	if (security_audit.resolve_scanner(context.root, platform) !== undefined) return
+
+	throw new Error(start_plan.scanner_report(outcome))
+}
+
 type StepAction = (context: RunContext) => void | Promise<void>
 
 const STEP_ACTIONS: Readonly<Record<StartStep, StepAction>> = {
@@ -178,6 +222,7 @@ async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext):
 	const labels = start_plan.step_labels(context.init_command)
 
 	run_push_preflight(steps, context)
+	await ensure_audit_scanner(steps, context)
 	const run_context: RunContext = { ...context, baseline: baseline_of(steps, context) }
 
 	for (const [index, step] of steps.entries()) {
@@ -192,6 +237,7 @@ async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext):
 const start_steps = {
 	read_git_state,
 	github_cli_refusal,
+	git_identity_refusal,
 	self_run_refusal,
 	run_steps,
 }

package/scripts/init/start.ts

@@ -106,6 +106,7 @@ function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Pr
 	const consent: Consent = settle(start_plan.github_consent(plan.steps, options, interaction))
 
 	stop_on(start_steps.github_cli_refusal(root))
+	stop_on(start_steps.git_identity_refusal(plan.steps, root))
 
 	return {
 		steps: plan.steps,

package/scripts/init/workflow-mark.ts

@@ -0,0 +1,35 @@
+import { json_value } from '#scripts/lib/json-value'
+
+// `josh start` sets a project up for the GitHub Issue workflow and `josh init` alone does not. The
+// difference decides whether a `basic` project receives `.claude/settings.json`, whose permissions,
+// hooks and plugin an unattended `backlogrun` agent runs on (#3796).
+//
+// `josh start` hands the mark to the setup it runs through this variable, not an argument: that setup
+// may be the project's own kit it hands off to or a toolkit's command (`--init-command`), and an older
+// one refuses an argument it does not know but ignores a variable. The setup records the mark in
+// `package.json`, where every later `josh init` and `josh sync` reads it.
+const WORKFLOW_ENV = 'JOSH_WORKFLOW'
+const GITHUB_WORKFLOW = 'github'
+
+function is_requested(environment: NodeJS.ProcessEnv = process.env): boolean {
+	return environment[WORKFLOW_ENV] === GITHUB_WORKFLOW
+}
+
+function is_recorded(manifest: Record<string, unknown> | undefined): boolean {
+	const josh = manifest?.['josh']
+
+	return json_value.is_record(josh) && josh['workflow'] === GITHUB_WORKFLOW
+}
+
+function request(environment: NodeJS.ProcessEnv = process.env): void {
+	environment[WORKFLOW_ENV] = GITHUB_WORKFLOW
+}
+
+// The `josh` record's field for the mark — none for a project `josh start` did not set up, so a
+// `josh init` never writes the mark of its own accord.
+function recorded_fields(has_workflow: boolean): Record<string, string> {
+	return has_workflow ? { workflow: GITHUB_WORKFLOW } : {}
+}
+
+const workflow_mark = { is_requested, is_recorded, request, recorded_fields }
+export { workflow_mark }

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { issue_watch, type Acknowledged } from './issue-watch'
+
+// `josh issue:ack <N>` — record that the run has read a person's update to its issue, so the hook,
+// the review attestation and `josh followup` stop raising it. It prints the update it acknowledges:
+// the same read becomes the new baseline (`issue-watch.ts` → `acknowledge`), so nothing that arrived
+// after the hook spoke can be acknowledged without being printed here.
+//
+// **The number is asked for, though the record already carries it**, so an acknowledgement typed for
+// one issue cannot silently clear the watch on another.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh issue:ack <issue-number>'
+const NO_WATCH_LINE =
+	'No run recorded a baseline for that issue in this checkout (`josh run:entry` writes it), or the issue could not be read — nothing was acknowledged.'
+const NOTHING_NEW_LINE = 'No person has updated the issue since the run last read it.'
+
+function parse_number(argv: ReadonlyArray<string>): string | undefined {
+	const [first] = argv
+
+	if (first === undefined || argv.length !== 1) return undefined
+
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(first) ? first : undefined
+}
+
+function report(acknowledged: Acknowledged): void {
+	const heading = `Acknowledged issue ${session_cite.issue(acknowledged.issue)}.`
+
+	console.info(
+		acknowledged.diff === undefined
+			? `${heading} ${NOTHING_NEW_LINE}`
+			: `${heading}\n\n${acknowledged.diff}`,
+	)
+}
+
+async function acknowledge(issue_number: string): Promise<number> {
+	const root = await git_command.repository_root()
+
+	if (issue_watch.read_record(root)?.issue !== issue_number) {
+		console.error(NO_WATCH_LINE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const acknowledged = await issue_watch.acknowledge(root)
+
+	if (acknowledged === undefined) {
+		console.error(NO_WATCH_LINE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	report(acknowledged)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = parse_number(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await acknowledge(issue_number)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_ack_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_ack_cli }

package/scripts/issue/issue-labels.ts

@@ -70,6 +70,9 @@ const ALREADY_DONE_LABEL = 'already-done'
 // 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.
 const RELEASE_LABEL = 'release'
+// 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'
 
 // The four labels that mean an open issue must not be handed to a run as it stands: an `epic`
 // tracks a batch and is never run directly (its children are), `in-progress` is already claimed by
@@ -205,8 +208,11 @@ interface LabelDefinition {
 }
 
 // What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
-// applies with its intended color. The `epic` and `in-progress` metadata is
-// the one the workflow documents create them with; the labels only a person applies are left out.
+// applies with its intended color. The metadata is the one the workflow documents create each label
+// with. **The labels only a person applies are provisioned too**: a person cannot apply a label the
+// repository does not have, so leaving one out made the first `auto-ok` a manual creation step.
+// `bug` is GitHub's default label, kept because `issue:file` applies it to a bug fix and a
+// repository may have been created without the defaults.
 const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 	{
 		name: EPIC_LABEL,
@@ -235,6 +241,32 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: 'fef2c0',
 		description: 'Tracks the next release; its blockers are the merged work it publishes',
 	},
+	{
+		name: AUTO_OK_LABEL,
+		color: '0e8a16',
+		description: 'Opted in to unattended execution outside an epic',
+	},
+	{
+		name: NEEDS_DECISION_LABEL,
+		color: 'd93f0b',
+		description: 'Parked: needs a decision before it can run',
+	},
+	{
+		name: NEEDS_HUMAN_REVIEW_LABEL,
+		color: 'd93f0b',
+		description: 'Implement and verify, but stop before committing so a person can look',
+	},
+	{
+		name: ALREADY_DONE_LABEL,
+		color: '6f42c1',
+		description: 'Verified already merged — a person closes it',
+	},
+	{
+		name: REVIEW_ROUND2_SKIPPED_LABEL,
+		color: 'c5def5',
+		description: 'Review round 2 was skipped under the condition in prompts/review.md',
+	},
+	{ name: BUG_LABEL, color: 'd73a4a', description: "Something isn't working" },
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -329,12 +361,6 @@ function depth_label_of(labels: ReadonlyArray<LabelReference> | undefined): stri
 // document operates on a label name that does not exist here — a stale or mistyped `labels[]=…`
 // otherwise fails silently at run time. One source, so a label added above joins the scan without a
 // second edit.
-// 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"). Provisioned inline
-// by the run that applies it rather than through `FILING_ROUTE_LABELS`, but still a managed label the
-// documents operate on, so the label-reference scan has to know it.
-const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
-
 const ALL_LABELS: ReadonlySet<string> = new Set([
 	EPIC_LABEL,
 	BUG_LABEL,
@@ -363,6 +389,11 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	IGNORE_FOR_RELEASE_LABEL,
 ])
 
+// The managed labels `REPOSITORY_LABELS` deliberately does not provision, each with its reason. Every
+// other member of `ALL_LABELS` is provisioned — `issue-labels.test.ts` fails on one that is in
+// neither list, so a label added above cannot silently become one a repository lacks. Empty today.
+const EXEMPT_FROM_PROVISIONING: ReadonlyMap<string, string> = new Map<string, string>()
+
 export type { LabelDefinition, ReleaseClassification }
 export {
 	ALL_LABELS,
@@ -379,6 +410,7 @@ export {
 	DEPTH_LABELS,
 	ENHANCEMENT_LABEL,
 	EPIC_LABEL,
+	EXEMPT_FROM_PROVISIONING,
 	FILING_ROUTE_LABELS,
 	has_any_label,
 	has_label_name,

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

@@ -1,10 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { IssueReadReason } from '#scripts/gh/git-gh-issue-read'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
+import { issue_report_failures } from './issue-report-failures'
 import { issue_state, type IssueState } from './issue-state'
 
 // `josh issue:state <N> [<N> ...]` — print each issue's state and labels, in the spelling the
@@ -50,7 +51,14 @@ interface StateRequest {
 // One issue's state, or the failure kind. Named for export because `run:prep` reads the state beside
 // the body and the dependency-update scope, reusing this read rather than a
 // second one that would drift from the `human_review` decision `parse_issue_state` owns.
-type StateRead = { kind: 'state'; state: IssueState } | { kind: ReadFailureKind }
+//
+// **Why a read failed rides along where the request said it**: `backlog:drive` names the reason when it
+// hands an unreadable named issue back. Both are optional, so a caller that only separates the kinds
+// needs no edit.
+type StateRead =
+	| { kind: 'state'; state: IssueState }
+	| { kind: 'missing' }
+	| { kind: 'unreadable'; reason?: IssueReadReason | undefined; status?: number | undefined }
 
 interface IssueReport {
 	issue_number: string
@@ -102,11 +110,13 @@ function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
 async function read_issue(issue_number: string, repo?: string): Promise<StateRead> {
 	const read = await git_gh_command.issue_view_json_classified(issue_number, STATE_FIELDS, repo)
 
-	if (read.kind !== 'read') return { kind: read.kind }
+	if (read.kind !== 'read') return read
 
 	const parsed = issue_state.parse_issue_state(read.json)
 
-	return parsed === undefined ? { kind: 'unreadable' } : { kind: 'state', state: parsed }
+	return parsed === undefined
+		? { kind: 'unreadable', reason: 'malformed' }
+		: { kind: 'state', state: parsed }
 }
 
 // Through the shared pool rather than a raw `Promise.all`: each read spawns a `gh` process, and a