@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/review/test-titles.ts

@@ -0,0 +1,118 @@
+import type ts from 'typescript'
+import type { TypeScriptApi } from './comment-ranges'
+
+// The tests a test file declares, each as its full name — the titles of the `describe` blocks around it
+// joined to its own `it` / `test` title — so two tests with the same title under different blocks
+// stay apart.
+//
+// **Read from the TypeScript parser, never from a pattern**: a title holding a quote or a bracket, or
+// a call split over lines, is exactly what a hand-written scanner misreads. `it.skip(…)`,
+// `test.each([…])(…)` and `describe.concurrent(…)` are the same test with a modifier, so a call
+// counts by the names its callee chain is built from: Playwright's `test.describe(…)` is a block and
+// its `test.step(…)` is part of the test around it, never a test. A template title with substitutions is kept
+// as its source text; a title held in a variable has no text to compare and is not listed.
+//
+// **A `describe` is a name, never a test**: renaming one moves the tests under it, and removing it
+// removes them, so only the `it` / `test` calls are listed.
+
+const BLOCK_FUNCTION = 'describe'
+const STEP_FUNCTION = 'step'
+const TEST_FUNCTIONS: ReadonlySet<string> = new Set(['it', 'test'])
+const TITLE_SEPARATOR = ' > '
+const VIRTUAL_FILE_NAME = 'test-titles.ts'
+
+type Prefix = ReadonlyArray<string>
+
+interface NamedCall {
+	chain: ReadonlyArray<string>
+	title: string
+}
+
+interface Walk {
+	api: TypeScriptApi
+	source: ts.SourceFile
+	into: Array<string>
+}
+
+function member_name(api: TypeScriptApi, expression: ts.Expression): ReadonlyArray<string> {
+	return api.isPropertyAccessExpression(expression) ? [expression.name.text] : []
+}
+
+// The names a callee chain is built from, root first: `test.describe.parallel` is
+// `['test', 'describe', 'parallel']`, and `it.each([…])` is `['it', 'each']`.
+function callee_chain(
+	api: TypeScriptApi,
+	expression: ts.Expression,
+): ReadonlyArray<string> | undefined {
+	if (api.isIdentifier(expression)) return [expression.text]
+	const is_chained = api.isPropertyAccessExpression(expression) || api.isCallExpression(expression)
+	const chain = is_chained ? callee_chain(api, expression.expression) : undefined
+
+	return chain === undefined ? undefined : [...chain, ...member_name(api, expression)]
+}
+
+function is_block(chain: ReadonlyArray<string>): boolean {
+	return chain.includes(BLOCK_FUNCTION)
+}
+
+function is_test(chain: ReadonlyArray<string>): boolean {
+	const [root = ''] = chain
+
+	return TEST_FUNCTIONS.has(root) && !is_block(chain) && !chain.includes(STEP_FUNCTION)
+}
+
+// Only a string or a template can be a title: the array `it.each([…])` is first called with is the
+// table of cases, not a name.
+function title_of(walk: Walk, call: ts.CallExpression): string | undefined {
+	const [first] = call.arguments
+
+	if (first === undefined) return undefined
+	if (walk.api.isStringLiteralLike(first)) return first.text
+
+	return walk.api.isTemplateExpression(first) ? first.getText(walk.source) : undefined
+}
+
+function named_call(walk: Walk, node: ts.Node): NamedCall | undefined {
+	if (!walk.api.isCallExpression(node)) return undefined
+	const chain = callee_chain(walk.api, node.expression)
+	const title = chain === undefined ? undefined : title_of(walk, node)
+
+	return chain === undefined || title === undefined ? undefined : { chain, title }
+}
+
+// The block titles a call adds to the name of everything inside it: a `describe` adds its own, a
+// test is listed and adds nothing further down, and any other node passes its prefix through.
+function entered(walk: Walk, call: NamedCall | undefined, prefix: Prefix): Prefix {
+	if (call === undefined) return prefix
+	const named = [...prefix, call.title]
+
+	if (is_test(call.chain)) walk.into.push(named.join(TITLE_SEPARATOR))
+
+	return is_block(call.chain) ? named : prefix
+}
+
+function visit(walk: Walk, node: ts.Node, prefix: Prefix): void {
+	const inner = entered(walk, named_call(walk, node), prefix)
+
+	walk.api.forEachChild(node, (child) => {
+		visit(walk, child, inner)
+	})
+}
+
+function titles_of(api: TypeScriptApi, text: string): ReadonlyArray<string> {
+	const source = api.createSourceFile(VIRTUAL_FILE_NAME, text, api.ScriptTarget.Latest, true)
+	const into: Array<string> = []
+
+	visit({ api, source, into }, source, [])
+
+	return into
+}
+
+// The title a test carries itself, without the blocks around it.
+function leaf_of(full_name: string): string {
+	return full_name.split(TITLE_SEPARATOR).at(-1) ?? full_name
+}
+
+const test_titles = { leaf_of, titles_of }
+
+export { test_titles }

package/scripts/rules/agent-model.ts

@@ -0,0 +1,67 @@
+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,
+	about: {
+		title: 'Subagent model named',
+		topic:
+			'`.claude/skills/workflow-commands/delegation.md` → "A `general-purpose` subagent names its model"',
+		fires:
+			'an `Agent` / `Task` call of the `general-purpose` type with no `model`. Every occurrence',
+		quiet: 'a named agent type, or a `model` set',
+	},
+}
+
+const agent_model = { AGENT_MODEL_REASON, ROW, is_unnamed_model }
+
+export { agent_model }

package/scripts/rules/bash-triggers.ts

@@ -1,6 +1,7 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_shell } from '#scripts/time-runtime/time-shell'
+import { git_argv } from './git-argv'
 import { shell_segments } from './shell-segments'
 
 // The trigger helpers the enumeration in `delivered-rules.ts` is built from, held here so a rule
@@ -35,10 +36,52 @@ const TITLE_FIELD = /(?:-f|-F|--field|--raw-field)\s*'?title=/u
 
 // A filing made by hand rather than through `josh issue:file` — the call the `direct-filing` row
 // refuses on every occurrence.
+//
+// **Read outside quotes, but not outside a heredoc** (joshuafolkken/kit#4525). `echo "… gh issue create
+// …"` files nothing, so the `gh` call is matched on the unquoted line — which keeps a `"$(gh issue
+// create …)"` that runs. A heredoc body is matched as written: `bash <<EOF` runs it, and the body cannot
+// be told apart from prose, so the rule errs on the refusing side. The endpoint and the title field are
+// still read from the line as written, where a quoted path or field keeps them.
+//
+// **A quoted script handed to a shell runs, so it is read as written too**: `bash -c "gh issue create
+// …"`, `sh -c '…'` and `eval "…"` file the Issue the quotes would otherwise hide.
+const GH_API_COMMAND = /\bgh\s+api\b/u
+const SHELL_SCRIPT_RUNNER = /\b(?:(?:ba|z|da|k)?sh\s+(?:-\w+\s+)*-\w*c\b|eval\b)/u
+
+function spoken_line(command: string): string {
+	if (time_shell.has_heredoc(command)) return command
+
+	const plain = time_shell.unquoted(command)
+
+	return SHELL_SCRIPT_RUNNER.test(plain) ? command : plain
+}
+
+const LEADING_SHELL_SCRIPT_RUNNER = new RegExp(`^${SHELL_SCRIPT_RUNNER.source}`, 'u')
+const QUOTE_MARK = /["']/gu
+
+// The quoted script a segment's shell runs, as a line of its own: `sh -c 'pnpm exec eslint .'` reads
+// as `pnpm exec eslint .`, so a caller cutting it into commands reads the programs the script
+// launches. Only when the segment's program is the runner — `echo sh -c x` hands no script to a shell.
+// `undefined` when the segment runs no shell script.
+function shell_script_of(segment: string): string | undefined {
+	const call = git_argv.program_of(segment)
+
+	if (call === undefined) return undefined
+
+	const spoken = [call.name, ...call.args].join(' ')
+	const runner = LEADING_SHELL_SCRIPT_RUNNER.exec(spoken)
+
+	if (runner === null) return undefined
+
+	return spoken.slice(runner[0].length).replaceAll(QUOTE_MARK, '').trim()
+}
+
 function is_direct_filing(command: string): boolean {
-	if (ISSUE_CREATE_COMMAND.test(command)) return true
+	const spoken = spoken_line(command)
+
+	if (ISSUE_CREATE_COMMAND.test(spoken)) return true
 
-	return ISSUES_ENDPOINT.test(command) && TITLE_FIELD.test(command)
+	return GH_API_COMMAND.test(spoken) && ISSUES_ENDPOINT.test(command) && TITLE_FIELD.test(command)
 }
 
 // `pnpm josh issue:file`, in either spelling — **the** filing act once a direct one is refused, so the
@@ -52,6 +95,6 @@ function is_issue_filing(command: string): boolean {
 		.some((segment) => shell_segments.is_josh_command(segment, FILING_NAMES))
 }
 
-const bash_triggers = { is_direct_filing, is_issue_filing, on_bash_command }
+const bash_triggers = { is_direct_filing, is_issue_filing, on_bash_command, shell_script_of }
 
 export { bash_triggers }

package/scripts/rules/decision-oracle-batch.ts

@@ -33,6 +33,7 @@ const EPIC_NEXT_REFERENCE = 'docs/josh-commands-backlog.md → `josh epic:next`'
 const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands-backlog.md → `josh backlog:budget`'
 const RUN_LIVENESS_REFERENCE = 'docs/josh-commands-run.md → `josh run:liveness`'
 const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands-backlog.md → `josh auto-ok:next`'
+const STASH_PUSH_REFERENCE = 'docs/josh-commands-backlog.md → `josh stash:push`'
 
 // Command used by two separate oracle entries (run:cut:resume and run:cut:gate).
 const RUN_CUT_CMD = 'run:cut'
@@ -65,9 +66,16 @@ const BATCH_ORACLES: ReadonlyArray<DecisionOracle> = [
 		name: 'run:liveness',
 		decision: 'Whether a delegated unit is still working or has stopped without reporting',
 		args: `${ISSUE_N_ARG} --output <path>`,
-		vocabulary: ['alive', 'stopped', 'settled', 'undetermined'],
+		vocabulary: ['alive', 'paused', 'stopped', 'settled', 'undetermined'],
 		single_source: RUN_LIVENESS_REFERENCE,
 	},
+	{
+		name: 'stash:push',
+		decision: 'Whether the working tree had anything outside the observation ledger to set aside',
+		args: '<message>',
+		vocabulary: ['stashed', 'clean'],
+		single_source: STASH_PUSH_REFERENCE,
+	},
 	{
 		name: 'stash:pop',
 		decision: 'Whether a named stash entry exists and can be applied',

package/scripts/rules/decision-oracle.ts

@@ -152,9 +152,9 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 	{
 		name: 'cases',
 		decision:
-			'Each boundary a change crosses (network, process, fs, time) and the abnormal cases it owes',
+			'Each boundary a change crosses (network, process, fs, time, shared state, environment) and the abnormal cases it owes',
 		args: '<path...>',
-		vocabulary: ['network', 'process', 'fs', 'time', NONE],
+		vocabulary: ['network', 'process', 'fs', 'time', 'state', 'env', NONE],
 		single_source: 'prompts/collaboration-workflow/report-format.md → 変更とテスト',
 	},
 	{

package/scripts/rules/delivered-rules.ts

@@ -2,8 +2,10 @@ 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 { direct_issue_comment } from './direct-issue-comment'
 import { early_heartbeat } from './early-heartbeat'
 import { file_body } from './file-body'
 import { filing_cap } from './filing-cap'
@@ -13,6 +15,7 @@ import { issue_comments } from './issue-comments'
 import { josh_git_bare } from './josh-git-bare'
 import { lane_background } from './lane-background'
 import { lane_carry_conflict } from './lane-carry-conflict'
+import { lane_direct_tool } from './lane-direct-tool'
 import { lane_interactive_ask } from './lane-interactive-ask'
 import { lane_park } from './lane-park'
 import { lane_split_park } from './lane-split-park'
@@ -28,6 +31,7 @@ import { run_tail_rule } from './run-tail-rule'
 import { shell_body_trigger } from './shell-body-trigger'
 import { test_declared_commit } from './test-declared-commit'
 import { third_party_write } from './third-party-write'
+import { timed_rerun } from './timed-rerun'
 import { worktree_guard } from './worktree-guard'
 
 // The rules delivered by a `PreToolUse` refusal at the moment they bind, rather than carried resident
@@ -46,12 +50,32 @@ 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
+
+// The human-readable side `pnpm josh rule:list` renders, carried on the row so a rule is one entry.
+interface RuleAbout {
+	title: string
+	// The single source of the rule's procedure.
+	topic: string
+	fires: string
+	// The silent turn — it matches the state in which the rule is already kept.
+	quiet: string
+	// The hook command that delivers it; absent reads as `PRETOOL_GUARD`.
+	entry?: string
+}
+
+// Every row here — batching and investigation included — is delivered by the one `PreToolUse`
+// process (`scripts/hooks/pretool-guard.ts`).
+const PRETOOL_GUARD = 'pnpm josh pretool:guard'
+
 // `id` keys the rule's own refusal record, so one rule firing never spends another's budget.
 interface DeliveredRule {
 	id: string
 	is_trigger: (call: GuardedCall) => boolean
 	// The only text that reaches the model: the instruction and the pointer.
 	reason: string
+	about: RuleAbout
 	// A stand-down when an earlier act on the tail already satisfied the rule; checked first, so a
 	// satisfied call spends no record.
 	already_satisfied?: (tail: string, call: GuardedCall) => boolean
@@ -63,6 +87,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
@@ -71,7 +98,7 @@ interface DeliveredRule {
 	former_reasons?: ReadonlyArray<string>
 }
 
-// Scored but possibly delivered by its own binary (batching, investigation) — joining `DELIVERED_RULES`
+// Scored but possibly delivered by its own guard inside `pretool-guard.ts` (batching, investigation) — joining `DELIVERED_RULES`
 // would refuse one violation twice — so `is_trigger` is optional here.
 type MeasuredRule = Omit<DeliveredRule, 'is_trigger'> & {
 	is_trigger?: DeliveredRule['is_trigger']
@@ -91,6 +118,9 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 	// The direct call only; `filing-cap` below triggers on `issue:file`. The WIP cap and the fold
 	// question are `issue:file`'s own steps, so no row gates them.
 	direct_filing.ROW,
+	// Before the body rows: a comment posted by hand is refused whatever its body, and the command it
+	// points at takes the body by path, so the body rows have nothing left to say.
+	direct_issue_comment.ROW,
 	filing_cap.ROW,
 	issue_comments.ROW,
 	{
@@ -99,6 +129,13 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		reason: SHELL_BODY_REASON,
 		keeps: on_bash_command(keeps_body_safe),
 		reaches: on_bash_command(carries_a_body),
+		about: {
+			title: 'No body on the shell',
+			topic: '`shell-body.md`',
+			fires:
+				'a double-quoted body value (`-f body="…"` / `-f "body=…"` / `--body "…"` / `--notify-message "…"`) carrying a backtick or `$`',
+			quiet: 'the shell does not evaluate the body',
+		},
 	},
 	raw_field_body.ROW,
 	{
@@ -107,8 +144,16 @@ 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,
+		about: {
+			title: 'Piped verification',
+			topic: '`output-bounds.md`',
+			fires:
+				'a pass/fail josh check (`gate` / `check` / `lint*` / `cspell*` / `test*` / `eval` / `overrides` / `ranges`) in front of a pipe — rewritten under `set -o pipefail` when every filter is `tail` or a full-reading `grep`, refused otherwise',
+			quiet: 'the exit code reaches the caller — a failure reads as a failure',
+		},
 	},
 	{
 		id: 'early-heartbeat',
@@ -117,6 +162,14 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		decide: early_heartbeat.decide,
 		keeps: on_bash_command(early_heartbeat.is_progress_watch),
 		reaches: on_bash_command(early_heartbeat.waits_for_progress),
+		about: {
+			title: 'Early progress report',
+			topic:
+				'`.claude/skills/workflow-commands/progress-watcher.md` → "Progress while the run is quiet"',
+			fires:
+				'a `Bash` whose only purpose is waiting (`sleep` alone, or `echo` / `:` / `date`) while a timer is live or before the interval. Every occurrence',
+			quiet: 'no hand-made wait timer — `run:progress` holds the one clock',
+		},
 	},
 	// Before `run-tail`: whether to commit at all is decided before how to push.
 	test_declared_commit.ROW,
@@ -130,6 +183,13 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		decide: run_tail_rule.decide,
 		keeps: run_tail_rule.is_backgrounded_push_step,
 		reaches: run_tail_rule.is_push_step_call,
+		about: {
+			title: 'Idle run tail',
+			topic: '`.claude/skills/workflow-commands/background-commands.md`',
+			fires:
+				'`pnpm josh git -y` (`josh g`, `--yes` alike) issued in the **foreground**. Every occurrence',
+			quiet: 'issued in the background — its completion resumes the run',
+		},
 	},
 	// Reads the lane name and the cut record. Once per run, not `decide`: taking the cut ends the
 	// process, and the verdicts that leave a run at the gate all need the reissue through. `reaches`
@@ -141,13 +201,25 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		reason: pre_gate_cut.PRE_GATE_CUT_REASON,
 		keeps: on_bash_command(pre_gate_cut.takes_the_cut),
 		reaches: pre_gate_cut.reaches_the_pre_gate_boundary,
+		about: {
+			title: 'The cut before the gate',
+			topic: '`.claude/skills/workflow-commands/pre-gate-cut.md`',
+			fires:
+				'`pnpm josh gate` (`josh ga`) in a lane work tree whose `JOSH_LANE_CHILD` names the Issue and has no cut record',
+			quiet: 'outside a lane, no marker (a person in the lane), or already cut',
+		},
 	},
 	// A split child's park is refused before `lane-park` sees it.
 	lane_split_park.ROW,
 	lane_park.ROW,
 	lane_interactive_ask.ROW,
+	agent_model.ROW,
 	lane_carry_conflict.ROW,
 	lane_switch_main.ROW,
+	// Before `lane-direct-tool`, its one overlap (a timed tool in a lane): the record is the right first
+	// act, and `lane-direct-tool` delivers on the reissue of a `time`-prefixed tool.
+	timed_rerun.ROW,
+	lane_direct_tool.ROW,
 	// Disjoint from `run-tail` by the `-y` flag.
 	josh_git_bare.ROW,
 	// The Bash-string gaps the deny glob cannot express, read by argv; `delivered-rules-bash.test.ts`
@@ -177,6 +249,13 @@ const BATCHING_RULE: MeasuredRule = {
 	reason: time_batch_guard.REASON,
 	keeps: batches_the_turn,
 	reaches: time_batch_guard.is_guarded_call,
+	about: {
+		title: 'Turn batching',
+		topic: '`turn-batching.md`',
+		fires:
+			'the `Bash` / `Edit` / `Read` after three single-call turns in a row; fires **again** every three more such turns',
+		quiet: 'calls per round trip above the floor',
+	},
 }
 
 // No `is_trigger`, as for batching. No `keeps`: any dispatch would read as compliance, so it is left
@@ -185,6 +264,13 @@ const INVESTIGATION_RULE: MeasuredRule = {
 	id: 'investigation',
 	reason: investigation_reads.REASON,
 	reaches: investigation_reads.is_refusable_call,
+	about: {
+		title: 'Investigation delegation threshold',
+		topic: '`delegation.md`',
+		fires:
+			'the `Read` / `Bash` that makes the third read of a file the run will not edit; fires **again** once reads pile up to the threshold again',
+		quiet: 'reads under the threshold — nothing to delegate yet',
+	},
 }
 
 const MEASURED_RULES: ReadonlyArray<MeasuredRule> = [
@@ -291,6 +377,7 @@ const delivered_rules = {
 	PIPED_VERIFICATION_REASON: piped_verification.PIPED_VERIFICATION_REASON,
 	POLL_LOOP_REASON: poll_loop.POLL_LOOP_REASON,
 	PRE_GATE_CUT_REASON: pre_gate_cut.PRE_GATE_CUT_REASON,
+	PRETOOL_GUARD,
 	RAW_FIELD_BODY_REASON: raw_field_body.RAW_FIELD_BODY_REASON,
 	RUN_TAIL_REASON: run_tail_rule.RUN_TAIL_REASON,
 	SHELL_BODY_REASON,
@@ -304,5 +391,5 @@ const delivered_rules = {
 	is_issue_filing,
 }
 
-export type { DeliveredRule, MeasuredRule }
+export type { CallRewrite, DeliveredRule, MeasuredRule, RuleAbout }
 export { delivered_rules }

package/scripts/rules/destructive-command.ts

@@ -93,7 +93,7 @@ function is_destructive_segment(segment: string): boolean {
 }
 
 function is_destructive_command(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_destructive_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_destructive_segment(segment))
 }
 
 const DESTRUCTIVE_COMMAND_REASON =
@@ -109,6 +109,13 @@ const ROW = {
 	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`'],
+	about: {
+		title: 'Destructive command',
+		topic: '`operating-rules.md`',
+		fires:
+			'`rm -rf` (any spelling), `gh repo delete` / `archive`, `gh pr close`, `gh api -X DELETE`. Every occurrence',
+		quiet: "`gh issue close` or removing an Issue label — the workflow's own steps",
+	},
 }
 
 const destructive_command = { DESTRUCTIVE_COMMAND_REASON, ROW, is_destructive_command }

package/scripts/rules/direct-filing.ts

@@ -8,8 +8,8 @@ import { bash_triggers } from './bash-triggers'
 // pointed there.
 
 const DIRECT_FILING_REASON =
-	'⛔ direct filing: an Issue is filed with `pnpm josh issue:file "<title>" --body-file <path> ' +
-	'--depth <0|1|2>`, never with `gh api …/issues` or `gh issue create` — it runs the scout, the lint, ' +
+	'⛔ direct filing: an Issue is filed with `pnpm josh issue:file "<title>" --body-file <path>`, ' +
+	'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`").'
 
@@ -27,6 +27,14 @@ const ROW = {
 	decide: (): boolean => true,
 	keeps: bash_triggers.on_bash_command(bash_triggers.is_issue_filing),
 	reaches: bash_triggers.on_bash_command(is_any_filing),
+	about: {
+		title: 'Direct filing',
+		topic: '`docs/josh-commands-backlog.md` → `josh issue:file`',
+		fires:
+			'a `Bash` that creates an Issue outside `josh issue:file` (`gh issue create`, or a POST with `title` to `…/issues`); the refusal hands over the `pnpm josh issue:file` form. Every occurrence',
+		quiet:
+			'filing through `pnpm josh issue:file` — the duplicate scan, the body check and `epic:bundle` all run',
+	},
 }
 
 const direct_filing = { DIRECT_FILING_REASON, ROW }