@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/josh/file-map-stamp.ts

@@ -3,7 +3,7 @@ import { stamp_file } from './stamp-file'
 
 // A stamp whose payload is "when this was taken, and the digest of every file it covers".
 //
-// `scripts/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
+// `tools/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
 // records of exactly the same kind — the gate's result, and the snapshot round 1 takes so round 2
 // can name the fix delta — and copying the payload type, its validation, the guarded read and the
 // comparison into a second module is the clone `CLAUDE.md` prohibits. What genuinely differs between
@@ -48,6 +48,14 @@ interface FileMapStamp {
 	// reads it and the two `josh review:brief` records, which assert a completed past fact by
 	// existing at all, neither write nor read it.
 	completed_at?: string
+	// The git blob of each mapped path as it was read — written only by the round-1 review snapshot
+	// (`review-round-one-blobs.ts`). When `base` moves, round 2 carries these onto the new base and
+	// measures the fix delta from there; a record without them falls back to the moved-base refusal.
+	blobs?: Record<string, string>
+	// The fingerprint of what the vouched check reads beside the files — its tools' versions and its
+	// environment (`verification-inputs.ts`, joshuafolkken/kit#4495). Written by a record created with an
+	// `inputs` source; a reader of such a record refuses one whose fingerprint is absent or differs.
+	inputs?: string
 }
 
 // Takes `unknown` rather than the declared field type, because the declared type is an assertion
@@ -64,28 +72,38 @@ function is_file_map(value: unknown): value is Record<string, string> {
 // reader treats an absent field as the safe answer — "not running" for a `pid`, "cannot be reused"
 // for a `base`. Spread rather than assigned, because `exactOptionalPropertyTypes` makes an explicit
 // `undefined` a different thing from an absent key.
-function optional_fields(
-	pid: unknown,
-	base: unknown,
-	completed_at: unknown,
-	process_start: unknown,
-): Partial<FileMapStamp> {
+function identity_fields({ pid, process_start }: Partial<FileMapStamp>): Partial<FileMapStamp> {
 	return {
 		...(typeof pid === 'number' && { pid }),
+		...(typeof process_start === 'string' && { process_start }),
+	}
+}
+
+function tree_fields({ base, completed_at, blobs }: Partial<FileMapStamp>): Partial<FileMapStamp> {
+	return {
 		...(typeof base === 'string' && { base }),
 		...(typeof completed_at === 'string' && { completed_at }),
-		...(typeof process_start === 'string' && { process_start }),
+		...(is_file_map(blobs) && { blobs }),
 	}
 }
 
+function input_fields({ inputs }: Partial<FileMapStamp>): Partial<FileMapStamp> {
+	return typeof inputs === 'string' ? { inputs } : {}
+}
+
 function parse_stamp(raw: string): FileMapStamp | undefined {
-	const { taken_at, files, pid, base, completed_at, process_start } = JSON.parse(
-		raw,
-	) as Partial<FileMapStamp>
+	const parsed = JSON.parse(raw) as Partial<FileMapStamp>
+	const { taken_at, files } = parsed
 
 	if (typeof taken_at !== 'string' || !is_file_map(files)) return undefined
 
-	return { taken_at, files, ...optional_fields(pid, base, completed_at, process_start) }
+	return {
+		taken_at,
+		files,
+		...identity_fields(parsed),
+		...tree_fields(parsed),
+		...input_fields(parsed),
+	}
 }
 
 // Whether the process that wrote this record is still running. It takes the
@@ -152,14 +170,22 @@ function changed_since(stamp: FileMapStamp, tree: Record<string, string>): Reado
 interface FileMapStampAccess {
 	stamp_path: () => string
 	// `base` is written by the one record that is acted on rather than merely reported — the
-	// green-gate reuse. The others omit it and are unaffected.
-	write: (files: Record<string, string>, target?: string, base?: string) => string
+	// green-gate reuse. The others omit it and are unaffected. `blobs` is the round-1 snapshot's alone.
+	write: (
+		files: Record<string, string>,
+		target?: string,
+		base?: string,
+		blobs?: Record<string, string>,
+	) => string
 	// Marks an existing record as belonging to a run that finished. It
 	// amends rather than rewrites, and answers `undefined` where there is no record to amend: a run
 	// whose record never got written has nothing to assert a completion about, and inventing one here
 	// would manufacture the very vouching the field exists to withhold.
 	complete: (target?: string) => string | undefined
 	read: (source?: string) => FileMapStamp | undefined
+	// Whether `stamp` was written under the inputs fingerprint read now; always `true` for a record
+	// created without an `inputs` source, which never vouches for a check.
+	describes_inputs: (stamp: FileMapStamp) => boolean
 	// For a record whose meaning is its existence rather than its contents — the in-flight gate marker.
 	// A record nobody removes would go on asserting a gate that ended.
 	remove: (target?: string) => void
@@ -219,7 +245,11 @@ function complete_at(target: string): string | undefined {
 // The destination is a parameter on both sides so a test can exercise the round trip without
 // overwriting the record a real run may be relying on — two commands share one path by design, and a
 // suite that wrote to it would be a second writer nobody declared.
-function create(prefix: string, root?: string): FileMapStampAccess {
+//
+// `inputs` answers the fingerprint of what the record vouches for beside its files
+// (`verification-inputs.ts`); it is read at each write and each comparison, so a tool reinstalled or an
+// environment variable changed between them leaves the record standing for nobody.
+function create(prefix: string, root?: string, inputs?: () => string): FileMapStampAccess {
 	function resolve(): string {
 		return stamp_file.stamp_path(prefix, root)
 	}
@@ -229,15 +259,18 @@ function create(prefix: string, root?: string): FileMapStampAccess {
 		// `base` goes into the payload undefined and all — `JSON.stringify` drops an undefined value,
 		// so a caller that has no base writes exactly the record it wrote before this field existed.
 		// `own_fields` is what writes the pid, and the writing process's start time beside it — assembled in one place so no record can carry half an identity.
-		write: (files, target = resolve(), base?: string) =>
+		write: (files, target = resolve(), base?: string, blobs?: Record<string, string>) =>
 			stamp_file.write_stamp(target, {
 				taken_at: new Date().toISOString(),
 				files,
 				...process_identity.own_fields(),
 				base,
+				blobs,
+				inputs: inputs?.(),
 			}),
 		complete: (target = resolve()) => complete_at(target),
 		read: (source = resolve()) => read_at(source),
+		describes_inputs: (stamp) => inputs === undefined || stamp.inputs === inputs(),
 		remove: (target = resolve()) => {
 			stamp_file.remove_stamp(target)
 		},

package/scripts/josh/hook-decision.ts

@@ -1,4 +1,6 @@
+import { text } from 'node:stream/consumers'
 import { json_value } from '#scripts/lib/json-value'
+import { file_reader } from '#scripts/lib/read-file'
 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'
@@ -43,7 +45,6 @@ const ALLOW_DECISION = 'allow'
 // No record means nothing has been refused yet, and every span began after instant zero — which is
 // the answer wanted: the first qualifying accumulation of a run is refused.
 const NEVER_MS = 0
-const MISSING_FILE = 'ENOENT'
 
 // More than one spelling, because the mistake on this side is silent: a value meant to disable a
 // guard that the list does not recognize leaves it on, and the person sees refusals they asked to
@@ -69,9 +70,7 @@ function is_switch_opt_in(key: string): boolean {
 }
 
 function parse_hook_payload(raw_payload: string): HookPayload | undefined {
-	const parsed = payload_schema.safeParse(JSON.parse(raw_payload))
-
-	return parsed.success ? parsed.data : undefined
+	return json_value.parse_with(raw_payload, payload_schema)
 }
 
 // The documented shape a `PreToolUse` hook answers with. Plain stdout is not it — only this envelope
@@ -137,25 +136,19 @@ function stamp_fault(switch_key: string): string {
 	)
 }
 
-// **A transcript that does not exist yet is not a fault.** A delegated unit's own file is named before
-// 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.
-function is_missing_file(error: unknown): boolean {
-	if (!(error instanceof Error) || !('code' in error)) return false
-
-	return typeof error.code === 'string' && error.code === MISSING_FILE
-}
-
 function error_text(error: unknown): string {
 	if (error instanceof Error) return error.message
 
 	return typeof error === 'string' ? error : 'a value that is not an error'
 }
 
+// **A transcript that does not exist yet is not a fault.** A delegated unit's own file is named before
+// 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.
 function fault_notice(switch_key: string, error: unknown): string | undefined {
-	if (is_missing_file(error)) return undefined
+	if (file_reader.is_absent(error)) return undefined
 
 	const detail = error_text(error)
 
@@ -416,10 +409,10 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 		return stamp.path(transcript_path)
 	}
 
-	// **Every failure allows the call.** A missing transcript, a payload that is not JSON, a
-	// half-written tail, a temp directory that cannot be written — each ends as "no refusal", for the
-	// 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.
+	// **Every failure allows the call.** An unreadable transcript, a half-written tail, a temp directory
+	// that cannot be written — each ends as "no refusal", for the 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. A payload that is not JSON names no call to judge, so it ends with no outcome at all.
 	//
 	// **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
@@ -481,6 +474,24 @@ function report_no_payload(command: string): void {
 	)
 }
 
+// A hook entry's whole main: the hand-run notice from a terminal, else the payload on stdin handed to
+// `respond` once `.env` is loaded.
+async function respond_from_stdin(
+	command: string,
+	respond: (raw: string) => Promise<void> | void,
+): Promise<void> {
+	if (process.stdin.isTTY) {
+		report_no_payload(command)
+
+		return
+	}
+
+	const raw_payload = await text(process.stdin)
+
+	load_environment_file()
+	await respond(raw_payload)
+}
+
 const hook_decision = {
 	DISABLED_VALUES,
 	ENABLED_VALUES,
@@ -497,6 +508,7 @@ const hook_decision = {
 	notice_envelope,
 	parse_hook_payload,
 	report_no_payload,
+	respond_from_stdin,
 	rewrite_envelope,
 	stamp_fault,
 	write_decision,

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

@@ -47,6 +47,7 @@ const ALIASES: Record<string, string> = {
 	tr: 'test:related',
 	td: 'test:declared',
 	trd: 'test:red',
+	tpn: 'test:pinned',
 	te: 'test:e2e',
 	c: 'check',
 	pt: 'port',
@@ -55,7 +56,6 @@ const ALIASES: Record<string, string> = {
 	st: 'start',
 	sy: 'sync',
 	un: 'uninstall',
-	rmi: 'registry:migrate',
 	g: 'git',
 	gp: 'pr',
 	ms: 'main:sync',
@@ -79,6 +79,7 @@ const ALIASES: Record<string, string> = {
 	rtr: 'retrospective',
 	ca: 'cost:audit',
 	rvf: 'review:findings',
+	rvs: 'review:stops',
 	ruv: 'rule:value',
 	ev: 'eval',
 	fr: 'fresh:run',
@@ -88,6 +89,8 @@ const ALIASES: Record<string, string> = {
 	lli: 'lane:limit',
 	lrs: 'lane:restart',
 	lwd: 'lane:withdraw',
+	lps: 'lane:pause',
+	lru: 'lane:resume',
 	blr: 'backlogrun',
 }
 

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

@@ -56,7 +56,8 @@ interface CommandFlag {
 }
 
 // What `josh help <command>` prints and what the reference pages render between their usage
-// markers — one source for both, so the page and the terminal cannot disagree (#3932).
+// markers — one source for both, so the page and the terminal cannot disagree (#3932). Each command's
+// entry carries its own, so a command cannot be registered without one (#4185).
 interface CommandUsage {
 	examples: ReadonlyArray<CommandExample>
 	flags?: ReadonlyArray<CommandFlag>
@@ -68,6 +69,7 @@ interface CommandEntry {
 	description: string
 	category: CommandCategory
 	reference: CommandReference
+	usage: CommandUsage
 	tsx_arguments?: ReadonlyArray<string>
 	default_script_arguments?: ReadonlyArray<string>
 	// Composite (`sh -c`) commands reject extra CLI arguments instead of swallowing them; this
@@ -93,6 +95,8 @@ interface CommandEntry {
 	// 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)
+	// A unit suite's claim, whose weight is its worker count (`gate_plan.DIRECT_UNIT_CLAIM`).
+	is_unit_claim?: boolean
 }
 
 // The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a
@@ -184,7 +188,7 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // 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
+// gate's because the two run at the same time: `josh gate` lints 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
 // own makes the hook structurally unable to degrade the cache this exists to protect.
@@ -193,7 +197,7 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // 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.
 // 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
+// between edits, and `josh gate` lints 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
@@ -204,8 +208,8 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // 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
-// whole tree before any commit. The scoped lint's prettier cache is its own for the same reason:
+// `josh lint:related` and the gate's `josh lint --changed` each narrow to the change, on caches of
+// their own. The scoped lint's prettier cache is its own for the same reason:
 // prettier rewrites its cache file whole as well.
 // What the ignore rules are asserted against: every cache file this package writes, wherever it is
 // written from. The gate's, the edit hook's, the scoped lint's and the pre-commit hook's — a cache
@@ -250,7 +254,8 @@ export type { CommandCategory, CommandEntry, CommandUsage, GateCacheSpec }
 // 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.
+// worktrees, but it still never overlaps the gate's distinct cache location. The pre-commit hook's
+// eslint cache is exported because the hook re-reads a red report against it (#4407).
 export {
 	COMMAND_AUDIENCES,
 	COMMAND_SIDE_EFFECTS,
@@ -259,6 +264,7 @@ export {
 	CSPELL_COMMIT_CACHE_FLAGS,
 	ESLINT_CACHE_FILE,
 	ESLINT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FILE,
 	ESLINT_COMMIT_CACHE_FLAGS,
 	ESLINT_EDIT_CACHE_FLAGS,
 	ESLINT_RELATED_CACHE_FLAGS,

package/scripts/josh/josh-commands-agent-hooks.ts

@@ -0,0 +1,83 @@
+import type { CommandEntry } from './josh-command-types'
+
+const PRE_TOOL_USE = 'run by the PreToolUse hook, the pending tool call as JSON on stdin'
+
+// The Claude Code and Codex hook commands, split out of `josh-commands-development.ts` when each
+// command's usage moved onto its entry (#4185). `DEV_COMMANDS` spreads this in at the same place, so
+// the map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const AGENT_HOOK_COMMANDS: Record<string, CommandEntry> = {
+	'format:edited': {
+		script: 'scripts/hooks/format-edited-cli.ts',
+		description: 'Claude Code hook: format the file just edited (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['', 'automation', ['files', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'run by the PostToolUse hook, the tool call as JSON on stdin' },
+			],
+		},
+	},
+	'pretool:guard': {
+		script: 'scripts/hooks/pretool-guard-cli.ts',
+		description:
+			'Claude Code hook: the batch, investigation and rule guards in one process (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['', 'automation', ['none']],
+		usage: { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+		// **No `tsx_arguments`, deliberately.** `JOSH_BATCH_GUARD` and the other guard switches are
+		// per-machine preferences 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 is the one PreToolUse hook consumers run
+		// before every guarded call, where a second ~0.16 s tsx start is not affordable. Each guard it
+		// composes loads `.env` through the shared loader instead.
+	},
+	'stop:guard': {
+		script: 'scripts/hooks/stop-guard.ts',
+		description:
+			'Claude Code Stop hook: send the hold notify, release the hold and print the issue citations itself; block on the rules that need the model (reads the Stop payload on stdin)',
+		category: 'Development',
+		reference: ['', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'run by the Stop hook, the stop payload as JSON on stdin' },
+			],
+		},
+		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs at every
+		// turn end, so it must stay eligible for in-process dispatch rather than pay a second tsx start.
+		// It loads `.env` through the shared `hook-decision.ts` loader.
+	},
+	'session:lang': {
+		script: 'scripts/josh/session-language-main.ts',
+		description:
+			'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']],
+		usage: {
+			examples: [{ arguments: '', note: 'run by the UserPromptSubmit hook; `ja` prints nothing' }],
+		},
+		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs on every
+		// `UserPromptSubmit`, so it must stay eligible for in-process dispatch rather than pay a second
+		// tsx start each turn. It calls `process.loadEnvFile` itself through the shared loader.
+	},
+	'codex:hook-adapter': {
+		script: 'scripts/hooks/codex-hook-adapter.ts',
+		description:
+			'Codex hook: run the pretool or posttool guard on a Codex payload (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['<pretool|posttool>', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'pretool', note: 'a Codex PreToolUse payload on stdin' },
+				{ arguments: 'posttool', note: 'a Codex PostToolUse payload on stdin' },
+			],
+		},
+		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
+		// bundle name. **No `tsx_arguments`**, the same as `pretool:guard`
+		// above: it runs before every guarded Codex call.
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { AGENT_HOOK_COMMANDS }