@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/issue/issue-cite-cli.ts

@@ -101,16 +101,26 @@ async function local_slug_for(targets: ReadonlyArray<CiteTarget>): Promise<strin
 	return has_bare_target ? await git_gh_command.repo_get_name_with_owner() : undefined
 }
 
+// The citation lines and the failure lines of one invocation, apart.
+interface CiteReport {
+	lines: ReadonlyArray<string>
+	failures: ReadonlyArray<string>
+}
+
+function split_results(results: ReadonlyArray<LineResult>): CiteReport {
+	return {
+		lines: results.filter((result) => result.kind === 'ok').map((result) => result.line),
+		failures: results.filter((result) => result.kind === 'fail').map((result) => result.line),
+	}
+}
+
 // Citations to stdout so the block stays paste-ready; failures to stderr so each unanswered number is
 // named without landing in what gets pasted. A failure sets a non-zero exit.
-function report(results: ReadonlyArray<LineResult>): number {
-	const lines = results.filter((result) => result.kind === 'ok').map((result) => result.line)
-	const failures = results.filter((result) => result.kind === 'fail').map((result) => result.line)
-
-	if (lines.length > 0) console.info(lines.join(LINE_SEPARATOR))
-	for (const failure of failures) console.error(failure)
+function report(cited: CiteReport): number {
+	if (cited.lines.length > 0) console.info(cited.lines.join(LINE_SEPARATOR))
+	for (const failure of cited.failures) console.error(failure)
 
-	return failures.length === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	return cited.failures.length === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
 // The targets the command line names, or `undefined` for a line nobody can read — an unknown flag and
@@ -122,14 +132,11 @@ function read_targets(args: ReadonlyArray<string>): ReadonlyArray<CiteTarget> |
 	return parse_targets(parsed.positionals, parsed.values.repo)
 }
 
-async function run(args: ReadonlyArray<string>): Promise<number> {
+// The lines `issue:cite` prints for `args`, without printing them — the `Stop` hook shows them itself
+// (`stop-actions.ts`). `undefined` for a line nobody can read.
+async function cite(args: ReadonlyArray<string>): Promise<CiteReport | undefined> {
 	const targets = read_targets(args)
-
-	if (targets === undefined) {
-		console.error(USAGE)
-
-		return FAILURE_EXIT_CODE
-	}
+	if (targets === undefined) return undefined
 
 	const local_slug = await local_slug_for(targets)
 	const results = await bounded_pool.bounded_map(
@@ -138,7 +145,19 @@ async function run(args: ReadonlyArray<string>): Promise<number> {
 		async (target) => await cite_target(target, local_slug),
 	)
 
-	return report(results)
+	return split_results(results)
+}
+
+async function run(args: ReadonlyArray<string>): Promise<number> {
+	const cited = await cite(args)
+
+	if (cited === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return report(cited)
 }
 
 async function main(args: ReadonlyArray<string>): Promise<void> {
@@ -147,6 +166,7 @@ async function main(args: ReadonlyArray<string>): Promise<void> {
 
 const issue_cite_cli = {
 	USAGE,
+	cite,
 	parse_targets,
 	run,
 }

package/scripts/issue/issue-classification.ts

@@ -2,7 +2,7 @@ import { issue_bug_label } from './issue-bug-label'
 import { BREAKING_CHANGE_LABEL, BUG_LABEL, ENHANCEMENT_LABEL, has_label_name } from './issue-labels'
 import { markdown_section } from './markdown-section'
 
-const FEATURE_DECLARATIONS = ['- 目的: 機能追加', '- 目的: 機能改善']
+const FEATURE_DECLARATIONS = ['- 目的: 機能追加', '- 目的: 機能改善', '- 目的: 時間短縮']
 const BREAKING_DECLARATION = '- 互換性: 破壊的変更'
 const NON_BUG_DECLARATION = '- 種別: 非不具合'
 const CLASSIFICATION_LABELS = [BUG_LABEL, ENHANCEMENT_LABEL, BREAKING_CHANGE_LABEL]

package/scripts/issue/issue-lint-cli.ts

@@ -2,6 +2,7 @@
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { behavior_change_lint } from './behavior-change-lint'
+import { expected_effect_lint } from './expected-effect-lint'
 import { issue_classification } from './issue-classification'
 import { issue_lint } from './issue-lint'
 
@@ -9,7 +10,7 @@ import { issue_lint } from './issue-lint'
 // one per line, exiting non-zero. It reads a path rather than stdin so it can
 // lint a body written to a file before the `gh api … issues` call that files it. A body that declares
 // itself a behavior-change Issue is additionally held to the firing-point, baseline and reproduction
-// rules.
+// rules, and one that declares a run-time-shortening aim to the expected-effect estimate.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -17,14 +18,15 @@ const OK_MESSAGE = 'ok'
 const NO_LABELS = 'none'
 const USAGE = 'Usage: josh issue:lint <path-to-issue-body>'
 
-// Every problem a body has: the four base template headings it lacks, then the behavior-change
-// problems (empty for an Issue that does not declare itself one).
+// Every problem a body has: the four base template headings it lacks, then the behavior-change and
+// expected-effect problems (each empty for an Issue that does not declare itself one).
 function problems(body: string): ReadonlyArray<string> {
 	const missing = issue_lint.missing_headings(body).map((heading) => `missing heading: ${heading}`)
 
 	return [
 		...missing,
 		...behavior_change_lint.problems(body),
+		...expected_effect_lint.problems(body),
 		...issue_classification.problems(body),
 	]
 }

package/scripts/issue/issue-scout-cli.ts

@@ -103,7 +103,7 @@ function draft_of(args: ScoutArguments, repo: string): BacklogIssue {
 }
 
 // The epic beside a candidate is the placement answer for a draft that cites nothing: the epic half
-// below decides from prose references, and a title-only draft has none to give it.
+// below decides from signal references, and a title-only draft has none to give it.
 function format_duplicate(candidate: DuplicateCandidate): string {
 	const score = candidate.is_referenced === true ? 'ref' : candidate.score.toFixed(SCORE_DIGITS)
 	const epic = candidate.epic === undefined ? '' : ` (epic ${session_cite.issue(candidate.epic)})`
@@ -162,12 +162,13 @@ function format_epic(decision: BundleDecision): Array<string> {
 	return lines
 }
 
-// A draft cites nothing, so the epic half has nothing to decide from: its two signals are prose
-// references and recorded dependencies, and a title carries neither. Saying "file it standalone" there
-// reports a scan that found nothing when none was possible — the confident wrong answer the gap
+// A draft cites nothing where a citation counts, so the epic half has nothing to decide from: its two
+// signals are references in the acceptance criteria or the `parent: #N` line and recorded
+// dependencies, and a title or a background mention carries neither. Saying "file it standalone"
+// there reports a scan that found nothing when none was possible — the confident wrong answer the gap
 // warnings exist to prevent everywhere else in this command.
 const NO_REFERENCE_LINE =
-	'Epic: not asked — no issue number in the summary. Pass --body "…#<N>…", or take the epic printed beside a duplicate above.'
+	'Epic: not asked — no issue number in the summary\'s acceptance criteria or parent line. Pass --body "parent: #<N>", or take the epic printed beside a duplicate above.'
 
 // Every placing verdict above asserts that no epic already tracks the draft's relatives, and a cut
 // epic listing cannot support that: `epic:bundle` withholds them for it,
@@ -195,18 +196,22 @@ function format_epic_decision(
 	return format_epic(decision).join('\n')
 }
 
-// Whether the summary names an issue at all, read through the same parser the decision itself uses —
-// a second reading of "does this body cite anything" could disagree with the one that matters.
-function has_reference(draft: BacklogIssue): boolean {
-	return epic_audit_logic.parse_references(draft.body, draft.repo).length > 0
+// The issue numbers the summary names where `decide_bundle` counts a reference — its acceptance
+// criteria and its `parent: #N` line — read through the same parser the decision itself uses: a
+// second reading of "does this body cite anything" could disagree with the one that matters, and an
+// issue cited only as the background of the filing is not one the draft belongs with.
+function signal_numbers(draft: BacklogIssue): Array<number> {
+	return epic_audit_logic
+		.signal_references(draft.body, draft.repo)
+		.map((reference) => reference.number)
 }
 
 // The open epics the summary names outright. `decide_bundle` excludes an epic from the candidate pool
-// — a container is not a sibling — so a draft saying "part of epic #1153", which is the phrasing the
-// workflow documents themselves suggest, otherwise reaches `none` and is told to file standalone with
-// the epic it named never mentioned.
+// — a container is not a sibling — so a draft whose `parent: #1153` line names the epic, which is the
+// phrasing the workflow documents themselves suggest, otherwise reaches `none` and is told to file
+// standalone with the epic it named never mentioned.
 function named_epics(draft: BacklogIssue, issues: ReadonlyArray<BacklogIssue>): Array<number> {
-	const named = new Set(epic_audit_logic.parse_references(draft.body, draft.repo))
+	const named = new Set(signal_numbers(draft))
 
 	return issues
 		.filter((issue) => issue.is_epic === true && named.has(issue.number))
@@ -241,7 +246,7 @@ function format_epic_answer(
 
 	if (named.length > 0) return format_named_epics(named, decision).join('\n')
 
-	return format_epic_decision(decision, has_reference(draft), is_membership_established)
+	return format_epic_decision(decision, signal_numbers(draft).length > 0, is_membership_established)
 }
 
 // The closed rows reach the duplicate half only. `decide_bundle` places a draft among issues that

package/scripts/issue/markdown-section.ts

@@ -3,6 +3,9 @@
 // way, so the slicing lives in one place rather than being written twice.
 
 const HEADING_PREFIX = '## '
+// A body saved from GitHub's web editor ends its lines with CRLF; a kept `\r` would end every line's
+// text with it and defeat each `$`-anchored match downstream.
+const LINE_BREAK_PATTERN = /\r?\n/u
 
 function is_heading(line: string): boolean {
 	return line.trimStart().startsWith(HEADING_PREFIX)
@@ -29,21 +32,31 @@ function next_fence(line: string, fence: string): string | undefined {
 	return undefined
 }
 
-function unfenced_lines(body: string): ReadonlyArray<string> {
+function lines_of(body: string): ReadonlyArray<string> {
+	return body.split(LINE_BREAK_PATTERN)
+}
+
+// The body's lines with every fenced line, fences included, blanked. Indentation is kept, so a list
+// item's indented continuation survives.
+function fence_free_lines(body: string): ReadonlyArray<string> {
 	let fence = ''
 	const visible: Array<string> = []
 
-	for (const line of body.split('\n')) {
+	for (const line of lines_of(body)) {
 		const next = next_fence(line, fence)
-		const visible_line = line.replace(/^(?: {4}|\t).*/u, '')
 
-		visible.push(next === undefined && fence === '' ? visible_line : '')
+		visible.push(next === undefined && fence === '' ? line : '')
 		fence = next ?? fence
 	}
 
 	return visible
 }
 
+// As `fence_free_lines`, with an indented code line (4 spaces or a tab) blanked too.
+function unfenced_lines(body: string): ReadonlyArray<string> {
+	return fence_free_lines(body).map((line) => line.replace(/^(?: {4}|\t).*/u, ''))
+}
+
 function has_unfenced_line(body: string, text: string): boolean {
 	return unfenced_lines(body).some((line) => line.trim() === text)
 }
@@ -59,7 +72,7 @@ function section_lines_matching(
 	body: string,
 	is_target: (line: string) => boolean,
 ): ReadonlyArray<string> {
-	const lines = body.split('\n')
+	const lines = lines_of(body)
 	const visible = unfenced_lines(body)
 	const start = visible.findIndex((line) => is_target(line))
 
@@ -80,6 +93,7 @@ function section_lines(body: string, heading: string): ReadonlyArray<string> {
 const markdown_section = {
 	section_lines,
 	section_lines_matching,
+	fence_free_lines,
 	unfenced_lines,
 	has_line,
 	has_unfenced_line,

package/scripts/josh/command-usage.ts

@@ -0,0 +1,110 @@
+import { canonical_command, COMMAND_MAP } from './josh-command-map'
+import type { CommandUsage } from './josh-command-types'
+import { AUTOMATION_USAGE } from './josh-usage-automation'
+import { BACKLOG_USAGE } from './josh-usage-backlog'
+import { DEVELOPER_USAGE } from './josh-usage-developer'
+import { HOOK_USAGE } from './josh-usage-hooks'
+import { ISSUE_USAGE } from './josh-usage-issue'
+import { REVIEW_USAGE } from './josh-usage-review'
+import { RUN_USAGE } from './josh-usage-run'
+import { SESSION_USAGE } from './josh-usage-session'
+import { WORKFLOW_USAGE } from './josh-usage-workflow'
+
+// The single renderer of a command's usage. `josh help <command>` prints it and
+// `scripts/document/generate-command-usage.ts` writes it between a reference page's usage markers,
+// so the terminal and the page are one text (#3932).
+
+type UsageTable = Readonly<Record<string, CommandUsage>>
+
+// Which reference page renders each usage table — the one place a table is tied to its page, so the
+// generator's coverage check and `josh help` read the same set (#3981).
+/* eslint-disable @typescript-eslint/naming-convention */
+const USAGE_PAGE_TABLES: Readonly<Record<string, ReadonlyArray<UsageTable>>> = {
+	'docs/josh-commands.md': [DEVELOPER_USAGE],
+	'docs/josh-commands-run.md': [RUN_USAGE, SESSION_USAGE],
+	'docs/josh-commands-backlog.md': [ISSUE_USAGE, BACKLOG_USAGE, REVIEW_USAGE],
+	'docs/josh-commands-automation.md': [AUTOMATION_USAGE, WORKFLOW_USAGE, HOOK_USAGE],
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+const COMMAND_USAGE: UsageTable = Object.fromEntries(
+	Object.values(USAGE_PAGE_TABLES)
+		.flat()
+		.flatMap((table) => Object.entries(table)),
+)
+const NOTE_GAP = 3
+
+interface ExampleLine {
+	command: string
+	note: string | undefined
+}
+
+function usage_for(name: string): CommandUsage | undefined {
+	return Object.hasOwn(COMMAND_USAGE, name) ? COMMAND_USAGE[name] : undefined
+}
+
+function example_line(name: string, example: CommandUsage['examples'][number]): ExampleLine {
+	const command = example.arguments ? `pnpm josh ${name} ${example.arguments}` : `pnpm josh ${name}`
+
+	return { command, note: example.note }
+}
+
+// Every comment starts in one column, so a block reads as a table of what each spelling does.
+function format_examples(name: string, usage: CommandUsage): string {
+	const lines = usage.examples.map((example) => example_line(name, example))
+	const width = Math.max(...lines.map((line) => line.command.length)) + NOTE_GAP
+	const rendered = lines.map((line) =>
+		line.note === undefined ? line.command : `${line.command.padEnd(width)}# ${line.note}`,
+	)
+
+	return ['```bash', ...rendered, '```'].join('\n')
+}
+
+function code_span(text: string): string {
+	return `\`${text}\``
+}
+
+function format_flags(flags: NonNullable<CommandUsage['flags']>): string {
+	const items = flags.map(
+		(flag) =>
+			`- ${flag.names.map((spelling) => code_span(spelling)).join(' / ')} — ${flag.description}`,
+	)
+
+	return ['**Options:**', '', ...items].join('\n')
+}
+
+function format_usage(name: string): string | undefined {
+	const usage = usage_for(name)
+	if (usage === undefined) return undefined
+	const flags = usage.flags === undefined ? [] : [format_flags(usage.flags)]
+
+	return [format_examples(name, usage), ...flags].join('\n\n')
+}
+
+// `josh help <command>`: the synopsis line, the description, then the usage block when the command
+// has one. An alias resolves to its command; a name that is neither answers `undefined`.
+function format_command_help(input: string): string | undefined {
+	const name = canonical_command(input)
+	const entry = Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name] : undefined
+	if (entry === undefined) return undefined
+	const [synopsis] = entry.reference
+	const head = synopsis ? `josh ${name} ${synopsis}` : `josh ${name}`
+	const usage = format_usage(name)
+
+	return [head, '', entry.description, ...(usage === undefined ? [] : ['', usage])].join('\n')
+}
+
+// The commands whose usage blocks a reference page renders — the keys of the tables tied to it.
+function page_commands(page: string): Array<string> {
+	const tables = Object.hasOwn(USAGE_PAGE_TABLES, page) ? USAGE_PAGE_TABLES[page] : undefined
+
+	return (tables ?? []).flatMap((table) => Object.keys(table))
+}
+
+const command_usage = {
+	USAGE_PAGES: Object.keys(USAGE_PAGE_TABLES),
+	format_command_help,
+	format_usage,
+	page_commands,
+}
+
+export { command_usage }

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

@@ -77,6 +77,7 @@ const ALIASES: Record<string, string> = {
 	tm: 'time',
 	tmd: 'time:density',
 	rtr: 'retrospective',
+	ca: 'cost:audit',
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
@@ -86,6 +87,7 @@ const ALIASES: Record<string, string> = {
 	lst: 'lane:stats',
 	lli: 'lane:limit',
 	lrs: 'lane:restart',
+	lwd: 'lane:withdraw',
 	blr: 'backlogrun',
 }
 

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

@@ -43,6 +43,25 @@ type CommandReference = readonly [
 	side_effects: ReadonlyArray<CommandSideEffect>,
 ]
 
+// One `pnpm josh <command> <arguments>` line of a usage block, with the comment printed after it.
+interface CommandExample {
+	arguments: string
+	note?: string
+}
+
+// Spellings of one option — `-y` and `--yes` — rendered side by side.
+interface CommandFlag {
+	names: ReadonlyArray<string>
+	description: string
+}
+
+// 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).
+interface CommandUsage {
+	examples: ReadonlyArray<CommandExample>
+	flags?: ReadonlyArray<CommandFlag>
+}
+
 interface CommandEntry {
 	script?: string
 	shell?: ReadonlyArray<string>
@@ -109,6 +128,13 @@ const TS_BUILD_INFO_FILE = '.tsbuildinfo'
 const CSPELL_CACHE_FILE = '.cspellcache'
 const ESLINT_EDIT_CACHE_FILE = '.eslintcache.edit'
 const ESLINT_RELATED_CACHE_FILE = '.eslintcache.related'
+const PRETTIER_CACHE_FILE = '.prettiercache'
+const PRETTIER_RELATED_CACHE_FILE = '.prettiercache.related'
+// The pre-commit hook's own, because a staged-files run on the gate's file degrades it: cspell prunes
+// every entry the run did not visit (measured 892 KB down to 18 KB), and `eslint --quiet` stores a
+// report without its warnings under the same config hash the gate reads.
+const CSPELL_COMMIT_CACHE_FILE = '.cspellcache.commit'
+const ESLINT_COMMIT_CACHE_FILE = '.eslintcache.commit'
 
 type GateCachePortability = 'raw' | 'rooted-json'
 
@@ -139,6 +165,10 @@ const ESLINT_RELATED_CACHE_SPEC: GateCacheSpec = {
 	cache_file: ESLINT_RELATED_CACHE_FILE,
 	portability: ROOTED_JSON_PORTABILITY,
 }
+// **Prettier's caches are in neither list: they do not survive a move to another checkout.**
+// Prettier 3 hashes each file's resolved options, *its absolute `filepath` included*, into the entry,
+// so rebasing the keys as ESLint's are still leaves every entry a miss — two checkouts of one tree
+// were measured sharing none of their 3,526 option hashes. Each checkout keeps a warm cache of its own.
 const GATE_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
 	ESLINT_CACHE_SPEC,
 	TS_CACHE_SPEC,
@@ -175,14 +205,20 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 //
 // **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.
+// whole tree before any commit. 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 three, the edit hook's, and the scoped lint's — a cache file that is not
-// ignored is committed, or spell-checked, which is a red gate with nothing misspelled in the tree.
+// written from. The gate's, the edit hook's, the scoped lint's and the pre-commit hook's — a cache
+// file that is not ignored is committed, or spell-checked, which is a red gate with nothing
+// misspelled in the tree.
 const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
 	...GATE_CACHE_FILES,
 	ESLINT_EDIT_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FILE,
+	PRETTIER_CACHE_FILE,
+	PRETTIER_RELATED_CACHE_FILE,
+	CSPELL_COMMIT_CACHE_FILE,
+	ESLINT_COMMIT_CACHE_FILE,
 ]
 
 // `--cache --cache-strategy content` is one convention rather than two coincidences: cspell adopted
@@ -190,11 +226,11 @@ const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
 const CONTENT_CACHE_FLAGS = ['--cache', '--cache-strategy', 'content'] as const
 const CACHE_LOCATION_FLAG = '--cache-location'
 
-// Four locations are written with these same four flags — the gate's eslint cache, the scoped lint's,
-// the edit hook's and the spell check's — so the sequence is built here once. Spelled out per
-// location, a fix to the order would have to be made four times and each copy fails silently: a flag
-// and its value are one unit, and a wrong order makes the tool read `--cache-strategy` as the file
-// name rather than erroring.
+// Every location is written with these same four flags — the eslint, prettier and spell-check caches
+// of the gate, the scoped lint, the edit hook and the pre-commit hook — so the sequence is built here
+// once. Spelled out per location, a fix to the order would have to be made once per location and
+// each copy fails silently: a flag and its value are one unit, and a wrong order makes the tool read
+// `--cache-strategy` as the file name rather than erroring.
 function content_cache_flags(cache_file: string): ReadonlyArray<string> {
 	return [...CONTENT_CACHE_FLAGS, CACHE_LOCATION_FLAG, cache_file]
 }
@@ -204,8 +240,12 @@ const ESLINT_EDIT_CACHE_FLAGS = content_cache_flags(ESLINT_EDIT_CACHE_FILE)
 const ESLINT_RELATED_CACHE_FLAGS = content_cache_flags(ESLINT_RELATED_CACHE_FILE)
 const TS_CACHE_FLAGS = ['--incremental', '--tsBuildInfoFile', TS_BUILD_INFO_FILE] as const
 const CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE)
+const PRETTIER_CACHE_FLAGS = content_cache_flags(PRETTIER_CACHE_FILE)
+const PRETTIER_RELATED_CACHE_FLAGS = content_cache_flags(PRETTIER_RELATED_CACHE_FILE)
+const CSPELL_COMMIT_CACHE_FLAGS = content_cache_flags(CSPELL_COMMIT_CACHE_FILE)
+const ESLINT_COMMIT_CACHE_FLAGS = content_cache_flags(ESLINT_COMMIT_CACHE_FILE)
 
-export type { CommandCategory, CommandEntry, GateCacheSpec }
+export type { CommandCategory, CommandEntry, CommandUsage, GateCacheSpec }
 // The three cache files are exported one by one as well as as a list, because `josh bench` clears
 // 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
@@ -216,8 +256,10 @@ export {
 	COMMAND_SIDE_EFFECTS,
 	CSPELL_CACHE_FILE,
 	CSPELL_CACHE_FLAGS,
+	CSPELL_COMMIT_CACHE_FLAGS,
 	ESLINT_CACHE_FILE,
 	ESLINT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FLAGS,
 	ESLINT_EDIT_CACHE_FLAGS,
 	ESLINT_RELATED_CACHE_FLAGS,
 	ESLINT_RELATED_CACHE_FILE,
@@ -226,6 +268,10 @@ export {
 	GATE_COMMAND,
 	IGNORED_CACHE_FILES,
 	OPTIONAL_ENV_FILE_FLAGS,
+	PRETTIER_CACHE_FILE,
+	PRETTIER_CACHE_FLAGS,
+	PRETTIER_RELATED_CACHE_FILE,
+	PRETTIER_RELATED_CACHE_FLAGS,
 	SHARED_CACHE_SPECS,
 	TS_BUILD_INFO_FILE,
 	TS_CACHE_FLAGS,

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

@@ -1,3 +1,4 @@
+import { core_budget } from '#scripts/gate/core-budget'
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 import { BACKLOG_COMMANDS } from './josh-commands-backlog'
 import { DOCUMENT_COMMANDS } from './josh-commands-document'
@@ -80,6 +81,16 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['(--cut | --over <tokens-per-request>) [--path <dir>]', 'automation', ['none']],
 	},
+	'cost:audit': {
+		script: 'scripts/cost-audit/cost-audit-cli.ts',
+		description:
+			'Report AI cost over a period by session kind, tool category and guard, with cost per merge and regressions against the period before',
+		category: 'AI tools',
+		reference: ['[--period <days>]', 'maintainer', ['none']],
+		// Kit-only: it reads kit's own transcript store, like `josh retrospective`, which carries its
+		// summary line.
+		is_kit_only: true,
+	},
 	...DOCUMENT_COMMANDS,
 	time: {
 		script: 'scripts/time/time-cli.ts',
@@ -108,6 +119,8 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			"Aggregate a finished run's cost, review findings, observation ledger and events into one digest",
 		category: 'AI tools',
 		reference: ['', 'maintainer', ['none']],
+		core_weight: core_budget.CORE_WEIGHTS.retrospective,
+		memory_mb: core_budget.MEMORY_MB.retrospective,
 		// 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, through the same declaration `josh time` uses for the same reason.

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

@@ -129,7 +129,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'stop:guard': {
 		script: 'scripts/hooks/stop-guard.ts',
 		description:
-			'Claude Code Stop hook: deliver the three stop-time rules — hold notify/release and issue citation (reads the Stop payload on stdin)',
+			'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']],
 		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs at every

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

@@ -19,6 +19,12 @@ const HOOKS_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Git hooks',
 		reference: ['[paths...]', 'automation', ['none']],
 	},
+	'pre-commit-lint': {
+		script: 'scripts/hooks/pre-commit-lint.ts',
+		description: 'Git hook: run cspell, prettier or eslint over staged files from a content cache',
+		category: 'Git hooks',
+		reference: ['<cspell|prettier|eslint> [paths...]', 'automation', ['files']],
+	},
 	'pre-push-unit': {
 		script: 'scripts/hooks/pre-push-unit.ts',
 		description: 'Git hook: run unit tests, reusing a green gate recorded on the pushed tree',

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

@@ -83,6 +83,15 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
 	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:withdraw': {
+		script: 'scripts/lane/lane-withdraw-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work, close its issue as not planned and close the lane — booked withdrawn, not as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue> --reason <text>', 'developer', ['files', 'git', 'processes', 'network']],
+	},
 	// 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': {
@@ -106,7 +115,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, the per-stage durations of a lane under it, and the wait after each ship stop reason under those',
+			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, and the duration and reuse count of each gate check last',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],

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

@@ -112,6 +112,11 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
 	// the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
 	// divergent branches` on exactly the diverged branch the command exists for.
+	//
+	// **It declares no core weight, by measurement** (joshuafolkken/kit#3944): its own work is git, and
+	// the catalog it may regenerate took 0.6s of CPU. The heavy processes seen beside it are commit
+	// hooks — its regenerated catalog's commit runs them — which reserve themselves, and a weight here
+	// would set the held mark they inherit, folding the parallel hook tools into this one place.
 	'main:merge': {
 		script: 'scripts/git/main-merge.ts',
 		description: 'Merge origin default branch into the current branch',