@joshuafolkken/kit 1.872.0

package/scripts/hooks/pre-push-unit.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { gate_skip } from '#scripts/gate/gate-skip'
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { hook_gate_reuse } from '#scripts/gate/hook-gate-reuse'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { test_unit_guard } from '#scripts/test/test-unit-guard'
+
+// The pre-push hook's unit run, which no longer re-runs a suite a green gate already covers
+// (joshuafolkken/kit#1334).
+//
+// Measured on joshuafolkken/kit#1326: `pnpm josh git -y` took 40 seconds, 15.9 of them the pre-push
+// `vitest run` — started 40 seconds after `pnpm josh gate` had printed all four checks green on that
+// same tree, with nothing edited in between. The gate had written the record down and the hook was
+// the one reader that never looked at it.
+//
+// **The decision is joshuafolkken/kit#1328's, imported rather than restated.** "There is a green
+// record and nothing it covers has moved" is one question, and a hook answering it differently from
+// the gate beside it would be two commands disagreeing about the same tree — the clone `CLAUDE.md`
+// prohibits. So `gate_skip.reusable_green_gate` decides all three of its conditions here too: the
+// file map matches, the **base commit** the map is a diff against matches, and the map is non-empty.
+//
+// **What this hook shares with the pre-commit type check is `hook-gate-reuse.ts`**
+// (joshuafolkken/kit#1381): the escape hatch, the pre-filter in front of the record and the one
+// `git status` reading both narrow themselves from. Only the narrowing itself is written here, because
+// only it is about a push.
+//
+// **What this adds is one condition, and it only ever narrows.** A commit changes nothing outside
+// this checkout; a push puts code where other people and CI read it, so an unverified commit reaching
+// the remote is the failure this must not have. The gate's record describes the **working tree**, and
+// a push carries **HEAD** — the same thing only while nothing is uncommitted. Commit half of a green
+// tree and the map still matches while the commit being pushed is a tree no check ever read. So the
+// reuse also requires a clean working tree, which is exactly what `josh git` leaves behind when it
+// commits before pushing, and any doubt whatever sends the hook back to the full suite.
+//
+// **`audit` is untouched.** The gate does not run it, so it is not a duplicate of anything.
+
+// The escape hatch's name; the shared reading of it is `hook_gate_reuse.is_force_requested`.
+const FORCE_ENV = 'JOSH_PRE_PUSH_FORCE'
+
+// The gate's own two readings — the changed-file map and the commit it is a diff against, taken from
+// `gate-tree.ts` rather than read a second way here — plus the one this hook adds.
+interface PushTree extends GateTree {
+	is_clean: boolean
+}
+
+// `git status --porcelain` prints one line per difference from HEAD, untracked files included — so an
+// empty output is the whole of "what this push carries is what the record was taken from". Untracked
+// files count: the gate's map covers them, and one left behind is content the record was green on
+// that the pushed commit does not have. An unreadable status fails toward running the suite, like
+// every other read here.
+//
+// The readings are independent, so they are started together rather than one after the other.
+async function read_push_tree(): Promise<PushTree> {
+	const [tree, lines] = await Promise.all([
+		gate_tree.read_gate_tree(),
+		hook_gate_reuse.read_status_lines(),
+	])
+
+	return { ...tree, is_clean: hook_gate_reuse.is_worktree_clean(lines) }
+}
+
+// `--force` is the gate's own flag, reused rather than respelled: it and `JOSH_PRE_PUSH_FORCE` are
+// one instruction in the two places a person gives it — typing the command, and pushing through the
+// hook, whose line carries no flags of its own. It is consumed here rather than forwarded, because
+// vitest would refuse it.
+function forwarded_arguments(extra_arguments: ReadonlyArray<string>): ReadonlyArray<string> {
+	return extra_arguments.filter((argument) => argument !== gate_skip.FORCE_FLAG)
+}
+
+// The stamp rather than a boolean, for the same reason `gate_skip` hands one back: the caller prints
+// `taken_at`, and a record that does not describe this tree has no timestamp worth printing.
+//
+// **Any argument at all refuses the reuse**, not only `--force`. Everything else is forwarded to
+// vitest, and a caller who narrowed the run to one spec asked for that run rather than for a
+// recorded result about a whole tree. The hook's own line passes none, so this costs it nothing.
+function reusable_green_push(
+	tree: PushTree,
+	extra_arguments: ReadonlyArray<string>,
+	source?: string,
+): FileMapStamp | undefined {
+	return hook_gate_reuse.reusable_green_hook({
+		tree,
+		is_tree_carried: tree.is_clean,
+		extra_arguments,
+		force_env: FORCE_ENV,
+		source,
+	})
+}
+
+// **The sentence claims the result, never merely the omission.** "unit tests skipped" reads as "not
+// verified", which is the one thing this line must not be mistaken for while the push it precedes
+// goes on to the remote. So it says what passed, on which tree, when, and how to run it anyway — in
+// the one sentence every reader of the record shares (joshuafolkken/kit#1381).
+function format_skip(taken_at: string): string {
+	return gate_skip.format_reuse_notice({
+		subject: 'the unit tests',
+		carried_clause: ', and this push carries that same tree',
+		taken_at,
+		force_hint: `${FORCE_ENV}=1 git push`,
+		rerun_object: 'them',
+	})
+}
+
+// The suite is run through the guard `josh test:unit` uses rather than a bare `vitest run`, so a
+// project with no vitest prints a skip notice instead of failing the push — the behavior the hook's
+// other commands already have. **A project that has vitest and no test file at all fails the push
+// instead** (joshuafolkken/kit#1224): the guard treats that half as a broken state rather than a
+// young project, and the hook returns what the guard returns.
+async function run_pre_push_unit(
+	extra_arguments: ReadonlyArray<string> = [],
+	source?: string,
+): Promise<number> {
+	const reusable = reusable_green_push(await read_push_tree(), extra_arguments, source)
+
+	if (reusable === undefined) {
+		return await test_unit_guard.run_guarded_unit(
+			process.cwd(),
+			forwarded_arguments(extra_arguments),
+		)
+	}
+
+	process.stdout.write(`${format_skip(reusable.taken_at)}\n`)
+
+	return 0
+}
+
+// `process.exitCode` rather than `process.exit()`: a non-zero code has to block the push, and exiting
+// outright truncates a piped stdout — which for a failing suite is the output that says why.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	// `process.argv` is [runner, script, ...arguments].
+	const FIRST_ARGUMENT_INDEX = 2
+
+	process.exitCode = await run_pre_push_unit(process.argv.slice(FIRST_ARGUMENT_INDEX))
+}
+
+const pre_push_unit = {
+	FORCE_ENV,
+	format_skip,
+	forwarded_arguments,
+	read_push_tree,
+	reusable_green_push,
+	run_pre_push_unit,
+}
+
+export { pre_push_unit }

package/scripts/hooks/pretool-guard.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
+import { investigation_refusal } from '#scripts/delegation/investigation-guard'
+import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
+import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
+import { batch_outcome } from './batch-guard'
+
+// One PreToolUse process for the three guards that used to be three (joshuafolkken/kit#1930). A Bash
+// call used to spawn `batch:guard`, `investigation:guard` and `rule:guard` separately — three pnpm
+// launches on top of the tool call — while consumers paid that thrice on every guarded call. The
+// three share one shell (`hook-decision.ts`): the same payload schema, the same deny envelope, the
+// same `.env` load. So the consolidation is a composition, not a rewrite — each guard's own
+// `refusal` / `outcome` is called, unchanged, on the one payload this process reads.
+//
+// **The verdict is identical to running the three in turn**, and that is the whole point. Each guard
+// self-gates on the tool name inside its own `is_candidate` / trigger, so running all three on the
+// union matcher (`Bash|Edit|Read|Write|AskUserQuestion`) refuses exactly what the three separate
+// entries did — `AskUserQuestion` is matched for the rule guard's lane-child interactive-ask row
+// (joshuafolkken/kit#2201), and the batching and investigation guards self-gate away from it. A
+// refusal from any guard wins first; only when none refuses is the batch guard's non-blocking notice
+// (the whole-file-write notice, joshuafolkken/kit#1848) emitted. Each guard still honours its own
+// switch (`JOSH_BATCH_GUARD` / `JOSH_INVESTIGATION_GUARD` / `JOSH_RULE_GUARD`) internally, so this
+// process needs no switch of its own.
+
+// Fold the guards' verdicts into one. A refusal wins over everything else, and the batch guard's
+// reason is shown first to match the entry order the separate hooks had. When nothing refuses,
+// whatever the batch guard reported (a notice, a fault, or nothing) passes through untouched.
+function combine_outcomes(batch: GuardOutcome, extra_reason: string | undefined): GuardOutcome {
+	if (batch.reason !== undefined) return batch
+
+	if (extra_reason !== undefined) {
+		return { reason: extra_reason, notice: undefined, fault: undefined }
+	}
+
+	return batch
+}
+
+function is_clear(outcome: GuardOutcome): boolean {
+	return outcome.reason === undefined && outcome.notice === undefined && outcome.fault === undefined
+}
+
+// The duplicate-read guard is `notice`-mode in a lane child, so it is the second guard that can raise a
+// non-refusal notice (joshuafolkken/kit#2298). Its notice is surfaced only where nothing else spoke —
+// a refusal from any guard, or the batch guard's own notice, wins first.
+function with_duplicate_notice(combined: GuardOutcome, notice: string | undefined): GuardOutcome {
+	if (notice === undefined || !is_clear(combined)) return combined
+
+	return { reason: undefined, notice, fault: undefined }
+}
+
+// All guards run unconditionally, exactly as the separate PreToolUse entries did: each records its own
+// once-per-run stamp, so short-circuiting on the first refusal would change which guard is allowed to
+// fire on a later call.
+function pretool_outcome(raw_payload: string): GuardOutcome {
+	const batch = batch_outcome(raw_payload)
+	const investigation = investigation_refusal(raw_payload)
+	const duplicate = duplicate_read_outcome(raw_payload)
+	const rule = delivered_rules.delivery(raw_payload)
+	const duplicate_refusal = duplicate.reason
+	const combined = combine_outcomes(batch, investigation ?? duplicate_refusal ?? rule)
+
+	return with_duplicate_notice(combined, duplicate.notice)
+}
+
+// The watcher guard is the one composed rule that cannot answer synchronously — it reads the lane
+// registry and the watcher's life record off disk (joshuafolkken/kit#2353). So it is asked after the
+// synchronous guards and only where they stayed clear: a refusal from any of them wins first, exactly
+// as `combine_outcomes` orders them, and the watcher's refusal fills a clear verdict rather than
+// overriding one. It fires once per run itself (`run-watcher-hook.ts`), so a stale watcher refuses the
+// first call but not the `pnpm josh run:progress --wait` that fixes it.
+async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {
+	const base = pretool_outcome(raw_payload)
+
+	if (!is_clear(base)) return base
+
+	const reason = await run_watcher_hook.watcher_hook_reason(raw_payload)
+
+	return reason === undefined ? base : { reason, notice: undefined, fault: undefined }
+}
+
+const pretool_guard = { combine_outcomes, pretool_outcome, pretool_outcome_async }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
+	else {
+		const raw_payload = await text(process.stdin)
+
+		hook_decision.load_environment_file()
+		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
+	}
+}
+
+export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/hooks/prevent-main-commit.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+
+interface CheckResult {
+	success: boolean
+	message: string
+}
+
+async function check_main_branch(): Promise<CheckResult> {
+	const current_branch = await git_command.branch()
+	const default_branch = await git_command.get_default_branch()
+
+	if (current_branch === default_branch) {
+		return {
+			success: false,
+			message:
+				`🚫 Error: Direct commits to main branch are not allowed\n` +
+				`   Please create a new branch and commit there:\n` +
+				`   git checkout -b feature/your-feature-name\n`,
+		}
+	}
+
+	return { success: true, message: `✅ Branch check passed: '${current_branch}'` }
+}
+
+async function main(): Promise<void> {
+	const result = await check_main_branch()
+
+	console.info(result.message)
+
+	if (!result.success) process.exit(1)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { check_main_branch }
+export type { CheckResult }

package/scripts/hooks/prompt-hooks.ts

@@ -0,0 +1,38 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// The `UserPromptSubmit` hook commands declared in a `.claude/settings.json`
+// (joshuafolkken/kit#1151).
+//
+// What these commands echo is injected into **every** user turn and then re-read as accumulated
+// context on every turn after it, which is why joshuafolkken/kit#967 put a ceiling on their size and
+// why `josh cost` names them in the resident breakdown. Two readers, one parser: the suite that
+// enforces the ceiling and the report that prices it must agree on what is being measured, or the
+// ceiling guards a quantity the report does not show.
+
+const HOOK_SCHEMA = z.object({ command: z.string().nullish() })
+const MATCHER_SCHEMA = z.object({ hooks: z.array(HOOK_SCHEMA).nullish() })
+const SETTINGS_SCHEMA = z.object({
+	hooks: z
+		.object({
+			UserPromptSubmit: z.array(MATCHER_SCHEMA).nullish(),
+		})
+		.nullish(),
+})
+
+// An unreadable or hook-less settings file yields no commands rather than throwing: a consumer
+// project may have neither, and `josh cost` must still print a breakdown there.
+function user_prompt_hook_commands(settings_text: string): Array<string> {
+	const parsed = SETTINGS_SCHEMA.safeParse(json_value.parse_or_undefined(settings_text))
+	const matchers = parsed.success ? (parsed.data.hooks?.UserPromptSubmit ?? []) : []
+
+	return matchers.flatMap((matcher) =>
+		(matcher.hooks ?? []).flatMap((hook) =>
+			typeof hook.command === 'string' ? [hook.command] : [],
+		),
+	)
+}
+
+const prompt_hooks = { user_prompt_hook_commands }
+
+export { prompt_hooks }

package/scripts/hooks/reserved-run.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { core_budget } from '#scripts/gate/core-budget'
+import { unit_worker_share } from '#scripts/test/unit-worker-share'
+import { execa } from 'execa'
+
+// Runs a command while holding a place in the machine-wide core budget (joshuafolkken/kit#2351).
+//
+// **The pre-push hook's `pnpm install` and `pnpm josh audit` are heavy and were outside the ledger.**
+// The gate's checks reserve their cores, but a lefthook `pre-push` fires `pnpm install` on every push
+// (`josh bump` rewrites `package.json` right before it) and runs `josh audit` beside it — and eight
+// lanes reach that push around the same time, so the two spiked a machine the gate thought it had to
+// itself. Wrapping each command here counts it: it claims a place before it starts and waits while the
+// budget is full, exactly as a gate check does, so a concurrent gate on another lane backs off for it.
+//
+// **It is one wrapper for both rather than a reservation written into each command.** The audit scans
+// synchronously and the install is pnpm's, so neither can hold an async reservation itself without
+// being rewritten around it — and a second copy of the claim-run-release dance is the clone
+// `CLAUDE.md` prohibits. The weight is the caller's, passed on the command line beside the command, so
+// the reservation these two conservative numbers stand for lives at the one place a person reads them.
+
+// `process.argv` is [runner, script, ...arguments].
+const FIRST_ARGUMENT_INDEX = 2
+// The token separating the reserved weight from the command it guards, so a command carrying flags of
+// its own is never mistaken for this wrapper's arguments.
+const COMMAND_SEPARATOR = '--'
+const WEIGHT_INDEX = 0
+const FAIL_EXIT_CODE = 1
+// A reservation claims at least one core; a zero or negative weight would subtract from the ledger's
+// cumulative sum and let a later reservation admit past the budget the ledger exists to hold.
+const MIN_WEIGHT = 1
+
+interface ReservedCommand {
+	weight: number
+	command: ReadonlyArray<string>
+}
+
+// `<weight> -- <command> [args...]`. `undefined` is a usage error: a missing separator, a weight that
+// is not an integer of at least one core, or nothing to run.
+function parse_arguments(argv: ReadonlyArray<string>): ReservedCommand | undefined {
+	const NOT_FOUND = -1
+	const separator = argv.indexOf(COMMAND_SEPARATOR)
+	const weight = Number(argv[WEIGHT_INDEX])
+	const is_valid_weight = Number.isSafeInteger(weight) && weight >= MIN_WEIGHT
+
+	if (separator === NOT_FOUND || !is_valid_weight) return undefined
+
+	const command = argv.slice(separator + 1)
+
+	return command.length > 0 ? { weight, command } : undefined
+}
+
+// `stdio: 'inherit'` so the command's own progress reaches the push, and `reject: false` so a failing
+// command becomes an exit code the caller returns rather than a throw — the reservation is released by
+// `with_core_reservation`'s `finally` on either path.
+async function run_command(command: ReadonlyArray<string>): Promise<number> {
+	const [file, ...args] = command
+	const result = await execa(file ?? '', args, { stdio: 'inherit', reject: false })
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+async function run_reserved(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = parse_arguments(argv)
+
+	if (parsed === undefined) {
+		process.stderr.write('reserved-run: usage: reserved-run <weight> -- <command> [args...]\n')
+
+		return FAIL_EXIT_CODE
+	}
+
+	// **A command already inside a gate's unit suite takes no place, for the reason a nested gate does
+	// not** (joshuafolkken/kit#2351): this repository's own gate tests exercise the wrapper, and a place
+	// claimed there would wait on cores the outer gate is holding. In its real use — the pre-push hook —
+	// nothing has set the marker, so the reservation is taken.
+	if (unit_worker_share.is_nested_run()) return await run_command(parsed.command)
+
+	return await core_budget.with_core_reservation(
+		parsed.weight,
+		async () => await run_command(parsed.command),
+	)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_reserved(process.argv.slice(FIRST_ARGUMENT_INDEX))
+}
+
+const reserved_run = { parse_arguments, run_command, run_reserved }
+
+export { reserved_run }

package/scripts/hooks/stop-guard.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { backlog_ready } from '#scripts/backlog/backlog-ready'
+import { backlog_stalled_detect } from '#scripts/backlog/backlog-stalled-detect'
+import { repo_party } from '#scripts/discovery/repo-party'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { session_language } from '#scripts/josh/session-language'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { filing_cap } from '#scripts/rules/filing-cap'
+import { lane_park } from '#scripts/rules/lane-park'
+import { stop_rules, type StopContext, type StopOutcome } from '#scripts/rules/stop-rules'
+import { run_cut } from '#scripts/run/run-cut'
+import { run_headless } from '#scripts/run/run-headless'
+import { run_hold } from '#scripts/run/run-hold'
+import { run_stranded_detect } from '#scripts/run/run-stranded-detect'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
+
+// The `Stop` hook entry: one process that delivers the three stop-time rules (joshuafolkken/kit#2121).
+// It is the stop-time counterpart of `pretool-guard.ts` — a second entry on the same `hook_decision`
+// foundation, not a second copy of it.
+//
+// **Every failure allows the stop.** A missing transcript, an unreadable hold record, a git status
+// that will not read — each ends as "no block", for the same reason the PreToolUse guard fails open:
+// a hook that failed closed would wedge a run over its own plumbing. The block rules are self-
+// resolving (send the notify, release the hold) and `stop_hook_active` is the backstop, so failing
+// open here costs at most a missed nudge, never a stuck run.
+
+// The hold record for this working tree is still in place. `unreadable` reads as absent: the safe
+// direction for a stop guard is not to block, and an unreadable record is not proof a run is holding.
+async function is_hold_present(): Promise<boolean> {
+	const directory = await run_hold.worktree_directory()
+
+	if (directory === undefined) return false
+
+	const read = run_hold.read_hold(run_hold.hold_path(directory))
+
+	return read.kind === 'held' || read.kind === 'stale'
+}
+
+// A `confirmation` notify sits on this run's transcript tail. The tail is derived exactly as the
+// PreToolUse guards derive it, and the judgement is `lane-park`'s, reused rather than re-spelled.
+function transcript_tail(transcript_path: string): string {
+	const transcript = time_hook_transcript.transcript_of(transcript_path, undefined)
+
+	return time_density_hook.read_tail(transcript)
+}
+
+// An Issue was filed on this turn — the tail from the last prompt on. The count is `filing_cap`'s, so a
+// filing a guard refused is not counted, and one an earlier turn made does not stand this turn down.
+function was_filed(tail: string): boolean {
+	return filing_cap.turn_filing_count(tail) > 0
+}
+
+// The session language the refusal is written for — `write_stop_decision` has already loaded the `.env`.
+function session_lang(): string {
+	return session_language.resolve_session_lang().lang
+}
+
+async function build_context(
+	transcript_path: string,
+	payload_tail: { stop_hook_active: boolean; message: string },
+): Promise<StopContext> {
+	const tail = transcript_tail(transcript_path)
+
+	return {
+		hold_present: await is_hold_present(),
+		tree_clean: !(await run_hold.is_tree_dirty()),
+		notified: lane_park.mentions_confirmation_notify(tail),
+		message: payload_tail.message,
+		stop_hook_active: payload_tail.stop_hook_active,
+		cut_pending: run_cut.carried_cut_sync() !== undefined,
+		filed: was_filed(tail),
+		session_owner: repo_party.current_owner(),
+		headless_waiting: await run_headless.must_keep_waiting(),
+		headless_refusals: stop_rules.count_headless_refusals(tail),
+		lane_child: lane_child_marker.is_child_of(process.cwd()),
+		session_lang: session_lang(),
+	}
+}
+
+async function stop_outcome_for_payload(raw_payload: string): Promise<StopOutcome> {
+	const payload = stop_rules.parse_stop_payload(raw_payload)
+
+	if (payload === undefined || !stop_rules.is_enabled()) return stop_rules.NO_OUTCOME
+
+	const context = await build_context(payload.transcript_path, {
+		stop_hook_active: payload.stop_hook_active ?? false,
+		message: payload.last_assistant_message ?? '',
+	})
+
+	return stop_rules.stop_outcome(context)
+}
+
+async function outcome_of(raw_payload: string): Promise<StopOutcome> {
+	try {
+		return await stop_outcome_for_payload(raw_payload)
+	} catch {
+		return stop_rules.NO_OUTCOME
+	}
+}
+
+// Nothing reaches stdout on an ordinary stop, so what the harness parses stays empty unless the stop
+// is being held — all three rules block, so a bare `#N` is reported the same way (joshuafolkken/kit#2247).
+async function write_stop_decision(raw_payload: string): Promise<void> {
+	hook_decision.load_environment_file()
+
+	// The stall check rides the Stop hook because the stop *is* the loop boundary: a run alive but not
+	// advancing ends turns without dispatching (joshuafolkken/kit#2359). It only reports — leaves a
+	// marker, sends a notification — and swallows its own failures, so it can never change the decision
+	// below or hold the stop.
+	await backlog_stalled_detect.run_stall_check(backlog_ready.DEFAULT_PORTS)
+
+	// The strand check rides the same boundary for the same reason, and is the step before the stall
+	// (joshuafolkken/kit#2375): the stall detector needs a live driver that could dispatch, and this one
+	// fires when that driver is gone — the budget handed off, the owner dead, no supervisor watching. It
+	// too only reports and swallows its own failures, so it never touches the stop decision below.
+	await run_stranded_detect.run_stranded_check()
+
+	const { reason } = await outcome_of(raw_payload)
+
+	if (reason === undefined) return
+
+	process.stdout.write(`${stop_rules.block_envelope(reason, session_lang())}\n`)
+}
+
+const stop_guard = { outcome_of, stop_outcome_for_payload }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('stop:guard')
+	else await write_stop_decision(await text(process.stdin))
+}
+
+export { stop_guard, write_stop_decision }

package/scripts/init/claude-plugin-config.ts

@@ -0,0 +1,51 @@
+import path from 'node:path'
+import { init_logic_json_merge } from './init-logic-json-merge'
+
+// The Claude Code plugin that ships kit's distributed skills (joshuafolkken/kit#1879). A consumer no
+// longer receives the five skill directories as a byte copy under its own `.claude/skills/`; it
+// receives this marketplace and plugin declaration in its `.claude/settings.json`, and the skills
+// load from the package as `kit:<name>`.
+const MARKETPLACE_NAME = 'kit'
+const PLUGIN_ID = 'kit@kit'
+// Relative to the consumer's project root, where `@joshuafolkken/kit` is installed. An absolute path
+// would be correct only on the machine it was written on, so it has to stay relative; the `./`
+// prefix keeps `claude plugin marketplace add` from reading it as a GitHub `owner/repo` shorthand.
+const MARKETPLACE_PATH = './node_modules/@joshuafolkken/kit'
+const CLAUDE_SETTINGS_DESTINATION = path.join('.claude', 'settings.json')
+
+// `enabledPlugins` declares the plugin; `extraKnownMarketplaces` says where to find it. The CLI does
+// not auto-install from these alone — a consumer runs `claude plugin install kit@kit` once — so the
+// declaration is what makes that one command resolve without further arguments.
+const PLUGIN_SETTINGS: Record<string, unknown> = {
+	extraKnownMarketplaces: {
+		[MARKETPLACE_NAME]: { source: { source: 'directory', path: MARKETPLACE_PATH } },
+	},
+	enabledPlugins: { [PLUGIN_ID]: true },
+}
+
+function inject_plugin_config(content: string): string {
+	return init_logic_json_merge.merge_json_object(content, PLUGIN_SETTINGS)
+}
+
+// Only the consumer's `.claude/settings.json` receives the plugin block. kit's own settings file is
+// never transformed in place — kit loads the skills locally from `.claude/skills/`, so enabling the
+// plugin in kit would double-load every skill (`kit:workflow-commands` beside the local
+// `workflow-commands`). The check is against the copied file's destination, which is why it runs in
+// the copy transform rather than against kit's source tree.
+function apply_plugin_config_for_destination(destination_path: string, content: string): string {
+	return destination_path.endsWith(CLAUDE_SETTINGS_DESTINATION)
+		? inject_plugin_config(content)
+		: content
+}
+
+const claude_plugin_config = {
+	MARKETPLACE_NAME,
+	PLUGIN_ID,
+	MARKETPLACE_PATH,
+	CLAUDE_SETTINGS_DESTINATION,
+	PLUGIN_SETTINGS,
+	inject_plugin_config,
+	apply_plugin_config_for_destination,
+}
+
+export { claude_plugin_config }