@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/rules/early-heartbeat.ts

@@ -185,10 +185,11 @@ function decide(call: GuardedCall, run: GuardRun, can_record: boolean): boolean
 // is the half that makes the rule believable — the promise was kept and the interval was not.
 const EARLY_HEARTBEAT_REASON =
 	'⛔ early heartbeat: this call arms a wait timer of its own, and the progress clock is not yours ' +
-	'to keep. `pnpm josh run:progress --wait` waits the interval out for you ' +
+	'to keep. `pnpm josh run:progress --wait` keeps it for you ' +
 	'(`JOSH_PROGRESS_INTERVAL_MINUTES`, or `josh.progress_interval_minutes` in `package.json`, ' +
-	'default 20 minutes), prints the five labelled lines and exits — start it in the background, relay ' +
-	'the lines it printed when it exits, and start the next one. Two timers armed at ' +
+	'default 20 minutes): start it once in the background and it reports the five labelled lines to ' +
+	"the run's event stream on its own, without waking you — relay nothing, and start it again only " +
+	'after it exits, which it does when newly runnable work arrives. Two timers armed at ' +
 	'once is what produced reports 3–5 minutes apart on a 15-minute setting ' +
 	'(joshuafolkken/kit#1570): a new one was armed on the turn a timer fired and again on the turn a ' +
 	"child's completion woke the run, and `--mark` recorded each report without anything refusing the " +

package/scripts/rules/file-body.ts

@@ -142,9 +142,6 @@ const file_body = {
 	FILE_BODY_REASON,
 	ROW,
 	carries_a_file_body,
-	is_in_place_perl,
-	is_interpreter_write,
-	writes_existing_file,
 }
 
 export { file_body }

package/scripts/rules/filing-cap.ts

@@ -127,8 +127,6 @@ const filing_cap = {
 	FILING_CAP,
 	FILING_CAP_REASON,
 	ROW,
-	current_turn,
-	decide,
 	is_prompt_line,
 	prior_filing_count,
 	turn_filing_count,

package/scripts/rules/gh-api.ts

@@ -40,8 +40,13 @@ function is_gh_api(segment: string): boolean {
 }
 
 // A read is a `GET` — explicit via a method flag, or implicit when no field flag makes it a POST.
+// The explicit `-X` / `--method` value, upper-cased, or `undefined` when the call names none.
+function method_of(segment: string): string | undefined {
+	return API_METHOD.exec(segment)?.[1]?.toUpperCase()
+}
+
 function is_read(segment: string): boolean {
-	const method = API_METHOD.exec(segment)?.[1]
+	const method = method_of(segment)
 
 	if (method !== undefined) return method.toUpperCase() === READ_METHOD
 
@@ -60,6 +65,6 @@ function repo_target(segment: string): RepoTarget | undefined {
 	return { owner: match[OWNER_GROUP] ?? '', repo: match[REPO_GROUP] ?? '' }
 }
 
-const gh_api = { GH_API_COMMAND, GH_FLAGS, is_gh_api, is_read, is_write, repo_target }
+const gh_api = { GH_FLAGS, is_gh_api, is_read, is_write, method_of, repo_target }
 
 export { gh_api }

package/scripts/rules/git-argv.ts

@@ -12,8 +12,9 @@
 // arguments is what makes the judgement independent of the spelling.
 
 // The wrapper words that may stand in front of `git`, the same ones `run-tail.ts` skips in front of
-// `josh`: environment assignments, the package-manager launchers, `sudo`, and an opening subshell
-// parenthesis. Left in, `sudo git push --force` and `(git push -f)` are silently not a git command.
+// `josh`: environment assignments, the package-manager launchers, `sudo`, `env`, and an opening
+// subshell parenthesis. Left in, `sudo git push --force`, `env git commit` and `(git push -f)` are
+// silently not a git command (joshuafolkken/kit#2983).
 const ENV_ASSIGNMENT = /^[A-Za-z_]\w*=/u
 const WRAPPER_WORDS: ReadonlySet<string> = new Set([
 	'pnpm',
@@ -22,6 +23,7 @@ const WRAPPER_WORDS: ReadonlySet<string> = new Set([
 	'run',
 	'sudo',
 	'command',
+	'env',
 ])
 const SUBSHELL_OPEN = '('
 
@@ -92,17 +94,26 @@ function after_globals(words: ReadonlyArray<string>, start: number): number {
 	return index
 }
 
+// The words after `command` once the wrapper is skipped, or `undefined` when the segment does not
+// invoke it. `gh` and `rm` are judged by the same wrapper cut as `git` (joshuafolkken/kit#2983), so
+// `env gh pr close` and `sudo rm -rf` are read as the calls they are.
+function arguments_of(segment: string, command: string): Array<string> | undefined {
+	const words = words_of(segment)
+	const command_index = after_wrapper(words)
+
+	return words[command_index] === command ? words.slice(command_index + NEXT) : undefined
+}
+
 // The subcommand and the arguments after it, or `undefined` when the segment is not a git invocation.
 // **`pnpm josh git` is deliberately not one**: the word after the wrapper is `josh`, not `git`, so a
 // run's own authorized `pnpm josh git -y` push is invisible here — which is exactly what keeps this row
 // off the node route the deny list already leaves alone.
 function parse(segment: string): GitCall | undefined {
-	const words = words_of(segment)
-	const git_index = after_wrapper(words)
+	const words = arguments_of(segment, GIT_COMMAND)
 
-	if (words[git_index] !== GIT_COMMAND) return undefined
+	if (words === undefined) return undefined
 
-	const subcommand_index = after_globals(words, git_index + NEXT)
+	const subcommand_index = after_globals(words, 0)
 
 	return { subcommand: words[subcommand_index], args: words.slice(subcommand_index + NEXT) }
 }
@@ -124,6 +135,6 @@ function short_cluster_has(token: string, letters: string): boolean {
 	return false
 }
 
-const git_argv = { parse, short_cluster_has, words_of }
+const git_argv = { arguments_of, parse, short_cluster_has }
 
 export { git_argv }

package/scripts/rules/git-force.ts

@@ -96,9 +96,7 @@ const ROW = {
 const git_force = {
 	GIT_FORCE_REASON,
 	ROW,
-	is_branch_delete,
 	is_force_or_delete,
-	is_force_or_delete_push,
 }
 
 export { git_force }

package/scripts/rules/implementation-cut.ts

@@ -224,7 +224,6 @@ const implementation_cut = {
 	REISSUE_WINDOW_MS,
 	ROW,
 	decide,
-	is_edit_tool,
 	is_over_threshold_edit,
 	is_reissued_refusal,
 	takes_the_impl_cut,

package/scripts/rules/index-guard.ts

@@ -0,0 +1,71 @@
+import { bash_triggers } from './bash-triggers'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+import { worktree_guard } from './worktree-guard'
+
+// The trigger and the delivered text behind the `index-mutation` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2983). `CLAUDE.md` → Git Rules forbids staging or otherwise mutating the git index
+// on the run's own judgement, and `.claude/settings.json` backs it with `Bash(git add*)` /
+// `Bash(git commit*)` and their siblings — but those are prefix globs, so `git -C . commit`,
+// `git -c k=v commit` and `env git commit` all pass them. Reading the argv through `git-argv.ts`, the
+// cut `git-force.ts` already uses, is what makes the judgement independent of the spelling.
+//
+// **The scope is accident prevention, not a sandbox.** Under `bypassPermissions` with `Bash(*)` a run
+// that means to get round the guard can always do so through `python -c` or a script; the decision
+// recorded on the Issue is to stop the variant spellings a run types by accident. The authorized
+// commit flow is `pnpm josh git -y`, which spawns git in a child process this hook never sees.
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does: overwriting the user's
+// staged snapshot is destructive each time it is issued.
+
+// The subcommands that write the index outright. `stage` is `add`'s synonym; `rm` and `mv` stage the
+// removal or rename they make.
+const INDEX_SUBCOMMANDS: ReadonlySet<string> = new Set([
+	'add',
+	'commit',
+	'mv',
+	'reset',
+	'rm',
+	'stage',
+])
+const RESTORE_SUBCOMMAND = 'restore'
+
+// A `git restore` that touches only the index (`--staged` / `-S` without `--worktree` / `-W`). One that
+// touches the working tree is the `worktree-mutation` row's, so the two rows never claim one command.
+function is_index_restore(args: ReadonlyArray<string>): boolean {
+	return !worktree_guard.touches_worktree(args)
+}
+
+function is_index_segment(segment: string): boolean {
+	const call = git_argv.parse(segment)
+
+	if (call === undefined) return false
+	if (INDEX_SUBCOMMANDS.has(call.subcommand ?? '')) return true
+
+	return call.subcommand === RESTORE_SUBCOMMAND && is_index_restore(call.args)
+}
+
+function is_index_mutation(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => is_index_segment(segment))
+}
+
+const INDEX_MUTATION_REASON =
+	'⛔ git index mutation: `git add` / `stage` / `commit` / `reset` / `rm` / `mv` and `git restore ' +
+	"--staged` overwrite the user's staged snapshot, which `CLAUDE.md` → Git Rules forbids on your own " +
+	'judgement (`prompts/collaboration-workflow/operating-rules.md` → "git index を勝手に変更しない"). The ' +
+	'`.claude/settings.json` deny list matches prefix globs, so it misses `git -C . commit`, `git -c ' +
+	'k=v commit` and `env git commit`; this row reads the argv instead, so the spelling does not matter. ' +
+	'A commit goes through `pnpm josh git -y`; any other staging needs explicit current-turn user ' +
+	'instruction, run by the user in their own terminal. **This rule fires on every occurrence, not once ' +
+	'per run.**'
+
+const ROW = {
+	id: 'index-mutation',
+	is_trigger: bash_triggers.on_bash_command(is_index_mutation),
+	reason: INDEX_MUTATION_REASON,
+	decide: (): boolean => true,
+}
+
+const index_guard = { INDEX_MUTATION_REASON, ROW, is_index_mutation }
+
+export { index_guard }

package/scripts/rules/issue-citation.ts

@@ -34,10 +34,23 @@ const REFERENCE_BOUNDARY = /[\s#()[\]<>|]/u
 // `issue:cite`'s parser accepts. A path-like run (`src/lib`, `a/b/c`) is not one, so it is not emitted
 // as a prefix that would make the suggested `issue:cite` call refuse the very reference it names.
 const OWNER_REPO = /^[^\s/#]+\/[^\s/#]+$/u
-// A markdown link, with its text captured as group 1: `[text](target)`. Each class excludes *both*
-// of its delimiters — no `[`/`]` in the text, no `(`/`)` in the target — so neither star is ambiguous
-// against a nested bracket and there is nothing to backtrack.
-const MARKDOWN_LINK = /\[([^[\]]*)\]\([^()]*\)/gu
+// A markdown link: `[text](target)`. Each class excludes *both* of its delimiters — no `[`/`]` in the
+// text, no `(`/`)` in the target — so neither star is ambiguous against a nested bracket and there is
+// nothing to backtrack.
+const MARKDOWN_LINK = /\[[^[\]]*\]\([^()]*\)/gu
+// What continues a `#N` into something longer, read off the two characters after its last digit: a
+// word character (a hex color, `#1e90ff`) or a hyphen and a letter (a heading anchor, `#12-setup`) —
+// never an Issue number (joshuafolkken/kit#2995). A hyphen before a digit or `#` is a range
+// (`#12-#15`, `#3-5`), whose first number is still a citation.
+const NUMBER_CONTINUATION = /^(?:\w|-[a-z])/iu
+// The width of the window `NUMBER_CONTINUATION` reads: a hyphen and the letter after it.
+const CONTINUATION_WIDTH = 2
+// What, in the run of non-boundary characters before a `#N`, glues it into a longer token: the `&` of
+// an HTML entity (`&#39;`), the `.` of a file fragment (`README.md#12`), the `/` of a path or URL
+// fragment (`src/lib/x#5`, `example.com/#12`). Any other lead leaves it a citation — a repository
+// without its owner (`kit#12`), a verb (`fixes#12`), prose in a non-Latin script or emphasis
+// (`**#12**`) is a slip all the same. A well-formed `owner/repo#N` is read off `repo_prefix` first.
+const GLUED_LEAD = /[&./]/u
 // A fenced-code delimiter line: three or more backticks or tildes after optional indentation — both
 // delimiters CommonMark allows. Toggling on each one brackets the fenced block, so a `closes #N` shown
 // in a `gh api` example never reads as a slip whichever fence the reply drew it with.
@@ -53,27 +66,34 @@ const PR_PREFIX = /\b(?:pr|pull request)\s*$/iu
 // sits inside a span.
 const BACKTICK_PAIR = 2
 
-// Whether a markdown link's *text* span — between the `[` and the `]`, never its `(target)` — covers
-// `index`. A `#N` inside the text is the approved `[#N](url)` citation; one in the target is not
-// reachable, since an issues URL carries no `#N`.
-function text_span_covers(link: RegExpMatchArray, index: number): boolean {
-	const start = (link.index ?? 0) + 1
-	const end = start + (link[1] ?? '').length
+// Whether a markdown link covers `index`, text or target alike. A `#N` in the text is the approved
+// `[#N](url)` citation; one in the target is a page fragment (`[setup](#12)`), not an Issue.
+function link_covers(link: RegExpMatchArray, index: number): boolean {
+	const start = link.index ?? 0
 
-	return index >= start && index < end
+	return index >= start && index < start + link[0].length
 }
 
-// The line is searched for a link whose text span covers this index, so `see [#12](url) and #34`
-// reads the first as linked and the second as bare. The scan is line-based (`is_bare_at` passes one
-// line), so a link and the `#N` it wraps must sit on the same line — which they always do.
+// The line is searched for a link covering this index, so `see [#12](url) and #34` reads the first as
+// linked and the second as bare. The scan is line-based (`is_bare_at` passes one line), so a link and
+// the `#N` it wraps must sit on the same line — which they always do.
 function is_linked_at(line: string, index: number): boolean {
 	for (const link of line.matchAll(MARKDOWN_LINK)) {
-		if (text_span_covers(link, index)) return true
+		if (link_covers(link, index)) return true
 	}
 
 	return false
 }
 
+// The run of non-boundary characters that ends at the `#` — what `repo_prefix` keeps when it is an
+// `owner/repo` and `is_glued` weighs when it is not.
+function lead_token(message: string, hash_index: number): string {
+	let start = hash_index
+	while (start > 0 && !REFERENCE_BOUNDARY.test(message.charAt(start - 1))) start -= 1
+
+	return message.slice(start, hash_index)
+}
+
 // **The message text alone, never a GitHub-bound artifact.** An Issue body or comment is passed to
 // `gh` as a `Bash` argument, not spoken in `last_assistant_message`, so those never reach here — which
 // is exactly the "silent on GitHub-bound artifacts" behavior the issue asks for, obtained by what the
@@ -83,10 +103,7 @@ function is_linked_at(line: string, index: number): boolean {
 // non-boundary characters ending at the `#`, kept only when it holds a `/`. Read backwards a
 // character at a time so a repository name of any length costs its own length and no more.
 function repo_prefix(message: string, hash_index: number): string {
-	let start = hash_index
-	while (start > 0 && !REFERENCE_BOUNDARY.test(message.charAt(start - 1))) start -= 1
-
-	const token = message.slice(start, hash_index)
+	const token = lead_token(message, hash_index)
 
 	return OWNER_REPO.test(token) ? token : ''
 }
@@ -115,17 +132,25 @@ interface LineReference {
 	text: string
 }
 
-// The bare references on one line, in order — the excluded mentions (linked, inline-code, PR) already
-// dropped by `is_bare_at`, so a caller acts on citations alone.
+// Whether the `#N` is part of a longer token rather than an Issue number of its own — continued past
+// its digits, or led by an entity, file or path run (`GLUED_LEAD`) that is not an `owner/repo`.
+function is_glued(line: string, reference: LineReference): boolean {
+	const end = reference.index + reference.text.length
+
+	if (NUMBER_CONTINUATION.test(line.slice(end, end + CONTINUATION_WIDTH))) return true
+
+	return reference.prefix === '' && GLUED_LEAD.test(lead_token(line, reference.index))
+}
+
+// The bare references on one line, in order — the glued tokens (`is_glued`) and the excluded mentions
+// (linked, inline-code, PR, `is_bare_at`) already dropped, so a caller acts on citations alone.
 function line_references(line: string): ReadonlyArray<LineReference> {
 	const references: Array<LineReference> = []
 
 	for (const match of line.matchAll(ISSUE_NUMBER)) {
-		const { index } = match
+		const reference = { index: match.index, prefix: repo_prefix(line, match.index), text: match[0] }
 
-		if (is_bare_at(line, index)) {
-			references.push({ index, prefix: repo_prefix(line, index), text: match[0] })
-		}
+		if (!is_glued(line, reference) && is_bare_at(line, match.index)) references.push(reference)
 	}
 
 	return references

package/scripts/rules/lane-background.ts

@@ -20,7 +20,13 @@ import { run_tail } from './run-tail'
 //
 // **So the refusal is put at the launch, and it names the detached route.** The region from the gate to
 // the merge belongs to `pnpm josh ship --detach` in a child (`chain-rule.md` step 0), whose supervisor
-// outlives the turn. `ship` itself is not in the set: #2457 already detaches it implicitly in a child.
+// outlives the turn.
+//
+// **`ship` is in the set too, `--detach` or not** (joshuafolkken/kit#3027). #2457 detaches it in a child,
+// but only after its preflight — the scoped checks — has passed in the calling process, so a
+// backgrounded `ship` is killed at the turn's end before any supervisor exists: the #3022 child did
+// exactly that and was parked as a failure. Issued in the foreground it returns at `launched` within the
+// tool timeout, and the supervisor carries the rest.
 //
 // **Its stop-time half reads the same fact from the other side.** A backgrounded task the transcript
 // launched but never saw finish is still running, and in a child the stop about to happen kills it —
@@ -30,7 +36,7 @@ import { run_tail } from './run-tail'
 // The josh subcommands that run long enough to be backgrounded, as `time_shell` names them — canonical,
 // so the `ga` / `g` / `fu` aliases are covered by the one spelling.
 const LONG_RUNNING_COMMANDS: ReadonlySet<string> = new Set(
-	['gate', 'git', 'followup'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
+	['gate', 'git', 'followup', 'ship'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
 )
 
 const BACKGROUND_KEY = 'run_in_background'
@@ -92,11 +98,13 @@ function pending_agent_ids(tail: string): ReadonlyArray<string> {
 const LANE_BACKGROUND_REASON =
 	'⛔ lane background: this session is a dispatched lane child (`JOSH_LANE_CHILD`), a headless ' +
 	'`claude -p` process whose background Bash tasks are killed when the turn ends — so a backgrounded ' +
-	'`josh gate` / `josh git` / `josh followup` never re-invokes you; it dies at `exit code 143` ' +
-	'(joshuafolkken/kit#2704, measured on the #2606 child: implementation, review and live verification ' +
-	'done, the run parked instead of merged). Hand the gate-to-merge region to the detached supervisor ' +
-	'instead: `pnpm josh ship --detach --review "<title> #<N>"` (add `--cite <N>`), then end the turn on ' +
-	'`launched` / `busy` — `.claude/skills/workflow-commands/chain-rule.md` step 0 is the single source. A ' +
+	'`josh gate` / `josh git` / `josh followup` / `josh ship` never re-invokes you; it dies at `exit code ' +
+	'143` (joshuafolkken/kit#2704, measured on the #2606 child: implementation, review and live ' +
+	'verification done, the run parked instead of merged). Hand the gate-to-merge region to the detached ' +
+	'supervisor instead: `pnpm josh ship --detach --review "<title> #<N>"` (add `--cite <N>`) issued in ' +
+	'the foreground — its preflight runs in this process before the supervisor exists, so a backgrounded ' +
+	'`ship` dies with the turn (joshuafolkken/kit#3027) — then end the turn on `launched` / `busy`. ' +
+	'`.claude/skills/workflow-commands/chain-rule.md` step 0 is the single source. A ' +
 	'single check you must read before continuing runs in the foreground within the tool timeout; the ' +
 	'commit-push step does not — in a child it too belongs to the detached ship, in either spelling. This ' +
 	'rule fires on every occurrence, not once per run.'

package/scripts/rules/lane-park.ts

@@ -1,5 +1,6 @@
-import { NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_handoff } from '#scripts/lane/lane-handoff'
 import { shell_segments } from './shell-segments'
 
 // A dispatched lane child records its park before it stops, delivered at the call it binds on
@@ -61,7 +62,15 @@ const NOTIFY_INVOCATION = /josh\s+(?:notify|nf)\b/u
 // notify appears and a `--task-type confirmation` appears. That is looser than `is_confirmation_notify`
 // on purpose — the guard's safe direction is to read a real stop notification as present, so a run
 // that sent one is never told it did not.
+//
+// **A command that sent the Telegram itself prints this line instead** (joshuafolkken/kit#3099):
+// `run:entry` notifies from inside its own stop, so no `josh notify` invocation reaches the transcript,
+// and the line it prints is what the tail carries. One constant, printed there and matched here.
+const COMMAND_NOTIFY_MARKER = 'stop notified: a confirmation Telegram was sent by this command'
+
 function mentions_confirmation_notify(text: string): boolean {
+	if (text.includes(COMMAND_NOTIFY_MARKER)) return true
+
 	return NOTIFY_INVOCATION.test(text) && CONFIRMATION_TASK_TYPE.test(text)
 }
 
@@ -70,13 +79,18 @@ function mentions_confirmation_notify(text: string): boolean {
 // confirmation stop, not on every `Bash` call in the run. `is_child_of` is the same mechanical
 // human-or-child fact the pre-gate cut reads: a person working in a lane carries no mark and sees no
 // refusal, and a mark that leaked in naming another issue is read as a person too.
-function is_unparked_stop(
-	command: string,
-	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
-): boolean {
+//
+// **A child that handed its region to the detached ship is not parking** (joshuafolkken/kit#2962): its
+// stop waits on nobody, so the park checklist is the wrong advice. `lane_handoff.is_handed_off` is the
+// reading the `Stop` hook stands its notify demand down on, so the two hooks cannot disagree.
+function is_parking_child(directory: string = process.cwd()): boolean {
+	return lane_child_marker.is_child_of(directory) && !lane_handoff.is_handed_off(directory)
+}
+
+function is_unparked_stop(command: string, is_child: () => boolean = is_parking_child): boolean {
 	if (!is_confirmation_notify(command)) return false
 
-	return is_lane_child
+	return is_child()
 }
 
 // **Keeping this rule is applying `needs-decision`**, the one act the park asks for before the stop.
@@ -111,8 +125,10 @@ const LANE_PARK_REASON =
 	'before it stops", and the park itself is `backlogrun-park.md` → "park and continue".'
 
 const lane_park = {
+	COMMAND_NOTIFY_MARKER,
 	LANE_PARK_REASON,
 	is_confirmation_notify,
+	is_parking_child,
 	is_unparked_stop,
 	mentions_confirmation_notify,
 	records_the_park,

package/scripts/rules/last-prompt.ts

@@ -20,6 +20,7 @@ const WORKFLOW_KEYWORDS: ReadonlySet<string> = new Set([
 	'kickoff',
 	'fullrun',
 	'halfrun',
+	'prrun',
 	'backlogrun',
 ])
 const NO_PROMPT = ''

package/scripts/rules/oracle-consulted.ts

@@ -76,6 +76,6 @@ const ROWS: ReadonlyArray<DeliveredRule> = oracle_firing
 	.firing_oracles()
 	.map(({ oracle, firing_point }) => row_for(oracle, firing_point))
 
-const oracle_consulted = { ROWS, command_line, reason_for, row_for, runs_the_oracle }
+const oracle_consulted = { ROWS, reason_for }
 
 export { oracle_consulted }

package/scripts/rules/oracle-firing.ts

@@ -99,6 +99,7 @@ const NOT_NAMED: ReadonlyMap<string, string> = new Map([
 	['epic:next', READ],
 	['run:merge', PHASE],
 	['run:step', SELF],
+	['run:entry', SELF],
 	['refactor:scan', PHASE],
 	['split:assess', PHASE],
 	['sonar:hotspots', READ],

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

@@ -70,10 +70,7 @@ function main(argv: ReadonlyArray<string>): void {
 }
 
 const oracle_list_cli = {
-	format_oracle,
-	main,
 	print_list,
-	run,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))

package/scripts/rules/permission-guards.ts

@@ -0,0 +1,14 @@
+import { destructive_command } from './destructive-command'
+import { index_guard } from './index-guard'
+import { protected_files } from './protected-files'
+
+// The three rows that close the deny-list bypasses (joshuafolkken/kit#2983), gathered so
+// `delivered-rules.ts` spreads one entry. Each reads argv or a file path rather than a glob: an index
+// mutation in any git spelling, a recursive forced `rm` or a destructive `gh` call, and a Read of
+// `.env` or an edit of a consumer's `.claude/settings.json`. Their triggers are disjoint from every
+// other row's — `git restore` is split with `worktree-mutation` by `--staged` alone.
+const ROWS = [index_guard.ROW, destructive_command.ROW, protected_files.ROW] as const
+
+const permission_guards = { ROWS }
+
+export { permission_guards }

package/scripts/rules/protected-files.ts

@@ -0,0 +1,74 @@
+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'
+
+// 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.
+//
+// - **`.env` is never read.** It carries the Telegram bot token, and a Read lands it in the transcript.
+//   The scripts that need it load it in their own process, so refusing the tool 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
+//   the settings file sits in, not the session's directory — so kit's own edits (it is the file's
+//   source) and the user-level `~/.claude/settings.json`, which belongs to no repository, both pass.
+//
+// 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 ENVIRONMENT_FILE = '.env'
+const SETTINGS_FILE = path.join('.claude', 'settings.json')
+
+function file_path_of(call: GuardedCall): string {
+	if (!json_value.is_record(call.input)) return ''
+
+	const value = call.input['file_path']
+
+	return typeof value === 'string' ? value : ''
+}
+
+function is_environment_read(call: GuardedCall): boolean {
+	return call.name === READ_TOOL && path.basename(file_path_of(call)) === ENVIRONMENT_FILE
+}
+
+// The repository the settings file belongs to is two levels above it (`<root>/.claude/settings.json`).
+function is_consumer_settings_edit(
+	call: GuardedCall,
+	is_kit_consumer: (root: string) => boolean,
+): boolean {
+	if (!EDIT_TOOLS.has(call.name)) return false
+
+	const file_path = path.resolve(file_path_of(call))
+
+	if (!file_path.endsWith(`${path.sep}${SETTINGS_FILE}`)) return false
+
+	return is_kit_consumer(path.dirname(path.dirname(file_path)))
+}
+
+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)
+}
+
+const PROTECTED_FILE_REASON =
+	'⛔ protected file: `.env` holds the Telegram bot token, so reading it puts a secret in the ' +
+	'transcript — the scripts that need it load it in their own process. `.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. ' +
+	'**This rule fires on every occurrence, not once per run.**'
+
+const ROW = {
+	id: 'protected-file',
+	is_trigger: is_protected_file_call,
+	reason: PROTECTED_FILE_REASON,
+	decide: (): boolean => true,
+}
+
+const protected_files = { ROW, is_protected_file_call }
+
+export { protected_files }

package/scripts/rules/reply-language.ts

@@ -111,6 +111,6 @@ function is_mismatch(message: string, lang: string): boolean {
 	return matches_share(prose, script, pattern) < MATCH_SHARE_FLOOR
 }
 
-const reply_language = { MIN_PROSE_LETTERS, is_mismatch, script_of }
+const reply_language = { is_mismatch, script_of }
 
 export { reply_language }

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

@@ -192,11 +192,8 @@ const ROW = {
 const rule_body_guard = {
 	RULE_BODY_REASON,
 	ROW,
-	adds_rule_prose,
 	answered_placement,
 	is_rule_document,
-	prose_of,
-	runs_placement_oracle,
 	writes_rule_prose,
 }
 

package/scripts/rules/rule-value-cli.ts

@@ -117,7 +117,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 }
 
 const rule_value_cli = {
-	gather_runs,
 	group_by_run,
 	render,
 	row,

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

@@ -196,7 +196,6 @@ const SHELL_BODY_REASON =
 const shell_body_trigger = {
 	SHELL_BODY_REASON,
 	carries_a_body,
-	is_safe_body_form,
 	is_shell_evaluated_body,
 	keeps_body_safe,
 }

package/scripts/rules/shell-segments.ts

@@ -37,7 +37,6 @@ function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
 }
 
 const shell_segments = {
-	SEGMENT_SEPARATOR,
 	is_josh_command,
 	segments_of,
 }