@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/rules/issue-comments.ts

@@ -1,3 +1,7 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
 import { bash_triggers } from './bash-triggers'
 import { gh_api } from './gh-api'
 import { prior_comment_read } from './prior-comment-read'
@@ -77,6 +81,9 @@ function reads_issue_comments(command: string): boolean {
 	return shell_segments.segments_of(command).some((segment) => fetches_issue_comments(segment))
 }
 
+const RULE_DOC = '`.claude/skills/workflow-commands/issue-comments.md`'
+const COMMENTS_FALLBACK = 'gh api repos/{owner}/{repo}/issues/<N>/comments'
+
 // **The refusal hands over the command that fixes it**, because reading is not the same as
 // obeying: a sentence saying "also read the comments" is prose that moves nothing, while a refused
 // body read leaves the run holding the reissue that makes the comments *present*. The conflict rule
@@ -88,12 +95,62 @@ function reads_issue_comments(command: string): boolean {
 // being the Issue the refused call named — so a run that reads only the opening still leaves holding
 // the fix. The label keeps `time_transcript_line.guard_from_refusal` naming this guard, not the command.
 const ISSUE_COMMENTS_REASON =
-	'⛔ issue comments: pnpm josh issue:read <N>\n' +
-	"Run that in place of this read — an Issue's comments are part of it, and a later comment " +
-	'supersedes the body it contradicts; refused until that command is on the transcript. Without ' +
-	'josh, read ' +
-	'`gh api repos/{owner}/{repo}/issues/<N>/comments` beside the body ' +
-	'(`.claude/skills/workflow-commands/issue-comments.md`).'
+	`⛔ issue comments: pnpm josh issue:read <N>\n` +
+	`Run that in place of this read — an Issue's comments are part of it, and a later comment ` +
+	`supersedes the body it contradicts; refused until that command is on the transcript. Without ` +
+	`josh, read \`${COMMENTS_FALLBACK}\` beside the body (${RULE_DOC}).`
+
+// **A `gh api` body read is rewritten rather than refused** (joshuafolkken/kit#3920): the fix is the
+// same Issue's comments endpoint, read on the same line, and the path the call already names is all
+// it needs. Prepended on lines of their own, so a trailing comment or a `&&` chain on the typed line
+// cannot swallow or skip them, and the typed line stays last — its exit status is still the call's.
+// A `gh issue view` read is left to the refusal — its global flags (`--repo`) and its `--json`
+// projection have no one comments spelling to add.
+const COMMENTS_JQ = String.raw`'.[] | "— \(.user.login) \(.created_at)\n\(.body)\n"'`
+
+const COMMENTS_NOTE =
+	"↻ issue comments: this read returned only the Issue's body, so the Issue's comments were fetched " +
+	`on the same line — a later comment supersedes the body it contradicts (${RULE_DOC}).`
+
+// **Only a line that opens with the body read is rewritten.** Prepended ahead of a `cd` or a
+// subshell, the comments read would resolve `{owner}/{repo}` in another directory and print another
+// repository's comments; and the line is cut on its quote-blanked reading, so a body-read spelling
+// quoted in a string or a heredoc body is never prepended as a real call. Every other line keeps the
+// refusal.
+function rewritable_path(command: string): string | undefined {
+	const read = shell_segments.first_of(command)
+
+	if (read === undefined || ISSUE_VIEW_COMMAND.test(read)) return undefined
+
+	return is_body_read_segment(read) ? ISSUE_BODY_PATH.exec(read)?.[0] : undefined
+}
+
+function comments_command(command: string): string | undefined {
+	if (!is_body_only_issue_read(command)) return undefined
+
+	const path = rewritable_path(command)
+
+	if (path === undefined) return undefined
+
+	return `gh api --paginate ${path}/comments --jq ${COMMENTS_JQ}\n${command}`
+}
+
+// The call's input with the comments read prepended, or `undefined` where the comments are already on
+// the tail or the read has no rewritable spelling.
+function comments_input(
+	call: GuardedCall,
+	tail: () => string,
+): Record<string, unknown> | undefined {
+	if (call.name !== cost_blocks.BASH_TOOL || !json_value.is_record(call.input)) return undefined
+
+	const command = comments_command(time_shell.bash_command(call.input))
+
+	if (command === undefined || prior_comment_read.already_read_for_call(tail(), call)) {
+		return undefined
+	}
+
+	return { ...call.input, command }
+}
 
 // The enumeration row itself, so `delivered-rules.ts` spreads one entry. `already_satisfied` stands it
 // down once the comments are on the transcript tail, and until then it refuses every body-only read.
@@ -103,13 +160,17 @@ const ROW = {
 	reason: ISSUE_COMMENTS_REASON,
 	already_satisfied: prior_comment_read.already_read_for_call,
 	keeps: bash_triggers.on_bash_command(reads_issue_comments),
+	rewrite: comments_input,
+	rewrite_note: COMMENTS_NOTE,
 	// The opening the reason carried before it led with the command.
 	former_reasons: ["⛔ an Issue's comments are part of the Issue: read them before implementing"],
 }
 
 const issue_comments = {
+	COMMENTS_NOTE,
 	ISSUE_COMMENTS_REASON,
 	ROW,
+	comments_input,
 	is_body_only_issue_read,
 }
 

package/scripts/rules/last-prompt.ts

@@ -30,10 +30,13 @@ const KEYWORD_BEFORE_ARGUMENT = -2
 
 const PROMPT_LINE_SCHEMA = z.object({
 	isMeta: z.boolean().nullish(),
+	timestamp: z.string().nullish(),
 	origin: z.object({ kind: z.string().nullish() }).nullish(),
 	message: z.object({ content: z.unknown() }),
 })
 
+const TIMED_LINE_SCHEMA = z.object({ timestamp: z.string() })
+
 type PromptLine = z.infer<typeof PROMPT_LINE_SCHEMA>
 
 function is_person(line: PromptLine): boolean {
@@ -42,13 +45,20 @@ function is_person(line: PromptLine): boolean {
 	return line.origin === null || line.origin === undefined || line.origin.kind === HUMAN_ORIGIN
 }
 
-// The prompt line's text, or `undefined` when the harness wrote it or it does not read as one.
-function person_text(line: string): string | undefined {
+// The prompt line as the person wrote it, or `undefined` when the harness wrote it or it does not
+// read as one.
+function person_line(line: string): PromptLine | undefined {
 	const parsed = PROMPT_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
 
-	if (!parsed.success || !is_person(parsed.data)) return undefined
+	return parsed.success && is_person(parsed.data) ? parsed.data : undefined
+}
 
-	return time_reported_failure.result_text(parsed.data.message.content)
+// The prompt line's text, or `undefined` when the harness wrote it or it does not read as one.
+function person_text(line: string): string | undefined {
+	const person = person_line(line)
+	if (person === undefined) return undefined
+
+	return time_reported_failure.result_text(person.message.content)
 }
 
 // A keyword opening the prompt is what a person types; a keyword before its one trailing argument is a
@@ -75,6 +85,41 @@ function prompt_text(tail: string): string {
 	return text === undefined || is_invocation(text) ? NO_PROMPT : text
 }
 
-const last_prompt = { prompt_text }
+// **The prompt that opened this turn, when a person typed it** — '' when the harness opened it (a task
+// notification, a subagent's hand-back), so a question asked turns ago does not answer for a stop the
+// run reached on its own since (`stop-decision.ts` → `is_question`).
+function turn_prompt(tail: string): string {
+	const opener = tail.split('\n').findLast((line) => filing_cap.is_prompt_line(line))
+	if (opener === undefined) return NO_PROMPT
+
+	return person_text(opener) ?? NO_PROMPT
+}
+
+// When the person last prompted on the tail, or `undefined` when no prompt of theirs is on it.
+function prompt_time(tail: string): string | undefined {
+	return tail
+		.split('\n')
+		.filter((line) => filing_cap.is_prompt_line(line))
+		.map((line) => person_line(line)?.timestamp ?? undefined)
+		.findLast((time) => time !== undefined)
+}
+
+// The first dated line on the tail, or `undefined` when none is.
+function tail_time(tail: string): string | undefined {
+	return tail
+		.split('\n')
+		.map((line) => TIMED_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line)).data?.timestamp)
+		.find((time) => time !== undefined)
+}
+
+// **When the current pause began, as far as the tail shows** — what a recorded notify is compared
+// against. A person's prompt ends the pause it reported, so the last one opens the next; with none on
+// the tail, only a send dated inside the tail is provably after every prompt, and an older send is
+// announced again (joshuafolkken/kit#3961).
+function pause_start(tail: string): string | undefined {
+	return prompt_time(tail) ?? tail_time(tail)
+}
+
+const last_prompt = { pause_start, prompt_text, turn_prompt }
 
 export { last_prompt }

package/scripts/rules/oracle-list-cli.ts

@@ -12,6 +12,10 @@ import { oracle_firing } from './oracle-firing'
 const ARGV_OFFSET = 2
 const INDENT = '  '
 const FIELD_WIDTH = 10
+// The rule-prose guard sends a rule author here first, so the list closes on the placement order a new
+// rule is weighed against before it becomes a guard or a document line.
+const AUTOMATION_ORDER =
+	'automate first: a command > a hook that runs it > a refusal guard > a document — a lower rung states why the higher cannot hold (`principles.md` → "automate-first"; a guard\'s `why` is `scripts/rules/guard-remedy.ts`)'
 
 function pad_field(label: string): string {
 	return label.padEnd(FIELD_WIDTH)
@@ -51,6 +55,8 @@ function print_list(): void {
 	for (const oracle of decision_oracle.DECISION_ORACLES) {
 		console.info(format_oracle(oracle))
 	}
+
+	console.info(AUTOMATION_ORDER)
 }
 
 function run(argv: ReadonlyArray<string>): number {
@@ -70,6 +76,7 @@ function main(argv: ReadonlyArray<string>): void {
 }
 
 const oracle_list_cli = {
+	AUTOMATION_ORDER,
 	print_list,
 }
 

package/scripts/rules/piped-verification.ts

@@ -124,6 +124,8 @@ function keeps_verdict_intact(command: string): boolean {
 // **Only a filter that reads its input to the end qualifies.** One that exits early — `head`, or a
 // `grep` stopping at its first match — closes the pipe on a check still writing, and under `pipefail` the
 // check's SIGPIPE turns a passing run into exit 141; `head` also cuts the verdict line josh prints last.
+// `cut`, `sort`, `uniq` and `wc` read to the end as well, and a `grep … | cut -c1-250` narrowing was the
+// commonest masking still refused after #3875 (joshuafolkken/kit#3920).
 //
 // **Each masked check is wrapped on its own, and the rest of the line runs as typed.** Most of the
 // refusals left after #3570 were a check chained beside other work — `vitest …; pnpm josh lint:related
@@ -141,7 +143,7 @@ function keeps_verdict_intact(command: string): boolean {
 const PIPEFAIL_OPEN = '(set -o pipefail; '
 const PIPEFAIL_CLOSE = ')'
 const COMMENT_START = /(?:^|\s)#/u
-const FULL_READING_FILTER = /^(?:tail|grep)\b/u
+const FULL_READING_FILTER = /^(?:tail|grep|cut|sort|uniq|wc)\b/u
 const EARLY_EXIT_GREP =
 	/^grep\b.*\s(?:-[a-zA-Z]*[lLmq]|--(?:quiet|silent|max-count|files-with(?:out)?-match))/u
 

package/scripts/rules/rule-list.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { delivered_rules } from './delivered-rules'
+import { guard_remedy } from './guard-remedy'
 import { rule_registry, type RegisteredRule } from './rule-registry'
 
 // `josh rule:list` — the list of trigger-delivered rules, rendered from the guard rows themselves.
@@ -12,6 +13,7 @@ import { rule_registry, type RegisteredRule } from './rule-registry'
 const HEADER =
 	'# Trigger-delivered rules — rendered by `pnpm josh rule:list` from `scripts/rules/delivered-rules.ts`'
 const MISSING = '(no entry in `scripts/rules/rule-registry.ts`)'
+const MISSING_WHY = '(no `why` in `scripts/rules/guard-remedy.ts`)'
 
 function item(id: string, rule: RegisteredRule | undefined): string {
 	if (rule === undefined) return `- \`${id}\` ${MISSING}`
@@ -20,6 +22,7 @@ function item(id: string, rule: RegisteredRule | undefined): string {
 		`- **${rule.title}** (\`${id}\`, ${rule.topic})`,
 		`  - fires: \`${rule.entry}\` — ${rule.fires}`,
 		`  - silent: ${rule.quiet}`,
+		`  - not automated: ${guard_remedy.why_of(id) ?? MISSING_WHY}`,
 	].join('\n')
 }
 
@@ -46,6 +49,6 @@ function orphans(): ReadonlyArray<string> {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) process.stdout.write(`${render()}\n`)
 
-const rule_list = { MISSING, orphans, render }
+const rule_list = { MISSING, MISSING_WHY, orphans, render }
 
 export { rule_list }

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

@@ -157,6 +157,16 @@ const GUARD_ROWS: ReadonlyArray<RegisteredRule> = [
 			"a dispatched lane child's `AskUserQuestion`; it hands over the park procedure. Every occurrence",
 		quiet: 'not a lane child, or not an interactive tool',
 	},
+	{
+		id: 'agent-model',
+		title: 'Subagent model named',
+		topic:
+			'`.claude/skills/workflow-commands/delegation.md` → "A `general-purpose` subagent names its model"',
+		entry: RULE_GUARD,
+		fires:
+			'an `Agent` / `Task` call of the `general-purpose` type with no `model`. Every occurrence',
+		quiet: 'a named agent type, or a `model` set',
+	},
 	{
 		id: 'lane-carry-conflict',
 		title: 'Lane child carry commands',

package/scripts/rules/rule-registry.ts

@@ -45,14 +45,16 @@ const MEASURED_ROWS: ReadonlyArray<RegisteredRule> = [
 	},
 ]
 
-// The `Stop` hook's rows; `stop:guard` judges every stop, so each blocks the stop while it holds.
+// 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.
 const STOP_ROWS: ReadonlyArray<RegisteredRule> = [
 	{
 		id: 'stop-notify',
 		title: 'Stop notification',
 		topic: '`CLAUDE.md` → "Mid-workflow stop notification"',
 		entry: STOP_GUARD,
-		fires: 'a stop with the work tree held and no `confirmation` notify that turn. Blocks the stop',
+		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',
 	},
 	{
@@ -60,7 +62,8 @@ const STOP_ROWS: ReadonlyArray<RegisteredRule> = [
 		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. Blocks the stop',
+		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',
 	},
@@ -70,7 +73,7 @@ const STOP_ROWS: ReadonlyArray<RegisteredRule> = [
 		topic: '`prompts/collaboration-workflow/issue-citation.md`',
 		entry: STOP_GUARD,
 		fires:
-			'a bare `#N` in the prose of the last reply. Blocks the stop until the reply is reissued with the citation fixed',
+			'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',
 	},
 	{

package/scripts/rules/rule-rewrite.ts

@@ -0,0 +1,114 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { json_value } from '#scripts/lib/json-value'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
+import { delivered_rules, type DeliveredRule } from './delivered-rules'
+import { guard_remedy } from './guard-remedy'
+
+// The call a `PreToolUse` hook runs in place of a mechanically fixable refusal (joshuafolkken/kit#3920).
+// Each row `guard-remedy.ts` classes as a rewrite gets the call in turn, so one line that both pipes a
+// check and reads a body is made right by both rows. The rewrite is the rule guard's delivery, so the
+// rule guard's switch turns it off too.
+
+interface RuleRewrite {
+	// The payload carrying the rewritten input, which the guards judge in place of the typed one.
+	payload: string
+	input: Record<string, unknown>
+	// The notes of the rows that rewrote, in row order.
+	note: string
+}
+
+interface Folded {
+	input: Record<string, unknown>
+	notes: ReadonlyArray<string>
+}
+
+const REWRITING_RULES: ReadonlyArray<DeliveredRule> = delivered_rules.DELIVERED_RULES.filter(
+	(rule) => guard_remedy.is_rewrite(rule.id) && rule.rewrite !== undefined,
+)
+
+const NOTE_SEPARATOR = '\n\n'
+
+// **A tail that cannot be read is an empty one**, as every guard fails open (`hook-decision.ts`): a
+// throw here would end the hook before any guard judged the call.
+function read_payload_tail(raw_payload: string): string {
+	try {
+		const payload = hook_decision.parse_hook_payload(raw_payload)
+
+		return payload
+			? time_density_hook.read_tail(
+					time_hook_transcript.transcript_of(payload.transcript_path, payload.agent_id),
+				)
+			: ''
+	} catch {
+		return ''
+	}
+}
+
+function tail_reader(raw_payload: string): () => string {
+	const cache: { tail?: string } = {}
+
+	return function tail(): string {
+		cache.tail ??= read_payload_tail(raw_payload)
+
+		return cache.tail
+	}
+}
+
+function fold(name: string, typed: Record<string, unknown>, tail: () => string): Folded {
+	const folded: Folded = { input: typed, notes: [] }
+
+	for (const rule of REWRITING_RULES) {
+		const input = rule.rewrite?.({ name, input: folded.input }, tail)
+
+		if (input === undefined) {
+			continue
+		}
+
+		folded.input = input
+		folded.notes = [...folded.notes, rule.rewrite_note ?? '']
+	}
+
+	return folded
+}
+
+// The typed call, beside the whole payload its rewrite is spread back into.
+interface TypedPayload {
+	fields: Record<string, unknown>
+	name: string
+	input: Record<string, unknown>
+}
+
+function typed_payload(raw_payload: string): TypedPayload | undefined {
+	const fields = json_value.parse_or_undefined(raw_payload)
+
+	if (!json_value.is_record(fields)) return undefined
+
+	const input = fields['tool_input']
+
+	return json_value.is_record(input)
+		? { fields, name: String(fields['tool_name']), input }
+		: undefined
+}
+
+function rewrite(raw_payload: string): RuleRewrite | undefined {
+	const typed = delivered_rules.is_enabled() ? typed_payload(raw_payload) : undefined
+
+	if (typed === undefined) return undefined
+
+	const { input, notes } = fold(typed.name, typed.input, tail_reader(raw_payload))
+
+	if (notes.length === 0) return undefined
+
+	const note = notes.join(NOTE_SEPARATOR)
+
+	return { payload: JSON.stringify({ ...typed.fields, tool_input: input }), input, note }
+}
+
+const rule_rewrite = {
+	NOTE_SEPARATOR,
+	rewrite,
+}
+
+export type { RuleRewrite }
+export { rule_rewrite }

package/scripts/rules/rule-value.ts

@@ -5,6 +5,7 @@ import {
 } from '#scripts/time-runtime/time-transcript-line'
 import { delivered_rules, type MeasuredRule } from './delivered-rules'
 import { hook_context_line } from './hook-context-line'
+import { rule_rewrite } from './rule-rewrite'
 
 // What a rule is worth on the channel that carries it when its delivery has not fired.
 //
@@ -287,7 +288,7 @@ function rewritten_id(text: string): string | undefined {
 	return found?.id
 }
 
-function observe_rewrite(states: Map<string, RuleState>, text: string): void {
+function observe_note(states: Map<string, RuleState>, text: string): void {
 	const id = rewritten_id(text)
 	const state = id === undefined ? undefined : states.get(id)
 
@@ -297,6 +298,11 @@ function observe_rewrite(states: Map<string, RuleState>, text: string): void {
 	state.is_triggered = true
 }
 
+// One line can be rewritten by several rows, whose notes `rule-rewrite.ts` joins into one context.
+function observe_rewrite(states: Map<string, RuleState>, text: string): void {
+	for (const note of text.split(rule_rewrite.NOTE_SEPARATOR)) observe_note(states, note)
+}
+
 function observe_for_rule(
 	rule: MeasuredRule,
 	state: RuleState,

package/scripts/rules/shell-segments.ts

@@ -26,6 +26,20 @@ function parts_of(command: string): Array<string> {
 	return command.split(SEGMENT_PARTS)
 }
 
+/**
+ * The line's first command as the shell runs it — cut where the quote-blanked line puts the first
+ * separator, so one inside a quoted string does not cut it — or `undefined` for a heredoc line.
+ */
+function first_of(command: string): string | undefined {
+	const plain = time_shell.blanked(command)
+
+	if (plain === undefined) return undefined
+
+	const cut = plain.search(SEGMENT_SEPARATOR)
+
+	return (cut === -1 ? command : command.slice(0, cut)).trim()
+}
+
 // **Both spellings match, and the expansion is not this file's.** `josh_command_of` expands the alias
 // in the command it reads, so `pnpm josh ga` arrives as `josh gate` and a caller's canonical set
 // matches it as it is. Widening as well would be a second copy of one rule, and the caller that
@@ -41,6 +55,7 @@ function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
 }
 
 const shell_segments = {
+	first_of,
 	is_josh_command,
 	parts_of,
 	segments_of,

package/scripts/rules/stop-decision.ts

@@ -0,0 +1,77 @@
+// What a held stop is waiting on, read from records rather than guessed from prose
+// (joshuafolkken/kit#3961): the decision lines the reply states, and whether the person's own prompt
+// this turn was a question.
+//
+// **The recommended choice is the reply's, never a fixed placeholder.** A `confirmation` reaches a
+// person away from the session, and "read the reply" tells them nothing about what they are asked to
+// decide. The reply names it on a line of its own — `Recommended: <choice>`, with an optional
+// `Alternative: <choice>` — the same two fields `josh notify` takes, so the hook copies them rather
+// than inferring them.
+//
+// **A turn the person opened with a question is answered in the session they are at.** Its stop is
+// the answer, not a pause, so a Telegram saying "confirmation required" only buries the ones that are.
+
+interface StopDecision {
+	recommended: string
+	alternative: string | undefined
+}
+
+// A label may close its emphasis before or after the colon: `**Recommended:**`, `**Recommended**:`.
+const RECOMMENDED_LABEL = /^recommended[*_]*:/iu
+const ALTERNATIVE_LABEL = /^alternative[*_]*:/iu
+// The list bullet and the Markdown emphasis a decision line may be written with. Emphasis is
+// stripped only at the edges of the label and the choice: an underscore inside a choice belongs to
+// a `snake_case` name the person is asked to approve.
+const LEADING_EMPHASIS = /^[*_]+/u
+const TRAILING_EMPHASIS = /(?<![*_])[*_]+$/u
+const BULLET = /^[-*]\s+/u
+
+// A prompt that ends asking: a question mark, or a Japanese sentence-final question particle, before
+// any trailing full stop or space.
+const QUESTION_ENDING = /(?:[?？]|か|かな|かね)[\s。.]*$/u
+
+function unwrapped(text: string): string {
+	return text.trim().replace(LEADING_EMPHASIS, '').replace(TRAILING_EMPHASIS, '').trim()
+}
+
+function bare_line(line: string): string {
+	return unwrapped(line.trim().replace(BULLET, ''))
+}
+
+// The choice on the reply's first line labelled `label`, or `undefined` when none carries one.
+function choice_of(message: string, label: RegExp): string | undefined {
+	const line = message
+		.split('\n')
+		.map((one) => bare_line(one))
+		.find((one) => label.test(one))
+	const choice = line === undefined ? undefined : unwrapped(line.replace(label, ''))
+
+	return choice === '' ? undefined : choice
+}
+
+// The decision the reply asks for, or `undefined` when it names no recommended choice.
+function decision_of(message: string): StopDecision | undefined {
+	const recommended = choice_of(message, RECOMMENDED_LABEL)
+	if (recommended === undefined) return undefined
+
+	return { recommended, alternative: choice_of(message, ALTERNATIVE_LABEL) }
+}
+
+function is_question(prompt: string): boolean {
+	return QUESTION_ENDING.test(prompt.trim())
+}
+
+// **A held stop with no decision line is sent back once rather than announced.** Either it waits on a
+// person and has to say on what, or it waits on nobody and the notify would be the noise this rule
+// exists to end; only the run can tell which, so the reason hands it both answers.
+const DECISION_REASON =
+	'⛔ stop decision: this working tree is held by your run and your reply names no decision. If the ' +
+	'run waits on a person, end the reply with a `Recommended: <choice>` line and, where there is ' +
+	'one, an `Alternative: <choice>` line — the hook sends the `confirmation` Telegram from them. If ' +
+	'it waits on nobody, continue the run, or say in one line that nothing is awaited. Do not repeat ' +
+	'your previous reply.'
+
+const stop_decision = { DECISION_REASON, decision_of, is_question }
+
+export type { StopDecision }
+export { stop_decision }