@joshuafolkken/kit 1.929.0 → 1.953.0

package/dist/hooks/codex-hook-adapter.js

@@ -1,25 +1,25 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-YO43HEPY.js";
-import "./chunk-GQ3EVWHY.js";
+} from "./chunk-Z5TVZ4AP.js";
+import "./chunk-452OKRQX.js";
 import {
   build_envelope,
   compose_context,
   format_edited_payload
-} from "./chunk-LCJZE42I.js";
+} from "./chunk-IA7WC4NS.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-ROULPSQC.js";
-import "./chunk-NJZSO7BK.js";
-import "./chunk-BNFG2IFK.js";
-import "./chunk-I3JP3D4A.js";
-import "./chunk-7XQ6TK3R.js";
+import "./chunk-V7RH56HU.js";
+import "./chunk-NKVLBB65.js";
+import "./chunk-IBFC25IX.js";
+import "./chunk-M4U4YNRE.js";
+import "./chunk-OM5VDM6F.js";
 import {
   hook_decision
-} from "./chunk-SXPTRFPG.js";
+} from "./chunk-O3PEDF3M.js";
 import {
   time_density_hook
-} from "./chunk-2PGRQ62K.js";
+} from "./chunk-EYFJ74MJ.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 

package/dist/hooks/duplicate-read-guard.js

@@ -9,11 +9,11 @@ import {
   is_enabled,
   notice_refusal_path,
   refusal_path
-} from "./chunk-BNFG2IFK.js";
-import "./chunk-I3JP3D4A.js";
-import "./chunk-7XQ6TK3R.js";
-import "./chunk-SXPTRFPG.js";
-import "./chunk-2PGRQ62K.js";
+} from "./chunk-IBFC25IX.js";
+import "./chunk-M4U4YNRE.js";
+import "./chunk-OM5VDM6F.js";
+import "./chunk-O3PEDF3M.js";
+import "./chunk-EYFJ74MJ.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {

package/dist/hooks/format-edited.js

@@ -15,9 +15,9 @@ import {
   relative_to_root,
   resolve_invocations,
   select_invocation
-} from "./chunk-LCJZE42I.js";
+} from "./chunk-IA7WC4NS.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-2PGRQ62K.js";
+import "./chunk-EYFJ74MJ.js";
 import "./chunk-RKUAD3I6.js";
 export {
   ESLINT_DAEMON,

package/dist/hooks/investigation-guard.js

@@ -10,11 +10,11 @@ import {
   is_enabled,
   load_environment_file,
   refusal_path
-} from "./chunk-NJZSO7BK.js";
-import "./chunk-I3JP3D4A.js";
-import "./chunk-7XQ6TK3R.js";
-import "./chunk-SXPTRFPG.js";
-import "./chunk-2PGRQ62K.js";
+} from "./chunk-NKVLBB65.js";
+import "./chunk-M4U4YNRE.js";
+import "./chunk-OM5VDM6F.js";
+import "./chunk-O3PEDF3M.js";
+import "./chunk-EYFJ74MJ.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {

package/dist/hooks/pretool-guard.js

@@ -3,16 +3,16 @@ import {
   pretool_guard,
   pretool_outcome,
   pretool_outcome_async
-} from "./chunk-YO43HEPY.js";
-import "./chunk-GQ3EVWHY.js";
+} from "./chunk-Z5TVZ4AP.js";
+import "./chunk-452OKRQX.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-ROULPSQC.js";
-import "./chunk-NJZSO7BK.js";
-import "./chunk-BNFG2IFK.js";
-import "./chunk-I3JP3D4A.js";
-import "./chunk-7XQ6TK3R.js";
-import "./chunk-SXPTRFPG.js";
-import "./chunk-2PGRQ62K.js";
+import "./chunk-V7RH56HU.js";
+import "./chunk-NKVLBB65.js";
+import "./chunk-IBFC25IX.js";
+import "./chunk-M4U4YNRE.js";
+import "./chunk-OM5VDM6F.js";
+import "./chunk-O3PEDF3M.js";
+import "./chunk-EYFJ74MJ.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {

package/dist/hooks/stop-guard.js

@@ -5,6 +5,7 @@ import {
   filing_cap,
   git_gh_api_path,
   git_gh_exec,
+  lane_background,
   lane_child_invocation,
   lane_park,
   lane_registry,
@@ -15,20 +16,20 @@ import {
   run_hold,
   run_invocation,
   run_watcher_guard
-} from "./chunk-GQ3EVWHY.js";
+} from "./chunk-452OKRQX.js";
 import {
   session_language
 } from "./chunk-6V5OPIUU.js";
 import {
   hook_decision,
   lane_child_marker
-} from "./chunk-SXPTRFPG.js";
+} from "./chunk-O3PEDF3M.js";
 import {
   PROJECT_ROOT,
   stamp_file,
   time_density_hook,
   time_hook_transcript
-} from "./chunk-2PGRQ62K.js";
+} from "./chunk-EYFJ74MJ.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 
@@ -1186,8 +1187,12 @@ function count_headless_refusals(tail) {
   const last_wait = Math.max(...HEADLESS_WAIT_CALLS.map((call) => tail.lastIndexOf(call)));
   return tail.slice(Math.max(last_wait, 0)).split(HEADLESS_WAIT_MARKER).length - 1;
 }
+function needs_background_wait(context) {
+  return context.lane_child && context.background_pending;
+}
 function hold_reason(context) {
   if (needs_index_route(context)) return LANE_INDEX_REASON;
+  if (needs_background_wait(context)) return lane_background.LANE_BACKGROUND_STOP_REASON;
   if (needs_notify(context)) return STOP_NOTIFY_REASON;
   if (needs_release(context)) return HOLD_RELEASE_REASON;
   return void 0;
@@ -1558,6 +1563,7 @@ async function build_context(transcript_path, payload_tail) {
     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()),
+    background_pending: lane_background.pending_background_ids(tail).length > 0,
     session_lang: session_lang()
   };
 }

package/dist/josh.js

@@ -262,7 +262,6 @@ var ENV_FILE_NAME = ".env";
 // scripts/josh/josh-command-types.ts
 var OPTIONAL_ENV_FILE_FLAGS = [`--env-file-if-exists=${ENV_FILE_NAME}`];
 var GATE_COMMAND = "gate";
-var PE = ["pnpm", "exec"];
 var ESLINT_CACHE_FILE = ".eslintcache";
 var TS_BUILD_INFO_FILE = ".tsbuildinfo";
 var CSPELL_CACHE_FILE = ".cspellcache";
@@ -300,7 +299,6 @@ function content_cache_flags(cache_file) {
 var ESLINT_CACHE_FLAGS = content_cache_flags(ESLINT_CACHE_FILE);
 var ESLINT_EDIT_CACHE_FLAGS = content_cache_flags(ESLINT_EDIT_CACHE_FILE);
 var ESLINT_RELATED_CACHE_FLAGS = content_cache_flags(ESLINT_RELATED_CACHE_FILE);
-var TS_CACHE_FLAGS = ["--incremental", "--tsBuildInfoFile", TS_BUILD_INFO_FILE];
 var CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE);
 
 // scripts/josh/josh-commands-backlog.ts
@@ -659,6 +657,12 @@ var AI_COMMANDS = {
     reference: ["[issue|--force]", "automation", ["files"]],
     default_script_arguments: ["--release"]
   },
+  "run:tidy": {
+    script: "scripts/run/run-tidy-cli.ts",
+    description: "Close merged lanes and drop stashes whose issues are all merged",
+    category: "AI tools",
+    reference: ["", "automation", ["git", "network", "files"]]
+  },
   "run:carry": {
     script: "scripts/run/run-carry-cli.ts",
     description: "Carry one invocation\u2019s budget across its own session cuts",
@@ -855,7 +859,7 @@ var DEV_COMMANDS = {
   },
   lint: {
     script: "scripts/lint/lint-parallel.ts",
-    description: "Check code with prettier and eslint",
+    description: "Check code with prettier and eslint (skips a tool a static project lacks)",
     category: "Development",
     reference: ["", "developer", ["processes"]]
   },
@@ -891,7 +895,7 @@ var DEV_COMMANDS = {
   },
   format: {
     script: "scripts/lint/format.ts",
-    description: "Format code with prettier and eslint",
+    description: "Format code with prettier and eslint (skips a tool a static project lacks)",
     category: "Development",
     reference: ["", "developer", ["files", "processes"]]
   },
@@ -1003,8 +1007,8 @@ var DEV_COMMANDS = {
     argument_targets: ["test:unit", "test:e2e"]
   },
   check: {
-    shell: [...PE, "tsc", "--noEmit", ...TS_CACHE_FLAGS],
-    description: "Type-check TypeScript project",
+    script: "scripts/gate/type-check-command.ts",
+    description: "Type-check with tsc (skips a static project with no TypeScript to check)",
     category: "Development",
     reference: ["[arguments...]", "developer", ["processes"]]
   },
@@ -1502,6 +1506,7 @@ var ALIASES = {
   rh: "run:hold",
   rr: "run:release",
   rc: "run:carry",
+  rtd: "run:tidy",
   rw: "run:wake",
   rct: "run:cut",
   rv: "run:liveness",

package/dist/version/index.js

@@ -163,9 +163,12 @@ var NO_QUARANTINE_MINUTES = 0;
 var NPMRC_PATH = ".npmrc";
 var release_times_schema = z2.record(z2.string(), z2.string());
 var MS_PER_MINUTE = 6e4;
-function parse_minimum_release_age(npmrc_content) {
+function parse_declared_minimum_release_age(npmrc_content) {
   const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1];
-  return raw === void 0 ? NO_QUARANTINE_MINUTES : Number(raw);
+  return raw === void 0 ? void 0 : Number(raw);
+}
+function parse_minimum_release_age(npmrc_content) {
+  return parse_declared_minimum_release_age(npmrc_content) ?? NO_QUARANTINE_MINUTES;
 }
 function is_on_major(version, major) {
   return major === void 0 || String(semver.major(version)) === major;
@@ -184,8 +187,7 @@ function select_aged_version(times, major, minimum_age_minutes, now_ms) {
 }
 function read_declared_minimum_release_age(npmrc_path) {
   try {
-    const raw = MINIMUM_RELEASE_AGE_RE.exec(readFileSync2(npmrc_path, "utf8"))?.[1];
-    return raw === void 0 ? void 0 : Number(raw);
+    return parse_declared_minimum_release_age(readFileSync2(npmrc_path, "utf8"));
   } catch {
     return void 0;
   }
@@ -206,6 +208,7 @@ function read_nearest_minimum_release_age(start, boundary) {
 var release_age = {
   release_times_schema,
   parse_minimum_release_age,
+  parse_declared_minimum_release_age,
   read_minimum_release_age,
   read_nearest_minimum_release_age,
   select_aged_version

package/package.json

@@ -1,6 +1,17 @@
 {
-  "version": "1.929.0",
+  "version": "1.953.0",
   "name": "@joshuafolkken/kit",
+  "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
+  "keywords": [
+    "ai",
+    "claude-code",
+    "cli",
+    "developer-tools",
+    "eslint",
+    "prettier",
+    "toolkit",
+    "workflow"
+  ],
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -177,6 +188,7 @@
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "@playwright/test": "^1.63.0",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.6",
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/node": "^26.6.3",

package/prompts/collaboration-workflow/issue-template.md

@@ -76,7 +76,7 @@ Issue には次の要素を必ず含める。
 - **互換性を壊す変更は影響を本文で宣言する。** 既存の利用者、API、設定の契約を変える場合は、`## 背景` の直下に `- 互換性: 破壊的変更` を書き、廃止対象と影響を説明する。移行措置や事前案内があっても破壊的変更なら宣言する。`pnpm josh issue:lint <本文ファイル>` が `labels: breaking-change` を返したら、同じ作成呼び出しに `-f 'labels[]=breaking-change'` を付ける。互換性を保つ変更には付けない。影響が曖昧なら起票文案で対象の利用者と契約を明確にしてから分類する
 - **`issue:lint` が返す分類ラベルをすべて起票時に指定する。** `bug`、`enhancement`、`breaking-change` は組み合わせて表示されることがある。`depth`・`route` など既存のラベルを残し、`labels: none` のときは分類ラベルを付けない。Issue が `enhancement` と `breaking-change` の両方を持つとき、PR のリリース分類は `breaking-change` 一つにする。Issue の目的の分類と PR のリリース分類を区別する
 - **`## 発火点`** には、その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つ書く。名前は `prompts/collaboration-workflow/rule-delivery.md` の配送表に載る、フックで配送可能なツール（`Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）と突き合わせる。**表に無い名前**（そもそもツールコール名でない）と**不一致**（既知のツールだが配送できない）は区別して印字され、joshuafolkken/kit#2201 の「規則は正しいが名指ししたコールが実際に破れるコールの 1 つ後ろ」を起票時に検出する
-- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `pnpm josh measure:rerun` が同じコマンドをやり直し、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/observations.md` に 1 行追記される（既存の append-only 台帳をそのまま使い、第 2 の台帳は作らない）
+- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `pnpm josh measure:rerun` が同じコマンドをやり直し、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/maintainers/observations.md` に 1 行追記される（既存の append-only 台帳を使い、別の台帳は作らない）
 - **`## 再現`** は **「コマンド + 実際の出力」** で書く。コマンドを backtick、出力をフェンス（``` または ~~~）で囲む。自然文の「確認した」は再実行できないため受け付けない（`## ベースライン` と同じ理由）。読みだけの起票を起票時に弾くためである
 - **検査は `pnpm josh issue:lint <path>` が行う。** 対象判定・3 見出しの有無・発火点の配送可否・ベースラインが「コマンド + 値」か・再現が「コマンド + 実際の出力」かと、起票時に必要な分類ラベルを、起票前の本文ファイルからまとめて答える（未リントの起票は `pnpm josh rule:guard` が拒否する）
 

package/scripts/ci/pr-classification.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import { execaSync } from 'execa'
 import { z } from 'zod'
 
 const BUGFIX = 'bugfix'
@@ -19,9 +20,10 @@ const LEGACY_LABELS: ReadonlySet<string> = new Set(['semver-major', 'semver-mino
 
 const LABEL = z.object({ name: z.string() })
 const USER = z.object({ login: z.string() })
-const PULL_REQUEST = z.object({ user: USER, labels: z.array(LABEL) })
+const PULL_REQUEST = z.object({ number: z.number(), user: USER })
 const EVENT = z.object({
 	pull_request: PULL_REQUEST,
+	repository: z.object({ full_name: z.string() }),
 })
 
 function classification_error(labels: ReadonlyArray<string>, author: string): string | undefined {
@@ -83,13 +85,32 @@ function select_issue_classification(issue_json: string): ReleaseClassification
 	return label
 }
 
-function check_event(event_path: string): string | undefined {
+// The labels as they stand when the check runs, not as the event carried them. `josh pr` opens the
+// pull request and labels it in a second call, so the `opened` event carries none; judged from the
+// payload, that run fails, and when it lands in the newer check suite GitHub keeps its red result —
+// a rerun replays the same payload and fails again (joshuafolkken/kit#2712).
+function fetch_current_labels(repository: string, pull_number: number): ReadonlyArray<string> {
+	const result = execaSync(
+		'gh',
+		['api', `repos/${repository}/issues/${String(pull_number)}/labels`, '--jq', '.[].name'],
+		{ reject: false },
+	)
+
+	if (result.exitCode !== 0) {
+		throw new Error(`Could not read the pull request labels: ${result.stderr}`)
+	}
+
+	return result.stdout.split('\n').filter((name) => name !== '')
+}
+
+function check_event(
+	event_path: string,
+	read_labels: typeof fetch_current_labels = fetch_current_labels,
+): string | undefined {
 	const event = EVENT.parse(JSON.parse(readFileSync(event_path, 'utf8')))
+	const labels = read_labels(event.repository.full_name, event.pull_request.number)
 
-	return classification_error(
-		event.pull_request.labels.map((label) => label.name),
-		event.pull_request.user.login,
-	)
+	return classification_error(labels, event.pull_request.user.login)
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/document/document-byte-budget.ts

@@ -82,7 +82,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/rule-residency.md', bytes: 24_576 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands.md', bytes: 163_840 },
+	{ path: 'docs/josh-commands.md', bytes: 167_936 },
 	{ path: 'prompts/agent-rules.md', bytes: 4096 },
 	{ path: 'prompts/coding-standards.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

package/scripts/gate/hook-gate-reuse.ts

@@ -53,7 +53,7 @@ function is_force_requested(force_environment: string): boolean {
 // nothing" for "git could not be asked". Every predicate below treats the two differently.
 //
 // **The observation ledger is dropped from the reading, and it is the one line that may be**
-// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes `docs/observations.md` from
+// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes the ledger from
 // what it stages, so a parent's appended line sits modified-but-never-staged for the whole interval
 // between the append and the next `pnpm josh observations:flush` — and every condition below reads a
 // non-empty status as "this operation carries a tree no check has read". Left in, one ledger line

package/scripts/gate/project-checks.ts

@@ -2,6 +2,7 @@ import { existsSync, globSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
+import { z } from 'zod'
 
 const PACKAGE_JSON = 'package.json'
 const IGNORED_DIRS = new Set([
@@ -36,6 +37,8 @@ const CSPELL_CONFIGS = [
 	'cspell.yaml',
 ]
 const TYPE_CONFIGS = ['tsconfig.json', 'jsconfig.json']
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies']
+const object_schema = z.record(z.string(), z.unknown())
 
 function project_root(directory: string): string {
 	let current = directory
@@ -78,50 +81,77 @@ function is_static_manifest(manifest: unknown): boolean {
 	return josh.profile === 'static'
 }
 
-function is_static(directory: string): boolean {
+function read_manifest(directory: string): unknown {
 	try {
 		const manifest_path = path.join(project_root(directory), PACKAGE_JSON)
-		const manifest: unknown = JSON.parse(readFileSync(manifest_path, 'utf8'))
 
-		return is_static_manifest(manifest)
+		return JSON.parse(readFileSync(manifest_path, 'utf8'))
 	} catch {
-		return false
+		return undefined
 	}
 }
 
+function is_static(directory: string): boolean {
+	return is_static_manifest(read_manifest(directory))
+}
+
+function is_declared(directory: string, package_name: string): boolean {
+	const manifest = object_schema.safeParse(read_manifest(directory))
+	if (!manifest.success) return false
+
+	return DEPENDENCY_FIELDS.some((field) => {
+		const dependencies = object_schema.safeParse(manifest.data[field])
+
+		return dependencies.success && Object.hasOwn(dependencies.data, package_name)
+	})
+}
+
+// A tool the manifest lists but `node_modules` lacks is a project that has not run `pnpm install`
+// yet — typically right after `josh init` added it (joshuafolkken/kit#2709). Skipping it would pass a
+// check the configuration asks for without running it, so only an undeclared tool is skipped; a
+// declared one is run and fails until it is installed.
+function missing_tool_reason(
+	directory: string,
+	package_name: string,
+	bin_name: string,
+): string | undefined {
+	if (has_bin(directory, bin_name) || is_declared(directory, package_name)) return undefined
+
+	return `${package_name} is not installed`
+}
+
 function skip_notice(check: string, reason: string): string {
 	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}.`
 }
 
+// Shared by `josh check` and the gate's type-check step, so neither reaches `tsc` on a static
+// project that has nothing to type-check (joshuafolkken/kit#2709).
 function type_check_skip_reason(directory: string): string | undefined {
 	if (!is_static(directory)) return undefined
 	if (!has_files(directory, TYPE_FILES)) return 'no TypeScript files were found'
 	if (!has_config(directory, TYPE_CONFIGS)) return 'no TypeScript configuration was found'
-	if (!has_bin(directory, 'tsc')) return 'typescript is not installed'
 
-	return undefined
+	return missing_tool_reason(directory, 'typescript', 'tsc')
 }
 
-// Shared by `josh lint` and `josh format`, so a static project without Web files — a Python or Rust
-// project, which `josh init` gives no Prettier — is skipped for the same reason by both
-// (joshuafolkken/kit#2606).
+// Shared by `josh lint`, `josh lint:related` and `josh format`, so a static project without Web
+// files — a Python or Rust project, which `josh init` gives no Prettier — is skipped for the same
+// reason by all three (joshuafolkken/kit#2606, joshuafolkken/kit#2709).
 function prettier_skip_reason(directory: string): string | undefined {
 	if (!is_static(directory)) return undefined
 	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
-	if (!has_bin(directory, 'prettier')) return 'prettier is not installed'
 
-	return undefined
+	return missing_tool_reason(directory, 'prettier', 'prettier')
 }
 
-// Shared by `josh lint` and `josh format`, so a static project without ESLint is skipped for the
-// same reason by both (joshuafolkken/kit#2693).
+// Shared by `josh lint`, `josh lint:related` and `josh format`, so a static project without ESLint
+// is skipped for the same reason by all three (joshuafolkken/kit#2693, joshuafolkken/kit#2709).
 function eslint_skip_reason(directory: string): string | undefined {
 	if (!is_static(directory)) return undefined
 	if (!has_files(directory, SCRIPT_FILES)) return 'no JavaScript or TypeScript files were found'
 	if (!has_config(directory, ESLINT_CONFIGS)) return 'no ESLint configuration was found'
-	if (!has_bin(directory, 'eslint')) return 'eslint is not installed'
 
-	return undefined
+	return missing_tool_reason(directory, 'eslint', 'eslint')
 }
 
 const project_checks = {

package/scripts/gate/type-check-command.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { TS_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { execa } from 'execa'
+import { project_checks } from './project-checks'
+
+// `josh check` — the project-wide TypeScript check. It used to be a bare `tsc --noEmit` shell entry,
+// so on a static project with nothing to type-check it failed with `Command "tsc" not found` while
+// the gate, which asks `type_check_skip_reason` first, skipped the same step
+// (joshuafolkken/kit#2709). Both now read that one decision.
+
+const ARGV_OFFSET = 2
+const FAIL_EXIT_CODE = 1
+const TSC_ARGS = ['exec', 'tsc', '--noEmit', ...TS_CACHE_FLAGS] as const
+
+async function run_type_check(
+	command_arguments: ReadonlyArray<string>,
+	directory: string,
+): Promise<number> {
+	const reason = project_checks.type_check_skip_reason(directory)
+
+	if (reason !== undefined) {
+		console.info(project_checks.skip_notice('check', reason))
+
+		return 0
+	}
+
+	const result = await execa('pnpm', [...TSC_ARGS, ...command_arguments], {
+		cwd: directory,
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_type_check(process.argv.slice(ARGV_OFFSET), process.cwd())
+}
+
+const type_check_command = { run_type_check }
+
+export { TSC_ARGS, type_check_command }

package/scripts/git/constants.ts

@@ -9,6 +9,9 @@ const GIT_COMMAND_UNIX = '/usr/bin/git'
 // here rather than beside either of them because `status` and `worktree_list` now sit in different
 // modules (joshuafolkken/kit#1640) and a copy in each is a second answer to one question.
 const PORCELAIN_FLAG = '--porcelain'
+// The untracked-files mode every porcelain status reading passes (`git-command.ts` carries why it is
+// passed and why it is `all`), shared so `run-carry-flush.ts`'s own reading cannot drift from it.
+const UNTRACKED_FILES_FLAG = '--untracked-files=all'
 
 function get_git_command(): string {
 	if (platform() === 'win32') {
@@ -37,5 +40,6 @@ export {
 	UNTRACKED_FILE_PREFIX,
 	SEPARATOR_LINE,
 	PORCELAIN_FLAG,
+	UNTRACKED_FILES_FLAG,
 	git_utilities,
 }

package/scripts/git/git-command.ts

@@ -1,4 +1,4 @@
-import { PORCELAIN_FLAG } from './constants'
+import { PORCELAIN_FLAG, UNTRACKED_FILES_FLAG } from './constants'
 import { git_push_transport } from './git-push-transport'
 import { git_spawn } from './git-spawn'
 
@@ -6,15 +6,21 @@ async function branch(): Promise<string> {
 	return await git_spawn.read(['rev-parse', '--abbrev-ref', 'HEAD'])
 }
 
-// **`--untracked-files=normal` is passed rather than inherited** (joshuafolkken/kit#1381). Every
+// **The untracked-files mode is passed rather than inherited** (joshuafolkken/kit#1381). Every
 // reader of this output depends on the `??` lines being there: `git-staging.ts` stages exactly those,
 // and `hook-gate-reuse.ts` reads an empty output as "this push carries the recorded tree". A person
 // with `status.showUntrackedFiles=no` in their git config — a common setting on large repositories —
 // gets porcelain output with those lines silently absent, so untracked files go unstaged and the
-// pre-push hook reuses a record for a commit that does not contain them. Naming git's own default
-// makes the reading answer to this codebase rather than to whoever ran it.
+// pre-push hook reuses a record for a commit that does not contain them. Naming the mode makes the
+// reading answer to this codebase rather than to whoever ran it.
+//
+// **`all` rather than `normal`, so a new file is named even inside an untracked directory**
+// (joshuafolkken/kit#2724). `normal` collapses it to `?? docs/maintainers/`, and every reader that
+// recognizes the observation ledger by its path then misses it: `git-staging.ts` stages the directory
+// — ledger included — into an unrelated pull request, and the flush refuses the directory as "other
+// changes".
 async function status(): Promise<string> {
-	return await git_spawn.read(['status', PORCELAIN_FLAG, '--untracked-files=normal'])
+	return await git_spawn.read(['status', PORCELAIN_FLAG, UNTRACKED_FILES_FLAG])
 }
 
 // The absolute path every other git command's output is relative to. Asking git rather than reading