@joshuafolkken/kit 1.983.0 → 1.998.0

package/scripts/init/start.ts

@@ -13,7 +13,7 @@ import { start_steps } from './start-steps'
 
 const ARGUMENT_START_INDEX = 2
 const READY_MESSAGE = 'GitHub workflow ready. Use kickoff new in your assistant to plan an Issue.'
-const START_USAGE = 'josh start [--profile static|node] [--yes] [--github] [--public]'
+const START_USAGE = 'josh start [--profile basic|full] [--yes] [--github] [--public]'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
@@ -72,7 +72,11 @@ function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Pr
 
 	stop_on(start_steps.github_cli_refusal(root))
 
-	return { steps: plan.steps, interaction, choices: { options, shape, consent, root } }
+	return {
+		steps: plan.steps,
+		interaction,
+		choices: { options, shape, consent, root, steps: plan.steps },
+	}
 }
 
 async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
@@ -82,7 +86,7 @@ async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void>
 	const profile = await resolve_profile(choices, interaction)
 	const { root, options } = choices
 
-	start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
+	await start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
 	console.info(`\n${READY_MESSAGE}`)
 }
 

package/scripts/josh/__snapshots__/josh-command-map.test.ts.snap

@@ -450,7 +450,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "init": [
-      "[--profile static|node] [--no-install]",
+      "[--profile basic|full] [--no-install]",
       "developer",
       [
         "files",
@@ -766,7 +766,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "profile": [
-      "[--profile static|node]",
+      "[--profile basic|full]",
       "developer",
       [
         "files",
@@ -1112,7 +1112,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "start": [
-      "[--profile static|node] [--yes] [--github] [--public]",
+      "[--profile basic|full] [--yes] [--github] [--public]",
       "developer",
       [
         "files",

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

@@ -22,7 +22,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	lint: {
 		script: 'scripts/lint/lint-parallel.ts',
-		description: 'Check code with prettier and eslint (skips a tool a static project lacks)',
+		description: 'Check code with prettier and eslint (skips a tool a basic project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 	},
@@ -61,7 +61,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	format: {
 		script: 'scripts/lint/format.ts',
-		description: 'Format code with prettier and eslint (skips a tool a static project lacks)',
+		description: 'Format code with prettier and eslint (skips a tool a basic project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['files', 'processes']],
 	},
@@ -183,7 +183,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	check: {
 		script: 'scripts/gate/type-check-command.ts',
-		description: 'Type-check with tsc (skips a static project with no TypeScript to check)',
+		description: 'Type-check with tsc (skips a basic project with no TypeScript to check)',
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
 	},

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

@@ -4,7 +4,7 @@ import type { CommandEntry } from './josh-command-types'
 // no identifier format allows. The same disable sits at the top of `josh-commands-maintenance.ts`
 // for the same reason.
 /* eslint-disable @typescript-eslint/naming-convention */
-const PROFILE_ARGUMENTS = '[--profile static|node]'
+const PROFILE_ARGUMENTS = '[--profile basic|full]'
 const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 	profile: {
 		script: 'scripts/init/project-profile-cli.ts',
@@ -14,7 +14,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 	},
 	start: {
 		script: 'scripts/init/start.ts',
-		description: 'Create a new project for the GitHub Issue workflow, from git init to labels',
+		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
 			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public]`,

package/scripts/lint/cspell-cached.ts

@@ -23,8 +23,8 @@ const CSPELL_ARGS = [
 
 // The wrapper puts cache transfer directly around cspell rather than around the whole gate (#2060),
 // so a later failing check cannot prevent a completed cache from reaching the primary checkout.
-function static_skip_reason(directory: string): string | undefined {
-	if (!project_checks.is_static(directory)) return undefined
+function basic_skip_reason(directory: string): string | undefined {
+	if (!project_checks.is_basic(directory)) return undefined
 
 	if (!project_checks.has_config(directory, project_checks.CSPELL_CONFIGS)) {
 		return 'no cspell configuration was found'
@@ -36,7 +36,7 @@ function static_skip_reason(directory: string): string | undefined {
 }
 
 async function run(extra_arguments: ReadonlyArray<string> = []): Promise<number> {
-	const reason = static_skip_reason(process.cwd())
+	const reason = basic_skip_reason(process.cwd())
 
 	if (reason !== undefined) {
 		console.info(project_checks.skip_notice('cspell', reason))

package/scripts/lint/format.ts

@@ -19,7 +19,7 @@ async function run_step(args: ReadonlyArray<string>, directory: string): Promise
 
 // prettier first, deliberately: `eslint --fix` exits 1 whenever a non-autofixable error remains, so
 // putting it first would mean one unused variable anywhere in the tree stops prettier from running.
-// A static project without Prettier or ESLint is skipped with the same reason `josh lint` prints
+// A basic project without Prettier or ESLint is skipped with the same reason `josh lint` prints
 // (joshuafolkken/kit#2693, joshuafolkken/kit#2606).
 async function run_unless_skipped(
 	check: string,

package/scripts/lint/lint-parallel.ts

@@ -64,8 +64,8 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 // The two checks are run from here whether they were pointed at the whole tree or at one change's
 // files, so `josh lint:related` reaches prettier and eslint through the same buffering, the same
 // "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298) —
-// and through the same static-project skip, so a narrowed run never reaches a tool the whole-tree
-// run would have skipped (joshuafolkken/kit#2709). The skip reasons answer nothing for a node
+// and through the same basic-project skip, so a narrowed run never reaches a tool the whole-tree
+// run would have skipped (joshuafolkken/kit#2709). The skip reasons answer nothing for a full
 // project, so the one path serves both profiles.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,

package/scripts/rules/filing-cap.ts

@@ -129,6 +129,7 @@ const filing_cap = {
 	ROW,
 	current_turn,
 	decide,
+	is_prompt_line,
 	prior_filing_count,
 	turn_filing_count,
 }

package/scripts/rules/issue-citation.ts

@@ -171,6 +171,28 @@ function bare_references(message: string): ReadonlyArray<string> {
 	return [...new Set(found)]
 }
 
+// Every reference the prompt carries, each as written — `#N` or `owner/repo#N` — with none of the
+// citation exclusions applied: a number pasted inside a fence or a quote is still the person's.
+function prompt_references(prompt: string): ReadonlySet<string> {
+	const found = new Set<string>()
+
+	for (const match of prompt.matchAll(ISSUE_NUMBER)) {
+		found.add(repo_prefix(prompt, match.index) + match[0])
+	}
+
+	return found
+}
+
+// **A number the person's prompt already carried is quoted, not cited** (joshuafolkken/kit#2819). A
+// pasted log from another repository holds its own `#1`…`#7`; `issue:cite` would link them to this
+// repository's unrelated Issues, so following the refusal would make the reply wrong. Only the exact
+// reference the prompt wrote is exempt, so a bare `#N` the run brought in itself is still refused.
+function unquoted_references(message: string, prompt: string): ReadonlyArray<string> {
+	const quoted = prompt_references(prompt)
+
+	return bare_references(message).filter((reference) => !quoted.has(reference))
+}
+
 function has_bare_reference(message: string): boolean {
 	return bare_references(message).length > 0
 }
@@ -237,6 +259,13 @@ function linkify(message: string, slug: string): string {
 	return out.join('\n')
 }
 
-const issue_citation = { bare_references, cite_arguments, has_bare_reference, linkify, prose_lines }
+const issue_citation = {
+	bare_references,
+	cite_arguments,
+	has_bare_reference,
+	linkify,
+	prose_lines,
+	unquoted_references,
+}
 
 export { issue_citation }

package/scripts/rules/last-prompt.ts

@@ -0,0 +1,79 @@
+import { json_value } from '#scripts/lib/json-value'
+import { time_reported_failure } from '#scripts/time-runtime/time-reported-failure'
+import { z } from 'zod'
+import { filing_cap } from './filing-cap'
+
+// The text of the person's last prompt on a transcript tail — what the stop guard's citation row
+// reads to tell a `#N` the person quoted from one the run brought in itself (joshuafolkken/kit#2819).
+//
+// **A prompt is `filing_cap`'s prompt line, minus what the harness wrote there.** A skill's body is a
+// `user` line with no tool result too, but it carries `isMeta`; a background task's completion notice
+// and a subagent's hand-back carry an `origin` whose `kind` is not `human`. Each is the harness
+// speaking, not the person — and a notice can name the very Issue the run filed — so only a line with
+// no `origin` (an SDK prompt) or a `human` one is read.
+//
+// **A workflow invocation quotes nothing.** `fullrun #2819` names this repository's own Issue, so a
+// bare `#2819` in that run's report is a citation slip like any other, and the prompt yields no text —
+// a resumed lane child's prompt included, since it ends on the same invocation.
+
+const WORKFLOW_KEYWORDS: ReadonlySet<string> = new Set([
+	'kickoff',
+	'fullrun',
+	'halfrun',
+	'backlogrun',
+])
+const NO_PROMPT = ''
+const HUMAN_ORIGIN = 'human'
+// The word before the prompt's last one — where a trailing `fullrun #N` puts its keyword.
+const KEYWORD_BEFORE_ARGUMENT = -2
+
+const PROMPT_LINE_SCHEMA = z.object({
+	isMeta: z.boolean().nullish(),
+	origin: z.object({ kind: z.string().nullish() }).nullish(),
+	message: z.object({ content: z.unknown() }),
+})
+
+type PromptLine = z.infer<typeof PROMPT_LINE_SCHEMA>
+
+function is_person(line: PromptLine): boolean {
+	if (line.isMeta === true) return false
+
+	return line.origin === null || line.origin === undefined || line.origin.kind === HUMAN_ORIGIN
+}
+
+// The prompt line's text, or `undefined` when the harness wrote it or it does not read as one.
+function person_text(line: string): string | undefined {
+	const parsed = PROMPT_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
+
+	if (!parsed.success || !is_person(parsed.data)) return undefined
+
+	return time_reported_failure.result_text(parsed.data.message.content)
+}
+
+// A keyword opening the prompt is what a person types; a keyword before its one trailing argument is a
+// lane child's resume prompt, whose preamble ends on `fullrun #N` (`lane-child-invocation.ts`).
+function is_invocation(prompt: string): boolean {
+	const words = prompt.trim().split(/\s+/u)
+
+	return [words.at(0), words.at(KEYWORD_BEFORE_ARGUMENT)].some((word) =>
+		WORKFLOW_KEYWORDS.has(word ?? NO_PROMPT),
+	)
+}
+
+function prompt_line_text(line: string): string | undefined {
+	return filing_cap.is_prompt_line(line) ? person_text(line) : undefined
+}
+
+// The last person prompt on the tail; '' when none is on it or it is an invocation.
+function prompt_text(tail: string): string {
+	const text = tail
+		.split('\n')
+		.map((line) => prompt_line_text(line))
+		.findLast((one) => one !== undefined)
+
+	return text === undefined || is_invocation(text) ? NO_PROMPT : text
+}
+
+const last_prompt = { prompt_text }
+
+export { last_prompt }

package/scripts/rules/stop-rules.ts

@@ -49,6 +49,8 @@ interface StopContext {
 	notified: boolean
 	// The turn's session-facing reply text.
 	message: string
+	// The person's last prompt — a `#N` it already carried is quoted, not cited (joshuafolkken/kit#2819).
+	prompt: string
 	// This stop already forced a continuation earlier in the prompt — the loop-breaker Claude Code
 	// documents, so a run that will not comply is not blocked forever.
 	stop_hook_active: boolean
@@ -242,8 +244,8 @@ function needs_release(context: StopContext): boolean {
 	return is_held_idle(context) && context.tree_clean
 }
 
-function citation_reason(message: string): string | undefined {
-	const references = issue_citation.bare_references(message)
+function citation_reason(context: StopContext): string | undefined {
+	const references = issue_citation.unquoted_references(context.message, context.prompt)
 	if (references.length === 0) return undefined
 
 	return build_citation_reason(references)
@@ -255,7 +257,7 @@ function citation_reason(message: string): string | undefined {
 function reply_reason(context: StopContext): string | undefined {
 	if (needs_filing(context)) return FILING_OFFER_REASON
 
-	return citation_reason(context.message) ?? language_reason(context)
+	return citation_reason(context) ?? language_reason(context)
 }
 
 // The headless wait holds past the loop-breaker until the spin bound is reached.

package/scripts/safe-chain/ci-installer-pin.ts

@@ -1,16 +1,14 @@
 import { createHash } from 'node:crypto'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { execaSync } from 'execa'
 
-// The workflows that install safe-chain on the runner. Each carries the release and the installer's
-// SHA-256 as workflow-level env, so one pin per file moves every "Setup safe-chain" step at once
-// (joshuafolkken/kit#2711, joshuafolkken/kit#2765). A consumer has the first and the last, and
-// `josh sync` rewrites both from kit, so moving them anywhere but kit is harmless and short-lived.
-const WORKFLOW_PATHS = [
-	'.github/workflows/ci.yml',
-	'templates/workflows/ci.yml',
-	'.github/workflows/pr-classification.yml',
-]
+// Where the workflows that install safe-chain on the runner live. Each carries the release and the
+// installer's SHA-256 as workflow-level env, so one pin per file moves every "Setup safe-chain" step
+// at once (joshuafolkken/kit#2711, joshuafolkken/kit#2765). The directories are scanned rather than
+// a file list kept, so a workflow another package distributes — app-kit's `dast.yml` and `load.yml`
+// — moves with the rest (joshuafolkken/kit#2830); a file without the pin is never a target.
+const WORKFLOW_DIRECTORIES = ['.github/workflows', 'templates/workflows']
+const WORKFLOW_FILE_RE = /\.ya?ml$/u
 // `[ \t]` rather than `\s`: under the `m` flag `\s*` would run across line ends and swallow the
 // blank line that follows the env block.
 const VERSION_RE = /^(?<key>[ \t]*SAFE_CHAIN_INSTALLER_VERSION:[ \t]*)(?<value>\S+)[ \t]*$/mu
@@ -27,6 +25,15 @@ function installer_url(version: string): string {
 	return `https://github.com/AikidoSec/safe-chain/releases/download/${version}/install-safe-chain.sh`
 }
 
+function list_workflows(): Array<string> {
+	return WORKFLOW_DIRECTORIES.filter((directory) => existsSync(directory)).flatMap((directory) =>
+		readdirSync(directory)
+			.filter((file_name) => WORKFLOW_FILE_RE.test(file_name))
+			.toSorted((left, right) => left.localeCompare(right))
+			.map((file_name) => `${directory}/${file_name}`),
+	)
+}
+
 function extract_pinned_version(content: string): string | undefined {
 	return VERSION_RE.exec(content)?.groups?.[VALUE_GROUP]
 }
@@ -66,7 +73,7 @@ function write_pin(workflow_path: string, pin: InstallerPin): void {
 	writeFileSync(workflow_path, rewrite_pin(readFileSync(workflow_path, 'utf8'), pin), 'utf8')
 }
 
-function sync(latest: string, workflow_paths: ReadonlyArray<string> = WORKFLOW_PATHS): void {
+function sync(latest: string, workflow_paths: ReadonlyArray<string> = list_workflows()): void {
 	const targets = stale_workflows(latest, workflow_paths)
 	if (targets.length === 0) return
 
@@ -82,7 +89,7 @@ function sync(latest: string, workflow_paths: ReadonlyArray<string> = WORKFLOW_P
 }
 
 const ci_installer_pin = {
-	WORKFLOW_PATHS,
+	list_workflows,
 	installer_url,
 	extract_pinned_version,
 	rewrite_pin,

package/scripts/safe-chain/project-config.ts

@@ -146,4 +146,4 @@ function sync_project_config(root: string): boolean {
 
 const project_config = { merge_project_config, sync_project_config }
 
-export { project_config }
+export { project_config, PROJECT_CONFIG_FILE }

package/scripts/sync/sync-ai-files.ts

@@ -0,0 +1,204 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { init_ai_copy } from '#scripts/init/init-ai-copy'
+import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { init_logic } from '#scripts/init/init-logic'
+import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
+import type { ProjectShape } from '#scripts/init/project-profile'
+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_hook_safety } from './sync-hook-safety'
+
+const WORKSPACE_YAML = 'pnpm-workspace.yaml'
+const PACKAGE_JSON = '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(source: string, filename: string): void {
+	if (should_skip_hook_file(filename)) return
+	const did_change = sync_ai_file(path.join(PACKAGE_DIR, source), 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)
+}
+
+// The source is the profile's: a basic project syncs from its own templates, as `josh init` wrote it.
+function sync_ai_copy_file(filename: string, is_force: boolean, shape?: ProjectShape): void {
+	const source = init_ai_copy.ai_file_source(filename, shape)
+
+	if (filename === WORKSPACE_YAML) {
+		const did_change = sync_workspace_yaml(
+			path.join(PACKAGE_DIR, source),
+			path.join(PROJECT_ROOT, WORKSPACE_YAML),
+			is_force,
+		)
+
+		console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${WORKSPACE_YAML}`)
+
+		return
+	}
+
+	sync_file(source, 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})`)
+}
+
+// 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)
+}
+
+function ensured_claude_md(existing: string | undefined, shape?: ProjectShape): string {
+	return shape?.profile === 'basic'
+		? init_ai_copy.ensure_basic_claude_md(existing)
+		: init_logic.ensure_claude_md_import(existing)
+}
+
+// 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, shape?: ProjectShape): void {
+	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : undefined
+	const ensured = ensured_claude_md(existing, shape)
+
+	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}`)
+}
+
+// A basic shape syncs the file set `josh init` writes for that profile; no shape is the full set,
+// unfiltered, as sync has always written it (joshuafolkken/kit#2827).
+function sync_ai_copy_all(is_force: boolean, shape?: ProjectShape): void {
+	console.info('AI files:')
+
+	sync_claude_md(path.join(PROJECT_ROOT, CLAUDE_MD_FILENAME), shape)
+
+	for (const filename of init_ai_copy.ai_files(shape)) {
+		sync_ai_copy_file(filename, is_force, shape)
+	}
+
+	for (const { src, dest } of init_ai_copy.ai_file_mappings(shape)) {
+		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()
+}
+
+const sync_ai_files = {
+	should_skip_hook_file,
+	sync_file_mapping,
+	sync_ai_file,
+	sync_workspace_yaml,
+	sync_claude_md,
+	sync_directory,
+	sync_ai_copy_all,
+}
+
+export { sync_ai_files }