@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,6 +1,12 @@
+import { ports } from '#ports'
 import { core_budget } from '#scripts/gate/core-budget'
 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'
+
+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).
+const UNSEEDED: Readonly<Record<string, string | undefined>> = {}
 
 const FILE_ARGUMENTS = '[files...]'
 const REQUIRED_FILE_ARGUMENTS = '<files...>'
@@ -11,24 +17,41 @@ const PATH_ARGUMENTS = '<path...>'
 /* eslint-disable @typescript-eslint/naming-convention */
 const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'pr:classification': {
-		script: 'scripts/ci/pr-classification.ts',
+		script: 'scripts/ci/pr-classification-main.ts',
 		description: 'Require one release classification on a pull request',
 		category: 'Development',
 		reference: ['', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '', note: 'run by CI on a pull request; fails without one label' }],
+		},
 	},
 	[GATE_COMMAND]: {
 		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']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: '--verbose', note: "every check's output, passing ones included" },
+				{ arguments: '--force', note: 're-run even on a tree already recorded green' },
+				{ arguments: '--no-unit', note: 'the static checks only (CI only)' },
+			],
+		},
 	},
 	lint: {
-		script: 'scripts/lint/lint-parallel.ts',
+		script: 'scripts/lint/lint-parallel-main.ts',
 		description: 'Check code with prettier and eslint (skips a tool a basic project lacks)',
 		category: 'Development',
-		reference: ['', 'developer', ['processes']],
+		reference: ['[--changed]', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.lint,
 		memory_mb: core_budget.MEMORY_MB.lint,
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: '--changed', note: "the branch's changed files — the gate's form" },
+			],
+		},
 	},
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
@@ -37,6 +60,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.lint,
 		memory_mb: core_budget.MEMORY_MB.lint,
+		usage: { examples: [{ arguments: '' }, NARROWED] },
 	},
 	lines: {
 		script: 'scripts/lines/lines-command.ts',
@@ -45,9 +69,12 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
 		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		usage: {
+			examples: [{ arguments: 'scripts/hooks/format-edited-file.ts scripts/josh/josh-logic.ts' }],
+		},
 	},
 	metrics: {
-		script: 'scripts/metrics/metrics-command.ts',
+		script: 'tools/metrics/metrics-command.ts',
 		description:
 			'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',
@@ -59,6 +86,12 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
 		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 		is_kit_only: true,
+		usage: {
+			examples: [
+				{ arguments: '', note: "print the totals and check them against the merge-base's" },
+				{ arguments: '--accept --reason "<why>"', note: "record this branch's growth and why" },
+			],
+		},
 	},
 	'refactor:scan': {
 		script: 'scripts/refactor/refactor-scan-cli.ts',
@@ -68,6 +101,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'automation', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
 		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		usage: { examples: [{ arguments: '' }] },
 	},
 	bytes: {
 		script: 'scripts/lines/bytes-command.ts',
@@ -75,6 +109,12 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			"Print an agent-read document's byte size against its ceiling and the headroom left",
 		category: 'Development',
 		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'docs/josh-commands.md', note: 'one document' },
+				{ arguments: '', note: 'scan: every budgeted document near its ceiling' },
+			],
+		},
 	},
 	'rule:value': {
 		script: 'scripts/rules/rule-value-cli.ts',
@@ -82,6 +122,15 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			"Print each delivered rule's unaided compliance — runs reached, kept rate, refusals",
 		category: 'AI tools',
 		reference: ['[--refresh]', 'developer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{
+					arguments: '--refresh',
+					note: 'write the reading to the loop-head cache instead of stdout',
+				},
+			],
+		},
 	},
 	'rule:list': {
 		script: 'scripts/rules/rule-list.ts',
@@ -89,73 +138,16 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			"Print the trigger-delivered rules — each one's source, firing call and silent turn — from the guard rows",
 		category: 'AI tools',
 		reference: ['', 'automation', ['none']],
+		usage: { examples: [{ arguments: '', note: 'print every trigger-delivered rule' }] },
 	},
 	format: {
 		script: 'scripts/lint/format.ts',
 		description: 'Format code with prettier and eslint (skips a tool a basic project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['files', 'processes']],
+		usage: { examples: [{ arguments: '' }] },
 	},
-	'format:edited': {
-		script: 'scripts/hooks/format-edited-cli.ts',
-		description: 'Claude Code hook: format the file just edited (reads the tool call on stdin)',
-		category: 'Development',
-		reference: ['', 'automation', ['files', 'processes']],
-	},
-	'batch:guard': {
-		script: 'scripts/hooks/batch-guard.ts',
-		description:
-			'Claude Code hook: refuse a third consecutive single-call turn (reads the tool call on stdin)',
-		category: 'Development',
-		reference: ['', 'automation', ['none']],
-		// **No `tsx_arguments`, deliberately.** `JOSH_BATCH_GUARD` is a per-machine preference kept in
-		// `.env`, which every other command reads through `OPTIONAL_ENV_FILE_FLAGS` — but declaring any
-		// `tsx_arguments` disqualifies a command from in-process dispatch (`josh-in-process.ts`), and
-		// this one runs before every `Bash` call, where a second ~0.16 s tsx start is not affordable.
-		// The script calls `process.loadEnvFile` itself instead, which is
-		// node's own `--env-file` parser with node's own precedence.
-	},
-	'pretool:guard': {
-		script: 'scripts/hooks/pretool-guard-cli.ts',
-		description:
-			'Claude Code hook: the batch, investigation and rule guards in one process (reads the tool call on stdin)',
-		category: 'Development',
-		reference: ['', 'automation', ['none']],
-		// **No `tsx_arguments`, deliberately**, the same as `batch:guard` above: this is the one
-		// PreToolUse hook consumers run before every guarded call, so it must stay eligible for
-		// in-process dispatch rather than pay a second tsx start. Each guard it composes loads `.env`
-		// through the shared loader.
-	},
-	'stop:guard': {
-		script: 'scripts/hooks/stop-guard.ts',
-		description:
-			'Claude Code Stop hook: send the hold notify, release the hold and print the issue citations itself; block on the rules that need the model (reads the Stop payload on stdin)',
-		category: 'Development',
-		reference: ['', 'automation', ['none']],
-		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs at every
-		// turn end, so it must stay eligible for in-process dispatch rather than pay a second tsx start.
-		// It loads `.env` through the shared `hook-decision.ts` loader.
-	},
-	'session:lang': {
-		script: 'scripts/josh/session-language-cli.ts',
-		description:
-			'Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, and the run:board reply rule while a backlogrun is live (otherwise nothing)',
-		category: 'Development',
-		reference: ['', 'automation', ['none']],
-		// **No `tsx_arguments`, deliberately**, the same as `batch:guard` above: this runs on every
-		// `UserPromptSubmit`, so it must stay eligible for in-process dispatch rather than pay a second
-		// tsx start each turn. It calls `process.loadEnvFile` itself through the shared loader.
-	},
-	'codex:hook-adapter': {
-		script: 'scripts/hooks/codex-hook-adapter.ts',
-		description:
-			'Codex hook: run the pretool or posttool guard on a Codex payload (reads the tool call on stdin)',
-		category: 'Development',
-		reference: ['<pretool|posttool>', 'automation', ['none']],
-		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
-		// bundle name. **No `tsx_arguments`**, the same as `pretool:guard`
-		// above: it runs before every guarded Codex call.
-	},
+	...AGENT_HOOK_COMMANDS,
 	'cspell:dot': {
 		script: 'scripts/lint/cspell-cached.ts',
 		description: 'Run spell check including dotfiles',
@@ -163,6 +155,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.spell_check,
 		memory_mb: core_budget.MEMORY_MB.spell_check,
+		usage: { examples: [{ arguments: '', note: 'includes dotfiles' }] },
 	},
 	behavior: {
 		script: 'scripts/behavior/behavior-cli.ts',
@@ -170,6 +163,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			"Check the current run's recorded transcript against the behavior assertions (no model call)",
 		category: 'Development',
 		reference: ['', 'developer', ['files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'exports:unused': {
 		script: 'scripts/exports/unused-members-cli.ts',
@@ -177,23 +171,30 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'Report exported namespace members nothing reads (kit only; a consumer project skips it)',
 		category: 'Development',
 		reference: ['', 'developer', ['none']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'test:unit': {
-		script: 'scripts/test/test-unit-guard.ts',
+		script: 'scripts/test/test-unit-guard-main.ts',
 		description:
 			'Run unit tests with Vitest (without Vitest: a basic project runs its own test script, others skip; fails when Vitest has no tests)',
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
-		core_weight: gate_plan.direct_unit_weight,
-		memory_mb: gate_plan.direct_unit_memory,
+		...gate_plan.DIRECT_UNIT_CLAIM,
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'test:related': {
-		script: 'scripts/test/test-related.ts',
+		script: 'scripts/test/test-related-main.ts',
 		description: 'Run only the unit tests related to the changed files (full suite on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
-		core_weight: gate_plan.direct_unit_weight,
-		memory_mb: gate_plan.direct_unit_memory,
+		...gate_plan.DIRECT_UNIT_CLAIM,
+		usage: {
+			examples: [
+				{ arguments: '' },
+				NARROWED,
+				{ arguments: '--silent', note: 'flags are forwarded to vitest' },
+			],
+		},
 	},
 	'test:declared': {
 		script: 'scripts/test/test-declared.ts',
@@ -201,13 +202,35 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'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.ts',
+		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' },
+			],
+		},
 	},
 	disposition: {
 		script: 'scripts/review/disposition-cli.ts',
@@ -215,18 +238,21 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'Say whether a review finding reaches a runtime path (runtime) or is inert (non-runtime)',
 		category: 'AI tools',
 		reference: [PATH_ARGUMENTS, 'automation', ['none']],
+		usage: { examples: [{ arguments: '<path...>', note: '→ runtime | non-runtime' }] },
 	},
 	'e2e:retry-check': {
 		script: 'scripts/test/e2e-retry-check.ts',
 		description: 'Report whether the preview server crashed during a failed E2E attempt (CI)',
 		category: 'Development',
 		reference: ['', 'automation', ['none']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'test:e2e': {
 		script: 'scripts/test/test-e2e-guard.ts',
 		description: 'Run E2E tests with Playwright (skips when absent or no e2e files)',
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	test: {
 		shell: ['sh', '-c', 'pnpm josh test:unit && pnpm josh test:e2e'],
@@ -234,6 +260,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 		argument_targets: ['test:unit', 'test:e2e'],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	check: {
 		script: 'scripts/gate/type-check-command.ts',
@@ -242,12 +269,25 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[arguments...]', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.type_check,
 		memory_mb: core_budget.MEMORY_MB.type_check,
+		usage: { examples: [{ arguments: '' }] },
 	},
 	port: {
 		script: 'scripts/ports/port-command.ts',
 		description: 'Print the PORT_SEED-resolved dev or preview port',
 		category: 'Development',
 		reference: ['<dev|preview>', 'developer', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: 'dev',
+					note: `${String(ports.resolve_development_port(UNSEEDED))} with no seed set`,
+				},
+				{
+					arguments: 'preview',
+					note: `${String(ports.resolve_preview_port(UNSEEDED))} with no seed set`,
+				},
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -9,17 +9,31 @@ import type { CommandEntry } from './josh-command-types'
 /* eslint-disable @typescript-eslint/naming-convention */
 const DOCUMENT_COMMANDS: Record<string, CommandEntry> = {
 	'doc:section': {
-		script: 'scripts/document/document-section-cli.ts',
+		script: 'scripts/document/document-section-main.ts',
 		description: 'Print one section of a markdown document, for a `file.md` → "Heading" reference',
 		category: 'AI tools',
 		reference: ['<file> <heading>', 'automation', ['none']],
 		is_bundled: true,
+		usage: {
+			examples: [
+				{ arguments: '<file.md> "<heading>"' },
+				{ arguments: 'backlogrun.md "The hand-off"' },
+			],
+		},
 	},
 	'read:set': {
 		script: 'scripts/document/read-set-cli.ts',
 		description: 'Print what an entry point reads before it starts, and what that read costs',
 		category: 'AI tools',
 		reference: ['[<entry>] [--json]', 'automation', ['none']],
+		is_bundled: true,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'every entry point' },
+				{ arguments: 'backlogrun', note: 'one of them' },
+				{ arguments: 'backlogrun --json' },
+			],
+		},
 	},
 	'doc:read': {
 		script: 'scripts/document/document-read-cli.ts',
@@ -27,18 +41,46 @@ const DOCUMENT_COMMANDS: Record<string, CommandEntry> = {
 			'Read a whole document safely: print it, or point at the Read tool when over the Bash cap',
 		category: 'AI tools',
 		reference: ['<file>', 'automation', ['none']],
+		is_bundled: true,
+		usage: {
+			examples: [
+				{ arguments: 'CLAUDE.md', note: 'under the cap: prints the document' },
+				{ arguments: 'backlogrun.md', note: 'over the cap: prints a directive, no content' },
+			],
+		},
 	},
 	'read:files': {
 		script: 'scripts/document/read-files-cli.ts',
 		description: 'Read several files in one call so edit targets fold into one turn',
 		category: 'AI tools',
 		reference: ['<path> [<path> ...]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: 'a.ts b.ts c.ts',
+					note: 'under the cap: prints each file under its own header',
+				},
+				{
+					arguments: 'a.ts big.ts',
+					note: 'over the cap: prints a directive to Read them in one turn, no content',
+				},
+			],
+		},
 	},
 	'edit:files': {
 		script: 'scripts/document/edit-files-cli.ts',
 		description: 'Apply several content-addressed edits from a plan in one call',
 		category: 'AI tools',
 		reference: ['<plan-path | ->', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: 'plan.txt',
+					note: 'applies every block in the plan, one line per edit reporting the outcome',
+				},
+				{ arguments: "- <<'EDITS'", note: 'plan from stdin, then EDITS' },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -0,0 +1,171 @@
+import type { CommandEntry } from './josh-command-types'
+
+const REPO = '--repo <owner/repo>'
+const EXCLUDE = '--exclude <N>'
+const JUST_MERGED = 'skip the issue just merged'
+
+// The epic and auto-ok 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 EPIC_COMMANDS: Record<string, CommandEntry> = {
+	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']],
+		usage: {
+			examples: [
+				{ arguments: '"Epic: split the parser work" 101 102 103' },
+				{ arguments: '"Epic: staged rollout" 101 102 --ordered' },
+				{ arguments: '"Epic: ..." 101 102 --rationale-file rationale.md' },
+				{ arguments: '--promote 858 101 102 103', note: 'turn an existing issue into an epic' },
+				{ arguments: '--add 893 894', note: 'track #894, declaring no order for it' },
+				{ arguments: '--add 893 894 --before 891', note: '#894 must finish before #891' },
+				{ arguments: '--add 893 894 --after 890', note: '#894 starts once #890 is done' },
+				{ arguments: '--add 893 894 --decision-file why.md', note: '…and record why, in one call' },
+				{
+					arguments: '--reconcile 2184',
+					note: 'rewrite the body to match the recorded blocked-by, and record any order the body declared',
+				},
+				{ arguments: '--decide 893 894 --decision-file why.md' },
+			],
+			flags: [
+				{
+					names: ['--ordered'],
+					description:
+						'argument order is the dependency order; writes the arrow chain, records the matching `blocked-by` relations, and adds a `### Declared order` entry under `## Decisions`.',
+				},
+				{
+					names: ['--rationale-file <path|->'],
+					description: 'split rationale prose (`-` reads stdin).',
+				},
+				{
+					names: ['--origin <owner/repo#N>'],
+					description: 'backlink when the split originated in another repository.',
+				},
+				{
+					names: ['--before <M>'],
+					description:
+						'with `--add`: insert before `#M`, re-pointing what `#M` was waiting on so the chain is never broken.',
+				},
+				{
+					names: ['--after <M>'],
+					description:
+						'with `--add`: start after `#M`; branches when `#M` already has a successor, extends when it is a tail.',
+				},
+				{
+					names: ['--order-before <M>', '--order-after <M>'],
+					description: 'with `--add`: move the task-list row only; write no `blocked-by` relation.',
+				},
+				{
+					names: ['--decision-file <path|->'],
+					description: 'with `--add`: record why the child was placed.',
+				},
+				{
+					names: ['--remove <E> <M> <N> [<N2> …]'],
+					description:
+						'delete a declared order from the body and the relations; each consecutive pair is one link.',
+				},
+			],
+		},
+	},
+	'epic:next': {
+		script: 'scripts/epic/epic-next-main.ts',
+		description: "List an epic's runnable children, bundled per repository",
+		category: 'AI tools',
+		reference: ['<epic>... [--repo <owner/repo>] [--lanes]', 'automation', ['network']],
+		usage: {
+			examples: [
+				{ arguments: '858' },
+				{
+					arguments: '858 --repo joshuafolkken/kit',
+					note: 'just the next child for one repository',
+				},
+				{
+					arguments: '858 --repo joshuafolkken/kit --lanes',
+					note: 'one child per free lane there',
+				},
+			],
+			flags: [
+				{
+					names: [REPO],
+					description:
+						'answer for one repository; stdout carries one token (an issue number, or `wait`/`stop`/`complete`), everything else on stderr.',
+				},
+				{
+					names: ['--lanes'],
+					description:
+						'print one issue number per free lane (requires `--repo`); `JOSH_LANE_LIMIT` sets the ceiling, default 4. Prints `triage` instead while any candidate carries neither `run:solo` nor `run:lane` (the triage gate in `josh backlog:next`).',
+				},
+			],
+		},
+	},
+	'epic:bundle': {
+		script: 'scripts/epic/epic-bundle-main.ts',
+		description: 'Say whether a newly filed issue belongs with ones already in the backlog',
+		category: 'AI tools',
+		reference: ['<issue> [--apply]', 'automation', ['network']],
+		usage: {
+			examples: [{ arguments: '874' }, { arguments: '874 --apply', note: 'write it' }],
+		},
+	},
+	'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']],
+		usage: { examples: [{ arguments: '858' }] },
+	},
+	'epic:check': {
+		script: 'scripts/epic/epic-check.ts',
+		description: 'Check an epic issue against the tracking requirements',
+		category: 'AI tools',
+		reference: ['<epic>', 'automation', ['network']],
+		usage: { examples: [{ arguments: '700' }] },
+	},
+	'auto-ok:next': {
+		script: 'scripts/auto-ok/auto-ok-main.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']],
+		usage: {
+			examples: [{ arguments: '' }, { arguments: '--exclude 906', note: JUST_MERGED }],
+			flags: [
+				{
+					names: [EXCLUDE],
+					description: 'drop issues from the answer; comma-separated, repeatable.',
+				},
+			],
+		},
+	},
+	'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)',
+		category: 'AI tools',
+		reference: [
+			'[--apply <n> (--lane | --solo) | --decline <n> --reason <text>]',
+			'automation',
+			['network'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'the issues that still owe a judgement' },
+				{ arguments: '--apply 912 --lane', note: 'opt it in, with its run label' },
+				{ arguments: '--decline 913 --reason "<why>"', note: 'record why it stays out' },
+			],
+			flags: [
+				{
+					names: ['--apply <N> --lane|--solo'],
+					description:
+						'checks the exclusions again against the labels as they stand, records the judgement on the issue, then applies the run label and then `auto-ok`.',
+				},
+				{ names: ['--decline <N> --reason <text>'], description: 'applies nothing.' },
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { EPIC_COMMANDS }

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

@@ -6,42 +6,65 @@ const HOOKS_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Git hook: block commits to main',
 		category: 'Git hooks',
 		reference: ['', 'automation', ['none']],
+		usage: { examples: [{ arguments: '', note: 'run by the pre-commit hook' }] },
 	},
 	'check-commit-message': {
-		script: 'scripts/hooks/check-commit-message.ts',
+		script: 'scripts/hooks/check-commit-message-main.ts',
 		description: 'Git hook: validate commit message',
 		category: 'Git hooks',
 		reference: ['[<message-file>]', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '.git/COMMIT_EDITMSG', note: 'run by the commit-msg hook' }],
+		},
 	},
 	'secretlint-scan': {
 		script: 'scripts/security/secretlint-scan.ts',
 		description: 'Git hook: scan staged files for secrets',
 		category: 'Git hooks',
 		reference: ['[paths...]', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: 'src/app.ts .env.example', note: 'the staged paths' }],
+		},
 	},
 	'pre-commit-lint': {
 		script: 'scripts/hooks/pre-commit-lint.ts',
 		description: 'Git hook: run cspell, prettier or eslint over staged files from a content cache',
 		category: 'Git hooks',
 		reference: ['<cspell|prettier|eslint> [paths...]', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: 'cspell src/app.ts' },
+				{ arguments: 'prettier src/app.ts' },
+				{ arguments: 'eslint src/app.ts' },
+			],
+		},
 	},
 	'pre-push-unit': {
 		script: 'scripts/hooks/pre-push-unit.ts',
 		description: 'Git hook: run unit tests, reusing a green gate recorded on the pushed tree',
 		category: 'Git hooks',
 		reference: ['', 'automation', ['processes']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'reserved-run': {
 		script: 'scripts/hooks/reserved-run.ts',
 		description: 'Git hook: run a command while holding a place in the machine-wide core budget',
 		category: 'Git hooks',
-		reference: ['<weight> -- <command...>', 'automation', ['processes']],
+		reference: ['<weight> [--memory <MB>] -- <command...>', 'automation', ['processes']],
+		usage: {
+			examples: [
+				{ arguments: '2 -- pnpm install', note: 'hold 2 cores while installing' },
+				{ arguments: '1 -- pnpm josh audit', note: 'hold 1 core while scanning' },
+				{ arguments: '1 --memory 3000 -- <command>', note: 'hold 3,000 MB beside the core' },
+			],
+		},
 	},
 	'pre-commit-type-check': {
 		script: 'scripts/gate/pre-commit-type-check.ts',
 		description: 'Git hook: type-check, reusing a green gate recorded on the committed tree',
 		category: 'Git hooks',
 		reference: ['', 'automation', ['processes']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 }