@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -26,46 +26,62 @@ 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 texts = runs.get(owned.owner) ?? []
+		const owner = cost_transcript.owning_session_id(file)
+		const owned = runs.get(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())
+}
+
+interface Tally {
+	runs: number
+}
+
+function* counted(
+	runs: Iterable<ReadonlyArray<string>>,
+	tally: Tally,
+): Generator<ReadonlyArray<string>> {
+	for (const texts of runs) {
+		tally.runs += 1
+		yield texts
+	}
 }
 
 // The id column, wide enough for the longest rule id, so the reading lines up whatever the registry
@@ -94,13 +110,15 @@ function row(reading: RuleReading): 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(runs: Iterable<ReadonlyArray<string>>): string {
+	const tally: Tally = { runs: 0 }
+	const readings = rule_value.measure(counted(runs, tally))
+
+	if (tally.runs === 0) return NO_TARGETS
 
-	return rule_value
-		.measure(runs)
-		.map((reading) => row(reading))
-		.join('\n')
+	return readings.map((reading) => row(reading)).join('\n')
 }
 
 // `--refresh` is the detached measurement the `backlogrun` loop head starts: the reading goes to the
@@ -123,6 +141,7 @@ const rule_value_cli = {
 	render,
 	row,
 	run_rule_value,
+	runs_of,
 	NO_TARGETS,
 	UNMEASURED,
 	UNREACHED,

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.
 //
@@ -39,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
@@ -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

@@ -16,16 +16,63 @@ 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.
+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())
+}
+
 /** 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)
 }
 
+/**
+ * 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,8 +88,11 @@ function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
 }
 
 const shell_segments = {
+	commands_of,
+	first_of,
 	is_josh_command,
 	parts_of,
+	quote_aware_commands_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 }

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

@@ -0,0 +1,64 @@
+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: '`CLAUDE.md` → "Mid-workflow stop notification"',
+			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: '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: {
+			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 }