@joshuafolkken/kit 1.1784.0 → 1.2114.0

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

@@ -1,8 +1,9 @@
 import { ports } from '#ports'
-import { core_budget } from '#scripts/gate/core-budget'
+import { core_weights } from '#scripts/gate/core-weights'
 import { gate_plan } from '#scripts/gate/gate-plan'
 import { GATE_COMMAND, type CommandEntry } from './josh-command-types'
 import { AGENT_HOOK_COMMANDS } from './josh-commands-agent-hooks'
+import { TEST_CHECK_COMMANDS } from './josh-commands-test-check'
 
 const NARROWED = { arguments: 'scripts/thing.ts', note: 'narrow by the given files instead' }
 // The unseeded ports are read from `ports/index.js`, their one definition (#818).
@@ -11,7 +12,6 @@ const UNSEEDED: Readonly<Record<string, string | undefined>> = {}
 const FILE_ARGUMENTS = '[files...]'
 const REQUIRED_FILE_ARGUMENTS = '<files...>'
 const FILTER_ARGUMENTS = '[filters...]'
-const MATCH_ARGUMENTS = '[--match]'
 const PATH_ARGUMENTS = '<path...>'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -29,7 +29,11 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/gate/verification-gate.ts',
 		description: 'Run lint, type check, spell check and unit tests concurrently',
 		category: 'Development',
-		reference: ['[--verbose|--force|--no-unit]', 'developer', ['files', 'processes']],
+		reference: [
+			'[--verbose|--force|--no-unit|--static-group=<group>]',
+			'developer',
+			['files', 'processes'],
+		],
 		usage: {
 			examples: [
 				{ arguments: '' },
@@ -44,8 +48,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Check code with prettier and eslint (skips a tool a basic project lacks)',
 		category: 'Development',
 		reference: ['[--changed]', 'developer', ['processes']],
-		core_weight: core_budget.CORE_WEIGHTS.lint,
-		memory_mb: core_budget.MEMORY_MB.lint,
+		core_weight: core_weights.CORE_WEIGHTS.lint,
+		memory_mb: core_weights.MEMORY_MB.lint,
 		usage: {
 			examples: [
 				{ arguments: '' },
@@ -55,11 +59,12 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
-		description: 'Check only the changed files with prettier and eslint (whole tree on fallback)',
+		description:
+			'Check only the changed files with prettier and eslint, and in kit the source guard tests (whole tree on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
-		core_weight: core_budget.CORE_WEIGHTS.lint,
-		memory_mb: core_budget.MEMORY_MB.lint,
+		core_weight: core_weights.CORE_WEIGHTS.lint,
+		memory_mb: core_weights.MEMORY_MB.lint,
 		usage: { examples: [{ arguments: '' }, NARROWED] },
 	},
 	lines: {
@@ -67,8 +72,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: "Print a file's code lines against the max-lines limit and the headroom left",
 		category: 'Development',
 		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
-		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
-		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		core_weight: core_weights.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_weights.MEMORY_MB.eslint_scan,
 		usage: {
 			examples: [{ arguments: 'scripts/hooks/format-edited-file.ts scripts/josh/josh-logic.ts' }],
 		},
@@ -79,12 +84,12 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'Print repository-wide quality totals and durations, and fail when a total grew past the merge-base or a duration past its baseline',
 		category: 'Development',
 		reference: [
-			'[--no-startup | --totals-only | --accept --reason "<why>"]',
+			'[--no-startup | --totals-only [--rerecord] | --accept --reason "<why>"]',
 			'developer',
 			['files'],
 		],
-		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
-		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		core_weight: core_weights.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_weights.MEMORY_MB.metrics,
 		is_kit_only: true,
 		usage: {
 			examples: [
@@ -99,8 +104,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'List refactoring candidates in the changed scope by category and answer clear/candidates',
 		category: 'Development',
 		reference: ['', 'automation', ['processes']],
-		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
-		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		core_weight: core_weights.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_weights.MEMORY_MB.eslint_scan,
 		usage: { examples: [{ arguments: '' }] },
 	},
 	bytes: {
@@ -121,10 +126,11 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			"Print each delivered rule's unaided compliance — runs reached, kept rate, refusals",
 		category: 'AI tools',
-		reference: ['[--refresh]', 'developer', ['files']],
+		reference: ['[--fresh | --refresh]', 'developer', ['files']],
 		usage: {
 			examples: [
-				{ arguments: '' },
+				{ arguments: '', note: 'a reading cached under 15 minutes ago, else measure' },
+				{ arguments: '--fresh', note: 'measure now, whatever the cache holds' },
 				{
 					arguments: '--refresh',
 					note: 'write the reading to the loop-head cache instead of stdout',
@@ -147,16 +153,46 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['files', 'processes']],
 		usage: { examples: [{ arguments: '' }] },
 	},
+	rename: {
+		script: 'scripts/lint/rename-cli.ts',
+		description:
+			'Rename an identifier, and the import specifier it moved with, across files through the TypeScript parse tree',
+		category: 'Development',
+		reference: [
+			'<old-identifier> <new-identifier> [--import <old-specifier> <new-specifier>] <file...>',
+			'automation',
+			['files', 'processes'],
+		],
+		usage: {
+			examples: [
+				{ arguments: 'old_name new_name scripts/a.ts scripts/b.ts' },
+				{
+					arguments:
+						"lane_ledger lane_ledger_write --import '#scripts/lane/lane-ledger' '#scripts/lane/lane-ledger-write' scripts/gate/core-wait-record.ts",
+					note: 'the identifier and its module together',
+				},
+			],
+		},
+	},
 	...AGENT_HOOK_COMMANDS,
 	'cspell:dot': {
 		script: 'scripts/lint/cspell-cached.ts',
 		description: 'Run spell check including dotfiles',
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
-		core_weight: core_budget.CORE_WEIGHTS.spell_check,
-		memory_mb: core_budget.MEMORY_MB.spell_check,
+		core_weight: core_weights.CORE_WEIGHTS.spell_check,
+		memory_mb: core_weights.MEMORY_MB.spell_check,
 		usage: { examples: [{ arguments: '', note: 'includes dotfiles' }] },
 	},
+	'check:related': {
+		script: 'scripts/gate/check-related.ts',
+		description: 'Run related lint, unit, type and dotfile spelling checks in parallel',
+		category: 'Development',
+		reference: ['', 'developer', ['processes']],
+		usage: {
+			examples: [{ arguments: '' }, { arguments: '--full', note: 'whole outputs' }],
+		},
+	},
 	behavior: {
 		script: 'scripts/behavior/behavior-cli.ts',
 		description:
@@ -187,51 +223,16 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Run only the unit tests related to the changed files (full suite on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
-		...gate_plan.DIRECT_UNIT_CLAIM,
 		usage: {
 			examples: [
 				{ arguments: '' },
 				NARROWED,
+				{ arguments: '--touched', note: "only the diff's tests and its modules' same-named ones" },
 				{ arguments: '--silent', note: 'flags are forwarded to vitest' },
 			],
 		},
 	},
-	'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_ARGUMENTS, '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/test-only',
-		category: 'Development',
-		reference: ['', 'developer', ['git', 'processes']],
-		usage: { examples: [{ arguments: '', note: 'red, green, no-test or test-only' }] },
-	},
-	'test:pinned': {
-		script: 'scripts/test/test-pinned-main.ts',
-		description:
-			'Revert each changed non-test hunk in a HEAD worktree, run its related tests, and list the hunks no test went red on',
-		category: 'Development',
-		reference: ['[--max <n>]', 'developer', ['git', 'processes']],
-		...gate_plan.DIRECT_UNIT_CLAIM,
-		usage: {
-			examples: [
-				{ arguments: '', note: 'unpinned / unchecked <file>:<line> lines' },
-				{ arguments: '--max 5', note: 'check at most 5 hunks; the rest print as unchecked' },
-			],
-		},
-	},
+	...TEST_CHECK_COMMANDS,
 	disposition: {
 		script: 'scripts/review/disposition-cli.ts',
 		description:
@@ -267,8 +268,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Type-check with tsc (skips a basic project with no TypeScript to check)',
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
-		core_weight: core_budget.CORE_WEIGHTS.type_check,
-		memory_mb: core_budget.MEMORY_MB.type_check,
+		core_weight: core_weights.CORE_WEIGHTS.type_check,
+		memory_mb: core_weights.MEMORY_MB.type_check,
 		usage: { examples: [{ arguments: '' }] },
 	},
 	port: {

package/scripts/josh/josh-commands-issue-write.ts

@@ -107,13 +107,17 @@ const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		// Releasing the hold runs `run:hold`, which reaches the stop confirmation.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
-		reference: [EVIDENCE_REFERENCE, 'automation', ['network', 'files']],
+		reference: [`${EVIDENCE_REFERENCE} [--unmet]`, 'automation', ['network', 'files']],
 		usage: {
 			examples: [
 				{
 					arguments: '4452 --evidence-file .josh/tmp/measured.md',
 					note: 'comment, label, close, release — in that order',
 				},
+				{
+					arguments: '4452 --unmet --evidence-file .josh/tmp/measured.md',
+					note: 'the measurement fell short of the expected effect: measured:unmet as well',
+				},
 			],
 			flags: [
 				{
@@ -121,16 +125,21 @@ const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
 					description:
 						'the result comment: per acceptance criterion, the measurement and the run it came from. An empty file is refused before anything is written.',
 				},
+				{
+					names: ['--unmet'],
+					description:
+						'the measurement fell short of the expected effect it checked; adds the measured:unmet label `josh effect:audit` reads',
+				},
 			],
 		},
 	},
 	'issue:file': {
 		script: 'scripts/issue/issue-file-cli.ts',
 		description:
-			'File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle',
+			'File an Issue with every filing step: filing cap, fold, local checks (lint, Origin, auto-ok label), start condition and WIP cap, then the duplicate scout once none refuses, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
+			'<title> --body-file <path> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--found-during <N>] [--over-cap] [--no-auto-ok] [--release] [--blocks-finder]',
 			'automation',
 			['network'],
 		],
@@ -159,9 +168,14 @@ const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
 					names: ['--distinct <N,…>'],
 					description: 'duplicate candidates you read and judged distinct.',
 				},
+				{
+					names: ['--found-during <N>'],
+					description:
+						'the Issue whose work the filing came from, when it is not the lane or branch Issue. The filing cap counts per origin (step 2); step 7 never holds it as a candidate here. #N gets a deferral comment.',
+				},
 				{
 					names: ['--over-cap'],
-					description: 'the run is blocked by this filing; the cap lets it through.',
+					description: 'the run is blocked by this filing; the WIP cap lets it through.',
 				},
 				{
 					names: ['--no-auto-ok'],
@@ -172,6 +186,11 @@ const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
 					description:
 						"a consumer can use the change only once it is published. The filed issue becomes a blocker of the target's release issue (step 10).",
 				},
+				{
+					names: ['--blocks-finder'],
+					description:
+						'with `--route interrupt`, the finder cannot go on until this issue is done. The finder is recorded as blocked by the filed issue (step 9); under an epic, `epic --reconcile <E>` after `epic --add` declares it.',
+				},
 			],
 		},
 	},

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

@@ -29,6 +29,13 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<issue>', 'automation', ['network']],
 		usage: { examples: [{ arguments: '3773' }] },
 	},
+	'issue:priority': {
+		script: 'scripts/issue/issue-priority-cli.ts',
+		description: 'Apply priority:high to an issue whose body reached the high floor after filing',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+		usage: { examples: [{ arguments: '4960' }] },
+	},
 	'issue:read': {
 		script: 'scripts/issue/issue-read-main.ts',
 		description: "Print each issue's title, body and every comment on it, in one call",
@@ -97,6 +104,31 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'automation', ['network']],
 		usage: { examples: [{ arguments: '', note: 'every issue labelled bug, open or closed' }] },
 	},
+	'effect:audit': {
+		script: 'scripts/issue/effect-audit-cli.ts',
+		description:
+			'List closed run-time-shortening issues with their expected effect, follow-up measurement and result',
+		category: 'AI tools',
+		reference: ['[--days <N>] [--draft <issue>]', 'automation', ['network', 'files']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'issues closed in the last 30 days, one line each' },
+				{ arguments: '--days 7', note: 'a shorter window' },
+				{
+					arguments: '--draft 4896',
+					note: 'write the retirement candidate of a shortfall and print its issue:file line',
+				},
+			],
+			flags: [
+				{ names: ['--days <N>'], description: 'the window, in days back from now (default 30)' },
+				{
+					names: ['--draft <issue>'],
+					description:
+						'an issue whose measurement carries measured:unmet: write its retirement-candidate body to a temporary file',
+				},
+			],
+		},
+	},
 	'issue:fold': {
 		script: 'scripts/issue/issue-fold-main.ts',
 		description:

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

@@ -16,6 +16,7 @@ const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
 // 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,
@@ -25,7 +26,7 @@ const PAUSE_ARGUMENTS = {
 	script: 'scripts/lane/lane-pause-cli.ts',
 	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	category: 'AI tools',
-	reference: ['<issue> | --all', 'developer', ['processes']],
+	reference: [ISSUE_OR_ALL, 'developer', ['processes']],
 } satisfies Partial<CommandEntry>
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -101,12 +102,12 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 				{
 					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_EFFORT'],
 					description:
-						'role effort overrides for either provider; defaults are `medium`, `medium`, and `high`.',
+						'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); Anthropic defaults are `claude-sonnet-5-5` / `high`, falling back to `JOSH_REVIEWER_*`.',
+						'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_*`.',
 				},
 			],
 		},
@@ -168,6 +169,18 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 			examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
 		},
 	},
+	// `.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 the files a lane child plans to edit, and give the lane back when a running lane that planned earlier declares or plans one of them — naming the file and that issue',
+		category: 'AI tools',
+		reference: ['<issue> <path>... [--probe]', '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,
@@ -182,6 +195,21 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		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': {
@@ -213,7 +241,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, and the duration and reuse count of each gate check last',
+			"Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, the duration and reuse count of each gate check, and each check's core claim against the cores it used",
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],
@@ -221,6 +249,61 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 			examples: [{ arguments: '--period 7', note: "a 7-day period's stage medians and maxima" }],
 		},
 	},
+	// 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 --column), 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 and the host's sleeps",
+		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>', 'maintainer', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: '4970',
+					note: 'the breakdown the overrun investigation comments on the lane',
+				},
+			],
+		},
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

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

@@ -15,10 +15,23 @@ const LINT_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'report:lint': {
 		script: 'scripts/report/report-lint-cli.ts',
-		description: 'Check a two-layer work summary on stdin against its mechanical format rules',
+		description:
+			"Check a two-layer work summary, or with --child-summary a lane child's summary, on stdin against its mechanical format rules",
+		category: 'AI tools',
+		reference: ['[--child-summary] (reads stdin)', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '< summary.md' }, { arguments: '--child-summary < summary.md' }],
+		},
+	},
+	'review:lint': {
+		script: 'scripts/review/review-lint-cli.ts',
+		description:
+			"Check a review's markdown on stdin against the review rubric's output format, round 1 or with --round 2 the verification pass",
 		category: 'AI tools',
-		reference: ['(reads stdin)', 'automation', ['none']],
-		usage: { examples: [{ arguments: '< summary.md' }] },
+		reference: ['[--round <1|2>] (reads stdin)', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '< review.md' }, { arguments: '--round 2 < review.md' }],
+		},
 	},
 	'report:template': {
 		script: 'scripts/report/report-template-cli.ts',

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

@@ -85,6 +85,21 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 			examples: [{ arguments: '', note: 'verify when the lockfile or its policy moved' }],
 		},
 	},
+	'command:derive': {
+		script: 'tools/document/command-derive.ts',
+		description:
+			'Write every artifact the command map derives — usage spans, catalog, snapshot, docs/why.md counts — and print page bytes against their ceilings',
+		category: 'Maintenance',
+		reference: ['', 'maintainer', ['files']],
+		// Kit-only: the pages it writes are kit's own documentation, and the script lives under the
+		// undistributed `tools/`.
+		is_kit_only: true,
+		// The command-map snapshot runs through one single-file vitest run.
+		core_weight: 1,
+		usage: {
+			examples: [{ arguments: '', note: 'after adding, renaming or describing a command' }],
+		},
+	},
 	'audit:provision': {
 		script: 'scripts/security/security-audit-provision-main.ts',
 		description: 'Install the pinned osv-scanner when the audit cannot find one (no-op if present)',

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

@@ -4,7 +4,7 @@ const LEVEL_ONLY = '--level-only'
 const CHECK = '--check'
 const MACHINE_READABLE = 'the verdict and the reason, machine-readable'
 const JSON_FLAG = '--json'
-const ROUND_1_CLOSED = '--round-1-closed'
+const RECORD = '--record'
 
 // The review and delegation 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
@@ -67,22 +67,57 @@ const REVIEW_COMMANDS: Record<string, CommandEntry> = {
 			],
 		},
 	},
+	'review:submit': {
+		script: 'scripts/review/review-submit-cli.ts',
+		description: "Write a ship reviewer's findings, read from stdin, where the ship reads them",
+		category: 'AI tools',
+		reference: ['[--interaction] < findings | [--interaction] --none', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '< findings.txt', note: 'the /code-review slot' },
+				{ arguments: '--interaction < findings.txt', note: 'the interaction review slot' },
+				{ arguments: '--none', note: 'a review with no findings' },
+			],
+			flags: [
+				{
+					names: ['--none'],
+					description: 'a review with no findings; empty stdin without it is refused.',
+				},
+			],
+		},
+	},
+	// The self-check's "Prose matches the code" as a search: each word the diff removed that prose still names.
+	'prose:stale': {
+		script: 'scripts/review/prose-stale-cli.ts',
+		description:
+			'List each removed declared or exported name, josh command, UPPER_CASE constant or .md heading that docs, prompts or comments still name',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: '',
+					note: '→ `file:line kind word` per reference, or `ok` (exit 1 / 0; 2 on a failure)',
+				},
+			],
+		},
+	},
 	'review:round2': {
 		script: 'scripts/review/review-round2-cli.ts',
 		description: 'Say whether the second /code-review round is due, or may be skipped entirely',
 		category: 'AI tools',
-		reference: ['[--round-1-closed] [--json]', 'automation', ['none']],
+		reference: ['[--record <N>] [--json]', 'automation', ['network']],
 		usage: {
 			examples: [
-				{ arguments: '', note: '→ required' },
-				{ arguments: ROUND_1_CLOSED, note: '→ required | skip' },
+				{ arguments: '', note: '→ required | skip, for the branch’s issue' },
+				{ arguments: `${RECORD} 123`, note: '→ required | skip, a skip commented on that issue' },
 				{ arguments: JSON_FLAG, note: MACHINE_READABLE },
 			],
 			flags: [
 				{
-					names: [ROUND_1_CLOSED],
+					names: [RECORD],
 					description:
-						'the caller states every round-1 High/Medium finding closed and none was filed or deferred; its absence answers `required`.',
+						'the issue whose ledger dispositions decide round 1’s closure — skip only when every High/Medium is `fixed` or `false-positive` — and where a skip is commented under `## Round 2 skipped`, once.',
 				},
 				{ names: [JSON_FLAG], description: 'machine-readable verdict and reason.' },
 			],