@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/rule-value-candidates.ts

@@ -0,0 +1,84 @@
+import { delivered_rules, type MeasuredRule } from './delivered-rules'
+import type { RuleReading } from './rule-value'
+
+// The rules `rule:value`'s reading says can go or shrink — the evidence
+// `prompts/collaboration-workflow/residency.md` lets a retirement or a condensation rest on. **It lists, never removes**: each candidate is retired or condensed in an
+// Issue of its own, or kept with a recorded reason.
+//
+// - **Retire**: no run reached the rule, over a window large enough for "never" to mean something.
+//   Below it nothing is judged, since a fresh checkout reaches no rule at all. **Measurable rows
+//   only**: an unmeasured row's trigger is the violation itself, so its `reached 0` says the rule was
+//   never broken — the guard working — not that its situation never arose. A measurable row's trigger
+//   is a neutral act or it declares `reaches` (`rule-value.ts`, `RuleReading.sessions`).
+// - **Condense**: the hook refuses the rule on every occurrence (`decide`) and has refused it at least
+//   once, so the prose need only point at the row — the hook, not the text, keeps it.
+
+// The one threshold: the runs a reading must cover before a rule no run reached is a retirement
+// candidate.
+const MIN_RUNS_FOR_RETIREMENT = 20
+const SEPARATOR = ', '
+const NONE = 'none'
+
+interface RuleCandidates {
+	retire: ReadonlyArray<string>
+	condense: ReadonlyArray<string>
+}
+
+function retire_candidates(readings: ReadonlyArray<RuleReading>, runs: number): Array<string> {
+	if (runs < MIN_RUNS_FOR_RETIREMENT) return []
+
+	return readings
+		.filter((reading) => reading.is_measurable && reading.sessions === 0)
+		.map((reading) => reading.id)
+}
+
+function is_enforced_on_every_occurrence(id: string, rules: ReadonlyArray<MeasuredRule>): boolean {
+	return rules.some((rule) => rule.id === id && rule.decide !== undefined)
+}
+
+function condense_candidates(
+	readings: ReadonlyArray<RuleReading>,
+	rules: ReadonlyArray<MeasuredRule> = delivered_rules.MEASURED_RULES,
+): Array<string> {
+	return readings
+		.filter((reading) => reading.refusals > 0)
+		.filter((reading) => is_enforced_on_every_occurrence(reading.id, rules))
+		.map((reading) => reading.id)
+}
+
+function judge(
+	readings: ReadonlyArray<RuleReading>,
+	runs: number,
+	rules: ReadonlyArray<MeasuredRule> = delivered_rules.MEASURED_RULES,
+): RuleCandidates {
+	return {
+		retire: retire_candidates(readings, runs),
+		condense: condense_candidates(readings, rules),
+	}
+}
+
+function listed(ids: ReadonlyArray<string>): string {
+	return ids.length === 0 ? NONE : ids.join(SEPARATOR)
+}
+
+function render(candidates: RuleCandidates, runs: number): string {
+	const window = `${runs.toString()} runs, threshold ${MIN_RUNS_FOR_RETIREMENT.toString()}`
+
+	return [
+		'candidates:',
+		`  retire (reached 0; ${window}): ${listed(candidates.retire)}`,
+		`  condense (refused on every occurrence by its hook): ${listed(candidates.condense)}`,
+	].join('\n')
+}
+
+const rule_value_candidates = {
+	condense_candidates,
+	judge,
+	render,
+	retire_candidates,
+	MIN_RUNS_FOR_RETIREMENT,
+	NONE,
+}
+
+export type { RuleCandidates }
+export { rule_value_candidates }

package/scripts/rules/rule-value-cli.ts

@@ -2,8 +2,10 @@
 import { fileURLToPath } from 'node:url'
 import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
 import { delivered_rules } from './delivered-rules'
+import { piped_verification_shapes, type ShapeCounts } from './piped-verification-shapes'
 import { rule_value, type RuleReading } from './rule-value'
-import { rule_value_cache } from './rule-value-cache'
+import { rule_value_cache, type FreshReading } from './rule-value-cache'
+import { rule_value_candidates } from './rule-value-candidates'
 
 // `josh rule:value` — what each delivered rule earns on the channel that carries it, one row per rule.
 // `rule_value.measure` was public but had no caller outside its own test, so
@@ -17,6 +19,8 @@ import { rule_value_cache } from './rule-value-cache'
 
 const ARGV_OFFSET = 2
 const REFRESH_FLAG = '--refresh'
+const FRESH_FLAG = '--fresh'
+const CACHED_NOTE = 'cached reading taken at'
 const PERCENT_SIGN = '%'
 const COLUMN_GAP = '  '
 const NO_TARGETS = 'no measurement targets'
@@ -26,46 +30,65 @@ const UNMEASURED = 'unmeasured'
 // A measurable rule no run reached: the denominator is zero, so no rate is taken over it.
 const UNREACHED = 'unreached'
 
-interface OwnedText {
-	owner: string
-	text: string
-}
-
-function owned_text(file: SessionFile): OwnedText | undefined {
-	const text = cost_transcript.read_optional(file)
-
-	if (text === undefined) return undefined
-
-	return { owner: cost_transcript.owning_session_id(file), text }
-}
-
 // Every transcript grouped by the run it belongs to: a session's own file and the units it delegated
 // share one `owning_session_id`, so a lane child is counted with its parent rather than as a run of
-// its own — the unit `rule_value.measure` reads.
-function group_by_run(files: ReadonlyArray<SessionFile>): Map<string, Array<string>> {
-	const runs = new Map<string, Array<string>>()
+// its own — the unit `rule_value.measure` reads. **Paths only**: no text is read here, so the
+// grouping never holds the corpus.
+function group_by_run(files: ReadonlyArray<SessionFile>): Map<string, Array<SessionFile>> {
+	const runs = new Map<string, Array<SessionFile>>()
 
 	for (const file of files) {
-		const owned = owned_text(file)
-
-		if (owned === undefined) continue
+		const owner = cost_transcript.owning_session_id(file)
+		const owned = runs.get(owner) ?? []
 
-		const texts = runs.get(owned.owner) ?? []
-
-		texts.push(owned.text)
-		runs.set(owned.owner, texts)
+		owned.push(file)
+		runs.set(owner, owned)
 	}
 
 	return runs
 }
 
+function readable_texts(files: ReadonlyArray<SessionFile>): Array<string> {
+	return files
+		.map((file) => cost_transcript.read_optional(file))
+		.filter((text): text is string => text !== undefined)
+}
+
+// **One run read at a time.** Each run's text is read only when `measure` asks for it and released
+// before the next is read, so the peak is the largest run rather than the whole corpus. A run whose
+// every file is unreadable yields nothing, as it was never a measurement target.
+function* runs_of(groups: Iterable<ReadonlyArray<SessionFile>>): Generator<Array<string>> {
+	for (const files of groups) {
+		const texts = readable_texts(files)
+
+		if (texts.length > 0) yield texts
+	}
+}
+
 // Every run reachable from the working tree — the session's own transcript directory and any lane
-// slugs beneath its main checkout — grouped into the shape `rule_value.measure` reads.
-function gather_runs(cwd: string = process.cwd()): Array<Array<string>> {
+// slugs beneath its main checkout — in the shape `rule_value.measure` reads.
+function gather_runs(cwd: string = process.cwd()): Generator<Array<string>> {
 	const directories = cost_transcript.transcript_directories(cwd)
 	const files = cost_transcript.list_sessions_across(directories)
 
-	return [...group_by_run(files).values()]
+	return runs_of(group_by_run(files).values())
+}
+
+// The `piped-verification` refusals are named by shape in the same pass, so the corpus is read once.
+interface Tally {
+	runs: number
+	shapes: ShapeCounts
+}
+
+function* counted(
+	runs: Iterable<ReadonlyArray<string>>,
+	tally: Tally,
+): Generator<ReadonlyArray<string>> {
+	for (const texts of runs) {
+		tally.runs += 1
+		for (const text of texts) piped_verification_shapes.count(text, tally.shapes)
+		yield texts
+	}
 }
 
 // The id column, wide enough for the longest rule id, so the reading lines up whatever the registry
@@ -92,24 +115,65 @@ function row(reading: RuleReading): string {
 	return [id, reached, rate_text(reading), refused, ...rewritten].join(COLUMN_GAP)
 }
 
+// `candidates` is set only where something measurable was found, so `NO_TARGETS` stays the whole answer.
+interface Rendered {
+	table: string
+	candidates?: string
+}
+
 // The reading as text, or `NO_TARGETS` when nothing measurable was found — never an empty output that
 // would read as a broken command.
-function render(runs: ReadonlyArray<ReadonlyArray<string>>): string {
-	if (runs.length === 0) return NO_TARGETS
+// The runs are counted as `measure` consumes them, since a lazy source cannot be asked its length
+// up front.
+function render_parts(runs: Iterable<ReadonlyArray<string>>): Rendered {
+	const tally: Tally = { runs: 0, shapes: new Map() }
+	const readings = rule_value.measure(counted(runs, tally))
+
+	if (tally.runs === 0) return { table: NO_TARGETS }
+
+	const judged = rule_value_candidates.judge(readings, tally.runs)
+	const shapes = piped_verification_shapes.render(tally.shapes)
 
-	return rule_value
-		.measure(runs)
-		.map((reading) => row(reading))
-		.join('\n')
+	return {
+		table: readings.map((reading) => row(reading)).join('\n'),
+		candidates: `${rule_value_candidates.render(judged, tally.runs)}\n${shapes}`,
+	}
 }
 
-// `--refresh` is the detached measurement the `backlogrun` loop head starts: the reading goes to the
-// cache `backlog:offer` prints from, never to stdout (`rule-value-cache.ts`).
-function run_rule_value(argv: ReadonlyArray<string> = [], cwd: string = process.cwd()): number {
-	const reading = render(gather_runs(cwd))
+function render(runs: Iterable<ReadonlyArray<string>>): string {
+	return render_parts(runs).table
+}
+
+// The cached table and when it was taken. The cache holds the table alone, so the line names the flag
+// that measures now for the `candidates:` section too.
+function cached_text(fresh: FreshReading): string {
+	const taken_at = fresh.taken_at.toISOString()
 
-	if (argv.includes(REFRESH_FLAG)) rule_value_cache.store(reading, cwd)
-	else process.stdout.write(`${reading}\n`)
+	return `${fresh.text.trimEnd()}\n\n${CACHED_NOTE} ${taken_at} — ${FRESH_FLAG} to measure now, with candidates`
+}
+
+function print_measured(cwd: string): void {
+	const { table, candidates } = render_parts(gather_runs(cwd))
+
+	process.stdout.write(`${[table, candidates].filter(Boolean).join('\n\n')}\n`)
+}
+
+function print_reading(argv: ReadonlyArray<string>, cwd: string): void {
+	const fresh = argv.includes(FRESH_FLAG) ? undefined : rule_value_cache.read_fresh(cwd)
+
+	if (fresh === undefined) print_measured(cwd)
+	else process.stdout.write(`${cached_text(fresh)}\n`)
+}
+
+// `--refresh` is the detached measurement the `backlogrun` loop head starts: the table goes to the
+// cache `backlog:offer` prints from, never to stdout (`rule-value-cache.ts`). The candidates are read
+// when a rule is retired, not at the loop head, so they print to stdout only and the cache keeps its
+// shape. Bare, a reading cached inside the refresh interval is printed instead of measuring again —
+// the measurement re-reads every transcript and takes minutes (joshuafolkken/kit#5186); `--fresh`
+// measures regardless.
+function run_rule_value(argv: ReadonlyArray<string> = [], cwd: string = process.cwd()): number {
+	if (argv.includes(REFRESH_FLAG)) rule_value_cache.store(render_parts(gather_runs(cwd)).table, cwd)
+	else print_reading(argv, cwd)
 
 	return 0
 }
@@ -121,8 +185,11 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 const rule_value_cli = {
 	group_by_run,
 	render,
+	render_parts,
 	row,
 	run_rule_value,
+	runs_of,
+	CACHED_NOTE,
 	NO_TARGETS,
 	UNMEASURED,
 	UNREACHED,

package/scripts/rules/rule-value.ts

@@ -40,7 +40,7 @@ const PERCENT = 100
 // **A refusal is an errored result, which is what separates it from a read of the file it is written
 // in.** Every signature exists verbatim in the module its rule is written in — the six delivered
 // rules in `scripts/rules/delivered-rules.ts`, the batching row's in
-// `scripts/time/time-batch-guard.ts` — so a session that
+// `tools/time/time-batch-guard.ts` — so a session that
 // merely opened that file carries the text too — and did so in a result whose `is_error` is false.
 //
 // **That fact is read off the parsed block, never off the raw line**. The
@@ -159,7 +159,8 @@ function observe_call(
 }
 
 // One transcript line, parsed once, as the things a reading is taken from: the calls it issued, the
-// bodies of the results the harness wrote back as failures, and the context a hook attached.
+// refusals the harness wrote back (failed results and Stop-hook blocks), and the context a hook
+// attached.
 interface DatedLine {
 	at_ms: number
 	message_id: string
@@ -183,6 +184,14 @@ function errors_of(parsed: TranscriptLine): Array<string> {
 		.filter((text) => text !== '')
 }
 
+// **A Stop-hook block is a refusal too** — of ending the turn — so its reason joins the
+// tool results the harness wrote back as failures (joshuafolkken/kit#4978).
+function refusals_of(parsed: TranscriptLine): Array<string> {
+	const errors = errors_of(parsed)
+
+	return parsed.stop_feedback === '' ? errors : [...errors, parsed.stop_feedback]
+}
+
 function dated_line(line: string): DatedLine | undefined {
 	const parsed = line === '' ? undefined : time_transcript_line.parse_line(line)
 
@@ -192,7 +201,7 @@ function dated_line(line: string): DatedLine | undefined {
 		at_ms: parsed.timestamp_ms,
 		message_id: parsed.message_id,
 		calls: calls_of(parsed),
-		errors: errors_of(parsed),
+		errors: refusals_of(parsed),
 		contexts: hook_context_line.hook_contexts_of(line),
 	}
 }
@@ -250,10 +259,14 @@ function turns_by_key(entries: ReadonlyArray<DatedLine>): Map<string, Array<Issu
 // each of them; the file opens with its imports, so under this test nothing claims it. Position is
 // what separates the two, so no count of how many signatures appear is needed — and a body naming
 // several can no longer be attributed to any of them.
+//
+// **The harness's own label is not the body.** It writes a deny as `PreToolUse:<Tool> hook error: ⛔ …`,
+// so the label is stripped before the opening is read; compared raw, no recorded refusal matched
+// (joshuafolkken/kit#4961).
 function refused_id(text: string): string | undefined {
-	const body = text.trimStart()
+	const body = time_transcript_line.refusal_body(text)
 	const found = delivered_rules.MEASURED_RULES.find((rule) =>
-		[rule.reason, ...(rule.former_reasons ?? [])].some((reason) =>
+		[rule.reason, ...(rule.former_reasons ?? []), ...(rule.stop_reasons ?? [])].some((reason) =>
 			body.startsWith(reason.slice(0, REASON_SIGNATURE_LENGTH)),
 		),
 	)

package/scripts/rules/run-tail-rule.ts

@@ -35,7 +35,7 @@ import { shell_segments } from './shell-segments'
 // one command cannot disagree: an opening subshell parenthesis, environment assignments, and the
 // package-manager wrapper in either of its spellings. Left out, `JOSH_CI_TIMEOUT_SECONDS=600 pnpm
 // josh git -y` and `(pnpm josh git -y)` are silently not the push step, and the run pays the tail the
-// rule exists to stop. `g` is the alias `josh-command-map.ts` resolves to `git`.
+// rule exists to stop. `g` is the alias `josh-aliases.ts` resolves to `git`.
 const SEGMENT_PREFIX = String.raw`(?:\(\s*)?(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:npx\s+|pnpm\s+(?:exec\s+|run\s+)?)?`
 // A closing parenthesis ends a word as a space does, so every boundary below admits it — without
 // that, a subshell defeats the flag test even where it does not defeat the command test.

package/scripts/rules/sed-in-place.ts

@@ -0,0 +1,196 @@
+import { file_reader } from '#scripts/lib/read-file'
+import { bash_triggers } from './bash-triggers'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `sed-in-place` row of `delivered-rules.ts`: a `sed -i`
+// that `file-edits.md`'s countable conditions do not clear (joshuafolkken/kit#5284).
+//
+// **The conditions are counts, so the guard counts them.** `file-edits.md` allows `sed -i` only for a
+// single `s` command whose pattern carries no meta character and matches exactly once in each target
+// file. Anything else — a meta character, a count other than one, a script that is not one `s` command —
+// can rewrite a line the run never meant to touch, and `Edit` is the tool that cannot.
+//
+// It fires on every occurrence, for the reason `file-body.ts` does.
+
+const SED = 'sed'
+// `-i`, `-i.bak`, `-Ei`: a short cluster carrying the in-place switch; `--in-place[=suffix]` long.
+const IN_PLACE_SHORT = /^-[A-Za-z]*i/u
+const IN_PLACE_LONG = /^--in-place(?:=|$)/u
+// A short cluster ending in the in-place switch: BSD reads its suffix from the next word.
+const IN_PLACE_CLUSTER = /^-[A-Za-z]*i$/u
+// `-E`, `-r`, `--regexp-extended`: the pattern is read as an extended regex, where `+ ? ( ) { } |`
+// are meta characters too, so a plain-text count no longer says what sed matches.
+const EXTENDED_SHORT = /^-[A-Za-z]*[Er]/u
+const EXTENDED_LONG = '--regexp-extended'
+// The `s` flags that keep the match plain text: none, or `g` (each line holds one match at most when
+// the count is one). `I`, `w file`, a number and the rest change what or where sed writes.
+const PLAIN_FLAGS: ReadonlySet<string> = new Set(['', 'g'])
+const SCRIPT_FLAG = '-e'
+const FLAG_PREFIX = '-'
+const SURROUNDING_QUOTES = /^(['"])(.*)\1$/su
+const QUOTED_BODY = 2
+// `file-edits.md`'s meta characters: `/ & \ . * [ ] ^ $`.
+const META_CHARACTER = /[/&\\.*[\]^$]/u
+const SUBSTITUTE = 's'
+const SUBSTITUTE_PARTS = 3
+const ONE_MATCH = 1
+
+interface SedCall {
+	scripts: Array<string>
+	files: Array<string>
+}
+
+function unquoted(word: string): string {
+	return SURROUNDING_QUOTES.exec(word)?.[QUOTED_BODY] ?? word
+}
+
+function is_in_place_flag(word: string): boolean {
+	return IN_PLACE_LONG.test(word) || IN_PLACE_SHORT.test(word)
+}
+
+// The words after the in-place flags: BSD's `-i ''` carries its suffix as the next (empty) word.
+function without_suffix(words: ReadonlyArray<string>): Array<string> {
+	const index = words.findIndex((word) => IN_PLACE_CLUSTER.test(word))
+
+	if (index === -1 || words[index + 1] !== '') return [...words]
+
+	return words.toSpliced(index + 1, 1)
+}
+
+function sed_words(segment: string): Array<string> | undefined {
+	const words = git_argv.arguments_of(segment, SED)?.map((word) => unquoted(word))
+
+	return words?.some((word) => is_in_place_flag(word)) === true ? without_suffix(words) : undefined
+}
+
+function is_script_value(words: ReadonlyArray<string>, index: number): boolean {
+	return words[index - 1] === SCRIPT_FLAG
+}
+
+// The scripts (`-e <script>`, or the first operand without one) and the files of an in-place `sed`.
+function sed_call(words: ReadonlyArray<string>): SedCall {
+	const scripts = words.filter((_word, index) => is_script_value(words, index))
+	const operands = words.filter(
+		(word, index) => !word.startsWith(FLAG_PREFIX) && !is_script_value(words, index),
+	)
+
+	if (scripts.length > 0) return { scripts, files: operands }
+
+	const [script, ...files] = operands
+
+	return { scripts: script === undefined ? [] : [script], files }
+}
+
+// An `s` command split on its delimiter into the pattern, the replacement and the flags; `undefined`
+// for any other script.
+function substitute_parts(script: string): Array<string> | undefined {
+	if (!script.startsWith(SUBSTITUTE)) return undefined
+
+	const parts = script.slice(SUBSTITUTE.length + 1).split(script.charAt(SUBSTITUTE.length))
+
+	return parts.length === SUBSTITUTE_PARTS ? parts : undefined
+}
+
+// `file-edits.md` condition 2 reads both sides: no meta character in the pattern or the replacement,
+// and no flag that turns the plain-text match into something else.
+function has_plain_flags(parts: ReadonlyArray<string>): boolean {
+	return PLAIN_FLAGS.has(parts.at(-1) ?? '')
+}
+
+function is_plain(parts: ReadonlyArray<string>): boolean {
+	const [pattern = '', replacement = ''] = parts
+
+	return pattern !== '' && has_plain_flags(parts) && !META_CHARACTER.test(pattern + replacement)
+}
+
+function is_extended(words: ReadonlyArray<string>): boolean {
+	return words.some((word) => word === EXTENDED_LONG || EXTENDED_SHORT.test(word))
+}
+
+// The one script of a basic-regex in-place `sed`; `undefined` for several, none, or `-E`.
+function single_script(words: ReadonlyArray<string>): string | undefined {
+	if (is_extended(words)) return undefined
+
+	const { scripts } = sed_call(words)
+
+	return scripts.length === 1 ? scripts[0] : undefined
+}
+
+// The pattern of a single plain `s` command; `undefined` for anything else.
+function plain_pattern(words: ReadonlyArray<string>): string | undefined {
+	const script = single_script(words)
+	const parts = script === undefined ? undefined : substitute_parts(script)
+
+	return parts !== undefined && is_plain(parts) ? parts[0] : undefined
+}
+
+function match_count(text: string, pattern: string): number {
+	return text.split(pattern).length - 1
+}
+
+type ReadFile = (file_path: string) => string
+
+// The trigger: an in-place `sed` the conditions do not clear in any of its target files.
+function is_unsafe_segment(segment: string, read: ReadFile): boolean {
+	const words = sed_words(segment)
+
+	if (words === undefined) return false
+
+	const { files } = sed_call(words)
+	const pattern = plain_pattern(words)
+
+	if (pattern === undefined || files.length === 0) return true
+
+	return files.some((file) => match_count(read(file), pattern) !== ONE_MATCH)
+}
+
+function is_unsafe_sed(command: string, read: ReadFile = file_reader.read_file_or_empty): boolean {
+	return shell_segments.segments_of(command).some((segment) => is_unsafe_segment(segment, read))
+}
+
+// The occasion the rule governs: any in-place `sed`.
+function is_in_place_sed(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => sed_words(segment) !== undefined)
+}
+
+// Keeping the rule: an in-place `sed` whose script clears the static conditions. The per-file count
+// is not re-read here, so a transcript is measured without the file as it stood then.
+function keeps_plain_sed(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => {
+		const words = sed_words(segment)
+
+		return words !== undefined && plain_pattern(words) !== undefined
+	})
+}
+
+const SED_IN_PLACE_REASON =
+	'⛔ unsafe `sed -i`: its pattern or replacement carries a meta character (`/ & \\ . * [ ] ^ $`), ' +
+	'it is not one plain `s` command (a flag other than `g`, or `-E`), or it does not match exactly once in each target file, so it can rewrite a line you did ' +
+	'not mean to. Change the region with the Edit tool. This rule fires on every occurrence ' +
+	'(`prompts/collaboration-workflow/file-edits.md`).'
+
+const ROW = {
+	id: 'sed-in-place',
+	is_trigger: bash_triggers.on_bash_command((command: string) => is_unsafe_sed(command)),
+	reason: SED_IN_PLACE_REASON,
+	decide: (): boolean => true,
+	keeps: bash_triggers.on_bash_command(keeps_plain_sed),
+	reaches: bash_triggers.on_bash_command(is_in_place_sed),
+	about: {
+		title: 'No `sed -i` its countable conditions do not clear',
+		topic: '`file-edits.md`',
+		fires:
+			'a `sed -i` whose script is not one `s` command, whose pattern or replacement has a meta character, or which does not match exactly once in a target file. Every occurrence',
+		quiet: 'not in place, or one plain `s` command matching once in each file',
+	},
+}
+
+const sed_in_place = {
+	ROW,
+	is_in_place_sed,
+	is_unsafe_sed,
+	keeps_plain_sed,
+}
+
+export { sed_in_place }

package/scripts/rules/shell-segments.ts

@@ -16,11 +16,51 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 const SEGMENT_SEPARATOR = /&&|\|\||;|\n/u
 const SEGMENT_PARTS = new RegExp(`(${SEGMENT_SEPARATOR.source})`, 'u')
 
+// **The rows that read a segment as argv cut at the pipe and the background `&` as well.** Their
+// question is which program a segment launches, and `true | git push -f` or `x & git push -f`
+// launches git all the same; a `--jq` fragment cut off by a `|` begins with no program word, so it
+// launches nothing they look for. A `&` that belongs to a redirection (`2>&1`, `&>file`, `<&3`) does
+// not cut, nor does the `|` of the clobber redirect `>|`.
+const COMMAND_SEPARATOR = /&&|\|\||;|\n|(?<!>)\|&?|(?<![<>])&(?!>)/u
+
 /** The line's commands, trimmed. Empty segments are kept: a caller anchoring at `^` rejects them. */
 function segments_of(command: string): Array<string> {
 	return command.split(SEGMENT_SEPARATOR).map((segment) => segment.trim())
 }
 
+/** The line's commands as separate programs: the `segments_of` cut plus a pipe and a background `&`. */
+function commands_of(command: string): Array<string> {
+	return command.split(COMMAND_SEPARATOR).map((segment) => segment.trim())
+}
+
+const COMMAND_SEPARATORS = new RegExp(COMMAND_SEPARATOR.source, 'gu')
+
+/**
+ * The `commands_of` cut taken where the quote-blanked line puts each separator, so a `|` or `;`
+ * inside a quoted argument does not cut it; a heredoc line falls back to `commands_of`.
+ */
+function quote_aware_commands_of(command: string): Array<string> {
+	const plain = time_shell.blanked(command)
+
+	if (plain === undefined) return commands_of(command)
+
+	const cuts = [...plain.matchAll(COMMAND_SEPARATORS)].map((match) => ({
+		begin: match.index,
+		end: match.index + match[0].length,
+	}))
+	const starts = [0, ...cuts.map((cut) => cut.end)]
+	const stops = cuts.map((cut) => cut.begin)
+
+	return starts.map((start, index) => command.slice(start, stops[index] ?? command.length).trim())
+}
+
+const LINE_CONTINUATION = /\\\n/gu
+
+/** The line with each backslash-newline joined, so a continued call stays one command at a `\n` cut. */
+function joined_continuations(command: string): string {
+	return command.replaceAll(LINE_CONTINUATION, ' ')
+}
+
 /** The same cut, untrimmed and with each separator kept between its commands, so the parts join back to the line. */
 function parts_of(command: string): Array<string> {
 	return command.split(SEGMENT_PARTS)
@@ -55,9 +95,12 @@ function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
 }
 
 const shell_segments = {
+	commands_of,
 	first_of,
 	is_josh_command,
+	joined_continuations,
 	parts_of,
+	quote_aware_commands_of,
 	segments_of,
 }
 

package/scripts/rules/stop-rule-rows.ts

@@ -0,0 +1,52 @@
+import type { DeliveredRule } from './delivered-rules'
+
+// The `Stop` hook's rows; `stop:guard` judges every stop. A row with a fixed answer runs it itself and
+// blocks only when that fails; a row that needs judgement blocks the stop while it holds. They have no
+// guard row, so the listing reads their description from here.
+
+type StopRule = Pick<DeliveredRule, 'about' | 'id'>
+
+const STOP_GUARD = 'pnpm josh stop:guard'
+
+const ROWS: ReadonlyArray<StopRule> = [
+	{
+		id: 'stop-notify',
+		about: {
+			title: 'Stop notification',
+			topic: '`rule-delivery.md` → "stop-notify"',
+			entry: STOP_GUARD,
+			fires:
+				'a stop with the work tree held and no `confirmation` notify that turn. Sends the notify itself; blocks only when the send fails',
+			quiet: 'no hold, a `confirmation` notify on the tail, or a pre-gate cut taken',
+		},
+	},
+	{
+		id: 'hold-release',
+		about: {
+			title: 'Hold release',
+			topic: '`.claude/skills/workflow-commands/working-tree-hold.md`',
+			entry: STOP_GUARD,
+			fires:
+				'a stop on a clean tree with the `run:hold` record still in place. Releases the hold itself; blocks only when that fails',
+			quiet:
+				'a dirty tree (a `halfrun` stop before the commit, a `needs-human-review` stop) or already released',
+		},
+	},
+	{
+		id: 'filing-offer',
+		about: {
+			title: 'Offer to file',
+			topic: '`.claude/skills/workflow-commands/observation-filing.md`',
+			entry: STOP_GUARD,
+			fires:
+				'an unattended run (a kit-launched headless session, a lane child, a `backlogrun` parent) whose last reply offers to file without filing. Blocks the stop',
+			quiet:
+				'an interactive session, already filed, inside a fence or quote, a named third-party `owner/repo`, or an unknown owner',
+		},
+	},
+]
+
+const stop_rule_rows = { ROWS }
+
+export type { StopRule }
+export { stop_rule_rows }