@joshuafolkken/kit 1.1005.0 → 1.1035.0

package/scripts/package/package-scout-cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { z } from 'zod'
 import {
 	package_scout,
@@ -120,27 +120,19 @@ function parse_size(raw: string | undefined): number {
 	return raw === undefined || !Number.isSafeInteger(parsed) || parsed <= 0 ? DEFAULT_SIZE : parsed
 }
 
-function parse_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
-	const { values, positionals } = parseArgs({
+// An unknown flag is `undefined` rather than a throw, so the answer is the usage line rather than a
+// stack trace, on a command whose output a workflow reads.
+function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
+	const parsed = cli_flags.parse_or_undefined({
 		args: [...argv],
 		options: { size: { type: 'string' } },
 		allowPositionals: true,
 	})
-	const keywords = positionals.join(' ').trim()
-
-	if (keywords === '') return undefined
+	const keywords = parsed?.positionals.join(' ').trim() ?? ''
 
-	return { keywords, size: parse_size(values.size) }
-}
+	if (parsed === undefined || keywords === '') return undefined
 
-// An unknown flag makes `parseArgs` throw. Caught so the answer is the usage line rather than a stack
-// trace, on a command whose output a workflow reads.
-function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
-	try {
-		return parse_arguments(argv)
-	} catch {
-		return undefined
-	}
+	return { keywords, size: parse_size(parsed.values.size) }
 }
 
 async function report(args: ScoutArguments): Promise<number> {

package/scripts/ports/port-command.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { ports, type PortEnvironment } from '#ports'
+import { error_text } from '#scripts/lib/error-message'
 
 const SUCCESS_EXIT_CODE = 0
 const USAGE_EXIT_CODE = 1
@@ -49,7 +50,7 @@ function run(argv: ReadonlyArray<string>, environment?: PortEnvironment): PortRe
 		return { text: String(RESOLVERS[name](environment)), exit_code: SUCCESS_EXIT_CODE }
 	} catch (error) {
 		return {
-			text: error instanceof Error ? error.message : String(error),
+			text: error_text.message_of(error),
 			exit_code: FAILURE_EXIT_CODE,
 		}
 	}

package/scripts/propagate/propagate-publish.ts

@@ -1,7 +1,6 @@
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { poll } from '#scripts/lib/poll'
 import { with_page_size } from '#scripts/version/version-remote'
-import { execaSync } from 'execa'
 
 // Waiting for a specific version of this package to actually exist in the registry.
 //
@@ -58,15 +57,15 @@ function finish(state: PublishWaitState, version: string, attempts: number): Pub
 // reported apart, because one means wait longer and the other means something is broken.
 function fetch_published_versions(versions_endpoint: string): Array<string> | undefined {
 	const endpoint = with_page_size(versions_endpoint, VERSIONS_PAGE_SIZE)
-	const result = execaSync('gh', ['api', endpoint, '--jq', NAMES_JQ], {
-		...git_gh_exec.direct_environment(),
-		reject: false,
-		timeout: GH_TIMEOUT_MS,
+	const stdout = git_gh_exec.read_gh_api_sync({
+		path: endpoint,
+		jq_filter: NAMES_JQ,
+		timeout_ms: GH_TIMEOUT_MS,
 	})
-	if (result.exitCode !== 0) return undefined
+	if (stdout === undefined) return undefined
 
 	try {
-		const parsed: unknown = JSON.parse(result.stdout)
+		const parsed: unknown = JSON.parse(stdout)
 
 		return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : undefined
 	} catch {

package/scripts/propagate/propagate-steps.ts

@@ -3,6 +3,7 @@ import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
 import { OTHER_CHANGE_LABEL } from '#scripts/git/issue-labels'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
+import { error_text } from '#scripts/lib/error-message'
 import { build_upgrade_shell_command } from '#scripts/version/upgrade-shell-command'
 import { create_version_command_config } from '#scripts/version/version-command-config'
 import { execaSync } from 'execa'
@@ -235,7 +236,7 @@ function precheck_step(target: PropagateTarget, step: string): StepResult {
 // multi-line detail would print raw JSON as an unindented second line and glue that warning to the
 // end of it, where nobody reading the report would see it.
 function to_issue_detail(error: unknown): string {
-	const message = error instanceof Error ? error.message : String(error)
+	const message = error_text.message_of(error)
 
 	return message.replaceAll('\n', ' ').trim()
 }

package/scripts/propagate/propagate.ts

@@ -2,7 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { refuse_unknown_flags } from '#scripts/lib/cli-flags'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { status_icons } from '#scripts/lib/status-icons'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
@@ -72,7 +72,8 @@ function parse_options(argv: ReadonlyArray<string>): RunOptions {
 		...(target !== undefined && { target }),
 	}
 	const usage =
-		target_usage ?? refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
+		target_usage ??
+		cli_flags.refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
 
 	return usage === undefined ? options : { ...options, usage }
 }

package/scripts/refactor/import-graph.ts

@@ -1,5 +1,5 @@
-import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 
 // The scope expansion `prompts/refactoring.md` §4.3 used to describe in prose (joshuafolkken/kit#2180):
 // from the seed files, follow imports both ways — the files a seed imports and the files that import a
@@ -67,11 +67,7 @@ function resolve_spec(
 }
 
 function read_source(file: string): string {
-	try {
-		return readFileSync(file, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(file) ?? ''
 }
 
 function file_imports(file: string, root: string, known: ReadonlySet<string>): ReadonlySet<string> {

package/scripts/registry-migration/migrate.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
 import { execa } from 'execa'
 import { z } from 'zod'
 import { migrate_logic, type MigrationPlan } from './migrate-logic'
@@ -70,7 +71,7 @@ interface MigrationContext {
 }
 
 function read_file(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(file_path)
 }
 
 function has_registry_override(environment: NodeJS.ProcessEnv): boolean {

package/scripts/registry-migration/user-npmrc.ts

@@ -1,13 +1,13 @@
-import { existsSync, readFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 
 const NPMRC = '.npmrc'
 
 function read(home: string = os.homedir()): string {
 	const file = path.join(home, NPMRC)
 
-	return existsSync(file) ? readFileSync(file, 'utf8') : ''
+	return file_reader.read_file_or_empty(file)
 }
 
 const user_npmrc = { read }

package/scripts/release/release-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
+import { error_text } from '#scripts/lib/error-message'
 import { release_history } from './release-history'
 import { release_plan, type ReleasePlan } from './release-plan'
 import { release_publish } from './release-publish'
@@ -76,7 +77,7 @@ async function main(): Promise<void> {
 	try {
 		process.exit(await run(is_dry_run_requested(process.argv)))
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(FAILURE_EXIT_CODE)
 	}
 }

package/scripts/repo/repo-setting.ts

@@ -1,7 +1,5 @@
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
-import { execaSync } from 'execa'
 
 // The shared half of every "report a GitHub repository setting kit cannot write" check.
 //
@@ -27,17 +25,21 @@ interface RepoApiResult {
 	stdout: string
 }
 
+const FAILED_EXIT_CODE = 1
+
 // One `gh api` call. Never throws and never propagates a non-zero exit: an unreadable answer is a
-// reported status, not a command failure.
+// reported status, not a command failure. Every failure reads as `FAILED_EXIT_CODE` with no output,
+// which `parse_payload` treats as unreadable whatever gh's own exit code was.
 function query_repo_api(api_path: string): RepoApiResult {
-	const result = execaSync('gh', ['api', api_path], {
-		...git_gh_exec.direct_environment(),
+	const stdout = git_gh_exec.read_gh_api_sync({
+		path: api_path,
 		cwd: PROJECT_ROOT,
-		reject: false,
-		timeout: GH_TIMEOUT_MS,
+		timeout_ms: GH_TIMEOUT_MS,
 	})
 
-	return { exit_code: result.exitCode ?? 1, stdout: read_spawn_stdout(result) }
+	return stdout === undefined
+		? { exit_code: FAILED_EXIT_CODE, stdout: '' }
+		: { exit_code: 0, stdout }
 }
 
 // The response body as an object, or nothing. A non-zero exit covers every case where the answer

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

@@ -1,9 +1,9 @@
 // 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
 // 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 (`docs/maintainers/observations.md`), under a distinct `- rf:`
-// prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger
-// file, one flush path, a second line *type* rather than a second ledger.
+// append-only ledger the observation lines use (`docs/maintainers/observations/`), under a distinct `- rf:`
+// prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
+// one commit path, a second line *type* rather than a second ledger.
 
 const FINDING_PREFIX = '- rf:'
 const FIELD_SEPARATOR = ' | '

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

@@ -1,5 +1,4 @@
 #!/usr/bin/env tsx
-import { readFile } from 'node:fs/promises'
 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'
@@ -29,16 +28,10 @@ function format_report(counts: ReadonlyArray<CategoryCount>, zero_rounds: number
 	return `findings by category:\n${body}\n${zero_line(zero_rounds)}`
 }
 
-async function read_ledger(ledger_path: string): Promise<string> {
-	try {
-		return await readFile(ledger_path, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-async function run(ledger_path: string = observation_ledger_home.ledger_path()): Promise<number> {
-	const content = await read_ledger(ledger_path)
+// Every issue's file of the ledger directory is counted (joshuafolkken/kit#2919): 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)) ?? ''
 	const counts = review_finding_ledger.category_counts(content)
 
 	console.info(format_report(counts, review_finding_ledger.zero_round_count(content)))

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

@@ -7,8 +7,8 @@ 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
-// the observation ledger, which `pnpm josh observations:flush` then commits like any other ledger
-// change. **A call with no findings is a zero-finding round, and it still writes one line** — so the
+// 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.
 //
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
@@ -121,14 +121,14 @@ function check_line(verdict: RecordVerdict): string {
 	return verdict.status === 'ok' ? RECORDED_LINE : NOT_REQUIRED_LINE
 }
 
-async function run_check(issue: string | undefined, ledger_path: string): Promise<number> {
+async function run_check(issue: string | undefined, root: string): Promise<number> {
 	if (issue === undefined || !ISSUE_PATTERN.test(issue)) {
 		console.error(CHECK_USAGE)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const verdict = await review_record.check(Number(issue), ledger_path)
+	const verdict = await review_record.check(Number(issue), root)
 
 	if (verdict.status === 'ok' || verdict.status === 'not-required') {
 		console.info(check_line(verdict))
@@ -141,7 +141,9 @@ async function run_check(issue: string | undefined, ledger_path: string): Promis
 	return FAILURE_EXIT_CODE
 }
 
-async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promise<number> {
+// The round lands in its own issue's file (joshuafolkken/kit#2919), 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) {
@@ -151,6 +153,7 @@ async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promi
 	}
 
 	const lines = build_lines(request, today(now))
+	const ledger_path = observation_ledger_home.issue_path(request.issue, root)
 
 	await observation_ledger_home.append(ledger_path, lines)
 	console.info(confirmation(lines.length, ledger_path))
@@ -158,13 +161,13 @@ async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promi
 	return 0
 }
 
-// **The default is the primary checkout's ledger, even inside a lane** (joshuafolkken/kit#2419). A line
-// appended to a lane's own copy never reached the default branch — the lane's flush is refused and
-// `lane:close` does not carry the file — while `--check` read that same copy and let the merge through.
+// **The default is the work tree the command runs in, a lane's inside a lane** (joshuafolkken/kit#2919).
+// 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(
 	argv: ReadonlyArray<string>,
 	now: Date,
-	ledger_path: string = observation_ledger_home.ledger_path(),
+	root: string = observation_ledger_home.ledger_root(),
 ): Promise<number> {
 	const parsed = parse_argv(argv)
 
@@ -174,9 +177,9 @@ async function run(
 		return FAILURE_EXIT_CODE
 	}
 
-	if (parsed.check) return await run_check(parsed.issue, ledger_path)
+	if (parsed.check) return await run_check(parsed.issue, root)
 
-	return await run_record(parsed, now, ledger_path)
+	return await run_record(parsed, now, root)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/review/review-record.ts

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger } from './review-finding-ledger'
 
@@ -29,24 +28,15 @@ interface RecordVerdict {
 	issue?: number
 }
 
-// `undefined` for both "the file is absent" and "the file could not be read" — they are the same
-// answer here, a ledger this checkout does not keep, and the caller turns that into `not-required`.
-async function read_ledger(ledger_path: string): Promise<string | undefined> {
-	try {
-		return await readFile(ledger_path, 'utf8')
-	} catch {
-		return undefined
-	}
-}
-
-// The default is the primary checkout's ledger, the one `review:record` writes from a lane
-// (joshuafolkken/kit#2419) — a cwd-relative default read the lane's copy, so the followup gate refused
-// every round recorded from a lane (joshuafolkken/kit#2431).
+// 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
+// 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(
 	issue: number,
-	ledger_path: string = observation_ledger_home.ledger_path(),
+	root: string = observation_ledger_home.ledger_root(),
 ): Promise<RecordVerdict> {
-	const content = await read_ledger(ledger_path)
+	const content = await observation_ledger_home.read(root)
 
 	if (content === undefined) return { status: 'not-required' }
 	if (review_finding_ledger.has_issue_record(content, issue)) return { status: 'ok', issue }

package/scripts/rules/decision-oracle.ts

@@ -47,7 +47,7 @@ const HUMAN_REVIEW = 'human-review'
 // test. `LIVE` is the silent norm; `STOPPED` and `UNKNOWN` lead the difference lines.
 const LIVE = 'live'
 const STOPPED = 'stopped'
-// The verdicts `epic --reconcile` prints; kept in step with the `git_epic_reconcile` constants in its
+// The verdicts `epic --reconcile` prints; kept in step with the `epic_reconcile` constants in its
 // test.
 const RECONCILED = 'reconciled'
 const NOTHING_TO_RECONCILE = 'nothing to reconcile'
@@ -302,7 +302,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 		decision: 'Whether cross-file or cross-repository code duplication exists',
 		args: '',
 		vocabulary: ['clean', 'clones:'],
-		single_source: 'prompts/collaboration-workflow/no-clones.md',
+		single_source: 'prompts/collaboration-workflow/principles.md → クローン禁止',
 	},
 	{
 		name: 'epic:reconcile',

package/scripts/rules/rule-body-guard.ts

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs'
 import { json_value } from '#scripts/lib/json-value'
+import { file_reader } from '#scripts/lib/read-file'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
@@ -81,7 +81,7 @@ function string_field(input: Record<string, unknown>, key: string): string {
 // measure against. Injected so the suite controls it without touching the real filesystem, the way
 // `file-body.ts` injects its existence check. A new file reads as empty, so its whole body is added.
 function read_existing(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(file_path)
 }
 
 function texts_of(

package/scripts/rules/rule-value-cache.ts

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process'
+import { mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
+
+// The `rule:value` reading at the `backlogrun` loop head, without the loop waiting on it
+// (joshuafolkken/kit#2881). Measuring re-reads every transcript and takes minutes, and `backlog:offer`
+// ran it synchronously on every iteration, so each dispatch waited on it. The loop head now prints the
+// last reading from a cache and, when the last refresh is old enough, starts one in a detached process
+// — `josh rule:value --refresh` — so the next iteration prints the newer reading.
+//
+// **It reports and never fails**, as `rule:value` itself does: a missing cache, an unwritable directory
+// or a refresh that could not start prints at most nothing, and never changes the offer's answer.
+
+const CACHE_DIRECTORY = ['node_modules', '.cache', 'josh']
+const CACHE_FILE = 'rule-value.txt'
+// Touched when a refresh starts, so the loop head starts at most one per interval however often it runs.
+const STAMP_FILE = 'rule-value.stamp'
+const MS_PER_MINUTE = 60_000
+const REFRESH_MINUTES = 15
+const REFRESH_MS = REFRESH_MINUTES * MS_PER_MINUTE
+const REFRESH_ARGV = ['josh', 'rule:value', '--refresh']
+const PNPM = 'pnpm'
+const TEMPORARY_SUFFIX = '.tmp'
+
+interface CachePorts {
+	now: () => number
+	start_refresh: (cwd: string) => void
+}
+
+function cache_path(cwd: string, file: string): string {
+	return path.join(cwd, ...CACHE_DIRECTORY, file)
+}
+
+function read_cached(cwd: string): string | undefined {
+	return file_reader.read_if_readable(cache_path(cwd, CACHE_FILE))
+}
+
+function is_refresh_due(cwd: string, now_ms: number): boolean {
+	try {
+		return now_ms - statSync(cache_path(cwd, STAMP_FILE)).mtimeMs >= REFRESH_MS
+	} catch {
+		return true
+	}
+}
+
+function write_cache_file(cwd: string, file: string, text: string): void {
+	const target = cache_path(cwd, file)
+	const temporary = `${target}${TEMPORARY_SUFFIX}`
+
+	mkdirSync(path.dirname(target), { recursive: true })
+	writeFileSync(temporary, text)
+	renameSync(temporary, target)
+}
+
+function ignore_spawn_error(): void {
+	/* a refresh that could not start leaves the last reading in place */
+}
+
+// Detached with no descriptor shared, so the loop head exits — and a backgrounded caller completes —
+// without waiting on the measurement.
+function start_refresh_default(cwd: string): void {
+	const child = spawn(PNPM, REFRESH_ARGV, { cwd, detached: true, stdio: 'ignore' })
+
+	child.on('error', ignore_spawn_error)
+	child.unref()
+}
+
+const DEFAULT_PORTS: CachePorts = { now: Date.now, start_refresh: start_refresh_default }
+
+function refresh_if_due(cwd: string, ports: CachePorts): void {
+	if (!is_refresh_due(cwd, ports.now())) return
+
+	write_cache_file(cwd, STAMP_FILE, new Date(ports.now()).toISOString())
+	ports.start_refresh(cwd)
+}
+
+// The loop-head call: the last reading to stderr, then a refresh when one is due.
+function emit(cwd: string = process.cwd(), ports: CachePorts = DEFAULT_PORTS): void {
+	const cached = read_cached(cwd)
+
+	if (cached !== undefined) process.stderr.write(cached)
+
+	try {
+		refresh_if_due(cwd, ports)
+	} catch {
+		// A refresh that could not be recorded or started leaves the last reading in place.
+	}
+}
+
+// The detached refresh's body: the reading written whole, so a reader never sees half of one.
+function store(text: string, cwd: string = process.cwd()): void {
+	write_cache_file(cwd, CACHE_FILE, `${text}\n`)
+}
+
+const rule_value_cache = { CACHE_FILE, REFRESH_MS, STAMP_FILE, cache_path, emit, store }
+
+export type { CachePorts }
+export { rule_value_cache }

package/scripts/rules/rule-value-cli.ts

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
 import { delivered_rules } from './delivered-rules'
 import { rule_value, type RuleReading } from './rule-value'
+import { rule_value_cache } from './rule-value-cache'
 
 // `josh rule:value` — what each delivered rule earns on the channel that carries it, one row per rule
 // (joshuafolkken/kit#2271). `rule_value.measure` was public but had no caller outside its own test, so
@@ -14,6 +15,8 @@ import { rule_value, type RuleReading } from './rule-value'
 // no measurable transcript prints `NO_TARGETS` and exits zero rather than erroring, so a fresh
 // checkout reads differently from a broken command.
 
+const ARGV_OFFSET = 2
+const REFRESH_FLAG = '--refresh'
 const PERCENT_SIGN = '%'
 const COLUMN_GAP = '  '
 const NO_TARGETS = 'no measurement targets'
@@ -98,24 +101,22 @@ function render(runs: ReadonlyArray<ReadonlyArray<string>>): string {
 		.join('\n')
 }
 
-// The loop-head call: `backlog:offer` writes this to stderr once per iteration, so a rule that never
-// fires appears as a printed row rather than as something a person has to go looking for.
-function emit(cwd: string = process.cwd()): void {
-	process.stderr.write(`${render(gather_runs(cwd))}\n`)
-}
+// `--refresh` is the detached measurement the `backlogrun` loop head starts: the reading goes to the
+// cache `backlog:offer` prints from, never to stdout (`rule-value-cache.ts`, joshuafolkken/kit#2881).
+function run_rule_value(argv: ReadonlyArray<string> = [], cwd: string = process.cwd()): number {
+	const reading = render(gather_runs(cwd))
 
-function run_rule_value(cwd: string = process.cwd()): number {
-	process.stdout.write(`${render(gather_runs(cwd))}\n`)
+	if (argv.includes(REFRESH_FLAG)) rule_value_cache.store(reading, cwd)
+	else process.stdout.write(`${reading}\n`)
 
 	return 0
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = run_rule_value()
+	process.exitCode = run_rule_value(process.argv.slice(ARGV_OFFSET))
 }
 
 const rule_value_cli = {
-	emit,
 	gather_runs,
 	group_by_run,
 	render,

package/scripts/rules/rule-value.ts

@@ -9,7 +9,7 @@ import { delivered_rules, type MeasuredRule } from './delivered-rules'
 // (joshuafolkken/kit#1525).
 //
 // **It exists because the eviction order was decided by protection rather than by value.**
-// `.claude/skills/workflow-commands/rule-residency.md` recorded that when a rule is trimmed to keep a
+// `prompts/collaboration-workflow/residency.md` records that when a rule is trimmed to keep a
 // byte count, the sentence that goes is the one no marker pinned (joshuafolkken/kit#951) — so the
 // least-defended text leaves, never the least-useful. Nothing in the repository could tell the two
 // apart: `scripts/josh/hook-decision.ts` keeps a once-per-run stamp that answers "has this fired

package/scripts/run/run-carry-args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
 import { run_issue_number } from './run-issue-number'
 
@@ -76,11 +76,7 @@ type Request =
 const READ_REQUEST: Request = { kind: 'read' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 function text_of(value: OptionValue): string | undefined {

package/scripts/run/run-carry-cli.ts

@@ -10,7 +10,6 @@ import {
 	type RunCarry,
 } from './run-carry'
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
-import { run_carry_flush } from './run-carry-flush'
 import { run_carry_stash } from './run-carry-stash'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
@@ -344,16 +343,15 @@ async function count(
 // **A stop over a record that is still there pushes one ⏸️ confirmation before the record goes**
 // (joshuafolkken/kit#2136). `plan` is read from the record `--end` is about to remove, so the second
 // `--end` reads `none` and plans nothing — one stop never notifies twice. A clean `--end` passes no
-// reason and stays silent, because a completed run has its own notification. The batch's one ledger
-// flush rides the same read for the same reason (joshuafolkken/kit#2492, `run-carry-flush.ts`), and
-// runs last: it waits out a pull request's CI, so a flush cut short must find the record already gone
-// and the stop already announced. The closed-issue stash report (joshuafolkken/kit#2505,
-// `run-carry-stash.ts`) is once per invocation on the same read, and goes first because it is quick.
+// reason and stays silent, because a completed run has its own notification. The closed-issue stash
+// report (joshuafolkken/kit#2505, `run-carry-stash.ts`) is once per invocation on the same read.
+//
+// **No ledger flush rides it any more** (joshuafolkken/kit#2919): each lane merges its own ledger
+// lines with its own pull request, so there is nothing left in the primary checkout to flush.
 async function report_end(read: CarryRead): Promise<void> {
 	if (read.kind === 'none') return
 
 	await run_carry_stash.report_orphans()
-	await run_carry_flush.flush_ledger()
 }
 
 async function finish(