@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/scripts/review/review-record-cli.ts

@@ -58,8 +58,12 @@ interface Parsed {
 // A finding spec is `<category>:<severity>:<file>`; the file field keeps any `:line` a citation
 // carries, so only the first two colons separate fields.
 function to_finding(category: string, severity: string, file: string): Finding | undefined {
-	if (!review_finding_ledger.is_category(category)) return undefined
-	if (!review_finding_ledger.is_severity(severity)) return undefined
+	if (
+		!review_finding_ledger.is_category(category) ||
+		!review_finding_ledger.is_severity(severity)
+	) {
+		return undefined
+	}
 
 	return review_finding_ledger.is_valid_file(file) ? { category, severity, file } : undefined
 }

package/scripts/rules/agent-model.ts

@@ -0,0 +1,59 @@
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+
+// A `general-purpose` subagent dispatched without a `model` is refused until it names one
+// (joshuafolkken/kit#3927).
+//
+// **The omission is the cost, not the dispatch.** A subagent with no `model` inherits the parent's,
+// so a routine unit runs on the main line's model — measured at 94 such dispatches on Opus. A named
+// agent type carries its own `model` in its definition, so only the catch-all type is in scope; an
+// absent `subagent_type` is that type, the harness's default.
+//
+// **It fires on every occurrence**: the remedy is one field on the same call, so a refusal costs one
+// round trip and never wedges the run.
+
+// Both spellings of the subagent tool are in use: `Task` (published) and `Agent` (this harness).
+const SUBAGENT_TOOLS: ReadonlySet<string> = new Set(['Agent', 'Task'])
+const GENERAL_PURPOSE = 'general-purpose'
+
+// A dispatch of the catch-all type — the one whose model is otherwise inherited.
+function is_general_purpose(call: GuardedCall): boolean {
+	if (!SUBAGENT_TOOLS.has(call.name) || !json_value.is_record(call.input)) return false
+
+	const type = call.input['subagent_type']
+
+	return type === undefined || type === GENERAL_PURPOSE
+}
+
+function names_model(call: GuardedCall): boolean {
+	const model = json_value.is_record(call.input) ? call.input['model'] : undefined
+
+	return typeof model === 'string' && model.length > 0
+}
+
+function is_unnamed_model(call: GuardedCall): boolean {
+	return is_general_purpose(call) && !names_model(call)
+}
+
+function keeps_model(call: GuardedCall): boolean {
+	return is_general_purpose(call) && names_model(call)
+}
+
+const AGENT_MODEL_REASON =
+	'⛔ agent model: a `general-purpose` subagent with no `model` inherits the parent model. ' +
+	'Reissue the call with `model` set — `sonnet` for routine work, `opus` for judgment such as a review. ' +
+	'It fires on every occurrence (`.claude/skills/workflow-commands/delegation.md`).'
+
+// `reaches` is every catch-all dispatch, so `rule-value.ts` scores the named-model ones against it.
+const ROW = {
+	id: 'agent-model',
+	is_trigger: is_unnamed_model,
+	reason: AGENT_MODEL_REASON,
+	decide: (): boolean => true,
+	keeps: keeps_model,
+	reaches: is_general_purpose,
+}
+
+const agent_model = { AGENT_MODEL_REASON, ROW, is_unnamed_model }
+
+export { agent_model }

package/scripts/rules/delivered-rules.ts

@@ -2,6 +2,7 @@ import { investigation_reads } from '#scripts/delegation/investigation-reads'
 import { hook_decision, type GuardRun, type TranscriptGuardSpec } from '#scripts/josh/hook-decision'
 import { lane_guard_policy } from '#scripts/lane/lane-guard-policy'
 import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { agent_model } from './agent-model'
 import { bash_triggers } from './bash-triggers'
 import { direct_filing } from './direct-filing'
 import { early_heartbeat } from './early-heartbeat'
@@ -46,6 +47,9 @@ type CallTest = (
 	run: ReadonlyArray<GuardedCall>,
 ) => boolean
 
+// The tail is read lazily: most calls no rewrite applies to never need it.
+type CallRewrite = (call: GuardedCall, tail: () => string) => Record<string, unknown> | undefined
+
 // `id` keys the rule's own refusal record, so one rule firing never spends another's budget.
 interface DeliveredRule {
 	id: string
@@ -63,6 +67,9 @@ interface DeliveredRule {
 	// The occasion the rule governs, for a row whose trigger is the violation itself (else `is_trigger`
 	// would only count runs that broke it).
 	reaches?: CallTest
+	// The call made right, for a row `guard-remedy.ts` classes as a rewrite: `rule-rewrite.ts` runs it
+	// in place of the refusal. `undefined` where this call has no mechanical fix, so it is refused.
+	rewrite?: CallRewrite
 	// The note a hook attaches where it rewrites a violating call instead of refusing it, so
 	// `rule-value.ts` counts the rewrite as this row's delivery.
 	rewrite_note?: string
@@ -107,7 +114,8 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		reason: piped_verification.PIPED_VERIFICATION_REASON,
 		keeps: on_bash_command(piped_verification.keeps_verdict_intact),
 		reaches: on_bash_command(piped_verification.runs_verification),
-		// A `| tail` / `| grep` masking is rewritten under `pipefail` by `pretool-guard.ts`, never refused.
+		// A masking whose filter reads to the end is rewritten under `pipefail`, never refused.
+		rewrite: piped_verification.pipefail_input,
 		rewrite_note: piped_verification.PIPEFAIL_NOTE,
 	},
 	{
@@ -146,6 +154,7 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 	lane_split_park.ROW,
 	lane_park.ROW,
 	lane_interactive_ask.ROW,
+	agent_model.ROW,
 	lane_carry_conflict.ROW,
 	lane_switch_main.ROW,
 	// Disjoint from `run-tail` by the `-y` flag.
@@ -304,5 +313,5 @@ const delivered_rules = {
 	is_issue_filing,
 }
 
-export type { DeliveredRule, MeasuredRule }
+export type { CallRewrite, DeliveredRule, MeasuredRule }
 export { delivered_rules }

package/scripts/rules/destructive-command.ts

@@ -97,21 +97,18 @@ function is_destructive_command(command: string): boolean {
 }
 
 const DESTRUCTIVE_COMMAND_REASON =
-	'⛔ destructive command: a recursive forced `rm` (`rm -rf`, `rm -fr`, `rm -r -f`, `rm --recursive ' +
-	'--force`), `gh repo delete` / `archive`, `gh repo edit --visibility`, `gh pr close`, or a `gh api ' +
-	'-X DELETE repos/…` call deletes or closes something that cannot be restored, which is Tier C and ' +
-	'needs explicit current-turn user instruction (`prompts/collaboration-workflow/operating-rules.md`). ' +
-	'The `.claude/settings.json` deny list matches prefix globs, so it misses these spellings; this row ' +
-	'reads the argv instead. Remove a file or directory one path at a time without `-f`, or ask the user ' +
-	'to run the command in their own terminal. `gh issue close` and removing a label from an Issue ' +
-	'(`DELETE repos/<o>/<r>/issues/<N>/labels/<name>`) are not refused. **This rule fires on every ' +
-	'occurrence, not once per run.**'
+	'⛔ destructive command: a recursive forced `rm`, a `gh repo delete` / `archive` / visibility edit, ' +
+	'`gh pr close` or a `gh api -X DELETE` cannot be undone, which is Tier C. Remove one path at a ' +
+	'time without `-f`, or ask the user to run it. It fires on every occurrence ' +
+	'(`prompts/collaboration-workflow/operating-rules.md`).'
 
 const ROW = {
 	id: 'destructive-command',
 	is_trigger: bash_triggers.on_bash_command(is_destructive_command),
 	reason: DESTRUCTIVE_COMMAND_REASON,
 	decide: (): boolean => true,
+	// The opening the reason carried before it was cut to the action and the next command.
+	former_reasons: ['⛔ destructive command: a recursive forced `rm` (`rm -rf`'],
 }
 
 const destructive_command = { DESTRUCTIVE_COMMAND_REASON, ROW, is_destructive_command }

package/scripts/rules/direct-filing.ts

@@ -9,13 +9,9 @@ import { bash_triggers } from './bash-triggers'
 
 const DIRECT_FILING_REASON =
 	'⛔ direct filing: an Issue is filed with `pnpm josh issue:file "<title>" --body-file <path> ' +
-	'--depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>]`, never with `gh api …/issues` ' +
-	'or `gh issue create`. The command runs every filing step in order — the duplicate scout, the body ' +
-	'lint and its classification labels, the depth and `route:` labels, the `## Origin` check when filing ' +
-	'into another repository, and `epic:bundle` after the create — so none of them is a step to remember. ' +
-	'When the scout prints candidates it holds the filing: read each, then reissue with `--distinct <N,…>` ' +
-	'for the ones that are separate deliverables. Reference: `docs/josh-commands-backlog.md` → "`josh issue:file`". ' +
-	'**This rule fires on every occurrence, not once per run.**'
+	'--depth <0|1|2>`, never with `gh api …/issues` or `gh issue create` — it runs the scout, the lint, ' +
+	'the labels and `epic:bundle` itself. It fires on every occurrence (`docs/josh-commands-backlog.md` ' +
+	'→ "`josh issue:file`").'
 
 function is_any_filing(command: string): boolean {
 	return bash_triggers.is_direct_filing(command) || bash_triggers.is_issue_filing(command)

package/scripts/rules/early-heartbeat.ts

@@ -178,25 +178,14 @@ function decide(call: GuardedCall, run: GuardRun, can_record: boolean): boolean
 }
 
 // The instruction in the shape a refusal can carry: what the call is about to do, what already does it
-// properly, and the one command an explicit ask is answered with. The observed failure is named
-// because it is what makes the rule believable.
+// properly, and the one command an explicit ask is answered with. The observed failure behind it is in
+// `docs/maintainers/rule-delivery-rationale.md`.
 const EARLY_HEARTBEAT_REASON =
-	'⛔ early heartbeat: this call arms a wait timer of its own, and the progress clock is not yours ' +
-	'to keep. `pnpm josh run:progress --wait` keeps it for you ' +
-	'(`JOSH_PROGRESS_INTERVAL_MINUTES`, or `josh.progress_interval_minutes` in `package.json`, ' +
-	'default 20 minutes): start it once in the background and it reports the five labelled lines to ' +
-	"the run's event stream on its own, without waking you — relay nothing, and start it again only " +
-	'after it exits, which it does when newly runnable work arrives. Two timers armed at ' +
-	'once is what produced reports 3–5 minutes apart on a 15-minute setting ' +
-	'(joshuafolkken/kit#1570): a new one was armed on the turn a timer fired and again on the turn a ' +
-	"child's completion woke the run, and `--mark` recorded each report without anything refusing the " +
-	'early ones. **An explicit ask is not a heartbeat**: if the person asked for progress now, run ' +
-	'`pnpm josh run:progress --once`, which prints the five labelled lines whatever the clock says — ' +
-	'under `backlogrun`, `pnpm josh run:board --chat` instead. If you are ' +
-	'waiting on something rather than on a clock, wait on the thing itself — `pnpm josh followup` ' +
-	'waits for CI. The procedure is `.claude/skills/workflow-commands/backlogrun.md` → "Progress while ' +
-	'the run is quiet". **This rule fires on every early arm, not once per run**, so reissuing the ' +
-	'same sleep will be refused again.'
+	'⛔ early heartbeat: this call arms a wait timer of its own. Start `pnpm josh run:progress --wait` ' +
+	"once in the background: it reports to the run's event stream on its own — relay nothing. When " +
+	'asked, `pnpm josh run:progress --once` — under `backlogrun`, `pnpm josh run:board --chat`; ' +
+	'for CI, `pnpm josh followup`. It fires on every occurrence ' +
+	'(`.claude/skills/workflow-commands/progress-watcher.md`).'
 
 // **Keeping this rule is letting the watcher hold the clock** — `pnpm josh run:progress --wait` waits
 // the interval out, and `--once` answers an explicit ask. `--mark` is neither: it records a report

package/scripts/rules/file-body.ts

@@ -171,20 +171,13 @@ function carries_a_file_body(
 	)
 }
 
-// The instruction in the shape a refusal can carry: what the command is doing, the safe tool, and the
-// file forms that stay allowed. The measured cost is named because it is the half that reads as
-// surprising — the command body is billed on every later request of the run.
+// The instruction in the shape a refusal can carry: what the command is doing and the safe tool. The
+// measured cost behind it is in `file-edits.md`.
 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, 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.**'
+	"⛔ file body in a shell command: this carries a file's new text inline, which is re-read on every " +
+	'later request. Edit a region with the Edit tool, rewrite a whole file with the Write tool, and ' +
+	'pass a body by path (`--body-file <path>`); a new-file `cat > <new-file> <<EOF` stays allowed. ' +
+	'This rule fires on every occurrence (`prompts/collaboration-workflow/file-edits.md`).'
 
 const ROW = {
 	id: 'file-body',

package/scripts/rules/filing-cap.ts

@@ -104,12 +104,9 @@ function decide(_call: unknown, run: GuardRun): boolean {
 }
 
 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` → ' +
-	"`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.'
+	`⛔ filing cap: this run has already filed ${String(FILING_CAP)} Issues, the per-run ceiling. Stop ` +
+	"filing and report; a further Issue is a person's call. It fires on every occurrence " +
+	'(`.claude/skills/workflow-commands/observation-filing.md`).'
 
 // The enumeration row itself, so `delivered-rules.ts` spreads one entry rather than restating the
 // trigger and reason it already single-sources here. It declares no `keeps`: staying under a cap is
@@ -126,6 +123,7 @@ const filing_cap = {
 	FILING_CAP,
 	FILING_CAP_REASON,
 	ROW,
+	current_turn,
 	is_prompt_line,
 	prior_filing_count,
 	turn_filing_count,

package/scripts/rules/firing-point.ts

@@ -9,15 +9,18 @@
 // time is the whole point of the check.
 
 // **The hook-deliverable set — the single source is the list `pnpm josh rule:list` renders.** The
-// `PreToolUse` guard is wired to `Bash|Edit|Read|Write` (`scripts/hooks/pretool-guard.ts`), and the
-// lane-child interactive-ask row triggers on `AskUserQuestion`. A firing point naming one of these can
-// be delivered at the moment it binds; anything else cannot.
+// `PreToolUse` guard is wired to `Bash|Edit|Read|Write` (`scripts/hooks/pretool-guard.ts`), the
+// lane-child interactive-ask row triggers on `AskUserQuestion`, and the `agent-model` row on
+// `Agent|Task`. A firing point naming one of these can be delivered at the moment it binds; anything
+// else cannot.
 const HOOK_DELIVERABLE_TOOLS: ReadonlyArray<string> = [
 	'Bash',
 	'Edit',
 	'Read',
 	'Write',
 	'AskUserQuestion',
+	'Agent',
+	'Task',
 ]
 
 // **Known Claude Code tool calls that a hook cannot deliver a rule on.** They are real tools, so a
@@ -31,8 +34,6 @@ const KNOWN_UNDELIVERABLE_TOOLS: ReadonlyArray<string> = [
 	'WebFetch',
 	'WebSearch',
 	'TodoWrite',
-	'Task',
-	'Agent',
 	'NotebookEdit',
 ]
 

package/scripts/rules/git-force.ts

@@ -69,19 +69,15 @@ function is_force_or_delete(command: string): boolean {
 	return shell_segments.segments_of(command).some((segment) => is_destructive_segment(segment))
 }
 
-// The instruction in the shape a refusal can carry: what the command does, why the deny list did not
-// stop it, and the one route left. There is no "safe reissue" the way a backgrounded push is for
+// The instruction in the shape a refusal can carry: what the command does and the one route left. The
+// spellings the deny glob misses are pinned on `is_force_or_delete`, not repeated in the text. There is no "safe reissue" the way a backgrounded push is for
 // `run-tail` — a force push and a branch delete are Tier C, so the honest next move is a person's, in
 // their own terminal.
 const GIT_FORCE_REASON =
 	'⛔ force push or branch delete: this rewrites or removes shared history, which is Tier C and needs ' +
-	'explicit current-turn user instruction — never an AI decision, even to fix a problem you caused ' +
-	'(`prompts/collaboration-workflow/operating-rules.md`). The `.claude/settings.json` deny list ' +
-	'matches globs, so it misses this spelling: a combined short cluster (`git push -uf`), a `git -C ' +
-	'<path>` prefix, and the colon-form delete (`git push origin :branch`) all pass it. This row reads ' +
-	'the argv instead, so the spelling does not matter. For an ordinary push use `pnpm josh git`; a ' +
-	"force push, a `git push --delete` / `:branch`, or a `git branch -d` / `-D` is the user's to run in " +
-	'their own terminal. **This rule fires on every occurrence, not once per run.**'
+	'explicit current-turn user instruction. Push with `pnpm josh git`; leave a force push or branch ' +
+	"delete to the user's own terminal. This rule fires on every occurrence " +
+	'(`prompts/collaboration-workflow/operating-rules.md`).'
 
 // The row itself, so `delivered-rules.ts` spreads one entry. `decide` returns true so it refuses every
 // occurrence; it declares no `keeps` — not force-pushing is the absence of a call, not a call, so the

package/scripts/rules/guard-remedy.ts

@@ -0,0 +1,117 @@
+// Every `PreToolUse` and `Stop` guard, classed by what its refusal asks for (joshuafolkken/kit#3920),
+// with the reason it cannot run itself instead.
+//
+// **A refusal whose right form follows from the call alone is a wasted round trip.** The model reissues
+// the call the refusal already described, at the run's whole context. Where that form is mechanical
+// and stays the same tool, the hook runs it instead (`rule-rewrite.ts`) and says what it changed. Every
+// other refusal asks for something the call does not carry: another tool, another command and its
+// arguments, or a decision.
+//
+// `rewrite` means the row rewrites where it can and refuses where it cannot; `judgment` means it always
+// refuses. **`why` is required**: a guard is the third rung of `principles.md` → "automate-first", so
+// each row says why a command or the hook running the step cannot replace it. `guard-remedy.test.ts`
+// pins that every guard is classed with a non-empty `why` and that each `rewrite` row has one.
+
+type Remedy = 'rewrite' | 'judgment'
+
+interface GuardRemedy {
+	remedy: Remedy
+	// Why the hook cannot make the step itself — printed by `rule:list` as `not automated`.
+	why: string
+}
+
+const REWRITTEN =
+	'the hook makes the same call right itself; it refuses only a spelling it cannot rewrite'
+const ANOTHER_TOOL = 'the right form is another tool, which `updatedInput` cannot switch to'
+const ANOTHER_COMMAND = 'the right act is another command, whose arguments the call does not carry'
+const NO_RUN = "the call must not run at all, or only on a person's word — refusing is the remedy"
+// The `Stop` rows that already run their step: each blocks only on the case the hook cannot finish.
+const STOP_NOTIFY = 'the hook sends the notify itself; it blocks only when the send fails'
+const HOLD_RELEASE = 'the hook releases the hold itself; it blocks only when that release fails'
+const ISSUE_CITATION =
+	'the hook prints the citation lines itself; it blocks only on a number it cannot cite'
+const FILING_OFFER = 'the filing needs a title and a body only the model can write'
+
+function rewrite(): GuardRemedy {
+	return { remedy: 'rewrite', why: REWRITTEN }
+}
+
+function judgment(why: string): GuardRemedy {
+	return { remedy: 'judgment', why }
+}
+
+const GUARD_REMEDIES: Readonly<Record<string, GuardRemedy>> = {
+	// The rewrites: each fix is the same call made right.
+	'piped-verification': rewrite(), // wrapped in `(set -o pipefail; …)`
+	'issue-comments': rewrite(), // the same Issue's comments read on the same line
+	'lane-background': rewrite(), // a lane child's `ship` run in the foreground (`pretool-guard.ts`)
+	'file-body': judgment(ANOTHER_TOOL), // Edit or Write
+	'shell-body': judgment(
+		"which part of the body the shell was meant to expand is the author's, not the hook's",
+	),
+	'raw-field-body': judgment('the body moves to a file the call does not name'),
+	'rule-body': judgment('a trigger-plus-pointer line is written, not derived'),
+	'direct-filing': judgment(ANOTHER_COMMAND),
+	'direct-pr-create': judgment(ANOTHER_COMMAND),
+	'josh-git-bare': judgment(ANOTHER_COMMAND),
+	'run-tail': judgment(ANOTHER_COMMAND),
+	'pre-gate-cut': judgment(ANOTHER_COMMAND),
+	'implementation-cut': judgment(ANOTHER_COMMAND),
+	'early-heartbeat': judgment(ANOTHER_COMMAND),
+	'poll-loop': judgment(ANOTHER_COMMAND),
+	'lane-park': judgment(ANOTHER_COMMAND),
+	'lane-split-park': judgment(ANOTHER_COMMAND),
+	'lane-interactive-ask': judgment(ANOTHER_COMMAND),
+	'agent-model': judgment("which model fits the unit is the author's call"),
+	'lane-carry-conflict': judgment(ANOTHER_COMMAND),
+	'lane-switch-main': judgment(ANOTHER_COMMAND),
+	'oracle-consulted': judgment(ANOTHER_COMMAND),
+	'test-declared': judgment(ANOTHER_COMMAND),
+	batching: judgment(ANOTHER_COMMAND),
+	investigation: judgment(ANOTHER_COMMAND),
+	'duplicate-read': judgment(ANOTHER_COMMAND),
+	'run-watcher': judgment(ANOTHER_COMMAND),
+	'parent-cut': judgment(ANOTHER_COMMAND),
+	'issue-watch': judgment(ANOTHER_COMMAND),
+	'third-party-write': judgment(NO_RUN),
+	'filing-cap': judgment(NO_RUN),
+	'git-force': judgment(NO_RUN),
+	'worktree-mutation': judgment(NO_RUN),
+	'index-mutation': judgment(NO_RUN),
+	'destructive-command': judgment(NO_RUN),
+	'protected-file': judgment(NO_RUN),
+	// The `Stop` rows: the hook judges a finished reply, so it has no call to rewrite.
+	'stop-notify': judgment(STOP_NOTIFY),
+	'issue-citation': judgment(ISSUE_CITATION),
+	'filing-offer': judgment(FILING_OFFER),
+	'hold-release': judgment(HOLD_RELEASE),
+}
+
+// A row family shares one class: `oracle-consulted:pkg:scout` is an `oracle-consulted` row.
+const FAMILY_SEPARATOR = ':'
+
+function entry_of(id: string): GuardRemedy | undefined {
+	return GUARD_REMEDIES[id] ?? GUARD_REMEDIES[id.split(FAMILY_SEPARATOR)[0] ?? '']
+}
+
+function remedy_of(id: string): Remedy | undefined {
+	return entry_of(id)?.remedy
+}
+
+function why_of(id: string): string | undefined {
+	return entry_of(id)?.why
+}
+
+function is_rewrite(id: string): boolean {
+	return remedy_of(id) === 'rewrite'
+}
+
+const guard_remedy = {
+	GUARD_REMEDIES,
+	is_rewrite,
+	remedy_of,
+	why_of,
+}
+
+export type { GuardRemedy, Remedy }
+export { guard_remedy }

package/scripts/rules/implementation-cut.ts

@@ -7,7 +7,9 @@ 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/cut/run-cut'
+import { run_cut_decline } from '#scripts/run/cut/run-cut-decline'
 import { run_cut_handoff } from '#scripts/run/cut/run-cut-handoff'
+import { run_cut_ready } from '#scripts/run/cut/run-cut-ready'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { implementation_cut_verdict } from './implementation-cut-verdict'
@@ -62,6 +64,16 @@ interface LaneCostState {
 	// held outside a lane is told apart from a person's tree.
 	held_issue: () => string | undefined
 	verdict: () => CostVerdict
+	// Whether `run:cut --impl` could take the cut for this issue now — see `can_cut_sync`.
+	can_cut: (issue: string) => boolean
+}
+
+// **The guard asks for a cut only where `run:cut --impl` could take one** (joshuafolkken/kit#3881).
+// A run held on the default branch, or one whose cut was already answered `not-a-lane` / `unready`
+// under this hold, can only be refused again, so each refusal was a round trip that cut nothing. The
+// decline record is a file read and comes first; the tree read spawns git and comes second.
+function can_cut_sync(issue: string): boolean {
+	return !run_cut_decline.is_declined_sync(issue) && run_cut_ready.is_ready_sync()
 }
 
 function current_state(): LaneCostState {
@@ -75,6 +87,7 @@ function current_state(): LaneCostState {
 		// the window collapses one turn's burst of edits to a single whole-transcript price.
 		verdict: (): CostVerdict =>
 			implementation_cut_verdict.reused_verdict(() => cost_cli.session_verdict()),
+		can_cut: can_cut_sync,
 	}
 }
 
@@ -140,14 +153,19 @@ function warrants_the_cut(state: LaneCostState): boolean {
 // **The unmeasurable direction matches the pre-gate cut**. A session that
 // cannot be priced reads as warranting the cut, the same safety-net direction `pre-gate-cut.ts`'s
 // `warrants_the_cut` takes (`verdict !== UNDER_VERDICT`): the two rules read one statistic against one
-// threshold, so they must not disagree about whether an unmeasurable session is due a cut.
+// threshold, so they must not disagree about whether an unmeasurable session is due a cut. Whether the
+// cut could be taken is asked only once it is warranted, so an under-threshold edit spawns no git.
 function is_over_threshold_edit(
 	call: GuardedCall,
 	state: LaneCostState = current_state(),
 ): boolean {
-	if (!is_edit_tool(call.name) || uncut_run_issue(state) === undefined) return false
+	if (!is_edit_tool(call.name)) return false
+
+	const issue = uncut_run_issue(state)
+
+	if (issue === undefined) return false
 
-	return warrants_the_cut(state)
+	return warrants_the_cut(state) && state.can_cut(issue)
 }
 
 // **The threshold in the refusal text is assembled from the constant, never spelled**.
@@ -155,36 +173,14 @@ function is_over_threshold_edit(
 // building it from `CONTEXT_CUT_THRESHOLD` keeps the two from drifting. `cost_format.format_tokens` renders it the way every cost report does.
 const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
 
-// The instruction in the shape a refusal can carry: what the cut is for, what each verdict means, and
-// the reissue sentence every delivery needs. The verdicts are spelled out rather than pointed at,
-// because `cut` is the only one that ends the turn and a run told merely to "take the cut" would have to
-// read which of the others leave it implementing — the same reason `pre-gate-cut.ts` spells them out.
+// The instruction in the shape a refusal can carry: the handoff in the format the parser reads, the
+// cut, and the one verdict that ends the turn — `cut` is the only one, so a run told merely to "take
+// the cut" is not left to look it up.
 const IMPLEMENTATION_CUT_REASON =
-	'⛔ implementation-phase cut: this checkout is a lane dispatched for this issue, or a run holds it for ' +
-	'this issue (joshuafolkken/kit#2760), and its recent-context ' +
-	`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 at \`${run_cut_handoff.HANDOFF_PATH}\` (ignored, so it is never committed) with the Write tool — the user’s instruction verbatim, what you have ` +
-	'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. ' +
-	'`pnpm josh run:cut --impl <N> --handoff <path>` ends this process and relaunches a fresh one that resumes back into ' +
-	'implementation (`resume-impl`), dropping the accumulated context rather than carrying it — ' +
-	'joshuafolkken/kit#1933 built the boundary and joshuafolkken/kit#2310 measured it firing 0 times ' +
-	'because the verdict was only ever read at session entry, where the context has not yet grown. The ' +
-	"verdict is `pnpm josh cost --cut`'s exactly — the same per-request billed-input statistic against the " +
-	'same threshold, never a second measurement. Issue `pnpm josh run:cut --impl <N> --handoff <path>` now and read the ' +
-	'verdict: on `cut`, read what the command printed. Where it relaunched a fresh process, **end the turn ' +
-	'immediately** — that process owns the run and continues implementing, so it must not be waited for, ' +
-	'and **no Telegram is owed**: a cut that resumes itself leaves a person nothing to act on. Where it printed that nothing was relaunched, do what it prints, then end the turn; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
-	'`unknown`, this process carries the run on and the edit is simply the next call. Never relaunch a ' +
-	'second process after `busy`. This fired because the dispatch mark names this lane or the run hold ' +
-	'names this issue; a person working here carries no mark and holds no run, so sees no refusal, so there is no human-or-child judgement left to make. The ' +
-	'procedure is `.claude/skills/workflow-commands/pre-gate-cut.md`. Reissue this edit once the cut has ' +
-	'answered — an edit reissued right after this refusal passes, so `busy` / `failed` cannot wedge the ' +
-	'run edit after edit; this fires again on the next threshold crossing rather than once per run.'
+	`⛔ implementation-phase cut: refused on every edit past the ${THRESHOLD_TEXT} line. ` +
+	`Write \`${run_cut_handoff.HANDOFF_PATH}\` as ${run_cut_handoff.HANDOFF_FORMAT}, run ` +
+	'`pnpm josh run:cut --impl <N> --handoff <path>`; `cut`: end the turn immediately, no Telegram ' +
+	'is owed; else reissue the edit (`.claude/skills/workflow-commands/pre-gate-cut.md`).'
 
 // **A refusal younger than this window is this edit's own refusal being answered**.
 // A `decide` row that refused every over-threshold edit would wedge a run whose cut came back `busy` /
@@ -201,7 +197,8 @@ function is_reissued_refusal(now_ms: number, delivered_at_ms: number): boolean {
 // silenced the row for the rest of a process the moment its first refusal landed — and a `busy` /
 // `failed` / `unready` verdict, or an edit reissued unchanged, left the context to grow unwatched to
 // 282,747 tokens with the cut never taken. `decide` re-asks on every over-threshold edit; the reissue
-// window is what keeps that from wedging a run that genuinely cannot cut. `delivered_at_ms` is this
+// window keeps that from wedging a run whose cut came back `busy` / `failed`, and a run that cannot
+// cut at all never reaches here — `can_cut_sync` keeps the trigger silent for it. `delivered_at_ms` is this
 // row's own last refusal, written by `fire_once` only when a refusal actually fired, so a passed
 // reissue does not move it.
 function decide(
@@ -213,8 +210,8 @@ function decide(
 	return !is_reissued_refusal(run.now_ms, delivered_at_ms)
 }
 
-// The row itself, so `delivered-rules.ts` spreads one entry. `decide` fires it per threshold crossing;
-// `keeps` is the implementation cut command, read from a `Bash` call the same
+// The row itself, so `delivered-rules.ts` spreads one entry. `decide` fires it per threshold crossing
+// in a run that can cut; `keeps` is the implementation cut command, read from a `Bash` call the same
 // way `pre-gate-cut`'s is.
 const ROW = {
 	id: 'implementation-cut',
@@ -222,6 +219,11 @@ const ROW = {
 	reason: IMPLEMENTATION_CUT_REASON,
 	decide,
 	keeps: bash_triggers.on_bash_command(takes_the_impl_cut),
+	// The opening the reason carried before it was cut to the action and the next command.
+	former_reasons: [
+		'⛔ implementation-phase cut: this checkout is a lane dispatched',
+		"⛔ implementation-phase cut: this run's context crossed the",
+	],
 }
 
 const implementation_cut = {

package/scripts/rules/index-guard.ts

@@ -51,13 +51,10 @@ function is_index_mutation(command: string): boolean {
 
 const INDEX_MUTATION_REASON =
 	'⛔ git index mutation: `git add` / `stage` / `commit` / `reset` / `rm` / `mv` and `git restore ' +
-	"--staged` overwrite the user's staged snapshot, which `CLAUDE.md` → Git Rules forbids on your own " +
-	'judgement (`prompts/collaboration-workflow/operating-rules.md` → "no-self-staging"). The ' +
-	'`.claude/settings.json` deny list matches prefix globs, so it misses `git -C . commit`, `git -c ' +
-	'k=v commit` and `env git commit`; this row reads the argv instead, so the spelling does not matter. ' +
-	'A commit goes through `pnpm josh git -y`; any other staging needs explicit current-turn user ' +
-	'instruction, run by the user in their own terminal. **This rule fires on every occurrence, not once ' +
-	'per run.**'
+	"--staged` overwrite the user's staged snapshot. Commit with `pnpm josh git -y`; any other staging " +
+	"is the user's, on explicit instruction. It fires on every occurrence " +
+	'(`prompts/collaboration-workflow/operating-rules.md` → ' +
+	'"no-self-staging").'
 
 const ROW = {
 	id: 'index-mutation',