@joshuafolkken/kit 1.1128.0 → 1.1166.0

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/init/init-copy-content.ts

@@ -1,6 +1,7 @@
 import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
 import { workflow_pin_logic } from '#scripts/sync/workflow-pin-logic'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { claude_kit_only_settings } from './claude-kit-only-settings'
 import { claude_plugin_config } from './claude-plugin-config'
 import { hook_command_rewrite } from './hook-command-rewrite'
 import { init_logic } from './init-logic'
@@ -19,7 +20,8 @@ import { init_logic } from './init-logic'
  * workflow-pin-logic.ts for why the template refs are not authoritative, and
  * managed-marker-logic.ts for why the stamp is on the file rather than in a list.
  *
- * The consumer's `.claude/settings.json` gets two further passes. The kit plugin's marketplace and
+ * The consumer's `.claude/settings.json` gets three further passes. The keys kit sets only for its
+ * own sessions are removed (joshuafolkken/kit#3140, see claude-kit-only-settings.ts). The kit plugin's marketplace and
  * `enabledPlugins` declaration is injected, because the skills that used to be copied now ship as the
  * `kit` plugin and load from that declaration (joshuafolkken/kit#1879). And its hook commands are
  * rewritten from `pnpm josh` to the published bundle invoked directly with node
@@ -36,10 +38,14 @@ function transform_copied_content(destination_path: string, content: string): st
 		with_pins,
 		KIT_PACKAGE_NAME,
 	)
-	const with_plugin = claude_plugin_config.apply_plugin_config_for_destination(
+	const with_kit_only_stripped = claude_kit_only_settings.apply_kit_only_strip_for_destination(
 		destination_path,
 		with_marker,
 	)
+	const with_plugin = claude_plugin_config.apply_plugin_config_for_destination(
+		destination_path,
+		with_kit_only_stripped,
+	)
 
 	return hook_command_rewrite.apply_hook_command_rewrite_for_destination(
 		destination_path,

package/scripts/init/initial-commit.ts

@@ -0,0 +1,24 @@
+import { start_exec } from './start-exec'
+
+// The first commit of a new repository, shared by `josh start` and `josh dogfood:commit` so neither
+// keeps a copy of how it is made.
+
+const DEFAULT_BRANCH = 'main'
+
+function create_repository(root: string): void {
+	start_exec.run('git', ['init', `--initial-branch=${DEFAULT_BRANCH}`], root)
+}
+
+function commit_all(root: string): void {
+	start_exec.run('git', ['add', '--all'], root)
+	// The first commit of a new repository has no branch to come from, so the hook that keeps commits
+	// off main — installed by the initialize step in a full project — would refuse the only commit
+	// that has to land there.
+	start_exec.run('git', ['commit', '--no-verify', '--message', 'Initial commit'], root)
+	// A repository created by an older `git init` may name its unborn branch `master`.
+	start_exec.run('git', ['branch', '--move', '--force', DEFAULT_BRANCH], root)
+}
+
+const initial_commit = { create_repository, commit_all }
+
+export { initial_commit }

package/scripts/init/start-exec.ts

@@ -1,10 +1,21 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_location_environment } from '#scripts/git/git-location-environment'
 import { execaSync } from 'execa'
 
 // The three spawn shapes every `josh start` step uses, shared by `start-steps.ts`, the setup pull
 // request step and the `josh init` hint so none of them keeps a copy of its own.
+//
+// The three git-driving shapes below act on `root`, so `cwd` has to mean it: an inherited `GIT_DIR` and friends beat `cwd`
+// and would carry a `git init` or commit into whichever repository a calling hook was firing in
+// (joshuafolkken/kit#3151).
+function root_environment(): Record<string, string | undefined> {
+	return git_location_environment.location_free_environment()
+}
+
 function succeeds(command: string, args: ReadonlyArray<string>, root: string): boolean {
-	return execaSync(command, args, { cwd: root, reject: false }).exitCode === 0
+	return (
+		execaSync(command, args, { cwd: root, env: root_environment(), reject: false }).exitCode === 0
+	)
 }
 
 function read_output(
@@ -12,7 +23,7 @@ function read_output(
 	args: ReadonlyArray<string>,
 	root: string,
 ): string | undefined {
-	const result = execaSync(command, args, { cwd: root, reject: false })
+	const result = execaSync(command, args, { cwd: root, env: root_environment(), reject: false })
 
 	return result.exitCode === 0 ? result.stdout.trim() : undefined
 }
@@ -20,7 +31,9 @@ function read_output(
 // Every step spawned here dials GitHub directly, past a scanner's loopback proxy, the same as every
 // other `gh` spawn under scripts/ (joshuafolkken/kit#2436); a local `git` step is unaffected by it.
 function run(command: string, args: ReadonlyArray<string>, root: string): void {
-	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
+	const environment = { ...root_environment(), ...git_gh_exec.direct_environment().env }
+
+	execaSync(command, args, { env: environment, cwd: root, stdio: 'inherit' })
 }
 
 // A caller's own initialize command stands in for the in-process `josh init`, so it keeps the

package/scripts/init/start-steps.ts

@@ -6,6 +6,7 @@ import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { parseCommandString } from 'execa'
 import { main as init_main } from './init'
 import { PACKAGE_DIR } from './init-paths'
+import { initial_commit } from './initial-commit'
 import { kit_setup_state } from './kit-setup-state'
 import type { ProjectProfile, ProjectShape } from './project-profile'
 import { start_exec } from './start-exec'
@@ -23,7 +24,6 @@ interface RunContext extends StepContext {
 	baseline: ReadonlyArray<string> | undefined
 }
 
-const DEFAULT_BRANCH = 'main'
 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 =
@@ -70,7 +70,7 @@ function self_run_refusal(root: string): string | undefined {
 }
 
 function create_git_repository(context: StepContext): void {
-	run('git', ['init', `--initial-branch=${DEFAULT_BRANCH}`], context.root)
+	initial_commit.create_repository(context.root)
 }
 
 // The same setup `josh init` runs, called rather than copied, with the profile the user confirmed.
@@ -90,13 +90,7 @@ function initialize(context: StepContext): void {
 }
 
 function commit_all(context: StepContext): void {
-	run('git', ['add', '--all'], context.root)
-	// The first commit of a new repository has no branch to come from, so the hook that keeps commits
-	// off main — installed by the initialize step in a full project — would refuse the only commit
-	// that has to land there.
-	run('git', ['commit', '--no-verify', '--message', 'Initial commit'], context.root)
-	// A repository created by an older `git init` may name its unborn branch `master`.
-	run('git', ['branch', '--move', '--force', DEFAULT_BRANCH], context.root)
+	initial_commit.commit_all(context.root)
 }
 
 function create_github_repository(context: StepContext): void {
@@ -119,13 +113,15 @@ async function open_setup_pull_request(context: RunContext): Promise<void> {
 	await start_setup_pr.open(context.root, context.baseline)
 }
 
-// What was already changed before a caller's initialize command ran, read only when the setup pull
-// request will need to tell that command's files from the user's own (#2872).
+// 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 (joshuafolkken/kit#3136).
 function baseline_of(
 	steps: ReadonlyArray<StartStep>,
 	context: StepContext,
 ): ReadonlyArray<string> | undefined {
-	if (context.init_command === undefined || !steps.includes('setup_pr')) return undefined
+	if (!steps.includes('setup_pr')) return undefined
 
 	return start_setup_pr.changed_paths(context.root)
 }

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

package/scripts/issue/issue-file.ts

@@ -4,7 +4,12 @@ import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_backlinks } from './issue-backlinks'
 import { issue_classification } from './issue-classification'
-import { DEPTH_LABEL_ORDER, FILING_ROUTE_LABELS, has_label_name } from './issue-labels'
+import {
+	AUTO_OK_LABEL,
+	DEPTH_LABEL_ORDER,
+	FILING_ROUTE_LABELS,
+	has_label_name,
+} from './issue-labels'
 import { markdown_section } from './markdown-section'
 
 // The decisions behind `josh issue:file` (joshuafolkken/kit#2808), kept apart from the command that
@@ -31,6 +36,10 @@ interface FileArguments {
 	labels: ReadonlyArray<string>
 	repo: string | undefined
 	distinct: ReadonlyArray<number>
+	// `--over-cap`: the run is blocked by this filing, so the WIP cap does not hold it (`issue-wip.ts`).
+	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
 }
 
 const OPTIONS = {
@@ -40,6 +49,8 @@ const OPTIONS = {
 	label: { type: 'string', multiple: true },
 	repo: { type: 'string' },
 	distinct: { type: 'string', multiple: true },
+	'over-cap': { type: 'boolean' },
+	'no-auto-ok': { type: 'boolean' },
 } as const
 
 // The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
@@ -101,7 +112,15 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 
 	if (labelled === undefined || !has_text(title) || !has_text(body_file)) return undefined
 
-	return { title, body_file, ...labelled, labels: values.label ?? [], repo: values.repo }
+	return {
+		title,
+		body_file,
+		...labelled,
+		labels: values.label ?? [],
+		repo: values.repo,
+		is_over_cap: values['over-cap'] === true,
+		is_auto_ok_opted_out: values['no-auto-ok'] === true,
+	}
 }
 
 // An unknown flag is `undefined` rather than a throw, so the answer is the usage line, not a stack trace.
@@ -121,12 +140,16 @@ 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`. One request applies them all, so no label is a separate step to forget.
-function labels_of(args: FileArguments, body: string): ReadonlyArray<string> {
+// extra `--label`, then `auto-ok` when the filing opted 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))
 	const declared = [args.depth, ...(args.route === undefined ? [] : [args.route]), ...extra]
+	const labels = issue_classification.labels_for(body, declared)
 
-	return issue_classification.labels_for(body, declared)
+	if (!is_auto_ok || has_label_name(labels, AUTO_OK_LABEL)) return labels
+
+	return [...labels, AUTO_OK_LABEL]
 }
 
 function is_same_repository(target: string, current: string): boolean {

package/scripts/issue/issue-labels.ts

@@ -16,7 +16,7 @@ const PLANNED_LABEL = 'run:planned'
 // 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`;
+// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `backlogrun-lanes.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'
@@ -36,11 +36,12 @@ const PRIORITY_HIGH_LABEL = 'priority:high'
 const AUTO_OK_LABEL = 'auto-ok'
 // Degrades one issue's run to a `halfrun`-shaped stop: it is implemented and taken through the
 // verification gate, and then nothing is committed, pushed, opened as a pull request or merged
-// (joshuafolkken/kit#1125). **Only a person applies it**, exactly as strongly as `auto-ok` — a mark a
-// run could clear for itself is not a mark.
+// (joshuafolkken/kit#1125). **Only a person applies it** — a mark a run could clear for itself is not
+// a mark.
 //
-// It is the opposite of `auto-ok` in what it does and its twin in who may apply it: one widens
-// unattended execution past an epic's edge, the other withholds the last step of it. `auto-ok`
+// It is the opposite of `auto-ok` in what it does: one widens unattended execution past an epic's
+// edge, the other withholds the last step of it. Unlike `auto-ok`, which `issue:file` applies by
+// default to work found by opted-in work (joshuafolkken/kit#3213), no run ever applies it. `auto-ok`
 // answers "may this run at all", this one answers "may its result ship without a person looking".
 //
 // **Not `needs-decision`, and the difference is what the two sets below encode.** A parked issue is
@@ -154,7 +155,7 @@ const FILING_ROUTE_LABELS: ReadonlyArray<{
 //
 // **The depth is read off the subject, so a run applies it.** Unlike `auto-ok` and
 // `needs-human-review` this is not a person's judgement about authorization; it is the same reading
-// §2i already asks a run to make before it files, and none of the three withholds or widens anything
+// `observation-filing.md` already asks a run to make before it files, and none of the three withholds or widens anything
 // a run may do.
 const DEPTH_0_LABEL = 'depth:0'
 const DEPTH_1_LABEL = 'depth:1'
@@ -171,9 +172,8 @@ const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL,
 // description, so provisioning from here is what gives each one a stable color a reader can scan by.
 // Green, amber and pale blue, so the consumer-facing depth is the one that stands out in a listing.
 //
-// **The provisioning command lives in `observation-filing.md`**, because prose cannot import this module —
-// the same split `FILING_ROUTE_LABELS` above lives with. `scripts/rules/issue-depth-label.test.ts` keys
-// those three command lines to this array, so a color changed here without the document fails.
+// **`josh issue:file` provisions them** through `repository_labels.ensure_labels` before its create
+// call (joshuafolkken/kit#3176), so no document carries a creation command to keep in step.
 const DEPTH_LABELS: ReadonlyArray<{
 	name: string
 	color: string
@@ -182,17 +182,17 @@ const DEPTH_LABELS: ReadonlyArray<{
 	{
 		name: DEPTH_0_LABEL,
 		color: '0e8a16',
-		description: 'Depth 0 — what a consumer of this package touches (SKILL.md §2i)',
+		description: 'Depth 0 — what a consumer of this package touches (observation-filing.md)',
 	},
 	{
 		name: DEPTH_1_LABEL,
 		color: 'fbc02d',
-		description: 'Depth 1 — the run orchestration that executes an Issue (SKILL.md §2i)',
+		description: 'Depth 1 — the run orchestration that executes an Issue (observation-filing.md)',
 	},
 	{
 		name: DEPTH_2_LABEL,
 		color: 'c5def5',
-		description: 'Depth 2 — what measures a run (SKILL.md §2i)',
+		description: 'Depth 2 — what measures a run (observation-filing.md)',
 	},
 ]
 

package/scripts/issue/issue-rank.ts

@@ -15,7 +15,7 @@ import {
 //
 // **`run:solo` alone is not a key.** It means "runs alone", not "runs first": tidying that only touches
 // the verification path carries it too, and a low-priority one is not owed a place ahead of the queue.
-// Only a defect on that path is, because `wip-cap.md` holds a batch until it has merged.
+// Only a defect on that path is, because `backlogrun-lanes.md` holds a batch until it has merged.
 
 interface RankRow {
 	labels: ReadonlyArray<string>

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

@@ -8,7 +8,7 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 // `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call
 // (joshuafolkken/kit#1715).
 //
-// It replaces the two `gh api` reads `.claude/skills/workflow-commands/SKILL.md` §2g tells an agent
+// It replaces the two `gh api` reads `.claude/skills/workflow-commands/issue-comments.md` tells an agent
 // to type per issue. Measured over four recorded `backlogrun` parents, `issue bookkeeping` was the
 // largest single contributor to the parent's turn count — 110 of 414 turns, 26.6% — and one issue
 // read at a time was its dominant shape: 19 `…/issues/<N>` calls and 5 `…/comments` calls, each its
@@ -23,7 +23,7 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 // prevent.
 //
 // **A failed read is never printed as an issue**, and neither is a failed comment listing printed as
-// "no comments" — the block says which of the two it holds, because §2g's rule is that the later text
+// "no comments" — the block says which of the two it holds, because `issue-comments.md`'s rule is that the later text
 // wins, and a comment nobody read cannot win anything.
 
 const FAILURE_EXIT_CODE = 1
@@ -88,7 +88,7 @@ async function read_issue(issue_number: string): Promise<NumberResult> {
 
 // One issue's block for a caller that wants the text rather than the printing — `run:prep` composes it
 // with the state block and the dependency-update line. A failed read is returned as its kind, never as
-// an empty block, so §2g's "a comment nobody read cannot win anything" holds through the bundle too.
+// an empty block, so `issue-comments.md`'s "a comment nobody read cannot win anything" holds through the bundle too.
 async function read_block(issue_number: string): Promise<BlockRead> {
 	const result = await read_issue(issue_number)
 
@@ -129,6 +129,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	issue_report_failures.print_blocks(
 		reports.flatMap((report) => issue_blocks(report)),
 		BLOCK_SEPARATOR,
+		`issue:read ${issue_numbers.join(' ')}`,
 	)
 
 	return issue_report_failures.report_failures(reports, FAILURE_TERMS)

package/scripts/issue/issue-read.ts

@@ -6,7 +6,7 @@ import { z } from 'zod'
 // (joshuafolkken/kit#1715).
 //
 // **It exists because reading one issue costs a parent two turns.** `.claude/skills/workflow-commands/SKILL.md`
-// §2g requires the body *and* the comments, since a decision recorded after the body was written
+// `issue-comments.md` requires the body *and* the comments, since a decision recorded after the body was written
 // lives only in a comment; typed by hand that is `gh api repos/{owner}/{repo}/issues/<N>` followed by
 // `gh api repos/{owner}/{repo}/issues/<N>/comments`. Measured over four recorded `backlogrun`
 // parents, `issue bookkeeping` was the single largest contributor to the parent's turn count — 110 of
@@ -15,7 +15,7 @@ import { z } from 'zod'
 // distribution this collapses.
 //
 // **The comments are never silently absent.** A listing that could not be read prints a line saying
-// so, because a block showing no comment where the read failed is exactly the misread §2g exists to
+// so, because a block showing no comment where the read failed is exactly the misread `issue-comments.md` exists to
 // prevent: the agreement in force would be taken from a body a comment had already overturned.
 
 const ISSUE_LABEL = 'issue: '