@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/test/vitest-failure-summary.ts

@@ -0,0 +1,111 @@
+import { stripVTControlCharacters } from 'node:util'
+import { gate_log } from '#scripts/gate/gate-log'
+import { verification_tail } from '#scripts/gate/verification-tail'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// A failed vitest run's answer, put where a `tail` reaches it (joshuafolkken/kit#4869).
+//
+// **The console's end is the last failure's stack, not the list of what failed.** vitest prints its
+// failures in order and then a summary of counts, so `josh test:related 2>&1 | tail -40` kept one stack
+// and no names, and the only way to learn the rest was to run the suite again. So every run's output
+// goes to a file, and a failed one ends with the failed tests' names and that file's path — the same
+// log and notice `josh gate` uses, imported rather than re-derived.
+
+const UNIT_LOG_PREFIX = 'josh-unit-log-'
+const UNIT_LOG_HEADER = 'vitest'
+const FAILED_LINE = /^FAIL\s+(?<name>\S.*)$/u
+const FAILED_HEADING = 'failed tests:'
+const NONE_NAMED = '  (none named in the output — read the full output)'
+const NONE_NAMED_VERDICT = 'none named'
+// A name is `<file> > <suite> > <test>` or `<file> [ <file> ]`, prefixed `|<project>| ` in a workspace —
+// or, with color on, ` <project>  ` once its badge's escapes are stripped (joshuafolkken/kit#5171).
+const FAILED_FILE = /^(?:\|[^|]*\|\s+|\S+\s{2,})?(?<file>\S+)/u
+// The guarded unit run, filtered to those files: it reserves its cores and ends a failure with this
+// same summary (joshuafolkken/kit#5023).
+const RERUN_PREFIX = 'rerun failed: pnpm josh test:unit '
+
+// One path per checkout and vitest mode, overwritten by each run, beside the gate's own log. **The
+// mode is in the name** because the gate's whole-suite `run` and a `related` run started beside it
+// overlap, and one shared file would hand the failed run's reader the other run's output.
+function unit_log_path(vitest_arguments: ReadonlyArray<string>): string {
+	const prefix = `${UNIT_LOG_PREFIX}${vitest_arguments[0] ?? UNIT_LOG_HEADER}-`
+
+	return stamp_file.stamp_path(prefix, PROJECT_ROOT, gate_log.GATE_LOG_SUFFIX)
+}
+
+function failed_name(line: string): string | undefined {
+	return FAILED_LINE.exec(stripVTControlCharacters(line).trim())?.groups?.['name']
+}
+
+// vitest names each failed test on a ` FAIL  <file> > <suite> > <test>` line, and a file that could
+// not load on ` FAIL  <file> [ <file> ]`. A name printed twice is listed once.
+function failed_tests(output: string): ReadonlyArray<string> {
+	const names = output.split('\n').map((line) => failed_name(line))
+
+	return [...new Set(names.filter((name) => name !== undefined))]
+}
+
+// The files the failed names belong to, each once — what to run after a fix, before the whole related
+// set again (joshuafolkken/kit#5023).
+function failed_files(names: ReadonlyArray<string>): ReadonlyArray<string> {
+	const files = names.map((name) => FAILED_FILE.exec(name)?.groups?.['file'])
+
+	return [...new Set(files.filter((file) => file !== undefined))]
+}
+
+function name_lines(names: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (names.length === 0) return [NONE_NAMED]
+
+	return [...names.map((name) => `  ${name}`), `${RERUN_PREFIX}${failed_files(names).join(' ')}`]
+}
+
+// The verdict names the failed files, so the last line alone says what to fix (joshuafolkken/kit#5162).
+function format_failure_summary(
+	output: string,
+	log_path: string | undefined,
+	label: string = UNIT_LOG_HEADER,
+): string {
+	const names = failed_tests(output)
+	const failures = `${[FAILED_HEADING, ...name_lines(names)].join('\n')}\n`
+	const failed = names.length === 0 ? [NONE_NAMED_VERDICT] : failed_files(names)
+	const verdict = verification_tail.format_verdict(label, failed)
+
+	return verification_tail.format_tail({ failures, log: { path: log_path }, verdict })
+}
+
+function format_green_summary(log_path: string | undefined, label: string): string {
+	const verdict = verification_tail.format_verdict(label, [])
+
+	return verification_tail.format_tail({ failures: '', log: { path: log_path }, verdict })
+}
+
+// Written on every run, as the gate's is, headed by the run's own invocation, and ended as every josh
+// check ends (`verification-tail.ts`): a green run's last line is its verdict, not vitest's counts.
+function report(
+	vitest_arguments: ReadonlyArray<string>,
+	output: string,
+	exit_code: number,
+	target: string = unit_log_path(vitest_arguments),
+): void {
+	const header = [UNIT_LOG_HEADER, ...vitest_arguments].join(' ')
+	const log_path = gate_log.write_gate_log([{ header, output }], target)
+	const label = [UNIT_LOG_HEADER, ...vitest_arguments.slice(0, 1)].join(' ')
+	const summary =
+		exit_code === 0
+			? format_green_summary(log_path, label)
+			: format_failure_summary(output, log_path, label)
+
+	process.stdout.write(summary)
+}
+
+const vitest_failure_summary = {
+	RERUN_PREFIX,
+	failed_files,
+	failed_tests,
+	format_failure_summary,
+	report,
+	unit_log_path,
+}
+
+export { vitest_failure_summary }

package/scripts/test/whole-suite-files.ts

@@ -36,12 +36,16 @@ const IMPORTED_BY_EVERY_TEST: ReadonlyArray<string> = [
 	'scripts/josh/process-identity.ts',
 	'scripts/josh/process-owner.ts',
 	'scripts/josh/stamp-file.ts',
+	'scripts/lane/lane-child-mark-keys.ts',
 	'scripts/lib/atomic-write.ts',
 	'scripts/lib/json-value.ts',
 	'scripts/lib/read-file.ts',
 	'scripts/lib/timeouts.ts',
+	'scripts/test/unit-durations.ts',
 	'scripts/test/unit-run-marker.ts',
 	'scripts/test/unit-setup-files.ts',
+	'scripts/test/vitest-cache-directory.ts',
+	'scripts/test/vitest-cli-excludes.ts',
 	'tools/test/duration-sequencer.ts',
 	'tools/test/duration-shard.ts',
 	'tools/test/pure-files.ts',
@@ -58,6 +62,13 @@ const WHOLE_SUITE_FILES: ReadonlySet<string> = new Set(
 	[...ROOT_FILES, ...IMPORTED_BY_EVERY_TEST, ...SETUP_FILES].map((file) => path.normalize(file)),
 )
 
-const whole_suite_files = { WHOLE_SUITE_FILES }
+// The part of `WHOLE_SUITE_FILES` a scoped run narrows to the test files importing it directly
+// (`direct-importers.ts`, joshuafolkken/kit#5122): each is a module some test imports by name, unlike a
+// root or setup file, which only the whole suite reaches.
+const EVERY_TEST_IMPORTS: ReadonlySet<string> = new Set(
+	IMPORTED_BY_EVERY_TEST.map((file) => path.normalize(file)),
+)
+
+const whole_suite_files = { EVERY_TEST_IMPORTS, WHOLE_SUITE_FILES }
 
 export { whole_suite_files }

package/scripts/time-runtime/time-batch-guard.ts

@@ -1,7 +1,9 @@
 import { time_bundle_call, type BundleFacts } from './time-bundle-call'
 import { time_bundles } from './time-bundles'
 import { time_call_identity } from './time-call-identity'
+import { time_search_call } from './time-search-call'
 import { time_spans, type Span } from './time-spans'
+import type { ToolCall } from './time-tool-call'
 import { time_transcript_line } from './time-transcript-line'
 
 // Whether the call about to go out should be refused because the run has stopped batching. What a
@@ -154,6 +156,16 @@ function is_reissued_refusal(spans: ReadonlyArray<Span>, call: GuardedCall): boo
 	)
 }
 
+// The closed history a refusal judges; empty where the call is not refusable or is a reissue, and an
+// empty history never reaches the limit.
+function refusable_spans(text: string, call: GuardedCall): ReadonlyArray<Span> {
+	if (!is_guarded_call(call)) return []
+
+	const { spans } = time_spans.parse_timeline(text)
+
+	return is_reissued_refusal(spans, call) ? [] : spans
+}
+
 // The lane-child notice passes `NOTICE_REFIRE_EVERY` to recur on the notice's cadence.
 function should_block(
 	text: string,
@@ -161,13 +173,37 @@ function should_block(
 	refused_at_ms: number,
 	refire_every: number = REFIRE_EVERY,
 ): boolean {
-	if (!is_guarded_call(call)) return false
+	return is_at_limit(refusable_spans(text, call), call, refused_at_ms, refire_every)
+}
 
-	const { spans } = time_spans.parse_timeline(text)
+function as_tool_call(call: GuardedCall): ToolCall {
+	return time_spans.to_tool_call(call.name, call.input, time_spans.NO_MESSAGE_ID)
+}
+
+// Asked before the transcript is read, like `is_guarded_call`, for the search-chain refusal alone.
+function is_search_chain_call(call: GuardedCall): boolean {
+	return is_guarded_call(call) && time_search_call.is_search_chain_call(as_tool_call(call))
+}
+
+// The turns that make the limit — the last closed ones and the call in hand — are all searches.
+function is_search_chain(spans: ReadonlyArray<Span>, call: GuardedCall): boolean {
+	const recent = time_bundles.open_sequence(spans).slice(-SEQUENCE_BEFORE_LIMIT)
+
+	return [...recent, as_tool_call(call)].every((turn) =>
+		time_search_call.is_search_chain_call(turn),
+	)
+}
 
-	if (is_reissued_refusal(spans, call)) return false
+// The narrower refusal a lane child keeps (`search-batching` in `lane-guard-policy.ts`): only a chain
+// of searches issued one per turn, the largest share of the child's single-call pairs.
+function should_block_search_chain(
+	text: string,
+	call: GuardedCall,
+	refused_at_ms: number,
+): boolean {
+	const spans = refusable_spans(text, call)
 
-	return is_at_limit(spans, call, refused_at_ms, refire_every)
+	return is_search_chain(spans, call) && is_at_limit(spans, call, refused_at_ms, REFIRE_EVERY)
 }
 
 // `notified_at_ms` is the notice's own record, so a notice never silences a later refusal.
@@ -279,9 +315,11 @@ const time_batch_guard = {
 	is_guarded_call,
 	is_notice_call,
 	is_read_only_call,
+	is_search_chain_call,
 	pairing_candidates,
 	recent_candidates,
 	should_block,
+	should_block_search_chain,
 	should_notify,
 }
 

package/scripts/time-runtime/time-bundle-call.ts

@@ -1,5 +1,5 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
-import { canonical_command } from '#scripts/josh/josh-command-map'
+import { canonical_command } from '#scripts/josh/josh-aliases'
 import { json_value } from '#scripts/lib/json-value'
 import { time_shell } from './time-shell'
 

package/scripts/time-runtime/time-bundles.ts

@@ -95,15 +95,29 @@ interface BundleTotals {
 	recoverable_round_trips: number
 	by_tool: ReadonlyArray<BundleToolRow>
 	unattributed_round_trips: number
+	single_call: SingleCallSplit
 	is_measured: boolean
 }
 
+// The consecutive single-call turns alone, split by the target test — what `josh time:density` reads.
+// **The spread-apart `Agent` launch series is left out** of every field here: the walk never sees a
+// launch, so it can be neither dependent nor independent, and folding its count into one side would
+// make the two sides measure different populations.
+interface SingleCallSplit {
+	// Turns that could have gone out beside the single-call turn before them.
+	independent_round_trips: number
+	// Turns whose call shared a target with the open sequence, so needed the turn before.
+	dependent_round_trips: number
+	by_tool: ReadonlyArray<BundleToolRow>
+}
+
 const NO_BUNDLES: BundleTotals = {
 	sequence_count: 0,
 	longest_sequence: 0,
 	recoverable_round_trips: 0,
 	by_tool: [],
 	unattributed_round_trips: 0,
+	single_call: { independent_round_trips: 0, dependent_round_trips: 0, by_tool: [] },
 	is_measured: false,
 }
 
@@ -191,10 +205,11 @@ interface Walk {
 	pending: Array<Span>
 	sequence: Array<Span>
 	closed: Array<Array<Span>>
+	dependent: number
 }
 
 function new_walk(): Walk {
-	return { pending: [], sequence: [], closed: [] }
+	return { pending: [], sequence: [], closed: [], dependent: NONE }
 }
 
 function flush(walk: Walk): void {
@@ -204,9 +219,13 @@ function flush(walk: Walk): void {
 }
 
 // A conflicting call does not end the run of single-call turns; it starts a new sequence at itself,
-// because everything after it may still have been bundleable with it.
+// because everything after it may still have been bundleable with it. The conflict is the one place a
+// dependent pair is seen, so it is counted here rather than by a second walk.
 function extend(walk: Walk, span: Span): void {
-	if (conflicts(span, walk.sequence)) flush(walk)
+	if (conflicts(span, walk.sequence)) {
+		walk.dependent += ONE_CALL
+		flush(walk)
+	}
 
 	walk.sequence.push(span)
 }
@@ -359,6 +378,14 @@ function with_agent_row(
 	return [...rows, row].toSorted(by_weight)
 }
 
+function single_call_split(walk: Walk, sizes: ReadonlyArray<number>): SingleCallSplit {
+	return {
+		independent_round_trips: recoverable_of(sizes),
+		dependent_round_trips: walk.dependent,
+		by_tool: tool_rows(walk.closed),
+	}
+}
+
 function build_bundles(spans: ReadonlyArray<Span>): BundleTotals {
 	const walk = new_walk()
 
@@ -373,8 +400,9 @@ function build_bundles(spans: ReadonlyArray<Span>): BundleTotals {
 	// is never bundleable, so it cannot have entered a sequence above — so their counts simply add.
 	const sizes = sizes_of(walk.closed)
 	const agent_sizes = time_agent_bundles.agent_bundles(spans)
-	const by_tool = with_agent_row(tool_rows(walk.closed), agent_sizes)
-	const recoverable_round_trips = recoverable_of(sizes) + recoverable_of(agent_sizes)
+	const single_call = single_call_split(walk, sizes)
+	const by_tool = with_agent_row(single_call.by_tool, agent_sizes)
+	const recoverable_round_trips = single_call.independent_round_trips + recoverable_of(agent_sizes)
 
 	return {
 		sequence_count: sizes.length + agent_sizes.length,
@@ -382,6 +410,7 @@ function build_bundles(spans: ReadonlyArray<Span>): BundleTotals {
 		recoverable_round_trips,
 		by_tool,
 		unattributed_round_trips: recoverable_round_trips - attributed_of(by_tool),
+		single_call,
 		is_measured: time_spans.has_transcript_data(spans.length),
 	}
 }
@@ -524,9 +553,11 @@ const time_bundles = {
 	NO_BUNDLES,
 	build_bundles,
 	bundle_lines,
+	by_weight,
 	is_dependent,
 	open_sequence,
 	shares_target,
 }
 
+export type { BundleToolRow }
 export { time_bundles }

package/scripts/time-runtime/time-markers.ts

@@ -32,8 +32,8 @@ import { json_value } from '#scripts/lib/json-value'
 // which the main line loaded the skill itself.
 //
 // **The launch is recognized by its prompt carrying both `/code-review` and `review:attest`.** The
-// first is the instruction to invoke the review skill; the second is the attestation line
-// `pnpm josh review:brief` emits into the brief the launch passes verbatim.
+// first is the instruction to invoke the review skill; the second is the attestation step the launch
+// prompt `pnpm josh run:review` prints beside each brief file names (joshuafolkken/kit#4863).
 // Neither alone is enough: an investigation subagent about the review tooling quotes `/code-review`
 // in prose and is handed no brief, so `review:attest` is what tells a genuine review launch from a
 // discussion of one — measured against five real launches, it admits the review and rejects every

package/scripts/time-runtime/time-search-call.ts

@@ -0,0 +1,38 @@
+import { time_shell } from './time-shell'
+import type { ToolCall } from './time-tool-call'
+
+// Which calls are a search, the one answer the investigation guard and the batching guard both read.
+// A search carries no file text but costs a turn, so it is what a run issues one per turn while it
+// locates the next edit.
+
+const SEARCH_COMMANDS: ReadonlyArray<string> = ['fd', 'find', 'grep', 'rg']
+const SEARCH_LABELS: ReadonlySet<string> = new Set(
+	SEARCH_COMMANDS.map((command) => time_shell.bash_label(command)),
+)
+
+// A search chain also prints the lines a search found, so `sed` (read-only) joins it: `grep` → `sed`
+// was measured the second-largest single-call pair in lane children.
+const CHAIN_COMMANDS: ReadonlyArray<string> = [...SEARCH_COMMANDS, 'sed']
+const CHAIN_LABELS: ReadonlySet<string> = new Set(
+	CHAIN_COMMANDS.map((command) => time_shell.bash_label(command)),
+)
+
+type SearchFacts = Pick<ToolCall, 'label' | 'is_bundleable' | 'may_write' | 'is_writing'>
+
+// `may_write` over-calls, as the investigation guard's refusal test must.
+function is_read_only_search(call: SearchFacts): boolean {
+	return SEARCH_LABELS.has(call.label) && call.is_bundleable && !call.may_write
+}
+
+// `may_write` holds for every `sed`, so the chain asks `is_writing` — certain, and false for `sed -n`.
+function is_search_chain_call(call: SearchFacts): boolean {
+	return CHAIN_LABELS.has(call.label) && call.is_bundleable && !call.is_writing
+}
+
+const time_search_call = {
+	is_read_only_search,
+	is_search_chain_call,
+}
+
+export type { SearchFacts }
+export { time_search_call }

package/scripts/time-runtime/time-shell.ts

@@ -1,5 +1,5 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
-import { canonical_command } from '#scripts/josh/josh-command-map'
+import { canonical_command } from '#scripts/josh/josh-aliases'
 import { json_value } from '#scripts/lib/json-value'
 
 // Reading a shell command well enough to name what it ran.

package/scripts/time-runtime/time-transcript-line.ts

@@ -118,6 +118,9 @@ interface TranscriptLine {
 	// every line lacking an id would otherwise fall into one bucket spanning the whole file.
 	message_id: string
 	blocks: Array<Block>
+	// The reason a Stop-hook block sent this turn back with, its label stripped, or `''` for every
+	// other line.
+	stop_feedback: string
 	// The guard whose Stop-hook block sent this turn back, or `''` for every other line
 	// — read the way `Block.refusal_guard` is, off the reason's opening.
 	stop_guard: string
@@ -135,6 +138,11 @@ function block_names(raw: TranscriptBlock): Pick<Block, 'type' | 'name' | 'id' |
 	}
 }
 
+// The body a refusal opens with, the harness's own label stripped — shared with `rule-value.ts`.
+function refusal_body(text: string): string {
+	return text.trimStart().replace(HOOK_ERROR_LABEL, '')
+}
+
 // **A refusal is identified by what its body opens with, never by what it carries inside**.
 // The hook denies a call on behalf of the one guard whose trigger fired and
 // writes that guard's reason back as the whole result, so the speaker is the token after the `⛔` and
@@ -146,7 +154,7 @@ function block_names(raw: TranscriptBlock): Pick<Block, 'type' | 'name' | 'id' |
 // label is stripped before the opening is read. Without it no live refusal
 // carried a guard: the fixtures wrote the bare `⛔` body and passed while every recorded one read `''`.
 function guard_from_refusal(text: string): string {
-	const trimmed = text.trimStart().replace(HOOK_ERROR_LABEL, '')
+	const trimmed = refusal_body(text)
 	if (!trimmed.startsWith(REFUSAL_MARKER)) return ''
 
 	const headline = trimmed.slice(REFUSAL_MARKER.length).split('\n', 1)[0]?.trimStart() ?? ''
@@ -157,12 +165,12 @@ function guard_from_refusal(text: string): string {
 
 // **Only the harness's own feedback line counts.** It writes a Stop block back as a user turn whose
 // whole body is `Stop hook feedback:` and the reason, so a prompt that merely quotes one never opens
-// with the label and reads `''`.
-function stop_guard_of(data: TranscriptRecord): string {
+// with the label and reads `''`. The reason is kept whole, so `rule-value.ts` can match it to its row.
+function stop_feedback_of(data: TranscriptRecord): string {
 	const content = data.message?.content
 	if (typeof content !== 'string' || !STOP_FEEDBACK_LABEL.test(content)) return ''
 
-	return guard_from_refusal(content.replace(STOP_FEEDBACK_LABEL, ''))
+	return content.replace(STOP_FEEDBACK_LABEL, '').trim()
 }
 
 function token_lines_of(text: string): Array<string> {
@@ -254,12 +262,15 @@ function to_line(data: TranscriptRecord): TranscriptLine | undefined {
 
 	if (timestamp_ms === undefined) return undefined
 
+	const stop_feedback = stop_feedback_of(data)
+
 	return {
 		type: data.type ?? '',
 		timestamp_ms,
 		branch: data.gitBranch ?? UNKNOWN_BRANCH,
 		finished_background: finished_background(data),
-		stop_guard: stop_guard_of(data),
+		stop_feedback,
+		stop_guard: guard_from_refusal(stop_feedback),
 		...message_fields(data.message),
 	}
 }
@@ -282,6 +293,7 @@ const time_transcript_line = {
 	guard_from_refusal,
 	parse_line,
 	parse_text,
+	refusal_body,
 }
 
 export type { Block, TranscriptLine }

package/scripts/version/development-engines-verdict.ts

@@ -0,0 +1,124 @@
+import { readFileSync } from 'node:fs'
+import { isDeepStrictEqual } from 'node:util'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
+import { z } from 'zod'
+import { package_manager_version } from './package-manager-version'
+
+// The `devEngines` verdict a dependency update is judged by (`.claude/skills/dependency-update`):
+// the committed manifest against the working tree, printed as one line so nobody compares the two
+// strings by eye. `kept` is the lockstep pnpm bump — the version equal to the `packageManager` pin,
+// integrity suffix included — and `josh sync`'s `onFail` move from `error` to `download`; any other
+// change is `restore`, with the reason in brackets.
+const HEAD_PACKAGE_JSON = `HEAD:./${PACKAGE_JSON}`
+const NOT_JUDGED = `devEngines: not judged (no ${PACKAGE_JSON} at HEAD to compare against)`
+const PACKAGE_MANAGER_KEY = 'packageManager'
+const VERSION_KEY = 'version'
+const ON_FAIL_KEY = 'onFail'
+const ON_FAIL_FROM = 'error'
+const ON_FAIL_TO = 'download'
+const UNCHANGED = 'devEngines: unchanged'
+const KEPT = 'devEngines: kept'
+const SUFFIX_MISSING = 'integrity suffix missing'
+const NO_PIN = 'no pnpm@ packageManager pin to match'
+
+type Entries = Record<string, unknown>
+
+const entries_schema = z.record(z.string(), z.unknown())
+const manifest_schema = z.looseObject({
+	packageManager: z.string().default(''),
+	devEngines: entries_schema.default({}),
+})
+
+type Manifest = z.infer<typeof manifest_schema>
+
+function read_manifest(content: string): Manifest {
+	return manifest_schema.parse(JSON.parse(content))
+}
+
+function is_entries(value: unknown): value is Entries {
+	return entries_schema.safeParse(value).success
+}
+
+function read_package_manager(development_engines: Entries): Entries {
+	const value = development_engines[PACKAGE_MANAGER_KEY]
+
+	return is_entries(value) ? value : {}
+}
+
+// `packageManager` is compared key by key only when both sides are objects; the npm array form, or
+// a block added or removed whole, is a structural change in itself.
+function is_compared_inside(key: string, before: Entries, after: Entries): boolean {
+	return key === PACKAGE_MANAGER_KEY && is_entries(before[key]) && is_entries(after[key])
+}
+
+function changed_keys(before: Entries, after: Entries): Array<string> {
+	const keys = new Set([...Object.keys(before), ...Object.keys(after)])
+
+	return [...keys].filter((key) => !isDeepStrictEqual(before[key], after[key]))
+}
+
+// The version is judged against the pin below, so only its presence counts here.
+function is_expected_change(key: string, before: Entries, after: Entries): boolean {
+	if (key === VERSION_KEY) return typeof after[key] === 'string'
+
+	return key === ON_FAIL_KEY && before[key] === ON_FAIL_FROM && after[key] === ON_FAIL_TO
+}
+
+function find_structure_change(before: Entries, after: Entries): string | undefined {
+	const outer = changed_keys(before, after).filter((key) => !is_compared_inside(key, before, after))
+	const pm_before = read_package_manager(before)
+	const pm_after = read_package_manager(after)
+	const inner = changed_keys(pm_before, pm_after).filter(
+		(key) => !is_expected_change(key, pm_before, pm_after),
+	)
+	const keys = [...outer, ...inner.map((key) => `${PACKAGE_MANAGER_KEY}.${key}`)]
+
+	return keys.length === 0 ? undefined : `structure changed: ${keys.join(', ')}`
+}
+
+// Without a `pnpm@` pin there is nothing the version could be kept in lockstep with.
+function find_version_mismatch(after: Manifest): string | undefined {
+	const pin = package_manager_version.extract_pnpm_pin(after.packageManager)
+	if (pin === undefined) return NO_PIN
+	const current = String(read_package_manager(after.devEngines)[VERSION_KEY])
+	if (current === pin) return undefined
+	if (pin.startsWith(`${current}+`)) return SUFFIX_MISSING
+
+	return `version ${current} is not the packageManager pin ${pin}`
+}
+
+function judge(before_content: string, after_content: string): string {
+	const before = read_manifest(before_content).devEngines
+	const after = read_manifest(after_content)
+	if (isDeepStrictEqual(before, after.devEngines)) return UNCHANGED
+	const reason = find_structure_change(before, after.devEngines) ?? find_version_mismatch(after)
+
+	return reason === undefined ? KEPT : `devEngines: restore (${reason})`
+}
+
+// A manifest that does not parse is answered apart from every verdict rather than thrown, so the
+// overrides check that follows still runs.
+function judge_or_explain(head: string, current: string): string {
+	try {
+		return judge(head, current)
+	} catch (error) {
+		return `devEngines: not judged (${PACKAGE_JSON} unreadable: ${String(error)})`
+	}
+}
+
+function describe(head: string | undefined, current: string): string {
+	return head === undefined ? NOT_JUDGED : judge_or_explain(head, current)
+}
+
+// A `git show` that fails — no commit yet, no repository — answers apart from every verdict, so it
+// never reads as a `devEngines` block the update added.
+function report(): void {
+	const head = git_spawn_sync.read(['show', HEAD_PACKAGE_JSON])
+
+	console.info(describe(head, readFileSync(PACKAGE_JSON, 'utf8')))
+}
+
+const development_engines_verdict = { judge, describe, report }
+
+export { development_engines_verdict }

package/scripts/version/latest-corepack.ts

@@ -46,6 +46,7 @@ import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { execaSync } from 'execa'
 import semver from 'semver'
 import { z } from 'zod'
+import { development_engines_verdict } from './development-engines-verdict'
 import { npm_registry } from './npm-registry'
 import { package_manager_version } from './package-manager-version'
 import { release_age } from './release-age'
@@ -392,6 +393,7 @@ function main(): number {
 	const status = bump_to_registry_target(original, extract_pnpm_major(original))
 
 	sync_development_engines()
+	development_engines_verdict.report()
 
 	return status
 }

package/templates/gitignore

@@ -77,6 +77,8 @@ e2e/.auth/chrome-profile/
 # Claude Code runtime artifacts
 .claude/scheduled_tasks.lock
 .claude/tmp/
+# The machine-local permission allowlist (commands and paths), never shared
+.claude/settings.local.json
 
 # Scratch files any agent writes (Issue / PR bodies, plans, handoffs, logs); the rest of .josh/ is tracked
 .josh/tmp/

package/templates/workflows/ci.yml

@@ -247,6 +247,47 @@ jobs:
             echo 'size-limit is not installed — skipping the bundle-size check.'
           fi
 
+  # The pre-commit secretlint scan skips when its binary is missing and never runs on a commit made
+  # with `--no-verify`, so this job scans the pull request's changes again where neither applies
+  # (joshuafolkken/kit#4657). It needs no other job and none needs it, so it stays off the critical
+  # path, and its own `Secret Scan` context is what makes a finding block the merge. Only the files
+  # the pull request adds or changes are read: the merge commit's first parent is the base, which is
+  # why the checkout fetches two commits. secretlint comes from the same store cache every other job
+  # installs from, and `JOSH_SECRETLINT_REQUIRE` turns the hook's missing-binary skip into a failure.
+  # `shell: bash` adds `pipefail`, so a diff that fails cannot hand `xargs` an empty list and pass.
+  secret-scan:
+    name: Secret Scan
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          fetch-depth: 2
+
+      - name: Setup Node.js
+        uses: ./.github/actions/setup-node
+
+      - name: Configure GitHub Packages authentication for existing projects
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
+
+      - name: Setup pnpm and install dependencies
+        uses: ./.github/actions/setup-pnpm
+        with:
+          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scan the changed files for secrets
+        id: scan
+        shell: bash
+        env:
+          JOSH_SECRETLINT_REQUIRE: '1'
+        run: git diff -z --name-only --diff-filter=d HEAD^1 HEAD | xargs -0 -r pnpm josh secretlint-scan
+
   security:
     name: Security Audit
     runs-on: ubuntu-latest