@joshuafolkken/kit 1.1784.0 → 1.2114.0

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'
@@ -70,8 +74,10 @@ function gather_runs(cwd: string = process.cwd()): Generator<Array<string>> {
 	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(
@@ -80,6 +86,7 @@ function* counted(
 ): 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
 	}
 }
@@ -108,26 +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.
 // The runs are counted as `measure` consumes them, since a lazy source cannot be asked its length
 // up front.
-function render(runs: Iterable<ReadonlyArray<string>>): string {
-	const tally: Tally = { runs: 0 }
+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 NO_TARGETS
+	if (tally.runs === 0) return { table: NO_TARGETS }
 
-	return readings.map((reading) => row(reading)).join('\n')
+	const judged = rule_value_candidates.judge(readings, tally.runs)
+	const shapes = piped_verification_shapes.render(tally.shapes)
+
+	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
 }
@@ -139,9 +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

@@ -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

@@ -20,8 +20,8 @@ const SEGMENT_PARTS = new RegExp(`(${SEGMENT_SEPARATOR.source})`, 'u')
 // 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.
-const COMMAND_SEPARATOR = /&&|\|\||;|\n|\|&?|(?<![<>])&(?!>)/u
+// 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> {
@@ -54,6 +54,13 @@ function quote_aware_commands_of(command: string): Array<string> {
 	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)
@@ -91,6 +98,7 @@ 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

@@ -13,7 +13,7 @@ const ROWS: ReadonlyArray<StopRule> = [
 		id: 'stop-notify',
 		about: {
 			title: 'Stop notification',
-			topic: '`CLAUDE.md` → "Mid-workflow 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',
@@ -32,18 +32,6 @@ const ROWS: ReadonlyArray<StopRule> = [
 				'a dirty tree (a `halfrun` stop before the commit, a `needs-human-review` stop) or already released',
 		},
 	},
-	{
-		id: 'issue-citation',
-		about: {
-			title: 'Issue citation format',
-			topic: '`prompts/collaboration-workflow/issue-citation.md`',
-			entry: STOP_GUARD,
-			fires:
-				'a bare `#N` in the prose of the last reply. Prints the citation lines itself; blocks only when a number cannot be cited',
-			quiet:
-				'link form, inside code or a quote, `#N` right after `PR`, or a GitHub-facing artifact',
-		},
-	},
 	{
 		id: 'filing-offer',
 		about: {

package/scripts/rules/stop-rules.ts

@@ -1,8 +1,8 @@
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
+import { concise_reply } from './concise-reply'
 import { filing_offer } from './filing-offer'
-import { issue_citation } from './issue-citation'
 import { lane_background } from './lane-background'
 import { reply_language } from './reply-language'
 import { stop_decision, type StopDecision } from './stop-decision'
@@ -22,7 +22,7 @@ import { stop_decision, type StopDecision } from './stop-decision'
 // `pretool-guard` is one — not a second copy of the plumbing.
 //
 // **A rule whose answer is fixed acts; only a rule that needs judgement refuses** (joshuafolkken/kit#3919).
-// The stop notification, the hold release and the citation lines are each one mechanical operation the
+// The stop notification and the hold release are each one mechanical operation the
 // hook can run itself, so they come back as `actions` and the stop goes through: a refusal is a whole
 // model turn spent re-reading the context to run a command the hook already knew. `stop-actions.ts`
 // runs them, and only an action that fails falls back to its refusal. The rest — the reply's language,
@@ -34,7 +34,7 @@ const SWITCH_ENV_KEY = 'JOSH_STOP_GUARD'
 const BLOCK_DECISION = 'block'
 
 // Only the fields the stop rules read. `last_assistant_message` is the turn's session-facing text —
-// Claude Code hands it directly so the transcript's async lag is never in the citation path.
+// Claude Code hands it directly so the transcript's async lag is never in the rules' path.
 const stop_payload_schema = z.object({
 	transcript_path: z.string().min(1),
 	stop_hook_active: z.boolean().nullish(),
@@ -64,8 +64,8 @@ interface StopContext {
 	notified: boolean
 	// The turn's session-facing reply text.
 	message: string
-	// The person's last prompt — a `#N` it already carried is quoted, not cited.
-	prompt: string
+	// The person's last prompt on the tail — `undefined` when none is on it (`last_prompt.person_prompt`).
+	prompt: string | undefined
 	// This stop already forced a continuation earlier in the prompt — the loop-breaker Claude Code
 	// documents, so a run that will not comply is not blocked forever.
 	stop_hook_active: boolean
@@ -74,7 +74,7 @@ interface StopContext {
 	// the cut holding the tree by design and hands off to a fresh process (`pre-gate-cut.md`), so that
 	// turn-end is an automatic continuation, not the person-waiting pause the block rules are for.
 	cut_pending: boolean
-	// An Issue filing no guard refused is on this run's transcript tail — `filing_cap`'s count.
+	// An Issue filing no guard refused is on this run's transcript tail — `turn_filings`' count.
 	filed: boolean
 	// The owner of the repository the session runs in, or `undefined` when it cannot be read.
 	session_owner: string | undefined
@@ -91,6 +91,9 @@ interface StopContext {
 	// A backgrounded subagent this run launched has not finished — `lane_background.pending_agent_ids`.
 	// Apart from `background_pending`, since only a subagent is sure to end.
 	agent_pending: boolean
+	// A backgrounded command this run launched has not finished — `lane_background.pending_command_ids`.
+	// Apart from `agent_pending`, since the two are waited on differently.
+	command_pending: boolean
 	// This lane child handed its region to a running detached ship — `lane_handoff.is_handed_off`.
 	// The supervisor notifies on its own outcome, so nobody waits on this stop.
 	handed_off: boolean
@@ -108,7 +111,6 @@ interface StopContext {
 type StopAction =
 	| { kind: 'notify'; issue: string; message: string; decision: StopDecision }
 	| { kind: 'release'; issue: string }
-	| { kind: 'cite'; references: ReadonlyArray<string> }
 
 // `reason` refuses the stop; otherwise `actions` run, and `blocks_on_failure` says whether a failed one
 // falls back to its refusal — never past the loop-breaker.
@@ -128,8 +130,8 @@ const STOP_NOTIFY_REASON =
 	'⛔ mid-workflow stop notification: this working tree is still held by a run and no `confirmation` ' +
 	'Telegram was sent this turn. Send ' +
 	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\' ' +
-	'--recommended "<choice>" --alternative "<choice>"` (`CLAUDE.md` → "Mid-workflow stop ' +
-	'notification"), then confirm in one line that it was sent — do not repeat your previous reply.'
+	'--recommended "<choice>" --alternative "<choice>"` (`rule-delivery.md` → "stop-notify"), ' +
+	'then confirm in one line that it was sent — do not repeat your previous reply.'
 
 // **A clean tree that still holds is a tree the next run will trample.** `working-tree-hold.md`: a stop that
 // leaves the tree clean releases the hold; a `halfrun` pre-commit stop and a `needs-human-review` stop
@@ -141,28 +143,6 @@ const HOLD_RELEASE_REASON =
 	'`working-tree-hold.md`), then confirm in one line that it was released — do not repeat your ' +
 	'previous reply.'
 
-// **The fallback when the hook could not print the citation lines itself**. The bare `#N` is already
-// on screen and the hook cannot unsay it, so the reason does the one thing that helps the *next* reply:
-// it names the numbers it detected and hands over the exact `issue:cite` call that prints the
-// paste-ready lines, then asks for the corrected citation lines alone — not the whole reply reissued.
-// Reprinting the whole reply is what made the correction read as a duplicate;
-// the bare copy already scrolled past stays, and the fix follows it as a short correction. The rule
-// itself is not restated — it is resident in `CLAUDE.md` — only pointed at.
-const ISSUE_CITATION_REASON =
-	'Session-facing output cites an Issue as a number-link so the reader can click through and see ' +
-	'which repository it is (`CLAUDE.md`, `prompts/collaboration-workflow/issue-citation.md`).'
-
-function build_citation_reason(references: ReadonlyArray<string>): string {
-	const numbers = references.join(', ')
-	const command = `pnpm josh issue:cite ${issue_citation.cite_arguments(references).join(' ')}`
-
-	return (
-		`⛔ issue citation: your reply names an Issue as a bare \`#N\` (${numbers}). Run \`${command}\` ` +
-		`to print the paste-ready citation lines, then print the corrected citation lines alone — do not ` +
-		`repeat your previous reply. ${ISSUE_CITATION_REASON}`
-	)
-}
-
 // **An offer to file in an unattended run is a Tier A filing deferred to nobody**.
 // The judgement is already made, so the reason hands over the filing chain rather than a question; the
 // rule itself is resident in `observation-filing.md` and only pointed at. **An interactive session asks
@@ -249,6 +229,13 @@ function language_reason(context: StopContext): string | undefined {
 	return build_language_reason(context.session_lang)
 }
 
+// **A reply's narrative over the limit is sent back once to be shortened** — `concise-reply.ts`.
+function concise_reason(context: StopContext): string | undefined {
+	if (!concise_reply.is_over(context.message, context.prompt)) return undefined
+
+	return concise_reply.build_reason(context.message)
+}
+
 // The sessions no person answers: one kit launched under `claude -p` (a lane child, a woken session), a
 // dispatched lane child, or the `backlogrun` parent the user handed the backlog to.
 function is_unattended(context: StopContext): boolean {
@@ -295,24 +282,16 @@ function needs_release(context: StopContext): boolean {
 	return is_held_idle(context) && context.tree_clean && !context.prrun_stopped
 }
 
-// The bare references the citation lines are printed for. **A headless agent's reply has no reader**:
-// its text lands in a stream-json log, so correcting its citations or its language costs a turn and
-// reaches nobody. The artifacts a person does read — a Telegram, an Issue, a pull request — are held
-// to the same rules by their own guards, not here.
-function bare_references(context: StopContext): ReadonlyArray<string> {
-	if (context.headless_agent) return []
-
-	return issue_citation.unquoted_references(context.message, context.prompt)
-}
-
-// The two rules that read the reply and need the model, the filing offer first. A drifted reply
+// The rules that read the reply and need the model: the filing offer, then the language, then the
+// length. **A headless agent's reply has no reader**: its text lands in a stream-json log, so
+// correcting its language costs a turn and reaches nobody. A drifted reply
 // refused for another reason is not rewritten, but the drift still ends: `block_envelope` appends the
 // session-language note to every refusal, so the turn it continues is written in the session language.
 function reply_reason(context: StopContext): string | undefined {
 	if (needs_filing(context)) return FILING_OFFER_REASON
 	if (context.headless_agent) return undefined
 
-	return language_reason(context)
+	return language_reason(context) ?? concise_reason(context)
 }
 
 // Sent back once; past the loop-breaker the run has said nothing is awaited, and nothing is sent.
@@ -342,11 +321,19 @@ function needs_background_wait(context: StopContext): boolean {
 	return context.lane_child && context.background_pending
 }
 
+// **Only subagents left take their own wait**: their notice comes in when a tool call ends, while a
+// command is waited on through the detached ship.
+function background_wait_reason(context: StopContext): string {
+	if (context.command_pending) return lane_background.LANE_BACKGROUND_STOP_REASON
+
+	return lane_background.LANE_AGENT_STOP_REASON
+}
+
 // The two lane rules that mean the run is not pausing at all — ahead of every action, since the notify
 // would announce a pause the run has no reason to take.
 function lane_reason(context: StopContext): string | undefined {
 	if (needs_index_route(context)) return LANE_INDEX_REASON
-	if (needs_background_wait(context)) return lane_background.LANE_BACKGROUND_STOP_REASON
+	if (needs_background_wait(context)) return background_wait_reason(context)
 
 	return undefined
 }
@@ -382,14 +369,6 @@ function hold_actions(context: StopContext): Array<StopAction> {
 	return needs_release(context) ? [...notify, { kind: 'release', issue }] : notify
 }
 
-// The actions in the order they run: the notify ahead of the release that ends the hold it reports.
-function stop_actions(context: StopContext): ReadonlyArray<StopAction> {
-	const references = bare_references(context)
-	const cite: Array<StopAction> = references.length > 0 ? [{ kind: 'cite', references }] : []
-
-	return [...hold_actions(context), ...cite]
-}
-
 // First-wins across the refusals. `stop_hook_active` is the loop-breaker, so a run that already got one
 // continuation this prompt may stop; the lane rules go first, then the filing offer, then the language.
 //
@@ -418,7 +397,7 @@ function stop_outcome(context: StopContext): StopOutcome {
 	const reason = block_reason(context)
 	if (!runs_actions(context, reason)) return { ...NO_OUTCOME, reason }
 
-	const actions = stop_actions(context)
+	const actions = hold_actions(context)
 	if (actions.length === 0) return NO_OUTCOME
 
 	return { reason, actions, blocks_on_failure: !context.stop_hook_active }
@@ -426,10 +405,7 @@ function stop_outcome(context: StopContext): StopOutcome {
 
 // The refusal an action falls back to when the hook could not run it.
 function fallback_reason(action: StopAction): string {
-	if (action.kind === 'notify') return STOP_NOTIFY_REASON
-	if (action.kind === 'release') return HOLD_RELEASE_REASON
-
-	return build_citation_reason(action.references)
+	return action.kind === 'notify' ? STOP_NOTIFY_REASON : HOLD_RELEASE_REASON
 }
 
 // The documented shape a `Stop` hook blocks with: `reason` is fed back to Claude, which then continues
@@ -460,7 +436,6 @@ const stop_rules = {
 	HEADLESS_REFUSAL_CAP,
 	HEADLESS_WAIT_REASON,
 	HOLD_RELEASE_REASON,
-	ISSUE_CITATION_REASON,
 	LANE_INDEX_REASON,
 	NO_OUTCOME,
 	STOP_NOTIFY_REASON,

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

@@ -44,7 +44,7 @@ const ROW = {
 	reason: REASON,
 	about: {
 		title: 'Test declaration',
-		topic: '`CLAUDE.md` → Code Change Rules',
+		topic: '`testing-guide.md` → "0. Per-Requirement Test Coverage (MANDATORY)"',
 		fires: '`pnpm josh git -y` (`josh g`) while `pnpm josh test:declared` answers `required`',
 		quiet: '`exempt` (non-runtime only) or `satisfied` (tests included)',
 	},