@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,226 @@
+import { ENV_FILE_NAME } from '#ports'
+
+// The file, loaded only when it is there. The filename comes from the module that reads the same
+// file from inside `playwright.config.ts`, so the two readers of `.env` cannot end up pointed at two
+// different files (#820).
+//
+// **There is no mandatory counterpart any more.** `--env-file=.env` aborts before the script's first
+// line when the file is missing, which is wrong for every command kit ships: `doctor` runs from
+// anywhere, including a directory with no project at all (joshuafolkken/kit#869), and `notify` /
+// `followup` run in cloud sessions that carry their credentials as environment variables and keep no
+// `.env` at all (joshuafolkken/kit#1564). A command that needs a value to be present says so itself,
+// where it can name what is missing.
+const OPTIONAL_ENV_FILE_FLAGS: ReadonlyArray<string> = [`--env-file-if-exists=${ENV_FILE_NAME}`]
+
+type CommandCategory =
+	'Development' | 'Project' | 'Workflow' | 'Versioning' | 'Maintenance' | 'Git hooks' | 'AI tools'
+
+// The two vocabularies are runtime tuples the types are derived from, rather than bare unions. A
+// union exists only at compile time, so the completeness test and the generated reference
+// (joshuafolkken/kit#2064) would each have to restate the values to check or render them — two
+// copies that drift apart silently. Deriving the type from the tuple keeps one definition.
+const COMMAND_AUDIENCES = ['developer', 'maintainer', 'automation'] as const
+const COMMAND_SIDE_EFFECTS = [
+	'none',
+	'files',
+	'git',
+	'network',
+	'processes',
+	'notifications',
+	'release',
+] as const
+
+type CommandAudience = (typeof COMMAND_AUDIENCES)[number]
+type CommandSideEffect = (typeof COMMAND_SIDE_EFFECTS)[number]
+// The synopsis is a claim about the command's own parser, not a summary of its description, and
+// `josh-command-reference.test.ts` checks it against that parser. Three rules keep it honest: an
+// empty string means the command takes no arguments at all — never "it takes some we did not list";
+// a flag that only reformats output, `--json` among them, is named like any other; and a positional
+// appears only where the script actually reads one.
+type CommandReference = readonly [
+	arguments_synopsis: string,
+	audience: CommandAudience,
+	side_effects: ReadonlyArray<CommandSideEffect>,
+]
+
+interface CommandEntry {
+	script?: string
+	shell?: ReadonlyArray<string>
+	description: string
+	category: CommandCategory
+	reference: CommandReference
+	tsx_arguments?: ReadonlyArray<string>
+	default_script_arguments?: ReadonlyArray<string>
+	// 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>
+	// 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 (joshuafolkken/kit#1988). The audience in
+	// `reference` separately decides whether the command appears in the default listing.
+	is_kit_only?: boolean
+}
+
+// The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a
+// consumer of the name — the command map, `propagate` — does not import the script module: that
+// module carries a `process.argv[1] === import.meta.url` main guard, and esbuild bundles every
+// import into one `dist/josh.js` where that guard matches on *any* `josh` invocation
+// (joshuafolkken/kit#914).
+const GATE_COMMAND = 'gate'
+
+const PE = ['pnpm', 'exec'] as const
+
+// joshuafolkken/kit#1256: three of the gate's four checks keep a content-addressed cache, so a
+// second run reads only what changed. eslint had one from the start; the type check and the spell
+// check rescanned the whole tree every time, which cost 10.5s of CPU against 2.8s cached.
+//
+// Neither of those two needs an invalidation rule of its own. `tsc` records the compiler options
+// inside the build-info file and re-checks everything when they differ, and `cspell` records a
+// content hash of every config and dictionary file it loaded as that entry's dependency — so editing
+// `tsconfig.json` or `cspell.config.yaml` invalidates what it should. CI restores only the eslint
+// cache (`.github/workflows/ci.yml` → "Setup ESLint cache"); the other two start every run cold.
+//
+// **eslint's does need one, and it is not here** (joshuafolkken/kit#1347). ESLint hashes the
+// *serialized* config, which drops every rule's `create`, so editing `eslint/rules/*.js` left every
+// cached entry valid on every cache file below. The fix is a content fingerprint of the rule modules
+// carried in the shared config's `settings` — `eslint/config-fingerprint.js` — because one value
+// there invalidates the gate's cache, the scoped one and the edit hook's at once, while a rule
+// written per cache file would have to be repeated for each and would go stale one file at a time.
+//
+// Every location is passed explicitly rather than left to the tool's default, eslint's included:
+// the ignore rules have to name the same paths, and a constant that merely copies a default is
+// wrong the moment the default moves without anything failing. `IGNORED_CACHE_FILES` below is what
+// the ignore rules are asserted against — `.gitignore` (which `useGitignore` also makes the spell
+// check's exclusion) and the distributed `cspell/index.yaml`, which does not wait for a
+// `josh sync` to reach a consumer.
+const ESLINT_CACHE_FILE = '.eslintcache'
+const TS_BUILD_INFO_FILE = '.tsbuildinfo'
+const CSPELL_CACHE_FILE = '.cspellcache'
+const ESLINT_EDIT_CACHE_FILE = '.eslintcache.edit'
+const ESLINT_RELATED_CACHE_FILE = '.eslintcache.related'
+
+type GateCachePortability = 'raw' | 'rooted-json'
+
+interface GateCacheSpec {
+	cache_file: string
+	portability: GateCachePortability
+}
+
+const ROOTED_JSON_PORTABILITY: GateCachePortability = 'rooted-json'
+
+// One declaration controls both the one-time lane seed and the caches a gate keeps current across
+// worktrees (#2060). ESLint stores absolute file paths and must be rebased; cspell stores relative
+// keys and can move byte-for-byte. TypeScript's build info is still seeded once, but is not
+// continuously published until its dependency-path portability is established on every project.
+const ESLINT_CACHE_SPEC: GateCacheSpec = {
+	cache_file: ESLINT_CACHE_FILE,
+	portability: ROOTED_JSON_PORTABILITY,
+}
+const TS_CACHE_SPEC: GateCacheSpec = {
+	cache_file: TS_BUILD_INFO_FILE,
+	portability: 'raw',
+}
+const CSPELL_CACHE_SPEC: GateCacheSpec = {
+	cache_file: CSPELL_CACHE_FILE,
+	portability: 'raw',
+}
+const ESLINT_RELATED_CACHE_SPEC: GateCacheSpec = {
+	cache_file: ESLINT_RELATED_CACHE_FILE,
+	portability: ROOTED_JSON_PORTABILITY,
+}
+const GATE_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
+	ESLINT_CACHE_SPEC,
+	TS_CACHE_SPEC,
+	CSPELL_CACHE_SPEC,
+]
+const SHARED_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
+	ESLINT_CACHE_SPEC,
+	ESLINT_RELATED_CACHE_SPEC,
+	CSPELL_CACHE_SPEC,
+]
+const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => spec.cache_file)
+
+// joshuafolkken/kit#1332: the `PostToolUse` edit hook runs eslint too, and ESLint *deletes* the file
+// at `--cache-location` whenever it is started without `--cache` — so every single edit wiped the
+// cache the gate had just filled, and both gates of run joshuafolkken/kit#1326 paid a cold lint
+// (59.4s and 54.5s, against 3.0s warm). The hook is given a location of its own rather than the
+// gate's because the two run at the same time: `josh gate` lints the whole tree beside the review
+// while this hook fires on every edit, and each eslint run rewrites its cache file whole from the
+// copy it loaded at start-up — so two writers silently discard each other's entries. A file of its
+// own makes the hook structurally unable to degrade the cache this exists to protect.
+//
+// **Pruning is not the reason**, though it reads like one: `file-entry-cache` defaults `noPrune` to
+// true, and a single-file run against the gate's full cache was measured byte-identical, so a shared
+// file would keep the entries that run never visited.
+// joshuafolkken/kit#1347: the same reasoning, reached a second time. `josh lint:related` is what an
+// implementation loop calls between edits, and `josh gate` lints the whole tree beside the review —
+// so those two run at the same time as readily as the hook and the gate do, and they shared one file
+// until this constant existed. Whichever of the pair wrote last replaced the file with "the copy I
+// loaded at start-up plus what I visited", so a narrowed run finishing during a whole-tree run rolled
+// the cache back to its pre-gate state, and a whole-tree run finishing second discarded the narrowed
+// one's entries.
+//
+// **The warming this gives up is worth less than the entries it stops losing.** The comment this
+// replaced argued the shared file let a narrowed run warm the gate's cache, which is true only while
+// the two never overlap; a file of its own is warm from its own second call onwards, and the gate's
+// stays exactly as the gate left it.
+//
+// **The lint's target scope is untouched.** This is where a cache is written, not what is read:
+// `josh lint:related` narrows in front of the gate and `josh gate` still runs `josh lint` over the
+// whole tree before any commit.
+// What the ignore rules are asserted against: every cache file this package writes, wherever it is
+// written from. The gate's three, the edit hook's, and the scoped lint's — a cache file that is not
+// ignored is committed, or spell-checked, which is a red gate with nothing misspelled in the tree.
+const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
+	...GATE_CACHE_FILES,
+	ESLINT_EDIT_CACHE_FILE,
+	ESLINT_RELATED_CACHE_FILE,
+]
+
+// `--cache --cache-strategy content` is one convention rather than two coincidences: cspell adopted
+// eslint's spelling for its own cache flags, so the pair is single-sourced here.
+const CONTENT_CACHE_FLAGS = ['--cache', '--cache-strategy', 'content'] as const
+const CACHE_LOCATION_FLAG = '--cache-location'
+
+// Four locations are written with these same four flags — the gate's eslint cache, the scoped lint's,
+// the edit hook's and the spell check's — so the sequence is built here once. Spelled out per
+// location, a fix to the order would have to be made four times and each copy fails silently: a flag
+// and its value are one unit, and a wrong order makes the tool read `--cache-strategy` as the file
+// name rather than erroring.
+function content_cache_flags(cache_file: string): ReadonlyArray<string> {
+	return [...CONTENT_CACHE_FLAGS, CACHE_LOCATION_FLAG, cache_file]
+}
+
+const ESLINT_CACHE_FLAGS = content_cache_flags(ESLINT_CACHE_FILE)
+const ESLINT_EDIT_CACHE_FLAGS = content_cache_flags(ESLINT_EDIT_CACHE_FILE)
+const ESLINT_RELATED_CACHE_FLAGS = content_cache_flags(ESLINT_RELATED_CACHE_FILE)
+const TS_CACHE_FLAGS = ['--incremental', '--tsBuildInfoFile', TS_BUILD_INFO_FILE] as const
+const CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE)
+
+export type { CommandCategory, CommandEntry, GateCacheSpec }
+// The three cache files are exported one by one as well as as a list, because `josh bench` clears
+// them per target (joshuafolkken/kit#1314): the lint step writes only the eslint one, so a target
+// that cleared the list would report a cold type check as the lint's own cost. The edit hook's cache
+// stays private; the scoped lint cache is exported because #2060 shares its completed file between
+// worktrees, but it still never overlaps the gate's distinct cache location.
+export {
+	COMMAND_AUDIENCES,
+	COMMAND_SIDE_EFFECTS,
+	CSPELL_CACHE_FILE,
+	CSPELL_CACHE_FLAGS,
+	ESLINT_CACHE_FILE,
+	ESLINT_CACHE_FLAGS,
+	ESLINT_EDIT_CACHE_FLAGS,
+	ESLINT_RELATED_CACHE_FLAGS,
+	ESLINT_RELATED_CACHE_FILE,
+	GATE_CACHE_FILES,
+	GATE_CACHE_SPECS,
+	GATE_COMMAND,
+	IGNORED_CACHE_FILES,
+	OPTIONAL_ENV_FILE_FLAGS,
+	PE,
+	SHARED_CACHE_SPECS,
+	TS_BUILD_INFO_FILE,
+	TS_CACHE_FLAGS,
+}

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

@@ -0,0 +1,327 @@
+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 { GUARD_COMMANDS } from './josh-commands-guard'
+import { ISSUE_COMMANDS } from './josh-commands-issue'
+import { LANE_COMMANDS } from './josh-commands-lane'
+import { SPLIT_COMMANDS } from './josh-commands-split'
+
+// One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
+const RUN_HOLD_SCRIPT = 'scripts/run/run-hold-cli.ts'
+const ISSUE_WITH_OPTIONS = '<issue> [options]'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const AI_COMMANDS: Record<string, CommandEntry> = {
+	...ISSUE_COMMANDS,
+	'pkg:scout': {
+		script: 'scripts/package/package-scout-cli.ts',
+		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']],
+	},
+	'stash:pop': {
+		script: 'scripts/git/stash-pop-cli.ts',
+		description: 'Pop the stash matching this message, not whichever a shared stack has on top',
+		category: 'AI tools',
+		reference: ['<message>', 'automation', ['git']],
+	},
+	epic: {
+		script: 'scripts-ai/epic.ts',
+		description: 'Create an epic issue from its child issue numbers',
+		category: 'AI tools',
+		reference: ['<title> <issue...> [--ordered]', 'automation', ['network']],
+	},
+	'epic:next': {
+		script: 'scripts/epic/epic-next.ts',
+		description: "List an epic's runnable children, bundled per repository",
+		category: 'AI tools',
+		reference: ['<epic>', 'automation', ['network']],
+	},
+	'epic:bundle': {
+		script: 'scripts/epic/epic-bundle-cli.ts',
+		description: 'Say whether a newly filed issue belongs with ones already in the backlog',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
+	'epic:audit': {
+		script: 'scripts/epic/epic-audit-cli.ts',
+		description: "Audit an epic's children against each other for contradictions",
+		category: 'AI tools',
+		reference: ['<epic>', 'automation', ['network']],
+	},
+	'epic:check': {
+		script: 'scripts-ai/epic-check.ts',
+		description: 'Check an epic issue against the tracking requirements',
+		category: 'AI tools',
+		reference: ['<epic>', 'automation', ['network']],
+	},
+	'auto-ok:next': {
+		script: 'scripts/auto-ok/auto-ok-cli.ts',
+		description: 'Print the next opted-in issue an unattended run may pick up outside an epic',
+		category: 'AI tools',
+		reference: ['[--exclude <n>[,<n>...]] [--label <name>]', 'automation', ['network']],
+	},
+	...BACKLOG_COMMANDS,
+	cost: {
+		script: 'scripts/cost-runtime/cost-cli.ts',
+		description: "Report a run's token and credit cost from Claude Code's session transcripts",
+		category: 'AI tools',
+		reference: ['[--cut|--over]', 'automation', ['none']],
+	},
+	...DOCUMENT_COMMANDS,
+	time: {
+		script: 'scripts/time/time-cli.ts',
+		description: "Report where a run's wall clock went: model wait, tool execution, human wait",
+		category: 'AI tools',
+		reference: ['[options]', 'maintainer', ['none']],
+		// Kit-only: it measures kit's own development runs and its report modules live under the
+		// undistributed `scripts/time/`, so it means nothing in a consumer project and is dropped from a
+		// consumer's help (joshuafolkken/kit#1997). The runtime analysis hooks and guards rely on stays
+		// distributed under `scripts/time-runtime/`.
+		is_kit_only: true,
+	},
+	// The tool-calls-per-round-trip density the batching guard is measured on, aggregated across the
+	// recent lane sessions (joshuafolkken/kit#2405). Kit-only for the same reason `time` is: it reads
+	// kit's own lane transcripts and means nothing in a consumer project.
+	'time:density': {
+		script: 'scripts/time/time-density-cli.ts',
+		description: 'Report tool calls per round trip across the recent lane sessions',
+		category: 'AI tools',
+		reference: ['[--lanes <n>] [--path <dir>]', 'maintainer', ['none']],
+		is_kit_only: true,
+	},
+	retrospective: {
+		script: 'scripts/retrospective/retrospective-cli.ts',
+		description:
+			"Aggregate a finished run's cost, review findings, observation ledger and events into one digest",
+		category: 'AI tools',
+		reference: ['', 'maintainer', ['none']],
+		// Kit-only: it reads kit's own development run — the transcript store, the review ledger and the
+		// run event stream — so it means nothing in a consumer project and is dropped from a consumer's
+		// help (joshuafolkken/kit#2328), through the same declaration `josh time` uses for the same reason.
+		is_kit_only: true,
+	},
+	'review:brief': {
+		script: 'scripts/review/review-brief-cli.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>] | --level-only [--staged] [--json]', 'automation', ['files']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+	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']],
+	},
+	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']],
+	},
+	'run:hold': {
+		script: RUN_HOLD_SCRIPT,
+		description: 'Claim this working tree for a run, or say which run already holds it',
+		category: 'AI tools',
+		reference: ['[issue]', 'automation', ['files']],
+	},
+	'run:release': {
+		script: RUN_HOLD_SCRIPT,
+		description: "Release this working tree's run record",
+		category: 'AI tools',
+		reference: ['[issue|--force]', 'automation', ['files']],
+		default_script_arguments: ['--release'],
+	},
+	'run:carry': {
+		script: 'scripts/run/run-carry-cli.ts',
+		description: 'Carry one invocation’s budget across its own session cuts',
+		category: 'AI tools',
+		reference: ['<operation> [arguments...]', 'automation', ['files']],
+	},
+	'run:wake': {
+		script: 'scripts/run/run-wake-cli.ts',
+		// `.env` rather than the ambient environment:
+		// the failure warning needs the Telegram credentials, the same
+		// reasons `notify` and `followup` carry these flags.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description: 'Wake the next session of a cut backlogrun from outside the conversation',
+		category: 'AI tools',
+		reference: ['[options]', 'automation', ['processes', 'notifications']],
+	},
+	'run:cut': {
+		script: 'scripts/run/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']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+	'run:progress': {
+		script: 'scripts/run/run-progress-cli.ts',
+		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
+		category: 'AI tools',
+		reference: ['[--wait|--mark]', 'automation', ['files']],
+	},
+	'run:prep': {
+		script: 'scripts/run/run-prep-cli.ts',
+		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
+	// The entry sequence a lane opened on, folded into one call (joshuafolkken/kit#2372): claim the tree,
+	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
+	// `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
+	'run:entry': {
+		script: 'scripts/run/run-entry-cli.ts',
+		description:
+			'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>', 'automation', ['git', 'network', 'files']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+	'run:step': {
+		script: 'scripts/run/run-step-cli.ts',
+		description:
+			'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']],
+	},
+	'repo:party': {
+		script: 'scripts/discovery/repo-party-cli.ts',
+		description:
+			'Say whether a repository is first-party or third-party by owner equality (computed, not judged)',
+		category: 'AI tools',
+		reference: ['[<owner/repo>]', 'automation', ['none']],
+	},
+	'run:merge': {
+		script: 'scripts/run/run-merge-cli.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']],
+	},
+	'run:review': {
+		script: 'scripts/run/run-review-cli.ts',
+		description:
+			'Start the gate in the background and print the /code-review brief in one call so the two overlap (--join to join the gate and check its verdict)',
+		category: 'AI tools',
+		reference: ['[--join]', 'automation', ['processes', 'files']],
+	},
+	// The post-merge sequence a run closed on, folded into one call (joshuafolkken/kit#2372): 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: commit the observation ledger, read the citations, decide the release scope',
+		category: 'AI tools',
+		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
+	},
+	// The commit-to-report region a run ships a change on, folded into one call (joshuafolkken/kit#2398):
+	// 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/run-ship-cli.ts',
+		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] [--detach] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
+			'automation',
+			['git', 'network'],
+		],
+	},
+	'run:event': {
+		script: 'scripts/run/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'],
+		],
+	},
+	'run:report': {
+		script: 'scripts/run/run-report-cli.ts',
+		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: ['', 'automation', ['files', 'network']],
+	},
+	...LANE_COMMANDS,
+	...GUARD_COMMANDS,
+	'run:watcher:guard': {
+		script: 'scripts/run/run-watcher-guard-cli.ts',
+		description:
+			'Guard: exits non-zero when lane children are in-flight but the watcher has not pinged recently',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
+	'run:stranded': {
+		script: 'scripts/run/run-stranded-cli.ts',
+		// `.env` rather than the ambient environment: the strand notification needs the Telegram
+		// credentials, the same reason `run:wake` carries these flags.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Report whether the run is stranded — budget handed off, owner gone, and no supervisor watching',
+		category: 'AI tools',
+		reference: ['', 'automation', ['processes', 'notifications']],
+	},
+	...SPLIT_COMMANDS,
+	'oracle:list': {
+		script: 'scripts/rules/oracle-list-cli.ts',
+		description: 'Print the decision oracles — commands that answer a rule question mechanically',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
+	eval: {
+		script: 'scripts/eval/eval-run.ts',
+		description: 'Run the agent rule-compliance scenarios (real Claude sessions)',
+		category: 'AI tools',
+		reference: ['[scenario...]', 'maintainer', ['processes', 'network']],
+		// Kit-only: it replays kit's own distributed rules against real Claude sessions, so it means
+		// nothing in a consumer project and is dropped from a consumer's help (joshuafolkken/kit#1988).
+		is_kit_only: true,
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { AI_COMMANDS }

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

@@ -0,0 +1,54 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The `backlog:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its
+// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason
+// (joshuafolkken/kit#2162, joshuafolkken/kit#2218). It is spread into `AI_COMMANDS` so the commands
+// stay grouped with the other AI tools under the 'AI tools' category.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
+	'backlog:next': {
+		script: 'scripts/backlog/backlog-next.ts',
+		description:
+			'Order the whole opted-in backlog: auto-ok issues and the descendants of auto-ok epics, transitively through nested epics',
+		category: 'AI tools',
+		reference: ['[--exclude <n>[,<n>...]] [--repo <owner/repo>]', 'automation', ['network']],
+	},
+	'backlog:offer': {
+		script: 'scripts/backlog/backlog-offer-cli.ts',
+		description:
+			'Collapse a backlogrun loop-head event into one call: read backlog:next, ask backlog:budget, return the verdict and any issues to start',
+		category: 'AI tools',
+		reference: ['[options]', 'automation', ['network']],
+	},
+	'backlog:drive': {
+		script: 'scripts/backlog/backlog-drive-cli.ts',
+		description:
+			'Drive backlogrun through offer, launch and merge; restore this run’s lanes and report when complete',
+		category: 'AI tools',
+		reference: ['--owner <pid> [options]', 'automation', ['network']],
+	},
+	'backlog:plan': {
+		script: 'scripts/backlog/backlog-plan-cli.ts',
+		description:
+			'Print the whole backlog as a plan: ready now, waiting on what, waiting on a person, out of scope',
+		category: 'AI tools',
+		reference: ['[issue...] [--only]', 'automation', ['network']],
+	},
+	'backlog:stalled': {
+		script: 'scripts/backlog/backlog-stalled-cli.ts',
+		description:
+			'Report whether ready backlog work is sitting undispatched with a free lane and no recent dispatch',
+		category: 'AI tools',
+		reference: ['', 'automation', ['network']],
+	},
+	'backlog:budget': {
+		script: 'scripts/backlog/backlog-budget-cli.ts',
+		description: 'Say whether a backlogrun may start more work, keep watching, or finish',
+		category: 'AI tools',
+		reference: ['[options]', 'automation', ['none']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { BACKLOG_COMMANDS }

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

@@ -0,0 +1,18 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The clone-detection commands, kept in their own module so `josh-commands-ai.ts` stays under its
+// line ceiling as the AI-tools set grows (joshuafolkken/kit#2217). Spread into `COMMAND_MAP` in
+// `josh-command-map.ts` alongside the other command groups.
+/* eslint-disable @typescript-eslint/naming-convention */
+const CLONE_COMMANDS: Record<string, CommandEntry> = {
+	'clone:scan': {
+		script: 'scripts/clone/clone-scan-cli.ts',
+		description:
+			'Count code duplication across files and first-party repositories, printing each clone as file:line pairs',
+		category: 'AI tools',
+		reference: ['', 'automation', ['files']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { CLONE_COMMANDS }