@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/josh/hook-decision.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
@@ -5,10 +6,10 @@ import { z } from 'zod'
 import { josh_environment_file } from './josh-environment-file'
 import { stamp_file } from './stamp-file'
 
-// The parts every refusing `PreToolUse` hook needs, held once (joshuafolkken/kit#1460).
+// The parts every refusing `PreToolUse` hook needs, held once.
 //
 // **It exists because the second such hook arrived.** `batch-guard.ts` was the first
-// (joshuafolkken/kit#1390) and carried the whole shell itself: the payload schema, the envelope
+//  and carried the whole shell itself: the payload schema, the envelope
 // Claude Code understands, the environment switch, and the stamp that makes a refusal
 // unrepeatable. The investigation guard needs all four unchanged and only its *rule* differs, so
 // copying them across would be the clone `CLAUDE.md` prohibits — and a rule fixed in one copy and
@@ -20,7 +21,7 @@ import { stamp_file } from './stamp-file'
 // Only the four fields a `PreToolUse` hook is handed and reads. Claude Code names the tool it is
 // about to run beside a transcript path, so nothing is searched for.
 //
-// **`agent_id` is what makes a delegated unit answerable with its own file** (joshuafolkken/kit#1424).
+// **`agent_id` is what makes a delegated unit answerable with its own file**.
 // The path in the payload is the *parent* session's whichever agent issued the call, so without this
 // field a guard judges the parent's frozen timeline and refuses nothing at all inside a fork.
 const payload_schema = z.object({
@@ -58,7 +59,7 @@ function is_switch_enabled(key: string): boolean {
 // The opt-in counterpart of `DISABLED_VALUES`: an unset variable stays off, and only one of these
 // spellings turns the switch on. A switch that must default off cannot be read with `is_switch_enabled`
 // — that one defaults on — so the value list is spelled out here rather than inverted at the call site,
-// keeping a typo from silently enabling what was meant to stay disabled (joshuafolkken/kit#2370).
+// keeping a typo from silently enabling what was meant to stay disabled.
 const ENABLED_VALUES: ReadonlyArray<string> = ['on', '1', 'true', 'yes']
 
 // Read at call time for the same reason as `is_switch_enabled`, so a suite that switches the variable
@@ -85,7 +86,7 @@ function deny_envelope(reason: string): string {
 	})
 }
 
-// **A rewrite, not a refusal** (joshuafolkken/kit#3154): the call proceeds with `updated_input` merged
+// **A rewrite, not a refusal**: the call proceeds with `updated_input` merged
 // over its own. `allow` is the decision the harness applies an `updatedInput` under; a settings `deny`
 // rule still wins over it, so this never widens what the call may do.
 function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
@@ -126,7 +127,7 @@ function stamp_fault(switch_key: string): string {
 // anything is written under it, so a fork's first guarded calls read a path with no file behind it —
 // `time-hook-transcript.ts` states that "no history" is the honest verdict there. Reported as a fault
 // it would print on every early call of every fork, which is the routine case drowning the signal this
-// exists to raise (joshuafolkken/kit#1509).
+// exists to raise.
 function is_missing_file(error: unknown): boolean {
 	if (!(error instanceof Error) || !('code' in error)) return false
 
@@ -168,11 +169,7 @@ function last_refusal_ms(target: string): number {
 
 	if (raw === undefined) return NEVER_MS
 
-	try {
-		return refusal_schema.parse(JSON.parse(raw)).refused_at_ms
-	} catch {
-		return NEVER_MS
-	}
+	return json_value.parse_with(raw, refusal_schema)?.refused_at_ms ?? NEVER_MS
 }
 
 function record_refusal(target: string, now_ms: number): boolean {
@@ -199,7 +196,7 @@ function create_refusal_stamp(prefix: string): RefusalStamp {
 // **`.env` is loaded here rather than through the dispatcher's `tsx_arguments`**, and the reason —
 // declaring any `tsx_arguments` disqualifies a command from in-process dispatch — is now shared with
 // every other command that has to stay in-process, so the loader lives in `josh-environment-file.ts` rather
-// than here (joshuafolkken/kit#1491). Re-exported under this namespace because that is where the
+// than here. Re-exported under this namespace because that is where the
 // hooks reach for it.
 //
 // **Call it only on the real hook path**, never inside the pure refusal function, so a developer's
@@ -217,7 +214,7 @@ interface GuardRun {
 }
 
 // The notice half of a guard's rule, kept optional so a guard that only refuses supplies nothing and is
-// untouched (joshuafolkken/kit#1848). The investigation guard omits it; the batching guard supplies one
+// untouched. The investigation guard omits it; the batching guard supplies one
 // for the whole-file write, which it cannot refuse but can advise.
 interface NotifySpec {
 	// This disposition's record prefix, distinct from the refusal's so the two dedupe independently and
@@ -226,8 +223,8 @@ interface NotifySpec {
 	// The same shape as `should_block`, asked of the tail for a notify-only call. `notified_at_ms` is
 	// this disposition's own last-fired instant, never the refusal's.
 	should_notify: (tail: string, call: GuardedCall, notified_at_ms: number, run: GuardRun) => boolean
-	// The non-blocking text handed to `notice_envelope`, chosen from the call and the tail
-	// (joshuafolkken/kit#2164, joshuafolkken/kit#2276). A guard now notifies about more than one kind of
+	// The non-blocking text handed to `notice_envelope`, chosen from the call and the tail.
+	// A guard now notifies about more than one kind of
 	// call — the whole-file write it cannot refuse, and, in a lane child, a refusable call whose refusal
 	// is downgraded to a notice — and the two want different wording, so the text is a function of the
 	// call. It is handed the tail as well so a notice can name the concrete calls the run just issued
@@ -252,18 +249,18 @@ interface TranscriptGuardSpec {
 	should_block: (tail: string, call: GuardedCall, refused_at_ms: number, run: GuardRun) => boolean
 	// What the model is told. The deny reason is the only text that reaches it.
 	reason: string
-	// **The optional notice disposition** (joshuafolkken/kit#1848). Supplied, it lets a guard emit a
+	// **The optional notice disposition**. Supplied, it lets a guard emit a
 	// non-blocking notice for a call it does not refuse. Its record lives under a prefix of its own.
 	notify?: NotifySpec
 }
 
-// What one hook invocation decided. **`fault` is the half that did not exist** (joshuafolkken/kit#1509):
+// What one hook invocation decided. **`fault` is the half that did not exist**:
 // every failure still allows the call, but a failure that nobody can see is indistinguishable from a
 // run that was batching properly — so the guard could be dead for two hours and read as satisfied.
 // `reason` refuses; `fault` allows and says so.
 interface GuardOutcome {
 	reason: string | undefined
-	// **A notice, not a refusal** (joshuafolkken/kit#1848). Set where a notify-only call — a whole-file
+	// **A notice, not a refusal**. Set where a notify-only call — a whole-file
 	// write — reached the limit; the call still proceeds, and `notice_envelope` carries this to the
 	// model and the person with no `permissionDecision`. Never set together with `reason`: the block
 	// path decides first and returns before the notice path is asked.
@@ -287,7 +284,7 @@ interface FireResult {
 
 // The three the guard closes over: the spec, and one record per disposition. Bundled so the functions
 // below stay within the parameter limit, and so a further disposition adds a field rather than a
-// parameter to every one of them (joshuafolkken/kit#1848).
+// parameter to every one of them.
 interface GuardParts {
 	spec: TranscriptGuardSpec
 	stamp: RefusalStamp
@@ -306,7 +303,7 @@ interface GuardContext extends GuardParts {
 // cannot repeat on the call in hand. **Recording before firing is what makes a refusal unrepeatable**,
 // so a disposition that cannot record does not fire — it reports the fault instead of risking the
 // wedge, which is the half `scripts/hooks/batch-guard.ts` names. Shared by the refusal and the notice so the
-// arm-then-fire order is written once (joshuafolkken/kit#1848).
+// arm-then-fire order is written once.
 function fire_once(
 	stamp: RefusalStamp,
 	run: GuardRun,
@@ -367,7 +364,7 @@ function guard_reason_for_payload(
 	if (!parts.spec.is_candidate(call)) return NO_OUTCOME
 
 	// A hook firing inside a delegated unit is handed the *parent's* path, so the fork's own file is
-	// derived here rather than judged from the parent's frozen timeline (joshuafolkken/kit#1424).
+	// derived here rather than judged from the parent's frozen timeline.
 	const transcript = time_hook_transcript.transcript_of(payload.transcript_path, payload.agent_id)
 	const tail = time_density_hook.read_tail(transcript)
 	const context = { ...parts, tail, call, run: { transcript, now_ms } }
@@ -393,7 +390,7 @@ function guard_outcome(parts: GuardParts, raw_payload: string, now_ms: number):
 function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 	const stamp = create_refusal_stamp(spec.prefix)
 	// A record of its own for the notice, only where a notify spec is supplied. Keyed on its own prefix
-	// so a notice never spends the refusal's stamp (joshuafolkken/kit#1848).
+	// so a notice never spends the refusal's stamp.
 	const notify_stamp = spec.notify ? create_refusal_stamp(spec.notify.prefix) : undefined
 	const parts = { spec, stamp, notify_stamp }
 
@@ -410,7 +407,7 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 	// same reason `format-edited-file.ts` swallows a formatter it could not start: a hook that failed
 	// closed would stop a run over its own plumbing.
 	//
-	// **What changed is that it no longer does so in silence** (joshuafolkken/kit#1509). The call still
+	// **What changed is that it no longer does so in silence**. The call still
 	// goes through — failing open is the right call and is not being revisited — but the fault comes
 	// back as text the run can see, so "the guard said nothing" and "the guard could not look" stop
 	// being the same observation.
@@ -430,8 +427,8 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 }
 
 // Write one already-resolved outcome, so a caller that has to await its rule (the watcher guard reads
-// the lane registry and the life record) can compute the outcome first and hand it here
-// (joshuafolkken/kit#2353). Nothing reaches stdout on the ordinary call, so what the harness parses
+// the lane registry and the life record) can compute the outcome first and hand it here.
+// Nothing reaches stdout on the ordinary call, so what the harness parses
 // stays empty unless the call is being refused.
 function emit_outcome(outcome: GuardOutcome): void {
 	const { reason, notice, fault } = outcome
@@ -453,9 +450,8 @@ function write_outcome(raw_payload: string, outcome: (raw: string) => GuardOutco
 // wrapper rather than a second implementation, so both paths write the same envelopes.
 //
 // **A guard still calling this discards any fault it raised** — `investigation-guard.ts` is the one
-// that does, so a stamp it could not write there is still silent. That is the same gap
-// joshuafolkken/kit#1509 closed for the batching guard, left standing deliberately: this Issue's
-// subject is the batching guard, and moving another hook across belongs with its own test.
+// that does, so a stamp it could not write there is still silent — the gap the batching guard no
+// longer has. Moving another hook across belongs with its own test.
 function write_decision(raw_payload: string, refusal: (raw: string) => string | undefined): void {
 	write_outcome(raw_payload, (raw) => ({
 		reason: refusal(raw),

package/scripts/josh/josh-command-map.ts

@@ -37,6 +37,7 @@ const ALIASES: Record<string, string> = {
 	lr: 'lint:related',
 	ln: 'lines',
 	by: 'bytes',
+	mt: 'metrics',
 	f: 'format',
 	sd: 'cspell:dot',
 	bh: 'behavior',
@@ -80,10 +81,12 @@ const ALIASES: Record<string, string> = {
 	ev: 'eval',
 	lsm: 'lane:sample',
 	lst: 'lane:stats',
+	lli: 'lane:limit',
+	blr: 'backlogrun',
 }
 
 // The canonical name of a `josh` subcommand: an alias expands, and anything else passes through
-// unchanged (joshuafolkken/kit#1789).
+// unchanged.
 //
 // **The expansion is one rule, so it lives beside the table it reads.** Two readers had each written
 // their own `ALIASES[name] ?? name` — the layer report and the gate-run count — and a third, the run

package/scripts/josh/josh-command-types.ts

@@ -6,9 +6,9 @@ import { ENV_FILE_NAME } from '#ports'
 //
 // **There is no mandatory counterpart any more.** `--env-file=.env` aborts before the script's first
 // line when the file is missing, which is wrong for every command kit ships: `doctor` runs from
-// anywhere, including a directory with no project at all (joshuafolkken/kit#869), and `notify` /
+// anywhere, including a directory with no project at all, and `notify` /
 // `followup` run in cloud sessions that carry their credentials as environment variables and keep no
-// `.env` at all (joshuafolkken/kit#1564). A command that needs a value to be present says so itself,
+// `.env` at all. A command that needs a value to be present says so itself,
 // where it can name what is missing.
 const OPTIONAL_ENV_FILE_FLAGS: ReadonlyArray<string> = [`--env-file-if-exists=${ENV_FILE_NAME}`]
 
@@ -17,7 +17,7 @@ type CommandCategory =
 
 // The two vocabularies are runtime tuples the types are derived from, rather than bare unions. A
 // union exists only at compile time, so the completeness test and the generated reference
-// (joshuafolkken/kit#2064) would each have to restate the values to check or render them — two
+//  would each have to restate the values to check or render them — two
 // copies that drift apart silently. Deriving the type from the tuple keeps one definition.
 const COMMAND_AUDIENCES = ['developer', 'maintainer', 'automation'] as const
 const COMMAND_SIDE_EFFECTS = [
@@ -57,21 +57,21 @@ interface CommandEntry {
 	// A command that only makes sense inside the kit repository itself — the rule-compliance eval and
 	// the run measurements that analyze kit's own development. It is dropped from a consumer's
 	// `josh --help` and refused with guidance when run in a consumer project, so a distributed help
-	// listing carries only what a consumer can run (joshuafolkken/kit#1988). The audience in
+	// listing carries only what a consumer can run. The audience in
 	// `reference` separately decides whether the command appears in the default listing.
 	is_kit_only?: boolean
 	// Pre-built to `dist/commands/` so a consumer's `dist/josh.js` imports it in its own process
-	// instead of spawning tsx for it (joshuafolkken/kit#3328, `docs/maintainers/runtime-bundling.md`).
+	// instead of spawning tsx for it (`docs/maintainers/runtime-bundling.md`).
 	is_bundled?: boolean
-	// The cores the command reserves from the machine-wide budget before it starts its heavy tools
-	// (joshuafolkken/kit#3345). `josh-logic.ts` claims them at the one dispatch point every command
+	// The cores the command reserves from the machine-wide budget before it starts its heavy tools.
+	// `josh-logic.ts` claims them at the one dispatch point every command
 	// passes through, so the command only declares the number. A function means the weight is read
 	// when the command starts: the unit suite's share depends on what else is running at that moment.
 	// **The edit hook declares none, on purpose.** It formats one file per edit and finishes in well
 	// under a second, so a wait for room on the machine would stall every edit for the length of
 	// another lane's check.
 	core_weight?: number | (() => number)
-	// The memory the command's tools hold, claimed with its cores (joshuafolkken/kit#3371); read like
+	// The memory the command's tools hold, claimed with its cores; read like
 	// `core_weight`, and none declared is none waited for.
 	memory_mb?: number | (() => number)
 }
@@ -79,23 +79,21 @@ interface CommandEntry {
 // The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a
 // consumer of the name — the command map, `propagate` — does not import the script module: that
 // module carries a `process.argv[1] === import.meta.url` main guard, and esbuild bundles every
-// import into one `dist/josh.js` where that guard matches on *any* `josh` invocation
-// (joshuafolkken/kit#914).
+// import into one `dist/josh.js` where that guard matches on *any* `josh` invocation.
 const GATE_COMMAND = 'gate'
 
-// joshuafolkken/kit#1256: three of the gate's four checks keep a content-addressed cache, so a
-// second run reads only what changed. eslint had one from the start; the type check and the spell
-// check rescanned the whole tree every time, which cost 10.5s of CPU against 2.8s cached.
+// Three of the gate's four checks keep a content-addressed cache, so a second run reads only what
+// changed.
 //
-// Neither of those two needs an invalidation rule of its own. `tsc` records the compiler options
-// inside the build-info file and re-checks everything when they differ, and `cspell` records a
-// content hash of every config and dictionary file it loaded as that entry's dependency — so editing
+// Neither the type check nor the spell check needs an invalidation rule of its own. `tsc` records
+// the compiler options inside the build-info file and re-checks everything when they differ, and
+// `cspell` records a content hash of every config and dictionary file it loaded as that entry's dependency — so editing
 // `tsconfig.json` or `cspell.config.yaml` invalidates what it should. CI restores only the eslint
 // cache (`.github/workflows/ci.yml` → "Setup ESLint cache"); the other two start every run cold.
 //
-// **eslint's does need one, and it is not here** (joshuafolkken/kit#1347). ESLint hashes the
-// *serialized* config, which drops every rule's `create`, so editing `eslint/rules/*.js` left every
-// cached entry valid on every cache file below. The fix is a content fingerprint of the rule modules
+// **eslint's does need one, and it is not here**. ESLint hashes the
+// *serialized* config, which drops every rule's `create`, so editing `eslint/rules/*.js` would leave
+// every cached entry valid on every cache file below. The answer is a content fingerprint of the rule modules
 // carried in the shared config's `settings` — `eslint/config-fingerprint.js` — because one value
 // there invalidates the gate's cache, the scoped one and the edit hook's at once, while a rule
 // written per cache file would have to be repeated for each and would go stale one file at a time.
@@ -153,10 +151,9 @@ const SHARED_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
 ]
 const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => spec.cache_file)
 
-// joshuafolkken/kit#1332: the `PostToolUse` edit hook runs eslint too, and ESLint *deletes* the file
-// at `--cache-location` whenever it is started without `--cache` — so every single edit wiped the
-// cache the gate had just filled, and both gates of run joshuafolkken/kit#1326 paid a cold lint
-// (59.4s and 54.5s, against 3.0s warm). The hook is given a location of its own rather than the
+// The `PostToolUse` edit hook runs eslint too, and ESLint *deletes* the file at `--cache-location`
+// whenever it is started without `--cache` — so a shared file would be wiped by every single edit,
+// leaving the gate a cold lint. The hook is given a location of its own rather than the
 // gate's because the two run at the same time: `josh gate` lints the whole tree beside the review
 // while this hook fires on every edit, and each eslint run rewrites its cache file whole from the
 // copy it loaded at start-up — so two writers silently discard each other's entries. A file of its
@@ -165,18 +162,16 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // **Pruning is not the reason**, though it reads like one: `file-entry-cache` defaults `noPrune` to
 // true, and a single-file run against the gate's full cache was measured byte-identical, so a shared
 // file would keep the entries that run never visited.
-// joshuafolkken/kit#1347: the same reasoning, reached a second time. `josh lint:related` is what an
-// implementation loop calls between edits, and `josh gate` lints the whole tree beside the review —
-// so those two run at the same time as readily as the hook and the gate do, and they shared one file
-// until this constant existed. Whichever of the pair wrote last replaced the file with "the copy I
-// loaded at start-up plus what I visited", so a narrowed run finishing during a whole-tree run rolled
-// the cache back to its pre-gate state, and a whole-tree run finishing second discarded the narrowed
-// one's entries.
+// The same reasoning for the scoped lint. `josh lint:related` is what an implementation loop calls
+// between edits, and `josh gate` lints the whole tree beside the review — so those two run at the
+// same time as readily as the hook and the gate do. Whichever of a pair sharing one file wrote last
+// would replace it with "the copy I loaded at start-up plus what I visited", so a narrowed run
+// finishing during a whole-tree run would roll the cache back to its pre-gate state, and a
+// whole-tree run finishing second would discard the narrowed one's entries.
 //
-// **The warming this gives up is worth less than the entries it stops losing.** The comment this
-// replaced argued the shared file let a narrowed run warm the gate's cache, which is true only while
-// the two never overlap; a file of its own is warm from its own second call onwards, and the gate's
-// stays exactly as the gate left it.
+// **The warming this gives up is worth less than the entries it stops losing.** A shared file would
+// let a narrowed run warm the gate's cache only while the two never overlap; a file of its own is
+// warm from its own second call onwards, and the gate's stays exactly as the gate left it.
 //
 // **The lint's target scope is untouched.** This is where a cache is written, not what is read:
 // `josh lint:related` narrows in front of the gate and `josh gate` still runs `josh lint` over the
@@ -212,7 +207,7 @@ const CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE)
 
 export type { CommandCategory, CommandEntry, GateCacheSpec }
 // The three cache files are exported one by one as well as as a list, because `josh bench` clears
-// them per target (joshuafolkken/kit#1314): the lint step writes only the eslint one, so a target
+// them per target: the lint step writes only the eslint one, so a target
 // that cleared the list would report a cold type check as the lint's own cost. The edit hook's cache
 // stays private; the scoped lint cache is exported because #2060 shares its completed file between
 // worktrees, but it still never overlaps the gate's distinct cache location.

package/scripts/josh/josh-commands-ai.ts

@@ -77,12 +77,12 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[options]', 'maintainer', ['none']],
 		// Kit-only: it measures kit's own development runs and its report modules live under the
 		// undistributed `scripts/time/`, so it means nothing in a consumer project and is dropped from a
-		// consumer's help (joshuafolkken/kit#1997). The runtime analysis hooks and guards rely on stays
+		// consumer's help. The runtime analysis hooks and guards rely on stays
 		// distributed under `scripts/time-runtime/`.
 		is_kit_only: true,
 	},
 	// The tool-calls-per-round-trip density the batching guard is measured on, aggregated across the
-	// recent lane sessions (joshuafolkken/kit#2405). Kit-only for the same reason `time` is: it reads
+	// recent lane sessions. Kit-only for the same reason `time` is: it reads
 	// kit's own lane transcripts and means nothing in a consumer project.
 	'time:density': {
 		script: 'scripts/time/time-density-cli.ts',
@@ -99,7 +99,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'maintainer', ['none']],
 		// Kit-only: it reads kit's own development run — the transcript store, the review ledger and the
 		// run event stream — so it means nothing in a consumer project and is dropped from a consumer's
-		// help (joshuafolkken/kit#2328), through the same declaration `josh time` uses for the same reason.
+		// help, through the same declaration `josh time` uses for the same reason.
 		is_kit_only: true,
 	},
 	'review:brief': {
@@ -156,7 +156,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--join]', 'automation', ['processes', 'files']],
 	},
-	// The post-merge sequence a run closed on, folded into one call (joshuafolkken/kit#2372): commit the
+	// The post-merge sequence a run closed on, folded into one call: commit the
 	// observation ledger, read the completion citations and decide the release scope. `observations:flush`,
 	// `issue:cite` and `release:scope` were three round trips re-billing the run's full context each.
 	'run:tail': {
@@ -166,7 +166,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
 	},
-	// The commit-to-report region a run ships a change on, folded into one call (joshuafolkken/kit#2398):
+	// The commit-to-report region a run ships a change on, folded into one call:
 	// the gate, the commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping
 	// (`run:tail`) were four round trips re-billing the run's full context each. It stops at the first
 	// failed step and names it, so the run reads only the step to fix.
@@ -231,7 +231,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[scenario...]', 'maintainer', ['processes', 'network']],
 		// Kit-only: it replays kit's own distributed rules against real Claude sessions, so it means
-		// nothing in a consumer project and is dropped from a consumer's help (joshuafolkken/kit#1988).
+		// nothing in a consumer project and is dropped from a consumer's help.
 		is_kit_only: true,
 	},
 }

package/scripts/josh/josh-commands-backlog.ts

@@ -1,12 +1,24 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The `backlog:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its
-// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason
-// (joshuafolkken/kit#2162, joshuafolkken/kit#2218). It is spread into `AI_COMMANDS` so the commands
+// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason.
+// It is spread into `AI_COMMANDS` so the commands
 // stay grouped with the other AI tools under the 'AI tools' category.
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
+	// Started from a terminal: the `backlogrun` keyword's launcher, and the board.
+	backlogrun: {
+		script: 'scripts/backlog/backlogrun-cli.ts',
+		description:
+			'Start a backlogrun in the background and show its board; with one already running, only show the board',
+		category: 'AI tools',
+		reference: [
+			'[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]',
+			'developer',
+			['files', 'network', 'processes'],
+		],
+	},
 	'backlog:next': {
 		script: 'scripts/backlog/backlog-next.ts',
 		description:
@@ -41,7 +53,7 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'backlog:stalled': {
 		script: 'scripts/backlog/backlog-stalled-cli.ts',
-		// A stall sends one Telegram warning (joshuafolkken/kit#3357). The `Stop` hook calls the detector
+		// A stall sends one Telegram warning. The `Stop` hook calls the detector
 		// directly, so this flag costs only the manual command its in-process dispatch.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:

package/scripts/josh/josh-commands-clone.ts

@@ -1,7 +1,7 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The clone-detection commands, kept in their own module so `josh-commands-ai.ts` stays under its
-// line ceiling as the AI-tools set grows (joshuafolkken/kit#2217). Spread into `COMMAND_MAP` in
+// line ceiling as the AI-tools set grows. Spread into `COMMAND_MAP` in
 // `josh-command-map.ts` alongside the other command groups.
 /* eslint-disable @typescript-eslint/naming-convention */
 const CLONE_COMMANDS: Record<string, CommandEntry> = {

package/scripts/josh/josh-commands-development.ts

@@ -46,6 +46,20 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
 		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 	},
+	metrics: {
+		script: 'scripts/metrics/metrics-command.ts',
+		description:
+			'Print repository-wide quality totals and durations, and fail when a total grew past the merge-base or a duration past its baseline',
+		category: 'Development',
+		reference: [
+			'[--no-startup | --totals-only | --accept --reason "<why>"]',
+			'developer',
+			['files'],
+		],
+		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		is_kit_only: true,
+	},
 	'refactor:scan': {
 		script: 'scripts/refactor/refactor-scan-cli.ts',
 		description:
@@ -69,6 +83,13 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--refresh]', 'developer', ['files']],
 	},
+	'rule:list': {
+		script: 'scripts/rules/rule-list.ts',
+		description:
+			"Print the trigger-delivered rules — each one's source, firing call and silent turn — from the guard rows",
+		category: 'AI tools',
+		reference: ['', 'automation', ['none']],
+	},
 	format: {
 		script: 'scripts/lint/format.ts',
 		description: 'Format code with prettier and eslint (skips a tool a basic project lacks)',
@@ -90,8 +111,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		// **No `tsx_arguments`, deliberately.** `JOSH_BATCH_GUARD` is a per-machine preference kept in
 		// `.env`, which every other command reads through `OPTIONAL_ENV_FILE_FLAGS` — but declaring any
 		// `tsx_arguments` disqualifies a command from in-process dispatch (`josh-in-process.ts`), and
-		// this one runs before every `Bash` call. That is the hot path joshuafolkken/kit#1342 took a
-		// second ~0.16 s tsx start off. The script calls `process.loadEnvFile` itself instead, which is
+		// this one runs before every `Bash` call, where a second ~0.16 s tsx start is not affordable.
+		// The script calls `process.loadEnvFile` itself instead, which is
 		// node's own `--env-file` parser with node's own precedence.
 	},
 	'pretool:guard': {
@@ -118,7 +139,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'session:lang': {
 		script: 'scripts/josh/session-language-cli.ts',
 		description:
-			'Claude Code hook: print the resolved JOSH_SESSION_LANG (defaults to ja) for the session context',
+			'Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, and the run:board reply rule while a backlogrun is live (otherwise nothing)',
 		category: 'Development',
 		reference: ['', 'automation', ['none']],
 		// **No `tsx_arguments`, deliberately**, the same as `batch:guard` above: this runs on every
@@ -132,7 +153,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['<pretool|posttool>', 'automation', ['none']],
 		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
-		// bundle name (joshuafolkken/kit#3184). **No `tsx_arguments`**, the same as `pretool:guard`
+		// bundle name. **No `tsx_arguments`**, the same as `pretool:guard`
 		// above: it runs before every guarded Codex call.
 	},
 	'cspell:dot': {

package/scripts/josh/josh-commands-document.ts

@@ -1,10 +1,10 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The document-reading and -editing command registry, split out of `josh-commands-ai.ts` so that file
-// stays under its 300-code-line limit, exactly as `SPLIT_COMMANDS` was for the same reason
-// (joshuafolkken/kit#2162, joshuafolkken/kit#2218, joshuafolkken/kit#2366). It is spread into
+// stays under its 300-code-line limit, exactly as `SPLIT_COMMANDS` was for the same reason.
+// It is spread into
 // `AI_COMMANDS` so the commands stay grouped under the 'AI tools' category. `read:files` and
-// `edit:files` are the read/write halves of the round-trip fold (joshuafolkken/kit#2202 / #2366).
+// `edit:files` are the read/write halves of the round-trip fold.
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const DOCUMENT_COMMANDS: Record<string, CommandEntry> = {

package/scripts/josh/josh-commands-guard.ts

@@ -1,11 +1,11 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The `PreToolUse` guard registry, split out of `josh-commands-ai.ts` so that file stays under its
-// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason
-// (joshuafolkken/kit#2162, joshuafolkken/kit#2218, joshuafolkken/kit#2298). It is spread into
+// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason.
+// It is spread into
 // `AI_COMMANDS` so the guards stay grouped with the other AI tools.
 //
-// **None declare `tsx_arguments`, for the reason `batch:guard` declares none** (joshuafolkken/kit#1342):
+// **None declare `tsx_arguments`, for the reason `batch:guard` declares none**:
 // declaring any disqualifies a command from in-process dispatch, and these run in front of every read
 // or shell call. Each script calls `process.loadEnvFile` itself instead, through `hook-decision.ts`.
 

package/scripts/josh/josh-commands-issue.ts

@@ -1,7 +1,7 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The issue-reading and issue-citation commands, split out of `josh-commands-ai.ts` when the mandated
-// `issue:cite` section pushed that file past its 300-line ceiling (joshuafolkken/kit#2220) — the same
+// `issue:cite` section pushed that file past its 300-line ceiling — the same
 // group-per-file shape `LANE_COMMANDS` and `SPLIT_COMMANDS` already take. `COMMAND_MAP` spreads this
 // in, so nothing downstream sees where an entry lives.
 
@@ -33,8 +33,7 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'defect:rate': {
 		script: 'scripts/issue/defect-rate-cli.ts',
-		description:
-			'Print the defect rate of merged work: defects filed per behavior change completed',
+		description: 'Print the defect rate of merged work: defects filed per enhancement completed',
 		category: 'AI tools',
 		reference: ['[--days <n>]', 'automation', ['network']],
 	},
@@ -66,10 +65,10 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	'issue:file': {
 		script: 'scripts/issue/issue-file-cli.ts',
 		description:
-			'File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle',
+			'File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]',
 			'automation',
 			['network'],
 		],

package/scripts/josh/josh-commands-lane.ts

@@ -1,7 +1,7 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The `lane:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its line
-// limit (joshuafolkken/kit#2162). One script answers `lane:open` / `lane:close` / `lane:list` /
+// limit. One script answers `lane:open` / `lane:close` / `lane:list` /
 // `lane:prune` / `lane:output` / `lane:dispatch` / `lane:await`, told apart by the verb below;
 // `lane:launch` is the composite that opens, pops-and-installs on the first lane, and dispatches.
 const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
@@ -74,12 +74,22 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
 	},
-	// The lane-limit measurement (joshuafolkken/kit#3355): `.env` is read so `lane:stats` labels the row
+	// A live run's lane limit: `.env` is read so the bare form reports the
+	// `JOSH_LANE_LIMIT` a person set there when no override stands.
+	'lane:limit': {
+		script: 'scripts/lane/lane-limit-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Change a live backlogrun’s lane limit without stopping it, or print the limit, lanes in use and free lanes',
+		category: 'AI tools',
+		reference: ['[<limit>] [--reset]', 'developer', ['files']],
+	},
+	// The lane-limit measurement: `.env` is read so `lane:stats` labels the row
 	// with the `JOSH_LANE_LIMIT` a person set there.
 	'lane:sample': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Record the machine load (load average, swap, free memory, working lanes) to the lane ledger',
+			'Record the machine load (load average, swap, free memory, working lanes) to the lane ledger — a backlogrun samples itself, this is for a reading outside one',
 		category: 'AI tools',
 		reference: ['[--every <seconds>]', 'maintainer', ['files']],
 		default_script_arguments: ['sample'],
@@ -87,7 +97,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period',
+			'Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],

package/scripts/josh/josh-commands-lint.ts

@@ -1,6 +1,6 @@
 import type { CommandEntry } from './josh-command-types'
 
-// The linters for the fixed-shape artifacts a run writes by hand (joshuafolkken/kit#2123). They are
+// The linters for the fixed-shape artifacts a run writes by hand. They are
 // `AI tools` by category, like every other automation command, but live in their own file so
 // `josh-commands-ai.ts` stays under its line ceiling.