@joshuafolkken/kit 1.1435.0 → 1.1455.0

package/scripts/issue/issue-auto-ok.ts

@@ -1,34 +1,30 @@
-import { git_branch } from '#scripts/git/git-branch'
-import { git_command } from '#scripts/git/git-command'
-import { run_carry } from '#scripts/run/carry/run-carry'
-import { issue_file } from './issue-file'
-import { AUTO_OK_LABEL, has_label_name, RELEASE_LABEL } from './issue-labels'
-import { issue_state_cli } from './issue-state-cli'
-
-// Whether `josh issue:file` applies `auto-ok` to the Issue it files. So that work found during an
-// unattended run does not wait in the backlog until a person labels it, the filing computes the
-// answer instead of leaving it to the agent's memory: an Issue filed while a
-// `backlogrun` carry record is live, or from a branch whose Issue carries `auto-ok`, is opted in by
-// default. `--no-auto-ok` is the one exception, declared for an Issue that needs a person's judgement
-// (a Tier B toss-up or a Tier C action). A filing to another repository is never opted in: that
-// repository's own `backlogrun` would implement and merge it though nobody opted that repository in.
-// A `release` Issue is never opted in either: a release is Tier C, so only a
-// person applies `auto-ok` to it, whatever the carry record or the branch's Issue says.
-// `--requested` withholds the default the same way: a person asked for this filing (a `new` entry, or
-// a request in conversation), so the run's own opt-in does not speak for them — `auto-ok` comes only
-// from their own `--label auto-ok`. A filing without the declaration — an observation, a
-// retrospective, a routed filing — keeps the default above.
-
-interface AutoOkSignals {
+import {
+	BREAKING_CHANGE_LABEL,
+	DEFERRED_LABEL,
+	EPIC_LABEL,
+	has_label_name,
+	NEEDS_HUMAN_REVIEW_LABEL,
+	RELEASE_LABEL,
+} from './issue-labels'
+import { markdown_section } from './markdown-section'
+
+// Whether `josh issue:file` applies `auto-ok` to the Issue it files, judged against the criteria
+// `docs/how-to/run-backlog.md` records rather than the context the filing happens in, so a filing a
+// person asked for (`kickoff new`) is judged the same as one an agent makes on its own. The answer is
+// a pure reading of the filing — its labels, its body and its target — so `backlogrun`'s judgement
+// of an Issue already open reuses `exclusion_of` rather than a second list (joshuafolkken/kit#3854).
+// The order: `--no-auto-ok`, a filing to another repository (whose own `backlogrun` would implement
+// and merge it though nobody opted that repository in), a label that keeps a person in the loop, and
+// last the body's judgement declaration (`JUDGEMENT_NEEDED` / `JUDGEMENT_NOT_NEEDED`): whether a
+// policy decision, an external account or a human visual check is needed.
+
+interface AutoOkFiling {
+	// `--no-auto-ok`: the filer declared the Issue needs a person's judgement.
 	is_opted_out: boolean
-	// `--requested`: a person asked for the filing, so neither the carry record nor the branch speaks.
-	is_requested: boolean
-	// The filing carries the `release` label.
-	is_release: boolean
-	is_carried: boolean
-	// The labels of the Issue the current branch names; `undefined` when the branch names none or the
-	// Issue could not be read.
-	branch_labels: ReadonlyArray<string> | undefined
+	is_cross_repository: boolean
+	// Every label the filing carries, including the ones the body's declarations add.
+	labels: ReadonlyArray<string>
+	body: string
 }
 
 interface AutoOkDecision {
@@ -36,98 +32,71 @@ interface AutoOkDecision {
 	reason: string
 }
 
+const BACKGROUND_HEADING = '## 背景'
+const JUDGEMENT_NOT_NEEDED = '- 人の判断: 不要'
+const JUDGEMENT_NEEDED = '- 人の判断: 要'
+const DECLARATION_PROBLEM = `declare under \`${BACKGROUND_HEADING}\` whether a person's judgement (a policy decision, an external account, a human visual check) is needed: \`${JUDGEMENT_NOT_NEEDED}\` or \`${JUDGEMENT_NEEDED}（<which one>）\` — exactly one (\`issue-template.md\`)`
+
 const OPTED_OUT: AutoOkDecision = { is_applied: false, reason: '--no-auto-ok declared' }
 const CROSS_REPOSITORY: AutoOkDecision = {
 	is_applied: false,
 	reason: 'the Issue is filed to another repository',
 }
-const RELEASE: AutoOkDecision = {
-	is_applied: false,
-	reason: `a ${RELEASE_LABEL} Issue is opted in by a person only`,
-}
-const REQUESTED: AutoOkDecision = {
+const JUDGEMENT: AutoOkDecision = {
 	is_applied: false,
-	reason: 'a person asked for this filing; auto-ok only when they declare it',
+	reason: `the body declares \`${JUDGEMENT_NEEDED}\``,
 }
-const CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
-const BRANCH_OPTED_IN: AutoOkDecision = {
+const APPLIED: AutoOkDecision = {
 	is_applied: true,
-	reason: 'the Issue this branch works on carries auto-ok',
-}
-const NOT_OPTED_IN: AutoOkDecision = {
-	is_applied: false,
-	reason: 'no backlogrun carry record is live and the branch names no auto-ok Issue',
-}
-
-// What the filing itself declares: `--no-auto-ok` and `--requested`.
-type AutoOkDeclared = Pick<AutoOkSignals, 'is_opted_out' | 'is_requested'>
-type Withholding = AutoOkDeclared & Pick<AutoOkSignals, 'is_release'>
-
-// The three signals that withhold `auto-ok` before any other is read, or `undefined` when none holds.
-function withheld(signals: Withholding): AutoOkDecision | undefined {
-	if (signals.is_opted_out) return OPTED_OUT
-	if (signals.is_release) return RELEASE
-	if (signals.is_requested) return REQUESTED
-
-	return undefined
+	reason: 'no exclusion holds and the body declares no judgement is needed',
 }
 
-// The opt-out, the `release` label and `--requested` win over every signal, then the carry record,
-// then the branch's Issue.
-function decide(signals: AutoOkSignals): AutoOkDecision {
-	const decision = withheld(signals)
+// The labels that keep a person in the loop, each with the reason it withholds `auto-ok`. A
+// `breaking-change` declared in the body arrives here as its label, added before the decision.
+const EXCLUDED_LABELS: ReadonlyArray<readonly [string, string]> = [
+	[RELEASE_LABEL, 'a release is Tier C'],
+	[BREAKING_CHANGE_LABEL, 'a breaking change needs a person to accept the migration'],
+	[DEFERRED_LABEL, 'the Issue is deferred'],
+	[NEEDS_HUMAN_REVIEW_LABEL, 'a person reviews the change before it lands'],
+	[EPIC_LABEL, 'an epic is opted in by a person, and that opts in every descendant'],
+]
 
-	if (decision !== undefined) return decision
-	if (signals.is_carried) return CARRIED
-	if (has_label_name(signals.branch_labels ?? [], AUTO_OK_LABEL)) return BRANCH_OPTED_IN
+// The first label that withholds `auto-ok`, or `undefined` when none of them is present.
+function exclusion_of(labels: ReadonlyArray<string>): AutoOkDecision | undefined {
+	const found = EXCLUDED_LABELS.find(([label]) => has_label_name(labels, label))
 
-	return NOT_OPTED_IN
-}
+	if (found === undefined) return undefined
 
-function line_of(decision: AutoOkDecision): string {
-	return `auto-ok: ${decision.is_applied ? 'applied' : 'not applied'} — ${decision.reason}`
+	return { is_applied: false, reason: `a \`${found[0]}\` Issue — ${found[1]}` }
 }
 
-// Read from the common git directory, so a lane sees the record its batch wrote in the main tree.
-async function is_carried(): Promise<boolean> {
-	const directory = await run_carry.repository_directory()
+// `true` / `false` for a declared need, `undefined` when the background declares neither or both.
+function judgement_of(body: string): boolean | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const lines = markdown_section.unfenced_lines(background).map((line) => line.trim())
+	const is_not_needed = lines.some((line) => line.startsWith(JUDGEMENT_NOT_NEEDED))
+	const is_needed = lines.some((line) => line.startsWith(JUDGEMENT_NEEDED))
 
-	if (directory === undefined) return false
-
-	return run_carry.read_carry(run_carry.carry_path(directory)).kind === 'carried'
+	return is_not_needed === is_needed ? undefined : is_needed
 }
 
-// An unreadable Issue is read as no labels: the filing goes on without `auto-ok` rather than failing.
-// The branch names an Issue of `current`, read there by name: a filing to another repository has
-// already pointed `GH_REPO` at its target, which would otherwise answer with the target's Issue.
-async function branch_labels(current: string): Promise<ReadonlyArray<string> | undefined> {
-	const issue_number = git_branch.issue_from_branch(await git_command.branch())
+// Why the filing is refused for its declaration, or `undefined` when it declares exactly one answer.
+function declaration_problem(body: string): string | undefined {
+	return judgement_of(body) === undefined ? DECLARATION_PROBLEM : undefined
+}
 
-	if (issue_number === undefined) return undefined
-	const read = await issue_state_cli.read_issue(String(issue_number), current)
+function decide(filing: AutoOkFiling): AutoOkDecision {
+	if (filing.is_opted_out) return OPTED_OUT
+	if (filing.is_cross_repository) return CROSS_REPOSITORY
 
-	return read.kind === 'state' ? read.state.labels : undefined
+	return exclusion_of(filing.labels) ?? (judgement_of(filing.body) === false ? APPLIED : JUDGEMENT)
 }
 
-// Each read is skipped once an earlier signal has already decided the answer; a cross-repository
-// filing is refused before any signal is read. `labels` are the ones the filing declares.
-async function resolve(
-	declared: AutoOkDeclared,
-	target: string,
-	current: string,
-	labels: ReadonlyArray<string> = [],
-): Promise<AutoOkDecision> {
-	const withholding = { ...declared, is_release: has_label_name(labels, RELEASE_LABEL) }
-	const decision = withheld(withholding)
-
-	if (decision !== undefined) return decision
-	if (!issue_file.is_same_repository(target, current)) return CROSS_REPOSITORY
-	if (await is_carried()) return CARRIED
-
-	return decide({ ...withholding, is_carried: false, branch_labels: await branch_labels(current) })
+function line_of(decision: AutoOkDecision): string {
+	return `auto-ok: ${decision.is_applied ? 'applied' : 'not applied'} — ${decision.reason}`
 }
 
-const issue_auto_ok = { decide, line_of, resolve }
+const issue_auto_ok = { declaration_problem, decide, exclusion_of, line_of }
 
-export type { AutoOkDeclared, AutoOkDecision, AutoOkSignals }
+export type { AutoOkDecision, AutoOkFiling }
 export { issue_auto_ok }

package/scripts/issue/issue-file-cli.ts

@@ -24,7 +24,7 @@ import { issue_scout_cli } from './issue-scout-cli'
 import { issue_wip } from './issue-wip'
 
 // `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
-// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]` — file an Issue
+// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]` — file an Issue
 // with every filing step run in order: the third-party refusal, the body
 // lint, the `## Origin` check for another repository, the `auto-ok` decision
 // with the run label it owes, the fold question against the run's earlier
@@ -37,7 +37,7 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
-	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]'
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
 const THIRD_PARTY_MESSAGE =
@@ -74,10 +74,13 @@ function is_third_party(target: string): boolean {
 // the filing may go on to the scout.
 function refusals_of(filing: Filing): ReadonlyArray<string> {
 	if (is_third_party(filing.target)) return [THIRD_PARTY_MESSAGE]
-	const problems = issue_lint_cli.problems(filing.body).map((problem) => `✖ ${problem}`)
-	const origin = issue_file.origin_problem(filing.body, filing.target, filing.current)
+	const problems = [
+		...issue_lint_cli.problems(filing.body),
+		issue_auto_ok.declaration_problem(filing.body),
+		issue_file.origin_problem(filing.body, filing.target, filing.current),
+	]
 
-	return origin === undefined ? problems : [...problems, `✖ ${origin}`]
+	return problems.filter((problem) => problem !== undefined).map((problem) => `✖ ${problem}`)
 }
 
 function unacknowledged_message(numbers: ReadonlyArray<number>): string {
@@ -143,18 +146,15 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 }
 
 // Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label.
-// Decided before the WIP count and the scout, so a refusal costs no listing.
-async function labels_of(filing: Filing): Promise<ReadonlyArray<string> | undefined> {
-	const declared = {
+// Decided before the WIP count and the scout, so a refusal costs no listing. The decision reads the
+// labels the body's declarations add, so a declared breaking change is excluded like its label.
+function labels_of(filing: Filing): ReadonlyArray<string> | undefined {
+	const auto_ok = issue_auto_ok.decide({
 		is_opted_out: filing.args.is_auto_ok_opted_out,
-		is_requested: filing.args.is_requested,
-	}
-	const auto_ok = await issue_auto_ok.resolve(
-		declared,
-		filing.target,
-		filing.current,
-		filing.args.labels,
-	)
+		is_cross_repository: !issue_file.is_same_repository(filing.target, filing.current),
+		labels: issue_file.labels_of(filing.args, filing.body),
+		body: filing.body,
+	})
 
 	console.info(issue_auto_ok.line_of(auto_ok))
 	const labels = issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied)
@@ -271,7 +271,7 @@ async function is_clear(filing: Filing): Promise<boolean> {
 
 async function file(filing: Filing): Promise<number> {
 	if (!is_admitted(filing)) return FAILURE_EXIT_CODE
-	const labels = await labels_of(filing)
+	const labels = labels_of(filing)
 
 	if (labels === undefined || !(await is_clear(filing))) return FAILURE_EXIT_CODE
 

package/scripts/issue/issue-file.ts

@@ -41,9 +41,6 @@ interface FileArguments {
 	is_over_cap: boolean
 	// `--no-auto-ok`: the Issue needs a person's judgement, so `auto-ok` is not applied (`issue-auto-ok.ts`).
 	is_auto_ok_opted_out: boolean
-	// `--requested`: a person asked for this filing, so `auto-ok` is applied only when a `--label` names
-	// it (`issue-auto-ok.ts`).
-	is_requested: boolean
 	// `--release`: the change reaches a consumer only once published, so the Issue is linked to the
 	// repository's release Issue as a blocker (`issue-release-cli.ts`).
 	is_release: boolean
@@ -58,7 +55,6 @@ const OPTIONS = {
 	distinct: { type: 'string', multiple: true },
 	'over-cap': { type: 'boolean' },
 	'no-auto-ok': { type: 'boolean' },
-	requested: { type: 'boolean' },
 	release: { type: 'boolean' },
 } as const
 
@@ -129,7 +125,6 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		repo: values.repo,
 		is_over_cap: values['over-cap'] === true,
 		is_auto_ok_opted_out: values['no-auto-ok'] === true,
-		is_requested: values.requested === true,
 		is_release: values.release === true,
 	}
 }
@@ -151,7 +146,7 @@ function is_undeclared_classification(label: string, body: string): boolean {
 
 // Every label the filing carries: the depth, the route when there is one, the classification labels
 // the body declares (`issue_classification.labels_for`, which merges case-insensitively), then any
-// extra `--label`, then `auto-ok` when the filing opted in (`issue-auto-ok.ts`) and no `--label`
+// extra `--label`, then `auto-ok` when the filing is judged in (`issue-auto-ok.ts`) and no `--label`
 // already named it. One request applies them all, so no label is a separate step to forget.
 function labels_of(args: FileArguments, body: string, is_auto_ok = false): ReadonlyArray<string> {
 	const extra = args.labels.filter((label) => !is_undeclared_classification(label, body))

package/scripts/issue/issue-labels.ts

@@ -67,9 +67,12 @@ const ALREADY_DONE_LABEL = 'already-done'
 // Marks the Issue that tracks a repository's next release. An Issue whose
 // change reaches a consumer only once published is linked to it as a `blocked_by` blocker
 // (`josh issue:release`), so "merged but not yet released" is visible in the backlog. A run applies
-// it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` refuses the default for it on every path,
-// since a release is Tier C — and only a person opts it into unattended execution.
+// it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` excludes it, since a release is Tier C —
+// and only a person opts it into unattended execution.
 const RELEASE_LABEL = 'release'
+// A person's mark for work set aside for now; `issue-auto-ok.ts` reads it as an exclusion. Applied by
+// hand and never provisioned, so it is not in `REPOSITORY_LABELS`.
+const DEFERRED_LABEL = 'deferred'
 // Applied to an Issue whose second review round was skipped, so the condition stays auditable
 // (`prompts/review.md` → "When round 2 is skipped entirely, and when it is not").
 const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
@@ -402,6 +405,7 @@ export {
 	BUG_LABEL,
 	BUGFIX_LABEL,
 	BREAKING_CHANGE_LABEL,
+	DEFERRED_LABEL,
 	depth_label_of,
 	DEPTH_0_LABEL,
 	DEPTH_1_LABEL,

package/scripts/issue/issue-release-cli.ts

@@ -18,16 +18,21 @@ import { session_cite } from './session-cite'
 // --release` calls the same `link` once its Issue exists, so a new and an existing Issue are linked
 // by one body of code.
 //
+// `--wait` points the edge the other way: `<N>` is blocked by the release Issue, so a run that needs
+// the published version records a dependency rather than a `needs-decision` park, and the backlog
+// offers `<N>` again once a person closes the release Issue (joshuafolkken/kit#3824).
+//
 // The relation is written through `issue_add_blocked_by`, which addresses the repository `gh`
 // resolves — the current one, or the target a cross-repository `issue:file` has pointed `GH_REPO` at.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh issue:release <issue-number>'
+const USAGE = 'Usage: josh issue:release <issue-number> [--wait]'
 const NONE = 'none'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote` — check `gh auth status`.'
+const OPTIONS = { wait: { type: 'boolean' } } as const
 
 interface ReleaseIssue {
 	issue_number: number
@@ -35,7 +40,20 @@ interface ReleaseIssue {
 	is_filed: boolean
 }
 
+interface ReleaseRequest {
+	issue_number: number
+	// `<N>` waits on the release Issue, rather than blocking it.
+	is_wait: boolean
+}
+
+// The two ends of one `blocked_by` edge.
+interface Edge {
+	blocked: number
+	blocker: number
+}
+
 // `undefined` when the listing is unreadable, `NONE` when it reads and names no open release Issue.
+// `pnpm josh release` asks the same question to close the Issue it has just published.
 async function find_open(target: string): Promise<number | typeof NONE | undefined> {
 	const outcome = await git_gh_issue_list.issue_list({
 		json_fields: 'number',
@@ -91,41 +109,59 @@ async function release_of(target: string): Promise<ReleaseIssue | undefined> {
 	return filed === undefined ? undefined : { issue_number: filed, is_filed: true }
 }
 
-function linked_line(release: ReleaseIssue, issue_number: number, target: string): string {
+function release_label_of(release: ReleaseIssue, target: string): string {
 	const how = release.is_filed ? 'filed' : 'open'
-	const release_cite = session_cite.issue(release.issue_number, undefined, target)
 
-	return `release: ${release_cite} (${how}) is blocked by ${session_cite.issue(issue_number, undefined, target)}`
+	return `${session_cite.issue(release.issue_number, undefined, target)} (${how})`
 }
 
-function unlinked_line(issue_number: number, blocked: string, target: string): string {
-	const blocker = session_cite.issue(issue_number, undefined, target)
+function linked_line(release: ReleaseIssue, request: ReleaseRequest, target: string): string {
+	const release_label = release_label_of(release, target)
+	const issue_label = session_cite.issue(request.issue_number, undefined, target)
 
-	return `✖ ${blocker} could not be recorded as a blocker of ${session_cite.issue(blocked, undefined, target)}`
+	return request.is_wait
+		? `release: ${issue_label} waits on ${release_label}`
+		: `release: ${release_label} is blocked by ${issue_label}`
 }
 
-// Whether Issue `issue_number` of `target` now blocks the release Issue. Every outcome is printed.
-async function link(issue_number: number, target: string): Promise<boolean> {
+function unlinked_line(edge: Edge, target: string): string {
+	const blocker = session_cite.issue(edge.blocker, undefined, target)
+
+	return `✖ ${blocker} could not be recorded as a blocker of ${session_cite.issue(edge.blocked, undefined, target)}`
+}
+
+function edge_of(release: ReleaseIssue, request: ReleaseRequest): Edge {
+	return request.is_wait
+		? { blocked: request.issue_number, blocker: release.issue_number }
+		: { blocked: release.issue_number, blocker: request.issue_number }
+}
+
+// Whether the edge between Issue `<N>` of `target` and the release Issue is now recorded. Every
+// outcome is printed.
+async function record(request: ReleaseRequest, target: string): Promise<boolean> {
 	const release = await release_of(target)
 
 	if (release === undefined) return false
-	const blocked = String(release.issue_number)
-	const is_linked = await git_gh_issue_write.issue_add_blocked_by(blocked, String(issue_number))
+	const edge = edge_of(release, request)
+	const is_linked = await git_gh_issue_write.issue_add_blocked_by(
+		String(edge.blocked),
+		String(edge.blocker),
+	)
 
-	if (is_linked) console.info(linked_line(release, issue_number, target))
-	else console.error(unlinked_line(issue_number, blocked, target))
+	if (is_linked) console.info(linked_line(release, request, target))
+	else console.error(unlinked_line(edge, target))
 
 	return is_linked
 }
 
-// An unknown flag parses to no positionals, so it refuses the call like a missing number.
-function positionals_of(argv: ReadonlyArray<string>): ReadonlyArray<string> {
-	return cli_flags.arguments_of(argv, {})?.positionals ?? []
+// Whether Issue `issue_number` of `target` now blocks the release Issue.
+async function link(issue_number: number, target: string): Promise<boolean> {
+	return await record({ issue_number, is_wait: false }, target)
 }
 
 // The number is the one positional: a missing, malformed or second one refuses the whole call.
-function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
-	const [issue_number, ...rest] = positionals_of(argv)
+function issue_number_of(positionals: ReadonlyArray<string>): number | undefined {
+	const [issue_number, ...rest] = positionals
 	const is_single = rest.length === 0 && issue_number !== undefined
 
 	return is_single && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
@@ -133,10 +169,20 @@ function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
 		: undefined
 }
 
+// An unknown flag parses to no request at all, so it refuses the call like a missing number.
+function request_of(argv: ReadonlyArray<string>): ReleaseRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	const issue_number = issue_number_of(parsed?.positionals ?? [])
+
+	if (parsed === undefined || issue_number === undefined) return undefined
+
+	return { issue_number, is_wait: parsed.values.wait === true }
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const issue_number = issue_number_of(argv)
+	const request = request_of(argv)
 
-	if (issue_number === undefined) {
+	if (request === undefined) {
 		console.error(USAGE)
 
 		return FAILURE_EXIT_CODE
@@ -150,7 +196,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return (await link(issue_number, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	return (await record(request, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
 // `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
@@ -158,8 +204,8 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_release_cli = { link, run }
+const issue_release_cli = { find_open, link, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
-export { issue_release_cli }
+export { issue_release_cli, NONE }

package/scripts/issue/issue-release.ts

@@ -42,7 +42,9 @@ function body_of(repo: string): string {
 		'',
 		'Every Issue this one is blocked by changes something a consumer can use only once it is published. Once they have merged, a person runs `pnpm josh release` in the primary checkout.',
 		'',
-		'Close this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'`pnpm josh release` closes this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'',
+		'Every Issue this one blocks needs the published version (`pnpm josh issue:release <N> --wait`); closing this Issue hands each of them back to the backlog.',
 		'',
 		'`auto-ok` is never applied to this Issue by a run; a person may apply it.',
 		'',

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

@@ -61,6 +61,17 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--exclude <n>[,<n>...]] [--label <name>]', 'automation', ['network']],
 	},
+	'auto-ok:judge': {
+		script: 'scripts/auto-ok/auto-ok-judge-cli.ts',
+		description:
+			'List the open issues backlogrun owes an auto-ok judgement, or record one (--apply / --decline)',
+		category: 'AI tools',
+		reference: [
+			'[--apply <n> (--lane | --solo) | --decline <n> --reason <text>]',
+			'automation',
+			['network'],
+		],
+	},
 	...BACKLOG_COMMANDS,
 	cost: {
 		script: 'scripts/cost-runtime/cost-cli.ts',

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

@@ -75,7 +75,7 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 			'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> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]',
+			'<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'],
 		],
@@ -83,9 +83,9 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	'issue:release': {
 		script: 'scripts/issue/issue-release-cli.ts',
 		description:
-			"Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+			"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>', 'automation', ['network']],
+		reference: ['<issue> [--wait]', 'automation', ['network']],
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -17,7 +17,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]`,
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]`,
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],
@@ -52,7 +52,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Initialize config in a new project',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--no-install]`,
+			`${PROFILE_ARGUMENTS} [--no-install] [--dry-run]`,
 			'developer',
 			['files', 'network', 'processes'],
 		],

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

@@ -47,7 +47,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: [
-			'[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]',
+			'[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>] [--recommended <text>] [--alternative <text>]...',
 			'automation',
 			['notifications'],
 		],