@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/review/review-brief-cli.ts

@@ -23,22 +23,20 @@ import { review_level, type ReviewLevel } from './review-level'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
 
-// `josh review:brief` — print the whole `/code-review` invocation, not just the level
-// (joshuafolkken/kit#1241).
+// `josh review:brief` — print the whole `/code-review` invocation, not just the level.
 //
 // The level is decided in-process by the `review_level` module and is also exposed on its own as
-// `--level-only` (joshuafolkken/kit#1927 folded the former `josh review:level` command in here), so
-// the level a brief prints and the level `--level-only` answers can never disagree. What the full
-// brief adds is everything else the forked review agent cannot find out for itself: whether the gate
-// has passed **or is running** on this tree (joshuafolkken/kit#1242 — the two are started together,
+// `--level-only`, so the level a brief prints and the level `--level-only` answers can never
+// disagree. What the full brief adds is everything else the forked review agent cannot find out for
+// itself: whether the gate has passed **or is running** on this tree (the two are started together,
 // so "still running" is the usual answer at this point), how this project runs its unit tests, and —
 // on round 2 — which files the first round's fixes touched.
 
 const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh review:brief [--round <1|2>] | --level-only [--staged] [--json]'
 
-// The rubric's absolute path, resolved against the kit package rather than the review checkout root
-// (joshuafolkken/kit#2402). The rubric ships inside the package, so a consumer that keeps no
+// The rubric's absolute path, resolved against the kit package rather than the review checkout root.
+// The rubric ships inside the package, so a consumer that keeps no
 // `prompts/` of its own still receives it at `node_modules/@joshuafolkken/kit/prompts/`.
 // `find_package_directory` ascends to the nearest package.json, so this resolves from both the tsx
 // source and the bundled `dist/josh.js`.
@@ -48,7 +46,7 @@ const RUBRIC_PATH = path.join(
 	review_brief.RUBRIC_RELATIVE_PATH,
 )
 const ROUND_FLAG = '--round'
-// `review:level` folded in here (joshuafolkken/kit#1927): it was a second command deciding the same
+// `review:level` folded in here: it was a second command deciding the same
 // thing `review:brief` already prints on its first line, so it is now a mode of this one. `--level-only`
 // answers the level alone — for a pre-commit review run outside any workflow — and, unlike the full
 // brief, it never refuses on the scoped-green gate: the level takes no judgement and reads the changed
@@ -93,7 +91,7 @@ function kept_note(taken_at: string): string {
 // digests describe the implementation as the first round read it. Taking it again on round 2 would
 // overwrite the very record the delta is measured against.
 //
-// **It is written once per run and never retaken** (joshuafolkken/kit#1441). Overwriting on every
+// **It is written once per run and never retaken**. Overwriting on every
 // round-1 invocation put a wrong `skip` one command away: run a bare `josh review:brief` after round
 // 1's fixes are in and the record is retaken against the fixed tree, the fix delta reads empty, and
 // `josh review:round2 --round-1-closed` fires arm A on unreviewed fix code. Keeping the record the
@@ -110,7 +108,7 @@ function kept_note(taken_at: string): string {
 // The write is swallowed for the same reason the gate's is: the brief has already been printed and
 // is correct, so a temp-directory problem must not turn it into a non-zero exit. What a missing
 // snapshot costs is a round 2 that reviews the whole change — wider, never narrower.
-// **The base is recorded beside the file map** (joshuafolkken/kit#1537). The map is a diff against
+// **The base is recorded beside the file map**. The map is a diff against
 // `change_base`, and `change_base` is recomputed on every invocation — so without the commit it was
 // measured against, round 2 cannot tell a fix from a base that moved under it, and reports the
 // difference between two incomparable sets as round 1's fixes.
@@ -137,13 +135,13 @@ function record_round_one(
 	}
 }
 
-// **Recorded before it is printed, and the write is not swallowed** (joshuafolkken/kit#1522). The
+// **Recorded before it is printed, and the write is not swallowed**. The
 // nonce the brief prints is a contract the run enforces later; a brief that printed one it had
 // failed to record would hand the review a command that cannot succeed and the run a check that
 // answers `not-required` — the guard gone, silently, which is the shape this whole record exists to
 // remove.
 //
-// **Whether this is a resume is read first** (joshuafolkken/kit#2945): `record_target` drops the
+// **Whether this is a resume is read first**: `record_target` drops the
 // previous nonce's records, so asked afterwards the finished review would always read as absent. The
 // findings file is the ship's, keyed on `PROJECT_ROOT` as the ship keys it; a review run outside the
 // ship writes none, so it never reads as a resume and keeps the whole change.
@@ -180,7 +178,7 @@ async function open_contract(): Promise<{
 	return { checkout, nonce: review_attest.record_target(checkout, checkout.root), resumed_from }
 }
 
-// Retaken on every round-1 brief, after the pointer it pairs with (joshuafolkken/kit#2945). Swallowed:
+// Retaken on every round-1 brief, after the pointer it pairs with. Swallowed:
 // a record that failed to write predates the next pointer, so the resume widens rather than narrows.
 function record_briefed(round: number, tree: Record<string, string>, base?: string): void {
 	if (round !== FIRST_ROUND) return
@@ -200,7 +198,7 @@ interface ComposeRequest {
 	profile: AgentProfile
 }
 
-// **Swallowed, and the brief keeps its target line** (joshuafolkken/kit#2963): parts that could not be
+// **Swallowed, and the brief keeps its target line**: parts that could not be
 // written leave the reviewer the whole `git diff` to read, which costs truncated output rather than
 // scope — the direction every failure here falls.
 async function read_diff(
@@ -234,9 +232,9 @@ async function compose_brief(request: ComposeRequest): Promise<string> {
 		stamps,
 		// Resolved by the caller rather than printed as a `$(…)` the forked agent would expand: a
 		// subshell that fails expands to nothing, and the bare `git diff` left behind lists only the
-		// unstaged working tree — a review silently narrowed to a fraction of the change
-		// (joshuafolkken/kit#1527). One reading is shared with the record written below, so the commit
-		// the map is stored against is the same one the brief printed (joshuafolkken/kit#1537).
+		// unstaged working tree — a review silently narrowed to a fraction of the change.
+		// One reading is shared with the record written below, so the commit
+		// the map is stored against is the same one the brief printed.
 		base,
 		rubric_path: RUBRIC_PATH,
 		...contract,
@@ -244,7 +242,7 @@ async function compose_brief(request: ComposeRequest): Promise<string> {
 	})
 }
 
-// **What is printed and what is recorded are two readings of one thing** (joshuafolkken/kit#1537).
+// **What is printed and what is recorded are two readings of one thing**.
 // `commit` is what the record stores and round 2 compares, and it has to be a commit: `change_base`
 // degrades to the default-branch *name* when `merge-base` cannot answer, and two rounds storing that
 // same name compare equal while the ref moves under them — the guard failing open, which is the
@@ -256,7 +254,7 @@ async function read_bases(): Promise<{ base: string; commit: string | undefined
 	return { base: commit ?? (await git_command.change_base()), commit }
 }
 
-// **The refusal goes to stderr and the exit code, never into the brief** (joshuafolkken/kit#1511).
+// **The refusal goes to stderr and the exit code, never into the brief**.
 // A line printed inside a brief is read by the review agent as one more fact about the tree; what has
 // to happen here is that no brief is composed at all, since composing one is what starts round 1 —
 // and this command is where `review:attest` mints the nonce a round is counted against, so there is
@@ -318,6 +316,7 @@ async function run_review(round: number, reading: ChangeReading): Promise<number
 	const resolved = agent_role_profile.resolve(agent_role_profile.REVIEWER)
 
 	if (resolved.kind === 'rejected') return report_error(resolved.note)
+	agent_role_profile.warn_of_default()
 	console.info(await compose_brief({ round, paths, tree, base, profile: resolved.profile }))
 	record_round_one(round, tree, commit)
 	record_briefed(round, tree, commit)

package/scripts/review/review-brief.ts

@@ -4,15 +4,13 @@ import { review_checkout, type ReviewCheckout } from './review-checkout'
 import { review_diff_parts, type DiffParts } from './review-diff-parts'
 
 // The text `josh review:brief` prints — the `/code-review` invocation, composed from what the run
-// already knows (joshuafolkken/kit#1241).
+// already knows.
 //
 // **Why a command and not a paragraph in `prompts/review.md`.** `/code-review` runs in a forked
 // process and reads none of this repository's documents; the only thing that reaches it is the
-// argument it is invoked with. Measured on joshuafolkken/kit#1240: both rounds re-ran the unit suite
-// `josh gate` had just passed, both fumbled the runner (`npx vitest`, then a retry), and round 2
-// re-read the whole diff — 439 seconds for a seven-file change. joshuafolkken/kit#1219 had already
-// redefined round 2 as a verification pass **in a document the agent never opens**, which is why it
-// cut nothing.
+// argument it is invoked with. Without it a round re-runs the unit suite `josh gate` just passed,
+// fumbles the runner (`npx vitest`, then a retry), and round 2 re-reads the whole diff — a rule
+// written **in a document the agent never opens** cuts nothing.
 //
 // **What is mechanical and what is only an instruction.** The round-2 target is mechanical: the
 // paths are computed from a digest comparison and handed over as the scope. The "already verified"
@@ -22,8 +20,8 @@ import { review_diff_parts, type DiffParts } from './review-diff-parts'
 const TEST_COMMAND_LINE =
 	'- The unit suite is `pnpm josh test:unit`. Do not reach for `npx vitest`; it is not how this project runs them.'
 
-// **The checkout block, and why the target below names a path instead of assuming one**
-// (joshuafolkken/kit#1522). `/code-review` is forked by the harness and inherits the session's
+// **The checkout block, and why the target below names a path instead of assuming one**.
+// `/code-review` is forked by the harness and inherits the session's
 // working directory, so during a lane run it starts in a tree that holds the previous child's
 // already-merged code. Reading that tree, it finds nothing wrong and says so — and the run reads
 // that silence as a clean review. Neither half of this block is a paragraph a person has to remember
@@ -41,7 +39,7 @@ function attest_line(nonce: string): string {
 	return `Attest before you report: run \`pnpm josh review:attest ${nonce}\` from the checkout you actually read. A non-zero exit means it was not the one above — report \`REVIEW TARGET MISMATCH\` and no findings. Never report "no findings" without that command having passed: a review of the wrong tree finds nothing wrong, and the run cannot tell that apart from approval (joshuafolkken/kit#1522).`
 }
 
-// **The rubric is handed over by path, not pasted in** (joshuafolkken/kit#1927). `/code-review` runs
+// **The rubric is handed over by path, not pasted in**. `/code-review` runs
 // in a forked process that reads none of this repository's documents, so the severity tests, the nine
 // categories and the output format never reached it — the review scored the diff on whatever the
 // forked skill happened to carry. The reviewer has file access (it already runs `git -C <root> …` and
@@ -49,7 +47,7 @@ function attest_line(nonce: string): string {
 // and applied before anything is reported. Absolute because a forked agent resolves a relative path
 // against the tree it was spawned in, which is the wrong one during a lane run.
 //
-// **The path is the kit package's, not the review checkout's** (joshuafolkken/kit#2402). The rubric
+// **The path is the kit package's, not the review checkout's**. The rubric
 // ships inside the kit package (`node_modules/@joshuafolkken/kit/prompts/`), not in a consumer's own
 // tree — so deriving it from the review checkout root pointed at a `prompts/` a `docs/`-less consumer
 // never receives, and the review ran without the scoring rules. The caller resolves it against the
@@ -71,7 +69,7 @@ function checkout_block(checkout: ReviewCheckout, nonce: string): string {
 // `-C <root>` rather than a bare `git diff`, so the command works from whatever directory the
 // forked agent happens to be sitting in rather than only from the right one.
 //
-// **The base is the merge base, not `main` itself** (joshuafolkken/kit#1527). A linked work tree
+// **The base is the merge base, not `main` itself**. A linked work tree
 // shares the `main` ref with every other lane, so a two-dot `git diff main` run in an unmerged lane
 // lists whatever another lane merged in the meantime — in reverse. This line is a command the forked
 // agent runs, so printing the old spelling would hand it exactly the mixed-in listing the reading
@@ -124,7 +122,7 @@ function verified_line(taken_at: string): string {
 	return `Already verified — do not re-run these:\n- lint, the type check, the spell check and the unit tests all passed on this exact tree at ${taken_at} (\`pnpm josh gate\`).`
 }
 
-// **The in-flight sentence claims no result, and that is the point** (joshuafolkken/kit#1242). The
+// **The in-flight sentence claims no result, and that is the point**. The
 // gate and this review are started together, so the honest thing to say is that a gate is running —
 // not that it passed. What it forbids is re-running the unit suite, which is wasted whether the gate
 // ends green or red, and it names who joins the result so the reader knows the check is not being
@@ -139,7 +137,7 @@ function in_flight_line(taken_at: string): string {
 // digests alone it would say a gate is running for as long as nobody edits that tree, about a process
 // that no longer exists: exactly the state the record must never describe.
 //
-// **The written pid alone did not separate the two** (joshuafolkken/kit#1245). It names whatever holds
+// **The written pid alone did not separate the two**. It names whatever holds
 // that number now, so once the operating system reissued it the abandoned marker passed the liveness
 // probe again and this line went back to printing `Running now` about nothing — the same untrue
 // sentence, reached by a longer route. The record therefore carries the writing process's start time
@@ -156,7 +154,7 @@ function live_marker(
 	return matched
 }
 
-// **Matching digests are not enough for the green claim** (joshuafolkken/kit#1537). The map covers
+// **Matching digests are not enough for the green claim**. The map covers
 // the paths the change makes changed, so a merge of the default branch that touches nothing the
 // branch touches leaves every digest identical while the tree gains code the gate never read —
 // and the brief would tell the reviewer that lint, the type check, the spell check and the unit tests
@@ -202,8 +200,8 @@ function format_paths(root: string, paths: ReadonlyArray<string>): string {
 	return paths.map((relative) => `  ${root}/${relative}`).join('\n')
 }
 
-// **An empty target has two readings, and only one of them is "nothing changed"**
-// (joshuafolkken/kit#1537). Since the delta is intersected with the change, round 1's fixes can be
+// **An empty target has two readings, and only one of them is "nothing changed"**.
+// Since the delta is intersected with the change, round 1's fixes can be
 // real and still leave no target — a fix that reverts a file to its base content takes that path out
 // of `git diff` altogether. Printing "nothing changed since round 1" there would contradict the
 // `Not in this change` list directly below it, which is the self-disagreement this whole change
@@ -219,10 +217,10 @@ function round_two_target(root: string, scope: RoundTwoScope): string {
 	return scope.dropped.length > 0 ? NOTHING_LEFT_LINE : EMPTY_DELTA_LINE
 }
 
-// **What round 2 is sent to read, reconciled against the change it is meant to cover**
-// (joshuafolkken/kit#1537). The delta alone is not that list. It is the difference between two file
-// maps, each one a diff against `change_base` **as it stood when that map was taken** — and nothing
-// used to record which commit that was. Move the base between the rounds, which is exactly what a
+// **What round 2 is sent to read, reconciled against the change it is meant to cover**.
+// The delta alone is not that list. It is the difference between two file
+// maps, each one a diff against `change_base` **as it stood when that map was taken**, so the record
+// must name which commit that was. Move the base between the rounds, which is exactly what a
 // resumed run's merge of the default branch does, and the two maps stop covering the same set of
 // paths: their difference then names files the branch never touched and misses files it did.
 //
@@ -247,8 +245,8 @@ function sorted_names(names: ReadonlyArray<string>): ReadonlyArray<string> {
 }
 
 // A record that cannot be compared widens the round to the whole change rather than narrowing it, so
-// every path the change touches is a target. This is the same direction joshuafolkken/kit#1241 chose
-// for a missing record, extended to a record that is present and unusable.
+// every path the change touches is a target — the same direction as for a missing record, extended
+// to a record that is present and unusable.
 function whole_change_scope(tree: Record<string, string>): RoundTwoScope {
 	return {
 		recorded_at: undefined,
@@ -320,8 +318,7 @@ function reconciliation(root: string, base: string, scope: RoundTwoScope): Reado
 	]
 }
 
-// The snapshot's own timestamp, printed rather than assumed. Since joshuafolkken/kit#1441 the record
-// is round 1's own — written once per run, and kept by a later round-1 invocation rather than retaken
+// The snapshot's own timestamp, printed rather than assumed. The record is round 1's own — written once per run, and kept by a later round-1 invocation rather than retaken
 // against the fixed tree — so this line says how far back the target below is measured from. A record
 // left behind by a run that never reached `josh followup` makes the target wider, and its timestamp is
 // the only thing that shows that from here.
@@ -358,8 +355,8 @@ function round_two_block(
 	return narrow_block(scope.recorded_at, scope, root, base)
 }
 
-// **A resumed round 1 reads what changed since the attested review, reusing round 2's reconciliation**
-// (joshuafolkken/kit#2945). A ship that stopped and was re-issued briefed the whole change again, so
+// **A resumed round 1 reads what changed since the attested review, reusing round 2's reconciliation**.
+// A ship that stopped and was re-issued briefed the whole change again, so
 // the reviewer re-read every file the attested review had just read. The scope is the comparison round
 // 2 makes, measured from the tree that review was briefed on. Every reading that cannot narrow falls back to the whole
 // change: no record, a moved base, or an empty target. An empty target is included because a resumed
@@ -406,15 +403,15 @@ interface BriefInput {
 	checkout: ReviewCheckout
 	nonce: string
 	// The commit the change is measured against, resolved by the caller so the printed target carries
-	// a value rather than a subshell that can fail open (joshuafolkken/kit#1527).
+	// a value rather than a subshell that can fail open.
 	base: string
 	// The rubric's absolute path, resolved by the caller against the kit package rather than the review
-	// checkout, so it resolves in a consumer that ships no `prompts/` of its own (joshuafolkken/kit#2402).
+	// checkout, so it resolves in a consumer that ships no `prompts/` of its own.
 	rubric_path: string
-	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume
-	// (joshuafolkken/kit#2945). Absent, round 1 reads the whole change.
+	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume.
+	// Absent, round 1 reads the whole change.
 	resumed_from?: FileMapStamp | undefined
-	// The change written as parts under the Bash output cap (joshuafolkken/kit#2963). Absent when the
+	// The change written as parts under the Bash output cap. Absent when the
 	// write failed, and the target line alone then names the change.
 	diff?: { parts: DiffParts; cap: number } | undefined
 }
@@ -435,7 +432,7 @@ function target_block(input: BriefInput): string {
 	return round_two_block(input.stamps.round_one, input.tree, input.checkout.root, input.base)
 }
 
-// **Only beside a whole-change target** (joshuafolkken/kit#2963): each part is a path's diff against
+// **Only beside a whole-change target**: each part is a path's diff against
 // the base, so beside a narrowed round 2 or a resumed round 1 the list would hand the reviewer the
 // code that narrowing exists to keep out of scope. Decided by the target actually printed, not by
 // the round: every round that cannot narrow widens through `whole_change_target`, and that round

package/scripts/review/review-checkout.ts

@@ -1,7 +1,7 @@
 import { git_command } from '#scripts/git/git-command'
 
 // The checkout `josh review:brief` is describing — the one thing the forked `/code-review` agent
-// cannot work out for itself (joshuafolkken/kit#1522).
+// cannot work out for itself.
 //
 // **`/code-review` runs in a fork that inherits the *session's* working directory, not the run's.**
 // Where the run implementing the change is a lane — a linked work tree under `.kit-lanes/` — that is
@@ -23,7 +23,7 @@ interface ReviewCheckout {
 
 // Three git reads that do not depend on each other, so they are issued together rather than one after
 // another: the brief is printed in front of a review the run is waiting on. The root is a near-instant
-// synchronous `rev-parse` (joshuafolkken/kit#3065); the branch and head still overlap.
+// synchronous `rev-parse`; the branch and head still overlap.
 async function read_checkout(): Promise<ReviewCheckout> {
 	const [root, branch, head] = await Promise.all([
 		git_command.repository_root(),

package/scripts/review/review-diff-parts.ts

@@ -1,8 +1,6 @@
-// The change handed to the reviewer as files no larger than the Bash output cap
-// (joshuafolkken/kit#2963). The brief used to name the whole change as one `git diff` and the rubric
-// as one path, and the forked reviewer printed both through Bash: every print past
-// `BASH_MAX_OUTPUT_LENGTH` came back as a truncated preview plus a saved file it then re-read, and both
-// stayed in the cached prefix of every later request — 120 overflows and 68 re-reads in one review.
+// The change handed to the reviewer as files no larger than the Bash output cap.
+// A print past `BASH_MAX_OUTPUT_LENGTH` comes back as a truncated preview plus a saved file the
+// reviewer then re-reads, and both stay in the cached prefix of every later request.
 //
 // **The diff is split, not shortened.** Each changed path gets its own parts, every part fits under the
 // cap, and the parts of one path concatenate back to exactly its diff — so the scope a review covers

package/scripts/review/review-diff-write.ts

@@ -4,7 +4,7 @@ import { git_spawn } from '#scripts/git/git-spawn'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { review_diff_parts, type DiffParts } from './review-diff-parts'
 
-// Writes the change as the parts `review-diff-parts.ts` cuts it into (joshuafolkken/kit#2963).
+// Writes the change as the parts `review-diff-parts.ts` cuts it into.
 //
 // **One diff per path, read the way the target line defines the change** — `git -C <root> diff
 // <base> -- <path>` for a tracked path, and the file's own content for an untracked one, which no

package/scripts/review/review-finding-ledger.ts

@@ -1,5 +1,7 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+
 // The review-finding line's grammar, its category vocabulary and the aggregation over it — the single
-// place all three are defined (joshuafolkken/kit#2325). A `/code-review` round's findings evaporated
+// place all three are defined. A `/code-review` round's findings evaporated
 // the moment they were fixed, so no one could say which category recurred. They now land in the same
 // append-only ledger the observation lines use (`.josh/observations/`), under a distinct `- rf:`
 // prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
@@ -60,7 +62,7 @@ function is_valid_file(file: string): boolean {
 }
 
 function issue_field(issue: number): string {
-	return `#${String(issue)}`
+	return issue_cite.plain(issue)
 }
 
 function line_of(fields: ReadonlyArray<string>): string {
@@ -132,7 +134,7 @@ function zero_round_count(content: string): number {
 
 // The issue a finding line is keyed to — its fifth field, the `#<N>` token — or `undefined` for a
 // non-finding or malformed line. The record check reads this to ask whether a given issue's round was
-// recorded at all (joshuafolkken/kit#2343).
+// recorded at all.
 function issue_of(line: string): string | undefined {
 	const fields = line.trimStart().slice(FINDING_PREFIX.length).split(FIELD_SEPARATOR)
 
@@ -142,7 +144,7 @@ function issue_of(line: string): string | undefined {
 // **A `none` zero-round line counts as recorded, exactly like a real finding line does.** The gate
 // asks whether the round was recorded, not whether it found anything — reading the issue field, which
 // a zero-finding line carries too, is what keeps a clean round's single line from reading as "nobody
-// recorded this" (joshuafolkken/kit#2343).
+// recorded this".
 function has_issue_record(content: string, issue: number): boolean {
 	const target = issue_field(issue)
 
@@ -158,6 +160,7 @@ const review_finding_ledger = {
 	is_finding_line,
 	is_severity,
 	is_valid_file,
+	SEVERITIES,
 	zero_round_count,
 	zero_round_line,
 }

package/scripts/review/review-findings-cli.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger, type CategoryCount } from './review-finding-ledger'
 
-// `josh review:findings` — the reader over the review-finding ledger (joshuafolkken/kit#2325). It
+// `josh review:findings` — the reader over the review-finding ledger. It
 // prints each recurring category's count, most frequent first, and the number of rounds that recorded
 // zero findings — the denominator that tells a genuinely quiet category apart from one nobody looked
 // at. The write half is `pnpm josh review:record`; both read one grammar from `review-finding-ledger`.
@@ -26,7 +26,7 @@ function format_report(counts: ReadonlyArray<CategoryCount>, zero_rounds: number
 	return `findings by category:\n${body}\n${zero_line(zero_rounds)}`
 }
 
-// Every issue's file of the ledger directory is counted (joshuafolkken/kit#2919): a recurring category
+// Every issue's file of the ledger directory is counted: a recurring category
 // is one whichever issue recorded each sighting.
 async function run(root: string = observation_ledger_home.ledger_root()): Promise<number> {
 	const content = (await observation_ledger_home.read(root)) ?? ''

package/scripts/review/review-level.ts

@@ -1,5 +1,4 @@
-// Which `/code-review` level a change is reviewed at, decided from the changed paths alone
-// (joshuafolkken/kit#966).
+// Which `/code-review` level a change is reviewed at, decided from the changed paths alone.
 //
 // **The decision takes no judgement.** "This one is small" is a judgement made under cost pressure,
 // and cost pressure resolves it toward "small" exactly when a defect is most likely to be shipped —
@@ -24,11 +23,9 @@ const REDUCED_LEVEL: ReviewLevel = 'low'
 // **Documentation is deliberately absent from this list**, which is the opposite of what the
 // "Non-runtime updates" testing exception does with it, and the difference is not an oversight.
 // That exception is about whether an automated test could have caught the defect; this is about
-// whether a human reading the diff is the only thing that can. Measured on this epic:
-// joshuafolkken/kit#963 and #965 were both documentation-only by that classification, and a
-// `medium` review found ten real defects in each — dangling pointers into sections that had been
-// removed, and citations naming the wrong file, in artifacts distributed to every consumer. No test
-// covered them, because prose is what they were.
+// whether a human reading the diff is the only thing that can. Documentation-only diffs carry real
+// defects — dangling pointers into removed sections, and citations naming the wrong file, in
+// artifacts distributed to every consumer — that no test covers, because prose is what they are.
 const INERT_PATHS: ReadonlyArray<string> = [
 	'.editorconfig',
 	'.gitignore',

package/scripts/review/review-record-cli.ts

@@ -1,31 +1,45 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger, type Finding } from './review-finding-ledger'
 import { review_record, type RecordVerdict } from './review-record'
 
 // `josh review:record --issue <N> [<category>:<severity>:<file> ...]` — the one write path for a
-// `/code-review` round's findings (joshuafolkken/kit#2325). It appends a `- rf:` line per finding to
+// `/code-review` round's findings. It appends a `- rf:` line per finding to
 // the issue's own file of the observation ledger, which the run's commit carries like any other
 // ledger change. **A call with no findings is a zero-finding round, and it still writes one line** — so the
 // round that found nothing is recorded rather than mistaken for a round nobody reviewed.
 //
+// **`--comment` records a round that ran after the pull request opened**: the same lines go to the
+// issue as a comment and nothing is appended. A line written to the tree then has no commit of the
+// run's left to ride, so `pnpm josh followup` would push it onto the open pull request and its CI
+// would start over.
+//
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
-// merges (joshuafolkken/kit#2343): `ok` / `not-required` exit zero, `missing` exits non-zero so the
+// merges: `ok` / `not-required` exit zero, `missing` exits non-zero so the
 // merge is refused until the round is recorded. It mirrors `josh review:attest --check`.
 
 const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
-const DATE_END = 10
 const USAGE =
-	'Usage: josh review:record --issue <N> [<category>:<severity>:<file> ...] | josh review:record --check --issue <N>'
+	'Usage: josh review:record --issue <N> [--comment] [<category>:<severity>:<file> ...] | josh review:record --check --issue <N>'
+const FILE_HINT = '  <file>: the cited path, optionally with :line'
 const CHECK_USAGE = 'Usage: josh review:record --check --issue <N>'
 const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
 const NOT_REQUIRED_LINE =
 	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
-const ISSUE_PATTERN = /^[1-9]\d*$/u
-const OPTIONS = { issue: { type: 'string' }, check: { type: 'boolean' } } as const
+const COMMENT_HEADING = '### Review round recorded after the pull request opened'
+const COMMENT_NOTE =
+	'Kept here rather than in the observation ledger: a line appended after the commit would be pushed onto the open pull request and restart its CI.'
+const CODE_FENCE = '```'
+const OPTIONS = {
+	issue: { type: 'string' },
+	check: { type: 'boolean' },
+	comment: { type: 'boolean' },
+} as const
 
 interface Request {
 	issue: number
@@ -34,6 +48,7 @@ interface Request {
 
 interface Parsed {
 	check: boolean
+	comment: boolean
 	issue: string | undefined
 	positionals: ReadonlyArray<string>
 }
@@ -77,6 +92,7 @@ function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
 
 	return {
 		check: parsed.values.check === true,
+		comment: parsed.values.comment === true,
 		issue: parsed.values.issue,
 		positionals: parsed.positionals,
 	}
@@ -85,15 +101,26 @@ function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
 function to_request(parsed: Parsed): Request | undefined {
 	const { issue } = parsed
 
-	if (issue === undefined || !ISSUE_PATTERN.test(issue)) return undefined
+	if (issue === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) return undefined
 
 	const findings = parse_findings(parsed.positionals)
 
 	return findings === undefined ? undefined : { issue: Number(issue), findings }
 }
 
-function today(now: Date): string {
-	return now.toISOString().slice(0, DATE_END)
+// The accepted values are built from the ledger's own vocabulary, so a
+// refused spec names what would have been accepted and a new category appears here unedited.
+function accepted_values(placeholder: string, values: ReadonlyArray<string>): string {
+	return `  ${placeholder}: ${values.join(' | ')}`
+}
+
+function usage_text(): string {
+	return [
+		USAGE,
+		accepted_values('<category>', review_finding_ledger.CATEGORIES),
+		accepted_values('<severity>', review_finding_ledger.SEVERITIES),
+		FILE_HINT,
+	].join('\n')
 }
 
 function build_lines(request: Request, date: string): ReadonlyArray<string> {
@@ -115,7 +142,7 @@ function check_line(verdict: RecordVerdict): string {
 }
 
 async function run_check(issue: string | undefined, root: string): Promise<number> {
-	if (issue === undefined || !ISSUE_PATTERN.test(issue)) {
+	if (issue === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) {
 		console.error(CHECK_USAGE)
 
 		return FAILURE_EXIT_CODE
@@ -134,18 +161,41 @@ async function run_check(issue: string | undefined, root: string): Promise<numbe
 	return FAILURE_EXIT_CODE
 }
 
-// The round lands in its own issue's file (joshuafolkken/kit#2919), so two lanes recording at once
+function comment_body(lines: ReadonlyArray<string>): string {
+	return [COMMENT_HEADING, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
+}
+
+// **A comment that could not be posted fails the record**: it is the round's only copy, so a
+// swallowed refusal would read as a recorded round that exists nowhere.
+async function post_comment(issue: number, lines: ReadonlyArray<string>): Promise<number> {
+	try {
+		const url = await git_gh_issue_write.issue_comment(String(issue), comment_body(lines))
+
+		console.info(`Recorded ${String(lines.length)} review-finding line(s) in ${url.trim()}.`)
+
+		return 0
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+// The round lands in its own issue's file, so two lanes recording at once
 // write two files, and their pull requests never conflict on the ledger.
 async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
 	const request = to_request(parsed)
 
 	if (request === undefined) {
-		console.error(USAGE)
+		console.error(usage_text())
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const lines = build_lines(request, today(now))
+	const lines = build_lines(request, observation_ledger_home.ledger_date(now))
+
+	if (parsed.comment) return await post_comment(request.issue, lines)
+
 	const ledger_path = observation_ledger_home.issue_path(request.issue, root)
 
 	await observation_ledger_home.append(ledger_path, lines)
@@ -154,7 +204,7 @@ async function run_record(parsed: Parsed, now: Date, root: string): Promise<numb
 	return 0
 }
 
-// **The default is the work tree the command runs in, a lane's inside a lane** (joshuafolkken/kit#2919).
+// **The default is the work tree the command runs in, a lane's inside a lane**.
 // The line rides that tree's own commit or `pnpm josh followup`'s pre-merge ledger commit, and
 // `--check` reads the same tree, so the two halves can never disagree about where the round is.
 async function run(
@@ -165,7 +215,7 @@ async function run(
 	const parsed = parse_argv(argv)
 
 	if (parsed === undefined) {
-		console.error(USAGE)
+		console.error(usage_text())
 
 		return FAILURE_EXIT_CODE
 	}
@@ -179,7 +229,14 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv, new Date())
 }
 
-const review_record_cli = { build_lines, parse_finding, run }
+const review_record_cli = {
+	accepted_values,
+	build_lines,
+	comment_body,
+	parse_finding,
+	run,
+	usage_text,
+}
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))