@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/rules/piped-verification.ts

@@ -1,7 +1,10 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { shell_segments } from './shell-segments'
 
-// The rule delivered at the call that pipes a verification command (joshuafolkken/kit#1556).
+// The rule delivered at the call that pipes a verification command.
 //
 // **A pipeline exits with its last command's status.** `pnpm josh gate 2>&1 | tail -40` therefore
 // answers success on a gate that printed `✗ verification gate failed`, and the failure that was
@@ -54,9 +57,8 @@ const VERIFICATION_COMMANDS: ReadonlySet<string> = new Set([
 ])
 
 // **The canonical name of each check, and both spellings still match**: `pnpm josh ga | tail` masks a
-// gate exactly as the long spelling does, and since joshuafolkken/kit#1789 the alias is expanded where
-// the command is read rather than by widening this set with every alias standing for one of its names
-// (joshuafolkken/kit#1643 for the reading). The suite names `pnpm josh ga` for that reason: an
+// gate exactly as the long spelling does, and the alias is expanded where the command is read rather
+// than by widening this set with every alias standing for one of its names. The suite names `pnpm josh ga` for that reason: an
 // expansion that regressed would show up here rather than as a guard that quietly stopped firing.
 function is_verification_command(segment: string): boolean {
 	return shell_segments.is_josh_command(segment, VERIFICATION_COMMANDS)
@@ -93,15 +95,18 @@ const PIPED_VERIFICATION_REASON =
 // command chain quoted inside a body is text rather than a call, and this repository's issue bodies
 // quote them constantly — without the blanking the two halves disagree, and
 // `gh issue comment 1 --body "… | pnpm josh gate | …"` reads as a check whose verdict survived.
-function command_pieces(command: string): Array<string> {
+function pipelines_of(command: string): Array<Array<string>> {
 	return shell_segments
 		.segments_of(time_shell.unquoted(command))
-		.flatMap((segment) => segment.split('|'))
-		.map((piece) => piece.trim())
+		.map((segment) => segment.split('|').map((piece) => piece.trim()))
+}
+
+function command_pieces(command: string): Array<string> {
+	return pipelines_of(command).flat()
 }
 
-// **The occasion this rule governs: a check whose result means pass or fail, run at all**
-// (joshuafolkken/kit#1643). The trigger fires only on the masked spelling, so a run that never piped
+// **The occasion this rule governs: a check whose result means pass or fail, run at all**.
+// The trigger fires only on the masked spelling, so a run that never piped
 // one would drop out of the reading entirely and the rate would be taken over runs that masked at
 // least once.
 function runs_verification(command: string): boolean {
@@ -115,11 +120,76 @@ function keeps_verdict_intact(command: string): boolean {
 	return runs_verification(command) && !is_masked_verification(command)
 }
 
+// **The commonest masking is rewritten rather than refused**. Almost every
+// refusal was a check narrowed with `| tail` or `| grep`, and the refusal cost a round trip to arrive at
+// the call `set -o pipefail;` in front would have made. Prefixed, the pipeline carries the check's
+// status, which is the rule's whole outcome — so the hook runs that call instead.
+//
+// **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.
+//
+// **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.
+//
+// **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
+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 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).'
+
+function reads_to_the_end(piece: string): boolean {
+	return FULL_READING_FILTER.test(piece) && !EARLY_EXIT_GREP.test(piece)
+}
+
+function is_filtered_check(pipeline: Array<string>): boolean {
+	const [head = '', ...filters] = pipeline
+
+	return is_verification_command(head) && filters.every((piece) => reads_to_the_end(piece))
+}
+
+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 call's input with the prefix in front, 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
+
+	return { ...call.input, command: `${PIPEFAIL_PREFIX}${command}` }
+}
+
 const piped_verification = {
 	PIPED_VERIFICATION_REASON,
+	PIPEFAIL_NOTE,
 	VERIFICATION_COMMANDS,
 	is_masked_verification,
 	keeps_verdict_intact,
+	pipefail_input,
 	runs_verification,
 }
 

package/scripts/rules/poll-loop.ts

@@ -1,23 +1,22 @@
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { bash_triggers } from './bash-triggers'
 
-// The trigger and the delivered text behind the `poll-loop` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2371). The hand-written wait loop a lane child improvises over a backgrounded
+// The trigger and the delivered text behind the `poll-loop` row of `delivered-rules.ts`.
+// The hand-written wait loop a lane child improvises over a backgrounded
 // command's output file.
 //
-// **The gap `early-heartbeat` left, on purpose.** joshuafolkken/kit#1570's rule refuses a bare
+// **The gap `early-heartbeat` left, on purpose.** That rule refuses a bare
 // `sleep` — a clock timer arming a progress report — and it stands down the moment it sees a loop
 // keyword (`early-heartbeat.ts`'s `LOOP_KEYWORD`), because a loop that ends on a condition is waiting
 // on a thing rather than on a clock. This is that thing: a `while`/`until` loop that sleeps between
-// probes of a command's output file. It never appeared in the heartbeat reading, and it is the larger
-// half of the waste — six lanes lost about 45 minutes, 13% of their wall clock, to it.
+// probes of a command's output file.
 //
 // **The loop does not know when the command finished.** A regex over the output file that never
 // matches waits to the harness block limit; one that matches a mid-run line exits too early. Either
 // way the command's *exit* is not what ends the wait, and each pass spends a full-context round trip.
 // A command backgrounded with `run_in_background` re-invokes the run when it exits — the completion
 // notification is what ends the wait on the task itself, which is the mechanism this row hands back,
-// the same reading joshuafolkken/kit#1510 took for the foreground push (`run-tail-rule.ts`).
+// the same reading `run-tail-rule.ts` takes for the foreground push.
 //
 // **It fires on every occurrence**, for the reason `git-force.ts` does: a poll loop wastes the same
 // round trips each time it is armed, so refused-once-and-free-after would put every loop but the first
@@ -31,10 +30,9 @@ const LOOP_KEYWORD = /\b(?:while|until)\s/u
 // a stream reader. Read anywhere in the line rather than at a command position, because the loop body
 // puts it behind a `do` keyword (`; do sleep 30; done`), which no separator precedes. The argument is
 // matched as any non-space rather than a digit, so a variable duration (`sleep "$INTERVAL"`) is caught
-// as a literal one is — a poll with a configurable interval is still a poll (joshuafolkken/kit#2371,
-// review round 1).
+// as a literal one is — a poll with a configurable interval is still a poll.
 const SLEEP_COMMAND = /\bsleep\s+\S/u
-// **A loop with no `sleep` is still a poll — a worse one** (joshuafolkken/kit#2421). A lane child ran
+// **A loop with no `sleep` is still a poll — a worse one**. A lane child ran
 // `until [ -f /tmp/gate-done ]; do if ! kill -0 %1 …; then break; fi; done` for hours: a busy-wait
 // that spun a core on a marker nobody wrote, and slipped through because the rule required the
 // `sleep`. Two headers make a loop a poll with or without one. An `until` header waits for a state to
@@ -59,12 +57,12 @@ function is_state_wait(plain: string): boolean {
 }
 
 // **A `while read … done < file` is a stream reader, not a poll**, even when its body sleeps to
-// throttle processing (joshuafolkken/kit#2371, review round 1). Its condition consumes input rather
+// throttle processing. Its condition consumes input rather
 // than probing for a state — a poll never reads its condition, it *tests* it (grep, wc, a file check)
 // — so the completion notification this rule points to has nothing to do with it. A `while read`
 // header is therefore always a stream reader; a line that also carried a separate `until` poll would
 // go un-refused, which fails safe (under-refusal) and is contrived enough not to warrant the added
-// regex the attempt to catch it needed (joshuafolkken/kit#2371, review round 2).
+// regex the attempt to catch it needs.
 const STREAM_READER = /\bwhile\s+read\b/u
 
 function is_stream_reader(plain: string): boolean {

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

@@ -1,3 +1,4 @@
+import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
@@ -7,31 +8,22 @@ import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
 
-// The pre-gate cut, delivered at the call it binds on (joshuafolkken/kit#1864).
+// The pre-gate cut, delivered at the call it binds on.
 //
-// **The mechanism was there and nothing called it.** joshuafolkken/kit#1839 built the cut and
-// joshuafolkken/kit#1850 measured the result: across six lane children — #1853, #1849, #1855, #1854,
-// #1856 and #1847 — the cut was taken **0 times**. Four of the six issued the *entry* check
-// `pnpm josh run:cut --resume <N>` and were answered `fresh`; not one issued `pnpm josh run:cut <N>`,
-// the call that actually cuts. The procedure was read three to five times per run and remained one
-// step of prose in the middle of it, so joshuafolkken/kit#1839's fourth acceptance condition — the
-// drop in context per request — could not be judged at all.
-//
-// **This is the third time prose lost to a refusal.** joshuafolkken/kit#1344 measured three
-// consecutive runs in which resident text about batching moved the number not at all, and
-// joshuafolkken/kit#1460 measured the same for the investigation threshold; in both, a `PreToolUse`
-// refusal was what finally moved it. A step a run is free to skip is a step that gets skipped under
-// time pressure, and `run:hold` — the one boundary step that never gets missed — is the one that
-// refuses.
+// **A refusal, not prose.** A lane child issues the *entry* check `pnpm josh run:cut --resume <N>`
+// and goes on to the gate; carried as a step of prose, `pnpm josh run:cut <N>` — the call that
+// actually cuts — is the step that gets skipped. A step a run is free to skip is a step that gets
+// skipped under time pressure, and `run:hold` — the one boundary step that never gets missed — is
+// the one that refuses.
 
 const GATE_COMMANDS: ReadonlySet<string> = new Set(['gate'])
 const CUT_COMMANDS: ReadonlySet<string> = new Set(['run:cut'])
 // The three spellings that ask about a cut rather than take one: the fresh process's entry check, the
-// teardown, and the record read. **Excluding them is the whole point** — four of the six measured
-// children issued `--resume` and went straight on to the gate, so a predicate that counted any
-// `run:cut` would have been silent on exactly the runs this rule exists for.
+// teardown, and the record read. **Excluding them is the whole point** — a child that issued
+// `--resume` and went straight on to the gate is the run this rule exists for, so a predicate that
+// counted any `run:cut` would be silent on exactly those runs.
 const CUT_MODE_FLAG = /(?:^|\s)--(?:resume|end|json)(?:[=\s]|$)/u
-// **The one entry call the resumed half never makes** (joshuafolkken/kit#1867).
+// **The one entry call the resumed half never makes**.
 // `.claude/skills/workflow-commands/pre-gate-cut.md` sends a `fresh` verdict on to "claim the hold,
 // ask the session boundary, read the issue, implement", and tells a `resume` verdict to "skip the
 // title, the plan, the fresh hold claim and the implementation". So the hold claim is what a run made
@@ -75,7 +67,7 @@ function claims_the_hold(command: string): boolean {
 	return invokes_josh(command, HOLD_COMMANDS, HOLD_MODE_FLAG)
 }
 
-// **One half of the occasion, never the whole of it** (joshuafolkken/kit#1867). Taken alone this
+// **One half of the occasion, never the whole of it**. Taken alone this
 // predicate enrols both processes of one obedient lane child: the cut relaunches a second session
 // which issues this same entry check byte for byte and can never take a cut of its own, so the row
 // read at half its true rate. `delivered-rules.ts` pairs it with `claims_the_hold`, which only the
@@ -87,7 +79,7 @@ function claims_the_hold(command: string): boolean {
 // read from the working directory and appears nowhere in a transcript, so it cannot be the
 // denominator — and taking the gate as the occasion instead would enrol every ordinary non-lane run,
 // where the rule can never be kept, and `pnpm josh rule:value` would read the row low by
-// construction. joshuafolkken/kit#1643 names exactly that failure.
+// construction.
 function asks_about_the_cut(command: string): boolean {
 	return invokes_josh(command, CUT_COMMANDS)
 }
@@ -95,12 +87,15 @@ function asks_about_the_cut(command: string): boolean {
 // What the trigger has to know about the world, passed in so the decision itself is testable without
 // a lane on disk and without a git call. `marked_issue` is the dispatch mark read from the
 // environment — the fact that makes the human-or-child question mechanical rather than the model's to
-// judge (joshuafolkken/kit#1904).
+// judge.
 interface LaneCutState {
 	directory: string
 	carried: (now?: Date) => RunCut | undefined
 	marked_issue: string | undefined
-	// **The context verdict, read lazily** (joshuafolkken/kit#2312). It is a thunk, like
+	// Whether this session is a ship reviewer, which carries the implementing child's mark without
+	// being the run the cut is for (joshuafolkken/kit#3623).
+	is_reviewer: boolean
+	// **The context verdict, read lazily**. It is a thunk, like
 	// `carried`, so `current_state` builds the object without pricing a session — the read happens only
 	// after the command and lane checks pass, off the handful of calls that actually run a lane's gate.
 	context_verdict: () => CostVerdict
@@ -111,6 +106,7 @@ function current_state(): LaneCutState {
 		directory: process.cwd(),
 		carried: run_cut.carried_cut_sync,
 		marked_issue: lane_child_marker.marked_issue(),
+		is_reviewer: agent_session_role.is_reviewer(),
 		context_verdict: cost_cli.session_verdict,
 	}
 }
@@ -119,27 +115,35 @@ function current_state(): LaneCutState {
 // A person working in the lane carries no mark, so the rule stays silent for them — the
 // human-or-child call is read from the environment, never left to the model. A mark that leaked in
 // from the parent session names some other issue, so requiring it to equal this lane's issue reads
-// that leak as a person too (joshuafolkken/kit#1904).
+// that leak as a person too.
 //
 // **The resumed process must also stay silent, and the cut record is what says so.** After a cut,
 // `adopt_cut` leaves the record in place with `is_handed_off: false`, so a carried record naming this
 // issue means the process asking is the one the cut already produced. Without this half the rule
 // would fire on the fresh process too — refusing a gate call on a run that had kept the rule
 // perfectly, which `prompts/collaboration-workflow/rule-delivery.md` calls worse than no hook at all.
+//
+// **A ship reviewer's inherited mark is not a dispatch**. The supervisor that launched it is waiting on
+// its findings, so there is no fresh process a cut could hand the gate to; `implementation-cut.ts`
+// stands down for the same session on the same fact.
+function dispatched_issue(state: LaneCutState): string | undefined {
+	return state.is_reviewer ? undefined : state.marked_issue
+}
+
 function uncut_lane_issue(state: LaneCutState): string | undefined {
 	const issue = lane_paths.lane_issue_of(state.directory)
 
 	if (issue === undefined) return undefined
 
-	if (state.marked_issue !== issue) return undefined
+	if (dispatched_issue(state) !== issue) return undefined
 
 	return state.carried()?.issue === issue ? undefined : issue
 }
 
-// **The cut is taken only when the current context is worth its resume** (joshuafolkken/kit#2312).
+// **The cut is taken only when the current context is worth its resume**.
 // Below the shared `CONTEXT_CUT_THRESHOLD` a short lane has no accumulation a cut would drop, so the
 // gate runs uncut rather than paying for a relaunch; an unmeasurable session keeps the old
-// unconditional cut as the safety net joshuafolkken/kit#1933 relies on. The verdict is
+// unconditional cut as the safety net. The verdict is
 // `cost_cli.session_verdict`'s, the same statistic and threshold `run:cut` and the implementation-phase
 // cut read, so the guard and the command can never disagree about whether a cut was due.
 function warrants_the_cut(verdict: CostVerdict): boolean {
@@ -176,12 +180,11 @@ const PRE_GATE_CUT_REASON =
 	'`.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.'
 
-// **The pre-gate cut is two acts, one call apart** (joshuafolkken/kit#2034), so its `rule:value`
+// **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,
 // somewhere in the same run, claimed the working-tree hold — the near half of the boundary a fresh
 // process never makes. Read only by the offline measurement, never the live delivery path. Moved here
-// from `delivered-rules.ts` so the pre-gate row lives with its rule, as `implementation-cut.ts`'s does
-// (joshuafolkken/kit#2346).
+// from `delivered-rules.ts` so the pre-gate row lives with its rule, as `implementation-cut.ts`'s does.
 function reaches_the_pre_gate_boundary(
 	call: GuardedCall,
 	_turn: ReadonlyArray<GuardedCall>,

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

@@ -1,10 +1,11 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { tail_commands } from './tail-commands'
 
 // The stand-down that keeps the `issue-comments` rule from refusing a body read the run has already
-// earned (joshuafolkken/kit#1905). The rule exists so a run reads an Issue's comments before building
+// earned. The rule exists so a run reads an Issue's comments before building
 // on its body — but a run that already read them, and later reads the body again (a post-merge state
 // check, a re-read), was refused a second time for a read it had already made. **The delivery path
 // sees only the raw transcript tail** — `delivered-rules.ts` names the reason the run's own calls are
@@ -22,7 +23,6 @@ const ISSUE_PATH_NUMBER = /issues\/(\d+)/gu
 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
-const A_NUMBER = /^\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.
@@ -38,7 +38,7 @@ function add_issue_read_numbers(command: string, numbers: Set<number>): void {
 	const tokens = (match[1] ?? '').split(/\s+/u)
 
 	for (const token of tokens) {
-		if (A_NUMBER.test(token)) numbers.add(Number(token))
+		if (issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) numbers.add(Number(token))
 	}
 }
 

package/scripts/rules/protected-files.ts

@@ -5,12 +5,13 @@ import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
 
-// The trigger and the delivered text behind the `protected-file` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2983): the two files a run's own file tools must not touch.
+// The trigger and the delivered text behind the `protected-file` row of `delivered-rules.ts`:
+// the two files a run's own file tools must not touch.
 //
-// - **`.env` is never read** — by the `Read` tool or by a shell reader in a `Bash` call. It carries the
-//   Telegram bot token, and either read lands it in the transcript. The scripts that need it load it
-//   in their own process, so refusing the call costs them nothing.
+// - **A secret file is never read** — by the `Read` tool or by a shell reader in a `Bash` call. `.env`
+//   carries the Telegram bot token, its `.env.*` variants and wrangler's `.dev.vars` carry the same
+//   kind of value, and either read lands it in the transcript. The scripts that need one load it in
+//   their own process, so refusing the call costs them nothing.
 // - **`.claude/settings.json` is never edited in a consumer repository.** It is the deny list and the
 //   hooks that enforce every other rule, so a run that rewrites it can switch the guards off; `josh
 //   sync` owns it there. Only a kit consumer's file is refused — decided per file from the repository
@@ -21,7 +22,11 @@ import { shell_segments } from './shell-segments'
 
 const READ_TOOL = 'Read'
 const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write'])
-const ENVIRONMENT_FILE = '.env'
+const SECRET_FILES: ReadonlySet<string> = new Set(['.env', '.dev.vars'])
+const ENVIRONMENT_VARIANT_PREFIX = '.env.'
+// The two variants `.gitignore` un-ignores: they are tracked and hold placeholders, not secrets. The
+// `Read(!…)` carve-outs in `.claude/settings.json` name the same two.
+const TRACKED_VARIANTS: ReadonlySet<string> = new Set(['.env.example', '.env.test'])
 const SETTINGS_FILE = path.join('.claude', 'settings.json')
 const WHITESPACE = /\s+/u
 const TOKEN_QUOTES = /["']/gu
@@ -56,12 +61,17 @@ function file_path_of(call: GuardedCall): string {
 }
 
 function is_environment_path(token: string): boolean {
-	return path.basename(token.replaceAll(TOKEN_QUOTES, '')) === ENVIRONMENT_FILE
+	const name = path.basename(token.replaceAll(TOKEN_QUOTES, ''))
+
+	if (TRACKED_VARIANTS.has(name)) return false
+
+	return SECRET_FILES.has(name) || name.startsWith(ENVIRONMENT_VARIANT_PREFIX)
 }
 
 // A shell read reaches the same bytes a `Read` does, so a segment that runs a reader (`cat .env`,
-// `source .env`) or redirects the file into a command (`< .env`) is refused too. `.env.example` and
-// `.env.local` keep passing: only a token whose basename is exactly `.env` counts.
+// `source .env`) or redirects the file into a command (`< .env`) is refused too. Claude Code applies
+// the `Read` deny rules to the readers it recognizes, but `source .env.local` passes them (measured on
+// 2.1.289, kit #3602), so the variants are matched here as well.
 function is_environment_read_segment(segment: string): boolean {
 	const words = segment
 		.replaceAll(INPUT_REDIRECT, ' < ')
@@ -109,12 +119,14 @@ function is_protected_file_call(
 }
 
 const PROTECTED_FILE_REASON =
-	'⛔ protected file: `.env` holds the Telegram bot token, so reading it — 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. `.claude/settings.json` in a ' +
+	'⛔ 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 both files alone, or ask the user. ' +
+	'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.**'
 
 const ROW = {

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

@@ -1,7 +1,7 @@
 import { bash_triggers } from './bash-triggers'
 
-// The trigger and the delivered text behind the `raw-field-body` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2304). Its sibling `shell-body` refuses a body a run passed *inline* so the shell
+// The trigger and the delivered text behind the `raw-field-body` row of `delivered-rules.ts`.
+// Its sibling `shell-body` refuses a body a run passed *inline* so the shell
 // evaluates it; this one refuses a body a run passed *by path with the wrong flag*, so the path is
 // posted as text.
 //
@@ -9,8 +9,7 @@ import { bash_triggers } from './bash-triggers'
 // reads the file when the value opens with `@`; `-f` / `--raw-field` sends the value verbatim, so
 // `-f body=@<path>` posts the literal string `@<path>`. The two differ by a single character, `gh`
 // exits 0 and returns a comment URL either way, and the break is invisible until a person reads the
-// issue — joshuafolkken/kit#2304 recorded two park comments (`@/tmp/2294-park.md` and a decision
-// record) lost exactly this way, which was the only place the reason for a stopped child was written.
+// issue — a park comment lost this way is the only place the reason for a stopped child was written.
 //
 // **The trigger is the raw-field flag with an `@`-opening body, not `@` alone.** `-F` / `--field
 // body=@<path>` is the spelling the rule *asks* for and stays silent; a `-f body="plain text"` with no

package/scripts/rules/reply-language.ts

@@ -1,4 +1,4 @@
-// Whether a reply is written in the session language (joshuafolkken/kit#2470). The session-language
+// Whether a reply is written in the session language. The session-language
 // line reaches a turn only through `UserPromptSubmit`, so a turn opened by a background completion or a
 // Stop hook refusal answered in whatever language it was just shown, and kept answering in it.
 //

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

@@ -5,15 +5,14 @@ import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
 import { tail_commands } from './tail-commands'
 
-// The trigger and the delivered text behind the `rule-body` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2272). It delivers the residency questions at the one moment they are skipped —
+// The trigger and the delivered text behind the `rule-body` row of `delivered-rules.ts`.
+// It delivers the residency questions at the one moment they are skipped —
 // the edit that writes a rule into prose.
 //
-// **The gap it closes.** joshuafolkken/kit#2117 put question 0 (is the answer computable, so it is a
-// decision oracle) into the residency criterion and built `pnpm josh oracle:list`, but nothing made
-// that question fire: a new computable rule could still be written into prose and no test would fail,
-// so friction ran one way only — toward more prose. The criterion lived in `residency.md`, and
-// whether a run read it before writing a rule was left to judgement. This row is the firing.
+// **The gap it closes.** Question 0 of the residency criterion (is the answer computable, so it is a
+// decision oracle) and `pnpm josh oracle:list` do not fire on their own: a new computable rule could
+// be written into prose and no test would fail, so friction would run one way only — toward more
+// prose. This row is the firing.
 //
 // **The trigger is the append, not the edit.** A rule delivered on *every* edit to these files would
 // speak on typo fixes, link swaps and deletions — the wrong-turn firing `rule-delivery.md` calls worse
@@ -22,13 +21,12 @@ import { tail_commands } from './tail-commands'
 // URL is stripped) all fail. What stays is the case the Issue names — writing rule prose into a rule
 // document.
 //
-// **The stand-down is what turned the reminder into a check** (joshuafolkken/kit#2324). Until now the
-// row only *reminded* — it fired once and let the reissue through unconditionally, so "reissue and it
-// goes" meant a computable rule could still be written into prose with nothing having answered the two
-// questions. Now the pass condition is a *record*: the run has run `pnpm josh oracle:list` (question 0)
+// **The stand-down is what makes the reminder a check**. A row that only *reminded* — fired once and
+// let the reissue through unconditionally — would let a computable rule be written into prose with
+// nothing having answered the two questions. The pass condition is a *record*: the run has run `pnpm josh oracle:list` (question 0)
 // and `pnpm josh run:step` (the ordering question) earlier in the transcript. Both present, the edit is
 // stood down; either missing, it is refused — on the reissue too, since a row with a stand-down
-// refuses until it is met (joshuafolkken/kit#2807). It passes on answering the questions, not on reading the
+// refuses until it is met. It passes on answering the questions, not on reading the
 // reminder. Keeping the rule is therefore running those two commands, which `keeps` names.
 
 // The two edit tools the `PreToolUse` matcher routes here. A `Write` carries the whole new file; an

package/scripts/rules/rule-guard.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { delivered_rules } from './delivered-rules'
 
-// The hook entry point for trigger-delivered rules (joshuafolkken/kit#1524).
+// The hook entry point for trigger-delivered rules.
 //
 // **It is the same shape `batch-guard.ts` and `investigation-guard.ts` already have**, and
 // deliberately so: read the payload on stdin, ask the rule, write the one envelope Claude Code

package/scripts/rules/rule-list.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { delivered_rules } from './delivered-rules'
+import { rule_registry, type RegisteredRule } from './rule-registry'
+
+// `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.
+
+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}`
+
+	return [
+		`- **${rule.title}** (\`${id}\`, ${rule.topic})`,
+		`  - fires: \`${rule.entry}\` — ${rule.fires}`,
+		`  - silent: ${rule.quiet}`,
+	].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))
+
+	return rule_registry.REGISTERED_RULES.map((rule) => rule.id).filter(
+		(id) => !reached.has(id) && !stop_ids.has(id),
+	)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.stdout.write(`${render()}\n`)
+
+const rule_list = { MISSING, orphans, render }
+
+export { rule_list }