@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/rules/index-guard.ts

@@ -46,7 +46,7 @@ function is_index_segment(segment: string): boolean {
 }
 
 function is_index_mutation(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_index_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_index_segment(segment))
 }
 
 const INDEX_MUTATION_REASON =
@@ -61,6 +61,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_index_mutation),
 	reason: INDEX_MUTATION_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Index mutation',
+		topic: '`operating-rules.md`',
+		fires:
+			'`git add` / `commit` / `reset` / `rm` / `mv` / `restore --staged` in any spelling. Every occurrence',
+		quiet: '`pnpm josh git` — the approved commit flow',
+	},
 }
 
 const index_guard = { INDEX_MUTATION_REASON, ROW, is_index_mutation }

package/scripts/rules/issue-comments.ts

@@ -1,3 +1,7 @@
+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 { bash_triggers } from './bash-triggers'
 import { gh_api } from './gh-api'
 import { prior_comment_read } from './prior-comment-read'
@@ -17,7 +21,7 @@ const ISSUE_VIEW_COMMAND = new RegExp(String.raw`^gh\s+${gh_api.GH_FLAGS}issue\s
 // (`…/issues`) and every sub-resource under it (`…/issues/1319/comments`) are left alone.
 const ISSUE_BODY_PATH = /repos\/[^\s'"]*\/issues\/\d+(?=$|["'\s])/u
 // **A write to that path is not a read of it**, which is why the body read below asks `gh_api.is_read`:
-// `gh api` sends POST as soon as any field flag appears, and `kickoff` PATCHes `…/issues/<N>` to
+// `gh api` sends POST as soon as any field flag appears, and a run PATCHes `…/issues/<N>` to
 // normalize a title and to fill a blank body — so without the read check the delivery would be spent
 // refusing a write, and the genuine body read later in the same run would never be guarded.
 // A segment that fetches comments: the flag, a `comments` field in a `--json` projection, or the
@@ -77,6 +81,9 @@ function reads_issue_comments(command: string): boolean {
 	return shell_segments.segments_of(command).some((segment) => fetches_issue_comments(segment))
 }
 
+const RULE_DOC = '`.claude/skills/workflow-commands/issue-comments.md`'
+const COMMENTS_FALLBACK = 'gh api repos/{owner}/{repo}/issues/<N>/comments'
+
 // **The refusal hands over the command that fixes it**, because reading is not the same as
 // obeying: a sentence saying "also read the comments" is prose that moves nothing, while a refused
 // body read leaves the run holding the reissue that makes the comments *present*. The conflict rule
@@ -88,12 +95,62 @@ function reads_issue_comments(command: string): boolean {
 // being the Issue the refused call named — so a run that reads only the opening still leaves holding
 // the fix. The label keeps `time_transcript_line.guard_from_refusal` naming this guard, not the command.
 const ISSUE_COMMENTS_REASON =
-	'⛔ issue comments: pnpm josh issue:read <N>\n' +
-	"Run that in place of this read — an Issue's comments are part of it, and a later comment " +
-	'supersedes the body it contradicts; refused until that command is on the transcript. Without ' +
-	'josh, read ' +
-	'`gh api repos/{owner}/{repo}/issues/<N>/comments` beside the body ' +
-	'(`.claude/skills/workflow-commands/issue-comments.md`).'
+	`⛔ issue comments: pnpm josh issue:read <N>\n` +
+	`Run that in place of this read — an Issue's comments are part of it, and a later comment ` +
+	`supersedes the body it contradicts; refused until that command is on the transcript. Without ` +
+	`josh, read \`${COMMENTS_FALLBACK}\` beside the body (${RULE_DOC}).`
+
+// **A `gh api` body read is rewritten rather than refused** (joshuafolkken/kit#3920): the fix is the
+// same Issue's comments endpoint, read on the same line, and the path the call already names is all
+// it needs. Prepended on lines of their own, so a trailing comment or a `&&` chain on the typed line
+// cannot swallow or skip them, and the typed line stays last — its exit status is still the call's.
+// A `gh issue view` read is left to the refusal — its global flags (`--repo`) and its `--json`
+// projection have no one comments spelling to add.
+const COMMENTS_JQ = String.raw`'.[] | "— \(.user.login) \(.created_at)\n\(.body)\n"'`
+
+const COMMENTS_NOTE =
+	"↻ issue comments: this read returned only the Issue's body, so the Issue's comments were fetched " +
+	`on the same line — a later comment supersedes the body it contradicts (${RULE_DOC}).`
+
+// **Only a line that opens with the body read is rewritten.** Prepended ahead of a `cd` or a
+// subshell, the comments read would resolve `{owner}/{repo}` in another directory and print another
+// repository's comments; and the line is cut on its quote-blanked reading, so a body-read spelling
+// quoted in a string or a heredoc body is never prepended as a real call. Every other line keeps the
+// refusal.
+function rewritable_path(command: string): string | undefined {
+	const read = shell_segments.first_of(command)
+
+	if (read === undefined || ISSUE_VIEW_COMMAND.test(read)) return undefined
+
+	return is_body_read_segment(read) ? ISSUE_BODY_PATH.exec(read)?.[0] : undefined
+}
+
+function comments_command(command: string): string | undefined {
+	if (!is_body_only_issue_read(command)) return undefined
+
+	const path = rewritable_path(command)
+
+	if (path === undefined) return undefined
+
+	return `gh api --paginate ${path}/comments --jq ${COMMENTS_JQ}\n${command}`
+}
+
+// The call's input with the comments read prepended, or `undefined` where the comments are already on
+// the tail or the read has no rewritable spelling.
+function comments_input(
+	call: GuardedCall,
+	tail: () => string,
+): Record<string, unknown> | undefined {
+	if (call.name !== cost_blocks.BASH_TOOL || !json_value.is_record(call.input)) return undefined
+
+	const command = comments_command(time_shell.bash_command(call.input))
+
+	if (command === undefined || prior_comment_read.already_read_for_call(tail(), call)) {
+		return undefined
+	}
+
+	return { ...call.input, command }
+}
 
 // The enumeration row itself, so `delivered-rules.ts` spreads one entry. `already_satisfied` stands it
 // down once the comments are on the transcript tail, and until then it refuses every body-only read.
@@ -103,13 +160,25 @@ const ROW = {
 	reason: ISSUE_COMMENTS_REASON,
 	already_satisfied: prior_comment_read.already_read_for_call,
 	keeps: bash_triggers.on_bash_command(reads_issue_comments),
+	rewrite: comments_input,
+	rewrite_note: COMMENTS_NOTE,
 	// The opening the reason carried before it led with the command.
 	former_reasons: ["⛔ an Issue's comments are part of the Issue: read them before implementing"],
+	about: {
+		title: 'Reading Issue comments',
+		topic: '`issue-comments.md`',
+		fires:
+			'a `Bash` that reads only the Issue body (`gh issue view <N>`, or a GET ending in `…/issues/<N>`). Refused until it is re-read with the comments',
+		quiet:
+			'no Issue read, or a read with `--comments` / `--json comments` / `…/comments` from the start',
+	},
 }
 
 const issue_comments = {
+	COMMENTS_NOTE,
 	ISSUE_COMMENTS_REASON,
 	ROW,
+	comments_input,
 	is_body_only_issue_read,
 }
 

package/scripts/rules/josh-git-bare.ts

@@ -66,6 +66,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_bare_josh_git),
 	reason: JOSH_GIT_BARE_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Bare `pnpm josh git`',
+		topic: '`CLAUDE.md` → Git Rules',
+		fires:
+			'`pnpm josh git` without `-y`, whose staging prompt cancels with no TTY. Every occurrence',
+		quiet: '`pnpm josh git -y`',
+	},
 }
 
 const josh_git_bare = {

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 = {