@aperant/framework 0.6.7 → 0.7.3

package/src/cli/commands/features-audit.mjs

@@ -11,25 +11,174 @@
  *   1. `--diff-files <a,b,c>` explicit CSV (highest priority)
  *   2. `--since <ref>` → runs `git diff --name-only <ref>..HEAD`
  *   3. fallback: `git diff HEAD --name-only` (current WIP)
+ *
+ * BUG-025b worktree-redirect: features-audit historically wrote to the
+ * invoking cwd's `.aperant/features/`, leaking generated `*.json` into
+ * main when the executor invoked it from a worktree-isolated task. The
+ * fix applies a 4-step resolution order (see resolveWriteRoot below):
+ *   (1) cwd IS a worktree root → write there (current behaviour)
+ *   (2) --task-id maps to an active non-terminal worktree task →
+ *       redirect writes to that worktree's `.aperant/features/`
+ *   (3) multiple active worktree-isolated tasks + no --task-id → error
+ *   (4) `--no-worktree-redirect` opt-out preserves layer (1) behaviour
  */
 
-import { execFileSync } from 'node:child_process'
-import { resolve } from 'node:path'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
 import { loadDocsPolicy, matchSurfaceToPolicy } from '../docs-audit/policy.mjs'
 import { applyStubPatches, auditFeatureRegistry } from '../features/registry-audit.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
 
+const TERMINAL_PHASES = new Set(['completed', 'cancelled', 'closed', 'shipped', 'merged'])
+
+/**
+ * BUG-025b — resolve where features-audit should write `*.json`.
+ * See module header for the 4-step order. Returns `{ writeRoot, redirect_notice }`
+ * on success or a synthetic error envelope (`{ error: { ... } }`) on the
+ * ambiguous-worktree case.
+ *
+ * @internal — exported for unit testing.
+ *
+ * @param {{projectDir: string, taskId?: string | null, noRedirect?: boolean}} args
+ * @returns {{writeRoot?: string, redirect_notice?: string | null, error?: {kind: string, message: string, active_worktree_tasks: string[]}}}
+ */
+export function resolveWriteRoot({ projectDir, taskId, noRedirect }) {
+	const root = resolve(projectDir)
+	if (noRedirect === true) {
+		return { writeRoot: root, redirect_notice: null }
+	}
+	// Layer (1): cwd IS a worktree root. Worktrees have `git rev-parse
+	// --git-dir` != `git rev-parse --git-common-dir`. Falling through to
+	// the existing behaviour writes to this worktree's .aperant/features.
+	// Fast path: git sets GIT_DIR and GIT_COMMON_DIR in the environment
+	// when running inside a worktree hook context — if both are set and
+	// differ, we are in a worktree. This env-var check is ONLY valid at
+	// Layer (1) where we ask "is this process in a worktree?"; it must
+	// NOT be used to validate an untrusted external path (Layer 2 below).
+	const envDir = process.env.GIT_DIR
+	const envCommonDir = process.env.GIT_COMMON_DIR
+	if (envDir && envCommonDir) {
+		if (resolve(envDir) !== resolve(envCommonDir)) {
+			return { writeRoot: root, redirect_notice: null }
+		}
+	} else if (isWorktreeRoot(root)) {
+		return { writeRoot: root, redirect_notice: null }
+	}
+	// Layer (2): --task-id maps to an active non-terminal worktree-isolated
+	// task → redirect.
+	const stateActive = readActiveTasks(root)
+	if (taskId) {
+		const task = stateActive[taskId]
+		if (
+			task &&
+			!TERMINAL_PHASES.has(task.lifecycle_phase) &&
+			typeof task.worktree_path === 'string' &&
+			existsSync(task.worktree_path)
+		) {
+			const resolvedWorktree = resolve(task.worktree_path)
+			const worktreesDir = resolve(root, '.aperant', 'worktrees') + sep
+			const isUnderProject = resolvedWorktree.startsWith(root + sep) || resolvedWorktree === root
+			const isUnderWorktrees = resolvedWorktree.startsWith(worktreesDir)
+			// Accept only paths under the project root, under .aperant/worktrees/,
+			// or confirmed as a real git worktree by git itself. Rejects arbitrary
+			// paths injected via a tampered state.json while preserving test
+			// fixtures that use ad-hoc worktree paths outside the project tree.
+			if (!isUnderProject && !isUnderWorktrees && !isWorktreeRoot(resolvedWorktree)) {
+				return { writeRoot: root, redirect_notice: null }
+			}
+			return {
+				writeRoot: resolvedWorktree,
+				redirect_notice: `features-audit redirected writes to worktree ${resolvedWorktree} (--task-id ${taskId})`,
+			}
+		}
+	}
+	// Layer (3): multiple active worktree-isolated tasks AND no --task-id
+	// → actionable error. Single-worktree case is OK to default to root
+	// (the executor will set up the worktree's registry on first scan).
+	const activeWorktreeTasks = Object.entries(stateActive).filter(([_id, t]) => {
+		return (
+			t &&
+			!TERMINAL_PHASES.has(t.lifecycle_phase) &&
+			typeof t.worktree_path === 'string' &&
+			existsSync(t.worktree_path)
+		)
+	})
+	if (!taskId && activeWorktreeTasks.length > 1) {
+		return {
+			error: {
+				kind: 'ambiguous-worktree-context',
+				message: 'ambiguous worktree context; pass --task-id <id> or --no-worktree-redirect',
+				active_worktree_tasks: activeWorktreeTasks.map(([id]) => id),
+			},
+		}
+	}
+	// Default: current behaviour (write into cwd).
+	return { writeRoot: root, redirect_notice: null }
+}
+
+function isWorktreeRoot(projectDir) {
+	try {
+		const dirRes = spawnSync('git', ['rev-parse', '--git-dir'], {
+			cwd: projectDir,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		const commonRes = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+			cwd: projectDir,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		if (dirRes.status !== 0 || commonRes.status !== 0) return false
+		return (dirRes.stdout || '').trim() !== (commonRes.stdout || '').trim()
+	} catch {
+		return false
+	}
+}
+
+function readActiveTasks(projectDir) {
+	const statePath = join(projectDir, '.aperant', 'state.json')
+	if (!existsSync(statePath)) return {}
+	try {
+		const parsed = JSON.parse(readFileSync(statePath, 'utf-8'))
+		return parsed?.active_tasks ?? {}
+	} catch {
+		return {}
+	}
+}
+
 export function cmdFeaturesAudit(projectDir, extraArgs) {
 	if (!projectDir) return err('Usage: apt-tools features-audit <project-dir> [flags]')
 	const root = resolve(projectDir)
 	const flags = parseFlags(extraArgs)
 
+	// BUG-025b: redirect writes to the active task's worktree when the
+	// caller is in a non-worktree cwd. See resolveWriteRoot for the
+	// 4-step resolution order.
+	const taskIdFlag = flags.get('task-id')
+	const taskId = typeof taskIdFlag === 'string' && taskIdFlag.trim() ? taskIdFlag.trim() : null
+	const noRedirect = flags.get('no-worktree-redirect') === true
+	const writeRootResult = resolveWriteRoot({ projectDir: root, taskId, noRedirect })
+	if (writeRootResult.error) {
+		return err(writeRootResult.error.message, 1, {
+			kind: writeRootResult.error.kind,
+			active_worktree_tasks: writeRootResult.error.active_worktree_tasks,
+		})
+	}
+	const writeRoot = writeRootResult.writeRoot
+	const redirectNotice = writeRootResult.redirect_notice
+	if (redirectNotice) {
+		// Surface the redirect once on stderr so the executor's log carries
+		// the audit trail without polluting stdout JSON.
+		process.stderr.write(`[features-audit] ${redirectNotice}\n`)
+	}
+
 	const diffFiles = resolveDiffFiles(root, flags)
 	const applyStubs = flags.has('apply-stubs')
 	const format = (flags.get('format') || 'json').toLowerCase()
 
-	const result = auditFeatureRegistry({ projectDir: root, diffFiles })
+	const result = auditFeatureRegistry({ projectDir: writeRoot, diffFiles })
 
 	// Honor `.aperant/config.json.docs_policy`: only apply stubs for targets
 	// whose resolved policy is `auto-update`. This closes the skill-vs-code
@@ -52,7 +201,9 @@ export function cmdFeaturesAudit(projectDir, extraArgs) {
 			}
 		}
 		if (eligible.length > 0) {
-			applied_patches = applyStubPatches(root, eligible)
+			// BUG-025b: stubs are written to the resolved `writeRoot` (which
+			// may be the active task's worktree) rather than the invoking cwd.
+			applied_patches = applyStubPatches(writeRoot, eligible)
 		}
 		if (skipped.length > 0) {
 			skipped_patches = skipped
@@ -65,6 +216,8 @@ export function cmdFeaturesAudit(projectDir, extraArgs) {
 			command: 'features-audit',
 			format: 'md',
 			markdown: renderMarkdown(result, applied_patches, skipped_patches),
+			write_root: writeRoot,
+			...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
 			...result,
 			...(applied_patches ? { applied_patches } : {}),
 			...(skipped_patches ? { skipped_patches } : {}),
@@ -74,6 +227,8 @@ export function cmdFeaturesAudit(projectDir, extraArgs) {
 	return ok({
 		status: 'ok',
 		command: 'features-audit',
+		write_root: writeRoot,
+		...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
 		...result,
 		...(applied_patches ? { applied_patches } : {}),
 		...(skipped_patches ? { skipped_patches } : {}),
@@ -88,7 +243,11 @@ function resolveDiffFiles(root, flags) {
 			.map((s) => s.trim())
 			.filter(Boolean)
 	}
-	const since = flags.get('since')
+	const sinceRaw = flags.get('since')
+	const since =
+		typeof sinceRaw === 'string' && /^[A-Za-z0-9/_.-]+$/.test(sinceRaw) && !sinceRaw.startsWith('-')
+			? sinceRaw
+			: null
 	try {
 		const args = since ? ['diff', '--name-only', `${since}..HEAD`] : ['diff', 'HEAD', '--name-only']
 		const out = execFileSync('git', args, {

package/src/cli/commands/health-check.mjs

@@ -2,7 +2,7 @@
  * commands/health-check.mjs — health-check command (C29).
  */
 
-import { execSync } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -13,6 +13,33 @@ import { readSkillInstallState } from '../util/skill-installs.mjs'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
+/**
+ * SECURITY: validate a component path string from `.aperant/features/*.json`
+ * before passing it to git. The registry is on-disk JSON authored by
+ * features-audit; pre-fix the orphan walker spliced this string into a
+ * shell command (`execSync(\`git rev-parse HEAD:${comp} 2>/dev/null\`)`),
+ * making a malicious entry like `foo.ts; rm -rf $HOME` a command-injection
+ * vector against any user who ran `apt-tools health-check`. The fix
+ * combines `execFileSync` (argv-form, no shell) with a strict path
+ * whitelist: relative posix paths only, no NUL / control bytes / shell
+ * metacharacters / leading `/` / `..` segments.
+ *
+ * @internal — exported for unit testing.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isSafeComponentPath(value) {
+	if (typeof value !== 'string' || value.length === 0 || value.length > 512) return false
+	// Reject NUL, control bytes, and shell metacharacters that could escape
+	// argv interpretation if a downstream caller ever reverts to shell mode.
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control bytes IS the security guard — see isSafeComponentPath docstring + test.
+	if (/[\x00-\x1f;&|`$<>"\\]/.test(value)) return false
+	if (value.startsWith('/')) return false
+	if (value.startsWith('-')) return false // would be parsed as a flag
+	if (value.split('/').some((seg) => seg === '..' || seg === '.' || seg === '')) return false
+	return true
+}
+
 export function cmdHealthCheck(projectDir) {
 	if (!projectDir) return err('Usage: apt-tools health-check <project-dir>')
 	const targetDir = resolve(projectDir)
@@ -22,9 +49,10 @@ export function cmdHealthCheck(projectDir) {
 	// 1. Check for uncommitted changes in working tree
 	let dirtyFiles = []
 	try {
-		const status = execSync('git status --porcelain 2>/dev/null', {
+		const status = execFileSync('git', ['status', '--porcelain'], {
 			cwd: targetDir,
 			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
 		}).trim()
 		if (status) {
 			dirtyFiles = status.split('\n').filter(Boolean)
@@ -140,7 +168,7 @@ export function cmdHealthCheck(projectDir) {
 			issues.push({
 				type: 'missing-skills',
 				severity: 'warning',
-				detail: 'No installed skill version stamps found under .claude/skills or .agents/skills',
+				detail: 'No apt install manifests or version stamps found for any supported runtime',
 				install_surfaces: installs,
 			})
 		}
@@ -156,6 +184,91 @@ export function cmdHealthCheck(projectDir) {
 		}
 	}
 
+	// 6. BUG-025b — orphaned-feature-component warning. Walk
+	// `.aperant/features/*.json`; for each cited component path, verify
+	// `git rev-parse HEAD:<path>` succeeds on the main repo's HEAD. A path
+	// that resolves on a worktree branch but is missing on main is a
+	// candidate orphan (the registry entry leaked from a worktree-isolated
+	// task and was never followed by the actual component landing on main).
+	// Severity `warn` — the registry is best-effort metadata, not a build
+	// blocker. Only fires on the main repo (skipped when health-check is
+	// invoked from a worktree).
+	try {
+		const featuresDir = join(aperantDir, 'features')
+		if (existsSync(featuresDir)) {
+			// SECURITY: argv-form (no shell) — see isSafeComponentPath comment.
+			const dirRes = execFileSync('git', ['rev-parse', '--git-dir'], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: ['ignore', 'pipe', 'ignore'],
+			}).trim()
+			const commonRes = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: ['ignore', 'pipe', 'ignore'],
+			}).trim()
+			if (dirRes === commonRes) {
+				const orphans = []
+				// PRF-001: one subprocess total instead of one per component.
+				// Build a Set of all tracked paths from a single ls-tree call.
+				const lsOut = execFileSync('git', ['ls-tree', '-r', 'HEAD', '--name-only'], {
+					cwd: targetDir,
+					encoding: 'utf-8',
+					stdio: ['ignore', 'pipe', 'ignore'],
+				}).trim()
+				const trackedPaths = new Set(
+					lsOut
+						.split('\n')
+						.map((s) => s.trim())
+						.filter(Boolean),
+				)
+				const files = readdirSync(featuresDir).filter(
+					(f) => f.endsWith('.json') && f !== 'REGISTRY.md',
+				)
+				// QUA-006: cap total component iterations to guard against
+				// adversarially large or malformed registry files.
+				const MAX_ORPHAN_ITERATIONS = 10_000
+				let iterCount = 0
+				let cappedAt = null
+				outer: for (const f of files) {
+					let area
+					try {
+						area = JSON.parse(readFileSync(join(featuresDir, f), 'utf-8'))
+					} catch {
+						continue
+					}
+					const components = Array.isArray(area?.components) ? area.components : []
+					for (const comp of components) {
+						if (iterCount >= MAX_ORPHAN_ITERATIONS) {
+							cappedAt = f
+							break outer
+						}
+						iterCount++
+						// SECURITY: reject obviously-unsafe component strings.
+						if (!isSafeComponentPath(comp)) continue
+						if (!trackedPaths.has(comp)) orphans.push({ area_file: f, component: comp })
+					}
+				}
+				if (cappedAt !== null) {
+					orphans.push({
+						area_file: cappedAt,
+						component: `(orphan scan capped at ${MAX_ORPHAN_ITERATIONS} entries — remaining components skipped)`,
+					})
+				}
+				if (orphans.length > 0) {
+					issues.push({
+						type: 'orphan-feature-components',
+						severity: 'warning',
+						detail: `${orphans.length} feature component(s) cited in .aperant/features/*.json are missing on HEAD — candidates leaked from worktree-isolated tasks`,
+						orphans: orphans.slice(0, 20),
+					})
+				}
+			}
+		}
+	} catch {
+		/* git not available or worktree — skip silently */
+	}
+
 	return ok({
 		status: 'ok',
 		command: 'health-check',

package/src/cli/commands/init.mjs

@@ -29,6 +29,11 @@ import { fileURLToPath } from 'node:url'
 import { detectMode } from '../bootstrap/detect-mode.mjs'
 import { deriveSidecar } from '../bootstrap/product-context-sidecar.mjs'
 import { assertConfigWriteAllowed } from '../config/guard.mjs'
+import {
+	AUDIT_001_LOCAL_FIELDS,
+	migrateDeferredFieldsToLocalConfig,
+	writeLocalConfigField,
+} from '../config/load.mjs'
 import { migrateConfigSchema, setAt } from '../config/schema-migrate.mjs'
 import { resolveSharePolicy } from '../config/share-policy.mjs'
 import { buildAperantGitignoreTemplate } from '../config/upgrade-gitignore.mjs'
@@ -41,6 +46,7 @@ import {
 	writeLastInstallSummary,
 } from '../install/pipeline.mjs'
 import { RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs'
+import { runLegacyCleanup } from '../install/runtime-migrate.mjs'
 import {
 	CLASS_A_SETTINGS,
 	CLASS_B_SETTINGS,
@@ -48,6 +54,7 @@ import {
 	parseClassFlags,
 } from '../install/setting-class.mjs'
 import { detectAgentRuntime } from '../util/agent-runtime.mjs'
+import { buildAptSection } from '../util/aperant-section.mjs'
 import { atomicWriteJson } from '../util/atomic-write.mjs'
 import { aperantBanner } from '../util/banner.mjs'
 import { copyDirRecursive, injectInstructionFile } from '../util/copy.mjs'
@@ -88,10 +95,22 @@ const TRANSFORM_LOADERS = new Map(
  * additive: callers without the flag still get the no-op short-circuit
  * (preserves `init-upgrade-drift.test.ts` case (a)).
  *
+ * 0.7.0 — `--force-overwrite-catalog` (FRAMEWORK-BUG-023) bypasses the
+ * foreign-row defensive check in `injectInstructionFile`. Power-user
+ * flag only — no interview prompt. Without it, an instruction file
+ * carrying rows the generator didn't produce causes init to exit 2 with
+ * `code: 'instruction-file.foreign-rows'` so unattended upgrade flows
+ * surface the would-be data loss instead of silently clobbering it.
+ *
  * @param {string[]} args
- * @returns {{ runtimes: string[], runtimes_explicit: boolean, target: string|null, interactive: boolean, skipBootstrap: boolean, visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean, forceRuntimes: boolean }}
+ * @returns {{ runtimes: string[], runtimes_explicit: boolean, target: string|null, interactive: boolean, skipBootstrap: boolean, visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean, forceRuntimes: boolean, forceOverwriteCatalog: boolean, keepLegacy: boolean }}
  */
 export function parseInstallFlags(args) {
+	// C58 (0.7.2): `--kilocode` is a deprecated alias of `--kilo`. Matches
+	// the upstream package + app branding so users typing what they see on
+	// kilocode.ai get the same install as the canonical `--kilo` flag.
+	// Internal runtime id stays `kilo` (no migration — per spec ID-01).
+	args = args.map((a) => (a === '--kilocode' ? '--kilo' : a))
 	const flagSet = new Set(args.filter((a) => a.startsWith('--')))
 	let target = null
 	for (let i = 0; i < args.length; i++) {
@@ -105,6 +124,14 @@ export function parseInstallFlags(args) {
 	// 0.6.7 (Bug 2 fix) — opt-in bypass of the upgrade_noop short-circuit
 	// so /apt:update can re-stamp runtime files on a no-drift upgrade.
 	const forceRuntimes = flagSet.has('--force-runtimes')
+	// 0.7.0 (FRAMEWORK-BUG-023) — opt-in bypass of the foreign-row check
+	// in injectInstructionFile. Power-user flag only.
+	const forceOverwriteCatalog = flagSet.has('--force-overwrite-catalog')
+	// 0.7.0 (FRAMEWORK-BUG-021) — opt out of the codex legacy-tree cleanup
+	// that fires when `codex` is in the runtime set. Defaults to false so
+	// the cleanup runs by default; pass `--keep-legacy` to preserve the
+	// orphaned `.agents/skills/` tree on upgrades.
+	const keepLegacy = flagSet.has('--keep-legacy')
 
 	const classFlags = parseClassFlags(args)
 
@@ -112,6 +139,8 @@ export function parseInstallFlags(args) {
 		target,
 		skipBootstrap,
 		forceRuntimes,
+		forceOverwriteCatalog,
+		keepLegacy,
 		visibility: classFlags.visibility,
 		autonomy: classFlags.autonomy,
 		accept_new_defaults: classFlags.accept_new_defaults,
@@ -702,7 +731,11 @@ async function interactiveInterview(targetDir, version, canonicalRoot, archetype
 			if (suggested.size === 0) suggested.add('claude')
 			const sel = await clack.multiselect({
 				message: 'Pick the runtimes to install Aperant into',
-				options: RUNTIMES.map((r) => ({ value: r.id, label: r.id, hint: r.flag })),
+				options: RUNTIMES.map((r) => ({
+					value: r.id,
+					label: r.displayLabel ?? r.id,
+					hint: r.flag,
+				})),
 				initialValues: [...suggested],
 				required: true,
 			})
@@ -928,7 +961,7 @@ async function interactiveInterview(targetDir, version, canonicalRoot, archetype
  * @param {Record<string, any>} config
  * @param {InstallAnswers} answers
  */
-function applyInterviewAnswers(config, answers) {
+export function applyInterviewAnswers(config, answers, targetDir = null) {
 	if (config.autonomy) {
 		config.autonomy.default = answers.autonomyDefault
 	}
@@ -943,8 +976,22 @@ function applyInterviewAnswers(config, answers) {
 	}
 	if (config.multi_model?.cross_verification) {
 		const xverify = answers.crossVerificationTools
+		// `enabled` is project policy (is cross-verification on for this
+		// project?) — stays in shared `config.json`.
 		config.multi_model.cross_verification.enabled = xverify.length > 0
-		config.multi_model.cross_verification.tools = xverify
+		// AUDIT-001 (0.7.2 S1) — `tools` is per-device (which CLIs are installed
+		// HERE) and MUST land in `config.local.json`, NOT shared. Strip from
+		// the template to keep the shared file clean. When `targetDir` is null
+		// (legacy callers / tests that don't go through finishInit), we leave
+		// the tools array on the shared template — backward-compatible fallback
+		// — but the writer path always passes targetDir so production lands
+		// the value in local.
+		if (targetDir) {
+			delete config.multi_model.cross_verification.tools
+			writeLocalConfigField(targetDir, 'multi_model.cross_verification.tools', xverify)
+		} else {
+			config.multi_model.cross_verification.tools = xverify
+		}
 	}
 	config.project_type =
 		answers.archetype.type === 'brownfield' ? 'unknown' : config.project_type || 'unknown'
@@ -1164,6 +1211,27 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			}
 		}
 
+		// FRAMEWORK-BUG-021 — sweep the legacy `.agents/skills/` codex tree
+		// BEFORE the install pipeline runs so the install can re-stamp
+		// `.codex/` against a clean slate. Only fires when codex is in the
+		// requested runtime set and `--keep-legacy` was not passed; the
+		// helper itself is conservative (no-op on managed installs, no-op
+		// when no legacy framework files are present).
+		let legacyCleanup = null
+		if (effectiveAnswers.runtimes.includes('codex')) {
+			if (parsedFlags.keepLegacy) {
+				legacyCleanup = { runtime: 'codex', ran: false, reason: '--keep-legacy' }
+			} else {
+				const cleanup = runLegacyCleanup({ targetDir: installTarget })
+				legacyCleanup = { runtime: 'codex', ...cleanup }
+				if (cleanup.ran && cleanup.retained.length > 0) {
+					process.stderr.write(
+						`[apt-tools] legacy_cleanup retained ${cleanup.retained.length} user-added path(s) under .agents/skills/: ${cleanup.retained.join(', ')}\n`,
+					)
+				}
+			}
+		}
+
 		const results = await installRuntimes(
 			effectiveAnswers.runtimes,
 			canonicalRoot,
@@ -1186,7 +1254,14 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			effectiveAnswers,
 			interactiveTty,
 			kernelResult,
+			parsedFlags.forceOverwriteCatalog === true,
+			legacyCleanup,
 		)
+		// FRAMEWORK-BUG-023 — finishInit signals the foreign-row defensive
+		// abort by returning an early-exit sentinel envelope.
+		if (envelope?.__earlyExit) {
+			return envelope.__earlyExit
+		}
 		if (interactiveTty) {
 			await renderOutro(effectiveAnswers, results, version, kernelResult)
 			// TTY mode: envelope was persisted to disk + suppressed from stdout
@@ -1365,6 +1440,19 @@ async function renderOutro(answers, results, version, kernelResult) {
  *                                         deps/` — surfaced in the envelope so
  *                                         downstream tooling can detect a
  *                                         degraded install.
+ * @param {boolean} [forceOverwriteCatalog=false]
+ *                                         FRAMEWORK-BUG-023 — bypass the
+ *                                         foreign-row check in
+ *                                         injectInstructionFile when the user
+ *                                         explicitly opted in via
+ *                                         --force-overwrite-catalog.
+ * @param {object|null} [legacyCleanup=null]
+ *                                         FRAMEWORK-BUG-021 — outcome of the
+ *                                         codex `.agents/skills/` cleanup
+ *                                         step. `null` when codex was not in
+ *                                         the runtime set; otherwise the
+ *                                         shape `{ runtime, ran, … }` from
+ *                                         `runLegacyCleanup`.
  */
 function finishInit(
 	targetDir,
@@ -1376,6 +1464,8 @@ function finishInit(
 	answers,
 	suppressStdout = false,
 	kernelResult = null,
+	forceOverwriteCatalog = false,
+	legacyCleanup = null,
 ) {
 	writeLastInstallSummary(targetDir, runtimeResults, version)
 
@@ -1420,7 +1510,11 @@ function finishInit(
 			() => {
 				if (!existsSync(configDest)) {
 					const template = JSON.parse(readFileSync(configTemplate, 'utf-8'))
-					applyInterviewAnswers(template, answers)
+					// AUDIT-001 (0.7.2 S1) — pass targetDir so the cross_verification.tools
+					// per-device field lands in `config.local.json`, not the shared
+					// `config.json`. Matches the upgrade-path migrator which already
+					// moves the same field via migrateDeferredFieldsToLocalConfig.
+					applyInterviewAnswers(template, answers, targetDir)
 					atomicWriteJson(configDest, template)
 					configCreated = true
 				}
@@ -1448,6 +1542,22 @@ function finishInit(
 		)
 	}
 
+	// AUDIT-001 — UPGRADE-only migrator. Moves the 5 deferred fields out
+	// of `config.json` into `config.local.json` on real upgrade paths
+	// (configMigrated === true), NOT on fresh seeds — the freshly-seeded
+	// template config.json IS the post-migration state, so the migrator
+	// would just round-trip with no observable benefit AND would trip
+	// the next init invocation's no-drift detection. Idempotent on
+	// re-run. Per-field independence per ID-08 — one failure does NOT
+	// block the others.
+	if (configMigrated && existsSync(configDest)) {
+		try {
+			migrateDeferredFieldsToLocalConfig(targetDir, AUDIT_001_LOCAL_FIELDS)
+		} catch {
+			/* never block init on telemetry-only migrator */
+		}
+	}
+
 	const stateTemplate = resolve(canonicalRoot, 'templates', 'state.json')
 	const stateDest = join(aperantDir, 'state.json')
 	let stateCreated = false
@@ -1506,7 +1616,40 @@ function finishInit(
 	if (existsSync(claudeMdPath)) instructionFile = claudeMdPath
 	else if (existsSync(agentsMdPath)) instructionFile = agentsMdPath
 	else instructionFile = claudeMdPath
-	const injectionResult = injectInstructionFile(instructionFile)
+	// FRAMEWORK-BUG-023 — generate the section from discoverSkills before
+	// handing it to the writer. The writer also runs a foreign-row defensive
+	// check; if rows present in the file aren't in the generated set we
+	// signal exit-2 via the __earlyExit sentinel so cmdInit can route the
+	// envelope through exitWith() without writing a malformed install.
+	const aptSection = buildAptSection({
+		canonicalRoot,
+		targetDir,
+		cli: detectAgentRuntime(),
+	})
+	const injectionOutcome = injectInstructionFile(instructionFile, {
+		aptSection,
+		force: forceOverwriteCatalog,
+	})
+	if (injectionOutcome.status === 'aborted-foreign-rows') {
+		return {
+			__earlyExit: exitWith(
+				{
+					ok: false,
+					status: 'error',
+					command: 'init',
+					code: 'instruction-file.foreign-rows',
+					message:
+						`${basename(instructionFile)} contains skill rows not present in the installed framework: ` +
+						`${injectionOutcome.foreignRowIds.join(', ')}. ` +
+						'Re-run with --force-overwrite-catalog to regenerate anyway, or remove the foreign rows manually.',
+					foreignRowIds: injectionOutcome.foreignRowIds,
+					instructionFile: basename(instructionFile),
+				},
+				2,
+			),
+		}
+	}
+	const injectionResult = injectionOutcome.status
 
 	const installedClaude = chosenIds.includes('claude') || existsSync(join(targetDir, '.claude'))
 	const precompactResult = installedClaude
@@ -1617,6 +1760,11 @@ function finishInit(
 					...(kernelResult.reason ? { reason: kernelResult.reason } : {}),
 				}
 			: null,
+		// FRAMEWORK-BUG-021 — always-present envelope field. `null` when
+		// codex was not in the runtime set; otherwise the cleanup outcome
+		// (uses `{ ran: false, reason }` for every skip case so parsers
+		// see a uniform shape).
+		legacy_cleanup: legacyCleanup,
 	}
 
 	if (suppressStdout) {

package/src/cli/commands/modes.mjs

@@ -41,6 +41,17 @@ const FRONTMATTER_RE = /^---\s*([\s\S]*?)\s*---/
  * which config keys a skill cares about. Skills that don't touch
  * config are omitted (their config_keys is `[]`).
  *
+ * AUDIT-001 (0.7.2): all dotted paths below resolve against the MERGED
+ * config (`loadMergedProjectConfig()` — shared `config.json` + local
+ * `config.local.json` overlay). The five per-device fields enumerated by
+ * `AUDIT_001_LOCAL_FIELDS` in `cli/config/load.mjs` (currently
+ * `verification.open_report`, `multi_model.cross_verification.tools`,
+ * `preferences.{date_format,time_format,quick_task_post_verify}`)
+ * physically live in `config.local.json`; the wildcard `'*'` surface for
+ * `apt:setup` covers both files. Consumers MUST go through the merged
+ * loader — never raw `JSON.parse(readFileSync('.aperant/config.json'))` —
+ * to honor per-device overrides correctly.
+ *
  * @type {Record<string, string[]>}
  */
 const SKILL_CONFIG_KEYS = {