@joshuafolkken/kit 1.1471.0 → 1.1514.0

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 }

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

@@ -0,0 +1,101 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the review, delegation and oracle commands `docs/josh-commands-backlog.md` documents
+// under "Review, delegation and oracles", 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 MACHINE_READABLE = 'the verdict and the reason, machine-readable'
+const LEVEL_ONLY = '--level-only'
+const JSON_FLAG = '--json'
+const CHECK = '--check'
+const ROUND_1_CLOSED = '--round-1-closed'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const REVIEW_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'review:brief': {
+		examples: [
+			{ arguments: '', note: 'round 1' },
+			{ arguments: '--round 2', note: 'verification pass, scoped to the fix delta' },
+			{ arguments: LEVEL_ONLY, note: 'the level alone (pre-commit review)' },
+			{ arguments: '--level-only --json', note: 'level and reason, machine-readable' },
+		],
+		flags: [
+			{
+				names: ['--round 2'],
+				description:
+					"target is round 1's fixes and nothing else (widened back to the whole change when the record's change base no longer matches).",
+			},
+			{
+				names: [LEVEL_ONLY],
+				description:
+					'print the level alone (level to stdout, reason to stderr); bypasses the scoped-green refusal.',
+			},
+			{
+				names: ['--staged', '--json'],
+				description: 'the staged diff; machine-readable level and reason.',
+			},
+		],
+	},
+	'review:round2': {
+		examples: [
+			{ arguments: '', note: '→ required' },
+			{ arguments: ROUND_1_CLOSED, note: '→ required | skip' },
+			{ arguments: JSON_FLAG, note: MACHINE_READABLE },
+		],
+		flags: [
+			{
+				names: [ROUND_1_CLOSED],
+				description:
+					'the caller states every round-1 High/Medium finding closed and none was filed or deferred; its absence answers `required`.',
+			},
+			{ names: [JSON_FLAG], description: 'machine-readable verdict and reason.' },
+		],
+	},
+	disposition: { examples: [{ arguments: '<path...>', note: '→ runtime | non-runtime' }] },
+	'review:attest': {
+		examples: [
+			{ arguments: '<nonce>', note: 'run by the review, from the checkout it read' },
+			{ arguments: CHECK, note: 'run by the run, before it acts on the review' },
+		],
+		flags: [
+			{ names: ['<nonce>'], description: 'attest the checkout the review read.' },
+			{
+				names: [CHECK],
+				description: 'verify before acting; `josh followup` asks again before merging.',
+			},
+		],
+	},
+	delegate: {
+		examples: [
+			{ arguments: 'gate-fix', note: '→ delegate' },
+			{ arguments: 'review', note: '→ keep' },
+			{ arguments: '--list', note: 'the enumeration, and what was rejected and why' },
+		],
+	},
+	fanout: {
+		examples: [
+			{ arguments: 'scripts/a.ts,scripts/a.test.ts scripts/b.ts', note: '→ parallel' },
+			{
+				arguments: 'scripts/a.ts,shared.ts scripts/b.ts,shared.ts',
+				note: '→ serial (units share shared.ts)',
+			},
+			{ arguments: 'scripts/a.ts', note: '→ serial (fewer than two units)' },
+		],
+	},
+	'split:assess': {
+		examples: [
+			{ arguments: '', note: '→ single' },
+			{ arguments: JSON_FLAG, note: MACHINE_READABLE },
+		],
+	},
+	'oracle:list': { examples: [{ arguments: '' }] },
+	'clone:scan': { examples: [{ arguments: '' }] },
+	cases: {
+		examples: [
+			{ arguments: 'scripts/a.ts scripts/b.ts', note: 'the boundaries these paths cross' },
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { REVIEW_USAGE }

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

@@ -0,0 +1,252 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the run-lifecycle commands `docs/josh-commands-run.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 (#3937). The page from `run:progress` on is
+// `josh-usage-session.ts`.
+const ISSUE = { arguments: '<N>' }
+const OUTPUT = '--output <path>'
+const OWNER = '--owner <pid>'
+const REPO_FLAG = { names: ['--repo <owner/name>'], description: 'a child in another repository.' }
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const RUN_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'run:hold': {
+		examples: [
+			{ arguments: '1091', note: 'claim for issue 1091' },
+			{ arguments: '1091 --fullrun', note: 'claim as `fullrun #1091` (what `run:entry` runs)' },
+		],
+		flags: [
+			{ names: ['--fullrun'], description: "marks the record as `fullrun #N`'s." },
+			{
+				names: ['--halfrun-stop'],
+				description: 'marks a `halfrun` stop for `run:entry` to adopt.',
+			},
+			{
+				names: ['--prrun-stop'],
+				description: 'marks a `prrun` stop with the commit its pull request is on.',
+			},
+		],
+	},
+	'run:release': {
+		examples: [
+			{ arguments: '1091', note: "release this run's own record" },
+			{ arguments: '--force', note: 'clear a record left by a run that has ended' },
+		],
+		flags: [
+			{
+				names: ['--force'],
+				description: "removes a record this run did not write, clearing another run's stale claim.",
+			},
+		],
+	},
+	'run:tidy': { examples: [{ arguments: '' }] },
+	'run:carry': {
+		examples: [
+			{ arguments: '--begin "backlogrun --max 5" --owner "$PPID"' },
+			{ arguments: '--json', note: 'read the record back in a resumed session' },
+			{ arguments: '--cut --owner "$PPID"', note: 'hand the record off before a cut' },
+			{
+				arguments:
+					'--retrospective --summary "0 filed; dropped #2240 already merged" --owner "$PPID"',
+				note: 'close the end-of-run retrospective',
+			},
+			{
+				arguments: '--resume "backlogrun --max 5" --owner "$PPID"',
+				note: 'adopt a record no cut handed off',
+			},
+			{
+				arguments: '--end --stopped "epic #2126: everything is blocked behind parked #2118"',
+				note: 'end + push',
+			},
+		],
+		flags: [
+			{
+				names: [OWNER],
+				description:
+					'the long-lived process spending the budget (`$PPID` under a loop); required by counts and `--begin` / `--resume`. A live PID stays `busy` if probes fail.',
+			},
+			{ names: ['--done <issue>'], description: "shrinks a named-issue run's `remaining` list." },
+			{
+				names: ['--merged <issue>'],
+				description:
+					'names the merged issue and counts it once against `merged_issues`, so a merge `run:merge` already recorded is not counted twice.',
+			},
+			{ names: ['--filed', '--cut'], description: 'increments, never totals.' },
+			{
+				names: ['--retrospective'],
+				description:
+					"marks the end-of-run retrospective run, once per invocation, and requires `--summary <text>` — the same close writes that result as one `retrospective` event on the run's event stream (best-effort), so a run that filed zero improvements reads apart from one whose retrospective never ran. Either flag without the other is refused.",
+			},
+			{
+				names: ['--stopped <reason>'],
+				description:
+					'rides on `--end`: the run stopped rather than finished, so one ⏸️ confirmation is pushed with the reason.',
+			},
+			{
+				names: ['--end'],
+				description:
+					'over a live record flushes pending ledger lines once (a failed flush goes to stderr and the record is still cleared); first collects each lane the run launched whose issue merged, exactly as `run:merge` would; keeps the run it removes as the last ended run — its invocation, start and end, one record overwritten by the next `--end` — so `run:board` can still draw a finished run.',
+			},
+		],
+	},
+	'run:add': {
+		examples: [
+			{ arguments: '101 102', note: 'ahead of the rest of the queue (`#N` works too)' },
+			{ arguments: '101 --no-priority', note: 'at the end of the queue' },
+		],
+	},
+	'run:wake': {
+		examples: [
+			{ arguments: '--start', note: 'launch the detached supervisor' },
+			{ arguments: '--list', note: 'supervisor state, cut/wake counts, latest progress line' },
+			{ arguments: '--stop', note: 'stop the supervisor alone' },
+			{ arguments: '--loop --interval 30', note: 'run the loop body in the foreground' },
+		],
+	},
+	'run:cut': {
+		examples: [
+			{ arguments: '1839', note: 'take the cut and hand it to a fresh process' },
+			{
+				arguments: '--impl 1839 --handoff .claude/tmp/handoff-1839.json',
+				note: 'cut mid-implementation, carrying the instruction',
+			},
+			{ arguments: '--resume 1839', note: "a fresh process's entry check" },
+			{ arguments: '--end', note: 'clear the record' },
+		],
+	},
+	'run:liveness': {
+		examples: [
+			{ arguments: '1169 --output <path>' },
+			{ arguments: '1169 --output <path> --window 45 --gap 2 --repo joshuafolkken/app-kit' },
+		],
+		flags: [
+			{
+				names: [OUTPUT],
+				description:
+					'absolute, under the home or temp directory; a symlink is followed and size compared as well as mtime.',
+			},
+			{
+				names: ['--process alive | none'],
+				description:
+					"overrides the process trace, which the command otherwise reads itself: the child's own command line (`fullrun #<N>`) or its detached ship supervisor.",
+			},
+			{
+				names: ['--window <min>'],
+				description: 'silent window the file must be frozen for (default 30).',
+			},
+			{ names: ['--gap <sec>'], description: 'spacing between samples (default 5).' },
+			REPO_FLAG,
+		],
+	},
+	'run:ending': {
+		examples: [
+			{ arguments: '2118 --output <path>' },
+			{ arguments: '2118 --output <path> --repo joshuafolkken/app-kit' },
+		],
+		flags: [
+			{
+				names: [OUTPUT],
+				description:
+					"the child's transcript, absolute and under the home or temp directory (validated the same way `run:liveness --output` is).",
+			},
+			REPO_FLAG,
+		],
+	},
+	'run:prep': { examples: [ISSUE] },
+	'run:entry': {
+		examples: [
+			{ arguments: '<N>', note: 'a `fullrun`' },
+			{ arguments: '<N> --to halfrun', note: 'a run that goes as far as `halfrun`' },
+		],
+	},
+	'run:status': {
+		examples: [ISSUE, { arguments: '<N> --repo <owner/repo>', note: 'a cross-repo child' }],
+	},
+	'run:next': { examples: [ISSUE] },
+	'run:step': {
+		examples: [
+			{ arguments: '<N>', note: "the run's next action for issue <N>" },
+			{ arguments: '', note: "the `backlogrun` parent's next action" },
+		],
+	},
+	'run:merge': {
+		examples: [
+			{
+				arguments: '<N> --epic <E> --repo <owner/repo> --owner "$PPID" --output <path>',
+				note: 'prints the next child number, or a verdict',
+			},
+			{ arguments: '<N> --owner "$PPID"', note: 'backlog offer (no epic)' },
+		],
+		flags: [
+			{
+				names: ['--epic <E>', '--repo <owner/repo>'],
+				description: "offer the epic's next children; omit both for the opted-in backlog.",
+			},
+			{
+				names: [OWNER],
+				description: "the parent's process, so the carry count respects the ownership guard.",
+			},
+			{
+				names: [OUTPUT],
+				description: 'the transcript the outage split reads; absent, it is off.',
+			},
+		],
+	},
+	'run:review': {
+		examples: [
+			{
+				arguments: '',
+				note: 'detach the gate, print the brief; then launch the /code-review subagent',
+			},
+			{ arguments: '--join', note: 'after the review returns: join the gate, check its verdict' },
+		],
+	},
+	'run:tail': {
+		examples: [
+			{ arguments: '<N>', note: 'the closed issue' },
+			{ arguments: '<N> <follow-up-N>', note: 'and a follow-up filed this run' },
+		],
+	},
+	ship: {
+		examples: [
+			{ arguments: '"<title> #<N>" --body-file <evidence.md>' },
+			{ arguments: '"<title> #<N>" --review', note: 'both review rounds inside the ship' },
+			{ arguments: '--detach "<title> #<N>"', note: 'hand the ship to a supervisor' },
+			{ arguments: '--log <N>', note: "a detached ship's log" },
+		],
+		flags: [
+			{
+				names: ['--body-file <path>'],
+				description:
+					'the PR body carrying the live-execution evidence `followup` gates on; forwarded to `git -y` alone.',
+			},
+			{ names: ['--notify-message <text>'], description: 'forwarded to `followup` alone.' },
+			{
+				names: ['--review'],
+				description:
+					'runs review round 1 beside the gate, and round 2 after the commit when `review:round2` requires it; a High or an unfixed Medium stops the ship.',
+			},
+			{
+				names: ['--detach'],
+				description:
+					'hands the ship to a supervisor (implied in a lane child); a stop emits `ship-stop` (`--log <N>`). The preflight, type check, unused exports, cspell and guard tests run before the hand-off; a stop returns to the same session.',
+			},
+		],
+	},
+	'run:report': {
+		examples: [{ arguments: '', note: 'print the report; the same text josh notify sends' }],
+	},
+	'run:event': {
+		examples: [
+			{ arguments: '--append <kind> <text>', note: 'append one event; prints its position' },
+			{ arguments: '--from <position>', note: 'every event after <position>, in order (JSON)' },
+			{ arguments: '--follow <position>', note: 'new events, waiting for one; position on stderr' },
+			{ arguments: '--watch [<position>]', note: 'every new event, rendered, until interrupted' },
+			{ arguments: '--last', note: 'the newest event alone' },
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { RUN_USAGE }