@joshuafolkken/kit 1.1240.0 → 1.1373.0

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))
 

package/scripts/review/review-record.ts

@@ -1,10 +1,11 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger } from './review-finding-ledger'
 
-// The gate that refuses a merge until the `/code-review` round was recorded (joshuafolkken/kit#2343).
+// The gate that refuses a merge until the `/code-review` round was recorded.
 //
 // **The instruction was prose, and prose failed.** `review:record` is the one write path for a
-// round's findings (joshuafolkken/kit#2325), but nothing enforced the call — so across eleven merges
+// round's findings, but nothing enforced the call — so across eleven merges
 // after the instruction landed, it was never run once, and the recurrence ledger stayed blind. This
 // module is the mechanical counterpart to `review-attest`'s `--check`, keyed on the issue rather than
 // on a checkout: a round that left no `- rf:` line for its issue is treated as no review at all.
@@ -29,7 +30,7 @@ interface RecordVerdict {
 }
 
 // The default is the work tree the check runs in — the one `review:record` wrote to, a lane's in a
-// lane (joshuafolkken/kit#2919). Every file of the directory is read, so the round is found whichever
+// lane. Every file of the directory is read, so the round is found whichever
 // file holds it; a directory that is not there answers `undefined`, a ledger this checkout does not
 // keep, which becomes `not-required`.
 async function check(
@@ -51,7 +52,7 @@ const REMEDY =
 	'Record the round with `pnpm josh review:record --issue <N> [<category>:<severity>:<file> ...]` — a clean round is a call with no findings, which records one zero-finding line — then reissue the merge.'
 
 function refusal_message(issue: number): string {
-	return [MISSING_REASON, `Issue: #${String(issue)}`, REMEDY].join('\n')
+	return [MISSING_REASON, `Issue: ${session_cite.issue(issue)}`, REMEDY].join('\n')
 }
 
 const review_record = {

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

@@ -6,7 +6,7 @@ import { review_round2 } from './review-round2'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
 
-// `josh review:round2` — say whether the second review round is due (joshuafolkken/kit#1433).
+// `josh review:round2` — say whether the second review round is due.
 //
 // A command rather than a paragraph in `prompts/review.md`, for the reason `josh review:level` is a
 // command: a rule an agent applies from memory is a rule an agent can talk
@@ -56,8 +56,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const { verdict, reason } = review_round2.decide({
 		// The commit the tree below is a diff against, so the snapshot can be refused when it was taken
 		// against a different one — and the resolved commit rather than `git_command.change_base`, whose
-		// fallback is a ref name that moves and would compare equal to itself
-		// (joshuafolkken/kit#1537).
+		// fallback is a ref name that moves and would compare equal to itself.
 		base: await change_base.resolved(),
 		is_round_one_closed: options.is_round_one_closed,
 		snapshot: review_stamps.round_one_stamp.read(),

package/scripts/review/review-round2.ts

@@ -2,27 +2,21 @@ import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { path_decision } from '#scripts/josh/path-decision'
 import { review_level } from './review-level'
 
-// Whether the second review round runs at all (joshuafolkken/kit#1433).
+// Whether the second review round runs at all.
 //
-// **Every previous measure narrowed round 2; this one asks whether it is due.** joshuafolkken/kit#1219
-// redefined its question, joshuafolkken/kit#1241 carried that question into the forked agent, and
-// `prompts/review.md` → "The narrowing is real in scope and does not show in the wall clock" recorded
-// that neither moved the wall clock. Those records answer "narrow round 2"; none of them answers "do
-// not run it", because none measured a run that skipped one.
+// **Narrowing round 2 does not show in the wall clock** (`prompts/review.md` → "The narrowing is real
+// in scope and does not show in the wall clock"), so this asks whether it is due at all.
 //
-// **The two arms are the two states in which joshuafolkken/kit#1222's reason does not arise.** That
-// issue's conclusion is that round 2 exists because round 1's *fix code* is unreviewed, and that this
-// is structural. Arm A applies where there is no fix code — the findings closed without an edit — so
+// **The two arms are the two states in which round 2's reason does not arise.** Round 2 exists
+// because round 1's *fix code* is unreviewed, and that is structural. Arm A applies where there is no fix code — the findings closed without an edit — so
 // the premise is absent rather than overridden. Arm B applies where the fix code neither executes,
 // nor instructs, nor ships, which is `review-level.ts`'s inert set: the same three ways a defect in
 // this repository escapes, read here for the fix delta instead of the whole change.
 //
-// **The wider line the issue proposed — "the fix delta touches no runtime code path" — is not
-// adopted**, and the evidence against it is already in this directory. `review-level.ts` records that
-// joshuafolkken/kit#963 and #965 were documentation-only diffs in which a `medium` review found ten
-// real defects each — dangling pointers and citations naming the wrong file, in artifacts distributed
-// to every consumer — that no test covered. A prompt fix and a test fix are exactly where the review
-// is the only detector, so exempting them would remove the round in the case it earns its keep.
+// **The wider line — "the fix delta touches no runtime code path" — is not adopted**: as
+// `review-level.ts` records, documentation-only diffs carry real defects no test covers. A prompt
+// fix and a test fix are exactly where the review is the only detector, so exempting them would
+// remove the round in the case it earns its keep.
 
 type RoundTwoVerdict = 'required' | 'skip'
 
@@ -44,7 +38,7 @@ const BASE_MOVED_REASON =
 	'the change base moved since round 1 was recorded, so the two file maps do not cover the same set of paths and their difference is not the fix delta — the round runs rather than reading that difference as one'
 
 interface RoundTwoInput {
-	// **The commit the tree above is a diff against** (joshuafolkken/kit#1537). This decision reads the
+	// **The commit the tree above is a diff against**. This decision reads the
 	// same digest comparison the brief's round-2 target does, so it inherits the same failure: taken
 	// against two different bases, the two maps do not cover the same set of paths, and an empty or
 	// inert-looking delta is then no evidence at all about what round 1 fixed. Here that evidence buys
@@ -68,11 +62,9 @@ interface RoundTwoDecision {
 }
 
 // **The snapshot's own timestamp travels with the answer**, the way `review-brief.ts` prints it
-// beside a round-2 target. An empty delta used to have two readings — round 1 wrote no fix code, or
-// the record was retaken after the fixes by a bare `josh review:brief` — and the digests cannot tell
-// them apart, so joshuafolkken/kit#1441 closed the second one at the source: the record is written
-// once per run and kept thereafter, which leaves "round 1 wrote no fix code" as the only reading of
-// an empty delta. The timestamp stays in the reason because a record can still **outlive** its run —
+// beside a round-2 target. The record is written once per run and kept thereafter, so a bare
+// `josh review:brief` cannot retake it after the fixes, which leaves "round 1 wrote no fix code" as
+// the only reading of an empty delta. The timestamp stays in the reason because a record can still **outlive** its run —
 // `josh followup` is what clears it — and a delta measured from an earlier run's record is wider
 // rather than narrower, which a reader can only see from when that record was taken.
 function empty_reason(taken_at: string): string {

package/scripts/review/review-stamps.ts

@@ -1,58 +1,12 @@
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
 
-// The three records `josh review:brief` reads (joshuafolkken/kit#1241, joshuafolkken/kit#1242).
-//
-// **The gate stamp** is written by `josh gate` when all four checks pass, and answers "were lint, the
-// type check, the spell check and the unit tests green on *this exact tree*". Without the tree half
-// the brief would assert a result that a later edit had already invalidated, which is the one kind of
-// report this repository refuses to make.
-//
-// **The in-flight marker** exists only while `josh gate` is running, and answers a question the gate
-// stamp cannot: the review and the gate now start together, so at the moment the brief is composed
-// the checks have usually not finished (joshuafolkken/kit#1242). Without it that state is
-// indistinguishable from "no gate was ever run", and the review agent re-runs the unit suite the run
-// is already running — the exact cost joshuafolkken/kit#1241 removed. **It asserts nothing about the
-// result**, only that a gate was started on this tree and the run joins it before committing.
-//
-// **The marker names its writer by pid *and* start time** (joshuafolkken/kit#1245). A pid on its own
-// is not a process: an interrupted gate leaves its marker behind, and once the operating system
-// reissues that pid the liveness probe passes again and the marker resumes asserting a gate that
-// ended. The pair closes that, because a reissued pid necessarily started after the record was
-// written. **The marker was not made weaker to fix it** — dropping it, or having the brief ignore it,
-// would put the re-run joshuafolkken/kit#1242 removed straight back.
-//
-// **A marker whose gate is gone is left where it is, and that is the decision rather than an
-// oversight** (joshuafolkken/kit#1245's second question). Three things make leaving it correct here.
-// The record is keyed per checkout, so exactly one file exists and nothing accumulates; the next
-// `josh gate` overwrites it, since `write_stamp` unlinks before it creates; and the identity check
-// makes a leftover inert for as long as it sits there. Removing it from the reader would buy none of
-// that and would cost the one thing that matters: the reader deletes on "not running", which is also
-// the answer a platform that cannot report a start time gives for a gate that **is** running — so the
-// sweep would delete live markers there, and the next brief of that same run would lose the in-flight
-// sentence. `unit-worker-share.ts` sweeps and is not inconsistent with this: its markers are keyed per
-// pid, so they accumulate without bound, and that is what a sweep is for.
-//
-// **The round-1 snapshot** is written by the brief itself, so that `--round 2` can name the fix
-// delta by comparison rather than by an agent recalling which files it edited.
-//
-// Both key on `PROJECT_ROOT` rather than the package directory: a globally installed `josh` has one
-// package directory for every project on the machine, so keying on it would let a run in one project
-// answer for another (the distinction joshuafolkken/kit#1215 drew for `josh latest:scope`).
-//
-// **`PROJECT_ROOT` is `process.cwd()`, so the two commands must run from the same directory to share
-// a record.** That is deliberate rather than overlooked: run from different directories they simply
-// miss each other, the brief finds no record, and it prints `Not verified` — the safe direction. The
-// tree *inside* the record cannot be left to `cwd()` the same way, because there a mismatch resolves
-// to "every file absent" on both sides and compares equal, so `review-tree.ts` asks git for the
-// repository root instead.
-
-// **The two scoped records** answer "were `josh lint:related` and `josh test:related` green on this
-// exact tree" (joshuafolkken/kit#1511). They are separate from the gate stamp because they claim
-// something narrower — the changed files rather than the whole project, and two checks rather than
-// four — and folding them into one record would let a green from either half stand for the other.
-// They are read by `scoped-green.ts`, which is where what they mean is written down; they live here
-// because a stamp prefix declared anywhere else is a second place to look for the same kind of file.
+// The records `josh review:brief` reads, keyed on `PROJECT_ROOT` so a global `josh` never answers for
+// another project. Gate stamp: the four checks were green on this exact tree. In-flight marker: a gate
+// is running on this tree (it asserts no result); it names its writer by pid and start time, so a
+// reissued pid cannot revive it, and a stale one is left for the next gate to overwrite. Round-1
+// snapshot: the tree `--round 2` measures the fix delta against.
+// The scoped stamps claim less than the gate stamp (changed files, two checks), so they stay separate.
 const LINT_RELATED_PREFIX = 'josh-lint-related-stamp-'
 const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
 
@@ -64,9 +18,7 @@ const BRIEFED_PREFIX = 'josh-review-briefed-'
 const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
 const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
 const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
-// **The tree the latest round-1 brief handed out, retaken on every brief** (joshuafolkken/kit#2945).
-// The round-1 snapshot is kept from the first brief of a run, so it is not the tree a later review
-// read — a resume narrowed against it would skip a file put back to that older content.
+// Retaken on every brief: the round-1 snapshot is not the tree a later review read.
 const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	LINT_RELATED_PREFIX,
@@ -77,22 +29,8 @@ const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	PROJECT_ROOT,
 )
 
-// **The round-1 snapshot's lifetime is one run, and something has to end it**
-// (joshuafolkken/kit#1441). Since the record is written once and never retaken, one left on disk
-// would be the record the **next** run's fix delta is measured against — so the run that ends removes
-// it, and `josh followup` is where a run ends. That is the answer to "the same run or a new one" the
-// retake guard needs, taken from the event itself rather than from a proxy for it.
-//
-// **Only one of the two directions is safe, which is why the caller is a single place.** A record
-// this never reaches — a run that stopped before `followup`, a `--no-merge` invocation, a `halfrun`,
-// a review run on its own — is measured from further back, so the next run's delta is wider and the
-// answer is `required`. **Removing one out of turn is the unsafe direction**: the next round-1 brief
-// finds nothing and writes a fresh record against the already-fixed tree, and arm A then fires on
-// unreviewed fix code — the defect joshuafolkken/kit#1441 closed, reintroduced from the other side.
-// So this is called from the end of a run that **merged**, and from nowhere else.
-//
-// Swallowed, and the caller is why: by the time this runs the pull request has already merged, so a
-// temp-directory problem must not turn a completed run into a failed one.
+// Called only from the end of a merged run: a leftover widens the next delta (safe), while an early
+// removal lets round 1 re-snapshot an already-fixed tree (unsafe). Swallowed — the PR already merged.
 function clear_round_one(target?: string): void {
 	try {
 		round_one_stamp.remove(target)

package/scripts/review/review-tree.ts

@@ -5,8 +5,7 @@ import { git_command } from '#scripts/git/git-command'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
 
-// The tree `josh review:brief` records: every path the change touches, and the digest of its content
-// (joshuafolkken/kit#1241).
+// The tree `josh review:brief` records: every path the change touches, and the digest of its content.
 //
 // The path list is `#scripts/git/changed-paths`', the same reading `josh review:level` decides from
 // — a second definition of "changed" would let the brief describe a different change from the level
@@ -33,11 +32,11 @@ function digest_of(root: string, relative: string): string {
 // stored stamp be compared against a fresh reading without a normalization step in between.
 //
 // **The observation ledger is left out of the map**, for the reason `hook-gate-reuse.ts` drops it from
-// the status it reads: it is no code any check runs (joshuafolkken/kit#1756). Kept in, a review's line
+// the status it reads: it is no code any check runs. Kept in, a review's line
 // appended after the gate moved the map, so the ledger commit `pnpm josh followup` pushes carried a
 // tree the record no longer matched — the pre-push hook re-ran the whole unit suite inside the push's
 // 120-second budget, the timed-out push was retried over the still-running suite, and the commit's
-// undo then moved the tree under both (joshuafolkken/kit#2998). Filtered here, every reader of the map
+// undo then moved the tree under both. Filtered here, every reader of the map
 // — the gate's record, both hooks, the brief and the round-2 fix delta — agrees on it.
 function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, string> {
 	const sorted = paths
@@ -54,7 +53,7 @@ function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, str
 // say the gate had verified an arbitrarily edited tree, and `--round 2` would report an empty fix
 // delta. **A defect that answers "all clear" is the one shape this record cannot take**, which is why
 // the root is resolved rather than assumed (measured from `scripts/`: 18 of 25 entries `absent`).
-// The observation ledger is dropped inside `tree_of`, above (joshuafolkken/kit#3017).
+// The observation ledger is dropped inside `tree_of`, above.
 async function read_changed_tree(
 	paths?: ReadonlyArray<string>,
 	root?: string,

package/scripts/rules/bash-triggers.ts

@@ -4,11 +4,11 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 import { shell_segments } from './shell-segments'
 
 // The trigger helpers the enumeration in `delivered-rules.ts` is built from, held here so a rule
-// that lives in its own module can build its own row without importing the enumeration back
-// (joshuafolkken/kit#2119). `is_issue_filing` is the one three rows share — the WIP cap, the per-run
+// that lives in its own module can build its own row without importing the enumeration back.
+// `is_issue_filing` is the one three rows share — the WIP cap, the per-run
 // filing cap and the fold — so it could not stay a private function of the file that spreads their rows.
 
-// **Only `Bash`, and the omission is deliberate** (joshuafolkken/kit#1390): Claude Code denies one
+// **Only `Bash`, and the omission is deliberate**: Claude Code denies one
 // call of a turn and runs the rest, so a refused `Edit` would leave its siblings applied and itself
 // not. Every rule delivered by the enumeration is therefore one whose binding moment is a shell call —
 // so the tool-name guard belongs here rather than to each row, and a row states only what it looks for
@@ -34,7 +34,7 @@ const ISSUES_ENDPOINT = /repos\/[^\s'"]*\/issues(?=$|["'\s])/u
 const TITLE_FIELD = /(?:-f|-F|--field|--raw-field)\s*'?title=/u
 
 // A filing made by hand rather than through `josh issue:file` — the call the `direct-filing` row
-// refuses on every occurrence (joshuafolkken/kit#2808).
+// refuses on every occurrence.
 function is_direct_filing(command: string): boolean {
 	if (ISSUE_CREATE_COMMAND.test(command)) return true
 

package/scripts/rules/decision-oracle-batch.ts

@@ -3,7 +3,7 @@ import { oracle_tokens } from './decision-oracle-tokens'
 
 // The batch oracles — the lane cut, the backlog budget and offer, the epic and post-merge steps, and
 // `run:step` — kept beside the enumeration rather than inside it because `decision-oracle.ts` reached
-// its file-size limit (joshuafolkken/kit#3264). They are one contiguous run of `DECISION_ORACLES`, so
+// its file-size limit. They are one contiguous run of `DECISION_ORACLES`, so
 // spreading them back in at the same position keeps the printed listing's order unchanged.
 
 const {
@@ -24,11 +24,10 @@ const PRE_GATE_CUT_MD = '.claude/skills/workflow-commands/pre-gate-cut.md'
 const BACKLOGRUN_MD = '.claude/skills/workflow-commands/backlogrun.md'
 
 // The command reference in `docs/josh-commands.md` — one section per command, headed by the command
-// itself. joshuafolkken/kit#2190 cut `backlogrun.md` back to a manifest of pointers, so a decision it
-// used to carry inline (`run:merge`, `epic:next`, `backlog:budget`, `run:liveness`, `auto-ok:next`)
-// now has its verdict contract only in this reference. That makes it the single source and the section
-// a reader is routed to, in the same `file.md → \`josh <command>\`` form the `epic:reconcile` and
-// `lane:list` entries already use. joshuafolkken/kit#2254.
+// itself. `backlogrun.md` is a manifest of pointers, so a decision (`run:merge`, `epic:next`,
+// `backlog:budget`, `run:liveness`, `auto-ok:next`) has its verdict contract only in this reference.
+// That makes it the single source and the section a reader is routed to, in the same
+// `file.md → \`josh <command>\`` form the `epic:reconcile` and `lane:list` entries use.
 const RUN_MERGE_REFERENCE = 'docs/josh-commands-run.md → `josh run:merge`'
 const EPIC_NEXT_REFERENCE = 'docs/josh-commands-backlog.md → `josh epic:next`'
 const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands-backlog.md → `josh backlog:budget`'
@@ -107,7 +106,7 @@ const BATCH_ORACLES: ReadonlyArray<DecisionOracle> = [
 	{
 		name: 'run:step',
 		decision: 'The run’s next single action, computed from the event stream, carry and issue state',
-		args: ISSUE_N_ARG,
+		args: `[${ISSUE_N_ARG}]`,
 		// The non-command answers: `run:step` prints a runnable command for a phase with one to run, and
 		// one of these verdicts otherwise. A command line is not a vocabulary token, exactly as an issue
 		// number is not one for `backlog:next`.

package/scripts/rules/decision-oracle-stage.ts

@@ -1,7 +1,7 @@
 import { run_stage } from '#scripts/run/run-stage'
 import type { DecisionOracle } from './decision-oracle'
 
-// The stage-ladder oracle (joshuafolkken/kit#3042), kept beside the enumeration rather than inside it
+// The stage-ladder oracle, kept beside the enumeration rather than inside it
 // because `decision-oracle.ts` sits at its file-size limit. Where a run on an issue starts — and whether
 // the command typed has already been reached — is computed by `run:entry` from the issue and the tree's
 // hold, so the skill's stage table points at the command rather than re-deciding it in prose. The

package/scripts/rules/decision-oracle-tokens.ts

@@ -1,6 +1,5 @@
 // Vocabulary tokens and arguments that appear in more than one oracle entry, shared by
-// `decision-oracle.ts` and `decision-oracle-batch.ts` so each string has one source
-// (joshuafolkken/kit#3264).
+// `decision-oracle.ts` and `decision-oracle-batch.ts` so each string has one source.
 
 const oracle_tokens = {
 	REQUIRED: 'required',

package/scripts/rules/decision-oracle.ts

@@ -1,5 +1,5 @@
 // The enumeration of decision oracles — commands that answer a rule question from mechanically
-// readable inputs, making prose reasoning unnecessary (joshuafolkken/kit#2117).
+// readable inputs, making prose reasoning unnecessary.
 //
 // **Question 0 of the rule-placement criterion**: "Can the rule's answer be computed from
 // mechanically readable inputs alone?" A yes means the rule is answered by a command on this list,
@@ -131,7 +131,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 		name: 'issue:fold',
 		decision: 'Whether findings filed from one session fold into one issue or stay separate',
 		args: '<title...>',
-		vocabulary: ['fold', 'separate', 'no-fold-needed'],
+		vocabulary: ['fold', 'separate', 'no-fold-needed', 'undetermined'],
 		single_source: SPLIT_ASSESSMENT_QUESTION,
 	},
 	{