@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -0,0 +1,181 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+const REPO = '--repo <owner/repo>'
+const BODY_FILE = '--body-file <path>'
+const EVIDENCE_FILE = '--evidence-file <path>'
+const EVIDENCE_REFERENCE = `<issue> ${EVIDENCE_FILE}`
+
+// The commands that write to an issue — comment, plan, already-done, measured and file — split out of
+// `josh-commands-issue.ts` when each command's usage moved onto its entry (#4185). `ISSUE_COMMANDS`
+// spreads this in at the same place, so the map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
+	'issue:comment': {
+		script: 'scripts/issue/issue-comment-main.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']],
+		usage: {
+			examples: [
+				{
+					arguments: '2304 --body-file .josh/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.',
+				},
+			],
+		},
+	},
+	'issue:plan': {
+		script: 'scripts/issue/issue-plan-cli.ts',
+		description:
+			'Record a plan: normalize the title, fill a blank body or comment, apply run:planned',
+		category: 'AI tools',
+		reference: [
+			'<issue> --body-file <path> [--title <title>] [--planned] [--repo <owner/name>]',
+			'automation',
+			['network'],
+		],
+		usage: {
+			examples: [
+				{
+					arguments: '4134 --body-file plan.md --title "Add issue:plan" --planned',
+					note: "kickoff's three writes",
+				},
+			],
+			flags: [
+				{
+					names: [BODY_FILE],
+					description:
+						'the plan, from a file or stdin (`-`): a blank body takes it, else a comment.',
+				},
+				{ names: ['--title <title>'], description: 'replace the issue title first.' },
+				{
+					names: ['--planned'],
+					description:
+						'apply `run:planned` once the plan is posted, so the next entry skips planning.',
+				},
+				{
+					names: ['--repo <owner/name>'],
+					description: "write to that repository's issue.",
+				},
+			],
+		},
+	},
+	'issue:already-done': {
+		script: 'scripts/issue/issue-already-done-cli.ts',
+		description:
+			'Exit an issue whose work is already merged: post the evidence, apply already-done, release the hold',
+		category: 'AI tools',
+		// Releasing the hold runs `run:hold`, which reaches the stop confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		reference: [EVIDENCE_REFERENCE, 'automation', ['network', 'files']],
+		usage: {
+			examples: [
+				{
+					arguments: '4130 --evidence-file .josh/tmp/already-done.md',
+					note: 'comment, label, release — in that order',
+				},
+			],
+			flags: [
+				{
+					names: [EVIDENCE_FILE],
+					description:
+						'the evidence comment: the merging PR or commit and, per acceptance criterion, its `file:line`. An empty file is refused before anything is written.',
+				},
+			],
+		},
+	},
+	'issue:measured': {
+		script: 'scripts/issue/issue-measured-cli.ts',
+		description:
+			'Complete a measurement-only issue: post the result, label it measured, close it, release the hold',
+		category: 'AI tools',
+		// Releasing the hold runs `run:hold`, which reaches the stop confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		reference: [EVIDENCE_REFERENCE, 'automation', ['network', 'files']],
+		usage: {
+			examples: [
+				{
+					arguments: '4452 --evidence-file .josh/tmp/measured.md',
+					note: 'comment, label, close, release — in that order',
+				},
+			],
+			flags: [
+				{
+					names: [EVIDENCE_FILE],
+					description:
+						'the result comment: per acceptance criterion, the measurement and the run it came from. An empty file is refused before anything is written.',
+				},
+			],
+		},
+	},
+	'issue:file': {
+		script: 'scripts/issue/issue-file-cli.ts',
+		description:
+			'File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle',
+		category: 'AI tools',
+		reference: [
+			'<title> --body-file <path> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
+			'automation',
+			['network'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '"<title>" --body-file body.md' },
+				{ arguments: '"<title>" --body-file body.md --route tier-a --repo joshuafolkken/kit' },
+				{ arguments: '"<title>" --body-file body.md --distinct 2801,2795' },
+			],
+			flags: [
+				{ names: [BODY_FILE], description: 'the body. Required.' },
+				{
+					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).",
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { ISSUE_WRITE_COMMANDS }

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

@@ -1,4 +1,14 @@
 import type { CommandEntry } from './josh-command-types'
+import { ISSUE_WRITE_COMMANDS } from './josh-commands-issue-write'
+
+const REPO = '--repo <owner/repo>'
+const CONCURRENT = 'several numbers, read concurrently'
+const REPO_FLAG = {
+	names: [REPO],
+	description: 'read a child in another repository; applies to every number.',
+}
+const BODY_FILE = '--body-file <path>'
+const JSON_FLAG = { names: ['--json'], description: 'print the verdict and reason as JSON.' }
 
 // 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 — the same
@@ -17,75 +27,165 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 			"Record that the run read a person's update to its issue, printing the update it acknowledges",
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
+		usage: { examples: [{ arguments: '3773' }] },
 	},
 	'issue:read': {
-		script: 'scripts/issue/issue-read-cli.ts',
+		script: 'scripts/issue/issue-read-main.ts',
 		description: "Print each issue's title, body and every comment on it, in one call",
 		category: 'AI tools',
 		reference: ['<issue...>', 'automation', ['network']],
+		usage: {
+			examples: [{ arguments: '1715' }, { arguments: '1715 1567 1605', note: CONCURRENT }],
+		},
 	},
 	'issue:state': {
-		script: 'scripts/issue/issue-state-cli.ts',
+		script: 'scripts/issue/issue-state-main.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']],
+		usage: {
+			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:scout': {
-		script: 'scripts/issue/issue-scout-cli.ts',
+		script: 'scripts/issue/issue-scout-main.ts',
 		description:
 			'Before filing: say whether an issue like this exists and which epic it belongs to',
 		category: 'AI tools',
 		reference: ['<title> [--body <summary> | --body-file <path>]', 'automation', ['network']],
+		usage: {
+			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".',
+				},
+			],
+		},
+	},
+	'defect:origin': {
+		script: 'scripts/issue/defect-origin-main.ts',
+		description:
+			'List the merged pull requests that last changed what a defect issue names, as candidates for its origin line',
+		category: 'AI tools',
+		reference: ['<N>', 'automation', ['network']],
+		usage: {
+			examples: [{ arguments: '4241', note: 'newest first, merged before the issue was filed' }],
+		},
 	},
-	'defect:rate': {
-		script: 'scripts/issue/defect-rate-cli.ts',
-		description: 'Print the defect rate of merged work: defects filed per enhancement completed',
+	'defect:report': {
+		script: 'scripts/issue/defect-report-main.ts',
+		description:
+			'Count defects by the origin pull request their issue declares, by change kind and by area',
 		category: 'AI tools',
-		reference: ['[--days <n>]', 'automation', ['network']],
+		reference: ['', 'automation', ['network']],
+		usage: { examples: [{ arguments: '', note: 'every issue labelled bug, open or closed' }] },
 	},
 	'issue:fold': {
-		script: 'scripts/issue/issue-fold-cli.ts',
+		script: 'scripts/issue/issue-fold-main.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']],
+		usage: {
+			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: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> [--json]', 'automation', ['none']],
+		usage: { examples: [{ arguments: 'assessment.json --json' }] },
 	},
 	'issue:cite': {
-		script: 'scripts/issue/issue-cite-cli.ts',
+		script: 'scripts/issue/issue-cite-main.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']],
+		usage: {
+			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': {
-		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']],
-	},
-	'issue:file': {
-		script: 'scripts/issue/issue-file-cli.ts',
+	...ISSUE_WRITE_COMMANDS,
+	'plan:consumers': {
+		script: 'scripts/issue/plan-consumers-main.ts',
 		description:
-			'File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle',
+			"List every existing reference to each identifier a plan adds or changes, by kind, and draft the plan's existing-consumers section",
 		category: 'AI tools',
-		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
-			'automation',
-			['network'],
-		],
+		reference: ['<identifier...>', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'lane:pause' },
+				{ arguments: 'lane:pause run:paused', note: 'one block per identifier, one draft' },
+			],
+		},
 	},
 	'issue:release': {
-		script: 'scripts/issue/issue-release-cli.ts',
+		script: 'scripts/issue/issue-release-main.ts',
 		description:
 			"Link an Issue to the repository's open release Issue as its blocker (or, with --wait, as waiting on it), filing one when none is open",
 		category: 'AI tools',
 		reference: ['<issue> [--wait]', 'automation', ['network']],
+		usage: {
+			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`).',
+				},
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -1,5 +1,12 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
+const BARE = { arguments: '' }
+// `lane:pause` and `lane:resume` take the same target.
+const LANE_SIGNAL_EXAMPLES = [
+	{ arguments: '4198' },
+	{ arguments: '--all', note: 'every open lane' },
+]
+
 // The `lane:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its line
 // limit. One script answers `lane:open` / `lane:close` / `lane:list` /
 // `lane:prune` / `lane:output` / `lane:dispatch` / `lane:await`, told apart by the verb below;
@@ -14,6 +21,13 @@ const MEASURE_ARGUMENTS = {
 	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 } as const
 
+const PAUSE_ARGUMENTS = {
+	script: 'scripts/lane/lane-pause-cli.ts',
+	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+	category: 'AI tools',
+	reference: ['<issue> | --all', 'developer', ['processes']],
+} satisfies Partial<CommandEntry>
+
 /* eslint-disable @typescript-eslint/naming-convention */
 const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:open': {
@@ -22,6 +36,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: [ISSUE_WITH_OPTIONS, 'automation', ['files', 'git']],
 		default_script_arguments: ['open'],
+		usage: { examples: [{ arguments: '1490', note: 'prints the lane directory on stdout' }] },
 	},
 	'lane:close': {
 		...LANE_ARGUMENTS,
@@ -29,6 +44,10 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['files', 'git']],
 		default_script_arguments: ['close'],
+		usage: {
+			examples: [{ arguments: '1490' }, { arguments: '--all' }],
+			flags: [{ names: ['--all'], description: 'closes every lane.' }],
+		},
 	},
 	'lane:list': {
 		...LANE_ARGUMENTS,
@@ -36,6 +55,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['', 'automation', ['none']],
 		default_script_arguments: ['list'],
+		usage: { examples: [BARE] },
 	},
 	'lane:prune': {
 		...LANE_ARGUMENTS,
@@ -44,6 +64,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
+		usage: { examples: [BARE] },
 	},
 	'lane:output': {
 		...LANE_ARGUMENTS,
@@ -51,6 +72,12 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [path]', 'automation', ['files']],
 		default_script_arguments: ['output'],
+		usage: {
+			examples: [
+				{ arguments: '1713 /abs/path/to/agent-7.jsonl', note: 'record it; prints the path back' },
+				{ arguments: '1713', note: 'read it; prints the path, or `none`' },
+			],
+		},
 	},
 	'lane:dispatch': {
 		...LANE_ARGUMENTS,
@@ -58,6 +85,31 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> <prompt>', 'automation', ['processes']],
 		default_script_arguments: ['dispatch'],
+		usage: {
+			examples: [
+				{
+					arguments: '1749',
+					note: "prints the child's pid; a refusal is an empty capture and exit 1",
+				},
+			],
+			flags: [
+				{
+					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_MODEL'],
+					description:
+						'Claude Code role overrides; Anthropic defaults are respectively `claude-opus-5-5`, `claude-opus-5-5`, and `claude-opus-5-5`. Codex keeps its provider-specific model.',
+				},
+				{
+					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_EFFORT'],
+					description:
+						'role effort overrides for either provider; defaults are `medium`, `medium`, and `high`.',
+				},
+				{
+					names: ['JOSH_REVIEWER_VERIFICATION_{MODEL,EFFORT}'],
+					description:
+						'review round 2 and later (the verification pass); Anthropic defaults are `claude-sonnet-5-5` / `high`, falling back to `JOSH_REVIEWER_*`.',
+				},
+			],
+		},
 	},
 	'lane:await': {
 		...LANE_ARGUMENTS,
@@ -66,13 +118,31 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [<issue>...] [--owner <pid>]', 'automation', ['files', 'processes']],
 		default_script_arguments: ['await'],
+		usage: {
+			examples: [
+				{ arguments: '1749 1750', note: 'block until either lane completes' },
+				{
+					arguments: '1749 1750 --owner "$PPID"',
+					note: 'reclaim the carry record for a resumed conversation first',
+				},
+			],
+		},
 	},
 	'lane:launch': {
-		script: 'scripts/lane/lane-launch-cli.ts',
+		script: 'scripts/lane/lane-launch-main.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']],
+		usage: {
+			examples: [
+				{ arguments: '1749', note: 'every lane after the first' },
+				{
+					arguments: '1749 --stash "backlogrun: josh latest before lanes"',
+					note: 'the first lane only',
+				},
+			],
+		},
 	},
 	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
 	'lane:restart': {
@@ -82,6 +152,35 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 			'Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session — not counted as an outage or a failure',
 		category: 'AI tools',
 		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [{ arguments: '3769', note: "prints the fresh child's pid" }],
+		},
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:withdraw': {
+		script: 'scripts/lane/lane-withdraw-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work and close the lane, leaving its issue open for the next run — booked withdrawn, not as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue> --reason <text>', 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
+		},
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so `--all` finds the lanes.
+	'lane:pause': {
+		...PAUSE_ARGUMENTS,
+		description:
+			'Suspend a running lane child’s process tree (SIGSTOP) in place, leaving its work tree, branch and issue untouched, and record the pause in the lane’s state and the run’s event stream',
+		default_script_arguments: ['pause'],
+		usage: { examples: LANE_SIGNAL_EXAMPLES },
+	},
+	'lane:resume': {
+		...PAUSE_ARGUMENTS,
+		description: 'Let a paused lane child carry on from where it stopped (SIGCONT)',
+		default_script_arguments: ['resume'],
+		usage: { examples: LANE_SIGNAL_EXAMPLES },
 	},
 	// A live run's lane limit: `.env` is read so the bare form reports the
 	// `JOSH_LANE_LIMIT` a person set there when no override stands.
@@ -92,6 +191,13 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 			'Change a live backlogrun’s lane limit without stopping it, or print the limit, lanes in use and free lanes',
 		category: 'AI tools',
 		reference: ['[<limit>] [--reset]', 'developer', ['files']],
+		usage: {
+			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' },
+			],
+		},
 	},
 	// The lane-limit measurement: `.env` is read so `lane:stats` labels the row
 	// with the `JOSH_LANE_LIMIT` a person set there.
@@ -102,14 +208,18 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--every <seconds>]', 'maintainer', ['files']],
 		default_script_arguments: ['sample'],
+		usage: { examples: [{ arguments: '', note: 'one machine-load reading' }] },
 	},
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those',
+			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, and the duration and reuse count of each gate check last',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],
+		usage: {
+			examples: [{ arguments: '--period 7', note: "a 7-day period's stage medians and maxima" }],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -7,29 +7,40 @@ import type { CommandEntry } from './josh-command-types'
 /* eslint-disable @typescript-eslint/naming-convention */
 const LINT_COMMANDS: Record<string, CommandEntry> = {
 	'issue:lint': {
-		script: 'scripts/issue/issue-lint-cli.ts',
+		script: 'scripts/issue/issue-lint-main.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']],
+		usage: { examples: [{ arguments: '.josh/tmp/issue-body.md' }] },
 	},
 	'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']],
+		usage: { examples: [{ arguments: '< summary.md' }] },
+	},
+	'report:template': {
+		script: 'scripts/report/report-template-cli.ts',
+		description:
+			'Print the work summary or completion report skeleton in the session language: summary | done',
+		category: 'AI tools',
+		reference: ['summary|done [<path>...]', 'automation', ['files']],
+		usage: {
+			examples: [{ arguments: 'summary scripts/report/report-lint.ts' }, { arguments: 'done' }],
+		},
 	},
 	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',
+			'Read changed paths and print the boundaries crossed and their mandatory abnormal cases: network | process | fs | time | state | env | none',
 		category: 'AI tools',
 		reference: ['<path...>', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: 'scripts/a.ts scripts/b.ts', note: 'the boundaries these paths cross' },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */