@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/rules/lane-background.ts

@@ -26,7 +26,7 @@ import { run_tail_rule } from './run-tail-rule'
 // killed at the turn's end before any supervisor exists. Issued in the foreground it returns at
 // `launched` within the tool timeout, and the supervisor carries the rest. A backgrounded `ship` alone
 // is not refused but rewritten into that foreground call (`foreground_input`); one chained after
-// another long command is refused.
+// another long command is refused. A foreground `ship` without the cap is given it the same way.
 //
 // **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 —
@@ -43,9 +43,10 @@ const LONG_RUNNING_COMMANDS: ReadonlySet<string> = new Set([
 
 const BACKGROUND_KEY = 'run_in_background'
 const TIMEOUT_KEY = 'timeout'
-// The longest a foreground Bash call may run. A backgrounded call rarely carries a `timeout`, and one that
-// does may exceed the foreground cap, so the rewrite sets it: left at the two-minute default, a preflight
-// whose scoped pair outruns it is cut before `launched`, the #3027 failure the rewrite exists to avoid.
+// The longest a foreground Bash call may run. A `ship` rarely carries a `timeout`, and a backgrounded one
+// that does may exceed the foreground cap, so the rewrite sets it: left at the two-minute default, a
+// preflight whose scoped pair outruns it is cut before `launched` (#3027) or moved to the background and
+// killed with the turn (#4101).
 const FOREGROUND_TIMEOUT_MS = 600_000
 
 function is_backgrounded(input: unknown): boolean {
@@ -101,38 +102,72 @@ function is_background_long_run(
 	return is_candidate(call) && is_lane_child()
 }
 
-// **A backgrounded `ship` in a child is rewritten, not refused**. The refusal
-// asked for nothing but the same call in the foreground — 14 of 41 lane `ship` refusals in one measured
-// backlogrun were that round trip, paid at the run's largest context. The input with the flag cleared,
-// or `undefined` for every call this does not apply to.
+// The input of a Bash call whose long-running work is `ship` alone, or `undefined` for any other call.
+function ship_alone_input(call: GuardedCall): Record<string, unknown> | undefined {
+	if (call.name !== cost_blocks.BASH_TOOL || !json_value.is_record(call.input)) return undefined
+
+	return ships_alone(time_shell.bash_command(call.input)) ? call.input : undefined
+}
+
+// A foreground call that already carries the foreground cap, which the harness never moves aside.
+function is_capped_foreground(input: Record<string, unknown>): boolean {
+	const timeout = input[TIMEOUT_KEY]
+
+	return !is_backgrounded(input) && typeof timeout === 'number' && timeout >= FOREGROUND_TIMEOUT_MS
+}
+
+// **A `ship` in a child is run in the foreground at the cap, not refused**. The refusal of a
+// backgrounded one asked for nothing but the same call in the foreground — 14 of 41 lane `ship`
+// refusals in one measured backlogrun were that round trip, paid at the run's largest context.
+//
+// A foreground one at the two-minute default is moved aside once its preflight outruns it, and dies
+// the same way (joshuafolkken/kit#4101). The input with the flag cleared and the cap set, or
+// `undefined` for every call this does not apply to.
 function foreground_input(
 	call: GuardedCall,
 	is_lane_child: () => boolean = () => lane_child_marker.is_child_of(process.cwd()),
 ): Record<string, unknown> | undefined {
-	if (!is_backgrounded_ship(call) || !json_value.is_record(call.input) || !is_lane_child()) {
-		return undefined
-	}
+	const input = ship_alone_input(call)
+
+	if (input === undefined || is_capped_foreground(input) || !is_lane_child()) return undefined
 
-	return { ...call.input, [BACKGROUND_KEY]: false, [TIMEOUT_KEY]: FOREGROUND_TIMEOUT_MS }
+	return { ...input, [BACKGROUND_KEY]: false, [TIMEOUT_KEY]: FOREGROUND_TIMEOUT_MS }
 }
 
 const FOREGROUND_NOTE =
-	'lane background: this lane child backgrounded `josh ship`, which would die with the headless turn ' +
-	'before its supervisor exists — so it was run in the foreground instead, where it detaches itself ' +
-	'after the preflight. End the turn on `launched` / `busy`.'
+	"lane background: a lane child's `josh ship` backgrounded, by its flag or by outrunning the Bash " +
+	'timeout, dies with the headless turn before its supervisor exists — so it was run in the ' +
+	'foreground at the 600000 ms cap, where it detaches itself after the preflight. End the turn on ' +
+	'`launched` / `busy`.'
+
+type LaunchedIds = (block: TranscriptBlock) => ReadonlyArray<string>
+
+// One line's word on each id: a launch opens it, a finish notice closes it.
+function apply_line(open: Set<string>, line: string, launched_ids: LaunchedIds): void {
+	const parsed = time_transcript_line.parse_line(line)
+
+	if (parsed === undefined) return
+
+	const launched = parsed.blocks.flatMap((block) => launched_ids(block))
+
+	for (const id of launched) open.add(id)
+	open.delete(parsed.finished_background)
+}
 
 // The launches `launched_ids` reads off the transcript tail that never saw their finish. A launch is
-// read off its own tool result and a finish off the harness notice, both by `time_transcript_line`.
-function unfinished_ids(
-	tail: string,
-	launched_ids: (block: TranscriptBlock) => ReadonlyArray<string>,
-): ReadonlyArray<string> {
-	const lines = tail.split('\n').map((line) => time_transcript_line.parse_line(line))
-	const finished = new Set(lines.map((line) => line?.finished_background ?? ''))
-	const blocks = lines.flatMap((line) => line?.blocks ?? [])
-	const launched = blocks.flatMap((block) => launched_ids(block))
+// read off its own tool result and a finish off the harness notice or a `TaskStop` result, both by
+// `time_transcript_line`.
+//
+// **Read in order, so the later word on an id wins.** A subagent resumed by `SendMessage` runs again
+// under the id its first run's notice already named; a set of every finish ever seen would read the
+// resumed run as finished (joshuafolkken/kit#4347).
+function unfinished_ids(tail: string, launched_ids: LaunchedIds): ReadonlyArray<string> {
+	const open = new Set<string>()
+
+	for (const line of tail.split('\n')) apply_line(open, line, launched_ids)
+	open.delete('')
 
-	return launched.filter((id) => id !== '' && !finished.has(id))
+	return [...open]
 }
 
 // The background tasks the tail launched and never saw finish — commands and subagents alike,
@@ -167,6 +202,13 @@ const ROW = {
 	is_trigger: (call: GuardedCall): boolean => is_background_long_run(call),
 	reason: LANE_BACKGROUND_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Lane child background push',
+		topic: '`.claude/skills/workflow-commands/background-commands.md`',
+		fires:
+			'a dispatched lane child backgrounding `josh gate` / `git` / `followup` / `ship`; it hands over `pnpm josh ship --detach`. Every occurrence',
+		quiet: 'not a lane child, or the foreground `ship --detach`',
+	},
 }
 
 const lane_background = {

package/scripts/rules/lane-carry-conflict.ts

@@ -109,6 +109,12 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_carry_conflict),
 	reason: LANE_CARRY_CONFLICT_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Lane child carry commands',
+		topic: '`.claude/skills/workflow-commands/backlogrun-lanes.md`',
+		fires: 'a dispatched lane child running `pnpm josh run:merge` / `run:carry`. Every occurrence',
+		quiet: 'not a lane child — the parent owns the run budget',
+	},
 }
 
 const lane_carry_conflict = {

package/scripts/rules/lane-direct-tool.ts

@@ -0,0 +1,74 @@
+import { command_memory } from '#scripts/gate/command-memory'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { bash_triggers } from './bash-triggers'
+
+// A dispatched lane child is stopped from running a heavy tool directly. The core budget
+// (`scripts/gate/core-budget.ts`) counts only what a `josh` command reserves, so an `eslint`, `vitest`,
+// `cspell` or `tsc` a lane agent launches itself is neither refused nor counted: it overlaps the other
+// lanes' gates and shows up only as unexplained load to whatever is admitted next.
+//
+// **Every spelling collapses to the tool's name.** `command_memory.tool_calls_of` skips the wrapper
+// words (`pnpm`, `npx`, `exec`, env assignments) and reads a shell's quoted script (`sh -c '…'`,
+// `bash -c "…"`, `eval`) as the commands it runs, so `pnpm exec eslint`, `npx vitest`, `pnpm tsc`, a
+// bare `cspell` and any of them inside `sh -c` are all read as the program they launch. A
+// `pnpm josh …` reads as `josh` and passes — that is the budgeted path, and the command
+// `pnpm josh reserved-run <weight> -- <command>` wraps is read as reserved.
+//
+// **A multi-worker eslint is refused even when reserved** (joshuafolkken/kit#4582): typed eslint holds a
+// TypeScript program per worker, so `--concurrency 4` or `auto` held 12 GB in one lane and swapped the
+// machine. `--concurrency off`, `1` and no flag pass.
+//
+// **Lane children only.** An interactive session outside a lane keeps its direct runs; the overlap this
+// prevents is between concurrently dispatched lanes.
+
+const HEAVY_TOOLS: ReadonlySet<string> = new Set(['eslint', 'vitest', 'cspell', 'tsc'])
+
+// True when any command on the shell line launches one of the heavy tools outside a `reserved-run`.
+// The cut is quote-aware, so a tool name inside a quoted argument (`git commit -m "run eslint"`) is
+// never read as a command; a quoted script handed to a shell is.
+function runs_heavy_tool(command: string): boolean {
+	return command_memory
+		.tool_calls_of(command)
+		.some((call) => !call.is_reserved && HEAVY_TOOLS.has(call.name))
+}
+
+// True when this session is a dispatched lane child launching a heavy tool directly, or eslint with
+// more than one worker by any path.
+function is_lane_direct_tool(
+	command: string,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): boolean {
+	if (!is_lane_child) return false
+
+	return runs_heavy_tool(command) || command_memory.runs_multi_worker_eslint(command)
+}
+
+const LANE_DIRECT_TOOL_REASON =
+	'⛔ lane child running `eslint` / `vitest` / `cspell` / `tsc` directly, or multi-worker eslint: ' +
+	'it overlaps the other lanes. Run `pnpm josh lint:related`, `pnpm josh test:related`, ' +
+	'`pnpm josh cspell:dot` or `pnpm josh reserved-run <weight> -- <command>`, eslint at ' +
+	'`--concurrency off`; measure concurrency outside a lane. Refused on every occurrence.'
+
+// The row itself, so `delivered-rules.ts` spreads one entry; the shape is `lane-switch-main.ts`'s.
+const ROW = {
+	id: 'lane-direct-tool',
+	is_trigger: bash_triggers.on_bash_command(is_lane_direct_tool),
+	reason: LANE_DIRECT_TOOL_REASON,
+	decide: (): boolean => true,
+	about: {
+		title: 'Lane child running a heavy tool directly',
+		topic: '`docs/josh-commands-automation.md` → `josh reserved-run`',
+		fires:
+			'a dispatched lane child launching `eslint` / `vitest` / `cspell` / `tsc` (bare, `pnpm exec`, `npx`, inside `sh -c`), or eslint with `--concurrency` other than `off` / `1` by any path, `reserved-run` included. Every occurrence',
+		quiet: 'not a lane child, or the run goes through `pnpm josh` with single-worker eslint',
+	},
+}
+
+const lane_direct_tool = {
+	LANE_DIRECT_TOOL_REASON,
+	ROW,
+	is_lane_direct_tool,
+	runs_heavy_tool,
+}
+
+export { lane_direct_tool }

package/scripts/rules/lane-interactive-ask.ts

@@ -43,8 +43,7 @@ function is_interactive_ask(
 const LANE_INTERACTIVE_ASK_REASON =
 	'⛔ lane child interactive ask: this session is a dispatched lane child and cannot ask a ' +
 	'person, so park instead: ' +
-	"`gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'`, " +
-	'`pnpm josh issue:comment <N> --body-file <path>`, ' +
+	'`pnpm josh run:park <N> --body-file <path>` (it applies `needs-decision`), ' +
 	'the `confirmation` Telegram, stop. It fires on every occurrence ' +
 	'(`.claude/skills/workflow-commands/pre-gate-cut.md`, `backlogrun-park.md`).'
 
@@ -56,6 +55,14 @@ const ROW = {
 	is_trigger: is_interactive_ask,
 	reason: LANE_INTERACTIVE_ASK_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Lane child interactive ask',
+		topic:
+			'`.claude/skills/workflow-commands/pre-gate-cut.md` → "The interactive ask is refused one call earlier"',
+		fires:
+			"a dispatched lane child's `AskUserQuestion`; it hands over the park procedure. Every occurrence",
+		quiet: 'not a lane child, or not an interactive tool',
+	},
 }
 
 const lane_interactive_ask = { LANE_INTERACTIVE_ASK_REASON, ROW, is_interactive_ask }

package/scripts/rules/lane-park.ts

@@ -1,6 +1,7 @@
 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 { run_park } from '#scripts/run/park/run-park'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
 
@@ -19,15 +20,12 @@ import { shell_segments } from './shell-segments'
 // confirmation` is the call every lane-child stop passes through. The agent that obeys this is always
 // a `claude -p` child, so the rule leaves residency entirely (`prompts/collaboration-workflow/rule-delivery.md`).
 //
-// **Why once per run and not a synchronous compliance check.** The pre-gate cut can stay silent on a
-// compliant run because the cut record is a local file it reads synchronously; the park is a label on
-// GitHub, which a `PreToolUse` guard cannot read (it answers synchronously, network calls are out).
-// Scanning the transcript tail for the label instead is unsafe in the one direction that matters: a
-// child that merely *read* `backlogrun-park.md`, whose prose carries the very `labels[]=needs-decision`
-// command, would look compliant and the guard would fall silent on a real violation — the whole bug,
-// reappearing inside its own check. So the row carries no `already_satisfied`: it fires once per run on
-// the stop, the reason is a checklist rather than an accusation, and a child that already parked simply
-// reissues. One wasted round trip on the compliant path is the safe direction; a missed park is not.
+// **A parked child is silent, read off the local park record.** The park is a label on GitHub, which a
+// `PreToolUse` guard cannot read (it answers synchronously, network calls are out), and scanning the
+// transcript tail for the label is unsafe: a child that merely *read* `backlogrun-park.md` would look
+// compliant. So `pnpm josh run:park` writes a local record once the comment and the label are both on
+// the issue, and the guard reads it synchronously, the way the pre-gate cut guard reads the cut record
+// (joshuafolkken/kit#4132). A child with no record still gets the once-per-run checklist.
 
 // `josh notify`, named canonically — `shell_segments.is_josh_command` expands an alias before the match.
 const NOTIFY_COMMANDS: ReadonlySet<string> = new Set(['notify'])
@@ -85,22 +83,42 @@ 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 {
+// A parking child that has not parked yet: `run:park` left no record for its issue in this repository.
+// Kept apart from `is_parking_child`, which `run:entry` reads to leave a lane child's stop to this row
+// whether or not it has parked.
+function is_unparked_child(directory: string = process.cwd()): boolean {
+	if (!is_parking_child(directory)) return false
+
+	const issue = lane_child_marker.marked_issue()
+
+	return issue === undefined || !run_park.is_parked_sync(issue, directory)
+}
+
+function is_unparked_stop(command: string, is_child: () => boolean = is_unparked_child): boolean {
 	if (!is_confirmation_notify(command)) return false
 
 	return is_child()
 }
 
 // **Keeping this rule is applying `needs-decision`**, the one act the park asks for before the stop.
-// It reads an actual `Bash` command — a label application by REST or by `gh issue edit` — never the
-// transcript tail, so a doc read that quotes the command is not mistaken for the run making it.
+// It reads an actual `Bash` command — `josh run:park`, or a label application by REST or by
+// `gh issue edit` — never the transcript tail, so a doc read that quotes the command is not mistaken
+// for the run making it. `run:park --clear` takes the park off, so it is not one.
 const APPLIES_NEEDS_DECISION = new RegExp(
 	String.raw`(?:labels\[\]=|--add-label[= ]'?)${NEEDS_DECISION_LABEL}\b`,
 	'u',
 )
+const PARK_COMMANDS: ReadonlySet<string> = new Set(['run:park'])
+const CLEAR_FLAG = /(?:^|\s)--clear\b/u
+
+function is_park_command(segment: string): boolean {
+	return shell_segments.is_josh_command(segment, PARK_COMMANDS) && !CLEAR_FLAG.test(segment)
+}
 
 function records_the_park(command: string): boolean {
-	return APPLIES_NEEDS_DECISION.test(command)
+	if (APPLIES_NEEDS_DECISION.test(command)) return true
+
+	return shell_segments.segments_of(command).some((segment) => is_park_command(segment))
 }
 
 // The instruction in the shape a refusal can carry: what the stop must leave behind, how to record it,
@@ -109,24 +127,27 @@ function records_the_park(command: string): boolean {
 // clone `CLAUDE.md` prohibits.
 const LANE_PARK_REASON =
 	'⛔ lane child park: this session is a dispatched lane child, so a stop for a person parks first: ' +
-	"`gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'`; " +
-	'`pnpm josh issue:comment <N> --body-file <path>` (question, options, stash); a ' +
+	'`pnpm josh run:park <N> --body-file <path>` (question, options, stash — it applies ' +
+	'`needs-decision`); a ' +
 	'`needs-human-review` / `already-done` stop already is. Reissue this notify, once per run ' +
 	'(`.claude/skills/workflow-commands/pre-gate-cut.md`).'
 
-// The row itself, so `delivered-rules.ts` spreads one entry. **Once per run rather than `decide`, and
-// no `already_satisfied`.** The stop ends the turn, so it is not the recurring act `decide` is for. It carries no `already_satisfied` because the park it asks for is a GitHub label a
-// synchronous guard cannot read, and the transcript-tail alternative would read a child that merely
-// *read* `backlogrun-park.md` — whose prose carries the `labels[]=needs-decision` command — as
-// compliant and fall silent on a real violation (the header above). `keeps` reads an actual
-// label-application `Bash` command, never the tail, so it is not fooled the same way; `reaches` stays
-// `is_trigger`, since a compliant run issues the same confirmation notify and belongs in the
-// denominator.
+// The row itself, so `delivered-rules.ts` spreads one entry. **Once per run rather than `decide`.** The
+// stop ends the turn, so it is not the recurring act `decide` is for. A parked child is excluded in the
+// trigger itself (`is_unparked_child`), so the park record is the satisfaction and no
+// `already_satisfied` reads the tail. `keeps` reads an actual park `Bash` command, never the tail, so a
+// doc read that quotes one is not mistaken for it.
 const ROW = {
 	id: 'lane-park',
 	is_trigger: bash_triggers.on_bash_command(is_unparked_stop),
 	reason: LANE_PARK_REASON,
 	keeps: bash_triggers.on_bash_command(records_the_park),
+	about: {
+		title: 'Lane child park',
+		topic: '`.claude/skills/workflow-commands/pre-gate-cut.md`',
+		fires: 'a dispatched lane child issuing `pnpm josh notify --task-type confirmation`',
+		quiet: 'not a lane child, or not a stop notification',
+	},
 }
 
 const lane_park = {
@@ -135,6 +156,7 @@ const lane_park = {
 	ROW,
 	is_confirmation_notify,
 	is_parking_child,
+	is_unparked_child,
 	is_unparked_stop,
 	mentions_confirmation_notify,
 	records_the_park,

package/scripts/rules/lane-split-park.ts

@@ -24,11 +24,12 @@ import { tail_commands } from './tail-commands'
 // `josh epic`, named canonically — `shell_segments.is_josh_command` expands an alias before the match.
 const EPIC_COMMANDS: ReadonlySet<string> = new Set(['epic'])
 const PROMOTED_ISSUE = /--promote[=\s]+["']?(?<issue>\d+)\b/u
-// The issue a label write targets, in the two spellings `lane_park.records_the_park` accepts: the REST
-// path `…/issues/<N>/labels` and `gh issue edit <N>`.
+// The issue a label write targets, in the spellings `lane_park.records_the_park` accepts: the REST
+// path `…/issues/<N>/labels`, `gh issue edit <N>` and `josh run:park <N>`.
 const LABEL_TARGETS: ReadonlyArray<RegExp> = [
 	/\/issues\/(?<issue>\d+)\/labels\b/u,
 	/\bissue\s+edit\s+["']?(?<issue>\d+)\b/u,
+	/\brun:park\s+["']?(?<issue>\d+)\b/u,
 ]
 // The issue a confirmation notify is about, read off its `--issue-url` the way `stop-rules.ts` spells it.
 const ISSUE_URL = /--issue-url[=\s]+["']?([^\s"']+)/u
@@ -111,6 +112,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_candidate),
 	reason: LANE_SPLIT_PARK_REASON,
 	decide,
+	about: {
+		title: 'A split is not a park',
+		topic: '`.claude/skills/workflow-commands/backlogrun-park.md` → "Splitting a child mid-run"',
+		fires:
+			'a lane child that promoted its Issue to an epic this run parking it (`needs-decision`, `confirmation` notify). Every occurrence',
+		quiet: 'no promotion this run',
+	},
 }
 
 const lane_split_park = {

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

@@ -120,6 +120,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_switch_away_from_lane),
 	reason: LANE_SWITCH_MAIN_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Lane child on `git switch main`',
+		topic: '`.claude/skills/workflow-commands/backlogrun-lanes.md`',
+		fires:
+			'a dispatched lane child switching to the default branch or running `josh main:sync`. Every occurrence',
+		quiet: 'not a lane child — `pnpm josh main:merge` brings the default in at the gate',
+	},
 }
 
 const lane_switch_main = {

package/scripts/rules/oracle-consulted.ts

@@ -55,6 +55,15 @@ function reason_for(oracle: Oracle, firing_point: FiringPoint): string {
 	)
 }
 
+// One description for every generated row: the rule is the same act whichever oracle it names.
+const ABOUT: DeliveredRule['about'] = {
+	title: 'An act its oracle was not asked about',
+	topic: '`decision-oracle.ts`',
+	fires:
+		'a `Bash` governed by an oracle that declared a firing point (`pkg:scout` governs `pnpm add`), issued without that `pnpm josh <command>`. Refused until it ran',
+	quiet: 'no governed act, or the oracle already ran',
+}
+
 function row_for(oracle: Oracle, firing_point: FiringPoint): DeliveredRule {
 	const names = command_names(oracle)
 
@@ -65,6 +74,7 @@ function row_for(oracle: Oracle, firing_point: FiringPoint): DeliveredRule {
 		already_satisfied: (tail: string, _call: GuardedCall): boolean =>
 			tail_commands.prior_bash_commands(tail).some((command) => runs_the_oracle(command, names)),
 		keeps: bash_triggers.on_bash_command((command: string) => runs_the_oracle(command, names)),
+		about: ABOUT,
 	}
 }
 

package/scripts/rules/oracle-firing.ts

@@ -90,6 +90,7 @@ const NOT_NAMED: ReadonlyMap<string, string> = new Map([
 	['run:cut:gate', SELF],
 	['backlog:budget', READ],
 	['run:liveness', READ],
+	['stash:push', SELF],
 	['stash:pop', SELF],
 	['backlog:next', READ],
 	['auto-ok:next', READ],

package/scripts/rules/permission-guards.ts

@@ -1,6 +1,7 @@
 import { destructive_command } from './destructive-command'
 import { direct_pr_create } from './direct-pr-create'
 import { index_guard } from './index-guard'
+import { pr_merge } from './pr-merge'
 import { protected_files } from './protected-files'
 
 // The three rows that close the deny-list bypasses, gathered so
@@ -10,11 +11,13 @@ import { protected_files } from './protected-files'
 // other row's — `git restore` is split with `worktree-mutation` by `--staged` alone. The fourth row,
 // `direct-pr-create`, closes the same kind of gap for `gh pr create`, which
 // the deny list never listed: it claims `gh pr create` and a `gh api` write to the pulls collection.
+// The fifth, `pr-merge`, claims a merge in every spelling the `gh pr merge*` glob misses.
 const ROWS = [
 	index_guard.ROW,
 	destructive_command.ROW,
 	protected_files.ROW,
 	direct_pr_create.ROW,
+	pr_merge.ROW,
 ] as const
 
 const permission_guards = { ROWS }

package/scripts/rules/piped-verification.ts

@@ -16,7 +16,7 @@ import { shell_segments } from './shell-segments'
 // document, prompt and skill in this repository found exactly one piped verification example, and it
 // was the repository's own explanation of this bug — so there were no examples to rewrite, and the
 // pipe is invented each time rather than copied. The other candidate, a calling convention, had
-// already been rejected in writing by `scripts/time/time-reported-failure.ts`: a convention is obeyed
+// already been rejected in writing by `tools/time/time-reported-failure.ts`: a convention is obeyed
 // or it is not. `prompts/collaboration-workflow/output-bounds.md` is the single source for the rule.
 //
 // It lives beside the enumeration rather than inside it because `delivered-rules.ts` is the list —

package/scripts/rules/poll-loop.ts

@@ -102,6 +102,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. 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` when the ' +
+	'run authorizes it; otherwise leave it to the user (`CLAUDE.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: '`CLAUDE.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_pr_merge }
+
+export { pr_merge }