@joshuafolkken/kit 1.872.0

package/scripts/rules/early-heartbeat.ts

@@ -0,0 +1,241 @@
+import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
+import { run_progress } from '#scripts/run/run-progress'
+import { run_progress_clock } from '#scripts/run/run-progress-clock'
+import { run_progress_config } from '#scripts/run/run-progress-config'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the decision behind the `early-heartbeat` row of `delivered-rules.ts`
+// (joshuafolkken/kit#1570).
+//
+// **The promise was kept and the interval was not.** `josh run:progress --mark` was called at every
+// real report exactly as `backlogrun.md` requires, and reports still arrived 3–5 minutes apart on a
+// 15-minute setting. The clock was never the problem: the parent armed a wait timer of its own on the
+// turn a timer fired **and** on the turn a delegated child's completion woke it, so two timers ran at
+// once and each produced a report the other knew nothing about. Nothing read the marked clock before
+// writing — `run:progress` refuses its own early lines, and there was no such refusal in front of the
+// parent's own prose.
+//
+// **So the refusal is put in front of the arm, not in front of the report.** A report is written in
+// prose and no hook can see it coming; the `Bash` call that sleeps is a call, and a call can be
+// refused — the same reading joshuafolkken/kit#1556 took for a verification behind a pipe.
+//
+// **An explicit ask is not a heartbeat, and it is exempt by construction rather than by exception.**
+// What is refused here is arming a *timer*; a person asking "how is it going" arrives as a turn with
+// no timer in front of it, and `pnpm josh run:progress --once` prints one line whatever the clock says
+// (`run-progress-cli.ts` → `once`). There is no rule to write for it, and so no rule to get wrong.
+
+const ARM_PREFIX = 'josh-heartbeat-arm-'
+
+// A shell line carries several commands, and each is judged on its own — the same separators
+// `delivered-rules.ts` cuts an Issue read on, plus the two spellings an arm actually reaches for:
+// `sleep 1200 || true`, and `sleep 1200 &` sent to the background. `&&` is listed before `&` so the pair is
+// never cut in half. A bare `|` is deliberately absent: a sleep is never piped into anything.
+const SEGMENT_SEPARATOR = /&&|\|\||;|&|\n/u
+// `sleep 600`, `sleep 10m`, `sleep 1.5`. The whole segment has to be the sleep: a `sleep` carrying
+// arguments this does not model is not something to guess the duration of.
+// cspell:ignore smhd
+const SLEEP_SEGMENT = /^sleep\s+(\d+(?:\.\d+)?)([smhd]?)$/u
+// What may stand beside the sleep without making the call something other than a wait — the marker a
+// waking turn prints for itself. Anything that does work is not a wait timer.
+const INERT_SEGMENT = /^(?::|true|(?:echo|printf|date)\b.*)$/u
+// **A loop is not an arm.** `until <condition>; do sleep 30; done` ends on the condition and reports
+// the condition; refusing it would take polling away from a run that is waiting on a thing rather
+// than on a clock, which is the opposite of what this rule is for.
+const LOOP_KEYWORD = /\b(?:while|until|for|do|done)\b/u
+
+// GNU `sleep` takes a suffix and BSD `sleep` does not, so both spellings are read. A bare number is
+// seconds, which is the one every shell agrees on.
+const SECONDS_PER_UNIT: Readonly<Record<string, number>> = { d: 86_400, h: 3600, m: 60, s: 1 }
+const BARE_NUMBER_SECONDS = 1
+
+const AMOUNT_GROUP = 1
+const UNIT_GROUP = 2
+
+const NO_SECONDS = 0
+
+// **The record holds the instant the armed timer expires**, and it is read through the shared refusal
+// stamp because that shell already answers `NEVER_MS` for a record that is absent, unreadable or
+// someone else's — which is exactly "no timer is live". Its field is named `refused_at_ms` for the
+// refusals it was written for; a second implementation of the same read-parse-fallback path would be
+// the clone `CLAUDE.md` prohibits, and this record is a temporary file nobody else reads.
+const ARM_RECORD = hook_decision.create_refusal_stamp(ARM_PREFIX)
+
+function segments_of(command: string): Array<string> {
+	return command
+		.split(SEGMENT_SEPARATOR)
+		.map((segment) => segment.trim())
+		.filter((segment) => segment !== '')
+}
+
+function sleep_seconds(segment: string): number | undefined {
+	const matched = SLEEP_SEGMENT.exec(segment)
+
+	if (matched === null) return undefined
+
+	const unit = matched[UNIT_GROUP] ?? ''
+
+	return Number(matched[AMOUNT_GROUP]) * (SECONDS_PER_UNIT[unit] ?? BARE_NUMBER_SECONDS)
+}
+
+function is_wait_or_inert(segment: string): boolean {
+	return sleep_seconds(segment) !== undefined || INERT_SEGMENT.test(segment)
+}
+
+/**
+ * Whether this call's whole purpose is to wait.
+ *
+ * **The shape is the discriminator, because the intent is not visible.** A call that sleeps and then
+ * does work is waiting *for* that work; a call that only sleeps is arming a timer, and the turn it
+ * wakes is the one that writes the report. Judged from the call alone, so nothing is read before the
+ * cheap answer is available.
+ */
+function is_wait_timer(command: string): boolean {
+	if (LOOP_KEYWORD.test(command)) return false
+
+	const segments = segments_of(command)
+
+	if (segments.every((segment) => sleep_seconds(segment) === undefined)) return false
+
+	return segments.every((segment) => is_wait_or_inert(segment))
+}
+
+/** How long the armed timer runs — the sum, because `sleep 60 && sleep 60` waits for two minutes. */
+function wait_duration_ms(command: string): number {
+	const seconds = segments_of(command).reduce(
+		(total, segment) => total + (sleep_seconds(segment) ?? NO_SECONDS),
+		NO_SECONDS,
+	)
+
+	return seconds * run_progress.MS_PER_SECOND
+}
+
+function is_armed(target: string, now_ms: number): boolean {
+	return now_ms < ARM_RECORD.last_ms(target)
+}
+
+/**
+ * Where the report this timer produces would land, or `undefined` when the arm must be refused.
+ *
+ * **A timer longer than the interval is refused rather than trimmed.** The watcher reports on its own
+ * every interval, so nothing legitimate waits longer than one — and the alternative, recording a
+ * shorter expiry than the timer really has, would let a second timer be armed while the first was
+ * still running, which is the defect this rule exists to prevent. Refusing instead keeps every record
+ * exact **and** bounds a record that turns out to be wrong to one interval, since no arm can reach
+ * further than that.
+ *
+ * **The rest is applied to where the report lands, not to where the arm is made.** A timer armed the
+ * moment a real report went out is legitimate exactly when it runs the full interval, and a rule that
+ * measured the arm would refuse the one arm that is always right.
+ */
+function landing_ms(command: string, now_ms: number, last_report_ms: number): number | undefined {
+	const interval_ms = run_progress_config.configured_interval_ms()
+	const duration_ms = wait_duration_ms(command)
+
+	if (duration_ms > interval_ms) return undefined
+
+	const lands_ms = now_ms + duration_ms
+
+	return run_progress.is_due(last_report_ms, lands_ms, interval_ms) ? lands_ms : undefined
+}
+
+/**
+ * The two conditions the Issue names, and one that scopes the rule to the runs it was written for.
+ *
+ * **No progress record means no clock, and no clock means no rule.** An ordinary conversational
+ * session never starts the watcher and never marks, so it reads `undefined` here and nothing is
+ * refused — the scope joshuafolkken/kit#1570 set out of bounds, held by the absence of a record rather
+ * than by a second judgement about what kind of session this is.
+ *
+ * **A live timer is counted from the record this function writes, never from the processes on the
+ * machine.** A process count cannot tell a heartbeat timer from a build step that sleeps, and a timer
+ * killed with its shell would leave the count wrong for the rest of the run; a record that expires at
+ * the instant the timer fires cannot.
+ *
+ * **`can_record` is false where the call may never run.** The record is written at `PreToolUse`,
+ * before the sleep starts, and nothing runs it back — so a call another hook is about to refuse would
+ * leave a timer recorded as live that never existed, and lock out the legitimate arm that follows.
+ * The caller answers that question, because it is the one that knows what the other hooks are doing.
+ * **Refusing is unaffected**: a rule that also stayed silent there would be silent on exactly the lone
+ * `Bash` call an arm always is. What it costs is the other direction — an arm that *was* allowed and
+ * did run inside that window is not recorded, so a second one before it fires is not caught. That is
+ * the lesser of the two, because a missing record loses one detection while a wrong one blocks every
+ * arm until it expires.
+ */
+function decide(call: GuardedCall, run: GuardRun, can_record: boolean): boolean {
+	const last_report_ms = run_progress_clock.read_last_report_sync()
+
+	if (last_report_ms === undefined) return false
+
+	const target = ARM_RECORD.path(run.transcript)
+
+	if (is_armed(target, run.now_ms)) return true
+
+	const lands_ms = landing_ms(time_shell.bash_command(call.input), run.now_ms, last_report_ms)
+
+	if (lands_ms === undefined) return true
+	if (can_record) ARM_RECORD.record(target, lands_ms)
+
+	return false
+}
+
+// The instruction in the shape a refusal can carry: what the call is about to do, what already does it
+// properly, and the one command an explicit ask is answered with. The measurement is named because it
+// is the half that makes the rule believable — the promise was kept and the interval was not.
+const EARLY_HEARTBEAT_REASON =
+	'⛔ early heartbeat: this call arms a wait timer of its own, and the progress clock is not yours ' +
+	'to keep. `pnpm josh run:progress --wait` waits the interval out for you ' +
+	'(`JOSH_PROGRESS_INTERVAL_MINUTES`, or `josh.progress_interval_minutes` in `package.json`, ' +
+	'default 20 minutes), prints the five labelled lines and exits — start it in the background, relay ' +
+	'the lines it printed when it exits, and start the next one. Two timers armed at ' +
+	'once is what produced reports 3–5 minutes apart on a 15-minute setting ' +
+	'(joshuafolkken/kit#1570): a new one was armed on the turn a timer fired and again on the turn a ' +
+	"child's completion woke the run, and `--mark` recorded each report without anything refusing the " +
+	'early ones. **An explicit ask is not a heartbeat**: if the person asked for progress now, run ' +
+	'`pnpm josh run:progress --once`, which prints the five labelled lines whatever the clock says. ' +
+	'If you are ' +
+	'waiting on something rather than on a clock, wait on the thing itself — `pnpm josh followup` ' +
+	'waits for CI. The procedure is `.claude/skills/workflow-commands/backlogrun.md` → "Progress while ' +
+	'the run is quiet". **This rule fires on every early arm, not once per run**, so reissuing the ' +
+	'same sleep will be refused again.'
+
+// **Keeping this rule is letting the watcher hold the clock** — `pnpm josh run:progress --wait` waits
+// the interval out, and `--once` answers an explicit ask. `--mark` is neither: it records a report
+// that has already gone out rather than waiting for the next one, and crediting it would score every
+// run that reported at all as having kept a rule about waiting.
+// The canonical name; both spellings match, because the alias is expanded where the command is read
+// (joshuafolkken/kit#1789).
+const PROGRESS_NAMES: ReadonlySet<string> = new Set(['run:progress'])
+const WATCH_FLAG = /(?:^|\s)--(?:wait|once)(?=\s|$)/u
+
+function is_progress_watch_segment(segment: string): boolean {
+	return shell_segments.is_josh_command(segment, PROGRESS_NAMES) && WATCH_FLAG.test(segment)
+}
+
+// The quoted spans are blanked first: this separator set cuts on `\n`, so a notify body carrying the
+// watcher's own command on a line of its own would otherwise be credited as the watcher running.
+function is_progress_watch(command: string): boolean {
+	return segments_of(time_shell.unquoted(command)).some((segment) =>
+		is_progress_watch_segment(segment),
+	)
+}
+
+// **The occasion this rule governs: waiting for the run's next progress report**, in either spelling
+// (joshuafolkken/kit#1643). The trigger fires only on the hand-armed timer, so a run that always let
+// the watcher wait would never appear in the reading at all.
+function waits_for_progress(command: string): boolean {
+	return is_wait_timer(command) || is_progress_watch(command)
+}
+
+const early_heartbeat = {
+	ARM_PREFIX,
+	EARLY_HEARTBEAT_REASON,
+	decide,
+	is_progress_watch,
+	is_wait_timer,
+	wait_duration_ms,
+	waits_for_progress,
+}
+
+export { early_heartbeat }

package/scripts/rules/file-body.ts

@@ -0,0 +1,150 @@
+import { existsSync } from 'node:fs'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `file-body` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2120). Group 3 of the three Bash-string gaps: a file's new body carried inline in
+// a shell command, the form `CLAUDE.md` → "Never carry a file's new text inside a shell command" and
+// `file-edits.md` forbid.
+//
+// **The detector existed for measurement and refused nothing.** `time-writes.ts` already knew a
+// redirection and a heredoc write a file; nothing turned that knowledge into a refusal. This row does,
+// and it keeps `file-edits.md`'s allow/deny table exactly: the one branch is whether the redirect target is an
+// existing file, and a synchronous `stat` decides it — a new-file creation and a read-only heredoc stay
+// silent, an existing-file rewrite is refused.
+//
+// **Three shapes, one row.** (1) A heredoc whose redirect or `tee` target already exists. (2) an
+// interpreter reading a heredoc — or a `node -e` — whose body writes a file: the canonical `python3 -
+// <<'PY' … open(f,'w') … PY`, which has no shell redirect to stat, is caught by its body instead. (3)
+// an in-place `perl -0pi -e`. A read-only heredoc (`cat <<'EOF'`, a compute-only `python3 -`) writes
+// nothing and stays silent — the enumeration's rule that a non-firing turn is a kept turn.
+//
+// **It fires on every occurrence** (`git-force.ts`): each inline body is paid for again, so
+// refused-once-and-free-after would let the second rewrite through.
+
+// A heredoc marker in any of its spellings: `<<EOF`, `<< 'EOF'`, `<<-"EOF"`. Its presence is what
+// separates a body-carrying write from an ordinary redirect a run legitimately uses to extract text.
+const HEREDOC = /<<-?\s*['"]?\w+/u
+// The first physical line carries the command, its redirect and the heredoc marker; the body follows on
+// the lines after it. The two are read separately so the redirect target is found on the command line
+// and the write indicators are scanned in the body.
+const LINE_BREAK = '\n'
+
+function first_line(command: string): string {
+	const [line] = command.split(LINE_BREAK)
+
+	return line ?? ''
+}
+
+function has_heredoc(command: string): boolean {
+	return HEREDOC.test(command)
+}
+
+// A file redirect (`> path`, `>> path`) or a `tee path`, with the target captured. A descriptor
+// redirect (`2>&1`) and an append-to-fd are excluded — the `&` after `>` marks them.
+const FILE_REDIRECT = /(?:^|\s)>>?\s*(?!&)("[^"]+"|'[^']+'|\S+)/u
+const TEE_TARGET = /\btee\s+(?:-a\s+)?(?!-)("[^"]+"|'[^']+'|\S+)/u
+const QUOTES = /^['"]|['"]$/gu
+
+function redirect_target(line: string): string | undefined {
+	const target = FILE_REDIRECT.exec(line)?.[1] ?? TEE_TARGET.exec(line)?.[1]
+
+	return target === undefined ? undefined : target.replaceAll(QUOTES, '')
+}
+
+// Shape 1: a heredoc write whose target already exists. The existence check is injected so the suite
+// controls it without touching the real filesystem, the same way `lane-park.ts` injects the lane fact.
+function writes_existing_file(command: string, has_file: (path: string) => boolean): boolean {
+	if (!has_heredoc(command)) return false
+
+	const target = redirect_target(first_line(command))
+
+	return target !== undefined && has_file(target)
+}
+
+// The interpreters that carry a body to run rather than a region to read. `cat` / `grep` / `sed -n`
+// are deliberately absent — a heredoc fed to them is the read-only form `file-edits.md` allows.
+const BODY_INTERPRETERS: ReadonlySet<string> = new Set(['python', 'python3', 'ruby', 'perl', 'php'])
+const NODE = 'node'
+const NODE_EVAL = /(?:^|\s)(?:-e|--eval)\b/u
+
+// A body that writes a file, in Python and Node spellings — split across two patterns so neither
+// exceeds the regex-complexity ceiling. The named write calls: `writeFile` covers `writeFileSync`,
+// `appendFile` covers its sync form, and `.write(` covers `.writelines(`.
+const WRITE_CALL = /writeFile|appendFile|createWriteStream|\.write(?:lines)?\s*\(/u
+// The mode-string and relocation forms: an `open(…, "w"|"a"|"x")`, `os.replace`, `shutil.copy` / `move`.
+// A mode string of `r` alone (a read) matches none of these, so a compute- or read-only heredoc stays
+// silent.
+const WRITE_MODE = /open\s*\([^)]*['"][rbt+]*[wax]|os\.replace|shutil\.(?:copy|move)/u
+
+function body_writes(command: string): boolean {
+	return WRITE_CALL.test(command) || WRITE_MODE.test(command)
+}
+
+// Shape 2: an interpreter reading a heredoc, or a `node -e`, whose body writes.
+function is_interpreter_write(segment: string, command: string): boolean {
+	const leading = time_shell.leading_word(segment)
+
+	if (BODY_INTERPRETERS.has(leading)) return has_heredoc(command) && body_writes(command)
+
+	return leading === NODE && NODE_EVAL.test(segment) && body_writes(segment)
+}
+
+// Shape 3: an in-place `perl` edit — `-i`, `-pi`, `-0pi`. A lowercase `i` in the flag cluster is the
+// in-place switch; the capital `-I` (an include path) is not, so the pattern keys on the lowercase.
+const PERL = 'perl'
+const PERL_IN_PLACE = /^-[A-Za-z0-9]*i/u
+const WHITESPACE = /\s+/u
+
+function is_in_place_perl(segment: string): boolean {
+	if (time_shell.leading_word(segment) !== PERL) return false
+
+	return segment.split(WHITESPACE).some((word) => PERL_IN_PLACE.test(word))
+}
+
+// The interpreter and perl shapes are read per first-line segment, so a heredoc marker on the same line
+// is judged against the command that opened it rather than against a later one in a chain.
+function has_body_interpreter(command: string): boolean {
+	return shell_segments
+		.segments_of(first_line(command))
+		.some((segment) => is_interpreter_write(segment, command) || is_in_place_perl(segment))
+}
+
+function carries_a_file_body(
+	command: string,
+	has_file: (path: string) => boolean = existsSync,
+): boolean {
+	return writes_existing_file(command, has_file) || has_body_interpreter(command)
+}
+
+// The instruction in the shape a refusal can carry: what the command is doing, the safe tool, and the
+// file forms that stay allowed. The measured cost is named because it is the half that reads as
+// surprising — the command body is billed on every later request of the run.
+const FILE_BODY_REASON =
+	"⛔ file body in a shell command: this carries a file's new text inline — a heredoc rewriting an " +
+	'existing file, an interpreter (`python3 - <<`, `node -e`) whose body writes, or an in-place `perl ' +
+	'-0pi -e`. `CLAUDE.md` forbids it because the command body is re-read on every later request of the ' +
+	'run, so an editing script written early is billed for the rest of it (`file-edits.md` measured one ' +
+	'run at ~2m45s spent retyping existing lines). Edit a region with the Edit tool (old / new), or pass ' +
+	'a body by path (`--field body=@<path>`, `--body-file <path>`). A new-file creation (`cat > ' +
+	'<new-file> <<EOF`), a read-only heredoc (`cat <<EOF`), and a short `sed -i` stay allowed. **This ' +
+	'rule fires on every occurrence, not once per run.**'
+
+const ROW = {
+	id: 'file-body',
+	is_trigger: bash_triggers.on_bash_command((command: string) => carries_a_file_body(command)),
+	reason: FILE_BODY_REASON,
+	decide: (): boolean => true,
+}
+
+const file_body = {
+	FILE_BODY_REASON,
+	ROW,
+	carries_a_file_body,
+	is_in_place_perl,
+	is_interpreter_write,
+	writes_existing_file,
+}
+
+export { file_body }

package/scripts/rules/filing-cap.ts

@@ -0,0 +1,133 @@
+import type { GuardRun } from '#scripts/josh/hook-decision'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_transcript_line, type Block } from '#scripts/time-runtime/time-transcript-line'
+import { bash_triggers } from './bash-triggers'
+import { tail_commands } from './tail-commands'
+
+// The trigger and the decision behind the `filing-cap` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2119).
+//
+// **Automatic filing is capped at 10 Issues per run, refused at the eleventh filing.** §2d and
+// `observation-filing.md` state the ceiling; nothing counted it, so a run that over-filed was held
+// only by self-restraint. The input is mechanical — how many Issues this run has already filed — so
+// it is a delivered rule rather than resident prose. **No new predicate**: the filing is
+// `bash_triggers.is_issue_filing`, reused verbatim.
+//
+// **It fires on every filing past the cap, not once per run.** The subject is a recurring act — one
+// more filing — so `DeliveredRule.decide` is the right disposition (joshuafolkken/kit#1570): refused
+// once and free afterwards would put the enforcement back on the self-restraint that failed.
+//
+// **A guard-refused filing does not count.** Claude Code writes a denied call to the transcript as a
+// `tool_use` block with an errored `tool_result`, so the WIP cap's own reissue would otherwise
+// double-count one Issue — the same exclusion `investigation-reads.ts` makes for a refused read
+// (joshuafolkken/kit#1764). The filing is counted only where its result carried no guard refusal.
+
+const FILING_CAP = 10
+// The current call is not yet on the tail, so the count read there is of filings *already* made. At
+// this many, the call in hand is the eleventh and is refused.
+const CAP_REACHED = FILING_CAP
+
+interface TailFilings {
+	// The `tool_use` id of every filing on the tail.
+	filing_ids: Array<string>
+	// Each result's id mapped to the guard that refused it, and `''` for a result no guard refused.
+	refusals: Map<string, string>
+}
+
+function is_filing_use(block: Block): boolean {
+	if (!tail_commands.is_bash_use(block)) return false
+
+	return bash_triggers.is_issue_filing(time_shell.bash_command(block.input))
+}
+
+function collect_block(block: Block, found: TailFilings): void {
+	if (block.result_id !== '') found.refusals.set(block.result_id, block.refusal_guard)
+	if (is_filing_use(block)) found.filing_ids.push(block.id)
+}
+
+function collect_line(line: string, found: TailFilings): void {
+	const parsed = time_transcript_line.parse_line(line)
+
+	if (parsed === undefined) return
+
+	for (const block of parsed.blocks) collect_block(block, found)
+}
+
+function scan_tail(tail: string): TailFilings {
+	const found: TailFilings = { filing_ids: [], refusals: new Map<string, string>() }
+
+	for (const line of tail.split('\n')) collect_line(line, found)
+
+	return found
+}
+
+// How many Issues the run has already filed, counting only filings no guard refused.
+function prior_filing_count(tail: string): number {
+	const { filing_ids, refusals } = scan_tail(tail)
+
+	return filing_ids.filter((id) => (refusals.get(id) ?? '') === '').length
+}
+
+// A person's prompt: a `user` line carrying no tool result. Tool results ride `user` lines too, so the
+// absence of one is what marks the line as typed rather than returned.
+function is_prompt_line(line: string): boolean {
+	const parsed = time_transcript_line.parse_line(line)
+
+	if (parsed?.type !== 'user') return false
+
+	return parsed.blocks.every((block) => block.result_id === '')
+}
+
+// The tail from the last prompt on, so a filing an earlier turn made does not answer for this one
+// (joshuafolkken/kit#2422). A tail with no prompt on it is returned whole.
+function current_turn(tail: string): string {
+	const lines = tail.split('\n')
+	const start = lines.findLastIndex((line) => is_prompt_line(line))
+
+	return lines.slice(Math.max(start, 0)).join('\n')
+}
+
+// How many Issues this turn has filed — the per-run count read over `current_turn`.
+function turn_filing_count(tail: string): number {
+	return prior_filing_count(current_turn(tail))
+}
+
+// **Fires on every filing past the cap, not once per run.** It records nothing and ignores the
+// last-fired instant, so `decide` — which the enumeration asks unconditionally — refuses each filing
+// while the count stands at or above the ceiling. `can_record` has nothing to protect for a row that
+// writes no stamp.
+function decide(_call: unknown, run: GuardRun): boolean {
+	return prior_filing_count(time_density_hook.read_tail(run.transcript)) >= CAP_REACHED
+}
+
+const FILING_CAP_REASON =
+	`⛔ filing cap: this run has already filed ${String(FILING_CAP)} Issues, the per-run ceiling — on ` +
+	'reaching it, stop and report rather than filing more. Automatic filing is capped so a run cannot ' +
+	'manufacture Issues faster than they can be closed (`.claude/skills/workflow-commands/SKILL.md` → ' +
+	"§2d, `observation-filing.md`). A further Issue that genuinely must exist is a person's call, not " +
+	"this run's. **This rule fires on every filing past the cap, not once per run**, so reissuing the " +
+	'same filing will be refused again.'
+
+// The enumeration row itself, so `delivered-rules.ts` spreads one entry rather than restating the
+// trigger and reason it already single-sources here. It declares no `keeps`: staying under a cap is
+// not a call, so the row is reported unmeasured rather than scored on an act that does not exist —
+// the honest answer `investigation` gives for the same reason.
+const ROW = {
+	id: 'filing-cap',
+	is_trigger: bash_triggers.on_bash_command(bash_triggers.is_issue_filing),
+	reason: FILING_CAP_REASON,
+	decide,
+}
+
+const filing_cap = {
+	FILING_CAP,
+	FILING_CAP_REASON,
+	ROW,
+	current_turn,
+	decide,
+	prior_filing_count,
+	turn_filing_count,
+}
+
+export { filing_cap }

package/scripts/rules/filing-offer.ts

@@ -0,0 +1,81 @@
+import { repo_party } from '#scripts/discovery/repo-party'
+import { issue_citation } from './issue-citation'
+
+// The predicates behind the `filing-offer` row of the stop guard (joshuafolkken/kit#2422).
+//
+// **A first-party filing is Tier A, and an offer to file is that filing deferred to the user.**
+// `SKILL.md` → §2i says a run that judges something worth filing files it without asking, yet a reply
+// can still end on "it is worth filing — say so if you want it filed". The rule was resident; what was
+// missing was anything that fired at the moment of hesitation. That moment is one `Stop` payload: a
+// reply that offers to file, on a turn that filed nothing.
+//
+// **The detection is tightened the way `issue-citation.ts` is**, because a block costs a turn: only
+// the run's own prose is read (`issue_citation.prose_lines` — no fenced example, no quote line), and
+// only a phrase that *asks* is matched. A reply reporting a filing ("Filed …", or its Japanese past
+// tense) carries no asking phrase, and a filing already on the transcript tail stands the row down
+// regardless of wording.
+//
+// **A third-party target is never pushed toward a filing.** It is Tier C (`CLAUDE.md` → "Third-party
+// repositories are Tier C"), so any `owner/repo` the reply names whose owner is not the session's —
+// `repo_party.classify`, the one definition `josh repo:party` reads — keeps the row silent, and so
+// does a session owner that cannot be read. The failure direction is a missed nudge, never a Tier C
+// write prompted by the hook.
+
+// The phrases that offer a filing rather than report one. Japanese first — the session language —
+// then English. Each asks for permission, proposes, or judges the filing appropriate without making it.
+const OFFER_PATTERNS: ReadonlyArray<RegExp> = [
+	/起票(?:して)?(?:も)?(?:よければ|よろしければ|よいですか|良いですか|よろしいですか|いいですか)/u,
+	/起票(?:しましょうか|しますか|するのが妥当|すべきだと|すべきと|を提案|をご提案)/u,
+	/Issue\s*[化に](?:しましょうか|しますか|してよければ)/iu,
+	/\b(?:shall|should)\s+I\s+(?:file|open|raise)\b/iu,
+	/\b(?:want|like)\s+me\s+to\s+(?:file|open|raise)\b/iu,
+	/\blet\s+me\s+know\s+if\s+you\s+(?:want|would\s+like)\s+(?:me\s+to\s+file|it\s+filed)\b/iu,
+]
+
+// A GitHub URL's owner, as group 1. The qualified `owner/repo#N` spelling is read by
+// `issue_citation.bare_references` instead, whose backward prefix scan stays linear.
+const GITHUB_URL_OWNER = /github\.com\/([\w.-]+)\//gu
+const OWNER_SEPARATOR = '/'
+
+function is_offer_line(line: string): boolean {
+	return OFFER_PATTERNS.some((pattern) => pattern.test(line))
+}
+
+// Whether the run's own prose offers to file an Issue instead of filing it.
+function offers_filing(message: string): boolean {
+	return issue_citation.prose_lines(message).some((line) => is_offer_line(line))
+}
+
+function url_owners(message: string): ReadonlyArray<string> {
+	return [...message.matchAll(GITHUB_URL_OWNER)].map((match) => match[1] ?? '')
+}
+
+// The owners of the qualified `owner/repo#N` references the prose writes out.
+function qualified_owners(message: string): ReadonlyArray<string> {
+	return issue_citation
+		.bare_references(message)
+		.filter((reference) => reference.includes(OWNER_SEPARATOR))
+		.map((reference) => reference.split(OWNER_SEPARATOR)[0] ?? '')
+}
+
+// Every repository owner the reply names, from either spelling.
+function mentioned_owners(message: string): ReadonlyArray<string> {
+	return [...url_owners(message), ...qualified_owners(message)]
+}
+
+// Whether the filing the reply offers targets a first-party repository: the session owner is readable
+// and every owner the reply names is it. A reply naming no repository offers a filing here, which is
+// first-party by definition once the session owner is known. The whole reply is read, not the offer
+// line alone: Japanese prose names the target on one line and asks on the next, and reading only the
+// ask would push a Tier C filing — so a third-party link cited as context costs a missed nudge instead.
+function is_first_party_target(message: string, session_owner: string | undefined): boolean {
+	if (session_owner === undefined) return false
+
+	return mentioned_owners(message).every(
+		(owner) => repo_party.classify(session_owner, owner) === repo_party.FIRST_PARTY,
+	)
+}
+
+const filing_offer = { is_first_party_target, mentioned_owners, offers_filing }
+
+export { filing_offer }

package/scripts/rules/firing-point.ts

@@ -0,0 +1,63 @@
+// A behavior-change Issue names its **firing point** — the tool call first invoked at the moment
+// the rule it changes would break (`prompts/collaboration-workflow/issue-template.md`). This
+// classifies that name against the rule-delivery table (joshuafolkken/kit#2212).
+//
+// **Why the name matters.** joshuafolkken/kit#2201 placed a correct rule whose named tool call was
+// one call behind the one that actually broke it: the lane child's turn ended at `AskUserQuestion`,
+// which the guard never saw. A rule delivered by a hook can only fire on a tool the hook is wired to;
+// a firing point naming a tool outside that set is a rule no hook can enforce, and saying so at filing
+// time is the whole point of the check.
+
+// **The hook-deliverable set — the single source is `rule-delivery.md`'s delivery table.** The
+// `PreToolUse` guard is wired to `Bash|Edit|Read|Write` (`scripts/hooks/pretool-guard.ts`), and the
+// lane-child interactive-ask row triggers on `AskUserQuestion`. A firing point naming one of these can
+// be delivered at the moment it binds; anything else cannot.
+const HOOK_DELIVERABLE_TOOLS: ReadonlyArray<string> = [
+	'Bash',
+	'Edit',
+	'Read',
+	'Write',
+	'AskUserQuestion',
+]
+
+// **Known Claude Code tool calls that a hook cannot deliver a rule on.** They are real tools, so a
+// firing point naming one is not a typo — it is a rule whose enforcement stays with the parent's
+// self-restraint, the thing that failed in joshuafolkken/kit#2201. Kept apart from
+// `HOOK_DELIVERABLE_TOOLS` so `not-delivered` (a real but undeliverable tool) reads differently from
+// `unknown` (not a tool call name at all).
+const KNOWN_UNDELIVERABLE_TOOLS: ReadonlyArray<string> = [
+	'Grep',
+	'Glob',
+	'WebFetch',
+	'WebSearch',
+	'TodoWrite',
+	'Task',
+	'Agent',
+	'NotebookEdit',
+]
+
+type FiringPointVerdict = 'delivered' | 'not-delivered' | 'unknown'
+
+function includes_name(names: ReadonlyArray<string>, name: string): boolean {
+	return names.includes(name.trim())
+}
+
+// Where a firing point's tool name sits against the delivery table: `delivered` when a hook can carry
+// the rule (a match), `not-delivered` when the tool is real but undeliverable (a mismatch), and
+// `unknown` when the name is not a tool call at all (off the table).
+function classify(name: string): FiringPointVerdict {
+	if (includes_name(HOOK_DELIVERABLE_TOOLS, name)) return 'delivered'
+
+	if (includes_name(KNOWN_UNDELIVERABLE_TOOLS, name)) return 'not-delivered'
+
+	return 'unknown'
+}
+
+const firing_point = {
+	HOOK_DELIVERABLE_TOOLS,
+	KNOWN_UNDELIVERABLE_TOOLS,
+	classify,
+}
+
+export type { FiringPointVerdict }
+export { firing_point }