@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/report/report-lint.ts

@@ -1,10 +1,14 @@
+import { report_format_reference } from './report-format-reference'
+
 // The mechanical half of the two-layer work summary (`CLAUDE.md` Step 0, single-sourced in
 // `prompts/collaboration-workflow/report-format.md`) is a fixed shape, yet only an advisory echo in
 // the `UserPromptSubmit` hook ever mentions it and nothing reads the summary an agent actually
 // wrote. This checks the half a machine can: the labels are present, the overview lines stay inside
 // their length, nothing wraps the summary in a code fence, and no file path or CLI flag leaks into
 // the overview. The judgement half — whether the subject is concrete — is deliberately left out,
-// because a machine cannot answer it (joshuafolkken/kit#2123).
+// because a machine cannot answer it.
+
+const TEMPLATE_HEADING = report_format_reference.SUMMARY_TEMPLATE_HEADING
 
 // The session-facing labels are Japanese because that is the form the summary is written in
 // (`JOSH_SESSION_LANG` defaults to `ja`); `report-format.md`'s template is the single source and the
@@ -33,7 +37,7 @@ const CLI_FLAG_PATTERN = /(?:^|\s)--[a-z]/u
 const BOLD_MARKER = '**'
 const LEADING_LABEL_PUNCTUATION = /^[\s:：]+/u
 
-// The case-based test declaration (joshuafolkken/kit#2246): the changes section carries a first tier
+// The case-based test declaration: the changes section carries a first tier
 // of fixed-vocabulary cases — each non-applicable one crossed out with a reason — and a second tier
 // of at-least-three "if it breaks" conditions. This checks the mechanical half: the two tier markers
 // are present, an N/A cross-out carries a reason, and the second tier holds enough conditions (or the
@@ -235,8 +239,18 @@ function lint_report(summary: string): ReadonlyArray<string> {
 	]
 }
 
+// The violations followed by one line naming where the summary's shape is written
+// — the violations say what is wrong, the pointer where the right shape is.
+// A clean summary stays empty, so `ok` is still the only output of a pass.
+function with_reference(violations: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (violations.length === 0) return violations
+
+	return [...violations, `→ the template: ${report_format_reference.pointer(TEMPLATE_HEADING)}`]
+}
+
 const report_lint = {
 	lint_report,
+	with_reference,
 	REQUIRED_LABELS,
 	MAX_OVERVIEW_CHARS,
 	CASE_LABEL,

package/scripts/review/disposition-cli.ts

@@ -2,8 +2,8 @@
 import { fileURLToPath } from 'node:url'
 import { disposition } from './disposition-logic'
 
-// `josh disposition <path...>` — the machine half of the three-way review disposition
-// (joshuafolkken/kit#2181). It prints `runtime` when any named path reaches a runtime path — a
+// `josh disposition <path...>` — the machine half of the three-way review disposition.
+// It prints `runtime` when any named path reaches a runtime path — a
 // runtime code path, a distributed artifact a consumer reads, or the verification guarding either —
 // and `non-runtime` when every path is inert. `prompts/review.md` → "Three-way disposition after the
 // cap" leaves the run one judgement after this: whether the finding is a confirmed defect.

package/scripts/review/disposition-logic.ts

@@ -1,7 +1,7 @@
 import { review_level } from './review-level'
 
 // Whether a review finding reaches a runtime path — the half of the three-way disposition a machine
-// can answer (joshuafolkken/kit#2181). `prompts/review.md` → "Three-way disposition after the cap"
+// can answer. `prompts/review.md` → "Three-way disposition after the cap"
 // routes a non-High finding to branch 2 (file it) only when it is a **confirmed defect that reaches a
 // runtime code path**. "Reaches" is read exactly as the review-level rubric reads it — a runtime code
 // path, a distributed artifact a consumer reads, or the verification guarding either — which is the

package/scripts/review/live-evidence.ts

@@ -1,11 +1,11 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_command } from '#scripts/git/git-command'
 import { reproduction_measure } from '#scripts/issue/reproduction-measure'
+import { report_format_reference } from '#scripts/report/report-format-reference'
 import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-logic'
 
-// joshuafolkken/kit#2446. "Done" meant lint, types and unit tests were green and the review found
-// nothing — proof the code is right in isolation, never that the feature works where it runs. The
-// recent defects (#2402, #2419, #2393) all came through that gap. **This is the seam where it closes**:
+// Lint, types and unit tests green and a review that found nothing prove the code is right in
+// isolation, never that the feature works where it runs. **This is the seam where that gap closes**:
 // a runtime change merges only once its pull request carries the acceptance criteria run for real —
 // the command and the output it actually printed, in the evidence section `EVIDENCE_HEADING` names.
 //
@@ -15,6 +15,9 @@ import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-l
 // reproduction-section parser, so a prose "confirmed it works" is refused here exactly as it is there.
 
 const EVIDENCE_HEADING = '## 実機証跡'
+// The shape the section needs and where it is written down, so a refusal
+// names the format instead of leaving the reader to search for it.
+const EVIDENCE_FORMAT = `under ${EVIDENCE_HEADING}, a backticked command followed by a fenced block holding the output it actually printed (prose such as "confirmed" is not accepted) — format: ${report_format_reference.pointer(report_format_reference.COMPLETION_REPORT_HEADING)}`
 
 function verdict_for(paths: ReadonlyArray<string>, body: string | undefined = ''): Verdict {
 	if (test_declared_logic.runtime_files(paths).length === 0) return 'exempt'
@@ -49,12 +52,12 @@ async function check(branch_name: string): Promise<Verdict> {
 function refusal_message(): string {
 	return [
 		`Merge refused: this pull request changes runtime code but its body has no ${EVIDENCE_HEADING} section.`,
-		'Run the acceptance criteria for real, then add the section: a backticked command followed by a',
-		'fenced block holding the output it actually printed (prose such as "confirmed" is not accepted).',
+		'Run the acceptance criteria for real, then add the section:',
+		EVIDENCE_FORMAT,
 		'Update the body with `gh api -X PATCH repos/{owner}/{repo}/pulls/<N> -F body=@<path>`, then re-run.',
 	].join('\n')
 }
 
-const live_evidence = { EVIDENCE_HEADING, check, refusal_message, verdict_for }
+const live_evidence = { EVIDENCE_FORMAT, EVIDENCE_HEADING, check, refusal_message, verdict_for }
 
 export { live_evidence }

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

@@ -3,8 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { review_attest, type AttestVerdict } from './review-attest'
 import { review_checkout } from './review-checkout'
 
-// `josh review:attest` — the two halves of the checkout contract `josh review:brief` opens
-// (joshuafolkken/kit#1522).
+// `josh review:attest` — the two halves of the checkout contract `josh review:brief` opens.
 //
 // **`josh review:attest <nonce>` is run by the review**, from the checkout it actually read. It
 // compares that checkout against the one the brief described and exits non-zero when they differ, so

package/scripts/review/review-attest.ts

@@ -6,7 +6,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
 
-// The record that says which checkout a `/code-review` actually read (joshuafolkken/kit#1522).
+// The record that says which checkout a `/code-review` actually read.
 //
 // **The root cause is not ours to fix.** `/code-review` is forked by the harness and inherits the
 // session's working directory; nothing in this repository decides that. What *is* ours is the
@@ -242,7 +242,7 @@ function is_written_since(source: string, taken_at: string): boolean {
 	}
 }
 
-// **Whether the last briefed review of this branch finished** (joshuafolkken/kit#2945). A ship resumed
+// **Whether the last briefed review of this branch finished**. A ship resumed
 // after a stop re-issues round 1, and without this answer it briefed the whole change again — the
 // files the finished review had just read, re-read at full cost. It is asked before `record_target`
 // mints the next nonce, since that call drops the record it reads. The branch must match: the pointer
@@ -265,7 +265,7 @@ function is_reviewed_on(checkout: ReviewCheckout, findings_path: string, root?:
 }
 
 // Whether a record written at `written_at` belongs to the brief the pointer names rather than an earlier
-// one (joshuafolkken/kit#2945): that brief writes it right after minting the pointer. ISO timestamps
+// one: that brief writes it right after minting the pointer. ISO timestamps
 // order as strings.
 function is_briefed_since(written_at: string, root?: string): boolean {
 	const pointer = read_pointer(root)

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',