@joshuafolkken/kit 1.1455.0 → 1.1514.0

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 }

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

@@ -0,0 +1,238 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands-run.md` documents from `run:progress` on — the run's
+// watchers, the lanes, and the session-budget and document-reading commands — 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 run lifecycle before it is `josh-usage-run.ts`.
+const BARE = { arguments: '' }
+const PATH_DIR = '--path <dir>'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const SESSION_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'run:progress': {
+		examples: [
+			{ arguments: '--output <path>' },
+			{ arguments: '--once', note: 'five labelled lines now, whatever the clock says' },
+			{ arguments: '--interval 20 --repo joshuafolkken/app-kit --hours 4' },
+		],
+		flags: [
+			{
+				names: ['--mark'],
+				description:
+					'record that a real report happened without printing a line (keeps the last line for `run:wake --list`).',
+			},
+			{
+				names: ['--path'],
+				description:
+					'print the ambient heartbeat log\'s path and exit. Every heartbeat line is mirrored there, so `tail -F "$(pnpm josh run:progress --path)"` follows the run across a `backlogrun` session cut. Reads no run state, so it answers in a lane child too.',
+			},
+			{
+				names: ['--interval <min>'],
+				description:
+					'silence interval (default 20; also `JOSH_PROGRESS_INTERVAL_MINUTES`, then `josh.progress_interval_minutes`).',
+			},
+			{
+				names: ['--wait'],
+				description:
+					'start once in the background: each report goes to the event stream and ambient log, never stdout; exits only on an arrival, `josh followup` ending the run, or `--hours`.',
+			},
+			{
+				names: ['--hours <n>'],
+				description: 'how long the watcher lives (default 8 with `--wait`, 1 otherwise).',
+			},
+			{ names: ['--repo <owner/name>'], description: 'scopes the read.' },
+		],
+	},
+	'run:board': {
+		examples: [
+			{ arguments: '', note: 'redraw until interrupted' },
+			{ arguments: '--once', note: 'one frame, then exit' },
+			{ arguments: '--chat', note: 'one frame for a chat, recorded as a progress report' },
+			{
+				arguments: '--every 5',
+				note: 'the --chat frame as a 📊 Progress Telegram every 5 minutes, until the run ends',
+			},
+		],
+		flags: [
+			{
+				names: ['--chat'],
+				description:
+					'answers a `backlogrun` progress question: the frame `--once` draws, with only `🧠` on the machine line and no escapes; it records the report as `run:progress --mark` does.',
+			},
+			{
+				names: ['--every <minutes>'],
+				description:
+					'sends the `--chat` frame as a `📊 Progress` Telegram now and every `<minutes>` until the run ends — only when a person asks for it.',
+			},
+		],
+	},
+	'run:watcher:guard': { examples: [BARE] },
+	'run:stranded': { examples: [BARE] },
+	'lane:open': { examples: [{ arguments: '1490', note: 'prints the lane directory on stdout' }] },
+	'lane:close': {
+		examples: [{ arguments: '1490' }, { arguments: '--all' }],
+		flags: [{ names: ['--all'], description: 'closes every lane.' }],
+	},
+	'lane:list': { examples: [BARE] },
+	'lane:prune': { examples: [BARE] },
+	'lane:output': {
+		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': {
+		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': {
+		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': {
+		examples: [
+			{ arguments: '1749', note: 'every lane after the first' },
+			{
+				arguments: '1749 --stash "backlogrun: josh latest before lanes"',
+				note: 'the first lane only',
+			},
+		],
+	},
+	'lane:sample': { examples: [{ arguments: '', note: 'one machine-load reading' }] },
+	'lane:stats': {
+		examples: [{ arguments: '--period 7', note: "a 7-day period's stage medians and maxima" }],
+	},
+	cost: {
+		examples: [
+			{
+				arguments: '--cut',
+				note: 'compare billed input per request with the shared 135,000 context-cut threshold',
+			},
+			{ arguments: '--over <tokens>', note: 'compare with an explicit limit' },
+			{ arguments: `--cut ${PATH_DIR}`, note: 'Anthropic project or current OpenAI worktree' },
+		],
+		flags: [
+			{
+				names: [PATH_DIR],
+				description:
+					'selects another Anthropic project; OpenAI accepts only linked checkouts of the current project.',
+			},
+		],
+	},
+	'doc:section': {
+		examples: [
+			{ arguments: '<file.md> "<heading>"' },
+			{ arguments: 'backlogrun.md "The hand-off"' },
+		],
+	},
+	'read:set': {
+		examples: [
+			{ arguments: '', note: 'every entry point' },
+			{ arguments: 'backlogrun', note: 'one of them' },
+			{ arguments: 'backlogrun --json' },
+		],
+	},
+	'doc:read': {
+		examples: [
+			{ arguments: 'CLAUDE.md', note: 'under the cap: prints the document' },
+			{ arguments: 'backlogrun.md', note: 'over the cap: prints a directive, no content' },
+		],
+	},
+	'read:files': {
+		examples: [
+			{ arguments: 'a.ts b.ts c.ts', note: 'under the cap: prints each file under its own header' },
+			{
+				arguments: 'a.ts big.ts',
+				note: 'over the cap: prints a directive to Read them in one turn, no content',
+			},
+		],
+	},
+	'edit:files': {
+		examples: [
+			{
+				arguments: 'plan.txt',
+				note: 'applies every block in the plan, one line per edit reporting the outcome',
+			},
+			{ arguments: "- <<'EDITS'", note: 'plan from stdin, then EDITS' },
+		],
+	},
+	time: {
+		examples: [
+			{ arguments: '', note: 'the last run tree, wall clock and cost by role' },
+			{ arguments: '--run', note: 'the same run-tree scope, named explicitly' },
+			{ arguments: '--json', note: 'the same figures, machine-readable' },
+			{ arguments: PATH_DIR, note: "read another project's transcripts from this checkout" },
+		],
+		flags: [
+			{
+				names: ['--run'],
+				description:
+					'(default) the whole run tree, wall clock led beside dollars. It is the only scope; any other flag is a usage error (exit 1). History: `docs/maintainers/josh-commands-run-rationale.md` → "`josh cost` and `josh time` lost their report scopes".',
+			},
+			{
+				names: [PATH_DIR],
+				description:
+					'aim the read at another project (absolute path); keeps the `cwd` behavior when absent.',
+			},
+			{ names: ['--json'], description: 'the run tree, machine-readable.' },
+		],
+	},
+	'cost:audit': {
+		examples: [
+			{ arguments: '', note: 'the last 7 days against the 7 before' },
+			{ arguments: '--period 30', note: 'the last 30 days against the 30 before' },
+		],
+		flags: [
+			{
+				names: ['--period <days>'],
+				description: 'the length of each period, a positive whole number of days (default 7).',
+			},
+		],
+	},
+	retrospective: {
+		examples: [{ arguments: '', note: 'the digest for the run this checkout carries' }],
+	},
+	eval: {
+		examples: [
+			{ arguments: '', note: 'every scenario' },
+			{ arguments: 'consult-not-execute', note: 'one scenario by name' },
+		],
+		flags: [
+			{ names: ['JOSH_EVAL_MODEL'], description: 'the model to run against (default `sonnet`).' },
+			{
+				names: ['JOSH_EVAL_CONCURRENCY'],
+				description:
+					'how many sessions run at once (default `5`); a non-positive-integer value is refused.',
+			},
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { SESSION_USAGE }