@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,5 +1,8 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
+const CHECK = '--check'
+const JSON_FLAG = '--json'
+
 /* eslint-disable @typescript-eslint/naming-convention */
 const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 	doctor: {
@@ -9,6 +12,21 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Maintenance',
 		reference: ['[--fix]', 'developer', ['files']],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'diagnose only' },
+				{ arguments: '--fix', note: 'reclaim the global josh by removing a stale kit shim' },
+				{ arguments: '--ports', note: 'also print the per-repository port-seed table' },
+			],
+			flags: [
+				{
+					names: ['--fix'],
+					description:
+						'remove a shadowing binary **only if it is a kit shim** (its body references `@joshuafolkken/kit` or the removed `install-bin` script); any other binary is left and reported for manual review. Also the one-shot recovery for an old project that re-created the global shim.',
+				},
+				{ names: ['--ports'], description: 'additionally print the port-seed table (see below).' },
+			],
+		},
 	},
 	'ruleset:check': {
 		script: 'scripts/repo/ruleset-check-cli.ts',
@@ -16,30 +34,94 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 			"Check that the default branch requires every status check kit's workflows report (--apply adds the missing ones)",
 		category: 'Maintenance',
 		reference: ['[--apply]', 'maintainer', ['network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'report only' },
+				{ arguments: '--apply', note: 'add the missing checks to the existing rule' },
+			],
+			flags: [
+				{
+					names: ['--apply'],
+					description:
+						"append the missing checks to the ruleset's required-checks rule (or to the branch protection's contexts). It never creates a ruleset: with none, create one under Settings → Rules → Rulesets, then rerun. Writing a repository setting needs admin access, so only this flag writes — `josh sync` and `josh doctor` never do.",
+				},
+			],
+		},
 	},
 	overrides: {
 		script: 'scripts/overrides/overrides-check.ts',
 		description: 'Check pnpm overrides for drift',
 		category: 'Maintenance',
 		reference: ['[--save]', 'developer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'verify overrides unchanged' },
+				{ arguments: '--save', note: 'snapshot current merged overrides' },
+			],
+			flags: [
+				{
+					names: ['--save'],
+					description:
+						'write the current merged overrides to `.overrides-snapshot.json` (gitignored); later runs compare against it and exit non-zero on any add, removal, or change.',
+				},
+			],
+		},
 	},
 	audit: {
-		script: 'scripts/security/security-audit.ts',
+		script: 'scripts/security/security-audit-main.ts',
 		description: 'Run security audit',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['processes']],
+		usage: { examples: [{ arguments: '' }] },
+	},
+	'lockfile:policy': {
+		script: 'tools/security/lockfile-policy.ts',
+		description:
+			"Verify the lockfile against pnpm's supply-chain policy (minimumReleaseAge) when it or the policy moved from the merge-base",
+		category: 'Maintenance',
+		reference: ['', 'automation', ['network']],
+		is_kit_only: true,
+		usage: {
+			examples: [{ arguments: '', note: 'verify when the lockfile or its policy moved' }],
+		},
 	},
 	'audit:provision': {
-		script: 'scripts/security/security-audit-provision.ts',
+		script: 'scripts/security/security-audit-provision-main.ts',
 		description: 'Install the pinned osv-scanner when the audit cannot find one (no-op if present)',
 		category: 'Maintenance',
 		reference: ['', 'automation', ['files', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'no-op if a scanner is already present' },
+				{ arguments: '--force', note: 'ignore backoff, allow a longer download' },
+			],
+			flags: [
+				{
+					names: ['--force'],
+					description:
+						'ignore the 6-hour failure backoff and allow a longer download window; the command to run after fixing a network problem.',
+				},
+			],
+		},
 	},
 	'reconcile-templates': {
 		script: 'scripts/sync/reconcile-templates.ts',
 		description: 'Record template source hashes (--check to verify drift)',
 		category: 'Maintenance',
 		reference: ['', 'maintainer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'regenerate copy templates + record tripwire hashes' },
+				{ arguments: CHECK, note: 'verify templates are in sync; non-zero on drift' },
+			],
+			flags: [
+				{
+					names: [CHECK],
+					description:
+						'verify only; exits non-zero on drift. A pre-commit hook runs this when a tracked source or copy template is staged.',
+				},
+			],
+		},
 	},
 	latest: {
 		shell: [
@@ -51,9 +133,10 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network', 'processes']],
 		argument_targets: ['latest:corepack', 'latest:update', 'audit'],
+		usage: { examples: [{ arguments: '', note: 'full update (update + audit + pnpm)' }] },
 	},
 	'latest:scope': {
-		script: 'scripts/version/latest-scope-cli.ts',
+		script: 'scripts/version/latest-scope-main.ts',
 		description:
 			'Say whether this run has to update dependencies, from when josh latest last finished (--record notes a run)',
 		category: 'Maintenance',
@@ -62,18 +145,42 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		// where the project keeps its settings — a variable that only works when exported from the
 		// shell is one a user follows the documentation for and gets the default from, silently.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'required or skip, the reason on stderr' },
+				{ arguments: '--record', note: 'note a finished josh latest run' },
+				{ arguments: JSON_FLAG, note: 'the verdict and the reason as JSON' },
+			],
+			flags: [
+				{
+					names: ['--record'],
+					description: 'write the completion record `josh latest` ends with.',
+				},
+				{ names: [JSON_FLAG], description: 'emit the verdict and its reason as JSON.' },
+			],
+		},
+	},
+	'latest:if-required': {
+		script: 'scripts/version/latest-if-required-cli.ts',
+		description: 'Run josh latest only when latest:scope answers required, stashing around it',
+		category: 'Maintenance',
+		reference: ['', 'automation', ['files', 'network', 'processes']],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: { examples: [{ arguments: '', note: 'stash, update, pop on required' }] },
 	},
 	'latest:guard': {
-		script: 'scripts/version/latest-lane-guard.ts',
+		script: 'scripts/version/latest-lane-guard-main.ts',
 		description: 'Refuse josh latest inside a lane (the update stamp is keyed to the project root)',
 		category: 'Maintenance',
 		reference: ['', 'automation', ['files']],
+		usage: { examples: [{ arguments: '', note: 'refuses inside a lane' }] },
 	},
 	'latest:corepack': {
 		script: 'scripts/version/latest-corepack.ts',
 		description: 'Update pnpm on the current major while preserving the integrity pin',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network']],
+		usage: { examples: [{ arguments: '', note: 'update pnpm only' }] },
 	},
 	'latest:update': {
 		script: 'scripts/version/latest-update.ts',
@@ -83,6 +190,7 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		// `JOSH_PLAYWRIGHT_BROWSERS` widens the browsers a Playwright bump installs, and a project
 		// keeps that setting in its `.env`.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: { examples: [{ arguments: '', note: 'update dependencies only' }] },
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -0,0 +1,29 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+// `run:pause`, split out of `josh-commands-run.ts` so that file stays under its 300-code-line limit,
+// as `PROGRESS_COMMANDS` is. `RUN_COMMANDS` spreads this in after `run:release`, so the map keeps
+// the order the run reads them in.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const PAUSE_COMMANDS: Record<string, CommandEntry> = {
+	'run:pause': {
+		script: 'scripts/run/pause/run-pause-cli.ts',
+		description: 'Set a run aside while its prerequisite lands first',
+		category: 'AI tools',
+		// `run:release` underneath can send the stop confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		reference: ['<issue> --for <prerequisite>', 'automation', ['git', 'network', 'files']],
+		usage: {
+			examples: [{ arguments: '1091 --for 1102', note: 'pause 1091 until 1102 lands' }],
+			flags: [
+				{
+					names: ['--for <prerequisite>'],
+					description: 'the issue that has to land first; `<issue>` is recorded blocked by it.',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { PAUSE_COMMANDS }

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

@@ -0,0 +1,87 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+// The run's progress and board commands, split out of `josh-commands-run.ts` when each command's
+// usage moved onto its entry (#4185). `RUN_COMMANDS` spreads this in at the same place, so the map
+// keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const PROGRESS_COMMANDS: Record<string, CommandEntry> = {
+	'run:progress': {
+		script: 'scripts/run/progress/run-progress-main.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'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '--output <path>' },
+				{ arguments: '--once', note: 'five labelled lines now, whatever the clock says' },
+				{ arguments: '--interval 20 --repo joshuafolkken/app-kit --hours 4' },
+			],
+			flags: [
+				{
+					names: ['--mark'],
+					description:
+						'record that a real report happened without printing a line (keeps the last line for `run:wake --list`).',
+				},
+				{
+					names: ['--path'],
+					description:
+						'print the ambient heartbeat log\'s path and exit. Every heartbeat line is mirrored there, so `tail -F "$(pnpm josh run:progress --path)"` follows the run across a `backlogrun` session cut. Reads no run state, so it answers in a lane child too.',
+				},
+				{
+					names: ['--interval <min>'],
+					description:
+						'silence interval (default 20; also `JOSH_PROGRESS_INTERVAL_MINUTES`, then `josh.progress_interval_minutes`).',
+				},
+				{
+					names: ['--wait'],
+					description:
+						'start once in the background: each report goes to the event stream and ambient log, never stdout; exits only on an arrival, `josh followup` ending the run, or `--hours`.',
+				},
+				{
+					names: ['--hours <n>'],
+					description: 'how long the watcher lives (default 8 with `--wait`, 1 otherwise).',
+				},
+				{ names: ['--repo <owner/name>'], description: 'scopes the read.' },
+			],
+		},
+	},
+	'run:board': {
+		script: 'scripts/run/board/run-board-main.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']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'redraw until interrupted' },
+				{ arguments: '--once', note: 'one frame, then exit' },
+				{ arguments: '--chat', note: 'one frame for a chat, recorded as a progress report' },
+				{
+					arguments: '--every 5',
+					note: 'the --chat frame as a 📊 Progress Telegram every 5 minutes, until the run ends',
+				},
+			],
+			flags: [
+				{
+					names: ['--chat'],
+					description:
+						'answers a `backlogrun` progress question: the frame `--once` draws, with only `🧠` on the machine line and no escapes; it records the report as `run:progress --mark` does.',
+				},
+				{
+					names: ['--every <minutes>'],
+					description:
+						'sends the `--chat` frame as a `📊 Progress` Telegram now and every `<minutes>` until the run ends — only when a person asks for it.',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { PROGRESS_COMMANDS }

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

@@ -1,5 +1,13 @@
 import type { CommandEntry } from './josh-command-types'
 
+const STAGED = '--staged'
+const JSON_FLAG = '--json'
+const BRANCH_DIFF = 'the branch diff'
+const STAGED_DIFF = 'the staged diff instead'
+const PR_NUMBER = '42'
+const DRY_RUN = '--dry-run'
+const SKIP_PUBLISH_WAIT = '--skip-publish-wait'
+
 // Command names are the CLI's, not TypeScript's: a scoped one carries a colon (`sync:scope`), which
 // no identifier format allows. The same disable sits at the top of `josh-commands-maintenance.ts`
 // for the same reason.
@@ -11,6 +19,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Show the project profile and the reason for it',
 		category: 'Project',
 		reference: [PROFILE_ARGUMENTS, 'developer', ['files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	start: {
 		script: 'scripts/init/start.ts',
@@ -21,13 +30,39 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'asks for the profile and the repository' },
+				{
+					arguments: '--yes --github --profile basic',
+					note: 'unattended, including the GitHub repository',
+				},
+			],
+			flags: [
+				{ names: ['--profile basic|full'], description: 'the profile, without asking.' },
+				{ names: ['--yes'], description: 'take the defaults — not consent to write to GitHub.' },
+				{ names: ['--github'], description: 'create the GitHub repository and push `main`.' },
+				{ names: ['--public'], description: 'create the repository public instead of private.' },
+				{
+					names: ['--init-command "<command>"'],
+					description: 'run this setup command in place of `josh init`.',
+				},
+				{
+					names: ['--push-preflight-command "<command>"'],
+					description:
+						'a check run before the first step when the plan pushes; a failure stops the run before it writes anything.',
+				},
+				{ names: ['--dry-run'], description: 'print the plan and change nothing.' },
+			],
+		},
 	},
 	'dogfood:commit': {
-		script: 'scripts/dogfood/dogfood-commit-cli.ts',
+		script: 'tools/dogfood/dogfood-commit-cli.ts',
 		description: "Make the first commit of a dogfood run's own kit-test-* project",
 		category: 'Project',
 		reference: ['<dir>', 'automation', ['files', 'git']],
 		is_kit_only: true,
+		usage: { examples: [{ arguments: '~/Development/kit-test-html-start' }] },
 	},
 	'fresh:run': {
 		script: 'scripts/fresh-machine/fresh-machine-cli.ts',
@@ -39,6 +74,35 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			'maintainer',
 			['files', 'network', 'processes'],
 		],
+		usage: {
+			examples: [
+				{ arguments: '--list', note: "kit's six patterns" },
+				{ arguments: 'kit-test-html-init', note: 'one pattern, the packed checkout' },
+				{
+					arguments: 'kit-test-html-start',
+					note: 'a GitHub pattern, the latest published version',
+				},
+				{ arguments: '--spec fresh/html-init.json', note: 'a scenario another toolkit wrote' },
+			],
+			flags: [
+				{ names: ['--list'], description: 'print the pattern names and run nothing.' },
+				{
+					names: ['--spec <file.json>'],
+					description:
+						'run the scenario in this file instead of a named pattern; the path is relative to the project root.',
+				},
+				{
+					names: ['--package-version <version>'],
+					description:
+						"the published version a `package_source: published` scenario installs. Default: the registry's latest version of the package the command is run from.",
+				},
+				{
+					names: ['--log-dir <dir>'],
+					description: 'where the log is written. Default: `.josh/tmp/fresh-machine`.',
+				},
+				{ names: ['--rebuild'], description: 'build the machine image without the layer cache.' },
+			],
+		},
 	},
 	'auth:setup': {
 		script: 'scripts/auth/auth-setup-cli.ts',
@@ -46,9 +110,15 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			'Save the long-lived Claude Code token `claude setup-token` prints in the macOS keychain, for josh fresh:run',
 		category: 'Project',
 		reference: ['[--check]', 'maintainer', ['network', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'sign in and save the token' },
+				{ arguments: '--check', note: 'ok: … saved on <date>, or missing: … and exit 1' },
+			],
+		},
 	},
 	init: {
-		script: 'scripts/init/init.ts',
+		script: 'scripts/init/init-main.ts',
 		description: 'Initialize config in a new project',
 		category: 'Project',
 		reference: [
@@ -56,30 +126,50 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			'developer',
 			['files', 'network', 'processes'],
 		],
+		usage: {
+			examples: [
+				{
+					arguments: '',
+					note: 'create/merge config files, install and format (--no-install skips both, --dry-run only prints the plan)',
+				},
+			],
+		},
 	},
 	sync: {
-		script: 'scripts/sync/sync.ts',
+		script: 'scripts/sync/sync-main.ts',
 		description: 'Sync config files',
 		category: 'Project',
 		reference: ['', 'developer', ['files']],
+		usage: { examples: [{ arguments: '', note: 'overwrite managed files' }] },
 	},
 	uninstall: {
 		script: 'scripts/uninstall/uninstall.ts',
 		description: 'Remove what kit added to a project and list what is left to review by hand',
 		category: 'Project',
 		reference: [`${PROFILE_ARGUMENTS} [--yes]`, 'developer', ['files', 'processes']],
-	},
-	'registry:migrate': {
-		script: 'scripts/registry-migration/migrate.ts',
-		description: 'Migrate a project from GitHub Packages to public npm',
-		category: 'Project',
-		reference: ['', 'developer', ['files', 'network', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'show the plan, then ask' },
+				{ arguments: '--yes', note: 'remove without asking' },
+			],
+		},
 	},
 	'sync:scope': {
 		script: 'scripts/sync/managed-config-scope-cli.ts',
 		description: 'Say whether this change touches a file josh sync distributes',
 		category: 'Project',
 		reference: ['[--staged] [--json]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: BRANCH_DIFF },
+				{ arguments: STAGED, note: STAGED_DIFF },
+				{ arguments: JSON_FLAG, note: '{"scope":"managed","reason":"..."}' },
+			],
+			flags: [
+				{ names: [STAGED], description: 'inspect the staged diff instead of the branch diff.' },
+				{ names: [JSON_FLAG], description: 'emit `{"scope","reason"}` as JSON.' },
+			],
+		},
 	},
 	'sonar:hotspots': {
 		script: 'scripts/sonar/sonar-hotspots-cli.ts',
@@ -87,18 +177,26 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			"Fetch SonarCloud hotspots on a pull request and print each one's Step B disposition",
 		category: 'Project',
 		reference: ['<PR>', 'automation', ['network']],
+		usage: { examples: [{ arguments: PR_NUMBER }] },
 	},
 	'sonar:new-code': {
 		script: 'scripts/sonar/sonar-new-code-cli.ts',
 		description: 'Fail when a pull request adds any new SonarCloud issue or duplicated block',
 		category: 'Project',
 		reference: ['<PR>', 'automation', ['network']],
+		usage: { examples: [{ arguments: PR_NUMBER }] },
 	},
 	'ui:routes': {
 		script: 'scripts/ui/ui-routes-cli.ts',
 		description: 'List the screenshot-target routes the current change touches',
 		category: 'Project',
 		reference: ['[--staged]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: BRANCH_DIFF },
+				{ arguments: STAGED, note: STAGED_DIFF },
+			],
+		},
 	},
 	propagate: {
 		script: 'scripts/propagate/propagate.ts',
@@ -109,12 +207,43 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			'maintainer',
 			['files', 'network'],
 		],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: DRY_RUN, note: 'report targets and steps, write nothing' },
+				{ arguments: SKIP_PUBLISH_WAIT, note: 'release already known to be published' },
+				{ arguments: '--target app-kit', note: 'carry the release into one consumer only' },
+			],
+			flags: [
+				{
+					names: [DRY_RUN],
+					description:
+						'report targets and steps without writing; skips the publish wait, opens no issues.',
+				},
+				{
+					names: [SKIP_PUBLISH_WAIT],
+					description: 'skip the registry poll for an already-published release.',
+				},
+				{
+					names: ['--target <repo>'],
+					description:
+						'process only that consumer (`app-kit` or `joshuafolkken/app-kit`); the rest are reported `skipped` and left untouched. An unknown, ambiguous or non-dependent name fails before the publish wait, writing nothing.',
+				},
+			],
+		},
 	},
 	adopt: {
 		script: 'scripts/adopt/adopt.ts',
 		description: 'Upgrade the @joshuafolkken toolkits and other dependencies here, open the PR',
 		category: 'Project',
 		reference: ['[--dry-run]', 'developer', ['files', 'git', 'network', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: '--dry-run', note: 'report the steps without touching anything' },
+			],
+			flags: [{ names: ['--dry-run'], description: 'report the plan without writing.' }],
+		},
 	},
 }
 

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

@@ -0,0 +1,124 @@
+import type { CommandEntry } from './josh-command-types'
+
+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'
+
+// 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
+// order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const REVIEW_COMMANDS: Record<string, CommandEntry> = {
+	'review:brief': {
+		script: 'scripts/review/review-brief-main.ts',
+		description:
+			'Print the whole /code-review invocation: level, what the gate already proved, target (--level-only for the level alone)',
+		category: 'AI tools',
+		reference: [
+			'[--round <1|2>] | --interaction | --level-only [--staged] [--json]',
+			'automation',
+			['files'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'round 1' },
+				{ arguments: '--round 2', note: 'verification pass, scoped to the fix delta' },
+				{ arguments: '--interaction', note: 'the interaction review of a run-tooling change' },
+				{ arguments: LEVEL_ONLY, note: 'the level alone (pre-commit review)' },
+				{ arguments: '--level-only --json', note: 'level and reason, machine-readable' },
+			],
+			flags: [
+				{
+					names: ['--round 2'],
+					description:
+						"target is round 1's fixes and nothing else (widened back to the whole change when the record's change base no longer matches).",
+				},
+				{
+					names: [LEVEL_ONLY],
+					description:
+						'print the level alone (level to stdout, reason to stderr); bypasses the scoped-green refusal.',
+				},
+				{
+					names: ['--staged', '--json'],
+					description: 'the staged diff; machine-readable level and reason.',
+				},
+			],
+		},
+	},
+	'review:attest': {
+		script: 'scripts/review/review-attest-cli.ts',
+		description: 'Record, or verify, which checkout a /code-review actually read',
+		category: 'AI tools',
+		reference: ['<nonce> | --check', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '<nonce>', note: 'run by the review, from the checkout it read' },
+				{ arguments: CHECK, note: 'run by the run, before it acts on the review' },
+			],
+			flags: [
+				{ names: ['<nonce>'], description: 'attest the checkout the review read.' },
+				{
+					names: [CHECK],
+					description: 'verify before acting; `josh followup` asks again before merging.',
+				},
+			],
+		},
+	},
+	'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']],
+		usage: {
+			examples: [
+				{ arguments: '', note: '→ required' },
+				{ arguments: ROUND_1_CLOSED, note: '→ required | skip' },
+				{ arguments: JSON_FLAG, note: MACHINE_READABLE },
+			],
+			flags: [
+				{
+					names: [ROUND_1_CLOSED],
+					description:
+						'the caller states every round-1 High/Medium finding closed and none was filed or deferred; its absence answers `required`.',
+				},
+				{ names: [JSON_FLAG], description: 'machine-readable verdict and reason.' },
+			],
+		},
+	},
+	delegate: {
+		script: 'scripts/delegation/delegation-cli.ts',
+		description: 'Say whether a run step may go to a cheaper execution tier',
+		category: 'AI tools',
+		reference: ['<step> | --list', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'gate-fix', note: '→ delegate' },
+				{ arguments: 'review', note: '→ keep' },
+				{ arguments: '--list', note: 'the enumeration, and what was rejected and why' },
+			],
+		},
+	},
+	fanout: {
+		script: 'scripts/delegation/fanout-cli.ts',
+		description:
+			'Say whether proposed implementation units are file-disjoint, so they may run in parallel',
+		category: 'AI tools',
+		reference: ['<unit-files> <unit-files> [<unit-files> …]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'scripts/a.ts,scripts/a.test.ts scripts/b.ts', note: '→ parallel' },
+				{
+					arguments: 'scripts/a.ts,shared.ts scripts/b.ts,shared.ts',
+					note: '→ serial (units share shared.ts)',
+				},
+				{ arguments: 'scripts/a.ts', note: '→ serial (fewer than two units)' },
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { REVIEW_COMMANDS }