@joshuafolkken/kit 1.1455.0 → 1.1471.0

package/scripts/rules/lane-switch-main.ts

@@ -61,8 +61,12 @@ const FLAG_PREFIX = '-'
 function switch_target(segment: string): string | undefined {
 	const call = git_argv.parse(segment)
 
-	if (call?.subcommand !== SWITCH_SUBCOMMAND) return undefined
-	if (call.args.some((argument) => NON_COLLIDING_FLAGS.has(argument))) return undefined
+	if (
+		call?.subcommand !== SWITCH_SUBCOMMAND ||
+		call.args.some((argument) => NON_COLLIDING_FLAGS.has(argument))
+	) {
+		return undefined
+	}
 
 	return call.args.find((argument) => !argument.startsWith(FLAG_PREFIX))
 }
@@ -103,16 +107,9 @@ function is_switch_away_from_lane(
 // prohibits. Apostrophes are avoided so the single-quoted literal needs no escaping, as the siblings do.
 const LANE_SWITCH_MAIN_REASON =
 	'⛔ lane child on `git switch main`: this session is a dispatched lane child, and switching to the ' +
-	'default branch here always fails — a lane is a linked work tree, the primary checkout holds the ' +
-	'default branch, and git allows one branch in one work tree at a time (`fatal: main is already used ' +
-	'by worktree at <the primary checkout>`, measured 11 times in the 2026-09-21 backlogrun). Do not ' +
-	'switch: the lane is already on its own issue branch, branched from a fresh default before it opened, ' +
-	'and the latest default is brought in during the gate by `pnpm josh main:merge`. So skip this step ' +
-	'and keep implementing on the current branch — no `git switch`, no `git pull`. `pnpm josh main:sync` ' +
-	'(`josh ms`) is refused in a lane for the same reason, and a lane is finished with `pnpm josh ' +
-	'lane:close <issue-number>`. The parent runs `pnpm josh ms` in the primary checkout ' +
-	'before each lane opens, never the child — `backlogrun-lanes.md` and `backlogrun-child.md` are the ' +
-	'single sources. This rule fires on every occurrence, not once per run.'
+	'default branch here always fails (`already used by worktree`: the primary checkout holds it). Skip ' +
+	'this step and keep implementing on the current branch; `pnpm josh main:merge` brings the default ' +
+	'in during the gate. Refused on every occurrence (`backlogrun-lanes.md`, `backlogrun-child.md`).'
 
 // The row itself, so `delivered-rules.ts` spreads one entry. `is_trigger` reads the input through
 // `on_bash_command` — the `Bash` tool-name gate every command row shares — and `decide` returns true so

package/scripts/rules/oracle-consulted.ts

@@ -48,11 +48,10 @@ function command_line(oracle: Oracle): string {
 // the single source of the procedure.
 function reason_for(oracle: Oracle, firing_point: FiringPoint): string {
 	return (
-		`⛔ decision oracle not consulted: this is ${firing_point.describes}, but the run has not run ` +
-		`\`${command_line(oracle)}\` first — the oracle that decides ${oracle.decision.toLowerCase()}. ` +
-		`It answers ${oracle.vocabulary.join(' | ')}; single source ${oracle.single_source}. Reissue ` +
-		`after running it and reading its verdict. Every such call is refused until that command is on ` +
-		`the transcript.`
+		`⛔ decision oracle not consulted: this is ${firing_point.describes}. Run ` +
+		`\`${command_line(oracle)}\` first — it decides ${oracle.decision.toLowerCase()} and answers ` +
+		`${oracle.vocabulary.join(' | ')} (${oracle.single_source}). Every such call is refused until ` +
+		`that command is on the transcript.`
 	)
 }
 

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.
@@ -129,26 +125,34 @@ function keeps_verdict_intact(command: string): boolean {
 // `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.
 //
-// **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; '
+// **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)\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 +168,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/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,

package/scripts/rules/shell-body-trigger.ts

@@ -187,12 +187,10 @@ function carries_a_body(command: string): boolean {
 // (`git-force.ts`, `lane-carry-conflict.ts`).
 const SHELL_BODY_REASON =
 	'⛔ shell-evaluated body: this command carries a body inline in double quotes, and that body ' +
-	'contains a backtick or a `$`, so the shell runs it — the text is executed rather than merely ' +
-	'mangled (joshuafolkken/kit#1198). Write the body to a file and pass it by path: `pnpm josh ' +
-	'issue:comment <N> --body-file <path>`, `pnpm josh followup --notify-message-file <path>`, or ' +
-	"`--body-file <path>` wherever offered. `$'…'` quoting is the other safe form; the rule and the " +
-	"trigger's blind spots are in `prompts/collaboration-workflow/shell-body.md`. Reissue this call " +
-	'once the body is in a file — it fires once per run and cannot repeat on the call in hand.'
+	'contains a backtick or a `$`, so the shell executes it. Reissue this call once the body is in a ' +
+	'file, passed by path (`pnpm josh issue:comment <N> --body-file <path>`, ' +
+	"`--notify-message-file <path>`), or use `$'…'` quoting " +
+	'(`prompts/collaboration-workflow/shell-body.md`).'
 
 const shell_body_trigger = {
 	SHELL_BODY_REASON,

package/scripts/rules/shell-segments.ts

@@ -14,12 +14,18 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 // because `sleep 1200 &` is an armed timer sent to the background and has to be seen as one. That is
 // a different question about a different character, not a second copy of this answer.
 const SEGMENT_SEPARATOR = /&&|\|\||;|\n/u
+const SEGMENT_PARTS = new RegExp(`(${SEGMENT_SEPARATOR.source})`, '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 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)
+}
+
 // **Both spellings match, and the expansion is not this file's.** `josh_command_of` expands the alias
 // in the command it reads, so `pnpm josh ga` arrives as `josh gate` and a caller's canonical set
 // matches it as it is. Widening as well would be a second copy of one rule, and the caller that
@@ -36,6 +42,7 @@ function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
 
 const shell_segments = {
 	is_josh_command,
+	parts_of,
 	segments_of,
 }
 

package/scripts/rules/stop-rules.ts

@@ -101,25 +101,19 @@ const NO_OUTCOME: StopOutcome = { reason: undefined }
 // mid-workflow, and the transcript is what says the notify was sent.
 const STOP_NOTIFY_REASON =
 	'⛔ mid-workflow stop notification: this working tree is still held by a run and no `confirmation` ' +
-	'Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run ' +
-	'paused. `CLAUDE.md` → "Mid-workflow stop notification" requires ' +
+	'Telegram was sent this turn. Send ' +
 	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\' ' +
-	'--recommended "<choice>" --alternative "<choice>"` before any ' +
-	'mid-workflow pause. Send it, then end with a one-line confirmation that it was sent — do not repeat ' +
-	'your previous reply. This fires only while the hold is held and no notify is on the transcript, and ' +
-	'`stop_hook_active` lets a second stop through so a run is never wedged.'
+	'--recommended "<choice>" --alternative "<choice>"` (`CLAUDE.md` → "Mid-workflow stop ' +
+	'notification"), then confirm in one line that it was sent — do not repeat your previous reply.'
 
 // **A clean tree that still holds is a tree the next run will trample.** `working-tree-hold.md`: a stop that
 // leaves the tree clean releases the hold; a `halfrun` pre-commit stop and a `needs-human-review` stop
 // keep it because their tree is dirty, which is why this row is silent whenever the tree is not clean.
 const HOLD_RELEASE_REASON =
 	'⛔ working-tree hold not released: this working tree is clean but its `run:hold` record is still in ' +
-	'place, so the next run here runs `pnpm josh ms` believing the tree is free while ' +
-	'you hold it. The workflow-commands skill → `working-tree-hold.md`: a stop that leaves the tree clean ' +
-	'releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` ' +
-	'pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a ' +
-	'`prrun` stop keeps it by its stop mark — this row is silent there. Release it, then end with a one-line confirmation that it was released — do ' +
-	'not repeat your previous reply.'
+	'place. Release it with `pnpm josh run:release <N>` (bare for a `new` entry; ' +
+	'`working-tree-hold.md`), then confirm in one line that it was released — do not repeat your ' +
+	'previous reply.'
 
 // **A refusal that corrects rather than advises**. The bare `#N` is already
 // on screen and the hook cannot unsay it, so the reason does the one thing that helps the *next* reply:
@@ -149,13 +143,10 @@ function build_citation_reason(references: ReadonlyArray<string>): string {
 // first**: there the offer is the correct reply, so `needs_filing` is silent.
 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. Filing into a first-party repository there is Tier A — ' +
-	"the trigger is the judgement that it is worth filing, not the run's progress (the " +
-	'workflow-commands skill → `observation-filing.md`). Run ' +
-	'`pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` — it scouts, lints, labels and ' +
-	'runs `epic:bundle` itself — 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.'
+	'unattended — nobody is there to answer. Run ' +
+	'`pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` (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.'
 
 // **A headless parent's turn-end is its process's end**. Under `claude -p` the
 // background waits die with the turn, so the lanes lose their parent and nothing re-invokes it. The
@@ -176,12 +167,10 @@ const HEADLESS_REFUSAL_CAP = 3
 const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await']
 
 const HEADLESS_WAIT_BODY =
-	' this is a `claude -p` `backlogrun` parent (`JOSH_RUN_HEADLESS`) with lanes still ' +
-	'in flight, and ending this turn ends the process — its background waits are killed with it and the ' +
-	"lanes are left without a parent. Do not watch them yourself: the `run:wake` supervisor's driver " +
-	'watches the lanes and wakes a session only for a branch that needs judging. Hand the loop back with ' +
+	' this is a `claude -p` `backlogrun` parent with lanes in flight, and ending this turn kills the ' +
+	'process and its background waits. Hand the loop back with ' +
 	'`pnpm josh run:carry --cut --owner "$PPID"` (or `--end` when the run is over), then end the turn ' +
-	'(`backlogrun-progress.md` → "Picking the lanes up in the fresh session").'
+	'(`backlogrun-progress.md`).'
 
 const HEADLESS_WAIT_REASON = `${HEADLESS_WAIT_MARKER}${HEADLESS_WAIT_BODY}`
 
@@ -195,11 +184,9 @@ const PERMISSION_PATTERN = /許可|承認|permission|approve|approval|authorizat
 
 const LANE_INDEX_REASON =
 	'⛔ lane index permission: this is a dispatched lane child (`JOSH_LANE_CHILD`) and your reply asks ' +
-	"a person for permission to change the git index. A lane is a per-run work tree with no person's " +
-	'staging to protect, and the sanctioned commit flow is already authorized: remove any conflict ' +
-	'markers, then run `pnpm josh git -y`, which stages and commits them — a conflicted merge included. ' +
-	'This is Tier A (`.claude/skills/workflow-commands/chain-rule.md` → "origin/main is merged in before ' +
-	'the gate"). Do it and continue the run — do not repeat your previous reply.'
+	'a person for permission to change the git index. That is Tier A here (`chain-rule.md`): remove any ' +
+	'conflict markers, run `pnpm josh git -y` (it stages and commits, a conflicted merge included) and ' +
+	'continue the run — do not repeat your previous reply.'
 
 function asks_index_permission(message: string): boolean {
 	return INDEX_COMMAND_PATTERN.test(message) && PERMISSION_PATTERN.test(message)

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

@@ -30,16 +30,10 @@ function is_untested_commit(call: GuardedCall): boolean {
 
 const REASON =
 	'⛔ test declared: this commits a runtime code change with no test beside it — `pnpm josh ' +
-	'test:declared` reads the working tree as `required` (a changed file that is neither a test — ' +
-	'`*.test.ts` / `*.e2e.ts` — nor a mechanically-exempt non-runtime path). `CLAUDE.md` → Code ' +
-	'Change Rules requires a test for ALL code changes: a bug fix gets a regression test, a refactor ' +
-	'gets tests pinning behavior first, logic gets a unit test, an observable UI/timing change gets an ' +
-	'E2E. Add the declared test and reissue this commit. **If the change genuinely touches no ' +
-	'executable runtime path** it is the pre-approved non-runtime exception — declare it in your Step ' +
-	'0 work summary with the reason it is exempt (non-executable config, a cosmetic asset swap) and ' +
-	'reissue; the exception is a presentation, not a stop. Run `pnpm josh test:declared` to see the ' +
-	'files it names. The procedure is `prompts/collaboration-workflow/rule-delivery.md` → ' +
-	'"配送されている規則". This fires once per run, so reissuing will not repeat on the call in hand.'
+	'test:declared` reads it `required` and names the files. Tests are required for ALL code changes: ' +
+	'add the test and reissue, or, for a change that touches no runtime path, declare the non-runtime ' +
+	'exception in your Step 0 work summary and reissue. It fires once per run (`CLAUDE.md` → Code ' +
+	'Change Rules).'
 
 // 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