@joshuafolkken/kit 1.1136.0 → 1.1166.0

package/scripts/rules/file-body.ts

@@ -14,31 +14,67 @@ import { shell_segments } from './shell-segments'
 // existing file, and a synchronous `stat` decides it — a new-file creation and a read-only heredoc stay
 // silent, an existing-file rewrite is refused.
 //
-// **Three shapes, one row.** (1) A heredoc whose redirect or `tee` target already exists. (2) an
+// **Four shapes, one row.** (1) A heredoc whose redirect or `tee` target already exists. (2) an
 // interpreter reading a heredoc — or a `node -e` — whose body writes a file: the canonical `python3 -
 // <<'PY' … open(f,'w') … PY`, which has no shell redirect to stat, is caught by its body instead. (3)
-// an in-place `perl -0pi -e`. A read-only heredoc (`cat <<'EOF'`, a compute-only `python3 -`) writes
-// nothing and stays silent — the enumeration's rule that a non-firing turn is a kept turn.
+// an in-place `perl -0pi -e`. (4) a heredoc creating an interpreter script whose body writes. Each is
+// read on every command line, not only the first. A read-only heredoc (`cat <<'EOF'`, a compute-only
+// `python3 -`) writes nothing and stays silent — the enumeration's rule that a non-firing turn is a
+// kept turn.
 //
 // **It fires on every occurrence** (`git-force.ts`): each inline body is paid for again, so
 // refused-once-and-free-after would let the second rewrite through.
 
-// A heredoc marker in any of its spellings: `<<EOF`, `<< 'EOF'`, `<<-"EOF"`. Its presence is what
-// separates a body-carrying write from an ordinary redirect a run legitimately uses to extract text.
-const HEREDOC = /<<-?\s*['"]?\w+/u
-// The first physical line carries the command, its redirect and the heredoc marker; the body follows on
-// the lines after it. The two are read separately so the redirect target is found on the command line
-// and the write indicators are scanned in the body.
+// A heredoc marker in any of its spellings: `<<EOF`, `<< 'EOF'`, `<<-"EOF"`, with its delimiter captured.
+// Its presence is what separates a body-carrying write from an ordinary redirect a run legitimately uses
+// to extract text. A here-string (`<<<`) and an arithmetic shift (`$((1<<2))`) carry no body, so a third
+// `<` on either side and a digit delimiter are excluded.
+const HEREDOC = /(?<!<)<<(?!<)-?\s*['"]?([A-Z_a-z]\w*)/u
 const LINE_BREAK = '\n'
 
-function first_line(command: string): string {
-	const [line] = command.split(LINE_BREAK)
+function has_heredoc(command: string): boolean {
+	return HEREDOC.test(command)
+}
 
-	return line ?? ''
+// The lines the shell reads as commands — every physical line outside a heredoc body — each paired with
+// the heredoc body it opened. A command, its redirect and its heredoc marker share one of these; the body
+// follows up to the delimiter line. Reading only the first physical line missed the interpreter a run
+// opened after a `cd <lane>` line (joshuafolkken/kit#3155), so every command line is read, a body line is
+// never mistaken for one, and a write is judged only in the body its own command opened.
+interface CommandLine {
+	text: string
+	body: string
 }
 
-function has_heredoc(command: string): boolean {
-	return HEREDOC.test(command)
+interface LineScan {
+	lines: ReadonlyArray<CommandLine>
+	delimiter: string | undefined
+}
+
+function with_body_line(lines: ReadonlyArray<CommandLine>, line: string): Array<CommandLine> {
+	const opener = lines.at(-1)
+
+	if (opener === undefined) return [...lines]
+
+	return [...lines.slice(0, -1), { ...opener, body: `${opener.body}${line}${LINE_BREAK}` }]
+}
+
+function scan_line(scan: LineScan, line: string): LineScan {
+	if (scan.delimiter === undefined) {
+		return { lines: [...scan.lines, { text: line, body: '' }], delimiter: HEREDOC.exec(line)?.[1] }
+	}
+
+	if (line.trim() === scan.delimiter) return { ...scan, delimiter: undefined }
+
+	return { ...scan, lines: with_body_line(scan.lines, line) }
+}
+
+function command_lines(command: string): ReadonlyArray<CommandLine> {
+	let scan: LineScan = { lines: [], delimiter: undefined }
+
+	for (const line of command.split(LINE_BREAK)) scan = scan_line(scan, line)
+
+	return scan.lines
 }
 
 // A file redirect (`> path`, `>> path`) or a `tee path`, with the target captured. A descriptor
@@ -53,40 +89,56 @@ function redirect_target(line: string): string | undefined {
 	return target === undefined ? undefined : target.replaceAll(QUOTES, '')
 }
 
-// Shape 1: a heredoc write whose target already exists. The existence check is injected so the suite
-// controls it without touching the real filesystem, the same way `lane-park.ts` injects the lane fact.
-function writes_existing_file(command: string, has_file: (path: string) => boolean): boolean {
-	if (!has_heredoc(command)) return false
-
-	const target = redirect_target(first_line(command))
-
-	return target !== undefined && has_file(target)
-}
-
 // The interpreters that carry a body to run rather than a region to read. `cat` / `grep` / `sed -n`
 // are deliberately absent — a heredoc fed to them is the read-only form `file-edits.md` allows.
-const BODY_INTERPRETERS: ReadonlySet<string> = new Set(['python', 'python3', 'ruby', 'perl', 'php'])
+const BODY_INTERPRETERS: ReadonlySet<string> = new Set([
+	'python',
+	'python3',
+	'ruby',
+	'perl',
+	'php',
+	'node',
+])
 const NODE = 'node'
 const NODE_EVAL = /(?:^|\s)(?:-e|--eval)\b/u
 
 // A body that writes a file, in Python and Node spellings — split across two patterns so neither
 // exceeds the regex-complexity ceiling. The named write calls: `writeFile` covers `writeFileSync`,
-// `appendFile` covers its sync form, and `.write(` covers `.writelines(`.
-const WRITE_CALL = /writeFile|appendFile|createWriteStream|\.write(?:lines)?\s*\(/u
+// `appendFile` covers its sync form, and `.write(` covers `.writelines(` and Python's path-object
+// `.write_text(` / `.write_bytes(`.
+const WRITE_CALL = /writeFile|appendFile|createWriteStream|\.write(?:lines|_text|_bytes)?\s*\(/u
 // The mode-string and relocation forms: an `open(…, "w"|"a"|"x")`, `os.replace`, `shutil.copy` / `move`.
 // A mode string of `r` alone (a read) matches none of these, so a compute- or read-only heredoc stays
 // silent.
 const WRITE_MODE = /open\s*\([^)]*['"][rbt+]*[wax]|os\.replace|shutil\.(?:copy|move)/u
 
-function body_writes(command: string): boolean {
-	return WRITE_CALL.test(command) || WRITE_MODE.test(command)
+function body_writes(body: string): boolean {
+	return WRITE_CALL.test(body) || WRITE_MODE.test(body)
+}
+
+// A script file for one of the body interpreters. Creating one is a new-file creation, but a script
+// whose body writes is the interpreter rewrite moved one call later — `cat > edit.py <<EOF` then
+// `python3 edit.py` carries the same replacement text (joshuafolkken/kit#3155).
+const SCRIPT_FILE = /\.(?:py|rb|pl|php|js|mjs|cjs)$/u
+
+// Shapes 1 and 4: a heredoc write whose target already exists, or whose target is a script that writes.
+// The existence check is injected so the suite controls it without touching the real filesystem, the
+// same way `lane-park.ts` injects the lane fact.
+function is_heredoc_write(line: CommandLine, has_file: (path: string) => boolean): boolean {
+	const target = has_heredoc(line.text) ? redirect_target(line.text) : undefined
+
+	if (target === undefined) return false
+	if (has_file(target)) return true
+
+	return SCRIPT_FILE.test(target) && body_writes(line.body)
 }
 
 // Shape 2: an interpreter reading a heredoc, or a `node -e`, whose body writes.
-function is_interpreter_write(segment: string, command: string): boolean {
+function is_interpreter_write(segment: string, body: string): boolean {
 	const leading = time_shell.leading_word(segment)
 
-	if (BODY_INTERPRETERS.has(leading)) return has_heredoc(command) && body_writes(command)
+	if (!BODY_INTERPRETERS.has(leading)) return false
+	if (has_heredoc(segment)) return body_writes(body)
 
 	return leading === NODE && NODE_EVAL.test(segment) && body_writes(segment)
 }
@@ -103,19 +155,21 @@ function is_in_place_perl(segment: string): boolean {
 	return segment.split(WHITESPACE).some((word) => PERL_IN_PLACE.test(word))
 }
 
-// The interpreter and perl shapes are read per first-line segment, so a heredoc marker on the same line
-// is judged against the command that opened it rather than against a later one in a chain.
-function has_body_interpreter(command: string): boolean {
+// The interpreter and perl shapes are read per command-line segment, so a heredoc marker is judged
+// against the command that opened it rather than against a later one in a chain.
+function has_body_interpreter(line: CommandLine): boolean {
 	return shell_segments
-		.segments_of(first_line(command))
-		.some((segment) => is_interpreter_write(segment, command) || is_in_place_perl(segment))
+		.segments_of(line.text)
+		.some((segment) => is_interpreter_write(segment, line.body) || is_in_place_perl(segment))
 }
 
 function carries_a_file_body(
 	command: string,
 	has_file: (path: string) => boolean = existsSync,
 ): boolean {
-	return writes_existing_file(command, has_file) || has_body_interpreter(command)
+	return command_lines(command).some(
+		(line) => is_heredoc_write(line, has_file) || has_body_interpreter(line),
+	)
 }
 
 // The instruction in the shape a refusal can carry: what the command is doing, the safe tool, and the
@@ -123,11 +177,13 @@ function carries_a_file_body(
 // surprising — the command body is billed on every later request of the run.
 const FILE_BODY_REASON =
 	"⛔ file body in a shell command: this carries a file's new text inline — a heredoc rewriting an " +
-	'existing file, an interpreter (`python3 - <<`, `node -e`) whose body writes, or an in-place `perl ' +
-	'-0pi -e`. `CLAUDE.md` forbids it because the command body is re-read on every later request of the ' +
-	'run, so an editing script written early is billed for the rest of it (`file-edits.md` measured one ' +
-	'run at ~2m45s spent retyping existing lines). Edit a region with the Edit tool (old / new), or pass ' +
-	'a body by path (`--field body=@<path>`, `--body-file <path>`). A new-file creation (`cat > ' +
+	'existing file, an interpreter (`python3 - <<`, `node -e`) whose body writes, a script file (`cat > ' +
+	'edit.py <<EOF`) whose body writes, or an in-place `perl -0pi -e`. `CLAUDE.md` forbids it because ' +
+	'the command body is re-read on every later request of the run, so an editing script written early ' +
+	'is billed for the rest of it (`file-edits.md` measured one run at ~2m45s spent retyping existing ' +
+	'lines). Edit a region with the Edit tool (old / new); a change scattered so widely that the ' +
+	'partial edits would carry more than the file is rewritten whole with the Write tool, never a ' +
+	'heredoc. Pass a body by path (`--field body=@<path>`, `--body-file <path>`). A new-file creation (`cat > ' +
 	'<new-file> <<EOF`), a read-only heredoc (`cat <<EOF`), and a short `sed -i` stay allowed. **This ' +
 	'rule fires on every occurrence, not once per run.**'
 

package/scripts/rules/filing-cap.ts

@@ -8,7 +8,7 @@ import { tail_commands } from './tail-commands'
 // The trigger and the decision behind the `filing-cap` row of `delivered-rules.ts`
 // (joshuafolkken/kit#2119).
 //
-// **Automatic filing is capped at 10 Issues per run, refused at the eleventh filing.** §2d and
+// **Automatic filing is capped at 10 Issues per run, refused at the eleventh filing.** `prerequisite.md` and
 // `observation-filing.md` state the ceiling; nothing counted it, so a run that over-filed was held
 // only by self-restraint. The input is mechanical — how many Issues this run has already filed — so
 // it is a delivered rule rather than resident prose. **No new predicate**: the filing is
@@ -108,7 +108,7 @@ const FILING_CAP_REASON =
 	`⛔ filing cap: this run has already filed ${String(FILING_CAP)} Issues, the per-run ceiling — on ` +
 	'reaching it, stop and report rather than filing more. Automatic filing is capped so a run cannot ' +
 	'manufacture Issues faster than they can be closed (`.claude/skills/workflow-commands/SKILL.md` → ' +
-	"§2d, `observation-filing.md`). A further Issue that genuinely must exist is a person's call, not " +
+	"`prerequisite.md`, `observation-filing.md`). A further Issue that genuinely must exist is a person's call, not " +
 	"this run's. **This rule fires on every filing past the cap, not once per run**, so reissuing the " +
 	'same filing will be refused again.'
 

package/scripts/rules/filing-offer.ts

@@ -4,7 +4,7 @@ import { issue_citation } from './issue-citation'
 // The predicates behind the `filing-offer` row of the stop guard (joshuafolkken/kit#2422).
 //
 // **A first-party filing is Tier A, and an offer to file is that filing deferred to the user.**
-// `SKILL.md` → §2i says a run that judges something worth filing files it without asking, yet a reply
+// `observation-filing.md` says a run that judges something worth filing files it without asking, yet a reply
 // can still end on "it is worth filing — say so if you want it filed". The rule was resident; what was
 // missing was anything that fired at the moment of hesitation. That moment is one `Stop` payload: a
 // reply that offers to file, on a turn that filed nothing.

package/scripts/rules/gh-api.ts

@@ -30,6 +30,11 @@ const REPO_PATH = /repos\/([^/\s'"?]+)\/([^/\s'"?]+)/u
 const OWNER_GROUP = 1
 const REPO_GROUP = 2
 
+// The placeholders `gh api` expands to its base repository's owner before it sends the request
+// (joshuafolkken/kit#3188) — `{owner}`, and the legacy `:owner` it still accepts. Which owner that is
+// depends on the checkout's remotes, so the caller resolves it rather than this parser.
+const OWNER_PLACEHOLDERS: ReadonlySet<string> = new Set(['{owner}', ':owner'])
+
 interface RepoTarget {
 	owner: string
 	repo: string
@@ -65,6 +70,18 @@ function repo_target(segment: string): RepoTarget | undefined {
 	return { owner: match[OWNER_GROUP] ?? '', repo: match[REPO_GROUP] ?? '' }
 }
 
-const gh_api = { GH_FLAGS, is_gh_api, is_read, is_write, method_of, repo_target }
+function is_owner_placeholder(owner: string): boolean {
+	return OWNER_PLACEHOLDERS.has(owner)
+}
+
+const gh_api = {
+	GH_FLAGS,
+	is_gh_api,
+	is_owner_placeholder,
+	is_read,
+	is_write,
+	method_of,
+	repo_target,
+}
 
 export { gh_api }

package/scripts/rules/implementation-cut.ts

@@ -6,6 +6,7 @@ import type { GuardRun } from '#scripts/josh/hook-decision'
 import { lane_child_marker, type MarkerSource } from '#scripts/lane/lane-child-marker'
 import { lane_paths } from '#scripts/lane/lane-paths'
 import { run_cut, type RunCut } from '#scripts/run/run-cut'
+import { run_cut_handoff } from '#scripts/run/run-cut-handoff'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { implementation_cut_verdict } from './implementation-cut-verdict'
@@ -161,7 +162,8 @@ const IMPLEMENTATION_CUT_REASON =
 	`cost has crossed the shared ${THRESHOLD_TEXT} threshold mid-implementation, so the thinking accumulated ` +
 	'so far is now re-read on every later request. Take the cut before this edit. ' +
 	'First write a handoff file with the Write tool — the user’s instruction verbatim, what you have ' +
-	'completed, what remains, and what you deliberately did not touch — and pass it as `--handoff <path>`, ' +
+	'completed, what remains, and what you deliberately did not touch, as ' +
+	`${run_cut_handoff.HANDOFF_FORMAT} (Markdown is refused) — and pass it as \`--handoff <path>\`, ` +
 	'so the fresh process resumes on the original instruction rather than the working tree alone ' +
 	'(joshuafolkken/kit#2354); a resume that finds no instruction is refused `incomplete` rather than ' +
 	'continuing blind. ' +

package/scripts/rules/lane-background.ts

@@ -26,7 +26,9 @@ import { run_tail } from './run-tail'
 // 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.
+// tool timeout, and the supervisor carries the rest. A backgrounded `ship` alone is no longer refused but
+// rewritten into that foreground call (`foreground_input`, joshuafolkken/kit#3154); one chained after
+// another long command is still refused.
 //
 // **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 —
@@ -35,29 +37,61 @@ 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', 'ship'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
-)
+const SHIP_COMMAND = `${time_shell.JOSH_PREFIX}ship`
+const LONG_RUNNING_COMMANDS: ReadonlySet<string> = new Set([
+	...['gate', 'git', 'followup'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
+	SHIP_COMMAND,
+])
 
 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.
+const FOREGROUND_TIMEOUT_MS = 600_000
 
 function is_backgrounded(input: unknown): boolean {
 	return json_value.is_record(input) && input[BACKGROUND_KEY] === true
 }
 
-function runs_long_command(command: string): boolean {
-	return time_shell.josh_commands_of(command).some((name) => LONG_RUNNING_COMMANDS.has(name))
+function long_commands_of(command: string): Array<string> {
+	return time_shell.josh_commands_of(command).filter((name) => LONG_RUNNING_COMMANDS.has(name))
+}
+
+// A call whose long-running work is `ship` alone. In a child a foreground `ship` already detaches
+// itself after its preflight (`run-ship-cli.ts` → `should_detach`), so the only fault in backgrounding
+// it is the flag — and the flag is what the hook rewrites (joshuafolkken/kit#3154).
+function ships_alone(command: string): boolean {
+	const names = long_commands_of(command)
+
+	return names.length > 0 && names.every((name) => name === SHIP_COMMAND)
+}
+
+function backgrounded_bash_command(call: GuardedCall): string | undefined {
+	if (call.name !== cost_blocks.BASH_TOOL || !is_backgrounded(call.input)) return undefined
+
+	return time_shell.bash_command(call.input)
+}
+
+function is_backgrounded_ship(call: GuardedCall): boolean {
+	const command = backgrounded_bash_command(call)
+
+	return command !== undefined && ships_alone(command)
 }
 
 // The call's own fields alone: a backgrounded Bash call that runs a long josh command, or the push step
 // in either spelling. A child's foreground push is claimed too, because `run-tail` would otherwise answer
 // it with "reissue it backgrounded" — the one reissue this row then refuses — so the child is handed the
-// detached route on its first refusal rather than two contradictory ones.
+// detached route on its first refusal rather than two contradictory ones. A backgrounded `ship` alone is
+// not refused: `foreground_input` turns it into the foreground call the refusal used to ask for.
 function is_candidate(call: GuardedCall): boolean {
 	if (run_tail.is_push_step_call(call)) return true
-	if (call.name !== cost_blocks.BASH_TOOL || !is_backgrounded(call.input)) return false
 
-	return runs_long_command(time_shell.bash_command(call.input))
+	const command = backgrounded_bash_command(call)
+
+	if (command === undefined || is_backgrounded_ship(call)) return false
+
+	return long_commands_of(command).length > 0
 }
 
 // True when this session is a dispatched lane child backgrounding a long-running josh command. The call's
@@ -69,6 +103,26 @@ function is_background_long_run(
 	return is_candidate(call) && is_lane_child()
 }
 
+// **A backgrounded `ship` in a child is rewritten, not refused** (joshuafolkken/kit#3154). 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.
+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)) return undefined
+
+	if (!is_lane_child()) return undefined
+
+	return { ...call.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` (joshuafolkken/kit#3154).'
+
 // 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(
@@ -103,7 +157,8 @@ const LANE_BACKGROUND_REASON =
 	'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`. ' +
+	'`ship` dies with the turn (joshuafolkken/kit#3027; a backgrounded `ship` issued alone is moved to ' +
+	'the foreground for you, joshuafolkken/kit#3154) — 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 ' +
@@ -128,9 +183,11 @@ const ROW = {
 }
 
 const lane_background = {
+	FOREGROUND_NOTE,
 	LANE_BACKGROUND_REASON,
 	LANE_BACKGROUND_STOP_REASON,
 	ROW,
+	foreground_input,
 	is_background_long_run,
 	pending_agent_ids,
 	pending_background_ids,

package/scripts/rules/permission-guards.ts

@@ -1,4 +1,5 @@
 import { destructive_command } from './destructive-command'
+import { direct_pr_create } from './direct-pr-create'
 import { index_guard } from './index-guard'
 import { protected_files } from './protected-files'
 
@@ -6,8 +7,15 @@ import { protected_files } from './protected-files'
 // `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
+// other row's — `git restore` is split with `worktree-mutation` by `--staged` alone. The fourth row,
+// `direct-pr-create` (joshuafolkken/kit#3183), 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.
+const ROWS = [
+	index_guard.ROW,
+	destructive_command.ROW,
+	protected_files.ROW,
+	direct_pr_create.ROW,
+] as const
 
 const permission_guards = { ROWS }
 

package/scripts/rules/stop-rules.ts

@@ -103,13 +103,13 @@ const STOP_NOTIFY_REASON =
 	'your previous reply. This fires only while the hold is held and no notify is on the transcript, and ' +
 	'`stop_hook_active` lets a second stop through so a run is never wedged.'
 
-// **A clean tree that still holds is a tree the next run will trample.** `SKILL.md` → §2f: a stop that
+// **A clean tree that still holds is a tree the next run will trample.** `working-tree-hold.md`: a stop that
 // leaves the tree clean releases the hold; a `halfrun` pre-commit stop and a `needs-human-review` stop
 // keep it because their tree is dirty, which is why this row is silent whenever the tree is not clean.
 const HOLD_RELEASE_REASON =
 	'⛔ working-tree hold not released: this working tree is clean but its `run:hold` record is still in ' +
 	'place, so the next run here runs `git switch main && git pull` believing the tree is free while ' +
-	'you hold it. `.claude/skills/workflow-commands/SKILL.md` → §2f: a stop that leaves the tree clean ' +
+	'you hold it. The workflow-commands skill → `working-tree-hold.md`: a stop that leaves the tree clean ' +
 	'releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` ' +
 	'pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a ' +
 	'`prrun` stop keeps it by its stop mark — this row is silent there. Release it, then end with a one-line confirmation that it was released — do ' +
@@ -139,11 +139,11 @@ function build_citation_reason(references: ReadonlyArray<string>): string {
 
 // **An offer to file is a Tier A filing deferred to the user** (joshuafolkken/kit#2422). The judgement
 // is already made, so the reason hands over the filing chain rather than a question; the rule itself
-// is resident in `SKILL.md` → §2i and only pointed at.
+// is resident in `observation-filing.md` and only pointed at.
 const FILING_OFFER_REASON =
 	'⛔ filing offer: your reply offers to file an Issue instead of filing it. Filing into a ' +
 	'first-party repository is Tier A — the trigger is the judgement that it is worth filing, not the ' +
-	"run's progress (`.claude/skills/workflow-commands/SKILL.md` → §2i, `observation-filing.md`). Run " +
+	"run's progress (the workflow-commands skill → `observation-filing.md`). Run " +
 	'`pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` — it scouts, lints, labels and ' +
 	'runs `epic:bundle` itself — then end with the one-line citation of what was filed; do not repeat ' +
 	'your previous reply. If it is not worth filing ' +

package/scripts/rules/test-declared-commit.ts

@@ -17,7 +17,7 @@ import { run_tail } from './run-tail'
 // pays nothing and only a `pnpm josh git -y` spawns `git status`.
 //
 // **Once per run, because the exemption is a person's judgement a synchronous guard cannot read.** The
-// non-executable-config and cosmetic-asset arms of `CLAUDE.md`'s "Non-runtime updates" exception stay
+// non-executable-config and cosmetic-asset arms of `prompts/testing-guide.md`'s "Non-runtime updates" exception stay
 // `required` by the classifier, and a person declares them in the Step 0 work summary — which no label
 // or transcript tail records. So a row that fired every time would wedge exactly that declared-exempt
 // commit; refusing once and passing the reissue is the same safe direction `issue-comments` takes, and

package/scripts/rules/third-party-write.ts

@@ -25,34 +25,78 @@ import { shell_segments } from './shell-segments'
 // A third-party write means all three: a `gh api` call, a write, and a repository target whose owner
 // the classification calls third-party. `unknown` (an unreadable session remote, an unparseable path)
 // is not third-party — the rule stays silent rather than refusing a write it cannot prove is external.
-function is_third_party_write_segment(segment: string, session_owner: string | undefined): boolean {
+// The `{owner}` placeholder (joshuafolkken/kit#3188) is judged by every owner `gh` could expand it to:
+// first-party only when all of them are, so a fork checkout whose `upstream` is another owner's still
+// refuses the write `gh` may send there. A candidate whose owner could not be read counts as
+// third-party here — unlike an unreadable session owner, it is a remote `gh` may really write to.
+function is_third_party_write_segment(
+	segment: string,
+	session_owner: string | undefined,
+	resolve_placeholder_owners: () => Array<string | undefined>,
+): boolean {
 	if (!gh_api.is_gh_api(segment) || !gh_api.is_write(segment)) return false
 
 	const target = gh_api.repo_target(segment)
-
 	if (target === undefined) return false
 
-	return repo_party.classify(session_owner, target.owner) === repo_party.THIRD_PARTY
+	if (!gh_api.is_owner_placeholder(target.owner)) {
+		return repo_party.classify(session_owner, target.owner) === repo_party.THIRD_PARTY
+	}
+
+	return resolve_placeholder_owners().some(
+		(owner) =>
+			owner === undefined || repo_party.classify(session_owner, owner) === repo_party.THIRD_PARTY,
+	)
+}
+
+// A segment that makes `gh` resolve the placeholder against something other than this process's
+// checkout: a directory change, or a `GH_REPO` assignment. The guard reads the hook's own cwd and
+// environment, so after either one its candidate set no longer describes what `gh` will expand.
+const GH_CONTEXT_CHANGE = /(?:^|\s)(?:cd|pushd)(?:\s|$)|(?:^|\s)(?:export\s+)?GH_REPO=/u
+
+function unreadable_candidates(): Array<string | undefined> {
+	return [undefined]
+}
+
+// The placeholder candidates for the segment at `index`: the checkout's own, unless an earlier
+// segment of the same line moved `gh` elsewhere — then one unreadable candidate, refused.
+function candidates_at(
+	segments: ReadonlyArray<string>,
+	index: number,
+	resolve_placeholder_owners: () => Array<string | undefined>,
+): () => Array<string | undefined> {
+	const has_moved = segments.slice(0, index).some((segment) => GH_CONTEXT_CHANGE.test(segment))
+
+	return has_moved ? unreadable_candidates : resolve_placeholder_owners
 }
 
 // The session owner is read only when a segment is actually a `gh api` write to a repository — so an
-// ordinary shell line, and every read, pays nothing for the local config read. `resolve_owner` is
-// injected so the suite fixes the owner without touching the real remote, the way `file-body.ts`
-// injects `has_file`. Each segment is judged on its own, so a `gh api` write quoted inside another
-// command's argument is read as the write it is not, exactly as every other trigger here reads its own.
+// ordinary shell line, and every read, pays nothing for the local config read. `resolve_owner` and
+// `resolve_placeholder_owners` are injected so the suite fixes the owners without touching the real
+// remotes, the way `file-body.ts` injects `has_file`. Each segment is judged on its own, so a `gh api`
+// write quoted inside another command's argument is read as the write it is not, exactly as every
+// other trigger here reads its own.
 function writes_third_party(
 	command: string,
 	resolve_owner: () => string | undefined = repo_party.current_owner,
+	resolve_placeholder_owners: () => Array<string | undefined> = repo_party.placeholder_owners,
 ): boolean {
-	const targets = shell_segments
-		.segments_of(command)
-		.filter((segment) => gh_api.is_gh_api(segment) && gh_api.is_write(segment))
+	const segments = shell_segments.segments_of(command)
+	const has_write = segments.some(
+		(segment) => gh_api.is_gh_api(segment) && gh_api.is_write(segment),
+	)
 
-	if (targets.length === 0) return false
+	if (!has_write) return false
 
 	const session_owner = resolve_owner()
 
-	return targets.some((segment) => is_third_party_write_segment(segment, session_owner))
+	return segments.some((segment, index) =>
+		is_third_party_write_segment(
+			segment,
+			session_owner,
+			candidates_at(segments, index, resolve_placeholder_owners),
+		),
+	)
 }
 
 // The instruction in the shape a refusal can carry: what the command does, why it is Tier C, and what

package/scripts/run/run-cut-handoff.ts

@@ -41,6 +41,22 @@ const UNTOUCHED_LABEL = 'Deliberately untouched'
 const INSTRUCTION_LABEL = 'Instruction (verbatim)'
 const EMPTY_LIST_NOTE = '(none)'
 
+type HandoffKey = keyof Handoff
+
+function describe_key(key: HandoffKey): string {
+	const value = handoff_schema.shape[key] instanceof z.ZodArray ? '["…"]' : '"…"'
+
+	return `"${key}": ${value}`
+}
+
+// The shape a handoff file must have, derived from `handoff_schema` so the refusal that asks for the file
+// and the error that rejects it can never name a key the parser does not read (joshuafolkken/kit#3195).
+// A refusal that listed the four items in prose was answered with Markdown, which `parse_handoff` rejects.
+const HANDOFF_FORMAT = `a JSON object {${handoff_schema
+	.keyof()
+	.options.map((key) => describe_key(key))
+	.join(', ')}}`
+
 function parse_handoff(raw: string): Handoff | undefined {
 	try {
 		const parsed = handoff_schema.safeParse(JSON.parse(raw))
@@ -84,7 +100,10 @@ function load_handoff(handoff_path: string | undefined, max_bytes: number): Hand
 	const handoff = read_handoff_file(handoff_path)
 
 	if (handoff === undefined) {
-		return { kind: 'bad', note: `--handoff ${handoff_path} is not a readable handoff file` }
+		return {
+			kind: 'bad',
+			note: `--handoff ${handoff_path} is not a readable handoff file — write ${HANDOFF_FORMAT}`,
+		}
 	}
 
 	if (!is_within_bound(handoff, max_bytes)) {
@@ -114,6 +133,7 @@ function describe_handoff(handoff: Handoff): string {
 }
 
 const run_cut_handoff = {
+	HANDOFF_FORMAT,
 	describe_handoff,
 	handoff_schema,
 	is_complete_handoff,