@joshuafolkken/kit 1.983.0 → 1.998.0

package/scripts/sync/sync.ts

@@ -1,12 +1,14 @@
 #!/usr/bin/env tsx
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { project_checks } from '#scripts/gate/project-checks'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
-import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { basic_path_migration } from '#scripts/init/basic-path-migration'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import { plugin_install_hint_module } from '#scripts/init/plugin-install-hint'
+import { project_profile } from '#scripts/init/project-profile'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { project_config } from '#scripts/safe-chain/project-config'
@@ -14,121 +16,13 @@ import { security_updates } from '#scripts/security/security-updates'
 import { sonar_file } from '#scripts/security/sonar-file'
 import { did_refuse_self_run } from '#scripts/self-sync-guard/self-sync-refusal'
 import { package_manager_version } from '#scripts/version/package-manager-version'
-import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
 import { file_content } from './file-content'
-import { REMOVED_SKILL_MANIFEST } from './removed-skill-manifest'
-import { skill_migration, type MigrationResult } from './skill-migration'
+import { sync_ai_files } from './sync-ai-files'
 import { sync_configs } from './sync-configs'
-import { sync_hook_safety } from './sync-hook-safety'
 
-const WORKSPACE_YAML = 'pnpm-workspace.yaml'
 const PACKAGE_JSON = 'package.json'
 const PACKAGE_JSON_UNCHANGED_MSG = '  ✔ unchanged package.json'
-const CLAUDE_MD_FILENAME = 'CLAUDE.md'
-const CLAUDE_SETTINGS_FILE = '.claude/settings.json'
-const CODEX_HOOKS_FILE = '.codex/hooks.json'
-
-function sync_ai_file(source_path: string, destination_path: string): boolean {
-	const content = readFileSync(source_path, 'utf8')
-
-	return file_content.write_text_if_changed(
-		destination_path,
-		transform_copied_content(destination_path, content),
-	)
-}
-
-// Both copied hook files must run against the consumer's installed bundle. When sync is run from a
-// newer source than that install, writing either file would leave hooks
-// that fail every prompt (joshuafolkken/kit#1930); skip it and print how to update instead.
-function should_skip_hook_file(filename: string): boolean {
-	if (filename !== CLAUDE_SETTINGS_FILE && filename !== CODEX_HOOKS_FILE) return false
-	const warning = sync_hook_safety.hook_write_warning(
-		PROJECT_ROOT,
-		sync_hook_safety.read_version_at(path.join(PACKAGE_DIR, PACKAGE_JSON)),
-		filename,
-	)
-	if (warning === undefined) return false
-	console.warn(warning)
-
-	return true
-}
-
-function sync_file(filename: string): void {
-	if (should_skip_hook_file(filename)) return
-	const did_change = sync_ai_file(
-		path.join(PACKAGE_DIR, filename),
-		path.join(PROJECT_ROOT, filename),
-	)
-
-	console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${filename}`)
-}
-
-function sync_file_mapping(source_path: string, destination_path: string): void {
-	if (!existsSync(source_path)) {
-		console.warn(`  ⚠ skipped   ${path.basename(destination_path)} (not found in package)`)
-
-		return
-	}
-
-	// Routed through sync_ai_file rather than cpSync: templates/workflows/ci.yml is a mapped
-	// file, so a byte copy would hand the consumer the template's own action pins. The pins
-	// have to be resolved from .github/workflows at write time (joshuafolkken/kit#747).
-	const did_change = sync_ai_file(source_path, destination_path)
-
-	console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${path.basename(destination_path)}`)
-}
-
-function sync_workspace_yaml(
-	template_path: string,
-	destination_path: string,
-	is_force = false,
-): boolean {
-	const template = readFileSync(template_path, 'utf8')
-	const existing =
-		!is_force && existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : ''
-	const merged = init_logic.merge_workspace_yaml(existing, template)
-
-	return file_content.write_text_if_changed(destination_path, merged)
-}
-
-function sync_ai_copy_file(filename: string, is_force: boolean): void {
-	if (filename === WORKSPACE_YAML) {
-		const did_change = sync_workspace_yaml(
-			path.join(PACKAGE_DIR, WORKSPACE_YAML),
-			path.join(PROJECT_ROOT, WORKSPACE_YAML),
-			is_force,
-		)
-
-		console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${WORKSPACE_YAML}`)
-
-		return
-	}
-
-	sync_file(filename)
-}
-
-// The reason this directory was not synced, or nothing when it was. Both halves answer the same
-// question — what stops the copy — so the caller has one line to print either way.
-function directory_sync_failure(
-	directory_name: string,
-	on_copy: (did_change: boolean) => void,
-): string | undefined {
-	const source_path = path.join(PACKAGE_DIR, directory_name)
-	const destination_path = path.join(PROJECT_ROOT, directory_name)
-
-	return (
-		directory_copy_blocker(source_path, destination_path) ??
-		copy_directory_failure(source_path, destination_path, on_copy)
-	)
-}
-
-function sync_directory(directory_name: string): void {
-	const failure = directory_sync_failure(directory_name, (did_change) => {
-		console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${directory_name}/`)
-	})
-
-	if (failure !== undefined) console.warn(`  ⚠ skipped   ${directory_name}/ (${failure})`)
-}
+const BASIC_PRETTIER_CONFIG = 'prettier.config.mjs'
 
 function did_migrate_prettierrc(destination_path: string): boolean {
 	const legacy_path = path.join(path.dirname(destination_path), '.prettierrc')
@@ -171,6 +65,20 @@ function sync_prettier_config(destination_path: string): void {
 	write_merged_prettier_config(destination_path)
 }
 
+// A basic project's prettier config written before joshuafolkken/kit#2829 still imports the static
+// preset path; it is moved onto the basic one with the rule `josh init` applies.
+function sync_basic_prettier_config(destination_path: string): void {
+	if (!existsSync(destination_path)) return
+
+	const existing = readFileSync(destination_path, 'utf8')
+	const did_change = file_content.write_text_if_changed(
+		destination_path,
+		basic_path_migration.migrate_basic_paths(existing),
+	)
+
+	console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${BASIC_PRETTIER_CONFIG}`)
+}
+
 function sync_playwright_config(destination_path: string): void {
 	if (!existsSync(destination_path)) return
 
@@ -220,70 +128,6 @@ function sync_sonar_with_template(name_with_owner: string | undefined, is_force
 	console.info(`  ✔ synced    ${destination}`)
 }
 
-// A consumer's stale copy of a distributed skill is removed once it still matches the shipment and
-// kept with a warning once it does not (joshuafolkken/kit#1879). Plugin skills compare against the
-// package source; a retired skill compares against the frozen manifest (joshuafolkken/kit#1990). The
-// note distinguishes the two, and `absent` — the consumer never had the copy — prints nothing.
-function report_migration_result(result: MigrationResult): void {
-	if (result.action === 'absent') return
-
-	if (result.action === 'removed') {
-		console.info(
-			`  ✔ removed   ${result.directory}/ (${skill_migration.removed_note(result.source)})`,
-		)
-
-		return
-	}
-
-	console.warn(`  ⚠ kept      ${result.directory}/ (${skill_migration.kept_note(result.source)})`)
-}
-
-function migrate_removed_skills(): void {
-	const plugin = skill_migration.migrate_removed_skill_directories(PACKAGE_DIR, PROJECT_ROOT)
-	const retired = skill_migration.migrate_manifest_skills(PROJECT_ROOT, REMOVED_SKILL_MANIFEST)
-
-	for (const result of [...plugin, ...retired]) report_migration_result(result)
-}
-
-// CLAUDE.md is not byte-copied (joshuafolkken/kit#1878): a consumer's file is one @import of kit's
-// published rules plus the project's own additions below it. Ensure the import line is present
-// without ever disturbing those additions — so this ignores --force, which would otherwise mean
-// discarding a consumer's content.
-function sync_claude_md(destination_path: string): void {
-	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : undefined
-	const ensured = init_logic.ensure_claude_md_import(existing)
-
-	if (ensured === existing) {
-		console.info(`  ✔ unchanged ${CLAUDE_MD_FILENAME}`)
-
-		return
-	}
-
-	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, ensured)
-	console.info(`  ✔ synced    ${CLAUDE_MD_FILENAME}`)
-}
-
-function sync_ai_copy_all(is_force: boolean): void {
-	console.info('AI files:')
-
-	sync_claude_md(path.join(PROJECT_ROOT, CLAUDE_MD_FILENAME))
-
-	for (const filename of init_logic.get_ai_copy_files()) {
-		sync_ai_copy_file(filename, is_force)
-	}
-
-	for (const { src, dest } of init_logic.get_ai_copy_file_mappings()) {
-		sync_file_mapping(path.join(PACKAGE_DIR, src), path.join(PROJECT_ROOT, dest))
-	}
-
-	for (const directory_name of init_logic.get_ai_copy_directories()) {
-		sync_directory(directory_name)
-	}
-
-	migrate_removed_skills()
-}
-
 function sync_config_files(): void {
 	sync_configs.sync_npmrc(path.join(PROJECT_ROOT, '.npmrc'))
 	sync_configs.sync_gitignore(path.join(PROJECT_ROOT, '.gitignore'))
@@ -376,7 +220,7 @@ function report_repository_settings(name_with_owner: string | undefined): void {
 }
 
 function sync_project_artifacts(is_force: boolean): void {
-	sync_ai_copy_all(is_force)
+	sync_ai_files.sync_ai_copy_all(is_force)
 	sync_prettier_config(path.join(PROJECT_ROOT, 'prettier.config.js'))
 	sync_playwright_config(path.join(PROJECT_ROOT, 'playwright.config.ts'))
 	sync_deploy_vps(path.join(PROJECT_ROOT, '.github/workflows/deploy-vps.yml'))
@@ -394,29 +238,47 @@ function sync_project_artifacts(is_force: boolean): void {
 	report_repository_settings(name_with_owner)
 }
 
+// A basic project gets what `josh init` gives that profile and nothing more: its AI file set and the
+// move of its prettier preset path. The full toolchain's configs, Sonar, package.json migrations and
+// repository settings are never written into it (joshuafolkken/kit#2827).
+function sync_basic_artifacts(is_force: boolean): void {
+	console.info('profile: basic (package.json josh.profile)\n')
+	sync_ai_files.sync_ai_copy_all(is_force, project_profile.inspect_project(PROJECT_ROOT, 'basic'))
+	sync_basic_prettier_config(path.join(PROJECT_ROOT, BASIC_PRETTIER_CONFIG))
+}
+
+function sync_full_artifacts(is_force: boolean): void {
+	sync_project_artifacts(is_force)
+	plugin_install_hint_module.report_plugin_install_hint()
+}
+
 // Checked before anything is written, never per file: the damage is the whole run, and a partial
 // sync that stopped halfway would leave the source repository in a state neither `git checkout` nor
 // a re-run describes (joshuafolkken/kit#868).
+//
+// Only a recorded basic profile switches the file set; an unrecorded one stays full, as every
+// project initialized before the profile was recorded was set up.
 function main(): void {
 	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
 
 	const is_force = process.argv.includes('--force')
 
 	console.info('\n🔄 Syncing @joshuafolkken/kit AI files\n')
-	sync_project_artifacts(is_force)
-	plugin_install_hint_module.report_plugin_install_hint()
+	if (project_checks.is_basic(PROJECT_ROOT)) sync_basic_artifacts(is_force)
+	else sync_full_artifacts(is_force)
 	console.info('\n✅ Done.\n')
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main()
 
 const sync = {
-	should_skip_hook_file,
-	sync_file_mapping,
-	sync_ai_file,
-	sync_workspace_yaml,
-	sync_claude_md,
+	should_skip_hook_file: sync_ai_files.should_skip_hook_file,
+	sync_file_mapping: sync_ai_files.sync_file_mapping,
+	sync_ai_file: sync_ai_files.sync_ai_file,
+	sync_workspace_yaml: sync_ai_files.sync_workspace_yaml,
+	sync_claude_md: sync_ai_files.sync_claude_md,
 	sync_prettier_config,
+	sync_basic_prettier_config,
 	sync_playwright_config,
 	sync_deploy_vps,
 	sync_package_manager_version,
@@ -427,4 +289,6 @@ const sync = {
 
 // `sync` is the entry point; `sync_directory` and `main` are exported for their own unit tests, the
 // way `git-pr-checks.ts` exports the helpers beside its namespace.
+const { sync_directory } = sync_ai_files
+
 export { main, sync, sync_directory }

package/scripts/test/josh-harness-environment.ts

@@ -85,7 +85,7 @@ type FixtureFile = readonly [string, string]
 
 const TOOLCHAIN_FILES: ReadonlyArray<FixtureFile> = [
 	['.gitignore', 'node_modules\n.*cache\n.tsbuildinfo\npnpm-lock.yaml\n'],
-	['.prettierignore', '*.json\npnpm-lock.yaml\n'],
+	['.prettierignore', '*.json\npnpm-lock.yaml\n_tmp_*\n'],
 	['.prettierrc', json_file({ semi: false, singleQuote: true, useTabs: true })],
 	[
 		'cspell.config.yaml',

package/scripts/test/pilot-files.ts

@@ -199,7 +199,6 @@ const PILOT_FILES: ReadonlyArray<string> = [
 	'scripts/hooks/prompt-hooks.test.ts',
 	'scripts/hooks/reserved-run.test.ts',
 	'scripts/init/claude-plugin-config.test.ts',
-	'scripts/init/init-actions.test.ts',
 	'scripts/init/init-copy-content.test.ts',
 	'scripts/init/init-logic-deploy-vps.test.ts',
 	'scripts/init/init-logic-development-engines.test.ts',

package/scripts/test/test-declared-changed.ts

@@ -62,7 +62,7 @@ function source_paths(): ReadonlyArray<string> {
 // The verdict over the current working tree. `paths` stays injectable for a direct caller; when it is
 // omitted the injected set is read if one is in force, else the real tree.
 function current_verdict(paths: ReadonlyArray<string> = source_paths()): Verdict {
-	return test_declared_logic.verdict_for(paths, project_checks.is_static(process.cwd()))
+	return test_declared_logic.verdict_for(paths, project_checks.is_basic(process.cwd()))
 }
 
 // Put the injection back to what it was before a `with_paths` span — cleared to the live reader when

package/scripts/test/test-declared-logic.ts

@@ -14,7 +14,8 @@
 // a clone avoided. Here only paths that are mechanically certain to touch no runtime code are exempt —
 // the non-executable config and cosmetic-asset arms of `CLAUDE.md`'s "Non-runtime updates" exception
 // stay `required`, and a person declares that exception in the Step 0 work summary. Under-exempting
-// costs one declared exception; over-exempting ships an untested runtime change.
+// costs one declared exception; over-exempting ships an untested runtime change. The one widening is
+// the basic profile's manual check below, for files no runner kit has could test.
 
 type Verdict = 'required' | 'exempt' | 'satisfied'
 
@@ -27,7 +28,30 @@ const TEST_SUFFIXES: ReadonlyArray<string> = ['.e2e.ts', '.test.ts']
 const EXEMPT_PATHS: ReadonlyArray<string> = ['.editorconfig']
 const EXEMPT_PREFIXES: ReadonlyArray<string> = ['.idea/', '.vscode/', 'prompts/']
 const EXEMPT_SUFFIXES: ReadonlyArray<string> = ['.md']
-const STATIC_VISUAL_SUFFIXES: ReadonlyArray<string> = ['.html', '.css']
+const BASIC_VISUAL_SUFFIXES: ReadonlyArray<string> = ['.html', '.css']
+
+// What stays `required` under the basic profile (joshuafolkken/kit#2820): the languages kit's own
+// runner can test, and the data and config formats a JS/TS test can load. Any other file — HTML/CSS, or
+// the source of a project kit does not run, such as Lua — has no test kit could execute, so `required`
+// there would be unsatisfiable; it is confirmed by hand instead. The kept side is enumerated rather than
+// the manual one, because that side is closed.
+const BASIC_REQUIRED_SUFFIXES: ReadonlyArray<string> = [
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.json',
+	'.jsonc',
+	'.json5',
+	'.yaml',
+	'.yml',
+	'.toml',
+]
 
 function normalize(paths: ReadonlyArray<string>): Array<string> {
 	return paths.map((path) => path.trim()).filter((path) => path !== '')
@@ -37,12 +61,21 @@ function is_test_file(path: string): boolean {
 	return TEST_SUFFIXES.some((suffix) => path.endsWith(suffix))
 }
 
-function is_static_visual(path: string, is_static: boolean): boolean {
-	return is_static && STATIC_VISUAL_SUFFIXES.some((suffix) => path.endsWith(suffix))
+// Matched case-insensitively, so `Main.TS` is not mistaken for a language kit cannot test.
+function is_basic_manual(path: string, is_basic: boolean): boolean {
+	const lower = path.toLowerCase()
+
+	return is_basic && BASIC_REQUIRED_SUFFIXES.every((suffix) => !lower.endsWith(suffix))
+}
+
+function is_basic_visual(path: string): boolean {
+	const lower = path.toLowerCase()
+
+	return BASIC_VISUAL_SUFFIXES.some((suffix) => lower.endsWith(suffix))
 }
 
-function is_exempt(path: string, is_static = false): boolean {
-	if (EXEMPT_PATHS.includes(path) || is_static_visual(path, is_static)) return true
+function is_exempt(path: string, is_basic = false): boolean {
+	if (EXEMPT_PATHS.includes(path) || is_basic_manual(path, is_basic)) return true
 
 	return (
 		EXEMPT_SUFFIXES.some((suffix) => path.endsWith(suffix)) ||
@@ -52,31 +85,37 @@ function is_exempt(path: string, is_static = false): boolean {
 
 // A runtime file is one that is neither a test nor exempt. Its presence with no test file beside it is
 // the whole of what `required` reports.
-function is_runtime(path: string, is_static = false): boolean {
-	return !is_test_file(path) && !is_exempt(path, is_static)
+function is_runtime(path: string, is_basic = false): boolean {
+	return !is_test_file(path) && !is_exempt(path, is_basic)
 }
 
 // **A test file changed → `satisfied`, whatever else did.** A runtime file with no test beside it →
 // `required`. Everything left — an all-exempt change, and the empty diff — is `exempt`, because there
 // is no runtime file the change failed to test.
-function verdict_for(paths: ReadonlyArray<string>, is_static = false): Verdict {
+function verdict_for(paths: ReadonlyArray<string>, is_basic = false): Verdict {
 	const changed = normalize(paths)
 
 	if (changed.some((path) => is_test_file(path))) return 'satisfied'
-	if (changed.some((path) => is_runtime(path, is_static))) return 'required'
+	if (changed.some((path) => is_runtime(path, is_basic))) return 'required'
 
 	return 'exempt'
 }
 
 // The runtime files with no test beside them — the `required` detail line, so the answer says which
 // files it is about rather than only that it refused.
-function runtime_files(paths: ReadonlyArray<string>, is_static = false): Array<string> {
-	return normalize(paths).filter((path) => is_runtime(path, is_static))
+function runtime_files(paths: ReadonlyArray<string>, is_basic = false): Array<string> {
+	return normalize(paths).filter((path) => is_runtime(path, is_basic))
 }
 
 // The paths that made the change exempt — the `exempt` detail line.
-function exempt_files(paths: ReadonlyArray<string>, is_static = false): Array<string> {
-	return normalize(paths).filter((path) => is_exempt(path, is_static))
+function exempt_files(paths: ReadonlyArray<string>, is_basic = false): Array<string> {
+	return normalize(paths).filter((path) => is_exempt(path, is_basic))
+}
+
+// The paths exempt only because the basic profile has no runner for them — the ones a person still has
+// to confirm by hand, as opposed to docs and editor settings, which nobody checks.
+function manual_check_files(paths: ReadonlyArray<string>, is_basic: boolean): Array<string> {
+	return normalize(paths).filter((path) => is_exempt(path, is_basic) && !is_exempt(path))
 }
 
 const test_declared_logic = {
@@ -85,9 +124,11 @@ const test_declared_logic = {
 	EXEMPT_SUFFIXES,
 	TEST_SUFFIXES,
 	exempt_files,
+	is_basic_visual,
 	is_exempt,
 	is_runtime,
 	is_test_file,
+	manual_check_files,
 	runtime_files,
 	verdict_for,
 }

package/scripts/test/test-declared.ts

@@ -76,36 +76,48 @@ function typed_runtime_file(path: string): string {
 	return `${test_type_logic.test_type_for(path)} — ${path}`
 }
 
+const BROWSER_CHECK = 'confirm the rendered page in a browser'
+const RUN_CHECK = 'run the changed code by hand and report what you observed'
+
+// The manual confirmation a basic-profile exemption owes, one instruction per kind of file it covers:
+// HTML/CSS is looked at in a browser, a source kit cannot test is run by hand (joshuafolkken/kit#2820).
+function manual_instruction(paths: ReadonlyArray<string>, is_basic: boolean): string {
+	const manual = test_declared_logic.manual_check_files(paths, is_basic)
+	const has_visual = manual.some((path) => test_declared_logic.is_basic_visual(path))
+	const has_source = manual.some((path) => !test_declared_logic.is_basic_visual(path))
+	const steps = [has_visual ? BROWSER_CHECK : '', has_source ? RUN_CHECK : ''].filter(Boolean)
+
+	return steps.length === 0 ? '' : ` — ${steps.join('; ')}`
+}
+
 // The word is stdout so a caller can read it alone; the reason — which files, and why — is stderr.
-function exempt_detail(paths: ReadonlyArray<string>, is_static: boolean): string {
-	const exempt = test_declared_logic.exempt_files(paths, is_static)
-	const has_visual = is_static && exempt.some((path) => /\.(?:html|css)$/u.test(path))
-	const instruction = has_visual ? ' — confirm the rendered page in a browser' : ''
+function exempt_detail(paths: ReadonlyArray<string>, is_basic: boolean): string {
+	const exempt = test_declared_logic.exempt_files(paths, is_basic)
 
-	return `exempt paths: ${exempt.join(', ')}${instruction}`
+	return `exempt paths: ${exempt.join(', ')}${manual_instruction(paths, is_basic)}`
 }
 
-function detail_for(verdict: Verdict, paths: ReadonlyArray<string>, is_static = false): string {
+function detail_for(verdict: Verdict, paths: ReadonlyArray<string>, is_basic = false): string {
 	if (verdict === 'required') {
 		const typed = test_declared_logic
-			.runtime_files(paths, is_static)
+			.runtime_files(paths, is_basic)
 			.map((path) => typed_runtime_file(path))
 
 		return `runtime files with no test: ${typed.join(', ')}`
 	}
 
-	if (verdict === 'exempt') return exempt_detail(paths, is_static)
+	if (verdict === 'exempt') return exempt_detail(paths, is_basic)
 
 	return 'a test file changed'
 }
 
 function report(
 	paths: ReadonlyArray<string>,
-	is_static: boolean = project_checks.is_static(process.cwd()),
+	is_basic: boolean = project_checks.is_basic(process.cwd()),
 ): { detail: string; verdict: Verdict } {
-	const verdict = test_declared_logic.verdict_for(paths, is_static)
+	const verdict = test_declared_logic.verdict_for(paths, is_basic)
 
-	return { detail: detail_for(verdict, paths, is_static), verdict }
+	return { detail: detail_for(verdict, paths, is_basic), verdict }
 }
 
 function run(): void {

package/scripts/test/test-unit-guard.ts

@@ -21,8 +21,8 @@ const NODE_MODULES = 'node_modules'
 // - **`vitest` absent is the young project.** `josh init` installs no vitest and writes no
 //   `test:unit` script, so a freshly-bootstrapped project always lands here — which is the case the
 //   skip was written for, and it keeps it.
-// - **`vitest` present is the node project's declaration that it runs unit tests.** Zero matching
-//   files there is a broken state — a mis-scoped glob, or a deleted suite — and fails. A static
+// - **`vitest` present is the full project's declaration that it runs unit tests.** Zero matching
+//   files there is a broken state — a mis-scoped glob, or a deleted suite — and fails. A basic
 //   project may carry vitest as an unused dependency without declaring a unit suite; zero files
 //   there are reported as skipped, never as a test pass.
 //
@@ -47,19 +47,19 @@ type GuardAction = 'run' | typeof SKIP_ACTION | typeof SKIP_NO_TESTS_ACTION | ty
 // body, and without this a gate that skipped the whole unit suite printed the same five lines as one
 // that ran it.
 const SKIP_REASON = 'vitest is not installed'
-const SKIP_NO_TESTS_REASON = 'no unit test files were found in this static project'
+const SKIP_NO_TESTS_REASON = 'no unit test files were found in this basic project'
 const FAIL_REASON =
 	'vitest is installed but no *.{test,spec}.{ts,js} test file was found — refusing to report a unit check that ran nothing'
 
 function resolve_guard_action(
 	is_installed: boolean,
 	has_tests: boolean,
-	is_static = false,
+	is_basic = false,
 ): GuardAction {
 	if (!is_installed) return SKIP_ACTION
 	if (has_tests) return 'run'
 
-	return is_static ? SKIP_NO_TESTS_ACTION : FAIL_ACTION
+	return is_basic ? SKIP_NO_TESTS_ACTION : FAIL_ACTION
 }
 
 function is_vitest_installed(project_directory: string): boolean {
@@ -160,7 +160,7 @@ async function run_guarded_vitest(
 	const action = resolve_guard_action(
 		is_installed,
 		has_tests,
-		project_checks.is_static(project_directory),
+		project_checks.is_basic(project_directory),
 	)
 
 	if (action !== 'run') return report_no_run(action, command_label)

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

@@ -45,7 +45,17 @@ const CHAIN_PATTERN = /&&|\|\||;/u
 // invisible here. Erring this way is the cheaper error for every caller: a missed reading costs
 // nothing beyond the reading, while a fragment read as a command answers about work the shell never
 // did, on the shape this repository writes constantly.
-const QUOTED_SPAN_PATTERN = /'[^']*'|"[^"]*"/gu
+//
+// **Escapes and heredoc bodies are text too** (joshuafolkken/kit#2841). A backslash outside single
+// quotes makes the next character literal, so `it\'s` opens nothing and a `"` closes only at an
+// unescaped `"`; inside `'…'` a backslash is an ordinary character, so `'C:\'` still closes. A heredoc
+// body is not shell syntax at all — an `it's` there is prose — so it is removed before the quotes are
+// paired, keeping the rest of its marker line (`cat <<EOF > f && git add f`) where the shell reads it.
+// Without both, a stray quote paired with one much later and erased every command between them.
+const QUOTED_SPAN_PATTERN = /\\[\s\S]|'[^']*'|"(?:\\[\s\S]|[^"\\])*"/gu
+const HEREDOC_MARKER = /(?<!<)<<-?\s*(['"]?)(\w+)\1/u
+const HEREDOC_DELIMITER_GROUP = 2
+const LINE_BREAK = '\n'
 // `set -o pipefail` tells the shell to report the pipeline with the first failing command's status,
 // so nothing in it is discarded. The flag letters are loose because `set -eo pipefail` and
 // `set -euo pipefail` are the same instruction, and the `set` word is required so that a path or a
@@ -146,13 +156,37 @@ function leading_word(command: string): string {
 //
 // **A pipeline under `set -o pipefail` discards nothing**, so it is not this function's business —
 // answering otherwise would name the very form a caller is told to use instead.
+// A line outside a heredoc body is kept with its marker blanked, and a marker opens a body whose
+// delimiter is returned; inside one, every line is dropped through the line that is the delimiter alone.
+function open_heredoc(line: string, kept: Array<string>): string | undefined {
+	kept.push(line.replace(HEREDOC_MARKER, ' '))
+
+	return HEREDOC_MARKER.exec(line)?.[HEREDOC_DELIMITER_GROUP]
+}
+
+function close_heredoc(line: string, delimiter: string): string | undefined {
+	return line.trim() === delimiter ? undefined : delimiter
+}
+
+function without_heredoc_bodies(command: string): string {
+	const kept: Array<string> = []
+	const body: { delimiter?: string | undefined } = {}
+
+	for (const line of command.split(LINE_BREAK)) {
+		body.delimiter =
+			body.delimiter === undefined ? open_heredoc(line, kept) : close_heredoc(line, body.delimiter)
+	}
+
+	return kept.join(LINE_BREAK)
+}
+
 // Quoted text replaced by a space, which is what a reader walking into the middle of a chain has to
 // do before it can trust an operator it finds there. Exported because `time-writes.ts` needs the same
 // removal for a different reason — a quoted `sed` script holds `|` and slashes that read as a
 // pipeline and as paths — and two spellings of "remove the quotes" would disagree the first time one
 // of them learned about a quoting form the other did not.
 function unquoted(command: string): string {
-	return command.replaceAll(QUOTED_SPAN_PATTERN, ' ')
+	return without_heredoc_bodies(command).replaceAll(QUOTED_SPAN_PATTERN, ' ')
 }
 
 function discarded_commands(command: string): Array<string> {

package/scripts-ai/git-workflow.ts

@@ -5,6 +5,7 @@ import { git_commit } from '../scripts/git/git-commit'
 import { git_error } from '../scripts/git/git-error'
 import { git_issue, type IssueInfo } from '../scripts/git/git-issue'
 import { git_pr } from '../scripts/git/git-pr'
+import { git_preflight } from '../scripts/git/git-preflight'
 import { git_prompt, type WorkflowConfirmations } from '../scripts/git/git-prompt'
 import { git_push } from '../scripts/git/git-push'
 import { git_staging } from '../scripts/git/git-staging'
@@ -206,6 +207,14 @@ async function execute_workflow(
 	const { cli_issue_input, is_auto_mode, commit_suffix } = parse_positionals(positionals)
 	const is_non_interactive = is_non_interactive_mode(is_auto_mode, values)
 
+	// Unattended, nobody can fix a precondition between stages — so all are asked before staging.
+	if (is_non_interactive) {
+		await git_preflight.check({
+			cli_input: cli_issue_input,
+			will_open_pr: values['skip-pr'] !== true,
+		})
+	}
+
 	await git_staging.check_and_confirm_staging(values.yes === true)
 
 	const issue_info = await prepare_issue_info(cli_issue_input, is_non_interactive)
@@ -235,6 +244,7 @@ try {
 }
 
 const git_workflow = {
+	execute_workflow,
 	parse_positionals,
 	get_workflow_confirmations,
 	prepare_issue_info,

package/templates/CLAUDE.basic.md

@@ -0,0 +1,8 @@
+# Project instructions
+
+- 既存のファイルと利用者の設定を尊重し、変更する前に内容を確認する。
+- 変更には検証を付け、実行した結果を報告する。
+- HTML、CSS、JavaScript のファイルがある場合は Prettier で整形する。
+- 画面に見える変更をした場合はブラウザーで表示と操作を確認する。
+- JavaScript または TypeScript の動作を変更した場合は、その動作を確認する自動テストを追加する。
+- Git や GitHub を使う場合だけ、それぞれのワークフローを利用する。