@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,206 @@
+import {
+	ESLINT_CACHE_FLAGS,
+	GATE_COMMAND,
+	PE,
+	TS_CACHE_FLAGS,
+	type CommandEntry,
+} from './josh-command-types'
+
+const FILE_ARGUMENTS = '[files...]'
+const REQUIRED_FILE_ARGUMENTS = '<files...>'
+const FILTER_ARGUMENTS = '[filters...]'
+const MATCH_ARGUMENTS = '[--match]'
+const PATH_ARGUMENTS = '<path...>'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const DEV_COMMANDS: Record<string, CommandEntry> = {
+	[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']],
+	},
+	lint: {
+		script: 'scripts/lint/lint-parallel.ts',
+		description: 'Check code with prettier and eslint',
+		category: 'Development',
+		reference: ['', 'developer', ['processes']],
+	},
+	'lint:related': {
+		script: 'scripts/lint/lint-related.ts',
+		description: 'Check only the changed files with prettier and eslint (whole tree on fallback)',
+		category: 'Development',
+		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
+	},
+	lines: {
+		script: 'scripts/lines/lines-command.ts',
+		description: "Print a file's code lines against the max-lines limit and the headroom left",
+		category: 'Development',
+		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
+	},
+	'refactor:scan': {
+		script: 'scripts/refactor/refactor-scan-cli.ts',
+		description:
+			'List refactoring candidates in the changed scope by category and answer clear/candidates',
+		category: 'Development',
+		reference: ['', 'automation', ['processes']],
+	},
+	bytes: {
+		script: 'scripts/bytes/bytes-command.ts',
+		description:
+			"Print an agent-read document's byte size against its ceiling and the headroom left",
+		category: 'Development',
+		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
+	},
+	'rule:value': {
+		script: 'scripts/rules/rule-value-cli.ts',
+		description:
+			"Print each delivered rule's unaided compliance — runs reached, kept rate, refusals",
+		category: 'AI tools',
+		reference: ['', 'developer', ['none']],
+	},
+	format: {
+		// prettier first here, unlike `format:edited`, and deliberately: `eslint --fix` exits 1
+		// whenever a non-autofixable error remains, so putting it first behind `&&` would mean one
+		// unused variable anywhere in the tree stops prettier from running at all.
+		shell: [
+			'sh',
+			'-c',
+			`pnpm exec prettier --write . && pnpm exec eslint . --fix ${ESLINT_CACHE_FLAGS.join(' ')}`,
+		],
+		description: 'Format code with prettier and eslint',
+		category: 'Development',
+		reference: ['', 'developer', ['files', 'processes']],
+	},
+	'format:edited': {
+		script: 'scripts/hooks/format-edited-file.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. That is the hot path joshuafolkken/kit#1342 took a
+		// second ~0.16 s tsx start off. 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.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: deliver the three stop-time rules — hold notify/release and issue citation (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 the resolved JOSH_SESSION_LANG (defaults to ja) for the session context',
+		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.
+	},
+	'cspell:dot': {
+		script: 'scripts/lint/cspell-cached.ts',
+		description: 'Run spell check including dotfiles',
+		category: 'Development',
+		reference: ['', 'developer', ['processes']],
+	},
+	behavior: {
+		script: 'scripts/behavior/behavior-cli.ts',
+		description:
+			"Check the current run's recorded transcript against the behavior assertions (no model call)",
+		category: 'Development',
+		reference: ['', 'developer', ['files']],
+	},
+	'test:unit': {
+		script: 'scripts/test/test-unit-guard.ts',
+		description:
+			'Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)',
+		category: 'Development',
+		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
+	},
+	'test:related': {
+		script: 'scripts/test/test-related.ts',
+		description: 'Run only the unit tests related to the changed files (full suite on fallback)',
+		category: 'Development',
+		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
+	},
+	'test:declared': {
+		script: 'scripts/test/test-declared.ts',
+		description:
+			'Report whether the working-tree change needs a test (required/exempt/satisfied); --match checks Step 0 declarations on stdin',
+		category: 'Development',
+		reference: [MATCH_ARGUMENTS, 'developer', ['processes']],
+	},
+	'test:red': {
+		script: 'scripts/test/test-red.ts',
+		description:
+			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test',
+		category: 'Development',
+		reference: ['', 'developer', ['git', 'processes']],
+	},
+	disposition: {
+		script: 'scripts/review/disposition-cli.ts',
+		description:
+			'Say whether a review finding reaches a runtime path (runtime) or is inert (non-runtime)',
+		category: 'AI tools',
+		reference: [PATH_ARGUMENTS, 'automation', ['none']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+	test: {
+		shell: ['sh', '-c', 'pnpm josh test:unit && pnpm josh test:e2e'],
+		description: 'Run unit and E2E tests',
+		category: 'Development',
+		reference: ['', 'developer', ['processes']],
+		argument_targets: ['test:unit', 'test:e2e'],
+	},
+	check: {
+		shell: [...PE, 'tsc', '--noEmit', ...TS_CACHE_FLAGS],
+		description: 'Type-check TypeScript project',
+		category: 'Development',
+		reference: ['[arguments...]', 'developer', ['processes']],
+	},
+	port: {
+		script: 'scripts/ports/port-command.ts',
+		description: 'Print the PORT_SEED-resolved dev or preview port',
+		category: 'Development',
+		reference: ['<dev|preview>', 'developer', ['none']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { DEV_COMMANDS }

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

@@ -0,0 +1,45 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The document-reading and -editing command registry, split out of `josh-commands-ai.ts` so that file
+// stays under its 300-code-line limit, exactly as `SPLIT_COMMANDS` was for the same reason
+// (joshuafolkken/kit#2162, joshuafolkken/kit#2218, joshuafolkken/kit#2366). It is spread into
+// `AI_COMMANDS` so the commands stay grouped under the 'AI tools' category. `read:files` and
+// `edit:files` are the read/write halves of the round-trip fold (joshuafolkken/kit#2202 / #2366).
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const DOCUMENT_COMMANDS: Record<string, CommandEntry> = {
+	'doc:section': {
+		script: 'scripts/document/document-section-cli.ts',
+		description: 'Print one section of a markdown document, for a `file.md` → "Heading" reference',
+		category: 'AI tools',
+		reference: ['<file> <heading>', 'automation', ['none']],
+	},
+	'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']],
+	},
+	'doc:read': {
+		script: 'scripts/document/document-read-cli.ts',
+		description:
+			'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']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { DOCUMENT_COMMANDS }

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

@@ -0,0 +1,38 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The `PreToolUse` guard 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, joshuafolkken/kit#2298). It is spread into
+// `AI_COMMANDS` so the guards stay grouped with the other AI tools.
+//
+// **None declare `tsx_arguments`, for the reason `batch:guard` declares none** (joshuafolkken/kit#1342):
+// declaring any disqualifies a command from in-process dispatch, and these run in front of every read
+// or shell call. Each script calls `process.loadEnvFile` itself instead, through `hook-decision.ts`.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const GUARD_COMMANDS: Record<string, CommandEntry> = {
+	'investigation:guard': {
+		script: 'scripts/delegation/investigation-guard.ts',
+		description:
+			'Claude Code hook: refuse a read once the unedited-read threshold is reached again (reads the tool call on stdin)',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
+	'duplicate-read:guard': {
+		script: 'scripts/delegation/duplicate-read-guard.ts',
+		description:
+			'Claude Code hook: refuse a second whole-file read of a path whose content has not changed since the run last read it (reads the tool call on stdin)',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
+	'rule:guard': {
+		script: 'scripts/rules/rule-guard.ts',
+		description:
+			'Claude Code hook: deliver a trigger-delivered rule at the call that binds it (reads the tool call on stdin)',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { GUARD_COMMANDS }

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

@@ -0,0 +1,42 @@
+import type { CommandEntry } from './josh-command-types'
+
+const HOOKS_COMMANDS: Record<string, CommandEntry> = {
+	'prevent-main-commit': {
+		script: 'scripts/hooks/prevent-main-commit.ts',
+		description: 'Git hook: block commits to main',
+		category: 'Git hooks',
+		reference: ['', 'automation', ['none']],
+	},
+	'check-commit-message': {
+		script: 'scripts/hooks/check-commit-message.ts',
+		description: 'Git hook: validate commit message',
+		category: 'Git hooks',
+		reference: ['[<message-file>]', 'automation', ['none']],
+	},
+	'secretlint-scan': {
+		script: 'scripts/security/secretlint-scan.ts',
+		description: 'Git hook: scan staged files for secrets',
+		category: 'Git hooks',
+		reference: ['[paths...]', 'automation', ['none']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+	'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']],
+	},
+}
+
+export { HOOKS_COMMANDS }

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

@@ -0,0 +1,69 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The issue-reading and issue-citation commands, split out of `josh-commands-ai.ts` when the mandated
+// `issue:cite` section pushed that file past its 300-line ceiling (joshuafolkken/kit#2220) — the same
+// group-per-file shape `LANE_COMMANDS` and `SPLIT_COMMANDS` already take. `COMMAND_MAP` spreads this
+// in, so nothing downstream sees where an entry lives.
+
+// The synopsis `issue:state` and `issue:cite` share: a list of numbers with an optional cross-repo
+// flag. One constant, so the two cannot drift and the literal is not duplicated.
+const ISSUES_WITH_REPO = '<issue...> [--repo <owner/repo>]'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const ISSUE_COMMANDS: Record<string, CommandEntry> = {
+	'issue:read': {
+		script: 'scripts/issue/issue-read-cli.ts',
+		description: "Print each issue's title, body and every comment on it, in one call",
+		category: 'AI tools',
+		reference: ['<issue...>', 'automation', ['network']],
+	},
+	'issue:state': {
+		script: 'scripts/issue/issue-state-cli.ts',
+		description:
+			"Print each issue's state and labels, in the spelling the documents compare against",
+		category: 'AI tools',
+		reference: [ISSUES_WITH_REPO, 'automation', ['network']],
+	},
+	'issue:scout': {
+		script: 'scripts/issue/issue-scout-cli.ts',
+		description:
+			'Before filing: say whether an issue like this exists and which epic it belongs to',
+		category: 'AI tools',
+		reference: ['<title> [--body <summary>]', 'automation', ['network']],
+	},
+	'defect:rate': {
+		script: 'scripts/issue/defect-rate-cli.ts',
+		description:
+			'Print the defect rate of merged work: defects filed per behavior change completed',
+		category: 'AI tools',
+		reference: ['[--days <n>]', 'automation', ['network']],
+	},
+	'issue:fold': {
+		script: 'scripts/issue/issue-fold-cli.ts',
+		description:
+			'Before a second filing: say whether findings from this session fold into one issue',
+		category: 'AI tools',
+		reference: ['<title>... [--not-separable] [--json]', 'automation', ['none']],
+	},
+	'issue:fold-existing': {
+		script: 'scripts/issue/issue-fold-existing-cli.ts',
+		description: 'Assess whether a complete draft can join an unstarted issue',
+		category: 'AI tools',
+		reference: ['<assessment.json>', 'automation', ['none']],
+	},
+	'issue:cite': {
+		script: 'scripts/issue/issue-cite-cli.ts',
+		description: 'Print the paste-ready number-link citation line for each issue, in one call',
+		category: 'AI tools',
+		reference: [ISSUES_WITH_REPO, 'automation', ['network']],
+	},
+	'issue:comment': {
+		script: 'scripts/issue/issue-comment-cli.ts',
+		description: 'Post one comment to an issue from a file, so no shell expands the body',
+		category: 'AI tools',
+		reference: ['<issue> --body <text> | --body-file <path>', 'automation', ['network']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { ISSUE_COMMANDS }

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

@@ -0,0 +1,75 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+// The `lane:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its line
+// limit (joshuafolkken/kit#2162). One script answers `lane:open` / `lane:close` / `lane:list` /
+// `lane:prune` / `lane:output` / `lane:dispatch` / `lane:await`, told apart by the verb below;
+// `lane:launch` is the composite that opens, pops-and-installs on the first lane, and dispatches.
+const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
+// `JOSH_LANE_ROOT` and `JOSH_LANE_LIMIT` are personal, non-committed settings, so every lane command
+// has to read `.env` to see them — without this the two are documented and unreachable.
+const LANE_ARGUMENTS = { script: LANE_SCRIPT, tsx_arguments: OPTIONAL_ENV_FILE_FLAGS } as const
+const ISSUE_WITH_OPTIONS = '<issue> [options]'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const LANE_COMMANDS: Record<string, CommandEntry> = {
+	'lane:open': {
+		...LANE_ARGUMENTS,
+		description: 'Open a lane: a linked work tree with its own branch and its own port seed',
+		category: 'AI tools',
+		reference: [ISSUE_WITH_OPTIONS, 'automation', ['files', 'git']],
+		default_script_arguments: ['open'],
+	},
+	'lane:close': {
+		...LANE_ARGUMENTS,
+		description: 'Close a lane, leaving no work tree, branch or directory behind',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['files', 'git']],
+		default_script_arguments: ['close'],
+	},
+	'lane:list': {
+		...LANE_ARGUMENTS,
+		description: 'List the open lanes: which issue, which ports, and where each one is',
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+		default_script_arguments: ['list'],
+	},
+	'lane:prune': {
+		...LANE_ARGUMENTS,
+		description: 'Close every lane an interruption left without its work tree',
+		category: 'AI tools',
+		reference: ['', 'automation', ['files', 'git']],
+		default_script_arguments: ['prune'],
+	},
+	'lane:output': {
+		...LANE_ARGUMENTS,
+		description: 'Record, or read back, where the unit running a lane’s child writes',
+		category: 'AI tools',
+		reference: ['<issue> [path]', 'automation', ['files']],
+		default_script_arguments: ['output'],
+	},
+	'lane:dispatch': {
+		...LANE_ARGUMENTS,
+		description: 'Start a lane’s child as a detached process that outlives this session',
+		category: 'AI tools',
+		reference: ['<issue> <prompt>', 'automation', ['processes']],
+		default_script_arguments: ['dispatch'],
+	},
+	'lane:await': {
+		...LANE_ARGUMENTS,
+		description:
+			'Block until any of the named in-flight lane children completes; prints which one finished',
+		category: 'AI tools',
+		reference: ['<issue> [<issue>...]', 'automation', ['processes']],
+		default_script_arguments: ['await'],
+	},
+	'lane:launch': {
+		script: 'scripts/lane/lane-launch-cli.ts',
+		description:
+			'Collapse a backlogrun lane-start event into one call: open the lane, pop and re-install on the first, dispatch the child',
+		category: 'AI tools',
+		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { LANE_COMMANDS }

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

@@ -0,0 +1,37 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The linters for the fixed-shape artifacts a run writes by hand (joshuafolkken/kit#2123). They are
+// `AI tools` by category, like every other automation command, but live in their own file so
+// `josh-commands-ai.ts` stays under its line ceiling.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const LINT_COMMANDS: Record<string, CommandEntry> = {
+	'issue:lint': {
+		script: 'scripts/issue/issue-lint-cli.ts',
+		description: "Check an issue body file for the template's required headings",
+		category: 'AI tools',
+		reference: ['<path>', 'automation', ['files']],
+	},
+	'issue:backlinks': {
+		script: 'scripts/issue/issue-backlinks-cli.ts',
+		description: 'Classify an origin issue’s upstream backlinks: ok, missing, or wrong heading',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
+	'report:lint': {
+		script: 'scripts/report/report-lint-cli.ts',
+		description: 'Check a two-layer work summary on stdin against its mechanical format rules',
+		category: 'AI tools',
+		reference: ['(reads stdin)', 'automation', ['none']],
+	},
+	cases: {
+		script: 'scripts/cases/cases-cli.ts',
+		description:
+			'Read changed paths and print the I/O boundaries crossed and their mandatory abnormal cases: network | process | fs | none',
+		category: 'AI tools',
+		reference: ['<path...>', 'automation', ['files']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { LINT_COMMANDS }

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

@@ -0,0 +1,80 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
+	doctor: {
+		script: 'scripts/doctor/doctor.ts',
+		description:
+			'Diagnose PATH shadowing of the global josh and show the discovered repository map (--fix reclaims a stale shim)',
+		category: 'Maintenance',
+		reference: ['[--fix]', 'developer', ['files']],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+	},
+	overrides: {
+		script: 'scripts/overrides/overrides-check.ts',
+		description: 'Check pnpm overrides for drift',
+		category: 'Maintenance',
+		reference: ['[--save]', 'maintainer', ['files']],
+	},
+	audit: {
+		script: 'scripts/security/security-audit.ts',
+		description: 'Run security audit',
+		category: 'Maintenance',
+		reference: ['', 'developer', ['processes']],
+	},
+	'audit:provision': {
+		script: 'scripts/security/security-audit-provision.ts',
+		description: 'Install the pinned osv-scanner when the audit cannot find one (no-op if present)',
+		category: 'Maintenance',
+		reference: ['', 'automation', ['files', 'network']],
+	},
+	'reconcile-templates': {
+		script: 'scripts/sync/reconcile-templates.ts',
+		description: 'Record template source hashes (--check to verify drift)',
+		category: 'Maintenance',
+		reference: ['', 'maintainer', ['files']],
+	},
+	latest: {
+		shell: [
+			'sh',
+			'-c',
+			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:corepack && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:scope --record',
+		],
+		description: 'Update pnpm, dependencies, and run security audit',
+		category: 'Maintenance',
+		reference: ['', 'maintainer', ['files', 'network', 'processes']],
+		argument_targets: ['latest:corepack', 'latest:update', 'audit'],
+	},
+	'latest:scope': {
+		script: 'scripts/version/latest-scope-cli.ts',
+		description:
+			'Say whether this run has to update dependencies, from when josh latest last finished (--record notes a run)',
+		category: 'Maintenance',
+		reference: ['[--record] [--json]', 'automation', ['files']],
+		// `JOSH_LATEST_MAX_AGE_HOURS` is documented as a project setting, so it has to be readable
+		// 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,
+	},
+	'latest:guard': {
+		script: 'scripts/version/latest-lane-guard.ts',
+		description: 'Refuse josh latest inside a lane (the update stamp is keyed to the project root)',
+		category: 'Maintenance',
+		reference: ['', 'automation', ['files']],
+	},
+	'latest:corepack': {
+		script: 'scripts/version/latest-corepack.ts',
+		description: 'Update pnpm on the current major while preserving the integrity pin',
+		category: 'Maintenance',
+		reference: ['', 'maintainer', ['files', 'network']],
+	},
+	'latest:update': {
+		script: 'scripts/version/latest-update.ts',
+		description: 'Update all dependencies to latest',
+		category: 'Maintenance',
+		reference: ['', 'maintainer', ['files', 'network']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { MAINTENANCE_COMMANDS }

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

@@ -0,0 +1,53 @@
+import type { CommandEntry } from './josh-command-types'
+
+// 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.
+/* eslint-disable @typescript-eslint/naming-convention */
+const PROJECT_COMMANDS: Record<string, CommandEntry> = {
+	init: {
+		script: 'scripts/init/init.ts',
+		description: 'Initialize config in a new project',
+		category: 'Project',
+		reference: ['', 'developer', ['files', 'processes']],
+	},
+	sync: {
+		script: 'scripts/sync/sync.ts',
+		description: 'Sync config files',
+		category: 'Project',
+		reference: ['', 'developer', ['files']],
+	},
+	'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']],
+	},
+	'sonar:hotspots': {
+		script: 'scripts/sonar/sonar-hotspots-cli.ts',
+		description:
+			"Fetch SonarCloud hotspots on a pull request and print each one's Step B disposition",
+		category: 'Project',
+		reference: ['<PR>', 'automation', ['network']],
+	},
+	'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']],
+	},
+	propagate: {
+		script: 'scripts/propagate/propagate.ts',
+		description: 'Carry the published release into every consumer repository next to this one',
+		category: 'Project',
+		reference: ['[--dry-run] [--skip-publish-wait]', 'maintainer', ['files', 'network']],
+	},
+	adopt: {
+		script: 'scripts/adopt/adopt.ts',
+		description: 'Upgrade every installed @joshuafolkken toolkit here and open the pull request',
+		category: 'Project',
+		reference: ['[--dry-run]', 'developer', ['files', 'git', 'network', 'processes']],
+	},
+}
+
+export { PROJECT_COMMANDS }