@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/review/review-untouched-readers.ts

@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { git_grep_hits, type Hit } from '#scripts/git/git-grep-hits'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { review_readers_scan, type Edited } from './review-readers-scan'
+
+// The readers outside the diff of each exported name the diff edits, listed in the brief
+// (joshuafolkken/kit#4515). A reader the change left on the old meaning was the most common kind of
+// finding that stopped a lane review; the self-check's "Every caller moved with it" asked for the
+// search and left it to the implementer, and this does it mechanically for the reviewer to read.
+//
+// **A reader is a line outside the changed paths that names the edited name as a word** — a
+// re-derivation or an alias is not found, and the list says so. A grep that could not run is printed
+// as such, never as "no readers".
+
+const SOURCE_FILE = /\.(?:ts|js)$/u
+const SEARCH_PATHS = ['*.ts', '*.js', '*.svelte', ':(exclude)*.snap']
+const WORD_FLAG = '-w'
+const MAX_HITS = 10
+const MAX_NAMES = 30
+const HEADING = '## Readers outside the diff'
+const ROLE_LINE =
+	'Each exported name this change edits, with every line outside the changed paths that names it (`git grep -w`). Check each reader still holds under the new meaning — the self-check\'s "Every caller moved with it" (`prompts/review.md`). A reader left on the old meaning is a finding at the reader\'s `file:line`. A reader reaching the name through an alias or a re-derivation is not listed.'
+const SEARCH_FAILED = '  - git grep failed; not searched'
+const READ_FAILED = 'The readers outside the diff could not be read; search them yourself:'
+const OMITTED_TAIL = 'not searched; search their readers yourself'
+
+interface Readers {
+	target: string
+	origin: string
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+// `omitted` counts the edited names past `MAX_NAMES`, which were never searched.
+interface ReadersRead {
+	readers: ReadonlyArray<Readers>
+	omitted: number
+	has_failed: boolean
+}
+
+const NO_READ: ReadersRead = { readers: [], omitted: 0, has_failed: false }
+const FAILED_READ: ReadersRead = { readers: [], omitted: 0, has_failed: true }
+
+interface ReadRequest {
+	root: string
+	base: string
+	paths: ReadonlyArray<string>
+}
+
+interface FileEdits {
+	relative: string
+	edits: ReadonlyArray<Edited>
+}
+
+async function file_edits(request: ReadRequest, relative: string): Promise<FileEdits> {
+	const { root, base } = request
+	const diff = await git_spawn.read(['-C', root, 'diff', '-U0', '--no-color', base, '--', relative])
+
+	if (diff.length === 0) return { relative, edits: [] }
+
+	// A path the change deletes has no text; its readers fail the typecheck rather than read stale.
+	try {
+		const source = readFileSync(path.join(root, relative), 'utf8')
+
+		return { relative, edits: review_readers_scan.edited(source, diff) }
+	} catch {
+		return { relative, edits: [] }
+	}
+}
+
+function excluded(paths: ReadonlyArray<string>): Array<string> {
+	return paths.map((relative) => `:(exclude,literal)${relative}`)
+}
+
+async function readers_of(request: ReadRequest, entry: FileEdits, edit: Edited): Promise<Readers> {
+	const pathspecs = [...SEARCH_PATHS, ...excluded(request.paths)]
+	const found = await git_grep_hits.search(edit.target, [WORD_FLAG], pathspecs, request.root)
+
+	return { target: edit.target, origin: `${entry.relative}:${String(edit.line)}`, ...found }
+}
+
+// Every edited name, with its readers outside `paths`. Only names that have a reader, or whose search
+// failed, are returned; the names past the cap are counted, never dropped silently.
+async function read(request: ReadRequest): Promise<ReadersRead> {
+	const sources = request.paths.filter((relative) => SOURCE_FILE.test(relative))
+	const files = await Promise.all(
+		sources.map(async (relative) => await file_edits(request, relative)),
+	)
+	const pairs = files.flatMap((entry) => entry.edits.map((edit) => ({ entry, edit })))
+	const capped = pairs.slice(0, MAX_NAMES)
+	const all = await Promise.all(
+		capped.map(async ({ entry, edit }) => await readers_of(request, entry, edit)),
+	)
+
+	const readers = all.filter((entry) => entry.has_failed || entry.hits.length > 0)
+
+	return { readers, omitted: pairs.length - capped.length, has_failed: false }
+}
+
+function hit_line(hit: Hit): string {
+	return `  - ${hit.path}:${hit.line}  ${hit.excerpt}`
+}
+
+function readers_lines(readers: Readers): Array<string> {
+	const head = `- \`${readers.target}\` — ${readers.origin}`
+
+	if (readers.has_failed) return [head, SEARCH_FAILED]
+
+	const more = readers.hits.length - MAX_HITS
+	const tail = more > 0 ? [`  - … and ${String(more)} more`] : []
+
+	return [head, ...readers.hits.slice(0, MAX_HITS).map((hit) => hit_line(hit)), ...tail]
+}
+
+function omitted_lines(omitted: number): Array<string> {
+	if (omitted === 0) return []
+
+	return [`- … and ${String(omitted)} more edited names ${OMITTED_TAIL}`]
+}
+
+// A read that failed as a whole says so, never reads as a change with no reader outside it; absent
+// or empty, no section.
+function brief_block(read_result: ReadersRead = NO_READ): ReadonlyArray<string> {
+	const { readers, omitted, has_failed } = read_result
+
+	if (has_failed) return ['', `${HEADING}\n${READ_FAILED}`]
+	if (omitted === 0 && readers.length === 0) return []
+
+	const listed = readers.flatMap((entry) => readers_lines(entry))
+
+	return ['', [HEADING, ROLE_LINE, ...listed, ...omitted_lines(omitted)].join('\n')]
+}
+
+const review_untouched_readers = {
+	brief_block,
+	FAILED_READ,
+	HEADING,
+	MAX_NAMES,
+	OMITTED_TAIL,
+	read,
+	READ_FAILED,
+}
+
+export type { Readers, ReadersRead }
+export { review_untouched_readers }

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

@@ -52,6 +52,14 @@ const ROW = {
 	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 }

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

@@ -5,6 +5,7 @@ import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-b
 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'
@@ -14,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'
@@ -29,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
@@ -50,12 +53,29 @@ type CallTest = (
 // 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
@@ -78,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']
@@ -98,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,
 	{
@@ -106,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,
 	{
@@ -117,6 +147,13 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		// 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',
@@ -125,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,
@@ -138,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`
@@ -149,6 +201,13 @@ 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,
@@ -157,6 +216,10 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 	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`
@@ -186,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
@@ -194,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> = [
@@ -300,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,
@@ -313,5 +391,5 @@ const delivered_rules = {
 	is_issue_filing,
 }
 
-export type { CallRewrite, 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 }