@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/rules/protected-files.ts

@@ -3,6 +3,7 @@ import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { json_value } from '#scripts/lib/json-value'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
+import { git_argv } from './git-argv'
 import { shell_segments } from './shell-segments'
 
 // The trigger and the delivered text behind the `protected-file` row of `delivered-rules.ts`:
@@ -31,25 +32,44 @@ const SETTINGS_FILE = path.join('.claude', 'settings.json')
 const WHITESPACE = /\s+/u
 const TOKEN_QUOTES = /["']/gu
 const INPUT_REDIRECT = '<'
+// Programs that print a named file's bytes, or run them. `cp` and `mv` are deliberately absent: they
+// write rather than print, and `cp .env.example .env` is how a checkout's `.env` is made.
 const SHELL_READERS: ReadonlySet<string> = new Set([
 	'.',
 	'awk',
+	'base64',
 	'bat',
 	'cat',
+	'cmp',
+	'column',
+	'comm',
 	'cut',
+	'diff',
+	'fold',
 	'grep',
 	'head',
+	'hexdump',
+	'jq',
 	'less',
 	'more',
 	'nl',
 	'od',
+	'paste',
+	'perl',
+	'python',
+	'python3',
+	'rev',
 	'rg',
+	'ruby',
 	'sed',
 	'sort',
 	'source',
 	'strings',
+	'tac',
 	'tail',
+	'uniq',
 	'xxd',
+	'yq',
 ])
 
 function file_path_of(call: GuardedCall): string {
@@ -80,15 +100,15 @@ function is_environment_read_segment(segment: string): boolean {
 	const is_redirected = words.some(
 		(word, index) => word === INPUT_REDIRECT && is_environment_path(words[index + 1] ?? ''),
 	)
-	const [command = '', ...rest] = words
+	const call = git_argv.program_of(segment)
 
-	return (
-		is_redirected || (SHELL_READERS.has(command) && rest.some((word) => is_environment_path(word)))
-	)
+	if (is_redirected || call === undefined) return is_redirected
+
+	return SHELL_READERS.has(call.name) && call.args.some((word) => is_environment_path(word))
 }
 
 function is_environment_shell_read(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_environment_read_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_environment_read_segment(segment))
 }
 
 function is_environment_read(call: GuardedCall): boolean {
@@ -130,6 +150,13 @@ const ROW = {
 	decide: (): boolean => true,
 	// The opening the reason carried before it was cut to the action and the next command.
 	former_reasons: ['⛔ protected file: `.env` holds the Telegram bot token'],
+	about: {
+		title: 'Protected file',
+		topic: '`operating-rules.md`',
+		fires:
+			'a `Read` of `.env`, or an `Edit` / `Write` of `.claude/settings.json` outside kit. Every occurrence',
+		quiet: "kit itself, or the user's `~/.claude/settings.json`",
+	},
 }
 
 const protected_files = { ROW, is_protected_file_call }

package/scripts/rules/raw-field-body.ts

@@ -44,6 +44,12 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(posts_at_path_literally),
 	reason: RAW_FIELD_BODY_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Posting `@path` literally',
+		topic: '`shell-body.md`',
+		fires: 'a raw field (`-f` / `--raw-field`) passing `body=@<path>`. Every occurrence',
+		quiet: '`-F` / `--field body=@`, a body without `@`, or `pnpm josh issue:comment`',
+	},
 }
 
 const raw_field_body = { RAW_FIELD_BODY_REASON, ROW, posts_at_path_literally }

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

@@ -178,6 +178,14 @@ const ROW = {
 	reason: RULE_BODY_REASON,
 	already_satisfied: answered_placement,
 	keeps: bash_triggers.on_bash_command(runs_placement_oracle),
+	about: {
+		title: 'Question 0 and the ordering question before writing a rule into prose',
+		topic: '`residency.md`',
+		fires:
+			'an `Edit` / `Write` to `CLAUDE.md` / `prompts/**/*.md` / `.claude/skills/**/*.md` appending at least the threshold. Refused until both `pnpm josh oracle:list` and `pnpm josh run:step` ran',
+		quiet:
+			'not a rule document, an append under the threshold (typo, link swap, deletion), or both commands ran',
+	},
 }
 
 const rule_body_guard = {

package/scripts/rules/rule-list.ts

@@ -2,53 +2,34 @@
 import { fileURLToPath } from 'node:url'
 import { delivered_rules } from './delivered-rules'
 import { guard_remedy } from './guard-remedy'
-import { rule_registry, type RegisteredRule } from './rule-registry'
+import { stop_rule_rows, type StopRule } from './stop-rule-rows'
 
 // `josh rule:list` — the list of trigger-delivered rules, rendered from the guard rows themselves.
 // One item per `MEASURED_RULES` row in delivery order, then the `Stop`
 // hook's rows; each carries its single source, the call it fires on and the turn it stays silent on.
-// The prose is `rule-registry.ts`; the order and the set are `delivered-rules.ts`, so a row added
-// there is listed without a document edit — and a row with no registry entry is listed as missing.
+// The prose is each row's own `about`, so a row added there is listed without a document edit.
 
 const HEADER =
 	'# Trigger-delivered rules — rendered by `pnpm josh rule:list` from `scripts/rules/delivered-rules.ts`'
-const MISSING = '(no entry in `scripts/rules/rule-registry.ts`)'
 const MISSING_WHY = '(no `why` in `scripts/rules/guard-remedy.ts`)'
 
-function item(id: string, rule: RegisteredRule | undefined): string {
-	if (rule === undefined) return `- \`${id}\` ${MISSING}`
-
+function item({ id, about }: StopRule): string {
 	return [
-		`- **${rule.title}** (\`${id}\`, ${rule.topic})`,
-		`  - fires: \`${rule.entry}\` — ${rule.fires}`,
-		`  - silent: ${rule.quiet}`,
+		`- **${about.title}** (\`${id}\`, ${about.topic})`,
+		`  - fires: \`${about.entry ?? delivered_rules.PRETOOL_GUARD}\` — ${about.fires}`,
+		`  - silent: ${about.quiet}`,
 		`  - not automated: ${guard_remedy.why_of(id) ?? MISSING_WHY}`,
 	].join('\n')
 }
 
-function row_ids(): ReadonlyArray<string> {
-	return delivered_rules.MEASURED_RULES.map((rule) => rule.id)
-}
-
 function render(): string {
-	const rows = row_ids().map((id) => item(id, rule_registry.entry_for(id)))
-	const stops = rule_registry.STOP_ROWS.map((rule) => item(rule.id, rule))
-
-	return [HEADER, '', ...rows, ...stops].join('\n')
-}
-
-// Registry entries no guard row reaches — a renamed or removed row left its prose behind.
-function orphans(): ReadonlyArray<string> {
-	const reached = new Set(row_ids().map((id) => rule_registry.registry_id(id)))
-	const stop_ids = new Set(rule_registry.STOP_ROWS.map((rule) => rule.id))
+	const rows = [...delivered_rules.MEASURED_RULES, ...stop_rule_rows.ROWS].map((rule) => item(rule))
 
-	return rule_registry.REGISTERED_RULES.map((rule) => rule.id).filter(
-		(id) => !reached.has(id) && !stop_ids.has(id),
-	)
+	return [HEADER, '', ...rows].join('\n')
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) process.stdout.write(`${render()}\n`)
 
-const rule_list = { MISSING, MISSING_WHY, orphans, render }
+const rule_list = { MISSING_WHY, render }
 
 export { rule_list }

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

@@ -1,7 +1,9 @@
 import { spawn } from 'node:child_process'
-import { mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { statSync } from 'node:fs'
 import path from 'node:path'
+import { atomic_write } from '#scripts/lib/atomic-write'
 import { file_reader } from '#scripts/lib/read-file'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 
 // The `rule:value` reading at the `backlogrun` loop head, without the loop waiting on it.
 // Measuring re-reads every transcript and takes minutes, and `backlog:offer`
@@ -16,12 +18,10 @@ 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
@@ -45,12 +45,7 @@ function is_refresh_due(cwd: string, now_ms: number): boolean {
 }
 
 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)
+	atomic_write.replace_file(cache_path(cwd, file), text)
 }
 
 function ignore_spawn_error(): void {

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

@@ -26,46 +26,62 @@ const UNMEASURED = 'unmeasured'
 // A measurable rule no run reached: the denominator is zero, so no rate is taken over it.
 const UNREACHED = 'unreached'
 
-interface OwnedText {
-	owner: string
-	text: string
-}
-
-function owned_text(file: SessionFile): OwnedText | undefined {
-	const text = cost_transcript.read_optional(file)
-
-	if (text === undefined) return undefined
-
-	return { owner: cost_transcript.owning_session_id(file), text }
-}
-
 // Every transcript grouped by the run it belongs to: a session's own file and the units it delegated
 // share one `owning_session_id`, so a lane child is counted with its parent rather than as a run of
-// its own — the unit `rule_value.measure` reads.
-function group_by_run(files: ReadonlyArray<SessionFile>): Map<string, Array<string>> {
-	const runs = new Map<string, Array<string>>()
+// its own — the unit `rule_value.measure` reads. **Paths only**: no text is read here, so the
+// grouping never holds the corpus.
+function group_by_run(files: ReadonlyArray<SessionFile>): Map<string, Array<SessionFile>> {
+	const runs = new Map<string, Array<SessionFile>>()
 
 	for (const file of files) {
-		const owned = owned_text(file)
-
-		if (owned === undefined) continue
-
-		const texts = runs.get(owned.owner) ?? []
+		const owner = cost_transcript.owning_session_id(file)
+		const owned = runs.get(owner) ?? []
 
-		texts.push(owned.text)
-		runs.set(owned.owner, texts)
+		owned.push(file)
+		runs.set(owner, owned)
 	}
 
 	return runs
 }
 
+function readable_texts(files: ReadonlyArray<SessionFile>): Array<string> {
+	return files
+		.map((file) => cost_transcript.read_optional(file))
+		.filter((text): text is string => text !== undefined)
+}
+
+// **One run read at a time.** Each run's text is read only when `measure` asks for it and released
+// before the next is read, so the peak is the largest run rather than the whole corpus. A run whose
+// every file is unreadable yields nothing, as it was never a measurement target.
+function* runs_of(groups: Iterable<ReadonlyArray<SessionFile>>): Generator<Array<string>> {
+	for (const files of groups) {
+		const texts = readable_texts(files)
+
+		if (texts.length > 0) yield texts
+	}
+}
+
 // Every run reachable from the working tree — the session's own transcript directory and any lane
-// slugs beneath its main checkout — grouped into the shape `rule_value.measure` reads.
-function gather_runs(cwd: string = process.cwd()): Array<Array<string>> {
+// slugs beneath its main checkout — in the shape `rule_value.measure` reads.
+function gather_runs(cwd: string = process.cwd()): Generator<Array<string>> {
 	const directories = cost_transcript.transcript_directories(cwd)
 	const files = cost_transcript.list_sessions_across(directories)
 
-	return [...group_by_run(files).values()]
+	return runs_of(group_by_run(files).values())
+}
+
+interface Tally {
+	runs: number
+}
+
+function* counted(
+	runs: Iterable<ReadonlyArray<string>>,
+	tally: Tally,
+): Generator<ReadonlyArray<string>> {
+	for (const texts of runs) {
+		tally.runs += 1
+		yield texts
+	}
 }
 
 // The id column, wide enough for the longest rule id, so the reading lines up whatever the registry
@@ -94,13 +110,15 @@ function row(reading: RuleReading): string {
 
 // The reading as text, or `NO_TARGETS` when nothing measurable was found — never an empty output that
 // would read as a broken command.
-function render(runs: ReadonlyArray<ReadonlyArray<string>>): string {
-	if (runs.length === 0) return NO_TARGETS
+// The runs are counted as `measure` consumes them, since a lazy source cannot be asked its length
+// up front.
+function render(runs: Iterable<ReadonlyArray<string>>): string {
+	const tally: Tally = { runs: 0 }
+	const readings = rule_value.measure(counted(runs, tally))
+
+	if (tally.runs === 0) return NO_TARGETS
 
-	return rule_value
-		.measure(runs)
-		.map((reading) => row(reading))
-		.join('\n')
+	return readings.map((reading) => row(reading)).join('\n')
 }
 
 // `--refresh` is the detached measurement the `backlogrun` loop head starts: the reading goes to the
@@ -123,6 +141,7 @@ const rule_value_cli = {
 	render,
 	row,
 	run_rule_value,
+	runs_of,
 	NO_TARGETS,
 	UNMEASURED,
 	UNREACHED,

package/scripts/rules/rule-value.ts

@@ -40,7 +40,7 @@ const PERCENT = 100
 // **A refusal is an errored result, which is what separates it from a read of the file it is written
 // in.** Every signature exists verbatim in the module its rule is written in — the six delivered
 // rules in `scripts/rules/delivered-rules.ts`, the batching row's in
-// `scripts/time/time-batch-guard.ts` — so a session that
+// `tools/time/time-batch-guard.ts` — so a session that
 // merely opened that file carries the text too — and did so in a result whose `is_error` is false.
 //
 // **That fact is read off the parsed block, never off the raw line**. The

package/scripts/rules/shell-segments.ts

@@ -16,11 +16,44 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 const SEGMENT_SEPARATOR = /&&|\|\||;|\n/u
 const SEGMENT_PARTS = new RegExp(`(${SEGMENT_SEPARATOR.source})`, 'u')
 
+// **The rows that read a segment as argv cut at the pipe and the background `&` as well.** Their
+// question is which program a segment launches, and `true | git push -f` or `x & git push -f`
+// launches git all the same; a `--jq` fragment cut off by a `|` begins with no program word, so it
+// launches nothing they look for. A `&` that belongs to a redirection (`2>&1`, `&>file`, `<&3`) does
+// not cut.
+const COMMAND_SEPARATOR = /&&|\|\||;|\n|\|&?|(?<![<>])&(?!>)/u
+
 /** The line's commands, trimmed. Empty segments are kept: a caller anchoring at `^` rejects them. */
 function segments_of(command: string): Array<string> {
 	return command.split(SEGMENT_SEPARATOR).map((segment) => segment.trim())
 }
 
+/** The line's commands as separate programs: the `segments_of` cut plus a pipe and a background `&`. */
+function commands_of(command: string): Array<string> {
+	return command.split(COMMAND_SEPARATOR).map((segment) => segment.trim())
+}
+
+const COMMAND_SEPARATORS = new RegExp(COMMAND_SEPARATOR.source, 'gu')
+
+/**
+ * The `commands_of` cut taken where the quote-blanked line puts each separator, so a `|` or `;`
+ * inside a quoted argument does not cut it; a heredoc line falls back to `commands_of`.
+ */
+function quote_aware_commands_of(command: string): Array<string> {
+	const plain = time_shell.blanked(command)
+
+	if (plain === undefined) return commands_of(command)
+
+	const cuts = [...plain.matchAll(COMMAND_SEPARATORS)].map((match) => ({
+		begin: match.index,
+		end: match.index + match[0].length,
+	}))
+	const starts = [0, ...cuts.map((cut) => cut.end)]
+	const stops = cuts.map((cut) => cut.begin)
+
+	return starts.map((start, index) => command.slice(start, stops[index] ?? command.length).trim())
+}
+
 /** The same cut, untrimmed and with each separator kept between its commands, so the parts join back to the line. */
 function parts_of(command: string): Array<string> {
 	return command.split(SEGMENT_PARTS)
@@ -55,9 +88,11 @@ function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
 }
 
 const shell_segments = {
+	commands_of,
 	first_of,
 	is_josh_command,
 	parts_of,
+	quote_aware_commands_of,
 	segments_of,
 }
 

package/scripts/rules/stop-rule-rows.ts

@@ -0,0 +1,64 @@
+import type { DeliveredRule } from './delivered-rules'
+
+// The `Stop` hook's rows; `stop:guard` judges every stop. A row with a fixed answer runs it itself and
+// blocks only when that fails; a row that needs judgement blocks the stop while it holds. They have no
+// guard row, so the listing reads their description from here.
+
+type StopRule = Pick<DeliveredRule, 'about' | 'id'>
+
+const STOP_GUARD = 'pnpm josh stop:guard'
+
+const ROWS: ReadonlyArray<StopRule> = [
+	{
+		id: 'stop-notify',
+		about: {
+			title: 'Stop notification',
+			topic: '`CLAUDE.md` → "Mid-workflow stop notification"',
+			entry: STOP_GUARD,
+			fires:
+				'a stop with the work tree held and no `confirmation` notify that turn. Sends the notify itself; blocks only when the send fails',
+			quiet: 'no hold, a `confirmation` notify on the tail, or a pre-gate cut taken',
+		},
+	},
+	{
+		id: 'hold-release',
+		about: {
+			title: 'Hold release',
+			topic: '`.claude/skills/workflow-commands/working-tree-hold.md`',
+			entry: STOP_GUARD,
+			fires:
+				'a stop on a clean tree with the `run:hold` record still in place. Releases the hold itself; blocks only when that fails',
+			quiet:
+				'a dirty tree (a `halfrun` stop before the commit, a `needs-human-review` stop) or already released',
+		},
+	},
+	{
+		id: 'issue-citation',
+		about: {
+			title: 'Issue citation format',
+			topic: '`prompts/collaboration-workflow/issue-citation.md`',
+			entry: STOP_GUARD,
+			fires:
+				'a bare `#N` in the prose of the last reply. Prints the citation lines itself; blocks only when a number cannot be cited',
+			quiet:
+				'link form, inside code or a quote, `#N` right after `PR`, or a GitHub-facing artifact',
+		},
+	},
+	{
+		id: 'filing-offer',
+		about: {
+			title: 'Offer to file',
+			topic: '`.claude/skills/workflow-commands/observation-filing.md`',
+			entry: STOP_GUARD,
+			fires:
+				'an unattended run (a kit-launched headless session, a lane child, a `backlogrun` parent) whose last reply offers to file without filing. Blocks the stop',
+			quiet:
+				'an interactive session, already filed, inside a fence or quote, a named third-party `owner/repo`, or an unknown owner',
+		},
+	},
+]
+
+const stop_rule_rows = { ROWS }
+
+export type { StopRule }
+export { stop_rule_rows }

package/scripts/rules/stop-rules.ts

@@ -1,4 +1,5 @@
 import { hook_decision } from '#scripts/josh/hook-decision'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { filing_offer } from './filing-offer'
 import { issue_citation } from './issue-citation'
@@ -169,7 +170,7 @@ function build_citation_reason(references: ReadonlyArray<string>): string {
 const FILING_OFFER_REASON =
 	'⛔ filing offer: your reply offers to file an Issue instead of filing it, and this run is ' +
 	'unattended — nobody is there to answer. Run ' +
-	'`pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` (Tier A, ' +
+	'`pnpm josh issue:file "<title>" --body-file <path>` (Tier A, ' +
 	'`observation-filing.md`), then end with the one-line citation of what was filed; do not repeat ' +
 	'your previous reply. If it is not worth filing after all, say so in one line instead.'
 
@@ -447,9 +448,7 @@ function notice_envelope(notice: string): string {
 }
 
 function parse_stop_payload(raw_payload: string): StopPayload | undefined {
-	const parsed = stop_payload_schema.safeParse(JSON.parse(raw_payload))
-
-	return parsed.success ? parsed.data : undefined
+	return json_value.parse_with(raw_payload, stop_payload_schema)
 }
 
 function is_enabled(): boolean {

package/scripts/rules/test-declared-commit.ts

@@ -38,7 +38,17 @@ const REASON =
 // The enumeration row itself, so `delivered-rules.ts` spreads one entry rather than restating the
 // trigger and reason it already single-sources here. Once per run (the default delivery) for the
 // reason above.
-const ROW = { id: 'test-declared', is_trigger: is_untested_commit, reason: REASON }
+const ROW = {
+	id: 'test-declared',
+	is_trigger: is_untested_commit,
+	reason: REASON,
+	about: {
+		title: 'Test declaration',
+		topic: '`CLAUDE.md` → Code Change Rules',
+		fires: '`pnpm josh git -y` (`josh g`) while `pnpm josh test:declared` answers `required`',
+		quiet: '`exempt` (non-runtime only) or `satisfied` (tests included)',
+	},
+}
 
 const test_declared_commit = { REASON, ROW }
 

package/scripts/rules/third-party-write.ts

@@ -117,6 +117,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command((command: string) => writes_third_party(command)),
 	reason: THIRD_PARTY_WRITE_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Third-party write',
+		topic: '`upstream-interrupt.md`',
+		fires:
+			'a `gh api` write (field flag or a write method) to a repository whose owner is not this session. Every occurrence',
+		quiet: 'a read, or a first-party owner (`pnpm josh repo:party`)',
+	},
 }
 
 const third_party_write = {

package/scripts/rules/timed-rerun.ts

@@ -0,0 +1,69 @@
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `timed-rerun` row of `delivered-rules.ts`
+// (joshuafolkken/kit#4356). A lane agent timed a whole-tree `eslint` twice to learn what CI already
+// records, and each run took about 1.3 cores for seven minutes outside the core budget.
+//
+// **The timer is the trigger, not the tool.** What a run is after when it prefixes `time` or reaches
+// for `hyperfine` is a duration, and a duration of CI or of the gate is already on record — the Actions
+// jobs and the lane ledger. The tool under the timer can be anything, so reading the timer is the one
+// trigger that does not have to enumerate them.
+//
+// **Once per run.** The rule allows one re-run when the record cannot answer, so the reissue goes
+// through. On that reissue `lane-direct-tool` still refuses a lane child's `time`-prefixed heavy tool
+// (`git_argv` skips the timer) and points it at `pnpm josh reserved-run`, the overlap
+// `delivered-rules.ts` admits. A `hyperfine "<command>"` carries the tool inside a quoted argument,
+// which `lane-direct-tool` does not read, so in a lane that reissue is not budgeted.
+
+// A segment that opens with a timer, behind any environment assignments: `time`, `/usr/bin/time -p`
+// and `hyperfine`. Anchored at the segment start, so a quoted mention or an argument is not a timer.
+const TIMED_SEGMENT = /^\s*(?:[A-Za-z_]\w*=\S*\s+)*(?:\S*\/)?(?:time|hyperfine)\s/u
+
+function is_timed_run(command: string): boolean {
+	return shell_segments
+		.quote_aware_commands_of(command)
+		.some((segment) => TIMED_SEGMENT.test(segment))
+}
+
+// Reading the record: an Actions run or job listing, or the lane ledger's gate timings.
+const RECORD_READ = /\bgh\s+api\b.*\/actions\/runs\b|\bjosh\s+(?:lane:stats|lst)\b/u
+
+function reads_the_record(command: string): boolean {
+	return RECORD_READ.test(command)
+}
+
+function measures_duration(command: string): boolean {
+	return reads_the_record(command) || is_timed_run(command)
+}
+
+const TIMED_RERUN_REASON =
+	'⛔ timed re-run: a CI or gate duration is already on record — read the Actions jobs with ' +
+	'`gh api …/actions/runs/<run_id>/jobs` or the gate timings with `pnpm josh lane:stats`. Re-run ' +
+	'only when the record cannot answer: reissue the same command once, and post the result on the ' +
+	'Issue (`prompts/collaboration-workflow/measurement.md`).'
+
+// The row itself, so `delivered-rules.ts` spreads one entry; once per run, so the one allowed re-run
+// goes through on the reissue.
+const ROW = {
+	id: 'timed-rerun',
+	is_trigger: bash_triggers.on_bash_command(is_timed_run),
+	reason: TIMED_RERUN_REASON,
+	keeps: bash_triggers.on_bash_command(reads_the_record),
+	reaches: bash_triggers.on_bash_command(measures_duration),
+	about: {
+		title: 'Timed re-run',
+		topic: '`measurement.md`',
+		fires: 'a command timed with `time` / `/usr/bin/time` / `hyperfine`',
+		quiet: 'the duration is read from the Actions jobs or `pnpm josh lane:stats`',
+	},
+}
+
+const timed_rerun = {
+	ROW,
+	TIMED_RERUN_REASON,
+	is_timed_run,
+	reads_the_record,
+}
+
+export { timed_rerun }

package/scripts/rules/worktree-guard.ts

@@ -17,7 +17,9 @@ import { shell_segments } from './shell-segments'
 // that stash findable and poppable by `pnpm josh stash:pop`, which is the whole of `operating-rules.md`'s
 // safety argument; the forms it warns against are the *positional/bare* ones. So `git stash push -m`
 // (with or without `-u`) and the read-only `git stash list` / `show` pass, and everything else — bare
-// `git stash`, a message-less push, `pop` / `apply` / `drop` / `save` / `clear` — is refused.
+// `git stash`, a message-less push, `pop` / `apply` / `drop` / `save` / `clear` — is refused. Those
+// flows now push with `pnpm josh stash:push` (joshuafolkken/kit#4131), invisible here; the raw message
+// form still passes for a procedure written before it.
 //
 // **The refusal names the way on for a handed-over stash.** joshuafolkken/kit#3630's plan restored a
 // stash with `git stash apply`, and the lane parked on how to apply it instead of popping by message;
@@ -117,7 +119,7 @@ function is_unauthorized_segment(segment: string): boolean {
 }
 
 function is_unauthorized_worktree_change(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_unauthorized_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_unauthorized_segment(segment))
 }
 
 // The instruction in the shape a refusal can carry: what the command touches, the authorized route,
@@ -125,7 +127,7 @@ function is_unauthorized_worktree_change(command: string): boolean {
 // invisible to this trigger, so a run that uses them is never refused.
 const WORKTREE_MUTATION_REASON =
 	'⛔ unauthorized working-tree change: `git checkout --`, `git restore`, `git clean -f`, ' +
-	'`git stash`. A documented flow stashes with `git stash push -u -m "<message>"`; a handed-over ' +
+	'`git stash`. A documented flow stashes with `pnpm josh stash:push "<message>"`; a handed-over ' +
 	'stash is `pnpm josh stash:pop "<message>"`; record the substitution on the Issue (Tier A) unless ' +
 	'the plan says why the owner keeps the stash: then stop and confirm. It fires on every occurrence ' +
 	'(`operating-rules.md`).'
@@ -135,6 +137,14 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_unauthorized_worktree_change),
 	reason: WORKTREE_MUTATION_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Unauthorized work-tree mutation',
+		topic: '`operating-rules.md`',
+		fires:
+			'`git checkout -- <path>` / `git restore <path>` / forced `git clean -f` / an unauthorized `git stash` (bare, push without a message, positional pop). Every occurrence',
+		quiet:
+			'`git stash push -m`, `git stash list`, `pnpm josh git`, `pnpm josh stash:push`, `pnpm josh stash:pop`',
+	},
 }
 
 const worktree_guard = {