@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,14 +1,18 @@
-import { core_budget } from '#scripts/gate/core-budget'
-import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+import { core_weights } from '#scripts/gate/core-weights'
+import 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 { EPIC_COMMANDS } from './josh-commands-epic'
 import { ISSUE_COMMANDS } from './josh-commands-issue'
 import { LANE_COMMANDS } from './josh-commands-lane'
+import { REVIEW_COMMANDS } from './josh-commands-review'
 import { RUN_COMMANDS } from './josh-commands-run'
+import { SHIP_COMMANDS } from './josh-commands-ship'
 import { SPLIT_COMMANDS } from './josh-commands-split'
 
-const ISSUE_WITH_OPTIONS = '<issue> [options]'
+const DIR = '--dir <path>'
+const PATH_DIR = '--path <dir>'
+const BARE = { arguments: '' }
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const AI_COMMANDS: Record<string, CommandEntry> = {
@@ -19,70 +23,81 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			'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']],
+		usage: {
+			examples: [{ arguments: '"date formatting" --size 5' }],
+			flags: [
+				{
+					names: ['--size <n>'],
+					description: 'how many candidates to fetch and rank (default 10).',
+				},
+			],
+		},
 	},
-	'stash:pop': {
-		script: 'scripts/git/stash/stash-pop-cli.ts',
-		description: 'Pop the stash matching this message, not whichever a shared stack has on top',
+	'stash:push': {
+		script: 'scripts/git/stash/stash-push-main.ts',
+		description: 'Stash the working tree, untracked files included, leaving the observation ledger',
 		category: 'AI tools',
 		reference: ['<message>', 'automation', ['git']],
+		usage: {
+			examples: [{ arguments: '"backlogrun: josh latest before lanes"' }],
+			flags: [
+				{
+					names: [DIR],
+					description: 'stashes that work tree (`git -C <path>`); without it the current checkout.',
+				},
+			],
+		},
 	},
-	epic: {
-		script: 'scripts/epic/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>... [--repo <owner/repo>] [--lanes]', '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/epic/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']],
-	},
-	'auto-ok:judge': {
-		script: 'scripts/auto-ok/auto-ok-judge-cli.ts',
-		description:
-			'List the open issues backlogrun owes an auto-ok judgement, or record one (--apply / --decline)',
+	'stash:pop': {
+		script: 'scripts/git/stash/stash-pop-main.ts',
+		description: 'Pop the stash matching this message, not whichever a shared stack has on top',
 		category: 'AI tools',
-		reference: [
-			'[--apply <n> (--lane | --solo) | --decline <n> --reason <text>]',
-			'automation',
-			['network'],
-		],
+		reference: ['<message>', 'automation', ['git']],
+		usage: {
+			examples: [
+				{ arguments: '"backlogrun: parked #2028"' },
+				{
+					arguments: '"backlogrun: josh latest before lanes" --dir "$dir"',
+					note: "into a lane's work tree",
+				},
+			],
+			flags: [
+				{
+					names: [DIR],
+					description:
+						'applies the pop in that work tree (`git -C <path>`); without it the pop lands in the current checkout. The stack is shared, so it reads the same either way.',
+				},
+			],
+		},
 	},
+	...EPIC_COMMANDS,
 	...BACKLOG_COMMANDS,
 	cost: {
-		script: 'scripts/cost-runtime/cost-cli.ts',
+		script: 'scripts/cost-runtime/cost-main.ts',
 		description:
 			'Say whether the next turn of a run crosses the context-cut threshold (--cut) or a given tokens-per-request figure (--over)',
 		category: 'AI tools',
 		reference: ['(--cut | --over <tokens-per-request>) [--path <dir>]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: '--cut',
+					note: 'compare billed input per request with the context-cut threshold priced at the session model',
+				},
+				{ arguments: '--over <tokens>', note: 'compare with an explicit limit' },
+				{ arguments: `--cut ${PATH_DIR}`, note: 'Anthropic project or current OpenAI worktree' },
+			],
+			flags: [
+				{
+					names: [PATH_DIR],
+					description:
+						'selects another Anthropic project; OpenAI accepts only linked checkouts of the current project.',
+				},
+			],
+		},
 	},
 	'cost:audit': {
-		script: 'scripts/cost-audit/cost-audit-cli.ts',
+		script: 'tools/cost-audit/cost-audit-main.ts',
 		description:
 			'Report AI cost over a period by session kind, tool category and guard, with cost per merge and regressions against the period before',
 		category: 'AI tools',
@@ -90,74 +105,102 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		// Kit-only: it reads kit's own transcript store, like `josh retrospective`, which carries its
 		// summary line.
 		is_kit_only: true,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'the last 7 days against the 7 before' },
+				{ arguments: '--period 30', note: 'the last 30 days against the 30 before' },
+			],
+			flags: [
+				{
+					names: ['--period <days>'],
+					description: 'the length of each period, a positive whole number of days (default 7).',
+				},
+			],
+		},
 	},
 	...DOCUMENT_COMMANDS,
 	time: {
-		script: 'scripts/time/time-cli.ts',
+		script: 'tools/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
+		// undistributed `tools/time/`, so it means nothing in a consumer project and is dropped from a
 		// consumer's help. The runtime analysis hooks and guards rely on stays
 		// distributed under `scripts/time-runtime/`.
 		is_kit_only: true,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'the last run tree, wall clock and cost by role' },
+				{ arguments: '--run', note: 'the same run-tree scope, named explicitly' },
+				{ arguments: '--json', note: 'the same figures, machine-readable' },
+				{ arguments: PATH_DIR, note: "read another project's transcripts from this checkout" },
+				{
+					arguments: '--split-at 2026-10-16T21:33:19Z',
+					note: 'the same tree compared by role before and after a merge',
+				},
+			],
+			flags: [
+				{
+					names: ['--run'],
+					description:
+						'(default) the whole run tree, wall clock led beside dollars. It is the only scope; any flag not listed here is a usage error (exit 1). History: `docs/maintainers/josh-commands-run-rationale.md` → "`josh cost` and `josh time` lost their report scopes".',
+				},
+				{
+					names: [PATH_DIR],
+					description:
+						'aim the read at another project (absolute path); keeps the `cwd` behavior when absent.',
+				},
+				{ names: ['--json'], description: 'the run tree, machine-readable.' },
+				{
+					names: ['--split-at <ISO time>'],
+					description:
+						'add a before → after block by role (time share, cost share, req/session), each session on the side of its first request; an unparseable time is a usage error (exit 1).',
+				},
+			],
+		},
 	},
 	// The tool-calls-per-round-trip density the batching guard is measured on, aggregated across the
 	// recent lane sessions. 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',
+		script: 'tools/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,
+		usage: {
+			examples: [{ arguments: '' }, { arguments: '--lanes 5', note: 'the five most recent lanes' }],
+			flags: [
+				{
+					names: ['--lanes <n>'],
+					description: 'average over a different count of recent qualifying lanes (default 10).',
+				},
+				{
+					names: [PATH_DIR],
+					description:
+						"read another project's lane transcripts, as `josh time` does. Run from a lane, it reads its main checkout's lanes.",
+				},
+			],
+		},
 	},
 	retrospective: {
-		script: 'scripts/retrospective/retrospective-cli.ts',
+		script: 'tools/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']],
-		core_weight: core_budget.CORE_WEIGHTS.retrospective,
-		memory_mb: core_budget.MEMORY_MB.retrospective,
+		core_weight: core_weights.CORE_WEIGHTS.retrospective,
+		memory_mb: core_weights.MEMORY_MB.retrospective,
 		// 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, through the same declaration `josh time` uses for the same reason.
 		is_kit_only: true,
+		usage: {
+			examples: [{ arguments: '', note: 'the digest for the run this checkout carries' }],
+		},
 	},
-	'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']],
-	},
+	...REVIEW_COMMANDS,
 	...RUN_COMMANDS,
 	'repo:party': {
 		script: 'scripts/discovery/repo-party-cli.ts',
@@ -165,82 +208,23 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			'Say whether a repository is first-party or third-party by owner equality (computed, not judged)',
 		category: 'AI tools',
 		reference: ['[<owner/repo>]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'joshuafolkken/kit', note: '→ first-party (in the kit session)' },
+				{ arguments: 'sveltejs/kit', note: '→ third-party' },
+				{ arguments: '', note: "no argument: the session's own repository" },
+			],
+		},
 	},
-	'run:merge': {
-		script: 'scripts/run/merge/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/review/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: 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']],
-	},
-	// 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',
-		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] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
-			'automation',
-			['git', 'network'],
-		],
-	},
-	'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'],
-		],
-	},
-	'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']],
-	},
+	...SHIP_COMMANDS,
 	...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 — owner gone, no successor holding the budget, and no supervisor watching',
-		category: 'AI tools',
-		reference: ['', 'automation', ['processes', 'notifications']],
+		usage: { examples: [BARE] },
 	},
 	...SPLIT_COMMANDS,
 	'oracle:list': {
@@ -248,15 +232,30 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Print the decision oracles — commands that answer a rule question mechanically',
 		category: 'AI tools',
 		reference: ['', 'automation', ['none']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	eval: {
-		script: 'scripts/eval/eval-run.ts',
+		script: 'tools/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.
 		is_kit_only: true,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'every scenario' },
+				{ arguments: 'consult-not-execute', note: 'one scenario by name' },
+			],
+			flags: [
+				{ names: ['JOSH_EVAL_MODEL'], description: 'the model to run against (default `sonnet`).' },
+				{
+					names: ['JOSH_EVAL_CONCURRENCY'],
+					description:
+						'how many sessions run at once (default `5`); a non-positive-integer value is refused.',
+				},
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -1,4 +1,9 @@
-import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+import type { CommandEntry } from './josh-command-types'
+
+const EXCLUDE = '--exclude <N>'
+const JUST_MERGED = 'skip the issue just merged'
+const EXCLUDE_1630 = '--exclude 1630'
+const BUDGET = '--answer candidates --started "$started" --active "$active"'
 
 // 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.
@@ -11,27 +16,48 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	backlogrun: {
 		script: 'scripts/backlog/backlogrun-cli.ts',
 		description:
-			'Start a backlogrun in the background and show its board; with one already running, only show the board, or replace it when it is idle and the invocation differs; --stop stops it',
+			'Start a backlogrun in the background and show its board; with one already running, only show the board, or replace it when it is idle and the invocation differs; --stop stops it; --restart replaces its processes and keeps its record',
 		category: 'AI tools',
 		reference: [
-			'[<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop',
+			'[<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop | --restart',
 			'developer',
 			['files', 'network', 'processes'],
 		],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'start in Claude, then show the board' },
+				{ arguments: '3437 --only', note: 'the arguments go to backlogrun as typed' },
+				{ arguments: '--agent codex', note: 'start in Codex' },
+				{ arguments: '--stop', note: 'stop the run in this repository' },
+				{ arguments: '--restart', note: "replace the run's processes, keeping its record" },
+			],
+		},
 	},
 	'backlog:next': {
-		script: 'scripts/backlog/backlog-next.ts',
+		script: 'scripts/backlog/backlog-next-main.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']],
+		usage: {
+			examples: [{ arguments: '' }, { arguments: EXCLUDE_1630, note: JUST_MERGED }],
+			flags: [
+				{
+					names: [EXCLUDE],
+					description: 'drop issues from every bucket; comma-separated, repeatable.',
+				},
+			],
+		},
 	},
 	'backlog:offer': {
-		script: 'scripts/backlog/backlog-offer-cli.ts',
+		script: 'scripts/backlog/backlog-offer-main.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', ['files', 'network', 'processes']],
+		usage: {
+			examples: [{ arguments: '--started "$started" --active "$active" --running 2 --retries 1' }],
+		},
 	},
 	'backlog:drive': {
 		script: 'scripts/backlog/backlog-drive-cli.ts',
@@ -39,6 +65,9 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 			'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']],
+		usage: {
+			examples: [{ arguments: '--owner "$PPID" [--max <n>] [--idle <minutes>] [--only]' }],
+		},
 	},
 	'backlog:plan': {
 		script: 'scripts/backlog/backlog-plan-cli.ts',
@@ -50,22 +79,59 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 			'automation',
 			['network'],
 		],
-	},
-	'backlog:stalled': {
-		script: 'scripts/backlog/backlog-stalled-cli.ts',
-		// A stall sends one Telegram warning. The `Stop` hook calls the detector
-		// directly, so this flag costs only the manual command its in-process dispatch.
-		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
-		description:
-			'Report whether ready backlog work is sitting undispatched with a free lane and no recent dispatch',
-		category: 'AI tools',
-		reference: ['', 'automation', ['network']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: EXCLUDE_1630, note: 'after #1630 merged' },
+				{ arguments: '--waves', note: 'the run order, wave by wave' },
+			],
+			flags: [
+				{ names: [EXCLUDE], description: 'same exclusion as `backlog:next`.' },
+				{
+					names: ['--waves'],
+					description:
+						'print the order the run takes, wave by wave, assuming each wave merges before the next. Read-only.',
+				},
+			],
+		},
 	},
 	'backlog:budget': {
-		script: 'scripts/backlog/backlog-budget-cli.ts',
+		script: 'scripts/backlog/backlog-budget-main.ts',
 		description: 'Say whether a backlogrun may start more work, keep watching, or finish',
 		category: 'AI tools',
 		reference: ['[options]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: BUDGET },
+				{ arguments: '--answer exhausted --started "$started" --active "$active" --idle 60' },
+				{ arguments: `${BUDGET} --merged 3 --running 2 --max 5` },
+			],
+			flags: [
+				{
+					names: ['--answer <candidates|exhausted|blocked|parked|unreadable|untriaged>'],
+					description: "`backlog:next`'s answer, mapped.",
+				},
+				{
+					names: ['--started', '--active'],
+					description:
+						'when the invocation began / when it last had work (required unless the watch is off).',
+				},
+				{
+					names: ['--idle <minutes>'],
+					description:
+						'once nothing can proceed, keep polling this long, counted from `--active` (default 480, 8 hours; `--idle 0` turns the watch off).',
+				},
+				{
+					names: ['--max <count>'],
+					description:
+						'issues one invocation may take (default unlimited); `--merged` and `--running` count against it.',
+				},
+				{
+					names: ['--json'],
+					description: 'collapse verdict and reason into `{"budget": "<verdict>", "reason": "…"}`.',
+				},
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -11,6 +11,7 @@ const CLONE_COMMANDS: Record<string, CommandEntry> = {
 			'Count code duplication across files and first-party repositories, printing each clone as file:line pairs',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */