@joshuafolkken/kit 1.872.0

package/scripts/rules/reply-language.ts

@@ -0,0 +1,116 @@
+// Whether a reply is written in the session language (joshuafolkken/kit#2470). The session-language
+// line reaches a turn only through `UserPromptSubmit`, so a turn opened by a background completion or a
+// Stop hook refusal answered in whatever language it was just shown, and kept answering in it.
+//
+// **The check is by script, derived from the configured language rather than a hard-coded pair.**
+// `Intl.Locale#maximize` names the script a language is written in (`ja` → `Jpan`, `en` → `Latn`,
+// `ru` → `Cyrl`), so any configured value is judged the same way and none is special-cased. Two
+// languages sharing one script (`en` and `fr`) are not told apart — the drift observed is a script
+// change, and a statistical detector would misread prose interleaved with English identifiers.
+//
+// **Latin is the fallback script of a line.** Identifiers are Latin in every language's prose, so a
+// Japanese line naming `Stop hook` is still Japanese; a line is Latin only when it carries no letter
+// of another script.
+
+const LATIN_SCRIPT = 'Latn'
+// The compound scripts `maximize` returns, spelled as the Unicode scripts a regex can name.
+const COMPOUND_SCRIPTS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	Jpan: ['Hira', 'Kana', 'Hani'],
+	Kore: ['Hang', 'Hani'],
+	Hans: ['Hani'],
+	Hant: ['Hani'],
+}
+
+// Below this many letters of prose the reply is a command, a path or a one-word acknowledgement, and
+// carries no language to judge.
+const MIN_PROSE_LETTERS = 20
+// The share of voting lines that must be in the session language. Lines, not letters: one kana or
+// kanji carries what several Latin letters do, so counting letters would shortchange a Japanese reply.
+const MATCH_SHARE_FLOOR = 0.5
+// Below this many letters a line is a heading or a label (`**Cause**`, `## Details`) and casts no vote,
+// unless no line of the reply is longer.
+const MIN_VOTING_LETTERS = 8
+
+const CODE_PATTERNS: ReadonlyArray<RegExp> = [
+	/```[\s\S]*?(?:```|$)/gu,
+	/`[^`\n]*`/gu,
+	/\]\([^)\s]*\)/gu,
+	/https?:\/\/\S+/gu,
+]
+// A run of printable ASCII; one holding a slash is a bare path the reply printed outside backticks.
+const ASCII_RUN_PATTERN = /[!-~]+/gu
+const LETTER_PATTERN = /\p{L}/gu
+// A letter of another script — `Common` and `Inherited` letters (`µ`) belong to no language of their own.
+const NON_LATIN_LETTER_PATTERN = /(?![\p{Script=Latn}\p{Script=Common}\p{Script=Inherited}])\p{L}/u
+
+function script_of(lang: string): string | undefined {
+	try {
+		return new Intl.Locale(lang).maximize().script
+	} catch {
+		return undefined
+	}
+}
+
+// The letters of the session script, or `undefined` for a script this runtime's regex cannot name.
+function letter_pattern(script: string): RegExp | undefined {
+	const scripts = COMPOUND_SCRIPTS[script] ?? [script]
+	const classes = scripts.map((name) => String.raw`\p{Script=${name}}`).join('')
+
+	try {
+		return new RegExp(`[${classes}]`, 'u')
+	} catch {
+		return undefined
+	}
+}
+
+function prose_of(message: string): string {
+	let text = message
+
+	for (const pattern of CODE_PATTERNS) text = text.replaceAll(pattern, ' ')
+
+	return text.replaceAll(ASCII_RUN_PATTERN, (run) => (run.includes('/') ? ' ' : run))
+}
+
+function letter_count(text: string): number {
+	return text.match(LETTER_PATTERN)?.length ?? 0
+}
+
+function is_line_in_script(line: string, script: string, pattern: RegExp): boolean {
+	if (script === LATIN_SCRIPT) return !NON_LATIN_LETTER_PATTERN.test(line)
+
+	return pattern.test(line)
+}
+
+function voting_lines(prose: string): Array<string> {
+	const lines = prose.split('\n').filter((line) => letter_count(line) > 0)
+	const voting = lines.filter((line) => letter_count(line) >= MIN_VOTING_LETTERS)
+
+	return voting.length > 0 ? voting : lines
+}
+
+function matches_share(prose: string, script: string, pattern: RegExp): number {
+	const lines = voting_lines(prose)
+	const matched = lines.filter((line) => is_line_in_script(line, script, pattern))
+
+	return matched.length / lines.length
+}
+
+// `true` only when the reply has prose enough to judge and most of it is in another script. Every
+// unanswerable case — an unknown language, a script with no regex, a code-only reply — reads as a match,
+// because a false refusal costs a turn and a missed one costs nothing new.
+function is_mismatch(message: string, lang: string): boolean {
+	const script = script_of(lang)
+	if (script === undefined) return false
+
+	const pattern = letter_pattern(script)
+	if (pattern === undefined) return false
+
+	const prose = prose_of(message)
+	if (letter_count(prose) < MIN_PROSE_LETTERS) return false
+
+	return matches_share(prose, script, pattern) < MATCH_SHARE_FLOOR
+}
+
+const reply_language = { MIN_PROSE_LETTERS, is_mismatch, script_of }
+
+export { reply_language }

package/scripts/rules/rule-body-guard.ts

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+import { tail_commands } from './tail-commands'
+
+// The trigger and the delivered text behind the `rule-body` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2272). It delivers the residency questions at the one moment they are skipped —
+// the edit that writes a rule into prose.
+//
+// **The gap it closes.** joshuafolkken/kit#2117 put question 0 (is the answer computable, so it is a
+// decision oracle) into the residency criterion and built `pnpm josh oracle:list`, but nothing made
+// that question fire: a new computable rule could still be written into prose and no test would fail,
+// so friction ran one way only — toward more prose. The criterion lived in `residency.md`, and
+// whether a run read it before writing a rule was left to judgement. This row is the firing.
+//
+// **The trigger is the append, not the edit.** A rule delivered on *every* edit to these files would
+// speak on typo fixes, link swaps and deletions — the wrong-turn firing `rule-delivery.md` calls worse
+// than no hook at all. So the trigger reads the edit's own text: a rule body is a net addition of
+// prose, which a deletion (net negative), a typo (net near zero) and a link swap (net zero once the
+// URL is stripped) all fail. What stays is the case the Issue names — writing rule prose into a rule
+// document.
+//
+// **No `decide`, so once per run.** The refusal changes what the run *knows* — that a new rule owes
+// question 0 and the ordering question — which is the shape `rule-delivery.md` says once-per-run is
+// right for: told once, the run applies it to every later rule it writes.
+//
+// **The stand-down is what turned the reminder into a check** (joshuafolkken/kit#2324). Until now the
+// row only *reminded* — it fired once and let the reissue through unconditionally, so "reissue and it
+// goes" meant a computable rule could still be written into prose with nothing having answered the two
+// questions. Now the pass condition is a *record*: the run has run `pnpm josh oracle:list` (question 0)
+// and `pnpm josh run:step` (the ordering question) earlier in the transcript. Both present, the edit is
+// stood down; either missing, it is refused. It passes on answering the questions, not on reading the
+// reminder. Keeping the rule is therefore running those two commands, which `keeps` names.
+
+// The two edit tools the `PreToolUse` matcher routes here. A `Write` carries the whole new file; an
+// `Edit` carries the region as `old_string` / `new_string`.
+const EDIT_TOOL = 'Edit'
+const WRITE_TOOL = 'Write'
+
+// The three rule-document families question 0 must be pushed at: the resident source, the
+// collaboration-workflow prompts, and the skill bodies. Anchored at a path separator or the string
+// start so a substring like `my-prompts/` cannot match. Split into three so no single pattern carries
+// the whole alternation.
+const CLAUDE_DOCUMENT = /(?:^|\/)CLAUDE\.md$/u
+const PROMPT_DOCUMENT = /(?:^|\/)prompts\/.+\.md$/u
+const SKILL_DOCUMENT = /(?:^|\/)\.claude\/skills\/.+\.md$/u
+
+function is_rule_document(file_path: string): boolean {
+	return (
+		CLAUDE_DOCUMENT.test(file_path) ||
+		PROMPT_DOCUMENT.test(file_path) ||
+		SKILL_DOCUMENT.test(file_path)
+	)
+}
+
+// A markdown link target (`](url)`) and a bare URL, blanked before the net-length measure so a link
+// swap — the change confined to a URL — reads as no prose added. The link target keeps its brackets so
+// only the URL is removed, and both spellings are stripped from old and new alike.
+const LINK_TARGET = /\]\([^)]*\)/gu
+const BARE_URL = /https?:\/\/\S+/gu
+
+function prose_of(text: string): string {
+	return text.replaceAll(LINK_TARGET, ']()').replaceAll(BARE_URL, '')
+}
+
+// A rule body is at least a sentence of guidance, and a trigger-plus-pointer line runs well past this.
+// Below it a change is a typo, a word tweak or a link swap, not a new rule — the threshold is what
+// keeps the firing on the wrong turn from being worse than no hook.
+const MIN_APPENDED_PROSE = 120
+
+function adds_rule_prose(old_text: string, new_text: string): boolean {
+	return prose_of(new_text).length - prose_of(old_text).length >= MIN_APPENDED_PROSE
+}
+
+function string_field(input: Record<string, unknown>, key: string): string {
+	const value = input[key]
+
+	return typeof value === 'string' ? value : ''
+}
+
+// The file's current text, read synchronously before the write lands so a `Write` has an `old` to
+// measure against. Injected so the suite controls it without touching the real filesystem, the way
+// `file-body.ts` injects its existence check. A new file reads as empty, so its whole body is added.
+function read_existing(file_path: string): string {
+	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+}
+
+function texts_of(
+	name: string,
+	input: Record<string, unknown>,
+	read: (file_path: string) => string,
+): { old_text: string; new_text: string } {
+	if (name === WRITE_TOOL) {
+		return {
+			old_text: read(string_field(input, 'file_path')),
+			new_text: string_field(input, 'content'),
+		}
+	}
+
+	return {
+		old_text: string_field(input, 'old_string'),
+		new_text: string_field(input, 'new_string'),
+	}
+}
+
+function is_edit_tool(name: string): boolean {
+	return name === EDIT_TOOL || name === WRITE_TOOL
+}
+
+// The call's input when it is an edit of a rule document, and `undefined` otherwise. The tool-name and
+// path tests run before the text read, so an ordinary edit pays nothing and a `Write`'s file read
+// happens only for a rule document.
+function rule_document_input(call: GuardedCall): Record<string, unknown> | undefined {
+	if (!is_edit_tool(call.name) || !json_value.is_record(call.input)) return undefined
+
+	return is_rule_document(string_field(call.input, 'file_path')) ? call.input : undefined
+}
+
+// The trigger: an `Edit` or `Write` that adds rule prose to a rule document.
+function writes_rule_prose(
+	call: GuardedCall,
+	read: (file_path: string) => string = read_existing,
+): boolean {
+	const input = rule_document_input(call)
+
+	if (input === undefined) return false
+
+	const { old_text, new_text } = texts_of(call.name, input, read)
+
+	return adds_rule_prose(old_text, new_text)
+}
+
+// The instruction in the shape a refusal can carry: what the edit is doing, the two questions it
+// skips, the commands that answer them, and the reissue every once-per-run delivery needs.
+const RULE_BODY_REASON =
+	'⛔ rule written into prose: this edit adds rule text to CLAUDE.md, a `prompts/**` doc or a skill ' +
+	'body. Before it lands, run the residency questions the addition skips. A rule whose answer is ' +
+	'computable from mechanically readable inputs should be a decision oracle, not prose — question 0; ' +
+	'`pnpm josh oracle:list` lists the existing oracles a new one joins (single source ' +
+	'`scripts/rules/decision-oracle.ts`). A rule that decides *when* or *in what order* to act belongs ' +
+	'in the run driver, not prose — the ordering question; `pnpm josh run:step` is the state machine a ' +
+	'sequencing rule moves into. Only a rule that is neither — not computable, not ordering — stays ' +
+	'prose, and then as a trigger-plus-pointer line rather than a second copy of its procedure. The ' +
+	'criterion is `prompts/collaboration-workflow/residency.md` (question 0 and the ordering question); ' +
+	'the delivery enumeration is `prompts/collaboration-workflow/rule-delivery.md`. This fires once per ' +
+	'run — once you have confirmed the rule can be neither an oracle nor an ordering step, reissue this ' +
+	'edit and it will go through.'
+
+// The two placement oracles the residency questions name: question 0 is `pnpm josh oracle:list`, the
+// ordering question is `pnpm josh run:step` (its degenerate pre-implementation form `run:next` counts
+// too). A run that answered both has run each earlier in the transcript.
+const PLACEMENT_ORACLES: ReadonlyArray<ReadonlySet<string>> = [
+	new Set(['oracle:list']),
+	new Set(['run:step', 'run:next']),
+]
+
+function ran_oracle(tail_commands_run: ReadonlyArray<string>, names: ReadonlySet<string>): boolean {
+	return tail_commands_run.some((command) =>
+		shell_segments
+			.segments_of(command)
+			.some((segment) => shell_segments.is_josh_command(segment, names)),
+	)
+}
+
+// The `already_satisfied` stand-down: the run has answered both placement questions, so this edit asks
+// for nothing new. Read off the transcript tail, the way the filing rows read their prior scout.
+function answered_placement(tail: string, _call: GuardedCall): boolean {
+	const commands = tail_commands.prior_bash_commands(tail)
+
+	return PLACEMENT_ORACLES.every((names) => ran_oracle(commands, names))
+}
+
+// Keeping the rule: a call that runs one of the two placement oracles. Segment-wise, so a spelling
+// quoted inside another command is not read as the consultation it is not.
+function runs_placement_oracle(command: string): boolean {
+	return PLACEMENT_ORACLES.some((names) =>
+		shell_segments
+			.segments_of(command)
+			.some((segment) => shell_segments.is_josh_command(segment, names)),
+	)
+}
+
+// The row itself, so `delivered-rules.ts` spreads one entry. Once per run with the placement-verdict
+// stand-down; `keeps` names running the placement oracles, the act the stand-down reads.
+const ROW = {
+	id: 'rule-body',
+	is_trigger: writes_rule_prose,
+	reason: RULE_BODY_REASON,
+	already_satisfied: answered_placement,
+	keeps: bash_triggers.on_bash_command(runs_placement_oracle),
+}
+
+const rule_body_guard = {
+	RULE_BODY_REASON,
+	ROW,
+	adds_rule_prose,
+	answered_placement,
+	is_rule_document,
+	prose_of,
+	runs_placement_oracle,
+	writes_rule_prose,
+}
+
+export { rule_body_guard }

package/scripts/rules/rule-guard.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { delivered_rules } from './delivered-rules'
+
+// The hook entry point for trigger-delivered rules (joshuafolkken/kit#1524).
+//
+// **It is the same shape `batch-guard.ts` and `investigation-guard.ts` already have**, and
+// deliberately so: read the payload on stdin, ask the rule, write the one envelope Claude Code
+// understands. What differs is only that this one asks an *enumeration* rather than a single rule —
+// so the next rule that leaves residency costs one row in `delivered-rules.ts` and no new process,
+// no new settings entry and no new test file.
+
+const rule_delivery = delivered_rules.delivery
+const { is_enabled, SWITCH_ENV_KEY } = delivered_rules
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('rule:guard')
+	else hook_decision.write_decision(await text(process.stdin), rule_delivery)
+}
+
+export { is_enabled, rule_delivery, SWITCH_ENV_KEY }

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

@@ -0,0 +1,129 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
+import { delivered_rules } from './delivered-rules'
+import { rule_value, type RuleReading } from './rule-value'
+
+// `josh rule:value` — what each delivered rule earns on the channel that carries it, one row per rule
+// (joshuafolkken/kit#2271). `rule_value.measure` was public but had no caller outside its own test, so
+// a rule that never fired stayed invisible until a person thought to measure it. This is that caller:
+// it groups every transcript by the run it belongs to — a lane's transcript counted with the parent
+// that dispatched it — measures them, and prints the reading.
+//
+// **It reports and never fails**, exactly as `josh bytes` and `josh lines` do. An environment holding
+// no measurable transcript prints `NO_TARGETS` and exits zero rather than erroring, so a fresh
+// checkout reads differently from a broken command.
+
+const PERCENT_SIGN = '%'
+const COLUMN_GAP = '  '
+const NO_TARGETS = 'no measurement targets'
+// A rule with no `keeps` predicate cannot be scored, so it reads as this rather than as 0% — "never
+// kept" is a claim the missing predicate cannot make (`rule-value.ts`).
+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>>()
+
+	for (const file of files) {
+		const owned = owned_text(file)
+
+		if (owned === undefined) continue
+
+		const texts = runs.get(owned.owner) ?? []
+
+		texts.push(owned.text)
+		runs.set(owned.owner, texts)
+	}
+
+	return runs
+}
+
+// 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>> {
+	const directories = cost_transcript.transcript_directories(cwd)
+	const files = cost_transcript.list_sessions_across(directories)
+
+	return [...group_by_run(files).values()]
+}
+
+// The id column, wide enough for the longest rule id, so the reading lines up whatever the registry
+// holds.
+const ID_WIDTH = Math.max(...delivered_rules.MEASURED_RULES.map((rule) => rule.id.length))
+
+function rate_text(reading: RuleReading): string {
+	if (!reading.is_measurable) return UNMEASURED
+
+	const rate = rule_value.unaided_rate(reading)
+
+	if (rate === undefined) return UNREACHED
+
+	return `${rate.toString()}${PERCENT_SIGN} unaided`
+}
+
+function row(reading: RuleReading): string {
+	const id = reading.id.padEnd(ID_WIDTH)
+	const reached = `reached ${reading.sessions.toString()}`
+	const refused = `refused ${reading.refusals.toString()}`
+
+	return [id, reached, rate_text(reading), refused].join(COLUMN_GAP)
+}
+
+// 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
+
+	return rule_value
+		.measure(runs)
+		.map((reading) => row(reading))
+		.join('\n')
+}
+
+// The loop-head call: `backlog:offer` writes this to stderr once per iteration, so a rule that never
+// fires appears as a printed row rather than as something a person has to go looking for.
+function emit(cwd: string = process.cwd()): void {
+	process.stderr.write(`${render(gather_runs(cwd))}\n`)
+}
+
+function run_rule_value(cwd: string = process.cwd()): number {
+	process.stdout.write(`${render(gather_runs(cwd))}\n`)
+
+	return 0
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = run_rule_value()
+}
+
+const rule_value_cli = {
+	emit,
+	gather_runs,
+	group_by_run,
+	render,
+	row,
+	run_rule_value,
+	NO_TARGETS,
+	UNMEASURED,
+	UNREACHED,
+}
+
+export { rule_value_cli }