@joshuafolkken/kit 1.1136.0 → 1.1178.0

package/scripts/git/main-merge.ts

@@ -44,44 +44,79 @@ function merge_message(default_branch: string, current_branch: string): string |
 	return `Merge ${default_branch} into ${current_branch} #${issue_number}`
 }
 
-// The refusal is read after the fetch, so the incoming paths are the ones the merge would bring in
-// (joshuafolkken/kit#2445).
-async function merge_refusal(default_branch: string): Promise<string | undefined> {
-	const status = await git_command.status()
-	const incoming = await main_merge_guard.incoming_paths(default_branch)
-
-	return main_merge_guard.refusal(status, incoming, default_branch)
+// What one merge of the default branch came to (joshuafolkken/kit#3221). `josh ship` merges it again
+// before the commit and on a conflicting pull request, and branches on the answer rather than on an
+// exit code: `current` brought nothing in, so the tree is unchanged; `merged` changed it; `refused`
+// is the guard's answer, nothing attempted; `conflict` names the paths git left unmerged, so a resumed
+// session goes straight to them instead of asking git again.
+type MergeOutcome =
+	| { kind: 'current'; branch: string }
+	| { kind: 'merged'; branch: string }
+	| { kind: 'refused'; message: string }
+	| { kind: 'conflict'; files: ReadonlyArray<string> }
+
+interface MergeTarget {
+	default_branch: string
+	current_branch: string
+	is_current: boolean
 }
 
-// A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
-// the sanctioned commit rather than a request for `git add`.
-async function merge_with_hint(default_branch: string, message: string | undefined): Promise<void> {
+// A failure that left no unmerged path — a remote that cannot be reached, a hook that refused — is not
+// a conflict, so it is rethrown rather than reported as one with nothing to resolve.
+async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
+	const { default_branch, current_branch } = target
+
 	try {
-		await git_command.merge_branch(default_branch, message)
+		await git_command.merge_branch(default_branch, merge_message(default_branch, current_branch))
 	} catch (error) {
-		console.error(main_merge_guard.CONFLICT_HINT)
-		throw error
+		const files = main_merge_guard.unmerged_paths(await git_command.status())
+
+		if (files.length === 0) throw error
+
+		return { kind: 'conflict', files }
 	}
+
+	return { kind: target.is_current ? 'current' : 'merged', branch: default_branch }
 }
 
 // The fetch is what makes `origin/<default>` current before the merge reads it. `git pull` did the
-// two together, which is the only thing it was doing here that is worth keeping.
-async function merge_default_branch(): Promise<number> {
+// two together, which is the only thing it was doing here that is worth keeping. The refusal is read
+// after the fetch, so the incoming paths are the ones the merge would bring in (joshuafolkken/kit#2445).
+async function merge(): Promise<MergeOutcome> {
 	const default_branch = await git_command.get_default_branch()
 	const current_branch = await git_command.branch()
 
 	await git_command.fetch_branch(default_branch)
 
-	const refusal = await merge_refusal(default_branch)
+	const status = await git_command.status()
+	const incoming = await main_merge_guard.incoming_paths(default_branch)
+	const message = main_merge_guard.refusal(status, incoming, default_branch)
+
+	if (message !== undefined) return { kind: 'refused', message }
+
+	return await merge_into({ default_branch, current_branch, is_current: incoming.length === 0 })
+}
+
+// A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
+// the sanctioned commit rather than a request for `git add`.
+function failure_text(outcome: MergeOutcome): string | undefined {
+	if (outcome.kind === 'refused') return outcome.message
+	if (outcome.kind === 'conflict') return main_merge_guard.CONFLICT_HINT
+
+	return undefined
+}
+
+async function merge_default_branch(): Promise<number> {
+	const outcome = await merge()
+	const failure = failure_text(outcome)
 
-	if (refusal !== undefined) {
-		console.error(refusal)
+	if (failure !== undefined) {
+		console.error(failure)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	await merge_with_hint(default_branch, merge_message(default_branch, current_branch))
-	console.info(default_branch)
+	if ('branch' in outcome) console.info(outcome.branch)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -114,8 +149,9 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const main_merge = { run }
+const main_merge = { merge, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
 export { main_merge }
+export type { MergeOutcome }

package/scripts/git/schemas.ts

@@ -140,6 +140,8 @@ const open_issue_schema = z.object({
 	labels: z.array(issue_label_schema).optional(),
 	createdAt: z.string(),
 	blockedBy: blocked_by_schema,
+	// Present only on the pickup listing, which reads it for the restructures each issue declares.
+	body: z.string().optional(),
 })
 
 type RollupItemData = z.infer<typeof rollup_item_schema>

package/scripts/hooks/pretool-guard-cli.ts

@@ -2,7 +2,7 @@
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
-import { pretool_outcome_async } from './pretool-guard'
+import { pretool_guard, pretool_outcome_async } from './pretool-guard'
 
 // The `PreToolUse` hook's entry, kept apart from the composition in `pretool-guard.ts`
 // (joshuafolkken/kit#2922). The hook bundles are built with `splitting: true`, which moves a module
@@ -16,6 +16,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 		const raw_payload = await text(process.stdin)
 
 		hook_decision.load_environment_file()
-		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
+		pretool_guard.emit(raw_payload, await pretool_outcome_async(raw_payload))
 	}
 }

package/scripts/hooks/pretool-guard.ts

@@ -1,9 +1,11 @@
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
-import type { GuardOutcome } from '#scripts/josh/hook-decision'
+import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { lane_background } from '#scripts/rules/lane-background'
 import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { batch_outcome } from './batch-guard'
 import { step_zero_notice } from './step-zero-notice'
 
@@ -108,6 +110,47 @@ async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome>
 	return with_step_zero_notice(base, raw_payload)
 }
 
-const pretool_guard = { combine_outcomes, pretool_outcome }
+function guarded_call(raw_payload: string): GuardedCall | undefined {
+	try {
+		const payload = hook_decision.parse_hook_payload(raw_payload)
+
+		return payload === undefined
+			? undefined
+			: { name: payload.tool_name, input: payload.tool_input }
+	} catch {
+		return undefined
+	}
+}
+
+// The envelope that replaces the outcome's own when a lane child backgrounded `josh ship` alone
+// (joshuafolkken/kit#3154): the call is run in the foreground instead of being refused. A refusal from
+// any guard still wins, and a notice the outcome carried rides along in the same context.
+function foreground_rewrite(
+	outcome: GuardOutcome,
+	raw_payload: string,
+	is_lane_child?: () => boolean,
+): string | undefined {
+	if (outcome.reason !== undefined) return undefined
+
+	const call = guarded_call(raw_payload)
+	const input =
+		call === undefined ? undefined : lane_background.foreground_input(call, is_lane_child)
+
+	if (input === undefined) return undefined
+
+	const context = [lane_background.FOREGROUND_NOTE, outcome.notice ?? outcome.fault]
+
+	return hook_decision.rewrite_envelope(input, context.filter(Boolean).join('\n\n'))
+}
+
+// The hook's one write: the foreground rewrite where it applies, the outcome's own envelope otherwise.
+function emit(raw_payload: string, outcome: GuardOutcome): void {
+	const rewrite = foreground_rewrite(outcome, raw_payload)
+
+	if (rewrite === undefined) hook_decision.emit_outcome(outcome)
+	else process.stdout.write(`${rewrite}\n`)
+}
+
+const pretool_guard = { combine_outcomes, emit, foreground_rewrite, pretool_outcome }
 
 export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/hooks/run-hook.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Launch one kit hook by name: `sh scripts/hooks/run-hook.sh <name> [arguments...]`
+# (joshuafolkken/kit#3184).
+#
+# A hook command in `.claude/settings.json` / `.codex/hooks.json` only moves to the project root
+# (`scripts/init/hook-launch.ts`) and calls this script, so everything every hook shares lives here once:
+#
+# - The git location variables a git hook exports are cleared when the root resolves without them, so
+#   the hook's own git calls act on the checkout it stands in. They are kept when the checkout needs
+#   them — git metadata outside the work tree.
+# - The pre-built bundle `dist/hooks/<name>.js` runs once its gate passes; otherwise the live source
+#   runs through josh, whose command is the name with its first `-` turned into `:`
+#   (`pretool-guard` → `pretool:guard`).
+# - In kit's own checkout the gate is `hook-bundle-ready.ts`, which rebuilds stale bundles
+#   (joshuafolkken/kit#2984). In an installed package it is a presence check: the published bundles
+#   cannot be stale against a source the consumer never edits, and Node strips no types under
+#   `node_modules`.
+# - An `if`/`else`, never `&&`/`||`: a guard's refusal is a non-zero exit, and a chain would read it as
+#   a missing bundle and run the hook twice.
+
+location_variables='GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
+unset_options=''
+for variable in $location_variables; do unset_options="$unset_options -u $variable"; done
+# shellcheck disable=SC2086
+if env $unset_options git rev-parse --show-toplevel >/dev/null 2>&1; then unset $location_variables; fi
+
+hook_name=$1
+shift
+hooks_dir=$(dirname "$0")
+package_dir="$hooks_dir/../.."
+bundle="$package_dir/dist/hooks/$hook_name.js"
+josh_command="${hook_name%%-*}:${hook_name#*-}"
+
+case $0 in
+*node_modules/*)
+	if [ -d "$package_dir/dist/hooks" ]; then node "$bundle" "$@"; else node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
+	;;
+*)
+	if node --disable-warning=ExperimentalWarning "$hooks_dir/hook-bundle-ready.ts"; then node "$bundle" "$@"; else pnpm josh "$josh_command" "$@"; fi
+	;;
+esac

package/scripts/init/hook-command-rewrite.ts

@@ -3,60 +3,43 @@ import { hook_launch } from './hook-launch'
 
 // The consumer's `.claude/settings.json` runs its hooks off the published package directly, not
 // through `pnpm josh` (joshuafolkken/kit#1930, joshuafolkken/kit#2023). Two paths inside a hook
-// command are rebased onto the installed package: the per-hook bundle `dist/hooks/<name>.js` a hook
-// prefers, and the `pnpm josh <command>` fallback it drops to when that bundle is missing — which for
-// a consumer becomes the `dist/josh.js` dispatcher, since the published package always ships `dist`
-// and a `pnpm` launch would only add the wrapper this exists to remove.
+// command are rebased onto the installed package: the hook launcher `scripts/hooks/run-hook.sh`
+// (joshuafolkken/kit#3184), which picks the bundle or the dispatcher from where it is installed, and a
+// plain `pnpm josh <command>`, which becomes the `dist/josh.js` dispatcher — the published package
+// always ships `dist`, and a `pnpm` launch would only add the wrapper this exists to remove.
 //
-// kit's own settings file keeps the `pnpm josh` fallback (`tsx scripts/josh/josh.ts` against live
-// source), so a fresh clone with no `dist/` still runs the current guards. The rewrite is gated on the
-// copy destination, exactly as the plugin injection is — kit's source tree is never transformed in
-// place.
+// kit's own settings file keeps the launcher's live-source fallback (`pnpm josh` against
+// `scripts/josh/josh.ts`), so a fresh clone with no `dist/` still runs the current guards. The rewrite
+// is gated on the copy destination, exactly as the plugin injection is — kit's source tree is never
+// transformed in place.
 
 const PNPM_JOSH_PREFIX = 'pnpm josh '
-const CODEX_ADAPTER_SOURCE = 'pnpm exec tsx scripts/hooks/codex-hook-adapter.ts'
 // Relative to the consumer's project root, which hook commands select before using this path.
 // The path is the plugin marketplace's `node_modules` location plus the built entry `bin.josh` names.
 const BUNDLE_INVOCATION = `node ${claude_plugin_config.MARKETPLACE_PATH}/dist/josh.js `
-// The per-hook bundle directory a fresh clone builds, and where it lives inside the installed package.
-const HOOK_BUNDLE_DIR = `${hook_launch.HOOK_DIST_DIR}/`
-const CONSUMER_HOOK_BUNDLE_DIR = `${claude_plugin_config.MARKETPLACE_PATH}/${HOOK_BUNDLE_DIR}`
+// Anchored on the `sh ` that launches it: the installed path still ends in the source path, so only the
+// anchor keeps a second pass from rebasing an already-rebased launcher onto itself.
+const RUN_HOOK_INVOCATION = `sh ${hook_launch.RUN_HOOK_SCRIPT} `
+const CONSUMER_RUN_HOOK_INVOCATION = `sh ${claude_plugin_config.MARKETPLACE_PATH}/${hook_launch.RUN_HOOK_SCRIPT} `
 const CONSUMER_PACKAGE_MANIFEST = `${claude_plugin_config.MARKETPLACE_PATH}/package.json`
 const MISSING_INSTALL_NOTICE = 'kit hooks inactive: run pnpm install, then reread CLAUDE.md'
 const MISSING_INSTALL_GUARD = `if [ ! -f ${CONSUMER_PACKAGE_MANIFEST} ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
-const CODEX_ADAPTER_BUNDLE = `node ${CONSUMER_HOOK_BUNDLE_DIR}codex-hook-adapter.js`
 const CODEX_HOOKS_DESTINATION = '.codex/hooks.json'
 // The values below are matched inside raw JSON text, so the root prefix is taken in its escaped form.
 const PROJECT_ROOT_PREFIX = JSON.stringify(hook_launch.PROJECT_ROOT_PREFIX).slice(1, -1)
-// The installed package ships its bundles built, so they cannot be stale against a source the consumer
-// never has: the ready gate kit's own commands pass (joshuafolkken/kit#2984) becomes a presence check.
-const CONSUMER_READY_GATE = `[ -d ${CONSUMER_HOOK_BUNDLE_DIR} ]`
 // Capture the value of every `"command"` field, escapes and all, so the rewrites below touch command
 // values alone — never an echo reminder's prose or a `"description"` that merely mentions the string.
 const COMMAND_FIELD = /("command":\s*")((?:[^"\\]|\\.)*)(")/gu
 
-// Idempotent on its own: `CONSUMER_HOOK_BUNDLE_DIR` still contains `HOOK_BUNDLE_DIR`, so a blind
-// second pass would rebase an already-rebased path onto itself. A value already targeting the
-// installed package is left untouched, restoring the idempotency the earlier `pnpm josh`-anchored
-// rewrite had for free.
-function rebase_bundle_directory(value: string): string {
-	return value.includes(CONSUMER_HOOK_BUNDLE_DIR)
-		? value
-		: value.split(HOOK_BUNDLE_DIR).join(CONSUMER_HOOK_BUNDLE_DIR)
-}
-
-// Rebase both paths a hook command can carry: the bundle it prefers, then the `pnpm josh` fallback.
-// The bundle rewrite runs first — its replacement never contains `pnpm josh`, so the two are
-// independent whichever order they run. The fallback rewrite is idempotent too (`BUNDLE_INVOCATION`
-// holds no `pnpm josh `), so the whole rewrite is safe to run more than once.
+// Rebase both paths a hook command can carry: the launcher, then a plain `pnpm josh`. Neither
+// replacement contains the other's anchor, so the two are independent whichever order they run, and
+// the whole rewrite is safe to run more than once.
 function rewrite_command_value(value: string): string {
-	const rewritten = rebase_bundle_directory(value)
-		.split(hook_launch.BUNDLE_READY_GATE)
-		.join(CONSUMER_READY_GATE)
+	const rewritten = value
+		.split(RUN_HOOK_INVOCATION)
+		.join(CONSUMER_RUN_HOOK_INVOCATION)
 		.split(PNPM_JOSH_PREFIX)
 		.join(BUNDLE_INVOCATION)
-		.split(CODEX_ADAPTER_SOURCE)
-		.join(CODEX_ADAPTER_BUNDLE)
 
 	if (!rewritten.includes(claude_plugin_config.MARKETPLACE_PATH)) return rewritten
 	if (rewritten.includes(MISSING_INSTALL_GUARD)) return rewritten

package/scripts/init/hook-launch.ts

@@ -7,51 +7,40 @@ import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
 //
 // **The command starts from the project root, never from wherever the session happens to be**
 // (joshuafolkken/kit#2984). Every path after the prefix is relative, so a hook fired from a
-// subdirectory would otherwise miss its bundle. The root is git's, with the location variables a git
-// hook exports cleared first — the same resolution the consumer rewrite (`hook-command-rewrite.ts`)
-// applies, so both sides stay one mechanism for Claude Code and Codex alike.
+// subdirectory would otherwise miss its script. The root is git's, resolved with the location
+// variables a git hook exports cleared first, and resolved with them only when that fails — git
+// metadata outside the work tree. The consumer rewrite (`hook-command-rewrite.ts`) keeps this prefix,
+// so both sides stay one mechanism for Claude Code and Codex alike.
 //
-// **The bundle runs only once the ready gate passes** (`scripts/hooks/hook-bundle-ready.ts`): it
-// rebuilds `dist/hooks/` when the source beside it has changed, so an edited guard is never shadowed by
-// its old bundle. The gate failing — a checkout that cannot build — drops to the fallback, the live
-// source. **An `if`/`else`, never `&&`/`||`**: a guard's refusal is a non-zero exit, and a
-// `node … || pnpm josh …` chain would read that refusal as a missing bundle and run the hook twice.
+// **Everything after the root is one script** (`scripts/hooks/run-hook.sh`, joshuafolkken/kit#3184):
+// clearing the location variables for the hook itself, the bundle-ready gate and the live-source
+// fallback live there once, so each hook command names only its hook.
 
 const HOOK_DIST_DIR = 'dist/hooks'
+const RUN_HOOK_SCRIPT = 'scripts/hooks/run-hook.sh'
 const UNSET_OPTIONS = GIT_LOCATION_VARIABLES.map((name) => `-u ${name}`).join(' ')
-const PROJECT_ROOT_PREFIX = `if project_root="$(env ${UNSET_OPTIONS} git rev-parse --show-toplevel 2>/dev/null)"; then unset ${GIT_LOCATION_VARIABLES.join(' ')}; else project_root="$(git rev-parse --show-toplevel)" || exit 1; fi; cd "$project_root" && `
-// Plain `node` runs the gate's TypeScript directly; the flag keeps Node 22's type-stripping notice off
-// every hook's stderr.
-const BUNDLE_READY_GATE =
-	'node --disable-warning=ExperimentalWarning scripts/hooks/hook-bundle-ready.ts'
+const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
+const PROJECT_ROOT_PREFIX = `project_root="$(env ${UNSET_OPTIONS} ${ROOT_LOOKUP} 2>/dev/null || ${ROOT_LOOKUP})" && cd "$project_root" && `
 
-// Run `primary_command` when `gate` exits 0, else `fallback_command` — both verbatim. Kept generic so
-// a test can exercise the branch selection with stub commands rather than real hooks.
-function launch_command(gate: string, primary_command: string, fallback_command: string): string {
-	return `if ${gate}; then ${primary_command}; else ${fallback_command}; fi`
+// `name` is the hook's bundle under `dist/hooks` without `.js` (e.g. `pretool-guard`), followed by any
+// arguments it takes (e.g. `codex-hook-adapter pretool`).
+function hook_launch_command(name: string): string {
+	return `${PROJECT_ROOT_PREFIX}sh ${RUN_HOOK_SCRIPT} ${name}`
 }
 
-// `invocation` is the hook's file under `dist/hooks` plus any arguments (e.g. `pretool-guard.js`);
-// `fallback_command` runs the same hook from source.
-function bundle_launch_command(invocation: string, fallback_command: string): string {
-	const primary = `node ${HOOK_DIST_DIR}/${invocation}`
-
-	return `${PROJECT_ROOT_PREFIX}${launch_command(BUNDLE_READY_GATE, primary, fallback_command)}`
-}
-
-// `bundle` is the hook's file under `dist/hooks` (e.g. `pretool-guard.js`); `command` is the josh
-// subcommand the fallback runs (e.g. `pretool:guard`).
-function hook_launch_command(bundle: string, command: string): string {
-	return bundle_launch_command(bundle, `pnpm josh ${command}`)
+// The josh subcommand the launcher falls back to for hook `name`: its first `-` becomes `:`
+// (`pretool-guard` → `pretool:guard`). The launcher derives it in shell; this is that rule for the tests
+// that hold every wired hook to a subcommand josh has.
+function fallback_command(name: string): string {
+	return name.replace('-', ':')
 }
 
 const hook_launch = {
-	BUNDLE_READY_GATE,
-	bundle_launch_command,
+	fallback_command,
 	HOOK_DIST_DIR,
 	hook_launch_command,
-	launch_command,
 	PROJECT_ROOT_PREFIX,
+	RUN_HOOK_SCRIPT,
 }
 
 export { hook_launch }

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

@@ -0,0 +1,95 @@
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { run_carry } from '#scripts/run/run-carry'
+import { issue_file } from './issue-file'
+import { AUTO_OK_LABEL, has_label_name } from './issue-labels'
+import { issue_state_cli } from './issue-state-cli'
+
+// Whether `josh issue:file` applies `auto-ok` to the Issue it files (joshuafolkken/kit#3213). Work
+// found during an unattended run used to wait in the backlog until a person labelled it, so the
+// filing now 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.
+
+interface AutoOkSignals {
+	is_opted_out: 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
+}
+
+interface AutoOkDecision {
+	is_applied: boolean
+	reason: string
+}
+
+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 CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
+const BRANCH_OPTED_IN: 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',
+}
+
+// The opt-out wins over every signal, then the carry record, then the branch's Issue.
+function decide(signals: AutoOkSignals): AutoOkDecision {
+	if (signals.is_opted_out) return OPTED_OUT
+	if (signals.is_carried) return CARRIED
+	if (has_label_name(signals.branch_labels ?? [], AUTO_OK_LABEL)) return BRANCH_OPTED_IN
+
+	return NOT_OPTED_IN
+}
+
+function line_of(decision: AutoOkDecision): string {
+	return `auto-ok: ${decision.is_applied ? 'applied' : 'not applied'} — ${decision.reason}`
+}
+
+// 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()
+
+	if (directory === undefined) return false
+
+	return run_carry.read_carry(run_carry.carry_path(directory)).kind === 'carried'
+}
+
+// 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())
+
+	if (issue_number === undefined) return undefined
+	const read = await issue_state_cli.read_issue(String(issue_number), current)
+
+	return read.kind === 'state' ? read.state.labels : undefined
+}
+
+// Each read is skipped once an earlier signal has already decided the answer; a cross-repository
+// filing is refused before any signal is read.
+async function resolve(
+	is_opted_out: boolean,
+	target: string,
+	current: string,
+): Promise<AutoOkDecision> {
+	if (is_opted_out) return OPTED_OUT
+	if (!issue_file.is_same_repository(target, current)) return CROSS_REPOSITORY
+	if (await is_carried()) return CARRIED
+
+	return decide({ is_opted_out, is_carried: false, branch_labels: await branch_labels(current) })
+}
+
+const issue_auto_ok = { decide, line_of, resolve }
+
+export type { AutoOkDecision, AutoOkSignals }
+export { issue_auto_ok }

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

@@ -5,24 +5,30 @@ import { repo_party } from '#scripts/discovery/repo-party'
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { error_text } from '#scripts/lib/error-message'
+import { repository_labels } from '#scripts/repo/repository-labels'
+import { issue_auto_ok } from './issue-auto-ok'
 import { issue_file, type FileArguments } from './issue-file'
 import { issue_lint_cli } from './issue-lint-cli'
 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,…>]` — file an Issue with every filing step run in order
-// (joshuafolkken/kit#2808): the third-party refusal, the body lint, the `## Origin` check for another
-// repository, the duplicate scout, the create call carrying every label, and `epic:bundle` after it.
+// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]` — file an Issue with every
+// filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body lint, the
+// `## Origin` check for another repository, the WIP cap count (joshuafolkken/kit#3181), the duplicate
+// scout, the missing workflow labels created (joshuafolkken/kit#3176), the `auto-ok` decision
+// (joshuafolkken/kit#3213), the create call carrying every label, and `epic:bundle` after it.
 // A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
 
 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,…>]'
+	'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]'
 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 =
@@ -68,6 +74,37 @@ function unacknowledged_message(numbers: ReadonlyArray<number>): string {
 	return `✖ duplicate candidate(s) ${listed} not declared separate — read each (\`issue-fold-existing.md\`); fold into a duplicate, or reissue with \`--distinct ${listed}\` when each is a separate deliverable.`
 }
 
+// The target's open Issues, pull requests excluded by the listing itself; `undefined` when unreadable.
+async function open_count(target: string): Promise<number | undefined> {
+	const outcome = await git_gh_issue_list.issue_list({
+		json_fields: 'number',
+		limit: MAX_SCANNED,
+		repo: target,
+	})
+
+	return outcome.json === undefined ? undefined : issue_wip.count_of(outcome.json)
+}
+
+// The count is printed whatever it answers, and the filing is held only past the cap with no
+// exemption declared. An unreadable count warns and goes on: the cap makes growth visible, and a
+// listing outage is not a reason to stop the run a blocked filing exists for.
+async function is_wip_clear(filing: Filing): Promise<boolean> {
+	const count = await open_count(filing.target)
+
+	if (count === undefined) {
+		console.error(issue_wip.UNREAD_MESSAGE)
+
+		return true
+	}
+
+	const verdict = issue_wip.verdict_of(count, filing.args)
+
+	console.info(issue_wip.count_line(count, filing.target, verdict))
+	if (verdict === issue_wip.HELD) console.error(issue_wip.HELD_MESSAGE)
+
+	return verdict !== issue_wip.HELD
+}
+
 // Set before the scout and left set for `epic:bundle`, so both read the target's backlog.
 function point_listings_at(filing: Filing): void {
 	if (issue_file.is_same_repository(filing.target, filing.current)) return
@@ -94,12 +131,21 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 }
 
 // `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
-// rather than printed, so it is printed here — otherwise the filing fails with no reason given.
+// rather than printed, so it is printed here — otherwise the filing fails with no reason given. A label
+// the create applies is provisioned first, so it never arrives with a generated color.
 async function create(filing: Filing): Promise<string | undefined> {
+	repository_labels.ensure_labels(filing.target)
+	const auto_ok = await issue_auto_ok.resolve(
+		filing.args.is_auto_ok_opted_out,
+		filing.target,
+		filing.current,
+	)
+
+	console.info(issue_auto_ok.line_of(auto_ok))
 	const request = git_gh_issue_write.issue_create_request({
 		title: filing.args.title,
 		body: filing.body,
-		labels: issue_file.labels_of(filing.args, filing.body),
+		labels: issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied),
 		repo: filing.target,
 	})
 
@@ -136,7 +182,7 @@ async function file(filing: Filing): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	if (!(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+	if (!(await is_wip_clear(filing)) || !(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
 	const url = await create(filing)
 
 	if (url === undefined) return FAILURE_EXIT_CODE