@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,4 +1,11 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+import { PAUSE_COMMANDS } from './josh-commands-pause'
+import { PROGRESS_COMMANDS } from './josh-commands-progress'
+
+const OWNER = '--owner <pid>'
+const OUTPUT = '--output <path>'
+const REPO_FLAG = { names: ['--repo <owner/name>'], description: 'a child in another repository.' }
+const ISSUE = { arguments: '<N>' }
 
 // The run-lifecycle registry (`run:hold` through `run:step`), split out of `josh-commands-ai.ts` so
 // that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` are. It
@@ -6,7 +13,7 @@ import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types
 // order.
 
 // One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
-const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-cli.ts'
+const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-main.ts'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const RUN_COMMANDS: Record<string, CommandEntry> = {
@@ -14,20 +21,72 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		script: RUN_HOLD_SCRIPT,
 		description: 'Claim this working tree for a run, or say which run already holds it',
 		category: 'AI tools',
-		reference: ['[<issue> [--fullrun | --halfrun-stop | --prrun-stop]]', 'automation', ['files']],
+		// A `--halfrun-stop` / `--human-review-stop` / `--prrun-stop` sends the stop confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		reference: [
+			'[<issue> [--fullrun | --halfrun-stop | --human-review-stop | --prrun-stop]] | --adopt <issue>',
+			'automation',
+			['files'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '1091', note: 'claim for issue 1091' },
+				{ arguments: '1091 --fullrun', note: 'claim as `fullrun #1091` (what `run:entry` runs)' },
+				{ arguments: '--adopt 1091', note: "hand a `new` run's hold to the issue it filed" },
+			],
+			flags: [
+				{ names: ['--fullrun'], description: "marks the record as `fullrun #N`'s." },
+				{
+					names: ['--adopt <issue>'],
+					description:
+						"re-keys the unnumbered `new` run's record to the filed issue and applies `in-progress`; answers `none` (exit 1) when the tree holds no record.",
+				},
+				{
+					names: ['--halfrun-stop'],
+					description:
+						'marks a `halfrun` stop for `run:entry` to adopt, and sends its `confirmation` Telegram; answers `e2e-owed` (exit 1) until `test:e2e` answered green on this tree.',
+				},
+				{
+					names: ['--human-review-stop'],
+					description:
+						'marks a `needs-human-review` stop as a `halfrun` stop, and sends its `confirmation` Telegram naming the lane; answers `e2e-owed` (exit 1) until `test:e2e` answered green on this tree.',
+				},
+				{
+					names: ['--prrun-stop'],
+					description:
+						'marks a `prrun` stop with the commit its pull request is on, and sends its `confirmation` Telegram.',
+				},
+			],
+		},
 	},
 	'run:release': {
 		script: RUN_HOLD_SCRIPT,
 		description: "Release this working tree's run record",
 		category: 'AI tools',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		reference: ['[issue|--force]', 'automation', ['files']],
 		default_script_arguments: ['--release'],
+		usage: {
+			examples: [
+				{ arguments: '1091', note: "release this run's own record" },
+				{ arguments: '--force', note: 'clear a record left by a run that has ended' },
+			],
+			flags: [
+				{
+					names: ['--force'],
+					description:
+						"removes a record this run did not write, clearing another run's stale claim.",
+				},
+			],
+		},
 	},
+	...PAUSE_COMMANDS,
 	'run:tidy': {
-		script: 'scripts/run/tidy/run-tidy-cli.ts',
+		script: 'scripts/run/tidy/run-tidy-main.ts',
 		description: 'Close merged lanes and drop stashes whose issues are all merged',
 		category: 'AI tools',
 		reference: ['', 'automation', ['git', 'network', 'files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'run:carry': {
 		script: 'scripts/run/carry/run-carry-cli.ts',
@@ -37,15 +96,70 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Carry one invocation’s budget across its own session cuts',
 		category: 'AI tools',
 		reference: ['<operation> [arguments...]', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '--begin "backlogrun --max 5" --owner "$PPID"' },
+				{ arguments: '--json', note: 'read the record back in a resumed session' },
+				{ arguments: '--cut --owner "$PPID"', note: 'hand the record off before a cut' },
+				{
+					arguments:
+						'--retrospective --summary "0 filed; dropped #2240 already merged" --owner "$PPID"',
+					note: 'close the end-of-run retrospective',
+				},
+				{
+					arguments: '--resume "backlogrun --max 5" --owner "$PPID"',
+					note: 'adopt a record no cut handed off',
+				},
+				{
+					arguments: '--end --stopped "epic #2126: everything is blocked behind parked #2118"',
+					note: 'end + push',
+				},
+			],
+			flags: [
+				{
+					names: [OWNER],
+					description:
+						'the long-lived process spending the budget (`$PPID` under a loop); required by counts and `--begin` / `--resume`. A live PID stays `busy` if probes fail.',
+				},
+				{ names: ['--done <issue>'], description: "shrinks a named-issue run's `remaining` list." },
+				{
+					names: ['--merged <issue>'],
+					description:
+						'names the merged issue and counts it once against `merged_issues`, so a merge `run:merge` already recorded is not counted twice.',
+				},
+				{ names: ['--filed', '--cut'], description: 'increments, never totals.' },
+				{
+					names: ['--retrospective'],
+					description:
+						"marks the end-of-run retrospective run, once per invocation, and requires `--summary <text>` — the same close writes that result as one `retrospective` event on the run's event stream (best-effort), so a run that filed zero improvements reads apart from one whose retrospective never ran. Either flag without the other is refused.",
+				},
+				{
+					names: ['--stopped <reason>'],
+					description:
+						'rides on `--end`: the run stopped rather than finished, so one ⏸️ confirmation is pushed with the reason.',
+				},
+				{
+					names: ['--end'],
+					description:
+						'over a live record flushes pending ledger lines once (a failed flush goes to stderr and the record is still cleared); first collects each lane the run launched whose issue merged, exactly as `run:merge` would; keeps the run it removes as the last ended run — its invocation, start and end, one record overwritten by the next `--end` — so `run:board` can still draw a finished run.',
+				},
+			],
+		},
 	},
 	'run:add': {
 		script: 'scripts/run/add/run-add-cli.ts',
 		description: 'Add issues to a live backlogrun, ahead of the queue unless --no-priority',
 		category: 'AI tools',
 		reference: ['<issue...> [--no-priority]', 'automation', ['network', 'files']],
+		usage: {
+			examples: [
+				{ arguments: '101 102', note: 'ahead of the rest of the queue (`#N` works too)' },
+				{ arguments: '101 --no-priority', note: 'at the end of the queue' },
+			],
+		},
 	},
 	'run:wake': {
-		script: 'scripts/run/wake/run-wake-cli.ts',
+		script: 'scripts/run/wake/run-wake-main.ts',
 		// `.env` rather than the ambient environment:
 		// the failure warning needs the Telegram credentials, the same
 		// reasons `notify` and `followup` carry these flags.
@@ -53,48 +167,105 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Wake the next session of a cut backlogrun from outside the conversation',
 		category: 'AI tools',
 		reference: ['[options]', 'automation', ['processes', 'notifications']],
+		usage: {
+			examples: [
+				{ arguments: '--start', note: 'launch the detached supervisor' },
+				{ arguments: '--list', note: 'supervisor state, cut/wake counts, latest progress line' },
+				{ arguments: '--stop', note: 'stop the supervisor alone' },
+				{ arguments: '--loop --interval 30', note: 'run the loop body in the foreground' },
+			],
+		},
 	},
 	'run:cut': {
 		script: 'scripts/run/cut/run-cut-cli.ts',
 		description: 'Cut a lane child before the gate and resume a fresh process',
 		category: 'AI tools',
 		reference: ['[--resume] <issue> [--impl] [--handoff <path>]', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '1839', note: 'take the cut and hand it to a fresh process' },
+				{
+					arguments: '--impl 1839 --handoff .josh/tmp/handoff-1839.json',
+					note: 'cut mid-implementation, carrying the instruction',
+				},
+				{ arguments: '--resume 1839', note: "a fresh process's entry check" },
+				{ arguments: '--end', note: 'clear the record' },
+			],
+		},
+	},
+	'run:park': {
+		script: 'scripts/run/park/run-park-cli.ts',
+		description: 'Park a lane child for a decision, or clear the park',
+		category: 'AI tools',
+		reference: ['<issue> --body-file <path> | <issue> --clear', 'automation', ['files', 'network']],
+		usage: {
+			examples: [
+				{
+					arguments: '1839 --body-file .josh/tmp/park-1839.md',
+					note: 'comment, needs-decision and the local record',
+				},
+				{ arguments: '1839 --clear', note: 'remove needs-decision and the record' },
+			],
+		},
 	},
 	'run:liveness': {
 		script: 'scripts/run/run-liveness-cli.ts',
 		description: 'Say whether a delegated unit is still working, or stopped without reporting',
 		category: 'AI tools',
 		reference: ['<issue> --output <path> [options]', 'automation', ['processes']],
+		usage: {
+			examples: [
+				{ arguments: '1169 --output <path>' },
+				{ arguments: '1169 --output <path> --window 45 --gap 2 --repo joshuafolkken/app-kit' },
+			],
+			flags: [
+				{
+					names: [OUTPUT],
+					description:
+						'absolute, under the home or temp directory; a symlink is followed and size compared as well as mtime.',
+				},
+				{
+					names: ['--process alive | none'],
+					description:
+						"overrides the process trace, which the command otherwise reads itself: the child's own command line (`fullrun #<N>`) or its detached ship supervisor.",
+				},
+				{
+					names: ['--window <min>'],
+					description: 'silent window the file must be frozen for (default 30).',
+				},
+				{ names: ['--gap <sec>'], description: 'spacing between samples (default 5).' },
+				REPO_FLAG,
+			],
+		},
 	},
 	'run:ending': {
 		script: 'scripts/run/run-ending-cli.ts',
 		description: 'Classify how a dispatched lane child ended (merged, cut, abandoned, unreadable)',
 		category: 'AI tools',
 		reference: ['<issue> --output <path> [--repo <owner/repo>]', 'automation', ['network']],
+		usage: {
+			examples: [
+				{ arguments: '2118 --output <path>' },
+				{ arguments: '2118 --output <path> --repo joshuafolkken/app-kit' },
+			],
+			flags: [
+				{
+					names: [OUTPUT],
+					description:
+						"the child's transcript, absolute and under the home or temp directory (validated the same way `run:liveness --output` is).",
+				},
+				REPO_FLAG,
+			],
+		},
 	},
-	'run:progress': {
-		script: 'scripts/run/progress/run-progress-cli.ts',
-		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
-		category: 'AI tools',
-		reference: [
-			'[--once | --wait] [--interval <minutes>] [--hours <hours>] [--repo <owner/repo>] [--output <path>] | --mark | --path',
-			'automation',
-			['files'],
-		],
-	},
-	'run:board': {
-		script: 'scripts/run/board/run-board-cli.ts',
-		// `--every` pushes its frame as a Telegram, so the credentials come from `.env` as for `run:carry`.
-		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
-		description: 'Draw a live board of the running backlogrun, redrawn every second',
-		category: 'AI tools',
-		reference: ['[--once | --chat | --every <minutes>]', 'automation', ['files', 'network']],
-	},
+	...PROGRESS_COMMANDS,
 	'run:prep': {
-		script: 'scripts/run/run-prep-cli.ts',
+		script: 'scripts/run/run-prep-main.ts',
 		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
+		is_bundled: true,
+		usage: { examples: [ISSUE] },
 	},
 	// The entry sequence a lane opened on, folded into one call: claim the tree,
 	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
@@ -107,18 +278,28 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',
 		category: 'AI tools',
 		reference: ['<issue> [--to <command>]', 'automation', ['git', 'network', 'files']],
+		usage: {
+			examples: [
+				{ arguments: '<N>', note: 'a `fullrun`' },
+				{ arguments: '<N> --to halfrun', note: 'a run that goes as far as `halfrun`' },
+			],
+		},
 	},
 	'run:status': {
 		script: 'scripts/run/run-status-cli.ts',
 		description: 'Bundle a run’s read-only status: issue state, cost verdict, carry counters',
 		category: 'AI tools',
 		reference: ['<issue> [--repo <owner/repo>]', 'automation', ['network']],
+		usage: {
+			examples: [ISSUE, { arguments: '<N> --repo <owner/repo>', note: 'a cross-repo child' }],
+		},
 	},
 	'run:next': {
 		script: 'scripts/run/run-next-cli.ts',
 		description: 'Print the next step a fullrun takes, computed from the run’s state',
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
+		usage: { examples: [ISSUE] },
 	},
 	'run:step': {
 		script: 'scripts/run/run-step-cli.ts',
@@ -126,6 +307,13 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 			'Print the run’s next single action, computed from the event stream, carry record and issue state',
 		category: 'AI tools',
 		reference: ['[<issue>]', 'automation', ['network', 'files']],
+		is_bundled: true,
+		usage: {
+			examples: [
+				{ arguments: '<N>', note: "the run's next action for issue <N>" },
+				{ arguments: '', note: "the `backlogrun` parent's next action" },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -0,0 +1,217 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+const OUTPUT = '--output <path>'
+const OWNER = '--owner <pid>'
+const ISSUE_WITH_OPTIONS = '<issue> [options]'
+
+// The merge, review-launch, tail and ship commands, split out of `josh-commands-ai.ts` when each
+// command's usage moved onto its entry (#4185). `AI_COMMANDS` spreads this in at the same place, so the
+// map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const SHIP_COMMANDS: Record<string, CommandEntry> = {
+	'run:merge': {
+		script: 'scripts/run/merge/run-merge-main.ts',
+		description:
+			'Collapse a backlogrun merge event into one call: confirm the child, do the post-merge steps, offer the next child',
+		category: 'AI tools',
+		reference: [ISSUE_WITH_OPTIONS, 'automation', ['git', 'network']],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{
+					arguments: '<N> --epic <E> --repo <owner/repo> --owner "$PPID" --output <path>',
+					note: 'prints the next child number, or a verdict',
+				},
+				{ arguments: '<N> --owner "$PPID"', note: 'backlog offer (no epic)' },
+			],
+			flags: [
+				{
+					names: ['--epic <E>', '--repo <owner/repo>'],
+					description: "offer the epic's next children; omit both for the opted-in backlog.",
+				},
+				{
+					names: [OWNER],
+					description: "the parent's process, so the carry count respects the ownership guard.",
+				},
+				{
+					names: [OUTPUT],
+					description:
+						'the transcript the outage and usage-limit splits read; absent, they are off.',
+				},
+				{
+					names: ['--driver'],
+					description:
+						'the caller is `backlog:drive`, which has no context to cut and asks `backlog:offer` itself, so the merge is never handed back `over` and answers `deferred` in place of the next offer.',
+				},
+			],
+		},
+	},
+	'run:review': {
+		script: 'scripts/run/review/run-review-cli.ts',
+		description:
+			'Start test:pinned and the gate in the background and write the /code-review brief to a file, printing its path, in one call so they overlap (--join to join them; it stops on an unpinned change)',
+		category: 'AI tools',
+		reference: [
+			'[--code-only] [--unpinned-ok "<reason>"] | --join [--fixing] | --pinned | --push',
+			'automation',
+			['processes', 'files', 'git', 'network'],
+		],
+		usage: {
+			examples: [
+				{
+					arguments: '',
+					note: 'detach test:pinned and the gate, write the brief (the interaction brief after it where due) to a file and print its path, then launch a reviewer per brief',
+				},
+				{
+					arguments: '--code-only',
+					note: "josh ship's own open: code's brief alone, since the ship opens the interaction brief itself",
+				},
+				{
+					arguments: '--unpinned-ok "only logs"',
+					note: 'check beside the pair as ever; the join prints the list and the reason and carries on past unpinned places',
+				},
+				{
+					arguments: '--join',
+					note: 'after the review returns: join the gate and test:pinned; exit 3 on an unpinned change',
+				},
+				{
+					arguments: '--join --fixing',
+					note: 'the join when round 1 has fixes to make: no grace on test:pinned, left running; prints the unpinned places the cache already holds',
+				},
+				{
+					arguments: '--pinned',
+					note: "read test:pinned alone (the ship's pre-detach reads it anyway); a lane child returns at once",
+				},
+				{
+					arguments: '--push',
+					note: 'launched by a lane open: push and open the PR at a green gate',
+				},
+			],
+		},
+	},
+	// The post-merge sequence a run closed on, folded into one call: commit the
+	// observation ledger, read the completion citations and decide the release scope. `observations:flush`,
+	// `issue:cite` and `release:scope` were three round trips re-billing the run's full context each.
+	'run:tail': {
+		script: 'scripts/run/run-tail-cli.ts',
+		description:
+			'Close a run in one call: return to the default branch, commit the observation ledger, read the citations, decide the release scope',
+		category: 'AI tools',
+		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '<N>', note: 'the closed issue' },
+				{ arguments: '<N> <follow-up-N>', note: 'and a follow-up filed this run' },
+			],
+		},
+	},
+	// The commit-to-report region a run ships a change on, folded into one call:
+	// the gate, the commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping
+	// (`run:tail`) were four round trips re-billing the run's full context each. It stops at the first
+	// failed step and names it, so the run reads only the step to fix.
+	ship: {
+		script: 'scripts/run/ship/run-ship-cli.ts',
+		// `.env` rather than the ambient environment: parking a lane child past the relaunch cap
+		// sends a Telegram warning, which needs the credentials.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Ship a change in one call: gate, commit/push/PR, the CI-wait merge and the report bookkeeping, stopping at the first failed step',
+		category: 'AI tools',
+		reference: [
+			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review [--unpinned-ok "<reason>"]] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
+			'automation',
+			['git', 'network'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '"<title> #<N>" --body-file <evidence.md>' },
+				{ arguments: '"<title> #<N>" --review', note: 'both review rounds inside the ship' },
+				{ arguments: '--detach "<title> #<N>"', note: 'hand the ship to a supervisor' },
+				{ arguments: '--log <N>', note: "a detached ship's log" },
+			],
+			flags: [
+				{
+					names: ['--body-file <path>'],
+					description:
+						'the PR body carrying the live-execution evidence `followup` gates on; forwarded to `git -y` alone.',
+				},
+				{ names: ['--notify-message <text>'], description: 'forwarded to `followup` alone.' },
+				{
+					names: ['--review'],
+					description:
+						'runs review round 1 beside the gate, and round 2 after the commit when `review:round2` requires it; a High or an unfixed Medium stops the ship. A pre-detach `test:pinned` stop at the first unpinned hunk probes the rest in the background, for the next pre-detach.',
+				},
+				{
+					names: ['--unpinned-ok <reason>'],
+					description:
+						"forwarded to round 1's `run:review`, past `unpinned` places no test can pin.",
+				},
+				{
+					names: ['--detach'],
+					description:
+						'hands the ship to a supervisor (implied in a lane child); a stop emits `ship-stop` (`--log <N>`). The preflight, type check, unused exports, cspell, guard tests and (`--review`, under `--unpinned-ok`, given or recorded, only if round 1 is reused) `test:pinned` precede hand-off, the checks even after a preflight refusal, so one stop reports every failure.',
+				},
+			],
+		},
+	},
+	'ship:wait': {
+		script: 'scripts/run/ship/run-ship-wait-cli.ts',
+		description:
+			'Wait on a detached ship through its gate and review round 1, so a stop there returns to this session (returned | passed | ended | pending)',
+		category: 'AI tools',
+		reference: ['<N>', 'automation', ['files', 'processes']],
+		usage: {
+			examples: [
+				{
+					arguments: '<N>',
+					note: 're-issue it on `pending` while `cost --cut` is `under`; `returned` prints the stop to fix',
+				},
+			],
+		},
+	},
+	'run:event': {
+		script: 'scripts/run/event/run-event-cli.ts',
+		description:
+			'Append to, read or watch the run’s append-only event stream (--append <kind> <text> | --from|--follow <n> | --watch [<n>] | --last)',
+		category: 'AI tools',
+		reference: [
+			'--append <kind> <text> | --from|--follow <n> | --watch [<n>] | --last',
+			'automation',
+			['files'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '--append <kind> <text>', note: 'append one event; prints its position' },
+				{ arguments: '--from <position>', note: 'every event after <position>, in order (JSON)' },
+				{
+					arguments: '--follow <position>',
+					note: 'new events, waiting for one; position on stderr',
+				},
+				{ arguments: '--watch [<position>]', note: 'every new event, rendered, until interrupted' },
+				{ arguments: '--last', note: 'the newest event alone' },
+			],
+		},
+	},
+	'run:report': {
+		script: 'scripts/run/run-report-cli.ts',
+		// `.env` rather than the ambient environment: `--handoff` sends the hand-off confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Generate the session-facing report for this invocation from the run’s event stream (merges, parks, cuts) with the release tail — the same text josh notify sends',
+		category: 'AI tools',
+		reference: ['[--handoff]', 'automation', ['files', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'print the report; the same text josh notify sends' },
+				{
+					arguments: '--handoff',
+					note: 'print the backlogrun hand-off report and send it as the confirmation',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { SHIP_COMMANDS }

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

@@ -1,5 +1,8 @@
 import type { CommandEntry } from './josh-command-types'
 
+const MACHINE_READABLE = 'the verdict and the reason, machine-readable'
+const JSON_FLAG = '--json'
+
 // The `split:assess` command registry, split out of `josh-commands-ai.ts` so that file stays under its
 // 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason. It is spread into `AI_COMMANDS` so the command stays grouped with the other
 // decision oracles under the 'AI tools' category.
@@ -12,6 +15,12 @@ const SPLIT_COMMANDS: Record<string, CommandEntry> = {
 			'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_FLAG, note: MACHINE_READABLE },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-commands-test-check.ts

@@ -0,0 +1,80 @@
+import { gate_plan } from '#scripts/gate/gate-plan'
+import type { CommandEntry } from './josh-command-types'
+
+// The commands that check a change's tests rather than run them, split out of
+// `josh-commands-development.ts` when it reached its line cap (joshuafolkken/kit#5153). `DEV_COMMANDS`
+// spreads this in at the same place, so the map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const TEST_CHECK_COMMANDS: Record<string, CommandEntry> = {
+	'test:declared': {
+		script: 'scripts/test/test-declared.ts',
+		description:
+			'Report whether the working-tree change needs a test (required/exempt/satisfied); --match checks Step 0 declarations on stdin',
+		category: 'Development',
+		reference: ['[--match]', 'developer', ['processes']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: '--match', note: 'check Step 0 declarations on stdin' },
+				{ arguments: '--help', note: 'print usage, including the --match stdin form' },
+			],
+		},
+	},
+	'test:red': {
+		script: 'scripts/test/test-red-main.ts',
+		description:
+			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test/stopped/test-only',
+		category: 'Development',
+		reference: ['', 'developer', ['git', 'processes']],
+		usage: { examples: [{ arguments: '', note: 'red, green, no-test, stopped or test-only' }] },
+	},
+	'test:reach': {
+		script: 'scripts/test/test-reach-cli.ts',
+		description:
+			"Print how many test files each file's imports reach — the count test:related sizes its claim by — one '<count> <file>' line per file",
+		category: 'Development',
+		reference: ['<files...>', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: 'scripts/lane/lane-ledger.ts',
+					note: 'a reach count to measure before and after a change',
+				},
+			],
+		},
+	},
+	'test:pinned': {
+		script: 'scripts/test/test-pinned-main.ts',
+		description:
+			"Revert each changed hunk outside tests and fixtures only they reach, and replace each added file's top-level function bodies with a throw, in a HEAD worktree, run the related tests, and list what no test went red on",
+		category: 'Development',
+		reference: [
+			'[--max <n>] [--record <token>] [--origin <run-review|pre-detach|manual>] [--first-unpinned]',
+			'developer',
+			['git', 'processes'],
+		],
+		...gate_plan.DIRECT_UNIT_CLAIM,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'unpinned <file>:<line> lines; unchecked counted per reason' },
+				{ arguments: '--max 5', note: 'check at most 5 hunks; the rest count as unchecked' },
+				{
+					arguments: '--record <token>',
+					note: 'also leave the answer, under the launch token, for run:review --join',
+				},
+				{
+					arguments: '--origin pre-detach',
+					note: 'name what started the run on its lane ledger row (default manual)',
+				},
+				{
+					arguments: '--first-unpinned',
+					note: 'start no probe once one hunk is unpinned; the rest count as unchecked',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { TEST_CHECK_COMMANDS }