@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/rules/last-prompt.ts

@@ -30,10 +30,13 @@ const KEYWORD_BEFORE_ARGUMENT = -2
 
 const PROMPT_LINE_SCHEMA = z.object({
 	isMeta: z.boolean().nullish(),
+	timestamp: z.string().nullish(),
 	origin: z.object({ kind: z.string().nullish() }).nullish(),
 	message: z.object({ content: z.unknown() }),
 })
 
+const TIMED_LINE_SCHEMA = z.object({ timestamp: z.string() })
+
 type PromptLine = z.infer<typeof PROMPT_LINE_SCHEMA>
 
 function is_person(line: PromptLine): boolean {
@@ -42,13 +45,20 @@ function is_person(line: PromptLine): boolean {
 	return line.origin === null || line.origin === undefined || line.origin.kind === HUMAN_ORIGIN
 }
 
-// The prompt line's text, or `undefined` when the harness wrote it or it does not read as one.
-function person_text(line: string): string | undefined {
+// The prompt line as the person wrote it, or `undefined` when the harness wrote it or it does not
+// read as one.
+function person_line(line: string): PromptLine | undefined {
 	const parsed = PROMPT_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
 
-	if (!parsed.success || !is_person(parsed.data)) return undefined
+	return parsed.success && is_person(parsed.data) ? parsed.data : undefined
+}
 
-	return time_reported_failure.result_text(parsed.data.message.content)
+// The prompt line's text, or `undefined` when the harness wrote it or it does not read as one.
+function person_text(line: string): string | undefined {
+	const person = person_line(line)
+	if (person === undefined) return undefined
+
+	return time_reported_failure.result_text(person.message.content)
 }
 
 // A keyword opening the prompt is what a person types; a keyword before its one trailing argument is a
@@ -75,6 +85,41 @@ function prompt_text(tail: string): string {
 	return text === undefined || is_invocation(text) ? NO_PROMPT : text
 }
 
-const last_prompt = { prompt_text }
+// **The prompt that opened this turn, when a person typed it** — '' when the harness opened it (a task
+// notification, a subagent's hand-back), so a question asked turns ago does not answer for a stop the
+// run reached on its own since (`stop-decision.ts` → `is_question`).
+function turn_prompt(tail: string): string {
+	const opener = tail.split('\n').findLast((line) => filing_cap.is_prompt_line(line))
+	if (opener === undefined) return NO_PROMPT
+
+	return person_text(opener) ?? NO_PROMPT
+}
+
+// When the person last prompted on the tail, or `undefined` when no prompt of theirs is on it.
+function prompt_time(tail: string): string | undefined {
+	return tail
+		.split('\n')
+		.filter((line) => filing_cap.is_prompt_line(line))
+		.map((line) => person_line(line)?.timestamp ?? undefined)
+		.findLast((time) => time !== undefined)
+}
+
+// The first dated line on the tail, or `undefined` when none is.
+function tail_time(tail: string): string | undefined {
+	return tail
+		.split('\n')
+		.map((line) => TIMED_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line)).data?.timestamp)
+		.find((time) => time !== undefined)
+}
+
+// **When the current pause began, as far as the tail shows** — what a recorded notify is compared
+// against. A person's prompt ends the pause it reported, so the last one opens the next; with none on
+// the tail, only a send dated inside the tail is provably after every prompt, and an older send is
+// announced again (joshuafolkken/kit#3961).
+function pause_start(tail: string): string | undefined {
+	return prompt_time(tail) ?? tail_time(tail)
+}
+
+const last_prompt = { pause_start, prompt_text, turn_prompt }
 
 export { last_prompt }

package/scripts/rules/oracle-consulted.ts

@@ -55,6 +55,15 @@ function reason_for(oracle: Oracle, firing_point: FiringPoint): string {
 	)
 }
 
+// One description for every generated row: the rule is the same act whichever oracle it names.
+const ABOUT: DeliveredRule['about'] = {
+	title: 'An act its oracle was not asked about',
+	topic: '`decision-oracle.ts`',
+	fires:
+		'a `Bash` governed by an oracle that declared a firing point (`pkg:scout` governs `pnpm add`), issued without that `pnpm josh <command>`. Refused until it ran',
+	quiet: 'no governed act, or the oracle already ran',
+}
+
 function row_for(oracle: Oracle, firing_point: FiringPoint): DeliveredRule {
 	const names = command_names(oracle)
 
@@ -65,6 +74,7 @@ function row_for(oracle: Oracle, firing_point: FiringPoint): DeliveredRule {
 		already_satisfied: (tail: string, _call: GuardedCall): boolean =>
 			tail_commands.prior_bash_commands(tail).some((command) => runs_the_oracle(command, names)),
 		keeps: bash_triggers.on_bash_command((command: string) => runs_the_oracle(command, names)),
+		about: ABOUT,
 	}
 }
 

package/scripts/rules/oracle-firing.ts

@@ -90,6 +90,7 @@ const NOT_NAMED: ReadonlyMap<string, string> = new Map([
 	['run:cut:gate', SELF],
 	['backlog:budget', READ],
 	['run:liveness', READ],
+	['stash:push', SELF],
 	['stash:pop', SELF],
 	['backlog:next', READ],
 	['auto-ok:next', READ],

package/scripts/rules/oracle-list-cli.ts

@@ -12,6 +12,10 @@ import { oracle_firing } from './oracle-firing'
 const ARGV_OFFSET = 2
 const INDENT = '  '
 const FIELD_WIDTH = 10
+// The rule-prose guard sends a rule author here first, so the list closes on the placement order a new
+// rule is weighed against before it becomes a guard or a document line.
+const AUTOMATION_ORDER =
+	'automate first: a command > a hook that runs it > a refusal guard > a document — a lower rung states why the higher cannot hold (`principles.md` → "automate-first"; a guard\'s `why` is `scripts/rules/guard-remedy.ts`)'
 
 function pad_field(label: string): string {
 	return label.padEnd(FIELD_WIDTH)
@@ -51,6 +55,8 @@ function print_list(): void {
 	for (const oracle of decision_oracle.DECISION_ORACLES) {
 		console.info(format_oracle(oracle))
 	}
+
+	console.info(AUTOMATION_ORDER)
 }
 
 function run(argv: ReadonlyArray<string>): number {
@@ -70,6 +76,7 @@ function main(argv: ReadonlyArray<string>): void {
 }
 
 const oracle_list_cli = {
+	AUTOMATION_ORDER,
 	print_list,
 }
 

package/scripts/rules/permission-guards.ts

@@ -1,6 +1,7 @@
 import { destructive_command } from './destructive-command'
 import { direct_pr_create } from './direct-pr-create'
 import { index_guard } from './index-guard'
+import { pr_merge } from './pr-merge'
 import { protected_files } from './protected-files'
 
 // The three rows that close the deny-list bypasses, gathered so
@@ -10,11 +11,13 @@ import { protected_files } from './protected-files'
 // other row's — `git restore` is split with `worktree-mutation` by `--staged` alone. The fourth row,
 // `direct-pr-create`, closes the same kind of gap for `gh pr create`, which
 // the deny list never listed: it claims `gh pr create` and a `gh api` write to the pulls collection.
+// The fifth, `pr-merge`, claims a merge in every spelling the `gh pr merge*` glob misses.
 const ROWS = [
 	index_guard.ROW,
 	destructive_command.ROW,
 	protected_files.ROW,
 	direct_pr_create.ROW,
+	pr_merge.ROW,
 ] as const
 
 const permission_guards = { ROWS }

package/scripts/rules/piped-verification.ts

@@ -16,7 +16,7 @@ import { shell_segments } from './shell-segments'
 // document, prompt and skill in this repository found exactly one piped verification example, and it
 // was the repository's own explanation of this bug — so there were no examples to rewrite, and the
 // pipe is invented each time rather than copied. The other candidate, a calling convention, had
-// already been rejected in writing by `scripts/time/time-reported-failure.ts`: a convention is obeyed
+// already been rejected in writing by `tools/time/time-reported-failure.ts`: a convention is obeyed
 // or it is not. `prompts/collaboration-workflow/output-bounds.md` is the single source for the rule.
 //
 // It lives beside the enumeration rather than inside it because `delivered-rules.ts` is the list —
@@ -124,6 +124,8 @@ function keeps_verdict_intact(command: string): boolean {
 // **Only a filter that reads its input to the end qualifies.** One that exits early — `head`, or a
 // `grep` stopping at its first match — closes the pipe on a check still writing, and under `pipefail` the
 // check's SIGPIPE turns a passing run into exit 141; `head` also cuts the verdict line josh prints last.
+// `cut`, `sort`, `uniq` and `wc` read to the end as well, and a `grep … | cut -c1-250` narrowing was the
+// commonest masking still refused after #3875 (joshuafolkken/kit#3920).
 //
 // **Each masked check is wrapped on its own, and the rest of the line runs as typed.** Most of the
 // refusals left after #3570 were a check chained beside other work — `vitest …; pnpm josh lint:related
@@ -141,7 +143,7 @@ function keeps_verdict_intact(command: string): boolean {
 const PIPEFAIL_OPEN = '(set -o pipefail; '
 const PIPEFAIL_CLOSE = ')'
 const COMMENT_START = /(?:^|\s)#/u
-const FULL_READING_FILTER = /^(?:tail|grep)\b/u
+const FULL_READING_FILTER = /^(?:tail|grep|cut|sort|uniq|wc)\b/u
 const EARLY_EXIT_GREP =
 	/^grep\b.*\s(?:-[a-zA-Z]*[lLmq]|--(?:quiet|silent|max-count|files-with(?:out)?-match))/u
 

package/scripts/rules/poll-loop.ts

@@ -102,6 +102,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_poll_loop),
 	reason: POLL_LOOP_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Output poll loop',
+		topic: '`.claude/skills/workflow-commands/background-commands.md`',
+		fires:
+			"a hand-written `while` / `until` wait loop over a command's output, a marker file or a process. Every occurrence",
+		quiet: 'the command started with `run_in_background` — its exit ends the wait',
+	},
 }
 
 const poll_loop = {

package/scripts/rules/pr-merge.ts

@@ -0,0 +1,123 @@
+import { bash_triggers } from './bash-triggers'
+import { direct_pr_create } from './direct-pr-create'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `pr-merge` row of `delivered-rules.ts`: a pull
+// request merged by the agent's own `Bash` call. A merge is Tier C, and the one authorized route is
+// `pnpm josh followup` (and `pnpm josh observations:flush`), which merges inside its own process —
+// the word after the wrapper is `josh`, so neither is claimed here.
+//
+// **The deny list matches globs; this reads the program.** `Bash(gh pr merge*)` and
+// `Bash(gh api *pulls/*/merge*)` miss `curl -X PUT …/pulls/5/merge`, a GraphQL body read from a file
+// (`gh api graphql -F query=@merge.graphql`), and `enablePullRequestAutoMerge`, which merges once
+// the checks pass. A body kept in a file or computed by the shell cannot be read here, so such a
+// GraphQL call is refused whatever it holds — kit's own GitHub calls are REST (`gh-rest.md`).
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does.
+
+const GH_COMMAND = 'gh'
+const CURL_COMMAND = 'curl'
+const PR_GROUP = 'pr'
+const MERGE_ACTION = 'merge'
+const API_SUBCOMMAND = 'api'
+const GRAPHQL_ENDPOINT = 'graphql'
+// The REST merge endpoint, in any spelling of the number (`5`, `$N`, `${PR}`).
+const MERGE_PATH = /pulls\/[^/\s'"]+\/merge(?![\w-])/u
+const MERGE_MUTATIONS = /\b(?:mergePullRequest|enablePullRequestAutoMerge)\b/u
+const GRAPHQL_URL = /\/graphql\b/u
+// A body read from a file or stdin: `@file` / `field=@file` for `gh api -F` and curl's `-d`, a
+// short flag with the value attached (`-d@file`), and the flags that upload a whole file.
+const FILE_BODY_VALUE = /^(?:-[A-Za-z]|[^=\s]*=)?['"]?@/u
+const FILE_BODY_FLAGS: ReadonlySet<string> = new Set(['--input', '-T', '--upload-file'])
+// A body the shell computes (`query="$(cat merge.graphql)"`, backticks) is no more readable here.
+const SUBSTITUTED_BODY = /\$\(|`/u
+
+type ApiCall = NonNullable<ReturnType<typeof git_argv.program_of>>
+
+// The words that are neither a flag nor a flag's value, with `gh api`'s value-taking flags, so
+// `gh api -X POST graphql` reaches `graphql` as the endpoint.
+function positional_words(args: ReadonlyArray<string>): Array<string> {
+	return direct_pr_create.positional_words(args, direct_pr_create.API_VALUE_TAKING_FLAGS)
+}
+
+function is_pr_merge_cli_call(args: ReadonlyArray<string>): boolean {
+	const [group, action] = positional_words(args)
+
+	return group === PR_GROUP && action === MERGE_ACTION
+}
+
+function is_github_api_call(name: string, args: ReadonlyArray<string>): boolean {
+	if (name === CURL_COMMAND) return true
+
+	return name === GH_COMMAND && positional_words(args)[0] === API_SUBCOMMAND
+}
+
+// `gh api` reaches GraphQL through its `graphql` endpoint or, like curl, through the `/graphql` path
+// or URL (`gh api /graphql --input body.json`).
+function is_graphql_call(name: string, args: ReadonlyArray<string>): boolean {
+	if (args.some((argument) => GRAPHQL_URL.test(argument))) return true
+
+	return name === GH_COMMAND && positional_words(args)[1] === GRAPHQL_ENDPOINT
+}
+
+function is_unreadable_body(argument: string): boolean {
+	if (FILE_BODY_FLAGS.has(argument)) return true
+
+	return FILE_BODY_VALUE.test(argument) || SUBSTITUTED_BODY.test(argument)
+}
+
+// The segment cut ignores quotes, so a multi-line `-f query='mutation {⏎ mergePullRequest…'` leaves
+// the mutation name in a later segment: a GraphQL call's mutation is looked for in the whole line.
+function is_graphql_merge(command: string, name: string, args: ReadonlyArray<string>): boolean {
+	if (!is_graphql_call(name, args)) return false
+
+	return MERGE_MUTATIONS.test(command) || args.some((argument) => is_unreadable_body(argument))
+}
+
+function is_api_merge(command: string, segment: string, call: ApiCall): boolean {
+	if (MERGE_PATH.test(segment) || MERGE_MUTATIONS.test(segment)) return true
+
+	return is_graphql_merge(command, call.name, call.args)
+}
+
+function is_pr_merge_segment(command: string, segment: string): boolean {
+	const call = git_argv.program_of(segment)
+
+	if (call === undefined) return false
+	if (call.name === GH_COMMAND && is_pr_merge_cli_call(call.args)) return true
+
+	return is_github_api_call(call.name, call.args) && is_api_merge(command, segment, call)
+}
+
+function is_pr_merge(command: string): boolean {
+	return shell_segments
+		.commands_of(command)
+		.some((segment) => is_pr_merge_segment(command, segment))
+}
+
+const PR_MERGE_REASON =
+	'⛔ direct PR merge: `gh pr merge`, a `gh api` / `curl` call to `…/pulls/<N>/merge`, a ' +
+	'`mergePullRequest` / `enablePullRequestAutoMerge` mutation, or a GraphQL body read from a file ' +
+	'merges outside the verified route, and a merge is Tier C. Merge with `pnpm josh followup` when the ' +
+	'run authorizes it; otherwise leave it to the user (`CLAUDE.md` → Git Rules). This rule fires on ' +
+	'every occurrence.'
+
+const ROW = {
+	id: 'pr-merge',
+	is_trigger: bash_triggers.on_bash_command(is_pr_merge),
+	reason: PR_MERGE_REASON,
+	decide: (): boolean => true,
+	about: {
+		title: 'Direct PR merge',
+		topic: '`CLAUDE.md` → Git Rules',
+		fires:
+			'`gh pr merge`, a `gh api` / `curl` call to `…/pulls/<N>/merge`, a `mergePullRequest` / `enablePullRequestAutoMerge` mutation, or a GraphQL body read from a file. Every occurrence',
+		quiet:
+			'`pnpm josh followup` and `pnpm josh observations:flush`, which merge in their own process',
+	},
+}
+
+const pr_merge = { PR_MERGE_REASON, ROW, is_pr_merge }
+
+export { pr_merge }

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

@@ -1,51 +1,35 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { delivered_rules } from './delivered-rules'
-import { rule_registry, type RegisteredRule } from './rule-registry'
+import { guard_remedy } from './guard-remedy'
+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`)'
-
-function item(id: string, rule: RegisteredRule | undefined): string {
-	if (rule === undefined) return `- \`${id}\` ${MISSING}`
+const MISSING_WHY = '(no `why` in `scripts/rules/guard-remedy.ts`)'
 
+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, orphans, render }
+const rule_list = { MISSING_WHY, render }
 
 export { rule_list }

package/scripts/rules/rule-rewrite.ts

@@ -0,0 +1,114 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { json_value } from '#scripts/lib/json-value'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
+import { delivered_rules, type DeliveredRule } from './delivered-rules'
+import { guard_remedy } from './guard-remedy'
+
+// The call a `PreToolUse` hook runs in place of a mechanically fixable refusal (joshuafolkken/kit#3920).
+// Each row `guard-remedy.ts` classes as a rewrite gets the call in turn, so one line that both pipes a
+// check and reads a body is made right by both rows. The rewrite is the rule guard's delivery, so the
+// rule guard's switch turns it off too.
+
+interface RuleRewrite {
+	// The payload carrying the rewritten input, which the guards judge in place of the typed one.
+	payload: string
+	input: Record<string, unknown>
+	// The notes of the rows that rewrote, in row order.
+	note: string
+}
+
+interface Folded {
+	input: Record<string, unknown>
+	notes: ReadonlyArray<string>
+}
+
+const REWRITING_RULES: ReadonlyArray<DeliveredRule> = delivered_rules.DELIVERED_RULES.filter(
+	(rule) => guard_remedy.is_rewrite(rule.id) && rule.rewrite !== undefined,
+)
+
+const NOTE_SEPARATOR = '\n\n'
+
+// **A tail that cannot be read is an empty one**, as every guard fails open (`hook-decision.ts`): a
+// throw here would end the hook before any guard judged the call.
+function read_payload_tail(raw_payload: string): string {
+	try {
+		const payload = hook_decision.parse_hook_payload(raw_payload)
+
+		return payload
+			? time_density_hook.read_tail(
+					time_hook_transcript.transcript_of(payload.transcript_path, payload.agent_id),
+				)
+			: ''
+	} catch {
+		return ''
+	}
+}
+
+function tail_reader(raw_payload: string): () => string {
+	const cache: { tail?: string } = {}
+
+	return function tail(): string {
+		cache.tail ??= read_payload_tail(raw_payload)
+
+		return cache.tail
+	}
+}
+
+function fold(name: string, typed: Record<string, unknown>, tail: () => string): Folded {
+	const folded: Folded = { input: typed, notes: [] }
+
+	for (const rule of REWRITING_RULES) {
+		const input = rule.rewrite?.({ name, input: folded.input }, tail)
+
+		if (input === undefined) {
+			continue
+		}
+
+		folded.input = input
+		folded.notes = [...folded.notes, rule.rewrite_note ?? '']
+	}
+
+	return folded
+}
+
+// The typed call, beside the whole payload its rewrite is spread back into.
+interface TypedPayload {
+	fields: Record<string, unknown>
+	name: string
+	input: Record<string, unknown>
+}
+
+function typed_payload(raw_payload: string): TypedPayload | undefined {
+	const fields = json_value.parse_or_undefined(raw_payload)
+
+	if (!json_value.is_record(fields)) return undefined
+
+	const input = fields['tool_input']
+
+	return json_value.is_record(input)
+		? { fields, name: String(fields['tool_name']), input }
+		: undefined
+}
+
+function rewrite(raw_payload: string): RuleRewrite | undefined {
+	const typed = delivered_rules.is_enabled() ? typed_payload(raw_payload) : undefined
+
+	if (typed === undefined) return undefined
+
+	const { input, notes } = fold(typed.name, typed.input, tail_reader(raw_payload))
+
+	if (notes.length === 0) return undefined
+
+	const note = notes.join(NOTE_SEPARATOR)
+
+	return { payload: JSON.stringify({ ...typed.fields, tool_input: input }), input, note }
+}
+
+const rule_rewrite = {
+	NOTE_SEPARATOR,
+	rewrite,
+}
+
+export type { RuleRewrite }
+export { rule_rewrite }

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 {