@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/josh/josh-command-map.ts

@@ -20,6 +20,21 @@ const CATEGORY_ORDER: ReadonlyArray<CommandCategory> = [
 ]
 
 const COMMAND_MAP: Record<string, CommandEntry> = {
+	completion: {
+		script: 'scripts/josh/josh-completion.ts',
+		description: 'Print command names and aliases, or a shell completion script',
+		category: 'Development',
+		reference: ['--names | <zsh|bash|fish>', 'automation', ['none']],
+		is_read_only: true,
+		usage: {
+			examples: [
+				{ arguments: '--names' },
+				{ arguments: 'zsh' },
+				{ arguments: 'bash' },
+				{ arguments: 'fish' },
+			],
+		},
+	},
 	...DEV_COMMANDS,
 	...PROJECT_COMMANDS,
 	...WORKFLOW_COMMANDS,

package/scripts/josh/josh-command-types.ts

@@ -75,15 +75,21 @@ interface CommandEntry {
 	// Composite (`sh -c`) commands reject extra CLI arguments instead of swallowing them; this
 	// names the sub-commands that do accept them, so the refusal points somewhere useful.
 	argument_targets?: ReadonlyArray<string>
+	// Flags that turn the invocation into a read whatever its declared side effects — `ship --log` —
+	// so a scope that may not implement passes it (`josh-read-only.ts`). Declared here, not read off
+	// `side_effects`: `none` there is documentation, not a write audit (`edit:files` writes).
+	read_only_flags?: ReadonlyArray<string>
+	// A command whose every invocation only reads — `cost:audit`, `read:set` — so it passes the same
+	// scope with no flag (`josh-read-only.ts`). Declared only after its code paths are audited for writes.
+	is_read_only?: boolean
+	// Flags that keep a declared read from passing when it writes, including --flag=value spellings.
+	write_flags?: ReadonlyArray<string>
 	// A command that only makes sense inside the kit repository itself — the rule-compliance eval and
 	// the run measurements that analyze kit's own development. It is dropped from a consumer's
 	// `josh --help` and refused with guidance when run in a consumer project, so a distributed help
 	// listing carries only what a consumer can run. The audience in
 	// `reference` separately decides whether the command appears in the default listing.
 	is_kit_only?: boolean
-	// Pre-built to `dist/commands/` so a consumer's `dist/josh.js` imports it in its own process
-	// instead of spawning tsx for it (`docs/maintainers/runtime-bundling.md`).
-	is_bundled?: boolean
 	// The cores the command reserves from the machine-wide budget before it starts its heavy tools.
 	// `josh-logic.ts` claims them at the one dispatch point every command
 	// passes through, so the command only declares the number. A function means the weight is read
@@ -135,7 +141,7 @@ const ESLINT_RELATED_CACHE_FILE = '.eslintcache.related'
 const PRETTIER_CACHE_FILE = '.prettiercache'
 const PRETTIER_RELATED_CACHE_FILE = '.prettiercache.related'
 // The pre-commit hook's own, because a staged-files run on the gate's file degrades it: cspell prunes
-// every entry the run did not visit (measured 892 KB down to 18 KB), and `eslint --quiet` stores a
+// every entry the run did not visit, and `eslint --quiet` stores a
 // report without its warnings under the same config hash the gate reads.
 const CSPELL_COMMIT_CACHE_FILE = '.cspellcache.commit'
 const ESLINT_COMMIT_CACHE_FILE = '.eslintcache.commit'
@@ -249,6 +255,18 @@ const PRETTIER_RELATED_CACHE_FLAGS = content_cache_flags(PRETTIER_RELATED_CACHE_
 const CSPELL_COMMIT_CACHE_FLAGS = content_cache_flags(CSPELL_COMMIT_CACHE_FILE)
 const ESLINT_COMMIT_CACHE_FLAGS = content_cache_flags(ESLINT_COMMIT_CACHE_FILE)
 
+// `josh lint:rule`'s own cache and report directory, under `node_modules` so no ignore rule has to
+// name it: its `--rule` override changes every entry's config hash, so on the gate's file each run
+// would leave the gate a cold lint. The workers are its `--concurrency`, and its registration claims
+// the whole-tree scan's cores and memory once per worker. A `--paths` run lints on a cache of its
+// own, so a subset run never rewrites the whole run's cache, whose unvisited entries eslint may drop.
+const LINT_RULE_DIRECTORY = 'node_modules/.cache/josh/lint-rule'
+const LINT_RULE_CACHE_FILE = `${LINT_RULE_DIRECTORY}/.eslintcache`
+const LINT_RULE_CACHE_FLAGS = content_cache_flags(LINT_RULE_CACHE_FILE)
+const LINT_RULE_PATHS_CACHE_FILE = `${LINT_RULE_DIRECTORY}/.eslintcache-paths`
+const LINT_RULE_PATHS_CACHE_FLAGS = content_cache_flags(LINT_RULE_PATHS_CACHE_FILE)
+const LINT_RULE_WORKERS = 2
+
 export type { CommandCategory, CommandEntry, CommandUsage, GateCacheSpec }
 // The three cache files are exported one by one as well as as a list, because `josh bench` clears
 // them per target: the lint step writes only the eslint one, so a target
@@ -273,6 +291,12 @@ export {
 	GATE_CACHE_SPECS,
 	GATE_COMMAND,
 	IGNORED_CACHE_FILES,
+	LINT_RULE_CACHE_FILE,
+	LINT_RULE_CACHE_FLAGS,
+	LINT_RULE_DIRECTORY,
+	LINT_RULE_PATHS_CACHE_FILE,
+	LINT_RULE_PATHS_CACHE_FLAGS,
+	LINT_RULE_WORKERS,
 	OPTIONAL_ENV_FILE_FLAGS,
 	PRETTIER_CACHE_FILE,
 	PRETTIER_CACHE_FLAGS,

package/scripts/josh/josh-commands-agent-hooks.ts

@@ -6,8 +6,16 @@ const PRE_TOOL_USE = 'run by the PreToolUse hook, the pending tool call as JSON
 // command's usage moved onto its entry (#4185). `DEV_COMMANDS` spreads this in at the same place, so
 // the map keeps its order.
 
-/* eslint-disable @typescript-eslint/naming-convention */
 const AGENT_HOOK_COMMANDS: Record<string, CommandEntry> = {
+	'usage:tee': {
+		script: 'scripts/usage/usage-tee-cli.ts',
+		description: 'Record account-wide Claude statusLine rate limits without printing output',
+		category: 'Development',
+		reference: ['', 'automation', ['files']],
+		usage: {
+			examples: [{ arguments: '', note: 'Claude statusLine JSON on stdin; stdout stays empty' }],
+		},
+	},
 	'format:edited': {
 		script: 'scripts/hooks/format-edited-cli.ts',
 		description: 'Claude Code hook: format the file just edited (reads the tool call on stdin)',
@@ -28,10 +36,35 @@ const AGENT_HOOK_COMMANDS: Record<string, CommandEntry> = {
 		usage: { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
 		// **No `tsx_arguments`, deliberately.** The guards read `.env` for their other values, as other
 		// commands do through `OPTIONAL_ENV_FILE_FLAGS`; the guard switches themselves come from the
-		// launch environment alone (`josh-environment-file.ts`). But declaring any `tsx_arguments`
-		// disqualifies a command from in-process dispatch (`josh-in-process.ts`), and this is the one PreToolUse hook consumers run
-		// before every guarded call, where a second ~0.16 s tsx start is not affordable. Each guard it
-		// composes loads `.env` through the shared loader instead.
+		// launch environment alone (`josh-environment-file.ts`). Each guard it composes loads `.env`
+		// through the shared loader on its real hook path instead, so the unit tests never see a
+		// developer's `.env`.
+	},
+	// The hook ledger read per rule (joshuafolkken/kit#6664): which rules refuse, and how often wrongly.
+	// `--apply` / `--restore` write the demoted-rules file (joshuafolkken/kit#6591).
+	'hook:ledger': {
+		script: 'scripts/hooks/hook-ledger-cli.ts',
+		is_read_only: true,
+		write_flags: ['--apply', '--restore'],
+		description:
+			'Print Claude Code hook refusals per hook and rule over a period: refusals, the same call passing later, and route:interrupt issues naming the rule; list, demote or restore rules that mostly refuse allowed work',
+		category: 'Development',
+		reference: [
+			'--period <days> [--demote [--apply]] | --restore <rule>',
+			'maintainer',
+			['network', 'files'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '--period 7', note: "a 7-day period's refusals per rule" },
+				{ arguments: '--period 7 --demote', note: 'rules to demote from blocking to notice' },
+				{
+					arguments: '--period 7 --demote --apply',
+					note: 'record them in .josh/hook-demoted.json',
+				},
+				{ arguments: '--restore batching', note: 'make a demoted rule block again' },
+			],
+		},
 	},
 	'stop:guard': {
 		script: 'scripts/hooks/stop-guard.ts',
@@ -51,7 +84,7 @@ const AGENT_HOOK_COMMANDS: Record<string, CommandEntry> = {
 	'session:lang': {
 		script: 'scripts/josh/session-language-main.ts',
 		description:
-			'Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, and the run:board reply rule while a backlogrun is live (otherwise nothing)',
+			'Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, the run:board reply rule while a backlogrun is live, and the run:handoff line for a workflow keyword on a consultation model (otherwise nothing)',
 		category: 'Development',
 		reference: ['', 'automation', ['none']],
 		usage: {
@@ -78,6 +111,5 @@ const AGENT_HOOK_COMMANDS: Record<string, CommandEntry> = {
 		// above: it runs before every guarded Codex call.
 	},
 }
-/* eslint-enable @typescript-eslint/naming-convention */
 
 export { AGENT_HOOK_COMMANDS }

package/scripts/josh/josh-commands-ai.ts

@@ -1,20 +1,43 @@
 import { core_weights } from '#scripts/gate/core-weights'
-import type { CommandEntry } from './josh-command-types'
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 import { BACKLOG_COMMANDS } from './josh-commands-backlog'
 import { DOCUMENT_COMMANDS } from './josh-commands-document'
 import { EPIC_COMMANDS } from './josh-commands-epic'
 import { ISSUE_COMMANDS } from './josh-commands-issue'
-import { LANE_COMMANDS } from './josh-commands-lane'
 import { REVIEW_COMMANDS } from './josh-commands-review'
 import { RUN_COMMANDS } from './josh-commands-run'
 import { SHIP_COMMANDS } from './josh-commands-ship'
-import { SPLIT_COMMANDS } from './josh-commands-split'
 
 const DIR = '--dir <path>'
 const PATH_DIR = '--path <dir>'
 const BARE = { arguments: '' }
+// `lane:pause` and `lane:resume` take the same target.
+const LANE_SIGNAL_EXAMPLES = [
+	{ arguments: '4198' },
+	{ arguments: '--all', note: 'every open lane' },
+]
+
+// One script answers `lane:open` / `lane:close` / `lane:list` / `lane:prune` / `lane:output` /
+// `lane:dispatch` / `lane:await`, told apart by the verb below; `lane:launch` is the composite that
+// opens, pops-and-installs on the first lane, and dispatches.
+const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
+// `JOSH_LANE_ROOT` and `JOSH_LANE_LIMIT` are personal, non-committed settings, so every lane command
+// has to read `.env` to see them — without this the two are documented and unreachable.
+const LANE_ARGUMENTS = { script: LANE_SCRIPT, tsx_arguments: OPTIONAL_ENV_FILE_FLAGS } as const
+const ISSUE_WITH_OPTIONS = '<issue> [options]'
+const ISSUE_OR_ALL = '<issue> | --all'
+const MEASURE_ARGUMENTS = {
+	script: 'scripts/lane/lane-measure-cli.ts',
+	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+} as const
+
+const PAUSE_ARGUMENTS = {
+	script: 'scripts/lane/lane-pause-cli.ts',
+	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+	category: 'AI tools',
+	reference: [ISSUE_OR_ALL, 'developer', ['processes']],
+} satisfies Partial<CommandEntry>
 
-/* eslint-disable @typescript-eslint/naming-convention */
 const AI_COMMANDS: Record<string, CommandEntry> = {
 	...ISSUE_COMMANDS,
 	'pkg:scout': {
@@ -22,7 +45,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Rank package candidates by measured metrics so the Package-First tier decision is read, not judged',
 		category: 'AI tools',
-		reference: ['<keywords> [--size <n>]', 'automation', ['network']],
+		reference: ['<keywords> [--size <n>] [--issue <n>]', 'automation', ['network']],
 		usage: {
 			examples: [{ arguments: '"date formatting" --size 5' }],
 			flags: [
@@ -30,6 +53,10 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 					names: ['--size <n>'],
 					description: 'how many candidates to fetch and rank (default 10).',
 				},
+				{
+					names: ['--issue <n>'],
+					description: 'the Issue a close pair reads for reuse (default: the held run).',
+				},
 			],
 		},
 	},
@@ -101,20 +128,44 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Report AI cost over a period by session kind, tool category and guard, with cost per merge and regressions against the period before',
 		category: 'AI tools',
-		reference: ['[--period <days>]', 'maintainer', ['none']],
+		reference: [
+			'[--period <days> | --since <YYYY-MM-DD> --until <YYYY-MM-DD>] [--density]',
+			'maintainer',
+			['none'],
+		],
 		// Kit-only: it reads kit's own transcript store, like `josh retrospective`, which carries its
 		// summary line.
 		is_kit_only: true,
+		// Reads transcripts and a `gh api` search (GET) only, so a consultation session can run it.
+		is_read_only: true,
 		usage: {
 			examples: [
 				{ arguments: '', note: 'the last 7 days against the 7 before' },
 				{ arguments: '--period 30', note: 'the last 30 days against the 30 before' },
+				{
+					arguments: '--since 2026-10-27 --until 2026-11-10',
+					note: 'those 15 UTC days against the 15 before',
+				},
+				{
+					arguments: '--density',
+					note: 'the lane-child calls per request alone, as the last line',
+				},
 			],
 			flags: [
 				{
 					names: ['--period <days>'],
 					description: 'the length of each period, a positive whole number of days (default 7).',
 				},
+				{
+					names: ['--since <YYYY-MM-DD>', '--until <YYYY-MM-DD>'],
+					description:
+						'a fixed period instead, from the first UTC date through the second, both included; given together and never beside `--period`.',
+				},
+				{
+					names: ['--density'],
+					description:
+						"print only the period's lane-child density (calls per request, two decimals), so a measurement Issue declares it; no lane-child request prints nothing and exits 1.",
+				},
 			],
 		},
 	},
@@ -216,8 +267,349 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			],
 		},
 	},
+	'pin:verify': {
+		script: 'scripts/discovery/pin-verify-cli.ts',
+		description:
+			'Check that a tag resolves to the commit a SHA pin names, printing a line a bypass reason cites',
+		category: 'AI tools',
+		reference: ['<owner/repo> <tag> <sha>', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: 'actions/checkout v4.2.2 11bd71901bbe5b1630ceea73d27597364c9af683',
+					note: '→ match / mismatch / unreadable',
+				},
+			],
+		},
+	},
 	...SHIP_COMMANDS,
-	...LANE_COMMANDS,
+	'lane:open': {
+		...LANE_ARGUMENTS,
+		description: 'Open a lane: a linked work tree with its own branch and its own port seed',
+		category: 'AI tools',
+		reference: [ISSUE_WITH_OPTIONS, 'automation', ['files', 'git']],
+		default_script_arguments: ['open'],
+		usage: { examples: [{ arguments: '1490', note: 'prints the lane directory on stdout' }] },
+	},
+	'lane:close': {
+		...LANE_ARGUMENTS,
+		description: 'Close a lane, leaving no work tree, branch or directory behind',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['files', 'git']],
+		default_script_arguments: ['close'],
+		usage: {
+			examples: [{ arguments: '1490' }, { arguments: '--all' }],
+			flags: [{ names: ['--all'], description: 'closes every lane.' }],
+		},
+	},
+	'lane:list': {
+		...LANE_ARGUMENTS,
+		description: 'List the open lanes: which issue, which ports, and where each one is',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+		default_script_arguments: ['list'],
+		usage: { examples: [BARE] },
+	},
+	'lane:prune': {
+		...LANE_ARGUMENTS,
+		description:
+			'Close every lane an interruption left without its work tree and every spent lane, then sweep unregistered leftovers under the lanes root',
+		category: 'AI tools',
+		reference: ['', 'automation', ['files', 'git']],
+		default_script_arguments: ['prune'],
+		usage: { examples: [BARE] },
+	},
+	'lane:output': {
+		...LANE_ARGUMENTS,
+		description: 'Record, or read back, where the unit running a lane’s child writes',
+		category: 'AI tools',
+		reference: ['<issue> [path]', 'automation', ['files']],
+		default_script_arguments: ['output'],
+		usage: {
+			examples: [
+				{ arguments: '1713 /abs/path/to/agent-7.jsonl', note: 'record it; prints the path back' },
+				{ arguments: '1713', note: 'read it; prints the path, or `none`' },
+			],
+		},
+	},
+	'lane:dispatch': {
+		...LANE_ARGUMENTS,
+		description: 'Start a lane’s child as a detached process that outlives this session',
+		category: 'AI tools',
+		reference: ['<issue> <prompt>', 'automation', ['processes']],
+		default_script_arguments: ['dispatch'],
+		usage: {
+			examples: [
+				{
+					arguments: '1749',
+					note: "prints the child's pid; a refusal is an empty capture and exit 1",
+				},
+			],
+			flags: [
+				{
+					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_MODEL'],
+					description:
+						'Claude Code role overrides; Anthropic defaults are respectively `claude-opus-5-5`, `claude-opus-5-5`, and `claude-opus-5-5`. Codex keeps its provider-specific model.',
+				},
+				{
+					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_EFFORT'],
+					description:
+						'role effort overrides for either provider; defaults are `medium`, `medium`, and `medium`.',
+				},
+				{
+					names: ['JOSH_REVIEWER_VERIFICATION_{MODEL,EFFORT}'],
+					description:
+						'review round 2 and later (the verification pass); defaults are `claude-sonnet-5-5` / `high` on Anthropic and `high` on OpenAI, falling back to `JOSH_REVIEWER_*`.',
+				},
+			],
+		},
+	},
+	'lane:await': {
+		...LANE_ARGUMENTS,
+		description:
+			'Block until any of the named in-flight lane children completes; prints which one finished',
+		category: 'AI tools',
+		reference: ['<issue> [<issue>...] [--owner <pid>]', 'automation', ['files', 'processes']],
+		default_script_arguments: ['await'],
+		usage: {
+			examples: [
+				{
+					arguments: '1749 1750',
+					note: 'reclaim a resumed conversation’s carry record, then block until either lane completes',
+				},
+			],
+		},
+	},
+	'lane:launch': {
+		script: 'scripts/lane/lane-launch-main.ts',
+		description:
+			'Collapse a backlogrun lane-start event into one call: open the lane, pop and re-install on the first, dispatch the child',
+		category: 'AI tools',
+		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '1749', note: 'every lane after the first' },
+				{
+					arguments: '1749 --stash "backlogrun: josh latest before lanes"',
+					note: 'the first lane only',
+				},
+			],
+		},
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:restart': {
+		script: 'scripts/lane/lane-restart-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session — not counted as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [{ arguments: '3769', note: "prints the fresh child's pid" }],
+		},
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:withdraw': {
+		script: 'scripts/lane/lane-withdraw-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work and close the lane, leaving its issue open for the next run — booked withdrawn, not as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue> --reason <text>', 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
+		},
+	},
+	'lane:resolve': {
+		script: 'scripts/lane/lane-resolve-cli.ts',
+		description:
+			"Merge the default branch into a lane's branch and print one verdict — resolved, conflict <paths>, or step-back 2 (overlapping hunks, merge aborted) / 3 (a resolution already recorded on the issue); --record posts that resolution comment once the lane is pushed",
+		category: 'AI tools',
+		reference: ['<issue> [--record [<path>...]]', 'developer', ['git', 'network', 'files']],
+		usage: {
+			examples: [
+				{ arguments: '3769', note: 'prints `conflict docs/a.md` on a hand-resolvable conflict' },
+				{
+					arguments: '3769 --record docs/a.md',
+					note: 'posts the `## Lane conflict resolved` comment once the lane is pushed',
+				},
+			],
+		},
+	},
+	// `.env` is read for the Telegram settings the yield's hold release reaches (`run-hold-cli.ts`).
+	'lane:plan': {
+		script: 'scripts/lane/lane-plan-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			"Record a lane child's planned files; yield its lane, naming file and holder, when an earlier-planned running lane declares or plans one; `--size-approval` bounds lines/files",
+		category: 'AI tools',
+		reference: [
+			'<issue> <path>... [--probe] [--single] [--estimate <json-file>] [--size-approval <json-file>] [--imports <path>...]',
+			'automation',
+			['files', 'network'],
+		],
+		usage: {
+			examples: [{ arguments: '4864 scripts/lane/lane-plan.ts scripts/backlog/backlog-next.ts' }],
+		},
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so `--all` finds the lanes.
+	'lane:pause': {
+		...PAUSE_ARGUMENTS,
+		description:
+			'Suspend a running lane child’s process tree (SIGSTOP) in place, leaving its work tree, branch and issue untouched, and record the pause in the lane’s state and the run’s event stream',
+		default_script_arguments: ['pause'],
+		usage: { examples: LANE_SIGNAL_EXAMPLES },
+	},
+	'lane:resume': {
+		...PAUSE_ARGUMENTS,
+		description: 'Let a paused lane child carry on from where it stopped (SIGCONT)',
+		default_script_arguments: ['resume'],
+		usage: { examples: LANE_SIGNAL_EXAMPLES },
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so `--all` finds the lanes.
+	'lane:adopt': {
+		script: 'scripts/lane/lane-adopt-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Give an open lane that lost its state record a record again, read from its process, work tree, unpushed commits, pull request and issue — its work untouched',
+		category: 'AI tools',
+		reference: [ISSUE_OR_ALL, 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '4744' },
+				{ arguments: '--all', note: 'every open lane with no record' },
+			],
+		},
+	},
+	// A live run's lane limit: `.env` is read so the bare form reports the
+	// `JOSH_LANE_LIMIT` a person set there when no override stands.
+	'lane:limit': {
+		script: 'scripts/lane/lane-limit-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Change a live backlogrun’s lane limit without stopping it, or print the limit, lanes in use and free lanes',
+		category: 'AI tools',
+		reference: ['[<limit>] [--reset]', 'developer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '8', note: "raise or lower the live run's limit to 8" },
+				{ arguments: '', note: 'print the limit, the lanes in use and the free lanes' },
+				{ arguments: '--reset', note: 'clear the override; the run’s start limit applies again' },
+			],
+		},
+	},
+	// The lane-limit measurement: `.env` is read so `lane:stats` labels the row
+	// with the `JOSH_LANE_LIMIT` a person set there.
+	'lane:sample': {
+		...MEASURE_ARGUMENTS,
+		description:
+			'Record the machine load (load average, swap, free memory, working lanes) to the lane ledger — a backlogrun samples itself, this is for a reading outside one',
+		category: 'AI tools',
+		reference: ['[--every <seconds>]', 'maintainer', ['files']],
+		default_script_arguments: ['sample'],
+		usage: { examples: [{ arguments: '', note: 'one machine-load reading' }] },
+	},
+	'lane:stats': {
+		...MEASURE_ARGUMENTS,
+		description:
+			'Print period lane throughput, stage, stop (by failed CI check, longest first), check and machine-load statistics; --sinks shows stage totals, --over lane chains, --why cause groups above a net-minute threshold, and --pairs scoped pair runs',
+		category: 'AI tools',
+		reference: [
+			'(--period <days> | --since <instant>) [--limit <lane-limit> | --sinks [<minutes>] | --over <minutes> | --why <minutes> | --pairs]',
+			'maintainer',
+			['none'],
+		],
+		default_script_arguments: ['stats'],
+		usage: {
+			examples: [
+				{ arguments: '--period 7', note: "a 7-day period's stage medians and maxima" },
+				{ arguments: '--period 1 --sinks', note: 'stage totals of the lanes over 30 net min' },
+				{ arguments: '--period 1 --over 40', note: 'ledger chains of lanes over 40 net min' },
+				{ arguments: '--period 1 --why 40', note: 'cause groups of lanes over 40 net min' },
+				{ arguments: '--period 7 --pairs', note: "a 7-day period's scoped pair runs" },
+				{ arguments: '--since 2026-11-10T01:00Z --why 40', note: 'cause groups since an instant' },
+			],
+		},
+	},
+	// One lane measurement as one number on the last line, for an Issue's measurement declaration
+	// (joshuafolkken/kit#4630).
+	'lane:value': {
+		...MEASURE_ARGUMENTS,
+		description:
+			'Print one lane measurement since an instant as a single number: cell (a lane:stats table cell, --table --row --where --column --item --zero), lint-unmoved (median s of a lint:related that found nothing moved), metrics-stops (pre-detach metrics stops per lane), lint-core-wait (lint:related core-budget wait, min per lane), edit (median s of one Edit)',
+		category: 'AI tools',
+		reference: ['<metric> --since <instant>', 'maintainer', ['none']],
+		default_script_arguments: ['value'],
+		usage: {
+			examples: [
+				{
+					arguments: 'edit --since 2026-10-23T03:29Z',
+					note: 'the median Edit time since an instant',
+				},
+				{
+					arguments:
+						'cell --table "test:related scope" --row related --column "median (s)" --since 2026-10-23T03:29Z',
+					note: 'one lane:stats table cell since an instant',
+				},
+			],
+		},
+	},
+	'lane:net': {
+		...MEASURE_ARGUMENTS,
+		description:
+			"Print a lane's net minutes: its issue's first dispatch to its merge, less the waits its parks, outages, usage-limit stops and yields stood, the host's sleeps and the ship's followup",
+		category: 'AI tools',
+		reference: ['<issue>', 'maintainer', ['none']],
+		default_script_arguments: ['net'],
+		usage: {
+			examples: [
+				{
+					arguments: '4695',
+					note: 'the net minutes a causing-lane line declares',
+				},
+			],
+		},
+	},
+	'lane:breakdown': {
+		script: 'scripts/lane/lane-breakdown-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			"Print a merged lane's net time by stage, longest first, the implementation split by its tool calls",
+		category: 'AI tools',
+		reference: ['<issue> [--timeline]', 'maintainer', ['none']],
+		usage: {
+			flags: [
+				{
+					names: ['--timeline'],
+					description:
+						'prints the lane in time order instead, one line a stage, wait or event, the stage lines adding up to the net time.',
+				},
+			],
+			examples: [
+				{
+					arguments: '4970',
+					note: 'the breakdown the overrun investigation comments on the lane',
+				},
+				{ arguments: '4970 --timeline', note: 'when each stage ran and where the lane waited' },
+			],
+		},
+	},
+	'lane:why': {
+		script: 'scripts/lane/lane-why-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			"Print a merged lane's stages over budget, one row each, beside the records that say why",
+		category: 'AI tools',
+		reference: ['<issue>', 'maintainer', ['processes', 'network']],
+		usage: {
+			examples: [
+				{
+					arguments: '6050',
+					note: 'the cause table an overrun investigation joins by hand',
+				},
+			],
+		},
+	},
 	'run:watcher:guard': {
 		script: 'scripts/run/run-watcher-guard-cli.ts',
 		description:
@@ -226,7 +618,27 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'automation', ['none']],
 		usage: { examples: [BARE] },
 	},
-	...SPLIT_COMMANDS,
+	'split:recover': {
+		script: 'scripts/split/split-child-recover-cli.ts',
+		description:
+			'Recover split-child evidence after verifying an existing child URL, split route and parent',
+		category: 'AI tools',
+		reference: ['<origin> <child-issue-url>', 'automation', ['network', 'files']],
+		usage: { examples: [{ arguments: '6212 https://github.com/joshuafolkken/kit/issues/6326' }] },
+	},
+	'split:assess': {
+		script: 'scripts/split/split-assess-cli.ts',
+		description:
+			'Measure the branch change size (tests excluded) and answer the split assessment size question: split | single',
+		category: 'AI tools',
+		reference: ['[--json]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: '→ single' },
+				{ arguments: '--json', note: 'the verdict and the reason, machine-readable' },
+			],
+		},
+	},
 	'oracle:list': {
 		script: 'scripts/rules/oracle-list-cli.ts',
 		description: 'Print the decision oracles — commands that answer a rule question mechanically',
@@ -258,6 +670,5 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		},
 	},
 }
-/* eslint-enable @typescript-eslint/naming-convention */
 
 export { AI_COMMANDS }