@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/gh/git-gh-conditional.ts

@@ -0,0 +1,66 @@
+import { git_gh_exec, has_stdout_field } from './git-gh-exec'
+
+// A `gh api` GET that sends the ETag of the previous answer, so a resource polled every few minutes
+// costs nothing when it has not changed: GitHub answers `304 Not Modified` to a matching
+// `If-None-Match`, and a conditional request answered 304 does not count against the rate limit.
+//
+// **`gh` exits non-zero on a 304** (it prints `gh: HTTP 304`), so the "unchanged" answer arrives as
+// a thrown failure. The status is read off the `--include` status line the failure still carries in
+// its stdout — the same reading `exec_gh_api_status` makes — never off the stderr wording.
+
+const NOT_MODIFIED_STATUS = 304
+const OK_STATUS = 200
+const INCLUDE_FLAG = '--include'
+const HEADER_FLAG = '-H'
+const IF_NONE_MATCH = 'If-None-Match: '
+const HEADER_BODY_SEPARATOR = /\r?\n\r?\n/u
+const ETAG_HEADER = /^etag: *(?<etag>[^\r\n]+)/imu
+
+type ConditionalRead =
+	| { kind: 'unchanged' }
+	| { kind: 'changed'; etag: string | undefined; body: string }
+	| { kind: 'unreadable' }
+
+const UNCHANGED: ConditionalRead = { kind: 'unchanged' }
+const UNREADABLE: ConditionalRead = { kind: 'unreadable' }
+
+function to_args(path: string, etag: string | undefined): Array<string> {
+	const header = etag === undefined ? [] : [HEADER_FLAG, `${IF_NONE_MATCH}${etag}`]
+
+	return ['api', INCLUDE_FLAG, ...header, path]
+}
+
+// The headers and the body of an `--include` answer, split at the first blank line.
+function to_changed(output: string): ConditionalRead {
+	const [headers = '', ...rest] = output.split(HEADER_BODY_SEPARATOR)
+	const etag = ETAG_HEADER.exec(headers)?.groups?.['etag']
+
+	return { kind: 'changed', etag, body: rest.join('\n\n') }
+}
+
+function to_read(output: string): ConditionalRead {
+	return git_gh_exec.parse_status_line(output) === OK_STATUS ? to_changed(output) : UNREADABLE
+}
+
+function failure_status(error: unknown): number | undefined {
+	const cause = error instanceof Error ? error.cause : undefined
+
+	return has_stdout_field(cause) ? git_gh_exec.parse_status_line(cause.stdout) : undefined
+}
+
+async function read_conditional(
+	path: string,
+	etag: string | undefined,
+	timeout_ms?: number,
+): Promise<ConditionalRead> {
+	try {
+		return to_read(await git_gh_exec.exec_gh_command(to_args(path, etag), timeout_ms))
+	} catch (error) {
+		return failure_status(error) === NOT_MODIFIED_STATUS ? UNCHANGED : UNREADABLE
+	}
+}
+
+const git_gh_conditional = { read_conditional, to_args }
+
+export type { ConditionalRead }
+export { git_gh_conditional }

package/scripts/gh/git-gh-exec.ts

@@ -288,7 +288,7 @@ interface GhApiRequest {
 	// second argument for the reason recorded beside that constant. `0` is
 	// execa's own "no budget", kept for the one reader whose caller's writes depend on the answer
 	// (`gh-spawn.ts`).
-	timeout_ms?: number
+	timeout_ms?: number | undefined
 	// The checkout gh runs in, which is what `{owner}/{repo}` in `path` resolves against. Absent means
 	// the process's own directory.
 	cwd?: string

package/scripts/gh/git-gh-issue-read.ts

@@ -350,11 +350,14 @@ async function issue_get_labels_and_body(issue_number: string): Promise<string |
 // No `repo` parameter, unlike the reads above: the auto-close lists its candidate epics from the
 // repository it runs in, so the epic whose comments are read is always a local one. The path builder
 // takes one when a caller that needs it appears.
-async function issue_list_comments(issue_number: string): Promise<string | undefined> {
+async function issue_list_comments(
+	issue_number: string,
+	timeout_ms?: number,
+): Promise<string | undefined> {
 	const path = `${git_gh_api_path.issue_comments_api_path(issue_number)}${git_gh_api_path.FULL_PAGE_QUERY}`
 
 	try {
-		return await git_gh_exec.exec_gh_api({ path, should_paginate: true })
+		return await git_gh_exec.exec_gh_api({ path, should_paginate: true, timeout_ms })
 	} catch {
 		return undefined
 	}
@@ -436,5 +439,5 @@ const git_gh_issue_read = {
 	issue_list_comments,
 }
 
-export type { IssueRead, IssueReadFailure }
+export type { IssueRead, IssueReadFailure, IssueReadReason }
 export { git_gh_issue_read, read_blocked_by, NOT_FOUND_STATUS }

package/scripts/gh/git-gh-issue-write.ts

@@ -1,3 +1,4 @@
+import { issue_watch_diff } from '#scripts/issue/issue-watch-diff'
 import { session_cite } from '#scripts/issue/session-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
@@ -64,10 +65,13 @@ async function issue_edit_body(issue_number: string, body: string): Promise<stri
 	})
 }
 
+// **Every comment josh posts carries `RUN_MARKER`**, an HTML comment GitHub does not render. A run
+// posts under the person's own `gh` login, so the marker is the only thing that tells the issue watch
+// (`issue-watch-diff.ts`) a run's comment from a person's update.
 async function issue_comment(issue_number: string, body: string): Promise<string> {
 	return await git_gh_exec.exec_gh_api({
 		path: `${git_gh_api_path.issue_api_path(issue_number)}${COMMENTS_SEGMENT}`,
-		body: JSON.stringify({ body }),
+		body: JSON.stringify({ body: `${body}\n\n${issue_watch_diff.RUN_MARKER}` }),
 		jq_filter: HTML_URL_FILTER,
 	})
 }

package/scripts/gh/git-gh-issue.ts

@@ -14,7 +14,10 @@ const NUMBER_AND_BODY_FIELDS = 'number,body'
 // tell a row with no blockers from one with some **before** deciding whether that row is worth a
 // per-issue read, which would otherwise be made for every open issue in the repository. Absent on a
 // row whose summary is missing, which must not be read as zero; `git-gh-issue-rest.ts` states why.
-const BACKLOG_SCAN_FIELDS = `number,title,body,${BLOCKED_BY_COUNT_FIELD}`
+//
+// `labels` rides along on the same response too: `epic:bundle` reads the release label off it,
+// because the release issue's blockers are recorded mechanically and signal no shared work.
+const BACKLOG_SCAN_FIELDS = `number,title,body,labels,${BLOCKED_BY_COUNT_FIELD}`
 // The recently-closed scan's fields. It compares titles like the scan above
 // and never reads a body, and it needs the labels to tell an epic from a deliverable — the open half
 // gets that from the epic listing, which by construction holds no closed epic.

package/scripts/gh/git-pr-checks-eval.ts

@@ -119,6 +119,18 @@ function is_coderabbit_check(check_name: string): boolean {
 	return is_required_match(check_name, CODERABBIT_CHECK_NAME)
 }
 
+// CodeRabbit reports a rate-limited review as a *passing* status whose description says so
+// (`Review rate limited`), so only the description tells it from a finished review
+// (joshuafolkken/kit#3770).
+const CODERABBIT_RATE_LIMIT_DESCRIPTION = /rate limit/iu
+
+function is_coderabbit_rate_limited(check: RollupCheck): boolean {
+	return (
+		is_coderabbit_check(check.name) &&
+		CODERABBIT_RATE_LIMIT_DESCRIPTION.test(check.description ?? '')
+	)
+}
+
 // Temporary: a pending or failing CodeRabbit check makes GitHub report UNSTABLE even
 // though CodeRabbit is not required. Accept that state only when CodeRabbit checks are the
 // sole non-passing ones — any other non-passing check keeps the gate strict.
@@ -249,6 +261,7 @@ export {
 	is_review_decision_decisive,
 	read_required_statuses,
 	is_coderabbit_check,
+	is_coderabbit_rate_limited,
 	collect_blocking_failures,
 	describe_pr_failure,
 	REQUIRED_CHECKS,

package/scripts/gh/git-pr-checks-parse.ts

@@ -31,10 +31,14 @@ const KEY_STATUS = 'status'
 const KEY_CONCLUSION = 'conclusion'
 const KEY_NAME = 'name'
 const KEY_CONTEXT = 'context'
+const KEY_DESCRIPTION = 'description'
 
 interface RollupCheck {
 	name: string
 	status: string
+	// A status context's own words — CodeRabbit says `Review rate limited` under a `success` state
+	// (joshuafolkken/kit#3770). Absent where the check carries none.
+	description?: string
 }
 
 interface PrStateSnapshot {
@@ -95,7 +99,10 @@ function parse_rollup_item(item: RollupItemData): RollupCheck | undefined {
 	const name = read_string(item[KEY_NAME]) ?? read_string(item[KEY_CONTEXT])
 	if (name === undefined) return undefined
 
-	return { name, status: parse_rollup_status(item) }
+	const check = { name, status: parse_rollup_status(item) }
+	const description = read_string(item[KEY_DESCRIPTION])
+
+	return description === undefined ? check : { ...check, description }
 }
 
 function parse_rollup_checks(raw_json: string): Array<RollupCheck> {

package/scripts/gh/git-pr-checks-watch.ts

@@ -4,9 +4,11 @@ import {
 	default_fetch_pr_state,
 	DEFAULT_STABLE_READS,
 	is_pr_checks_timeout,
+	observed_fetcher,
 	SECONDS_TO_MS,
 	wait_for_pr_success,
 	type PrStateEvaluator,
+	type SnapshotObserver,
 } from './git-pr-checks'
 import { is_coderabbit_check, is_required_check, type PrEvaluation } from './git-pr-checks-eval'
 import {
@@ -125,10 +127,12 @@ const CHECKS_SETTLED_EVALUATOR: PrStateEvaluator = {
 	should_read_review_decision: should_never_read_review_decision,
 }
 
-async function watch_until_settled(branch_name: string): Promise<void> {
+// `observe` sees the watch's polls too, so a red wait's checks line is replaced while the new CI is
+// still pending rather than only after the watch (joshuafolkken/kit#3770).
+async function watch_until_settled(branch_name: string, observe?: SnapshotObserver): Promise<void> {
 	await wait_for_pr_success({
 		branch_name,
-		fetcher: default_fetch_pr_state,
+		fetcher: observed_fetcher(observe),
 		interval_ms: CHECK_WAIT_INTERVAL_MS,
 		max_attempts: compute_max_attempts(
 			PR_CHECKS_WATCH_TIMEOUT_MS / SECONDS_TO_MS,
@@ -154,9 +158,12 @@ async function fail_when_no_checks(branch_name: string): Promise<void> {
 // Everything else — a failing check, an unreadable read, a branch with no checks — is rethrown, which
 // is what the caller already handles: `git-pr-followup.ts` swallows it and falls through to its own
 // poll.
-async function pr_checks_watch(branch_name: string): Promise<WatchResult> {
+async function pr_checks_watch(
+	branch_name: string,
+	observe?: SnapshotObserver,
+): Promise<WatchResult> {
 	try {
-		await watch_until_settled(branch_name)
+		await watch_until_settled(branch_name, observe)
 
 		return { timed_out: false }
 	} catch (error) {

package/scripts/gh/git-pr-checks.ts

@@ -128,6 +128,9 @@ interface WaitForPrSuccessOptions {
 	max_attempts: number
 	required_stable_reads: number
 	evaluator?: PrStateEvaluator
+	// Asked before every poll; a throw ends the wait with that error. `josh followup` stops here on a
+	// person's unread issue update (`issue-watch-gate.ts`).
+	before_poll?: (() => Promise<void>) | undefined
 }
 
 function parse_repo_name_from_package(package_json_content: string): string {
@@ -272,6 +275,8 @@ async function wait_for_pr_success(options: WaitForPrSuccessOptions): Promise<Pr
 
 	for (let attempt = 0; attempt < options.max_attempts; attempt += 1) {
 		console.info(`Checking PR status… (${String(attempt + 1)}/${String(options.max_attempts)})`)
+		// eslint-disable-next-line no-await-in-loop -- polling: the check belongs to this poll, not to all of them at once
+		await options.before_poll?.()
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		carried = await attempt_pr_success_poll({
 			options,
@@ -311,16 +316,38 @@ async function default_fetch_pr_state(
 // **`required_stable_reads` is a parameter, not a constant, so the caller can lower it** — `run_checks`
 // passes `WATCH_CONFIRMED_STABLE_READS` when the watch already confirmed completion. It defaults to
 // `DEFAULT_STABLE_READS`, so every caller that names only the branch is exactly where it was.
+// What a caller is shown of each poll it waits on — `followup` reports the checks to the run's event
+// stream from it (joshuafolkken/kit#3770). It decides nothing: the wait reads the same snapshot.
+type SnapshotObserver = (snapshot: PrStateSnapshot) => Promise<void>
+
+function observed_fetcher(observe: SnapshotObserver | undefined): PrStateFetcher {
+	if (observe === undefined) return default_fetch_pr_state
+
+	return async function fetch_observed(
+		branch_name: string,
+		should_read_review_decision: ReviewDecisionPredicate,
+	): Promise<PrStateSnapshot> {
+		const snapshot = await default_fetch_pr_state(branch_name, should_read_review_decision)
+
+		await observe(snapshot)
+
+		return snapshot
+	}
+}
+
 async function wait_for_pr_success_default(
 	branch_name: string,
 	required_stable_reads: number = DEFAULT_STABLE_READS,
+	before_poll?: () => Promise<void>,
+	observe?: SnapshotObserver,
 ): Promise<PrStateSnapshot> {
 	return await wait_for_pr_success({
 		branch_name,
-		fetcher: default_fetch_pr_state,
+		fetcher: observed_fetcher(observe),
 		interval_ms: CHECK_WAIT_INTERVAL_MS,
 		max_attempts: CHECK_MAX_ATTEMPTS,
 		required_stable_reads,
+		before_poll,
 	})
 }
 
@@ -383,10 +410,17 @@ export {
 	SECONDS_TO_MS,
 	is_pr_checks_timeout,
 	default_fetch_pr_state,
+	observed_fetcher,
 	MERGE_GATE_EVALUATOR,
 	should_always_read_review_decision,
 }
-export type { MergeProgress, PrStateFetcher, PrStateEvaluator, ReviewDecisionPredicate }
+export type {
+	MergeProgress,
+	PrStateFetcher,
+	PrStateEvaluator,
+	ReviewDecisionPredicate,
+	SnapshotObserver,
+}
 export {
 	collect_blocking_failures,
 	describe_pr_failure,

package/scripts/git/git-command.ts

@@ -166,14 +166,25 @@ async function delete_branch(branch_name: string): Promise<void> {
 // report "nothing is stranded" about a branch nobody measured, which is the one wrong answer that
 // loses work. `count_merges` guards the same way and falls back to `0` instead, because there a
 // missing count means an empty range rather than a claim about somebody's commits.
-async function commit_count_beyond(base: string, tip: string): Promise<number> {
-	const range = `${base}..${tip}`
-	const output = await git_spawn.read(['rev-list', '--count', range])
+async function read_commit_count(revisions: ReadonlyArray<string>): Promise<number> {
+	const output = await git_spawn.read(['rev-list', '--count', ...revisions])
 	const parsed = Number(output)
 
 	if (output.length > 0 && Number.isFinite(parsed)) return parsed
 
-	throw new Error(`\`git rev-list --count ${range}\` printed \`${output}\` rather than a count`)
+	throw new Error(
+		`\`git rev-list --count ${revisions.join(' ')}\` printed \`${output}\` rather than a count`,
+	)
+}
+
+async function commit_count_beyond(base: string, tip: string): Promise<number> {
+	return await read_commit_count([`${base}..${tip}`])
+}
+
+// How many commits `branch_name` holds that no remote-tracking ref reaches — what deleting the branch
+// would lose. An unparseable count throws for the reason `commit_count_beyond`'s does.
+async function commit_count_unpushed(branch_name: string): Promise<number> {
+	return await read_commit_count([branch_name, '--not', '--remotes'])
 }
 
 function is_exit_code_128(cause: unknown): boolean {
@@ -397,6 +408,7 @@ const git_command = {
 	checkout,
 	commit,
 	commit_count_beyond,
+	commit_count_unpushed,
 	delete_branch,
 	push,
 	pull_fast_forward,

package/scripts/git/git-schemas.ts

@@ -10,6 +10,7 @@ const rollup_item_schema = z.looseObject({
 	conclusion: z.string().optional(),
 	name: z.string().optional(),
 	context: z.string().optional(),
+	description: z.string().nullish(),
 })
 
 const pr_raw_schema = z.object({

package/scripts/git/git-spawn-sync.ts

@@ -72,4 +72,4 @@ function toplevel(timeout: number = GIT_TIMEOUT_MS): GitSyncResult {
 const git_spawn_sync = { GIT_TIMEOUT_MS, C_LOCALE, run, read, origin_url, toplevel }
 
 export { git_spawn_sync }
-export type { GitSyncResult }
+export type { GitSyncOptions, GitSyncResult }

package/scripts/hooks/pretool-guard.ts

@@ -1,5 +1,6 @@
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
+import { issue_watch_hook } from '#scripts/issue/issue-watch-hook'
 import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
 import { lane_phase } from '#scripts/lane/lane-phase'
 import { json_value } from '#scripts/lib/json-value'
@@ -104,8 +105,9 @@ async function mark_phase(outcome: GuardOutcome): Promise<void> {
 // surfaced first.
 async function async_reason(raw_payload: string): Promise<string | undefined> {
 	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
+	const cut = watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
 
-	return watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+	return cut ?? (await issue_watch_hook.watch_reason())
 }
 
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {

package/scripts/init/hook-command-rewrite.ts

@@ -25,6 +25,30 @@ const CONSUMER_PACKAGE_MANIFEST = `${claude_plugin_config.MARKETPLACE_PATH}/pack
 const MISSING_INSTALL_NOTICE = 'kit hooks inactive: run pnpm install, then reread CLAUDE.md'
 const MISSING_INSTALL_GUARD = `if [ ! -f ${CONSUMER_PACKAGE_MANIFEST} ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
 const CODEX_HOOKS_DESTINATION = '.codex/hooks.json'
+// Every shape a hook command kit wrote can carry: the launcher as kit's own file names it, the
+// launcher rebased onto the installed package, and the installed dispatcher the releases from
+// 2026-09-13 (joshuafolkken/kit#1930) to the launcher rebased `pnpm josh` onto. The settings merge
+// tells kit's hooks from a project's own by these and the list below, so the shapes stay beside the
+// rewrite that produces them.
+const KIT_COMMAND_MARKERS: ReadonlyArray<string> = [
+	RUN_HOOK_INVOCATION,
+	CONSUMER_RUN_HOOK_INVOCATION,
+	BUNDLE_INVOCATION,
+]
+// Before joshuafolkken/kit#1930 nothing was rebased: a consumer received these six as the whole hook
+// command. A plain `pnpm josh <command>` is also how a project writes a hook of its own, so only the
+// exact commands count — and kit still delivers each of them through the launcher, so one left in
+// place would run its guard or formatter a second time. The list is history and never grows.
+const PLAIN_KIT_COMMANDS: ReadonlySet<string> = new Set(
+	[
+		'audit:provision',
+		'batch:guard',
+		'format:edited',
+		'investigation:guard',
+		'rule:guard',
+		'session:lang',
+	].map((command) => `${PNPM_JOSH_PREFIX}${command}`),
+)
 // The values below are matched inside raw JSON text, so the root prefix is taken in its escaped form.
 const PROJECT_ROOT_PREFIX = JSON.stringify(hook_launch.PROJECT_ROOT_PREFIX).slice(1, -1)
 // Capture the value of every `"command"` field, escapes and all, so the rewrites below touch command
@@ -80,8 +104,15 @@ function apply_hook_command_rewrite_for_destination(
 	return content
 }
 
+function is_kit_hook_command(command: string): boolean {
+	if (PLAIN_KIT_COMMANDS.has(command)) return true
+
+	return KIT_COMMAND_MARKERS.some((marker) => command.includes(marker))
+}
+
 const hook_command_rewrite = {
 	apply_hook_command_rewrite_for_destination,
+	is_kit_hook_command,
 	rewrite_hook_commands,
 }
 

package/scripts/init/init-actions.ts

@@ -221,6 +221,9 @@ function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	}
 
 	actions.push(...build_basic_vscode_actions(shape))
+	// The `.claude/settings.json` a `josh start` project receives wires the `session:lang` hook, whose
+	// unset default is `ja`, so the language is seeded from the locale as on `full`.
+	if (shape.has_workflow) actions.push(...session_language_environment.build_session_lang_actions())
 
 	return actions
 }
@@ -248,4 +251,4 @@ function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
 const init_actions = { build_file_actions, read_package_json }
 
 export type { FileAction }
-export { init_actions, PRETTIER_CONFIG_JS, BASIC_PRETTIER_CONFIG }
+export { init_actions, PRETTIER_CONFIG_JS, BASIC_PRETTIER_CONFIG, LEFTHOOK_PATH }

package/scripts/init/init-ai-copy.ts

@@ -25,9 +25,11 @@ const PRETTIER_IGNORE = '.prettierignore'
 const GIT_ATTRIBUTES = '.gitattributes'
 const CODE_OF_CONDUCT = 'CODE_OF_CONDUCT.md'
 const { SECURITY_MD } = security_policy
+const AGENTS_MD = 'AGENTS.md'
+const GEMINI_MD = 'GEMINI.md'
 const BASIC_AI_FILES = [
-	'AGENTS.md',
-	'GEMINI.md',
+	AGENTS_MD,
+	GEMINI_MD,
 	PRETTIER_IGNORE,
 	GIT_ATTRIBUTES,
 	CODE_OF_CONDUCT,
@@ -36,6 +38,8 @@ const BASIC_AI_FILES = [
 ]
 // A basic project gets its own template for these, not kit's development copy.
 const BASIC_SOURCES: Readonly<Record<string, string>> = {
+	[AGENTS_MD]: 'templates/AGENTS.basic.md',
+	[GEMINI_MD]: 'templates/GEMINI.basic.md',
 	[PRETTIER_IGNORE]: 'templates/prettierignore.basic',
 	[WORKSPACE_YAML]: 'templates/pnpm-workspace.basic.yaml',
 }
@@ -43,6 +47,9 @@ const BASIC_SOURCES: Readonly<Record<string, string>> = {
 const CONSUMER_SOURCES: Readonly<Record<string, string>> = {
 	[SECURITY_MD]: security_policy.SECURITY_TEMPLATE,
 }
+// A basic project `josh start` set up for the GitHub Issue workflow runs its agents unattended, on the
+// permissions, hooks and plugin this file declares (#3796).
+const BASIC_WORKFLOW_AI_FILES = [...BASIC_AI_FILES, '.claude/settings.json']
 const GITHUB_FILES = new Set([CODE_OF_CONDUCT, SECURITY_MD])
 const BASIC_POINTER_MAPPING = { src: 'templates/cursorrules.basic', dest: '.cursorrules' }
 const PULL_REQUEST_TEMPLATE = '.github/pull_request_template.md'
@@ -62,11 +69,15 @@ function did_read_unstamped(destination_path: string): boolean {
 	}
 }
 
-function copy_ai_file(source_path: string, destination_path: string): void {
-	const content = readFileSync(source_path, 'utf8')
+// What kit writes at a destination it copies to — the content `josh uninstall` compares a project's
+// file against, so it is read from the one place the copy itself reads it.
+function copied_content(source_path: string, destination_path: string): string {
+	return transform_copied_content(destination_path, readFileSync(source_path, 'utf8'))
+}
 
+function copy_ai_file(source_path: string, destination_path: string): void {
 	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, transform_copied_content(destination_path, content))
+	writeFileSync(destination_path, copied_content(source_path, destination_path))
 }
 
 // `init` declines to modify a file that already exists, and that includes not stamping it: the
@@ -132,6 +143,14 @@ function merge_existing_workspace_yaml(source_path: string, destination_path: st
 	console.info(`  ✔ updated   ${WORKSPACE_YAML}`)
 }
 
+// The workspace file kit writes where the project has none.
+function workspace_content(source_path: string, destination_path: string): string {
+	return transform_copied_content(
+		destination_path,
+		read_workspace_template(source_path, destination_path),
+	)
+}
+
 function did_skip_workspace_yaml_copy(source_path: string, destination_path: string): boolean {
 	if (existsSync(destination_path)) {
 		merge_existing_workspace_yaml(source_path, destination_path)
@@ -139,9 +158,7 @@ function did_skip_workspace_yaml_copy(source_path: string, destination_path: str
 		return false
 	}
 
-	const template = read_workspace_template(source_path, destination_path)
-
-	writeFileSync(destination_path, transform_copied_content(destination_path, template))
+	writeFileSync(destination_path, workspace_content(source_path, destination_path))
 	console.info(`  ✔ created   ${WORKSPACE_YAML}`)
 
 	return false
@@ -342,8 +359,12 @@ function should_copy_ai_file(filename: string, shape?: ProjectShape): boolean {
 	)
 }
 
+function basic_ai_files(shape: ProjectShape): ReadonlyArray<string> {
+	return shape.has_workflow ? BASIC_WORKFLOW_AI_FILES : BASIC_AI_FILES
+}
+
 function ai_files(shape?: ProjectShape): ReadonlyArray<string> {
-	const files = shape?.profile === 'basic' ? BASIC_AI_FILES : init_logic.get_ai_copy_files()
+	const files = shape?.profile === 'basic' ? basic_ai_files(shape) : init_logic.get_ai_copy_files()
 
 	return files.filter((filename) => should_copy_ai_file(filename, shape))
 }
@@ -397,6 +418,8 @@ function run_ai_copies(shape?: ProjectShape): string | undefined {
 
 const init_ai_copy = {
 	copy_ai_file,
+	copied_content,
+	workspace_content,
 	run_ai_copies,
 	ai_files,
 	ai_file_source,
@@ -405,4 +428,4 @@ const init_ai_copy = {
 	read_workspace_template,
 }
 
-export { init_ai_copy, CLAUDE_MD_FILENAME }
+export { init_ai_copy, CLAUDE_MD_FILENAME, WORKSPACE_YAML }

package/scripts/init/init-basic.ts

@@ -3,6 +3,7 @@ import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { init_logic } from './init-logic'
 import type { ProjectShape } from './project-profile'
+import { workflow_mark } from './workflow-mark'
 
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
 const record_schema = z.record(z.string(), z.unknown())
@@ -16,13 +17,17 @@ function initial_manifest(): string {
 	return json_format.format_json({ private: true })
 }
 
-function with_recorded_profile(content: string, profile: ProjectShape['profile']): string {
+function with_recorded_profile(
+	content: string,
+	profile: ProjectShape['profile'],
+	has_workflow = false,
+): string {
 	const parsed: unknown = JSON.parse(content)
 	const manifest = record_schema.parse(parsed)
 	const existing = manifest['josh']
 	const josh = json_value.is_record(existing) ? existing : {}
 
-	manifest['josh'] = { ...josh, profile }
+	manifest['josh'] = { ...josh, profile, ...workflow_mark.recorded_fields(has_workflow) }
 
 	return json_format.format_json(manifest)
 }
@@ -32,7 +37,7 @@ function merge_basic_manifest(
 	shape: ProjectShape,
 	versions: BasicVersions,
 ): string {
-	const with_profile = with_recorded_profile(content, shape.profile)
+	const with_profile = with_recorded_profile(content, shape.profile, shape.has_workflow)
 	const with_script = init_logic.merge_package_scripts(with_profile, {
 		preinstall: init_logic.SAFE_CHAIN_CMD,
 		josh: 'josh',

package/scripts/init/init-logic-toolchain.ts

@@ -0,0 +1,76 @@
+import { parse_jsonc } from '#scripts/config-merge/parse-jsonc'
+import { json_value } from '#scripts/lib/json-value'
+import { init_logic_json_merge } from './init-logic-json-merge'
+import { kit_development_versions } from './kit-development-versions'
+
+// The tools a consumer has to resolve itself, as opposed to the ones only kit's own ESLint config
+// imports. Those are optional kit peers, which pnpm does not install unlisted, so a consumer still
+// needs them — `josh init` writes them, `josh sync` leaves them to it (#3711). A tool belongs here
+// when the consumer runs its bin from the project root (eslint, prettier, tsc, playwright, cspell,
+// lefthook), when a config the consumer owns imports it (`playwright.config.ts` → @playwright/test,
+// @types/node), or when it is named by a string Prettier resolves from the consumer (the preset's
+// plugins). `josh init` and `josh sync` both read this one list, so a tool added here reaches a fresh
+// project and an already-initialized one alike.
+const CONSUMER_RESOLVED_TOOLS = [
+	'eslint',
+	'prettier',
+	'typescript',
+	'@playwright/test',
+	'@ianvs/prettier-plugin-sort-imports',
+	'prettier-plugin-svelte',
+	'prettier-plugin-tailwindcss',
+	'cspell',
+	'@types/node',
+]
+// Only a project with Git gets `lefthook.yml`, so only that one needs the bin.
+const LEFTHOOK_DEVELOPMENT_DEPENDENCY = 'lefthook'
+const DECLARING_FIELDS = [
+	'dependencies',
+	'devDependencies',
+	'peerDependencies',
+	'optionalDependencies',
+]
+
+function consumer_resolved_names(has_git: boolean): ReadonlyArray<string> {
+	return has_git
+		? [...CONSUMER_RESOLVED_TOOLS, LEFTHOOK_DEVELOPMENT_DEPENDENCY]
+		: CONSUMER_RESOLVED_TOOLS
+}
+
+// What `josh init` adds: every kit peer — the ones only kit's own configs import included — and the
+// tools above. Versions mirror kit's own devDependencies, so the consumer runs the toolchain kit is
+// verified with.
+function get_toolchain_development_dependencies(has_git: boolean): Record<string, string> {
+	return kit_development_versions.versions_of([
+		...kit_development_versions.peer_names(),
+		...consumer_resolved_names(has_git),
+	])
+}
+
+function is_declared(manifest: Record<string, unknown>, name: string): boolean {
+	return DECLARING_FIELDS.some((field) => {
+		const dependencies = manifest[field]
+
+		return json_value.is_record(dependencies) && Object.hasOwn(dependencies, name)
+	})
+}
+
+// What `josh sync` adds to an already-initialized consumer: only the tools above, and only the ones
+// the manifest declares nowhere — a tool kept under `dependencies` is present, not missing.
+function merge_consumer_resolved_development_deps(content: string, has_git: boolean): string {
+	const manifest = parse_jsonc(content)
+	const missing = consumer_resolved_names(has_git).filter((name) => !is_declared(manifest, name))
+
+	return init_logic_json_merge.merge_development_dependencies(
+		content,
+		kit_development_versions.versions_of(missing),
+	)
+}
+
+const init_logic_toolchain = {
+	consumer_resolved_names,
+	get_toolchain_development_dependencies,
+	merge_consumer_resolved_development_deps,
+}
+
+export { init_logic_toolchain }