@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/scripts/rules/piped-verification.ts

@@ -73,20 +73,16 @@ function is_masked_verification(command: string): boolean {
 	return time_shell.discarded_commands(command).some((segment) => is_verification_command(segment))
 }
 
-// The masking, the two ways out of it and the boundary, in the shape a refusal can carry. **The way
+// The masking and the ways out of it, in the shape a refusal can carry; the boundary is the topic file's. **The way
 // out travels with the refusal rather than being named**, because a delivery saying only "do not pipe
 // it" leaves the caller with the same long output and no sanctioned way to read it, which is what put
 // the pipe there in the first place.
 const PIPED_VERIFICATION_REASON =
 	"⛔ piped verification: a pipeline exits with its last command's status, so `pnpm josh gate | " +
-	'tail` reports success on a gate that failed, and the verdict is discarded before anything reads ' +
-	'it. Run the check without the pipe — josh prints its verdict line last, so the harness output cap ' +
-	'keeps it even when the middle is elided. Where the output genuinely has to be narrowed, redirect ' +
-	'it to a file and read ranges from that file, or prefix `set -o pipefail` so the pipeline carries ' +
-	"the check's status. Read the printed verdict either way, never the exit code alone. Read-only " +
-	'listings are untouched — this fires only on a command whose result means pass or fail. The rule ' +
-	'is in `prompts/collaboration-workflow/output-bounds.md`. Reissue this call with no pipe — it ' +
-	'fires once per run and cannot repeat on the call in hand.'
+	'tail` reports success on a gate that failed. Reissue this call with no pipe (josh prints its ' +
+	'verdict last), or redirect it to a file and read ranges from that file, or prefix ' +
+	'`set -o pipefail`; read the verdict line, never the exit code alone ' +
+	'(`prompts/collaboration-workflow/output-bounds.md`).'
 
 // Every command position on the line: the chain cut `shell_segments` makes, each piece of a pipeline
 // inside it taken on its own.
@@ -128,27 +124,37 @@ 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).
 //
-// **Every command on the line is a josh check or a filter after one.** The rewrite answers `allow`, so
-// anything else chained beside the check — `&& rm -r dist`, or a `git log | head` never written for
-// `pipefail` — would skip the permission prompt it would otherwise meet. Those lines are refused as before.
+// **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
+// | tail -5; git status` — so the check's own pipeline becomes `(set -o pipefail; …)` and nothing else
+// on the line is put under a `pipefail` it was not written for (joshuafolkken/kit#3875). The envelope
+// carries no permission decision (`hook_decision.flow_rewrite_envelope`), so whatever else the line runs
+// meets its own permission prompt exactly as the typed call would have.
 //
-// **The raw line is read for what the cut cannot see.** `segments_of` does not split on a lone `&`, and
-// `time_shell.unquoted` blanks a double-quoted `$(…)`, so `| tail & curl …`, `| tail > ~/.zshrc` and
-// `| grep "$(cmd)"` all look like a filter after a check. Any `&`, redirection, backtick or `$(` beyond
-// the `&&` chain and the check's own `2>&1` leaves the line to the refusal.
-const PIPEFAIL_PREFIX = 'set -o pipefail; '
-const FULL_READING_FILTER = /^(?:tail|grep)\b/u
+// **The check's own pipeline is read for what the cut cannot see.** `parts_of` does not split on a lone
+// `&`, so `| tail & curl …`, `| tail > ~/.zshrc` and `| tail -n $(cmd)` look like a filter after a check.
+// Any `&`, redirection, backtick or `$(` there beyond the check's own `2>&1` leaves the line to the
+// refusal, as does a heredoc anywhere on it, whose body lines the cut would read as commands. An
+// unquoted `(` or `)` does too: the cut splits inside a group, so `(cd x && pnpm josh lint) | tail` would
+// wrap the inner check and leave the group's own pipe without `pipefail`.
+const PIPEFAIL_OPEN = '(set -o pipefail; '
+const PIPEFAIL_CLOSE = ')'
+const COMMENT_START = /(?:^|\s)#/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
 
 const ALLOWED_OPERATORS = /2>&1|&&/gu
 const SIDE_EFFECT_SYNTAX = /[&<>`]|\$\(/u
+const GROUP_SYNTAX = /[()]/u
 
 const PIPEFAIL_NOTE =
-	'↻ piped verification: the josh check was piped, so `set -o pipefail;` was prefixed and the call ran ' +
-	"with the check's status carried to the exit code. Read the printed verdict, never the exit code " +
-	'alone — `prompts/collaboration-workflow/output-bounds.md` (joshuafolkken/kit#3570).'
+	'↻ piped verification: the josh check was piped, so its pipeline was wrapped in ' +
+	"`(set -o pipefail; …)` to carry the check's status, and the rest of the line ran as typed. Read " +
+	'the printed verdict, never the exit code alone — `prompts/collaboration-workflow/output-bounds.md`.'
 
 function reads_to_the_end(piece: string): boolean {
 	return FULL_READING_FILTER.test(piece) && !EARLY_EXIT_GREP.test(piece)
@@ -164,23 +170,69 @@ function has_side_effect_syntax(command: string): boolean {
 	return SIDE_EFFECT_SYNTAX.test(command.replaceAll(ALLOWED_OPERATORS, ' '))
 }
 
-function is_pipefail_rewritable(command: string): boolean {
-	return (
-		is_masked_verification(command) &&
-		!has_side_effect_syntax(command) &&
-		pipelines_of(command).every((pipeline) => is_filtered_check(pipeline))
-	)
+// The side-effect syntax is read on the typed part, since a double-quoted `$(cmd)` still runs; the pipe
+// cut and the grouping are read on the blanked one, since a quoted `|` or `(` is text.
+function is_rewritable_part(raw: string, judged: string): boolean {
+	const pipeline = judged.split('|').map((piece) => piece.trim())
+
+	return !has_side_effect_syntax(raw) && !GROUP_SYNTAX.test(judged) && is_filtered_check(pipeline)
+}
+
+// Where the part's code ends: an unquoted `#` opens a comment, which would swallow the closing `)`.
+function code_end(judged: string): number {
+	const comment = COMMENT_START.exec(judged)
+
+	return comment === null ? judged.length : comment.index
+}
+
+// The part with its surrounding whitespace and any trailing comment kept outside the subshell, so the
+// line reads as typed.
+function wrapped(raw: string, judged: string): string {
+	const code = raw.slice(0, code_end(judged))
+	const core = code.trim()
+	const lead = code.slice(0, code.indexOf(core))
+
+	return `${lead}${PIPEFAIL_OPEN}${core}${PIPEFAIL_CLOSE}${raw.slice(lead.length + core.length)}`
+}
+
+// One part of the line as it will run: as typed where it masks nothing, wrapped where it masks a check a
+// wrapper can carry, and `undefined` where it masks one no wrapper can.
+function rewritten_part(raw: string, judged: string): string | undefined {
+	if (!is_masked_verification(judged)) return raw
+
+	return is_rewritable_part(raw, judged) ? wrapped(raw, judged) : undefined
 }
 
-// The call's input with the prefix in front, or `undefined` where the call is not a rewritable masking.
+// The command with every masked check wrapped, judged on the quote-blanked line and cut from the typed
+// one at the same offsets — a `|` inside `grep -E "a|b"` is text, and the typed line keeps its quotes.
+function pipefail_command(command: string): string | undefined {
+	const judged = time_shell.blanked(command)
+
+	if (judged === undefined || !is_masked_verification(command)) return undefined
+
+	const offset = { at: 0 }
+	const parts = shell_segments.parts_of(judged).map((part) => {
+		const raw = command.slice(offset.at, offset.at + part.length)
+
+		offset.at += part.length
+
+		return rewritten_part(raw, part)
+	})
+
+	const rewritten = parts.includes(undefined) ? undefined : parts.join('')
+
+	// A line masked as a whole but in no part wraps nothing, so no note may claim a wrap.
+	return rewritten === command ? undefined : rewritten
+}
+
+// The call's input with each masked check wrapped, or `undefined` where the call is not a rewritable
+// masking.
 function pipefail_input(call: GuardedCall): Record<string, unknown> | undefined {
 	if (call.name !== cost_blocks.BASH_TOOL || !json_value.is_record(call.input)) return undefined
 
-	const command = time_shell.bash_command(call.input)
-
-	if (!is_pipefail_rewritable(command)) return undefined
+	const command = pipefail_command(time_shell.bash_command(call.input))
 
-	return { ...call.input, command: `${PIPEFAIL_PREFIX}${command}` }
+	return command === undefined ? undefined : { ...call.input, command }
 }
 
 const piped_verification = {

package/scripts/rules/poll-loop.ts

@@ -83,25 +83,15 @@ function is_poll_loop(command: string): boolean {
 	return LOOP_KEYWORD.test(plain) && SLEEP_COMMAND.test(plain)
 }
 
-// The instruction in the shape a refusal can carry: what the loop is about to cost, why the command's
-// exit is the thing to wait on, and the one route that delivers that exit. The measurement is named
-// because it is what makes the rule believable — six lanes, about 45 minutes, 13% of their wall clock.
+// The instruction in the shape a refusal can carry: why the command's exit is the thing to wait on,
+// and the one route that delivers that exit. The measurement behind it is in
+// `docs/maintainers/rule-delivery-rationale.md`.
 const POLL_LOOP_REASON =
 	"⛔ output poll loop: this hand-writes a `while`/`until` wait loop over a command's output, a " +
-	'marker file or a process — with a `sleep` or, worse, without one — and the loop does not know ' +
-	'when the command finished. A regex that never matches waits to ' +
-	'the harness block limit; one that matches a mid-run line exits too early — either way the ' +
-	'command exit is not what ends the wait, and each pass spends a full-context round trip ' +
-	'(joshuafolkken/kit#2371 measured about 45 minutes, 13% of six lanes, lost to exactly this). Do ' +
-	'not poll the output file. A command known to take minutes — `pnpm josh gate`, `pnpm josh ' +
-	'followup`, `pnpm josh format` — is started detached from the first with `run_in_background` set, ' +
-	'and the harness re-invokes you when it exits: its completion notification is what ends the wait, ' +
-	'on the task exit rather than a regex or the block limit. So issue the long command in the ' +
-	'background and end the turn — do not arm a loop; the wake-up brings you back. To glance at ' +
-	'interim output, `Read` the output file once, never in a sleep loop. If you are waiting on CI, ' +
-	'`pnpm josh followup` waits on it for you. The procedure is ' +
-	'`.claude/skills/workflow-commands/background-commands.md`, "A command that can take minutes is ' +
-	'issued in the background". **This rule fires on every occurrence, not once per run.**'
+	'marker file or a process, and the loop does not know when the command finished. Issue the long ' +
+	'command with `run_in_background` set and end the turn — its exit re-invokes you; for CI, ' +
+	'`pnpm josh followup` (`.claude/skills/workflow-commands/background-commands.md`). It fires on ' +
+	'every occurrence.'
 
 // The row itself, so `delivered-rules.ts` spreads one entry. `decide` returns true so it refuses every
 // occurrence; it declares no `keeps` — waiting on the task exit is the *absence* of a loop, not a

package/scripts/rules/pre-gate-cut.ts

@@ -133,9 +133,7 @@ function dispatched_issue(state: LaneCutState): string | undefined {
 function uncut_lane_issue(state: LaneCutState): string | undefined {
 	const issue = lane_paths.lane_issue_of(state.directory)
 
-	if (issue === undefined) return undefined
-
-	if (dispatched_issue(state) !== issue) return undefined
+	if (issue === undefined || dispatched_issue(state) !== issue) return undefined
 
 	return state.carried()?.issue === issue ? undefined : issue
 }
@@ -159,26 +157,14 @@ function is_uncut_gate(command: string, state: LaneCutState = current_state()):
 	return warrants_the_cut(state.context_verdict())
 }
 
-// The instruction in the shape a refusal can carry: what the cut is for, what each verdict means, and
-// the reissue sentence every delivery needs. **The verdicts are spelled out rather than pointed at**,
-// because `cut` is the only one that ends the turn and a run told merely to "take the cut" would have
-// to go and read which of the other five leave it holding the run — the same reason the WIP cap's
-// delivery names its three interrupt tests instead of naming the file they live in.
+// The instruction in the shape a refusal can carry: the cut, the one verdict that ends the turn, and
+// the reissue sentence every delivery needs. `cut` is the only verdict that ends the turn, so the
+// refusal says so rather than leaving a run to look up which of the others leave it holding the run.
 const PRE_GATE_CUT_REASON =
 	'⛔ pre-gate cut: this checkout is a lane dispatched for this issue and the gate is the boundary to ' +
-	'cut at, so take the cut before running it. `pnpm josh run:cut <N>` ends this process and ' +
-	'relaunches a fresh one that resumes from the gate, dropping the thinking built up while ' +
-	'implementing rather than carrying it on every later request — joshuafolkken/kit#1839 measured ' +
-	'176K of 204K output riding across that boundary, and joshuafolkken/kit#1864 measured the step ' +
-	'itself firing 0 times in 6 lane children while it was carried as prose. Issue ' +
-	'`pnpm josh run:cut <N>` now, and read the verdict: on `cut`, **end the turn immediately** — the ' +
-	'fresh process owns the run from there and must not be waited for, and **no Telegram is owed** for a cut that resumes itself; on `not-a-lane`, `unready`, ' +
-	'`busy`, `failed` or `unknown`, this process carries the run on and the gate is simply the next ' +
-	'call. Never relaunch a second process after `busy`. This fired because the dispatch mark names ' +
-	'this lane; a person working here carries no mark and sees no refusal, so there is no ' +
-	'human-or-child judgement left to make. The procedure is ' +
-	'`.claude/skills/workflow-commands/pre-gate-cut.md`. Reissue the gate once the cut has answered — ' +
-	'this fires once per run, so it cannot repeat on the call in hand.'
+	'cut at. Issue `pnpm josh run:cut <N>`: on `cut`, end the turn immediately — no Telegram is owed; ' +
+	'on any other verdict (`not-a-lane`, `busy`, …), reissue the gate — this fires once per run ' +
+	'(`.claude/skills/workflow-commands/pre-gate-cut.md`).'
 
 // **The pre-gate cut is two acts, one call apart**, so its `rule:value`
 // denominator is only the runs that reached the boundary: a run that issues the cut's entry check and,

package/scripts/rules/prior-comment-read.ts

@@ -15,20 +15,22 @@ import { tail_commands } from './tail-commands'
 // **It reads comments in the josh spelling too.** `pnpm josh issue:read <N>` prints the body and every
 // comment in one call, so a run that opened an Issue with it has read the comments as surely as one
 // that passed `--comments` — and that spelling is the one the workflow itself reaches for, so leaving
-// it out would refuse the reader that obeyed the rule most directly.
+// it out would refuse the reader that obeyed the rule most directly. **`run:entry <N>` and `run:prep <N>`
+// count the same way**: both print the bundled report that carries the body and every comment, and a
+// run that opened with one was refused for a read it had made (joshuafolkken/kit#3875).
 
 // The path segment `…/issues/<N>` and `…/issues/<N>/comments` both name the Issue in the same capture.
 const ISSUE_PATH_NUMBER = /issues\/(\d+)/gu
 // The positional after `gh issue view`, past any flags that precede it.
 const ISSUE_VIEW_NUMBER = /\bissue\s+view\s+(?:-{1,2}\S+\s+)*(\d+)/u
-// The run of numbers `pnpm josh issue:read` takes as its positional arguments.
-const ISSUE_READ_ARGUMENTS = /\bissue:read\b([\s\d]*)/u
+// The run of numbers a josh comment-reading command takes as its positional arguments.
+const ISSUE_READ_ARGUMENTS = /\b(?:issue:read|run:entry|run:prep)\b([\s\d]*)/u
 
 // A command that prints an Issue's comments: the comments endpoint, `gh issue view … --comments`, or
-// the josh command that reads body and comments together.
+// a josh command that reads body and comments together.
 const COMMENTS_ENDPOINT = /issues\/\d+\/comments\b/u
 const VIEW_WITH_COMMENTS = /\bissue\s+view\b[^\n]*--comments\b/u
-const ISSUE_READ_COMMAND = /\bissue:read\b/u
+const ISSUE_READ_COMMAND = /\b(?:issue:read|run:entry|run:prep)\b/u
 
 function add_issue_read_numbers(command: string, numbers: Set<number>): void {
 	const match = ISSUE_READ_ARGUMENTS.exec(command)

package/scripts/rules/protected-files.ts

@@ -119,21 +119,17 @@ function is_protected_file_call(
 }
 
 const PROTECTED_FILE_REASON =
-	'⛔ protected file: `.env` holds the Telegram bot token, and a `.env.*` variant or `.dev.vars` ' +
-	'holds the same kind of secret, so reading one — with the Read tool or a shell reader such as ' +
-	'`cat` / `grep` / `source` — puts a secret in the transcript — the scripts that need it load it ' +
-	'in their own process (the tracked `.env.example` and `.env.test` stay readable). ' +
-	'`.claude/settings.json` in a ' +
-	'consumer repository is the deny list and the hooks every other rule rests on, so a run must not ' +
-	'rewrite it; `josh sync` owns it, and a change belongs upstream in kit (`CLAUDE.md` → "Route ' +
-	'distributed-doc / config changes upstream to kit"). Leave these files alone, or ask the user. ' +
-	'**This rule fires on every occurrence, not once per run.**'
+	'⛔ protected file: `.env`, a `.env.*` variant and `.dev.vars` hold secrets, and a consumer ' +
+	'`.claude/settings.json` is owned by `josh sync` (a change belongs upstream in kit). Leave these ' +
+	'files alone, or ask the user. It fires on every occurrence.'
 
 const ROW = {
 	id: 'protected-file',
 	is_trigger: is_protected_file_call,
 	reason: PROTECTED_FILE_REASON,
 	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'],
 }
 
 const protected_files = { ROW, is_protected_file_call }

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

@@ -35,13 +35,9 @@ function posts_at_path_literally(command: string): boolean {
 // it reads as unbelievable — the call succeeds and returns a URL while posting the path as text.
 const RAW_FIELD_BODY_REASON =
 	'⛔ literal @path body: this passes `body=@<path>` to `gh api` with a raw field flag (`-f` / ' +
-	'`--raw-field`), which sends the value verbatim — the string `@<path>` is posted as the comment, ' +
-	'not the file it points at. `-F` / `--field` is the flag that reads the file, and the two spellings ' +
-	'differ by one character while `gh` exits 0 and returns a comment URL either way, so the break is ' +
-	'invisible until a person reads the issue (joshuafolkken/kit#2304 lost two park comments this way). ' +
-	'Post an issue or PR comment with `pnpm josh issue:comment <N> --body-file <path>` — the one ' +
-	'spelling, which cannot take the wrong flag. The rule and the safe forms are in ' +
-	'`prompts/collaboration-workflow/shell-body.md`. This rule fires on every occurrence, not once per run.'
+	'`--raw-field`), which posts the string `@<path>` rather than the file. Post the comment with ' +
+	'`pnpm josh issue:comment <N> --body-file <path>`; this rule fires on every occurrence ' +
+	'(`prompts/collaboration-workflow/shell-body.md`).'
 
 const ROW = {
 	id: 'raw-field-body',

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

@@ -131,17 +131,10 @@ function writes_rule_prose(
 // skips, the commands that answer them, and the reissue once they have run.
 const RULE_BODY_REASON =
 	'⛔ rule written into prose: this edit adds rule text to CLAUDE.md, a `prompts/**` doc or a skill ' +
-	'body. Before it lands, run the residency questions the addition skips. A rule whose answer is ' +
-	'computable from mechanically readable inputs should be a decision oracle, not prose — question 0; ' +
-	'`pnpm josh oracle:list` lists the existing oracles a new one joins (single source ' +
-	'`scripts/rules/decision-oracle.ts`). A rule that decides *when* or *in what order* to act belongs ' +
-	'in the run driver, not prose — the ordering question; `pnpm josh run:step` is the state machine a ' +
-	'sequencing rule moves into. Only a rule that is neither — not computable, not ordering — stays ' +
-	'prose, and then as a trigger-plus-pointer line rather than a second copy of its procedure. The ' +
-	'criterion is `prompts/collaboration-workflow/residency.md` (question 0 and the ordering question); ' +
-	'the delivery enumeration is `prompts/collaboration-workflow/rule-delivery.md`. Every such edit is ' +
-	'refused until both commands are on the transcript — run them, confirm the rule can be neither an ' +
-	'oracle nor an ordering step, then reissue this edit.'
+	'body. Answer question 0 (`pnpm josh oracle:list`) and the ordering question (`pnpm josh ' +
+	'run:step`) of `prompts/collaboration-workflow/residency.md`; refused until both commands are on ' +
+	'the transcript, then reissue this as a trigger-plus-pointer line ' +
+	'(`prompts/collaboration-workflow/rule-delivery.md`).'
 
 // The two placement oracles the residency questions name: question 0 is `pnpm josh oracle:list`, the
 // ordering question is `pnpm josh run:step` (its degenerate pre-implementation form `run:next` counts

package/scripts/rules/rule-list.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 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'
 
 // `josh rule:list` — the list of trigger-delivered rules, rendered from the guard rows themselves.
@@ -12,6 +13,7 @@ import { rule_registry, type RegisteredRule } from './rule-registry'
 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}`
@@ -20,6 +22,7 @@ function item(id: string, rule: RegisteredRule | undefined): string {
 		`- **${rule.title}** (\`${id}\`, ${rule.topic})`,
 		`  - fires: \`${rule.entry}\` — ${rule.fires}`,
 		`  - silent: ${rule.quiet}`,
+		`  - not automated: ${guard_remedy.why_of(id) ?? MISSING_WHY}`,
 	].join('\n')
 }
 
@@ -46,6 +49,6 @@ function orphans(): ReadonlyArray<string> {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) process.stdout.write(`${render()}\n`)
 
-const rule_list = { MISSING, orphans, render }
+const rule_list = { MISSING, MISSING_WHY, orphans, render }
 
 export { rule_list }

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

@@ -157,6 +157,16 @@ const GUARD_ROWS: ReadonlyArray<RegisteredRule> = [
 			"a dispatched lane child's `AskUserQuestion`; it hands over the park procedure. Every occurrence",
 		quiet: 'not a lane child, or not an interactive tool',
 	},
+	{
+		id: 'agent-model',
+		title: 'Subagent model named',
+		topic:
+			'`.claude/skills/workflow-commands/delegation.md` → "A `general-purpose` subagent names its model"',
+		entry: RULE_GUARD,
+		fires:
+			'an `Agent` / `Task` call of the `general-purpose` type with no `model`. Every occurrence',
+		quiet: 'a named agent type, or a `model` set',
+	},
 	{
 		id: 'lane-carry-conflict',
 		title: 'Lane child carry commands',

package/scripts/rules/rule-registry.ts

@@ -45,14 +45,16 @@ const MEASURED_ROWS: ReadonlyArray<RegisteredRule> = [
 	},
 ]
 
-// The `Stop` hook's rows; `stop:guard` judges every stop, so each blocks the stop while it holds.
+// 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.
 const STOP_ROWS: ReadonlyArray<RegisteredRule> = [
 	{
 		id: 'stop-notify',
 		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. Blocks the stop',
+		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',
 	},
 	{
@@ -60,7 +62,8 @@ const STOP_ROWS: ReadonlyArray<RegisteredRule> = [
 		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. Blocks the stop',
+		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',
 	},
@@ -70,7 +73,7 @@ const STOP_ROWS: ReadonlyArray<RegisteredRule> = [
 		topic: '`prompts/collaboration-workflow/issue-citation.md`',
 		entry: STOP_GUARD,
 		fires:
-			'a bare `#N` in the prose of the last reply. Blocks the stop until the reply is reissued with the citation fixed',
+			'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',
 	},
 	{

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.ts

@@ -5,6 +5,7 @@ import {
 } from '#scripts/time-runtime/time-transcript-line'
 import { delivered_rules, type MeasuredRule } from './delivered-rules'
 import { hook_context_line } from './hook-context-line'
+import { rule_rewrite } from './rule-rewrite'
 
 // What a rule is worth on the channel that carries it when its delivery has not fired.
 //
@@ -287,7 +288,7 @@ function rewritten_id(text: string): string | undefined {
 	return found?.id
 }
 
-function observe_rewrite(states: Map<string, RuleState>, text: string): void {
+function observe_note(states: Map<string, RuleState>, text: string): void {
 	const id = rewritten_id(text)
 	const state = id === undefined ? undefined : states.get(id)
 
@@ -297,6 +298,11 @@ function observe_rewrite(states: Map<string, RuleState>, text: string): void {
 	state.is_triggered = true
 }
 
+// One line can be rewritten by several rows, whose notes `rule-rewrite.ts` joins into one context.
+function observe_rewrite(states: Map<string, RuleState>, text: string): void {
+	for (const note of text.split(rule_rewrite.NOTE_SEPARATOR)) observe_note(states, note)
+}
+
 function observe_for_rule(
 	rule: MeasuredRule,
 	state: RuleState,

package/scripts/rules/run-tail-rule.ts

@@ -137,30 +137,14 @@ function decide(): boolean {
 	return true
 }
 
-// The instruction in the shape a refusal can carry: what the call is about to cost, the reissue that
-// avoids it, and the half a run forgets once the push has landed. The measurement is named because it
-// is what makes the rule believable — the work was 17 minutes and the run was 45.
+// The instruction in the shape a refusal can carry: the reissue, and the half a run forgets once the
+// push has landed. The measurement behind it is in `docs/maintainers/rule-delivery-rationale.md`.
 const RUN_TAIL_REASON =
 	'⛔ run tail: this issues the commit-push-PR step in the foreground, where the harness decides ' +
-	'when to stop waiting. Reissue it with `run_in_background` set. In `fullrun #1501` this call was ' +
-	'given a 900-second timeout, the harness detached it at its own 600-second cap, and nothing read ' +
-	'the output for a further 6m28s — 45m03s of wall clock on about 17 minutes of work ' +
-	'(joshuafolkken/kit#1510). **Never give a foreground call a timeout above the harness cap**: the ' +
-	'cap decides, not the number. A backgrounded call re-invokes you when it exits, so the completion ' +
-	'notification is what resumes the run. **When it arrives, the turn that reads it goes straight ' +
-	'through any branch-2 filing and `pnpm josh epic:bundle` to `pnpm josh followup` — the turn never ' +
-	'ends at the push.** CI went green 6m06s before the merge started in that run, and it started ' +
-	'only because the person asked; joshuafolkken/kit#1333 had already settled that the merge is ' +
-	'issued in the turn the review closes. While the push runs, do the work that writes nothing — ' +
-	'drafting the completion body to a file, deciding the branch-2 disposition. `pnpm josh followup` ' +
-	'itself stays in the **foreground** — nearly every step after it reads its result. But a tail ' +
-	'does follow the merge, measured at 3.0 min and 5.9% of a run (joshuafolkken/kit#1462), so ' +
-	'empty it beforehand: the steps that read the merge result stay after `followup`, and the rest ' +
-	'are composed in the turn that issues it, bar the one exception background-commands.md names. The ' +
-	'procedure is `.claude/skills/workflow-commands/background-commands.md`, "A command that can take ' +
-	'minutes is issued in the background". **This rule fires on every foreground push, not once per ' +
-	'run**, so ' +
-	'reissuing the same call in the foreground will be refused again.'
+	'when to stop waiting. Reissue it with `run_in_background` set; when it exits, go straight on to ' +
+	'`pnpm josh followup` in the foreground — the turn never ends at the push ' +
+	'(`.claude/skills/workflow-commands/background-commands.md`). It fires on every foreground push, ' +
+	'not once per run.'
 
 const run_tail_rule = {
 	RUN_TAIL_REASON,