@joshuafolkken/kit 1.872.0

package/scripts/backlog/backlog-stalled-detect.ts

@@ -0,0 +1,143 @@
+import { telegram_notify } from '#scripts/git/telegram-notify'
+import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
+import { backlog_ready, type ReadyPorts } from './backlog-ready'
+import { backlog_stalled, type StallReading, type StallVerdict } from './backlog-stalled'
+
+// The I/O half of the stall detector (joshuafolkken/kit#2359): it gathers the three counts the pure
+// judge in `backlog-stalled.ts` weighs, then — on a stall — leaves the marker and sends the one
+// notification. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary; the CLI
+// exposes the same call for a person to run by hand.
+//
+// **Cheap first.** The costly read is `backlog:next`, a subprocess that hits the network. The two local
+// reads gate it: the dispatch age comes free from the stream this already reads, and the free-lane count
+// is one `git worktree list`. Neither the lane count nor the backlog read is made unless the cheaper
+// condition ahead of it already holds, so an ordinary stop — a run not idle, or with no free lane —
+// costs a single file read and nothing more.
+
+const NO_FREE = 0
+const NO_READY = 0
+const NO_AGE = 0
+
+// The recovery line names the command that resolves the stall — the same one `run:step` points a stalled
+// run at — so the person the notification reaches has the fix in hand.
+const STALL_RECOVERY = 'Dispatch the ready work with `pnpm josh backlog:next`.'
+
+// The seams a test replaces: the stream target and its events, the clock, the two counts, and the two
+// side effects. The defaults are the real readers; a test hands fakes so the gather and report logic run
+// without a git tree, a network or a wall clock.
+interface DetectPorts {
+	resolve_target: () => Promise<string | undefined>
+	read_events: (target: string) => ReadonlyArray<RunEvent>
+	now_ms: () => number
+	free_lane_count: () => Promise<number>
+	ready_count: () => Promise<number>
+	emit_stall: (text: string) => Promise<boolean>
+	notify_stalled: (body: string) => Promise<boolean>
+}
+
+// The free-lane and runnable-issue reads are `backlog-ready.ts`'s — the watcher's ready line reads the
+// same two, so they live once there (joshuafolkken/kit#2452) — and a caller that reads them again after
+// this check hands its own ports in, so the two share one reading (joshuafolkken/kit#2472).
+function ready_count_of(ready: ReadyPorts): () => Promise<number> {
+	return async function (): Promise<number> {
+		const issues = await ready.ready_issues()
+
+		return issues.length
+	}
+}
+
+// One stall per episode, and the episode ends at a dispatch rather than at whatever event lands next
+// (joshuafolkken/kit#2464) — every parallel lane appends to this stream, so a newest-event dedup re-fired.
+async function real_emit_stall(text: string): Promise<boolean> {
+	const { STALL, CHILD_LAUNCH } = run_event_stream.EVENT_KIND
+
+	return await run_event_stream_emit.emit_once_since(STALL, text, CHILD_LAUNCH)
+}
+
+async function real_notify_stalled(body: string): Promise<boolean> {
+	return await telegram_notify.stalled({ body, recovery: STALL_RECOVERY })
+}
+
+function ports_over(ready: ReadyPorts): DetectPorts {
+	return {
+		resolve_target: run_event_stream_emit.stream_target,
+		read_events: run_event_stream.read_events,
+		now_ms: () => Date.now(),
+		free_lane_count: ready.free_lane_count,
+		ready_count: ready_count_of(ready),
+		emit_stall: real_emit_stall,
+		notify_stalled: real_notify_stalled,
+	}
+}
+
+const DEFAULT_PORTS: DetectPorts = ports_over(backlog_ready.DEFAULT_PORTS)
+
+function ok_reading(dispatch_age_ms: number): StallReading {
+	return { ready_count: NO_READY, free_lanes: NO_FREE, dispatch_age_ms }
+}
+
+// The idle-and-past-threshold branch, where the costly reads finally happen: count the free lanes, and
+// only if one is free read the backlog. A full pool short-circuits before the network call — a stall
+// needs a lane to go into.
+async function probe_reading(ports: DetectPorts, dispatch_age_ms: number): Promise<StallReading> {
+	const free_lanes = await ports.free_lane_count()
+
+	if (free_lanes <= NO_FREE) return { ready_count: NO_READY, free_lanes, dispatch_age_ms }
+
+	return { ready_count: await ports.ready_count(), free_lanes, dispatch_age_ms }
+}
+
+// The reading that decides the verdict, assembled cheap-condition-first. `undefined` is the unreadable
+// answer: no stream to key on, so no run to be stalled. Every early return yields a reading the judge
+// maps to `ok`; only when the run is idle past the threshold does `probe_reading` make the costly reads.
+async function gather(ports: DetectPorts, threshold_ms: number): Promise<StallReading | undefined> {
+	const target = await ports.resolve_target()
+
+	if (target === undefined) return undefined
+
+	const age = backlog_stalled.dispatch_age_ms(ports.read_events(target), ports.now_ms())
+
+	if (age === undefined) return ok_reading(NO_AGE)
+	if (age <= threshold_ms) return ok_reading(age)
+
+	return await probe_reading(ports, age)
+}
+
+// The marker and the notification, both once per stall episode. `emit_stall` refuses a second until a
+// dispatch has intervened, and its `false` is what holds the notification back too — so a stall
+// polled every stop reaches the person once, not once a turn.
+async function report(ports: DetectPorts, reading: StallReading): Promise<void> {
+	const text = backlog_stalled.describe(reading)
+
+	if (await ports.emit_stall(text)) await ports.notify_stalled(text)
+}
+
+// Read the three conditions, print nothing, and on a stall leave the marker and notify. The verdict is
+// returned for the CLI to print; the side effects are the report's.
+async function detect_and_report(
+	ports: DetectPorts = DEFAULT_PORTS,
+	threshold_ms: number = backlog_stalled.STALL_THRESHOLD_MS,
+): Promise<StallVerdict> {
+	const reading = await gather(ports, threshold_ms)
+	const verdict = backlog_stalled.assess(reading, threshold_ms)
+
+	if (reading !== undefined && verdict === backlog_stalled.STALLED) await report(ports, reading)
+
+	return verdict
+}
+
+// Best-effort for the Stop hook: the detector is a report, so a failure to gather or notify is dropped
+// rather than raised into the stop decision it rides alongside.
+async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS): Promise<void> {
+	try {
+		await detect_and_report(ports_over(ready))
+	} catch {
+		// Reporting is best-effort: a stall we could not read or send is dropped, never a blocked stop.
+	}
+}
+
+const backlog_stalled_detect = { DEFAULT_PORTS, detect_and_report, gather, report, run_stall_check }
+
+export { backlog_stalled_detect }
+export type { DetectPorts }

package/scripts/backlog/backlog-stalled.ts

@@ -0,0 +1,118 @@
+import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+
+// When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks
+// (joshuafolkken/kit#2359). This is the mechanical judge of that state: three facts read, never
+// weighed — is there runnable work, is there a free lane, and has nothing been dispatched for a while.
+// The verdict is a report, not a stop: a false positive costs one notification, never a halted run.
+//
+// **Pure by design.** The clock and the counts are handed in, so the four acceptance cases — work with
+// a free lane, work with no free lane, no work, and an unreadable record — and the elapsed-time
+// boundary are unit-tested without a git tree, a network or a wall clock. The I/O that gathers the
+// counts is `backlog-stalled-detect.ts`; this file only decides.
+
+const STALL_THRESHOLD_MINUTES = 10
+const MS_PER_MINUTE = 60_000
+const STALL_THRESHOLD_MS = STALL_THRESHOLD_MINUTES * MS_PER_MINUTE
+const NONE = 0
+
+// `stalled` when all three conditions hold, `unreadable` when the dispatch record could not be read at
+// all, `ok` otherwise. An issue number is never one of these — they are the only three answers. The
+// verdicts carry this type rather than a bare literal so the exported `backlog_stalled` namespace does
+// not widen them to `string` at the object boundary (object-literal widening).
+type StallVerdict = 'stalled' | 'ok' | 'unreadable'
+
+const STALLED: StallVerdict = 'stalled'
+const OK: StallVerdict = 'ok'
+const UNREADABLE: StallVerdict = 'unreadable'
+
+// The three facts, read and never judged: how many issues could start now, how many lanes are free, and
+// how long since the last dispatch. Assembled by the detect layer; consumed only here.
+interface StallReading {
+	ready_count: number
+	free_lanes: number
+	dispatch_age_ms: number
+}
+
+// All three together, and only together. Separated from `assess` so the short-circuit gate in the
+// detect layer — the one that decides whether the expensive backlog read is worth making — reads the
+// same condition rather than a second copy of it.
+function is_stalled(reading: StallReading, threshold_ms: number): boolean {
+	return (
+		reading.ready_count > NONE &&
+		reading.free_lanes > NONE &&
+		reading.dispatch_age_ms > threshold_ms
+	)
+}
+
+// **The verdict, and the whole of the judgement.** An unread record answers first — `undefined` is the
+// detect layer saying it could not resolve the run's own stream — so a missing record never reads as a
+// stall. The boundary is strict: exactly at the threshold is not yet a stall, one millisecond past it
+// is.
+function assess(reading: StallReading | undefined, threshold_ms: number): StallVerdict {
+	if (reading === undefined) return UNREADABLE
+	if (is_stalled(reading, threshold_ms)) return STALLED
+
+	return OK
+}
+
+// The time a stall is measured from: the newest dispatch (`child-launch`), or — before the first
+// dispatch — the run's earliest recorded event, so a run that has never dispatched is still aged from
+// when it began. `undefined` for a stream with nothing on it: there is no run to be stalled.
+function dispatch_reference_iso(events: ReadonlyArray<RunEvent>): string | undefined {
+	const last_launch = events.findLast(
+		(event) => event.kind === run_event_stream.EVENT_KIND.CHILD_LAUNCH,
+	)
+
+	return last_launch?.at ?? events[0]?.at
+}
+
+// Milliseconds since that reference, or `undefined` when there is no reference or the stamp is
+// unparseable — the caller reads either as "nothing to age against" and returns no stall.
+function dispatch_age_ms(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
+	const iso = dispatch_reference_iso(events)
+
+	if (iso === undefined) return undefined
+
+	const at = Date.parse(iso)
+
+	return Number.isNaN(at) ? undefined : now_ms - at
+}
+
+// The one line a person reads in the notification and on the stream: what is waiting and how long.
+function describe(reading: StallReading): string {
+	const minutes = Math.floor(reading.dispatch_age_ms / MS_PER_MINUTE)
+
+	return `${String(reading.ready_count)} ready, ${String(reading.free_lanes)} free lane(s), ${String(minutes)}m since the last dispatch`
+}
+
+const NUMERIC_TOKEN = /^\d+$/u
+
+// The runnable issue numbers `backlog:next` printed: one token per line, a bare number per runnable
+// issue and a verdict word (`wait`, `stop`, …) when there is none — so the numeric lines are the ready
+// issues.
+function ready_tokens(out: string): ReadonlyArray<string> {
+	return out
+		.split('\n')
+		.map((token) => token.trim())
+		.filter((token) => NUMERIC_TOKEN.test(token))
+}
+
+function count_ready_tokens(out: string): number {
+	return ready_tokens(out).length
+}
+
+const backlog_stalled = {
+	STALLED,
+	OK,
+	UNREADABLE,
+	STALL_THRESHOLD_MS,
+	assess,
+	count_ready_tokens,
+	describe,
+	dispatch_age_ms,
+	is_stalled,
+	ready_tokens,
+}
+
+export { backlog_stalled }
+export type { StallReading, StallVerdict }

package/scripts/behavior/behavior-assertion.ts

@@ -0,0 +1,87 @@
+import {
+	time_transcript_line,
+	type TranscriptLine,
+} from '#scripts/time-runtime/time-transcript-line'
+
+// Verifying an agent's behavior against the transcripts every run already writes, with no live
+// Claude session and no model call (joshuafolkken/kit#2365).
+//
+// **The mechanism that measured behavior used to be the completion gate's own, and it was removed
+// for being slow rather than for being wrong.** joshuafolkken/kit#1922 took `josh eval`'s five
+// scenarios out of the gate because each starts a real Claude session, so the step never ran without
+// `JOSH_EVAL` and paid a prompt-and-report cost every run for nothing. What it left behind is a gate
+// that proves the *machinery* works — 8,000-odd unit tests — and nothing at all that proves the
+// agent *behaves*. This is the half worth keeping, separated from the half worth removing: an
+// assertion read off a recorded transcript is deterministic, re-runnable and never calls a model.
+//
+// **The reading is single-sourced, not re-implemented.** One transcript line is parsed by
+// `time-transcript-line.ts` — the reader the span walk and the guards already use — and the files are
+// located and read by `cost-transcript.ts`. This module is only the assertions and the walk over the
+// parsed turns; it owns no second copy of "where a transcript lives" or "how a line is shaped".
+
+// Where in a transcript an assertion broke: which run, and which point in it. The failure names the
+// next place a reader looks rather than reporting that a rule broke somewhere in a session.
+interface Violation {
+	// The rule that broke, by name — so a reader tells one broken assertion from another without
+	// re-deriving it from the detail.
+	assertion: string
+	// The run the transcript belongs to. `''` until the caller that read the file stamps it, because
+	// the scan knows the turn and the detail but not which session file it was handed.
+	session_id: string
+	// The 1-based line position of the offending turn in the transcript, so "which point" is a place
+	// a reader can open rather than a description.
+	position: number
+	// What broke, in the assertion's own words — for the git-index rule, the command that mutated the
+	// index directly.
+	detail: string
+}
+
+// A violation before the session it was found in is attached. The scan produces these; the reader
+// that opened the file supplies the `session_id`.
+type Finding = Omit<Violation, 'session_id'>
+
+// One behavior rule: a name, a human description, and a pure scan over the parsed turns of one
+// transcript. The scan returns every point it broke, so a single transcript can report more than one
+// violation and each names its own position.
+interface Assertion {
+	name: string
+	describe: string
+	scan: (lines: ReadonlyArray<TranscriptLine>) => ReadonlyArray<Finding>
+}
+
+// The parsed turns of one transcript, in file order. A line that fails to parse is dropped rather
+// than dated — it has no turn to point at — exactly as `time-spans.ts` drops it.
+function parse_transcript(text: string): ReadonlyArray<TranscriptLine> {
+	return text
+		.split('\n')
+		.map((line) => time_transcript_line.parse_line(line))
+		.filter((line): line is TranscriptLine => line !== undefined)
+}
+
+// Every assertion's findings over one set of parsed turns, each stamped with the session it was read
+// from. The single walk the CLI and the tests share, so a synthetic transcript and a real one are
+// checked the same way.
+function check_lines(
+	lines: ReadonlyArray<TranscriptLine>,
+	session_id: string,
+	assertions: ReadonlyArray<Assertion>,
+): ReadonlyArray<Violation> {
+	return assertions.flatMap((assertion) =>
+		assertion.scan(lines).map((finding) => ({ ...finding, session_id })),
+	)
+}
+
+// One transcript's raw text checked against every assertion — parsed once, then walked. The entry
+// point a caller uses when it holds the text rather than the parsed lines.
+function check_transcript(
+	text: string,
+	session_id: string,
+	assertions: ReadonlyArray<Assertion>,
+): ReadonlyArray<Violation> {
+	return check_lines(parse_transcript(text), session_id, assertions)
+}
+
+const behavior_assertion = { parse_transcript, check_lines, check_transcript }
+
+export type { Assertion, Finding, Violation }
+export { behavior_assertion }

package/scripts/behavior/behavior-cli.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
+import { status_icons } from '#scripts/lib/status-icons'
+import { behavior_assertion, type Violation } from './behavior-assertion'
+import { behavior_rules } from './behavior-rules'
+
+// `josh behavior` — check the current run's recorded transcript against the behavior assertions and
+// report where any broke (joshuafolkken/kit#2365). It runs inside `pnpm josh gate`, calls no model,
+// and reads one file: the session it is running in.
+//
+// **The scope is the current run, not the whole corpus.** The store holds thousands of transcripts
+// and over a gigabyte; walking all of it every gate would cost minutes, not the seconds the other
+// checks take. Each gate checks its own run, so across runs the whole corpus is covered a run at a
+// time — and the engine stays general, so a broad scan of past runs (the greenness check this seed
+// assertion was verified with) is the same walk over a different set of files.
+
+const PASS_EXIT_CODE = 0
+const FAIL_EXIT_CODE = 1
+const LABEL = 'josh behavior'
+
+// The current run's transcript: the newest of the session's *own* files across the directories a run
+// writes to, resolved by `cost-transcript.ts` exactly as `josh cost` resolves "the run that just
+// finished". A gate runs inside that session, so its transcript is the newest own file.
+function current_session(cwd: string = process.cwd()): SessionFile | undefined {
+	const directories = cost_transcript.transcript_directories(cwd)
+	const sessions = cost_transcript.list_sessions_across(directories)
+
+	return sessions[cost_transcript.latest_own_index(sessions)]
+}
+
+// **A run with no transcript passes, and passes without the skip marker.** The gate reads `—
+// skipping` to withhold its green record; a behavior check that found no transcript — a CI runner has
+// none — has nothing to say about the tree and must not withhold the record the other checks earned.
+function report_no_transcript(): number {
+	console.info(`${LABEL}: no recorded transcript to check ${status_icons.PASS_ICON}`)
+
+	return PASS_EXIT_CODE
+}
+
+// Which run and which point, in the assertion's own words — the failure names the place a reader
+// opens rather than reporting that a rule broke somewhere.
+function format_violation(violation: Violation): string {
+	const where = `run ${violation.session_id} at position ${String(violation.position)}`
+
+	return `${status_icons.FAIL_ICON} ${violation.assertion} broke in ${where}\n    ${violation.detail}`
+}
+
+function report_violations(violations: ReadonlyArray<Violation>): number {
+	for (const violation of violations) console.error(format_violation(violation))
+	console.error(`${LABEL}: ${String(violations.length)} behavior assertion(s) broke`)
+
+	return FAIL_EXIT_CODE
+}
+
+function report_green(session_id: string): number {
+	const count = String(behavior_rules.ALL_ASSERTIONS.length)
+
+	console.info(`${LABEL}: ${count} assertion(s) green in ${session_id} ${status_icons.PASS_ICON}`)
+
+	return PASS_EXIT_CODE
+}
+
+function check_session(file: SessionFile): number {
+	const text = cost_transcript.read_optional(file)
+
+	if (text === undefined) return report_no_transcript()
+
+	const violations = behavior_assertion.check_transcript(
+		text,
+		file.session_id,
+		behavior_rules.ALL_ASSERTIONS,
+	)
+
+	return violations.length > 0 ? report_violations(violations) : report_green(file.session_id)
+}
+
+function run(cwd: string = process.cwd()): number {
+	const file = current_session(cwd)
+
+	return file === undefined ? report_no_transcript() : check_session(file)
+}
+
+const behavior_cli = { LABEL, check_session, current_session, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = run()
+
+export { behavior_cli }

package/scripts/behavior/behavior-rules.ts

@@ -0,0 +1,128 @@
+import { json_value } from '#scripts/lib/json-value'
+import type { Block, TranscriptLine } from '#scripts/time-runtime/time-transcript-line'
+import type { Assertion, Finding } from './behavior-assertion'
+
+// The behavior assertions checked against recorded transcripts (joshuafolkken/kit#2365). This is the
+// **seed set** — the issue's own plan is to land one rule that is green across the recorded corpus,
+// then add more one at a time, each verified green before it joins. Starting with many would land a
+// wall of red that says nothing about which behavior actually regressed.
+
+const BASH_TOOL = 'Bash'
+const TOOL_USE = 'tool_use'
+const COMMAND_KEY = 'command'
+const FIRST_POSITION_OFFSET = 1
+const TOOL_RESULT = 'tool_result'
+const DENIED_BASH_PREFIX = 'Permission to use Bash with command '
+
+// The git subcommands that stage or rewrite the index — the ones `CLAUDE.md` reserves for `pnpm josh
+// git` under "Never stage or mutate the git index on your own". An agent that runs one directly has
+// overwritten the user's snapshot with a command the settings deny it.
+//
+// **The match is anchored at the start of a command segment, not searched anywhere in the string.** A
+// `grep '…git commit…'` or an `echo "git add"` mentions the words without running them, and searching
+// the whole command would read the mention as the act — the exact false positive that would turn a
+// run that only investigated git into a red gate. Splitting on the shell's own separators and
+// requiring the segment to *begin* with the mutation is what tells the command from the quotation.
+const SEGMENT_SEPARATOR = /[\n;&|]+/u
+const INDEX_MUTATION_HEAD = /^git\s+(?:commit|add|rm\s+--cached|restore\s+--staged)\b/u
+// `git add -n` / `--dry-run` stage nothing, so they are not a mutation — the one such command in the
+// recorded corpus is a `git add -n .` dry run, and reading it as a violation would fail the assertion
+// on a run that broke no rule. **`-n` means dry-run only where the subcommand defines it that way**:
+// for `add`/`rm` it is `--dry-run`, but for `git commit` `-n` is `--no-verify`, a real commit — so the
+// short flag is honored only after an `add`/`rm` head, while `--dry-run` is unambiguous everywhere.
+const DRY_RUN_LONG = /(?:^|\s)--dry-run(?:\s|$)/u
+const DRY_RUN_SHORT = /(?:^|\s)-n(?:\s|$)/u
+const DRY_RUN_SHORT_HEAD = /^git\s+(?:add|rm)\b/u
+
+function is_dry_run(segment: string): boolean {
+	if (DRY_RUN_LONG.test(segment)) return true
+
+	return DRY_RUN_SHORT_HEAD.test(segment) && DRY_RUN_SHORT.test(segment)
+}
+
+const INDEX_ASSERTION_NAME = 'no-direct-git-index-mutation'
+
+// The Bash command a tool-use block requested, or `undefined` for every other block — a text block,
+// a tool result, or a call to any tool but `Bash`. Read through `json_value.is_record` so a malformed
+// input is treated as absent rather than throwing mid-scan.
+function command_of(block: Block): string | undefined {
+	if (block.type !== TOOL_USE || block.name !== BASH_TOOL) return undefined
+	if (!json_value.is_record(block.input)) return undefined
+
+	const command = block.input[COMMAND_KEY]
+
+	return typeof command === 'string' ? command : undefined
+}
+
+// Whether any segment of a command directly mutates the index: it begins with a staging or commit
+// subcommand and is not a dry run. Each `;`/`&&`/`|`-separated segment is judged on its own, so a
+// mutation anywhere in a chain is caught while a mention inside another command's argument is not.
+function is_index_mutation(command: string): boolean {
+	return command
+		.split(SEGMENT_SEPARATOR)
+		.map((segment) => segment.trim())
+		.some((segment) => INDEX_MUTATION_HEAD.test(segment) && !is_dry_run(segment))
+}
+
+// An errored result alone may mean a command ran and failed. Only the permission layer's refusal
+// identifies a Bash call that never ran; the parser keeps the opening of that result's text.
+function is_denied_result(block: Block): boolean {
+	return (
+		block.type === TOOL_RESULT &&
+		block.result_id !== '' &&
+		block.is_error === true &&
+		block.error_text.startsWith(DENIED_BASH_PREFIX)
+	)
+}
+
+function denied_call_ids(lines: ReadonlyArray<TranscriptLine>): ReadonlySet<string> {
+	return new Set(
+		lines.flatMap((line) =>
+			line.blocks.filter((block) => is_denied_result(block)).map((block) => block.result_id),
+		),
+	)
+}
+
+// The direct index mutations one transcript line ran, each as a finding at that line's position. A
+// line is one assistant content block, so its position is a place a reader can open in the file.
+function line_mutations(
+	line: TranscriptLine,
+	index: number,
+	denied_ids: ReadonlySet<string>,
+): ReadonlyArray<Finding> {
+	return line.blocks
+		.filter((block) => !denied_ids.has(block.id))
+		.map((block) => command_of(block))
+		.filter((command): command is string => command !== undefined && is_index_mutation(command))
+		.map((command) => ({
+			assertion: INDEX_ASSERTION_NAME,
+			position: index + FIRST_POSITION_OFFSET,
+			detail: command,
+		}))
+}
+
+function scan_index_mutation(lines: ReadonlyArray<TranscriptLine>): ReadonlyArray<Finding> {
+	const denied_ids = denied_call_ids(lines)
+
+	return lines.flatMap((line, index) => line_mutations(line, index, denied_ids))
+}
+
+const index_mutation_assertion: Assertion = {
+	name: INDEX_ASSERTION_NAME,
+	describe: 'git staging or commit must go through `pnpm josh git`, never a direct git call',
+	scan: scan_index_mutation,
+}
+
+// The seed set: every rule green across the recorded corpus today. A new rule is appended here only
+// after it has been verified green against past real runs.
+const ALL_ASSERTIONS: ReadonlyArray<Assertion> = [index_mutation_assertion]
+
+const behavior_rules = {
+	ALL_ASSERTIONS,
+	INDEX_ASSERTION_NAME,
+	command_of,
+	index_mutation_assertion,
+	is_index_mutation,
+}
+
+export { behavior_rules }

package/scripts/build/build-bin.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const ENTRY_POINT = path.join(PACKAGE_DIR, 'scripts', 'josh', 'josh.ts')
+const OUTFILE = path.join(PACKAGE_DIR, 'dist', 'josh.js')
+const NODE_BANNER = '#!/usr/bin/env node'
+
+async function build_bin(): Promise<void> {
+	await build({
+		entryPoints: [ENTRY_POINT],
+		outfile: OUTFILE,
+		bundle: true,
+		platform: 'node',
+		format: 'esm',
+		target: 'node22',
+		packages: 'external',
+		banner: { js: NODE_BANNER },
+	})
+}
+
+async function main(): Promise<void> {
+	try {
+		await build_bin()
+		console.info(`  ✔ ${OUTFILE} built`)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_bin, NODE_BANNER, OUTFILE }

package/scripts/build/build-claude-md.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env tsx
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { init_logic } from '#scripts/init/init-logic'
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = path.resolve(SCRIPT_DIR, '..', '..')
+const SOURCE_CLAUDE_MD = path.join(REPO_ROOT, 'CLAUDE.md')
+const DIST_CLAUDE_MD = path.join(REPO_ROOT, 'dist', 'CLAUDE.md')
+
+// Read kit's own CLAUDE.md and apply the distribution path transform. kit's source keeps relative
+// paths so it resolves inside the kit repository; the published copy rewrites them so every backtick
+// reference resolves in a consumer too (joshuafolkken/kit#1878). Pure — the guard test asserts the
+// result carries no reference a consumer cannot open.
+function generate_distributed_claude_md(): string {
+	return init_logic.transform_distributed_paths(readFileSync(SOURCE_CLAUDE_MD, 'utf8'))
+}
+
+// Ship the transformed CLAUDE.md from dist/, like every other build artifact: gitignored, but carried
+// into the package by the `files` array, so a consumer imports it at
+// node_modules/@joshuafolkken/kit/dist/CLAUDE.md.
+function build_claude_md(): string {
+	mkdirSync(path.dirname(DIST_CLAUDE_MD), { recursive: true })
+	writeFileSync(DIST_CLAUDE_MD, generate_distributed_claude_md())
+
+	return DIST_CLAUDE_MD
+}
+
+function main(): void {
+	console.info(`  ✔ ${build_claude_md()} built`)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export {
+	build_claude_md,
+	generate_distributed_claude_md,
+	SOURCE_CLAUDE_MD,
+	DIST_CLAUDE_MD,
+	REPO_ROOT,
+}

package/scripts/build/build-config-merge.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { build_library, library_paths } from './build-library'
+
+const CONFIG_MERGE_LIBRARY = 'config-merge'
+const { outfile: CONFIG_MERGE_OUTFILE, dts_file: CONFIG_MERGE_DTS_FILE } =
+	library_paths(CONFIG_MERGE_LIBRARY)
+
+async function build_config_merge_library(): Promise<void> {
+	await build_library(CONFIG_MERGE_LIBRARY)
+}
+
+async function main(): Promise<void> {
+	try {
+		await build_config_merge_library()
+		console.info(`  ✔ ${CONFIG_MERGE_OUTFILE} built`)
+		console.info(`  ✔ ${CONFIG_MERGE_DTS_FILE} built`)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_config_merge_library, CONFIG_MERGE_OUTFILE, CONFIG_MERGE_DTS_FILE }