@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/issue/issue-fold.ts

@@ -1,6 +1,6 @@
 import { split_assess, type SplitVerdict } from '#scripts/split/split-assess'
 
-// The filing-time counterpart to the split assessment (joshuafolkken/kit#2213).
+// The filing-time counterpart to the split assessment.
 //
 // `split-assessment.md` → "The question" decides whether *one request* is really several
 // deliverables; this decides whether *several findings filed from one session* fold into one Issue or
@@ -11,32 +11,47 @@ import { split_assess, type SplitVerdict } from '#scripts/split/split-assess'
 //
 // **The default is `fold`.** Separability alone never separates — it is necessary, not sufficient —
 // and a size that does not clear the split guide folds however separable the findings are. That is
-// why an unmeasurable size is treated by the caller as under the guide: tipping the doubt toward
-// `separate` would reproduce the every-finding-its-own-Issue behavior this exists to end.
+// why an unmeasurable size never tips to `separate`: that would reproduce the every-finding-its-own-Issue
+// behavior this exists to end.
+//
+// **Nor does an unmeasurable size fold**. The size half is read off the working
+// tree's diff, and a filing made before any implementation — `kickoff new`, a split's children — has
+// no diff that says anything about the findings' size. Reading that as `single` folded every such
+// filing; it answers `undetermined` instead, which leaves the size to the whole request's estimate
+// (`split-assessment.md` → "The question").
 
-type FoldVerdict = 'fold' | 'separate' | 'no-fold-needed'
+type FoldVerdict = 'fold' | 'separate' | 'no-fold-needed' | 'undetermined'
 
 const FOLD: FoldVerdict = 'fold'
 const SEPARATE: FoldVerdict = 'separate'
 const NO_FOLD_NEEDED: FoldVerdict = 'no-fold-needed'
+const UNDETERMINED: FoldVerdict = 'undetermined'
 
 // One finding is nothing to fold: the question only arises once a session holds two or more.
 const MIN_CANDIDATES = 2
 
+// Separable findings: the size alone decides, and a size nobody measured decides nothing.
+function separable_verdict(size_verdict: SplitVerdict | undefined): FoldVerdict {
+	if (size_verdict === undefined) return UNDETERMINED
+
+	return size_verdict === split_assess.SPLIT_VERDICT ? SEPARATE : FOLD
+}
+
 // The same two questions as the split assessment, in the same conjunction: `separate` only when the
 // findings are separable **and** their combined size clears the split guide. Either half alone folds,
-// and fewer than two candidates is not a fold question at all.
+// and fewer than two candidates is not a fold question at all. An `undefined` size is one the diff
+// could not measure, which decides nothing.
 function fold_verdict(
 	candidate_count: number,
 	is_separable: boolean,
-	size_verdict: SplitVerdict,
+	size_verdict: SplitVerdict | undefined,
 ): FoldVerdict {
 	if (candidate_count < MIN_CANDIDATES) return NO_FOLD_NEEDED
 
-	return is_separable && size_verdict === split_assess.SPLIT_VERDICT ? SEPARATE : FOLD
+	return is_separable ? separable_verdict(size_verdict) : FOLD
 }
 
-const issue_fold = { FOLD, SEPARATE, NO_FOLD_NEEDED, MIN_CANDIDATES, fold_verdict }
+const issue_fold = { FOLD, SEPARATE, NO_FOLD_NEEDED, UNDETERMINED, MIN_CANDIDATES, fold_verdict }
 
 export type { FoldVerdict }
 export { issue_fold }

package/scripts/issue/issue-labels.ts

@@ -7,41 +7,41 @@ const ENHANCEMENT_LABEL = 'enhancement'
 const BREAKING_CHANGE_LABEL = 'breaking-change'
 const IN_PROGRESS_LABEL = 'in-progress'
 // Applied by `kickoff` once its plan is on the issue, so the next command's `run:entry` reads the issue
-// as planned and starts at the implementation rather than planning again (joshuafolkken/kit#3042).
+// as planned and starts at the implementation rather than planning again.
 // Namespaced like `run:solo`: a bare `planned` is a common roadmap label a person may already apply,
 // and reading one as kickoff's mark would skip the planning that never happened.
 const PLANNED_LABEL = 'run:planned'
 // Parks a child that cannot advance without a person deciding something. `epic:next` is what reads
 // it: a parked child is why a run reports "nothing left that time will fix" rather than waiting
-// forever (joshuafolkken/kit#860).
+// forever.
 const NEEDS_DECISION_LABEL = 'needs-decision'
-// Marks an issue whose defect reaches the verification path, so it runs with nothing beside it
-// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `backlogrun-lanes.md`;
+// Marks an issue whose defect reaches the verification path, so it runs with nothing beside it.
+// A run applies it from the verification-path enumeration in `backlogrun-lanes.md`;
 // `backlog:next` enforces it (`backlog-solo.ts`), so the rule no longer rests on a judgement at
 // dispatch time.
 const RUN_SOLO_LABEL = 'run:solo'
-// The other half of the same judgement: an issue a run read and found safe to run beside others
-// (joshuafolkken/kit#2779). Without it an issue lacking `run:solo` could mean "judged parallel" or
+// The other half of the same judgement: an issue a run read and found safe to run beside others.
+// Without it an issue lacking `run:solo` could mean "judged parallel" or
 // "never judged", and `backlog:next` withholds the second (`epic-triage.ts`).
 const RUN_LANE_LABEL = 'run:lane'
-// Puts an issue at the head of the backlog's ranking (joshuafolkken/kit#2928). A person or a run may
+// Puts an issue at the head of the backlog's ranking. A person or a run may
 // apply it — a run only where it can cite a deadline or a stated urgency, or a policy a person wrote
 // (`backlogrun-steps.md`) — and **only a person removes it**: a run that could clear it could undo
 // the person's ordering. Read by `issue-rank.ts`, the one place the ranking keys are decided.
 const PRIORITY_HIGH_LABEL = 'priority:high'
-// Opts one issue outside any epic into unattended execution (joshuafolkken/kit#906). **Only a
+// Opts one issue outside any epic into unattended execution. **Only a
 // person applies it.** `epicrun #<E>` approves the merges inside `#<E>`; this label is the only way
 // a person extends that approval past the epic's edge, so a label an AI could apply to itself would
 // let an unattended run widen its own authorization — which is not a guard at all.
 const AUTO_OK_LABEL = 'auto-ok'
 // Degrades one issue's run to a `halfrun`-shaped stop: it is implemented and taken through the
-// verification gate, and then nothing is committed, pushed, opened as a pull request or merged
-// (joshuafolkken/kit#1125). **Only a person applies it** — a mark a run could clear for itself is not
+// verification gate, and then nothing is committed, pushed, opened as a pull request or merged.
+// **Only a person applies it** — a mark a run could clear for itself is not
 // a mark.
 //
 // It is the opposite of `auto-ok` in what it does: one widens unattended execution past an epic's
 // edge, the other withholds the last step of it. Unlike `auto-ok`, which `issue:file` applies by
-// default to work found by opted-in work (joshuafolkken/kit#3213), no run ever applies it. `auto-ok`
+// default to work found by opted-in work, no run ever applies it. `auto-ok`
 // answers "may this run at all", this one answers "may its result ship without a person looking".
 //
 // **Not `needs-decision`, and the difference is what the two sets below encode.** A parked issue is
@@ -51,10 +51,9 @@ const AUTO_OK_LABEL = 'auto-ok'
 // checkout and must go on holding the repository. Read as parked in either place, the next child
 // would start on top of that work.
 const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
-// Marks an issue whose work a run verified is **already merged** (joshuafolkken/kit#1679). Closing
-// an Issue is Tier C, so a run that reaches that conclusion may not act on it — and before this
-// label there was no exit that was not Tier C: `fullrun #1656` verified the work was already in
-// `main` from joshuafolkken/kit#1623 and closed the Issue itself.
+// Marks an issue whose work a run verified is **already merged**. Closing
+// an Issue is Tier C, so a run that reaches that conclusion may not act on it — this label is its
+// exit that is not Tier C.
 //
 // **It is not `needs-decision`, and the difference is the whole reason it exists.** A parked issue
 // waits for an answer nobody has given; this one has its answer already — the work is done, and all
@@ -65,6 +64,12 @@ const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
 // takes it off, because taking it off asserts the work is *not* done, which is the same claim in
 // reverse and is no more a run's to make.
 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.
+const RELEASE_LABEL = 'release'
 
 // The four labels that mean an open issue must not be handed to a run as it stands: an `epic`
 // tracks a batch and is never run directly (its children are), `in-progress` is already claimed by
@@ -84,20 +89,19 @@ const NOT_DIRECTLY_RUNNABLE_LABELS: ReadonlySet<string> = new Set([
 	ALREADY_DONE_LABEL,
 ])
 
-// joshuafolkken/kit#1083: filing-route labels, applied at filing time so the backlog's composition —
-// a review-cap carry-forward vs a split child vs a Tier A in-implementation filing — is countable
-// with `gh api "repos/{owner}/{repo}/issues?labels=<route>"` instead of grepping issue bodies by
-// hand, which is how the 2026-08-30 breakdown was produced and why it did not reproduce. Purely
+// Filing-route labels, applied at filing time so the backlog's composition — a review-cap
+// carry-forward vs a split child vs a Tier A in-implementation filing — is countable with
+// `gh api "repos/{owner}/{repo}/issues?labels=<route>"` instead of grepping issue bodies by hand,
+// which does not reproduce. Purely
 // informational: unlike the three above, a route label says nothing about whether an issue may run,
 // so none of them joins NOT_DIRECTLY_RUNNABLE_LABELS. The names are duplicated as literals in the
 // filing procedures (prose cannot import this module); `scripts/rules/filing-route-label.test.ts` keys the
 // docs to these constants so a filing command that drops the label fails rather than drifting.
 //
-// joshuafolkken/kit#1518 added a fourth: an interrupt is a defect found in *this* repository that
-// does not block the run that found it, and which the WIP cap would otherwise push into the
-// discretionary exit — the route joshuafolkken/kit#1517 took, surviving only as a comment on another
-// issue. It is not `route:tier-a`: that one is a filing the run is blocked by (an upstream defect or
-// a prerequisite), and reading the two as one is what lost #1517.
+// `route:interrupt` is a defect found in *this* repository that does not block the run that found
+// it, and which the WIP cap would otherwise push into the discretionary exit, surviving only as a
+// comment on another issue. It is not `route:tier-a`: that one is a filing the run is blocked by (an
+// upstream defect or a prerequisite), and reading the two as one loses the interrupt.
 const INTERRUPT_ROUTE_LABEL = 'route:interrupt'
 const REVIEW_CAP_ROUTE_LABEL = 'route:review-cap'
 const SPLIT_ROUTE_LABEL = 'route:split'
@@ -139,7 +143,7 @@ const FILING_ROUTE_LABELS: ReadonlyArray<{
 	},
 ]
 
-// joshuafolkken/kit#1729: the depth of an issue's subject, recorded as a label at filing time.
+// The depth of an issue's subject, recorded as a label at filing time.
 //
 // **The definition is not here.** `.claude/skills/workflow-commands/observation-filing.md` → "The depth test",
 // is the single source: depth 0 is what a consumer of this package touches, depth 1 the run
@@ -148,10 +152,9 @@ const FILING_ROUTE_LABELS: ReadonlyArray<{
 // would be the clone `CLAUDE.md` prohibits, and the descriptions below therefore name the section
 // rather than paraphrase it.
 //
-// **Why a label at all.** joshuafolkken/kit#1698 set a measurable target — the share of open issues
-// at depth 0 — and left nothing that records a depth, so the share could only be obtained by reading
-// every open issue's body by hand. Two hand counts a day apart disagreed on the denominator and were
-// therefore not comparable, which is the failure a recorded label removes.
+// **Why a label at all.** The share of open issues at depth 0 is a measured target, and without a
+// recorded depth it could only be obtained by reading every open issue's body by hand — hand counts
+// disagree on the denominator and are not comparable, which is the failure a recorded label removes.
 //
 // **The depth is read off the subject, so a run applies it.** Unlike `auto-ok` and
 // `needs-human-review` this is not a person's judgement about authorization; it is the same reading
@@ -163,8 +166,7 @@ const DEPTH_2_LABEL = 'depth:2'
 
 // Ordered shallowest first, which is what makes `depth_label_of` deterministic: an issue carrying
 // more than one depth label counts as the **lowest** depth present, the one closest to the consumer.
-// Without a fixed tie-break the same listing measured twice could answer differently, which is the
-// whole defect joshuafolkken/kit#1729 was filed for.
+// Without a fixed tie-break the same listing measured twice could answer differently.
 const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL, DEPTH_2_LABEL]
 
 // The metadata `gh api ... labels` needs, in the shape `FILING_ROUTE_LABELS` above uses and for the
@@ -173,7 +175,7 @@ const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL,
 // Green, amber and pale blue, so the consumer-facing depth is the one that stands out in a listing.
 //
 // **`josh issue:file` provisions them** through `repository_labels.ensure_labels` before its create
-// call (joshuafolkken/kit#3176), so no document carries a creation command to keep in step.
+// call, so no document carries a creation command to keep in step.
 const DEPTH_LABELS: ReadonlyArray<{
 	name: string
 	color: string
@@ -203,7 +205,7 @@ interface LabelDefinition {
 }
 
 // What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
-// applies with its intended color (joshuafolkken/kit#2197). The `epic` and `in-progress` metadata is
+// applies with its intended color. The `epic` and `in-progress` metadata is
 // the one the workflow documents create them with; the labels only a person applies are left out.
 const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 	{
@@ -228,12 +230,17 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: 'e99695',
 		description: 'Offered first in a backlogrun; only a person removes it',
 	},
+	{
+		name: RELEASE_LABEL,
+		color: 'fef2c0',
+		description: 'Tracks the next release; its blockers are the merged work it publishes',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
 
-// The pull request release classifications `pr-classification.yml` requires exactly one of
-// (joshuafolkken/kit#2797). The check is distributed by `josh sync`, so the labels it asks for are
+// The pull request release classifications `pr-classification.yml` requires exactly one of.
+// The check is distributed by `josh sync`, so the labels it asks for are
 // provisioned from this same list — a repository that never had them would otherwise fail the check
 // on every pull request that is not an `enhancement`.
 const BUGFIX_LABEL = 'bugfix'
@@ -289,7 +296,7 @@ function has_any_label(
 // A membership test answers whether the label is there; a *removal* has to name it, and
 // `DELETE …/issues/<N>/labels/<name>` names it in the path. Lowercasing the wanted name and sending
 // that would be a second comparison — GitHub's, on a spelling we did not read — so the removal reads
-// the stored one and sends it back (joshuafolkken/kit#1794).
+// the stored one and sends it back.
 function label_name_of(labels: ReadonlyArray<string>, wanted: string): string | undefined {
 	const target = wanted.toLowerCase()
 
@@ -318,7 +325,7 @@ function depth_label_of(labels: ReadonlyArray<LabelReference> | undefined): stri
 }
 
 // Every workflow label this package manages. The label-reference scan
-// (`scripts/document/label-reference.test.ts`, joshuafolkken/kit#1923) reads this to check that no
+// (`scripts/document/label-reference.test.ts`) reads this to check that no
 // document operates on a label name that does not exist here — a stale or mistyped `labels[]=…`
 // otherwise fails silently at run time. One source, so a label added above joins the scan without a
 // second edit.
@@ -340,6 +347,7 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	NEEDS_HUMAN_REVIEW_LABEL,
 	ALREADY_DONE_LABEL,
 	PRIORITY_HIGH_LABEL,
+	RELEASE_LABEL,
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
@@ -386,6 +394,7 @@ export {
 	PRIORITY_HIGH_LABEL,
 	RELEASE_CLASSIFICATION_LABELS,
 	RELEASE_CLASSIFICATION_NAMES,
+	RELEASE_LABEL,
 	REPOSITORY_LABELS,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,

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

@@ -6,10 +6,10 @@ import { issue_classification } from './issue-classification'
 import { issue_lint } from './issue-lint'
 
 // `josh issue:lint <path>` — read an Issue body from a file and print `ok`, or every template problem
-// one per line, exiting non-zero (joshuafolkken/kit#2123). It reads a path rather than stdin so it can
+// one per line, exiting non-zero. It reads a path rather than stdin so it can
 // lint a body written to a file before the `gh api … issues` call that files it. A body that declares
 // itself a behavior-change Issue is additionally held to the firing-point, baseline and reproduction
-// rules (joshuafolkken/kit#2212, joshuafolkken/kit#2353).
+// rules.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1

package/scripts/issue/issue-lint.ts

@@ -2,7 +2,7 @@ import { markdown_section } from './markdown-section'
 
 // The Issue body template's four headings (`prompts/collaboration-workflow/issue-template.md`) are a
 // fixed shape, but unlike an epic — which `josh epic:check` verifies — nothing checks that a filed
-// Issue carries them. This reports the ones a body is missing (joshuafolkken/kit#2123). The headings
+// Issue carries them. This reports the ones a body is missing. The headings
 // are the single source's, and the document test pins that these match it.
 const REQUIRED_HEADINGS: ReadonlyArray<string> = [
 	'## 背景',

package/scripts/issue/issue-merged.ts

@@ -1,7 +1,7 @@
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 
-// Whether an issue was closed by a merge, read from its REST timeline (joshuafolkken/kit#2701). The
+// Whether an issue was closed by a merge, read from its REST timeline. The
 // issue's own `state_reason` cannot tell: a pull request's `closes #N` and a person's "Close as
 // completed" both answer `completed`. What only a merge leaves is a merged pull request referencing
 // the issue, so the answer is the conjunction — closed now, as completed, and referenced by a merged
@@ -55,7 +55,9 @@ function is_merged_close(rows: ReadonlyArray<TimelineRow>): boolean {
 	return rows.some((row) => row.event === MERGED_REFERENCE)
 }
 
-async function read_merged(issue: string): Promise<boolean> {
+// `undefined` when the timeline could not be read, so a caller that keeps the answer can tell "not
+// merged" from "ask again".
+async function read_merge_state(issue: string): Promise<boolean | undefined> {
 	try {
 		const raw = await git_gh_exec.exec_gh_api({
 			path: `${git_gh_api_path.issue_api_path(issue)}/timeline?per_page=100`,
@@ -65,11 +67,15 @@ async function read_merged(issue: string): Promise<boolean> {
 
 		return is_merged_close(parse_rows(raw))
 	} catch {
-		return false
+		return undefined
 	}
 }
 
-const issue_merged = { is_merged_close, parse_rows, read_merged }
+async function read_merged(issue: string): Promise<boolean> {
+	return (await read_merge_state(issue)) ?? false
+}
+
+const issue_merged = { is_merged_close, parse_rows, read_merge_state, read_merged }
 
 export type { TimelineRow }
 export { issue_merged }

package/scripts/issue/issue-number-shape.ts

@@ -0,0 +1,27 @@
+// The shape an issue number may take, and the refusal when it does not — the one declaration every
+// command reads.
+//
+// It sits in its own module because a rule copied into two files is a rule kept correct in one: a
+// copy that read `/^\d+$/u` accepted issue `0` and a leading zero where every other command refused
+// them. A command that interpolates the number into a shell command a caller is told to paste, a
+// GitHub path, a branch or a lane directory refuses before the interpolation rather than leaving the
+// check to whichever entry point remembered.
+//
+// `ISSUE_NUMBER_PATTERN` stays exported beside `is_issue_number`: a taint analyzer credits a literal
+// pattern test in the expression that returns the value as a sanitizer, but not one reached through a
+// call (`run-merge-cli.ts`).
+
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const BAD_ISSUE_MESSAGE = 'Not an issue number: '
+
+function is_issue_number(value: string): boolean {
+	return ISSUE_NUMBER_PATTERN.test(value)
+}
+
+function require_issue_number(issue: string): void {
+	if (!is_issue_number(issue)) throw new Error(`${BAD_ISSUE_MESSAGE}${issue}`)
+}
+
+const issue_number_shape = { ISSUE_NUMBER_PATTERN, is_issue_number, require_issue_number }
+
+export { issue_number_shape }

package/scripts/issue/issue-rank.ts

@@ -6,7 +6,7 @@ import {
 	RUN_SOLO_LABEL,
 } from './issue-labels'
 
-// The keys that decide which open issue is offered first (joshuafolkken/kit#2928), defined once for
+// The keys that decide which open issue is offered first, defined once for
 // every ranking that asks: the `🗒 Next issues` display, the `auto-ok` pickup and `backlog:next`.
 //
 // In order: `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or

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

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { issue_read, type IssueComment, type IssueFields } from './issue-read'
 import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
 
-// `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call
-// (joshuafolkken/kit#1715).
+// `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call.
 //
 // It replaces the two `gh api` reads `.claude/skills/workflow-commands/issue-comments.md` tells an agent
 // to type per issue. Measured over four recorded `backlogrun` parents, `issue bookkeeping` was the
@@ -28,7 +28,6 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh issue:read <issue-number> [<issue-number> ...]'
 const BLOCK_SEPARATOR = '\n\n---\n\n'
 // The same bound `issue:state` puts on its batch read, for the same reason: every read is a `gh`
@@ -45,7 +44,7 @@ interface IssueContent {
 type NumberResult = { kind: 'issue'; content: IssueContent } | { kind: ReadFailureKind }
 
 // The formatted block for one issue, or the failure kind — what `run:prep` bundles beside the state
-// and the dependency-update scope (joshuafolkken/kit#1978). It reuses this file's read and the shared
+// and the dependency-update scope. It reuses this file's read and the shared
 // `format_issue` rather than reproducing either, so the two `gh` reads and the block shape stay
 // single-sourced here.
 type BlockRead = { kind: 'ok'; block: string } | { kind: ReadFailureKind }
@@ -59,7 +58,7 @@ interface IssueReport {
 // Dropping it answers fewer numbers than were asked for and still exits zero — and nothing in the
 // output then says a number went unanswered. `#1262` copied out of a table is exactly that token.
 function parse_numbers(argv: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
-	const numbers = argv.filter((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+	const numbers = argv.filter((argument) => issue_number_shape.is_issue_number(argument))
 
 	if (numbers.length === 0 || numbers.length !== argv.length) return undefined
 

package/scripts/issue/issue-read.ts

@@ -1,9 +1,8 @@
-import { parse_json_object_safe, read_json_listing } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined, read_json_listing } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
 // The block `josh issue:read` prints for one issue, kept apart from the reading and the printing so
-// the shape of the report is decided by one pure function — the seam `issue-state.ts` already has
-// (joshuafolkken/kit#1715).
+// the shape of the report is decided by one pure function — the seam `issue-state.ts` already has.
 //
 // **It exists because reading one issue costs a parent two turns.** `.claude/skills/workflow-commands/SKILL.md`
 // `issue-comments.md` requires the body *and* the comments, since a decision recorded after the body was written
@@ -11,7 +10,7 @@ import { z } from 'zod'
 // `gh api repos/{owner}/{repo}/issues/<N>/comments`. Measured over four recorded `backlogrun`
 // parents, `issue bookkeeping` was the single largest contributor to the parent's turn count — 110 of
 // 414 turns, 26.6% — and one-issue-at-a-time `gh api` reads were its dominant shape. A parent's cost
-// grows as n²/2 in its own request count (joshuafolkken/kit#1567), so those turns are the
+// grows as n²/2 in its own request count, so those turns are the
 // distribution this collapses.
 //
 // **The comments are never silently absent.** A listing that could not be read prints a line saying
@@ -65,7 +64,7 @@ const UNKNOWN_TIME = '(undated)'
 // parse.
 function parse_issue_fields(json: string): IssueFields | undefined {
 	try {
-		const parsed = parse_json_object_safe(json, issue_fields_schema)
+		const parsed = parse_json_object_or_undefined(json, issue_fields_schema)
 
 		if (parsed === undefined) return undefined
 

package/scripts/issue/issue-reference.ts

@@ -1,14 +1,14 @@
 // An issue named from outside any one graph — a task-list row, a citation in prose, a blocker
 // relation, a child that could not be read. Repository **and** number, because a number alone cannot
 // identify one: issue numbers are unique per repository, so the same `#40` names two different issues
-// depending on who wrote it (joshuafolkken/kit#1014).
+// depending on who wrote it.
 //
 // It lives in the git layer because the `blocked-by` relations are read here and carry a repository
-// of their own (joshuafolkken/kit#1126); the epic domain builds on this layer, never the other way
-// round (joshuafolkken/kit#2904). `epic-reference` re-exports it, so every epic importer is unchanged.
+// of their own; the epic domain builds on this layer, never the other way
+// round. `epic-reference` re-exports it, so every epic importer is unchanged.
 //
-// `state` is present only on a reference read from a `blocked-by` relation whose response carried it
-// (joshuafolkken/kit#1943). The classifier needs it for a blocker no named graph tracks, where there is
+// `state` is present only on a reference read from a `blocked-by` relation whose response carried it.
+// The classifier needs it for a blocker no named graph tracks, where there is
 // no child record to read the state from; every other reference leaves it out.
 interface IssueReference {
 	repo: string

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

@@ -0,0 +1,165 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { github_issue_url } from '#scripts/gh/github-issue-url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { repository_labels } from '#scripts/repo/repository-labels'
+import { RELEASE_LABEL } from './issue-labels'
+import { issue_release } from './issue-release'
+import { session_cite } from './session-cite'
+
+// `josh issue:release <N>` — link Issue `<N>` to its repository's release Issue as a `blocked_by`
+// blocker, filing the release Issue when none is open. `josh issue:file
+// --release` calls the same `link` once its Issue exists, so a new and an existing Issue are linked
+// by one body of code.
+//
+// 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 NONE = 'none'
+const UNKNOWN_REPO_MESSAGE =
+	'Could not read this repository from `git remote` — check `gh auth status`.'
+
+interface ReleaseIssue {
+	issue_number: number
+	// Filed by this call, rather than found open.
+	is_filed: boolean
+}
+
+// `undefined` when the listing is unreadable, `NONE` when it reads and names no open release Issue.
+async function find_open(target: string): Promise<number | typeof NONE | undefined> {
+	const outcome = await git_gh_issue_list.issue_list({
+		json_fields: 'number',
+		limit: MAX_SCANNED,
+		label: RELEASE_LABEL,
+		repo: target,
+	})
+
+	if (outcome.json === undefined) return undefined
+
+	return issue_release.open_release_of(outcome.json) ?? NONE
+}
+
+// The new release Issue's number, or `undefined` when the create call failed. Never `auto-ok`: the
+// labels are `RELEASE_LABELS`, decided here rather than by `issue_auto_ok`, which refuses the label too.
+async function file_release(target: string): Promise<number | undefined> {
+	repository_labels.ensure_labels(target)
+	const request = git_gh_issue_write.issue_create_request({
+		title: issue_release.title_of(target),
+		body: issue_release.body_of(target),
+		labels: issue_release.RELEASE_LABELS,
+		repo: target,
+	})
+
+	try {
+		const url = await git_gh_exec.exec_gh_api(request)
+		const issue_number = Number(github_issue_url.parse(url)?.issue_number) || undefined
+
+		if (issue_number === undefined) console.error(`✖ the release number is unreadable: ${url}`)
+
+		return issue_number
+	} catch (error) {
+		console.error(`✖ the release Issue could not be filed: ${error_text.message_of(error)}`)
+
+		return undefined
+	}
+}
+
+// An unreadable listing files nothing: a second release Issue beside one the listing failed to show
+// would split the blockers between two releases.
+async function release_of(target: string): Promise<ReleaseIssue | undefined> {
+	const open = await find_open(target)
+
+	if (open === undefined) {
+		console.error(`✖ the open ${RELEASE_LABEL} Issues of ${target} could not be listed`)
+
+		return undefined
+	}
+
+	if (open !== NONE) return { issue_number: open, is_filed: false }
+	const filed = await file_release(target)
+
+	return filed === undefined ? undefined : { issue_number: filed, is_filed: true }
+}
+
+function linked_line(release: ReleaseIssue, issue_number: number, 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)}`
+}
+
+function unlinked_line(issue_number: number, blocked: string, target: string): string {
+	const blocker = session_cite.issue(issue_number, undefined, target)
+
+	return `✖ ${blocker} could not be recorded as a blocker of ${session_cite.issue(blocked, undefined, target)}`
+}
+
+// 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> {
+	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))
+
+	if (is_linked) console.info(linked_line(release, issue_number, target))
+	else console.error(unlinked_line(issue_number, blocked, 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 ?? []
+}
+
+// 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)
+	const is_single = rest.length === 0 && issue_number !== undefined
+
+	return is_single && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
+		? Number(issue_number)
+		: undefined
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = issue_number_of(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const current = await git_gh_command.repo_get_name_with_owner()
+
+	if (current === undefined) {
+		console.error(UNKNOWN_REPO_MESSAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return (await link(issue_number, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_release_cli = { link, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_release_cli }