@joshuafolkken/kit 1.1455.0 → 1.1514.0

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

@@ -0,0 +1,180 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the epic and backlog commands `docs/josh-commands-backlog.md` documents under "Epics
+// and backlog", keyed by command name. The page's usage blocks are generated from this table and
+// `josh help <command>` prints it, so an example or a flag is written once, here (#3938).
+const EXCLUDE = '--exclude <N>'
+const BUDGET = '--answer candidates --started "$started" --active "$active"'
+const REPO = '--repo <owner/repo>'
+const JUST_MERGED = 'skip the issue just merged'
+const EXCLUDE_1630 = '--exclude 1630'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const BACKLOG_USAGE: Readonly<Record<string, CommandUsage>> = {
+	epic: {
+		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',
+			},
+		],
+		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': {
+		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': { examples: [{ arguments: '874' }] },
+	'epic:audit': { examples: [{ arguments: '858' }] },
+	'epic:check': { examples: [{ arguments: '700' }] },
+	'auto-ok:next': {
+		examples: [{ arguments: '' }, { arguments: '--exclude 906', note: JUST_MERGED }],
+		flags: [
+			{
+				names: [EXCLUDE],
+				description: 'drop issues from the answer; comma-separated, repeatable.',
+			},
+		],
+	},
+	'auto-ok:judge': {
+		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, applies the run label and then `auto-ok`, and notes it on the progress board.',
+			},
+			{ names: ['--decline <N> --reason <text>'], description: 'applies nothing.' },
+		],
+	},
+	'backlog:next': {
+		examples: [{ arguments: '' }, { arguments: EXCLUDE_1630, note: JUST_MERGED }],
+		flags: [
+			{
+				names: [EXCLUDE],
+				description: 'drop issues from every bucket; comma-separated, repeatable.',
+			},
+		],
+	},
+	'backlog:plan': {
+		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:stalled': { examples: [{ arguments: '' }] },
+	'backlog:budget': {
+		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": "…"}`.',
+			},
+		],
+	},
+	'backlog:offer': {
+		examples: [{ arguments: '--started "$started" --active "$active" --running 2 --retries 1' }],
+	},
+	'backlog:drive': {
+		examples: [{ arguments: '--owner "$PPID" [--max <n>] [--idle <minutes>] [--only]' }],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { BACKLOG_USAGE }

package/scripts/josh/josh-usage-developer.ts

@@ -0,0 +1,230 @@
+import { ports } from '#ports'
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands.md` documents, keyed by command name. The page's
+// usage blocks are generated from this table and `josh help <command>` prints it, so an example or a
+// flag is written once, here (#3932).
+// The unseeded ports are read from `ports/index.js`, their one definition (#818).
+const UNSEEDED: Readonly<Record<string, string | undefined>> = {}
+const NARROWED = { arguments: 'scripts/thing.ts', note: 'narrow by the given files instead' }
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const DEVELOPER_USAGE: Readonly<Record<string, CommandUsage>> = {
+	gate: {
+		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: { examples: [{ arguments: '' }] },
+	'lint:related': { examples: [{ arguments: '' }, NARROWED] },
+	lines: {
+		examples: [{ arguments: 'scripts/hooks/format-edited-file.ts scripts/josh/josh-logic.ts' }],
+	},
+	bytes: {
+		examples: [
+			{ arguments: 'docs/josh-commands.md', note: 'one document' },
+			{ arguments: '', note: 'scan: every budgeted document near its ceiling' },
+		],
+	},
+	metrics: {
+		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" },
+		],
+	},
+	format: { examples: [{ arguments: '' }] },
+	'cspell:dot': { examples: [{ arguments: '', note: 'includes dotfiles' }] },
+	behavior: { examples: [{ arguments: '' }] },
+	'exports:unused': { examples: [{ arguments: '' }] },
+	'test:unit': { examples: [{ arguments: '' }] },
+	'test:related': {
+		examples: [
+			{ arguments: '' },
+			NARROWED,
+			{ arguments: '--silent', note: 'flags are forwarded to vitest' },
+		],
+	},
+	'test:declared': {
+		examples: [
+			{ arguments: '' },
+			{ arguments: '--match', note: 'check Step 0 declarations on stdin' },
+			{ arguments: '--help', note: 'print usage, including the --match stdin form' },
+		],
+	},
+	'test:e2e': { examples: [{ arguments: '' }] },
+	test: { examples: [{ arguments: '' }] },
+	check: { examples: [{ arguments: '' }] },
+	port: {
+		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`,
+			},
+		],
+	},
+	profile: { examples: [{ arguments: '' }] },
+	init: {
+		examples: [
+			{
+				arguments: '',
+				note: 'create/merge config files, install and format (--no-install skips both, --dry-run only prints the plan)',
+			},
+		],
+	},
+	'registry:migrate': { examples: [{ arguments: '' }] },
+	sync: { examples: [{ arguments: '', note: 'overwrite managed files' }] },
+	uninstall: {
+		examples: [
+			{ arguments: '', note: 'show the plan, then ask' },
+			{ arguments: '--yes', note: 'remove without asking' },
+		],
+	},
+	adopt: {
+		examples: [
+			{ arguments: '' },
+			{ arguments: '--dry-run', note: 'report the steps without touching anything' },
+		],
+		flags: [{ names: ['--dry-run'], description: 'report the plan without writing.' }],
+	},
+	git: {
+		examples: [
+			{ arguments: '', note: 'interactive' },
+			{ arguments: '-y', note: 'unattended (no TTY required)' },
+			{ arguments: '-y "title"', note: 'set commit message prefix' },
+			{ arguments: '-y "<title> #<N>"', note: 'follow-up commit on the same branch' },
+			{
+				arguments: '-y --skip-commit --skip-push',
+				note: 'open the PR without committing/pushing',
+			},
+		],
+		flags: [
+			{
+				names: ['-y', '--yes'],
+				description: 'run non-interactively; works without a TTY (agent or CI shell).',
+			},
+			{
+				names: ['--skip-commit', '--skip-push'],
+				description: 'recover/open a PR without a new commit or push.',
+			},
+		],
+	},
+	pr: { examples: [{ arguments: '', note: 'open the PR for the current <N>-<slug> branch' }] },
+	'review:findings': { examples: [{ arguments: '' }] },
+	'main:sync': { examples: [{ arguments: '' }] },
+	'main:merge': { examples: [{ arguments: '' }] },
+	version: {
+		examples: [
+			{ arguments: '' },
+			{
+				arguments: '--upgrade',
+				note: 'upgrade global + project to latest, then re-run fix-gh-packages',
+			},
+		],
+		flags: [
+			{
+				names: ['--upgrade'],
+				description:
+					'upgrade both the global install (`pnpm add -g`) and the project devDependency (`pnpm add -D` + `fix-gh-packages`); already-current or not-installed targets are skipped.',
+			},
+		],
+	},
+	ranges: { examples: [{ arguments: '' }] },
+	doctor: {
+		examples: [
+			{ arguments: '', note: 'diagnose only' },
+			{ arguments: '--fix', note: 'reclaim the global josh by removing a stale kit shim' },
+			{ arguments: '--ports', note: 'also print the per-repository port-seed table' },
+		],
+		flags: [
+			{
+				names: ['--fix'],
+				description:
+					'remove a shadowing binary **only if it is a kit shim** (its body references `@joshuafolkken/kit` or the removed `install-bin` script); any other binary is left and reported for manual review. Also the one-shot recovery for an old project that re-created the global shim.',
+			},
+			{ names: ['--ports'], description: 'additionally print the port-seed table (see below).' },
+		],
+	},
+	audit: { examples: [{ arguments: '' }] },
+	overrides: {
+		examples: [
+			{ arguments: '', note: 'verify overrides unchanged' },
+			{ arguments: '--save', note: 'snapshot current merged overrides' },
+		],
+		flags: [
+			{
+				names: ['--save'],
+				description:
+					'write the current merged overrides to `.overrides-snapshot.json` (gitignored); later runs compare against it and exit non-zero on any add, removal, or change.',
+			},
+		],
+	},
+	backlogrun: {
+		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' },
+		],
+	},
+	'lane:limit': {
+		examples: [
+			{ arguments: '8', note: "raise or lower the live run's limit to 8" },
+			{ arguments: '', note: 'print the limit, the lanes in use and the free lanes' },
+			{ arguments: '--reset', note: 'clear the override; JOSH_LANE_LIMIT applies again' },
+		],
+	},
+	'lane:withdraw': {
+		examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
+	},
+	'test:red': { examples: [{ arguments: '', note: 'red, green, no-test or test-only' }] },
+	start: {
+		examples: [
+			{ arguments: '', note: 'asks for the profile and the repository' },
+			{
+				arguments: '--yes --github --profile basic',
+				note: 'unattended, including the GitHub repository',
+			},
+		],
+		flags: [
+			{ names: ['--profile basic|full'], description: 'the profile, without asking.' },
+			{ names: ['--yes'], description: 'take the defaults — not consent to write to GitHub.' },
+			{ names: ['--github'], description: 'create the GitHub repository and push `main`.' },
+			{ names: ['--public'], description: 'create the repository public instead of private.' },
+			{
+				names: ['--init-command "<command>"'],
+				description: 'run this setup command in place of `josh init`.',
+			},
+			{
+				names: ['--push-preflight-command "<command>"'],
+				description:
+					'a check run before the first step when the plan pushes; a failure stops the run before it writes anything.',
+			},
+			{ names: ['--dry-run'], description: 'print the plan and change nothing.' },
+		],
+	},
+	latest: { examples: [{ arguments: '', note: 'full update (update + audit + pnpm)' }] },
+	'latest:corepack': { examples: [{ arguments: '', note: 'update pnpm only' }] },
+	'latest:update': { examples: [{ arguments: '', note: 'update dependencies only' }] },
+	'lane:restart': {
+		examples: [{ arguments: '3769', note: "prints the fresh child's pid" }],
+	},
+	'rule:value': {
+		examples: [
+			{ arguments: '' },
+			{
+				arguments: '--refresh',
+				note: 'write the reading to the loop-head cache instead of stdout',
+			},
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { DEVELOPER_USAGE }

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

@@ -0,0 +1,38 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the Claude Code and Codex hook commands `docs/josh-commands-automation.md` documents
+// under "Development", keyed by command name. A hook is fed its payload as JSON on stdin, so each
+// example names the event that runs it rather than an argument. The page's usage blocks are generated
+// from this table and `josh help <command>` prints it, so an example is written once, here (#3981).
+const PRE_TOOL_USE = 'run by the PreToolUse hook, the pending tool call as JSON on stdin'
+const IN_PRETOOL_GUARD = 'run inside pretool:guard, not wired on its own'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const HOOK_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'format:edited': {
+		examples: [
+			{ arguments: '', note: 'run by the PostToolUse hook, the tool call as JSON on stdin' },
+		],
+	},
+	'batch:guard': { examples: [{ arguments: '', note: IN_PRETOOL_GUARD }] },
+	'investigation:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+	'duplicate-read:guard': { examples: [{ arguments: '', note: IN_PRETOOL_GUARD }] },
+	'rule:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+	'rule:list': { examples: [{ arguments: '', note: 'print every trigger-delivered rule' }] },
+	'pretool:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+	'codex:hook-adapter': {
+		examples: [
+			{ arguments: 'pretool', note: 'a Codex PreToolUse payload on stdin' },
+			{ arguments: 'posttool', note: 'a Codex PostToolUse payload on stdin' },
+		],
+	},
+	'stop:guard': {
+		examples: [{ arguments: '', note: 'run by the Stop hook, the stop payload as JSON on stdin' }],
+	},
+	'session:lang': {
+		examples: [{ arguments: '', note: 'run by the UserPromptSubmit hook; `ja` prints nothing' }],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { HOOK_USAGE }

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

@@ -0,0 +1,205 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the issue commands `docs/josh-commands-backlog.md` documents under "Issues", keyed by
+// command name. The page's usage blocks are generated from this table and `josh help <command>`
+// prints it, so an example or a flag is written once, here (#3938). The epic and backlog commands are
+// `josh-usage-backlog.ts`, the review and delegation commands `josh-usage-review.ts`.
+const REPO = '--repo <owner/repo>'
+const BODY_FILE = '--body-file <path>'
+const CONCURRENT = 'several numbers, read concurrently'
+const REPO_FLAG = {
+	names: [REPO],
+	description: 'read a child in another repository; applies to every number.',
+}
+const JSON_FLAG = { names: ['--json'], description: 'print the verdict and reason as JSON.' }
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const ISSUE_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'issue:read': {
+		examples: [{ arguments: '1715' }, { arguments: '1715 1567 1605', note: CONCURRENT }],
+	},
+	'issue:ack': { examples: [{ arguments: '3773' }] },
+	'issue:state': {
+		examples: [
+			{ arguments: '42', note: 'single-number shape' },
+			{ arguments: '42 43 44', note: 'each block headed by `issue:`' },
+			{ arguments: '42 43 --repo joshuafolkken/app-kit', note: 'a child in another repo' },
+		],
+		flags: [REPO_FLAG],
+	},
+	'issue:release': {
+		examples: [
+			{ arguments: '3360' },
+			{ arguments: '3716 --wait', note: 'blocked by the release issue instead' },
+		],
+		flags: [
+			{
+				names: ['--wait'],
+				description:
+					'the issue is blocked by the release issue instead, so `backlog:next` offers it again once the release ships (`.claude/skills/workflow-commands/prerequisite.md`).',
+			},
+		],
+	},
+	'issue:scout': {
+		examples: [
+			{ arguments: '"Stop the gate re-running after every edit"' },
+			{ arguments: '"<title>" --body "parent: #1246"' },
+			{ arguments: '"<title>" --body-file draft.md' },
+		],
+		flags: [
+			{
+				names: ['--body "<text>"'],
+				description:
+					'supply references (`#N`) in a `parent: #N` line or an acceptance-criteria section so the epic half has a number to work from; without one there (a background mention does not count) it prints `Epic: not asked`.',
+			},
+			{
+				names: [BODY_FILE],
+				description:
+					'pass the whole draft, including its purpose, requirements and acceptance criteria. A file that cannot be read ends the command rather than being treated as "no candidates".',
+			},
+		],
+	},
+	'issue:file': {
+		examples: [
+			{ arguments: '"<title>" --body-file body.md --depth 1' },
+			{
+				arguments:
+					'"<title>" --body-file body.md --depth 0 --route tier-a --repo joshuafolkken/kit',
+			},
+			{ arguments: '"<title>" --body-file body.md --depth 1 --distinct 2801,2795' },
+		],
+		flags: [
+			{ names: [BODY_FILE], description: 'the body. Required.' },
+			{
+				names: ['--depth <0|1|2>'],
+				description:
+					'the depth label. Required. The criteria are `.claude/skills/workflow-commands/observation-filing.md` → "The depth test".',
+			},
+			{
+				names: ['--route <tier-a|split|interrupt|review-cap>'],
+				description:
+					'the `route:` label naming the filing route. Omit it for a filing with no route.',
+			},
+			{
+				names: ['--label <name>'],
+				description: 'an extra label (for example `epic`). Repeatable.',
+			},
+			{
+				names: [REPO],
+				description: 'the target repository. Defaults to this repository.',
+			},
+			{
+				names: ['--distinct <N,…>'],
+				description: 'duplicate candidates you read and judged distinct.',
+			},
+			{
+				names: ['--over-cap'],
+				description: 'the run is blocked by this filing; the cap lets it through.',
+			},
+			{
+				names: ['--no-auto-ok'],
+				description: "needs a person's judgement (Tier B / C); no `auto-ok`.",
+			},
+			{
+				names: ['--release'],
+				description:
+					"a consumer can use the change only once it is published. The filed issue becomes a blocker of the target's release issue (step 10).",
+			},
+		],
+	},
+	'issue:fold-existing': { examples: [{ arguments: 'assessment.json --json' }] },
+	'issue:fold': {
+		examples: [
+			{
+				arguments: '"First finding" "Second finding"',
+				note: 'fold | separate | no-fold-needed | undetermined',
+			},
+			{ arguments: '"a" "b" --not-separable', note: 'the pair is really one deliverable → fold' },
+			{ arguments: '"a" "b" --json', note: 'the verdict and reason, machine-readable' },
+		],
+		flags: [
+			{
+				names: ['--not-separable'],
+				description:
+					'declare the judgement half: the findings are one deliverable, so they fold whatever their size.',
+			},
+			JSON_FLAG,
+		],
+	},
+	'issue:cite': {
+		examples: [
+			{ arguments: '2220' },
+			{ arguments: '2220 1758 1252', note: CONCURRENT },
+			{ arguments: '45 --repo joshuafolkken/app-kit', note: 'bare numbers in another repository' },
+			{ arguments: 'joshuafolkken/app-kit#45 2220', note: 'per-token owner/repo#N notation' },
+		],
+		flags: [
+			{
+				names: [REPO],
+				description:
+					'the repository for every bare number; a token written `owner/repo#N` overrides it for itself.',
+			},
+		],
+	},
+	'issue:comment': {
+		examples: [
+			{
+				arguments: '2304 --body-file .claude/tmp/park.md',
+				note: 'the body from a file — no shell evaluates it',
+			},
+			{
+				arguments: '2304 --body "a short note"',
+				note: 'inline, for a body with no backticks or $',
+			},
+		],
+		flags: [
+			{
+				names: ['--body <text>'],
+				description: 'the comment body, inline. Trimmed, with `\\n` expanded to a newline.',
+			},
+			{
+				names: [BODY_FILE],
+				description:
+					'read the body from a file, or from stdin with `-`. The safe form the rule steers every caller toward.',
+			},
+		],
+	},
+	'pkg:scout': {
+		examples: [{ arguments: '"date formatting" --size 5' }],
+		flags: [
+			{ names: ['--size <n>'], description: 'how many candidates to fetch and rank (default 10).' },
+		],
+	},
+	'issue:lint': { examples: [{ arguments: '.claude/tmp/issue-body.md' }] },
+	'defect:rate': {
+		examples: [{ arguments: '', note: 'the last 14 days' }, { arguments: '--days 30' }],
+		flags: [
+			{
+				names: ['--days <n>'],
+				description:
+					'the window in whole days (default 14, at most 3650). Anything else prints the usage and exits 1.',
+			},
+		],
+	},
+	'issue:backlinks': { examples: [{ arguments: '2123' }] },
+	'report:lint': { examples: [{ arguments: '< summary.md' }] },
+	'stash:pop': {
+		examples: [
+			{ arguments: '"backlogrun: parked #2028"' },
+			{
+				arguments: '"backlogrun: josh latest before lanes" --dir "$dir"',
+				note: "into a lane's work tree",
+			},
+		],
+		flags: [
+			{
+				names: ['--dir <path>'],
+				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.',
+			},
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { ISSUE_USAGE }