@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/poll-loop.ts

@@ -1,5 +1,7 @@
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { bash_triggers } from './bash-triggers'
+import { early_heartbeat } from './early-heartbeat'
+import { shell_segments } from './shell-segments'
 
 // 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
@@ -23,8 +25,7 @@ import { bash_triggers } from './bash-triggers'
 // back on the run's self-restraint — the thing that let these loops through in the first place.
 
 // A `while` or `until` header, in either spelling a poll loop reaches for. The trailing whitespace is
-// what separates the keyword from a path that merely begins with it (`until.txt`); a `for` loop is out
-// by omission — it iterates a fixed list rather than probing a state.
+// what separates the keyword from a path that merely begins with it (`until.txt`).
 const LOOP_KEYWORD = /\b(?:while|until)\s/u
 // A `sleep` command with any argument — the pause between probes that makes a loop a poll rather than
 // a stream reader. Read anywhere in the line rather than at a command position, because the loop body
@@ -52,10 +53,72 @@ const PROBE_HEADERS: ReadonlyArray<RegExp> = [
 	String.raw`grep\s+-[A-Za-z]*q`,
 ].map((probe) => new RegExp(`${WHILE_HEADER}${probe}`, 'u'))
 
+// **A counted `for` that sleeps is a poll with a deadline** (joshuafolkken/kit#4800). A lane child
+// waited out a backgrounded reviewer with `for i in $(seq 1 30); do sleep 10; done`, and the
+// completion notification sat queued until the loop returned — the same held-back exit a `while` poll
+// costs, spelled as a count. A header that counts — `$(seq …)`, a `{1..N}` range, or `((…))` — has no
+// list to work through, so its `sleep` is the whole point. A `for` over a real list (`for f in *.ts`)
+// is ordinary work and passes, sleep or not. The `sleep` is read in the loop's body only — from the
+// header to its first `done` — so a counted loop beside an unrelated `sleep` is not a wait (review
+// round 1); a nested loop's inner `done` cuts the body short, which under-refuses and so fails safe.
+const COUNTED_FOR = new RegExp(
+	String.raw`${COMMAND_POSITION}for(?:\s*\(\(|\s+\w+\s+in\s+(?:\$\(\s*seq\b|\{\d+\.\.))`,
+	'u',
+)
+const THROUGH_FIRST_DONE = /^[\s\S]*?\bdone\b/u
+
+// **A sleep chain in front of a read is the same poll, unrolled** (joshuafolkken/kit#5115). A lane
+// child watched a backgrounded task with `sleep 20; sleep 20; sleep 20; tail -c 1500 …/x.output` and
+// `sleep 20; ps -p 123`: no loop keyword, so the rows above miss it, and a read segment makes it
+// work rather than a bare timer, so `early-heartbeat` stands down. Its sleep is only there for the
+// read after it, which the completion notification makes unnecessary. The call is cut where the shell
+// starts a program (`shell_segments.commands_of`), and every cut is a sleep, an inert marker
+// (`early-heartbeat`'s own reading of both), or a read of a file or a process — at least one read,
+// which is what keeps it disjoint from `early-heartbeat`'s bare timer. A short settle (`sleep 3; tail`)
+// is below the threshold and passes.
+const SETTLE_SECONDS = 10
+const NO_SECONDS = 0
+const READ_COMMAND = /^(?:tail|cat|head|ps|stat|grep|wc|ls|pgrep|test|kill\s+-0|\[\[?)(?=\s|$)/u
+
+function slept_seconds(segments: ReadonlyArray<string>): number {
+	return segments.reduce(
+		(total, segment) => total + (early_heartbeat.sleep_seconds(segment) ?? NO_SECONDS),
+		NO_SECONDS,
+	)
+}
+
+// Only the sleep in front of the first read counts: `tail x; sleep 20` reads first and waits after,
+// which is not a wait *for* the read.
+function is_sleep_then_read(plain: string): boolean {
+	const segments = shell_segments.commands_of(plain).filter((segment) => segment !== '')
+	const first_work = segments.findIndex((segment) => !early_heartbeat.is_wait_or_inert(segment))
+	const waited = first_work === -1 ? NO_SECONDS : slept_seconds(segments.slice(0, first_work))
+
+	if (waited < SETTLE_SECONDS) return false
+
+	return segments
+		.slice(first_work)
+		.every((segment) => early_heartbeat.is_wait_or_inert(segment) || READ_COMMAND.test(segment))
+}
+
 function is_state_wait(plain: string): boolean {
 	return UNTIL_HEADER.test(plain) || PROBE_HEADERS.some((header) => header.test(plain))
 }
 
+function is_counted_sleep(plain: string): boolean {
+	const header = COUNTED_FOR.exec(plain)
+
+	if (header === null) return false
+
+	const rest = plain.slice(header.index)
+
+	return SLEEP_COMMAND.test(THROUGH_FIRST_DONE.exec(rest)?.[0] ?? rest)
+}
+
+function is_sleeping_loop(plain: string): boolean {
+	return (LOOP_KEYWORD.test(plain) && SLEEP_COMMAND.test(plain)) || is_counted_sleep(plain)
+}
+
 // **A `while read … done < file` is a stream reader, not a poll**, even when its body sleeps to
 // 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)
@@ -80,18 +143,18 @@ function is_poll_loop(command: string): boolean {
 	if (is_stream_reader(plain)) return false
 	if (is_state_wait(plain)) return true
 
-	return LOOP_KEYWORD.test(plain) && SLEEP_COMMAND.test(plain)
+	return is_sleeping_loop(plain) || is_sleep_then_read(plain)
 }
 
 // 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, 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.'
+	'⛔ output poll loop: a `while`/`until` or counted `for` loop, or a `sleep` chain before a read, ' +
+	'does not know when the task finished. `run_in_background` and end the turn — its exit ' +
+	're-invokes you; a background `Agent` is waited on by its completion notification (lane child: ' +
+	'bare `sleep 20`, `pnpm josh run:liveness`); CI by `pnpm josh followup` ' +
+	'(`background-commands.md`). 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
@@ -102,6 +165,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_poll_loop),
 	reason: POLL_LOOP_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Output poll loop',
+		topic: '`.claude/skills/workflow-commands/background-commands.md`',
+		fires:
+			"a hand-written `while` / `until` wait loop over a command's output, a marker file or a process, a counted `for` that sleeps, or a `sleep` chain of 10 s or more before a read of a file or process. Every occurrence",
+		quiet: 'the command started with `run_in_background` — its exit ends the wait',
+	},
 }
 
 const poll_loop = {

package/scripts/rules/pr-merge.ts

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

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

@@ -139,7 +139,7 @@ function uncut_lane_issue(state: LaneCutState): string | undefined {
 }
 
 // **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
+// Below the model-priced `pnpm josh cost --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. The verdict is
 // `cost_cli.session_verdict`'s, the same statistic and threshold `run:cut` and the implementation-phase
@@ -163,8 +163,8 @@ function is_uncut_gate(command: string, state: LaneCutState = current_state()):
 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. 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`).'
+	'on `split-unresolved`, answer its notice and rerun it; 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/protected-files.ts

@@ -2,7 +2,10 @@ import path from 'node:path'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { json_value } from '#scripts/lib/json-value'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
 import { bash_triggers } from './bash-triggers'
+import { edit_tool } from './edit-tool'
+import { git_argv } from './git-argv'
 import { shell_segments } from './shell-segments'
 
 // The trigger and the delivered text behind the `protected-file` row of `delivered-rules.ts`:
@@ -21,7 +24,7 @@ import { shell_segments } from './shell-segments'
 // It fires on every occurrence, for the reason `git-force.ts` does.
 
 const READ_TOOL = 'Read'
-const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write'])
+const { is_edit_tool } = edit_tool
 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
@@ -30,26 +33,57 @@ const TRACKED_VARIANTS: ReadonlySet<string> = new Set(['.env.example', '.env.tes
 const SETTINGS_FILE = path.join('.claude', 'settings.json')
 const WHITESPACE = /\s+/u
 const TOKEN_QUOTES = /["']/gu
-const INPUT_REDIRECT = '<'
-const SHELL_READERS: ReadonlySet<string> = new Set([
+// Each character of a redirect operator (`<`, `>`, `>>`, `2>`, `&>`) — and the clobber `>|` whole —
+// is spaced out to a mark, so the word after the last one is the file it reads or writes.
+const REDIRECT = />\||[<>]/gu
+const REDIRECT_MARK = '<'
+// Programs that run their quoted argument as a script.
+const SHELLS: ReadonlySet<string> = new Set(['bash', 'eval', 'sh', 'zsh'])
+// The body of a `$(…)` (innermost) or a backtick command substitution.
+const SUBSTITUTION = /\$\((?<dollar>[^()]*)\)|`(?<backtick>[^`]*)`/gu
+// Programs that print a named file's bytes or run them, and programs that write one: a write could set
+// a guard switch, so `cp .env.example .env` is refused too (kit #4660) — the person makes the file.
+const SHELL_PROGRAMS: ReadonlySet<string> = new Set([
+	'cp',
+	'install',
+	'ln',
+	'mv',
+	'tee',
 	'.',
 	'awk',
+	'base64',
 	'bat',
 	'cat',
+	'cmp',
+	'column',
+	'comm',
 	'cut',
+	'diff',
+	'fold',
 	'grep',
 	'head',
+	'hexdump',
+	'jq',
 	'less',
 	'more',
 	'nl',
 	'od',
+	'paste',
+	'perl',
+	'python',
+	'python3',
+	'rev',
 	'rg',
+	'ruby',
 	'sed',
 	'sort',
 	'source',
 	'strings',
+	'tac',
 	'tail',
+	'uniq',
 	'xxd',
+	'yq',
 ])
 
 function file_path_of(call: GuardedCall): string {
@@ -68,33 +102,82 @@ function is_environment_path(token: string): boolean {
 	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. 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, ' < ')
+// A shell read reaches the same bytes a `Read` does, and a shell write changes the file an `Edit`
+// would, so a segment that runs one of the programs (`cat .env`, `source .env`, `tee .env`) or
+// redirects the file (`< .env`, `>> .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.
+//
+// A quoted `>` is text (`git commit -m "x >> .env"`), so the marks are read on the quote-blanked
+// segment, whose offsets match the original; a shell's quoted script (`sh -c "echo x > .env"`) runs,
+// so its marks are read as written, as is a heredoc line, which `blanked` does not cut.
+function redirect_marks_of(segment: string, program: string | undefined): string {
+	if (program !== undefined && SHELLS.has(program)) return segment
+
+	return time_shell.blanked(segment) ?? segment
+}
+
+function spaced_redirects(segment: string, program: string | undefined): string {
+	const marks = redirect_marks_of(segment, program)
+
+	return segment.replaceAll(REDIRECT, (mark, offset: number) =>
+		marks.startsWith(mark, offset) ? ` ${REDIRECT_MARK} ` : mark,
+	)
+}
+
+function is_environment_shell_segment(segment: string): boolean {
+	const call = git_argv.program_of(segment)
+	const words = spaced_redirects(segment, call?.name)
 		.split(WHITESPACE)
 		.filter((word) => word !== '')
 	const is_redirected = words.some(
-		(word, index) => word === INPUT_REDIRECT && is_environment_path(words[index + 1] ?? ''),
+		(word, index) => word === REDIRECT_MARK && is_environment_path(words[index + 1] ?? ''),
 	)
-	const [command = '', ...rest] = words
 
-	return (
-		is_redirected || (SHELL_READERS.has(command) && rest.some((word) => is_environment_path(word)))
+	if (is_redirected || call === undefined) return is_redirected
+
+	return SHELL_PROGRAMS.has(call.name) && call.args.some((word) => is_environment_path(word))
+}
+
+// A shell's quoted script holds commands of its own (`bash -c "true; cat .env"`), so it is cut again
+// without regard to quotes.
+function script_commands_of(segment: string): Array<string> {
+	const program = git_argv.program_of(segment)?.name
+
+	if (program === undefined || !SHELLS.has(program)) return []
+
+	return shell_segments.commands_of(segment)
+}
+
+// A command substitution runs even inside double quotes (`echo "$(echo x > .env)"`), which the
+// quote-blanked reading takes for text, so its body is cut out as commands of their own.
+function substitution_commands_of(segment: string): Array<string> {
+	return [...segment.matchAll(SUBSTITUTION)].flatMap((match) =>
+		shell_segments.commands_of(match.groups?.['dollar'] ?? match.groups?.['backtick'] ?? ''),
 	)
 }
 
-function is_environment_shell_read(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_environment_read_segment(segment))
+function segments_of(command: string): Array<string> {
+	return shell_segments
+		.quote_aware_commands_of(command)
+		.flatMap((segment) => [
+			segment,
+			...script_commands_of(segment),
+			...substitution_commands_of(segment),
+		])
+}
+
+function is_environment_shell_access(command: string): boolean {
+	return segments_of(command).some((segment) => is_environment_shell_segment(segment))
 }
 
-function is_environment_read(call: GuardedCall): boolean {
-	if (call.name === READ_TOOL) return is_environment_path(file_path_of(call))
+// A `Read` lands the secret in the transcript; an `Edit` / `Write` could set a guard switch.
+function is_environment_access(call: GuardedCall): boolean {
+	if (call.name === READ_TOOL || is_edit_tool(call.name)) {
+		return is_environment_path(file_path_of(call))
+	}
 
-	return bash_triggers.on_bash_command(is_environment_shell_read)(call)
+	return bash_triggers.on_bash_command(is_environment_shell_access)(call)
 }
 
 // The repository the settings file belongs to is two levels above it (`<root>/.claude/settings.json`).
@@ -102,7 +185,7 @@ function is_consumer_settings_edit(
 	call: GuardedCall,
 	is_kit_consumer: (root: string) => boolean,
 ): boolean {
-	if (!EDIT_TOOLS.has(call.name)) return false
+	if (!is_edit_tool(call.name)) return false
 
 	const file_path = path.resolve(file_path_of(call))
 
@@ -115,11 +198,12 @@ function is_protected_file_call(
 	call: GuardedCall,
 	is_kit_consumer: (root: string) => boolean = doctor_consumer.is_kit_consumer,
 ): boolean {
-	return is_environment_read(call) || is_consumer_settings_edit(call, is_kit_consumer)
+	return is_environment_access(call) || is_consumer_settings_edit(call, is_kit_consumer)
 }
 
 const PROTECTED_FILE_REASON =
-	'⛔ protected file: `.env`, a `.env.*` variant and `.dev.vars` hold secrets, and a consumer ' +
+	'⛔ protected file: `.env`, a `.env.*` variant and `.dev.vars` hold secrets and are written only ' +
+	'by the person, 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.'
 
@@ -130,6 +214,13 @@ const ROW = {
 	decide: (): boolean => true,
 	// The opening the reason carried before it was cut to the action and the next command.
 	former_reasons: ['⛔ protected file: `.env` holds the Telegram bot token'],
+	about: {
+		title: 'Protected file',
+		topic: '`operating-rules.md`',
+		fires:
+			'a `Read`, `Edit` or `Write` of `.env` (or a shell read or write of it), or an `Edit` / `Write` of `.claude/settings.json` outside kit. Every occurrence',
+		quiet: "kit itself, or the user's `~/.claude/settings.json`",
+	},
 }
 
 const protected_files = { ROW, is_protected_file_call }

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

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

package/scripts/rules/reply-language.ts

@@ -1,3 +1,5 @@
+import { reply_prose } from './reply-prose'
+
 // 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.
@@ -31,14 +33,6 @@ const MATCH_SHARE_FLOOR = 0.5
 // unless no line of the reply is longer.
 const MIN_VOTING_LETTERS = 8
 
-const CODE_PATTERNS: ReadonlyArray<RegExp> = [
-	/```[\s\S]*?(?:```|$)/gu,
-	/`[^`\n]*`/gu,
-	/\]\([^)\s]*\)/gu,
-	/https?:\/\/\S+/gu,
-]
-// A run of printable ASCII; one holding a slash is a bare path the reply printed outside backticks.
-const ASCII_RUN_PATTERN = /[!-~]+/gu
 const LETTER_PATTERN = /\p{L}/gu
 // A letter of another script — `Common` and `Inherited` letters (`µ`) belong to no language of their own.
 const NON_LATIN_LETTER_PATTERN = /(?![\p{Script=Latn}\p{Script=Common}\p{Script=Inherited}])\p{L}/u
@@ -63,14 +57,6 @@ function letter_pattern(script: string): RegExp | undefined {
 	}
 }
 
-function prose_of(message: string): string {
-	let text = message
-
-	for (const pattern of CODE_PATTERNS) text = text.replaceAll(pattern, ' ')
-
-	return text.replaceAll(ASCII_RUN_PATTERN, (run) => (run.includes('/') ? ' ' : run))
-}
-
 function letter_count(text: string): number {
 	return text.match(LETTER_PATTERN)?.length ?? 0
 }
@@ -105,7 +91,7 @@ function is_mismatch(message: string, lang: string): boolean {
 	const pattern = letter_pattern(script)
 	if (pattern === undefined) return false
 
-	const prose = prose_of(message)
+	const prose = reply_prose.prose_of(message)
 	if (letter_count(prose) < MIN_PROSE_LETTERS) return false
 
 	return matches_share(prose, script, pattern) < MATCH_SHARE_FLOOR

package/scripts/rules/reply-prose.ts

@@ -0,0 +1,34 @@
+// The prose of a session-facing reply — the text a person reads as sentences, with code, links and
+// bare paths taken out. Two Stop rules read it: the reply's language (`reply-language.ts`) and its
+// length (`concise-reply.ts`).
+
+const CODE_PATTERNS: ReadonlyArray<RegExp> = [
+	/```[\s\S]*?(?:```|$)/gu,
+	/`[^`\n]*`/gu,
+	/\]\([^)\s]*\)/gu,
+	/https?:\/\/\S+/gu,
+]
+// A run of printable ASCII; one holding a slash is a bare path the reply printed outside backticks.
+const ASCII_RUN_PATTERN = /[!-~]+/gu
+// A table row or a list item — the structure a reply's points are carried in, not its narrative.
+const STRUCTURE_LINE_PATTERN = /^\s*(?:\||[-*+] |[・•] ?|\d+\. )/u
+
+function prose_of(message: string): string {
+	let text = message
+
+	for (const pattern of CODE_PATTERNS) text = text.replaceAll(pattern, ' ')
+
+	return text.replaceAll(ASCII_RUN_PATTERN, (run) => (run.includes('/') ? ' ' : run))
+}
+
+// The prose outside tables and lists: what a reply narrates around its one table or list.
+function narrative_of(message: string): string {
+	return prose_of(message)
+		.split('\n')
+		.filter((line) => !STRUCTURE_LINE_PATTERN.test(line))
+		.join('\n')
+}
+
+const reply_prose = { narrative_of, prose_of }
+
+export { reply_prose }