@aperant/framework 0.7.0 → 0.7.3

package/skills/apt-verify-proof/SKILL.md

@@ -89,8 +89,10 @@ For multi-model verification details:
 
 ## Config
 
-Settings in `.aperant/config.json` control behavior (run `/apt:setup` to configure):
-- `verification.evidence_capture` — capture screenshots + terminal output (default: true)
-- `verification.open_report` — open HTML in browser when done (default: true)
-- `multi_model.enabled` — run multi-model verification (default: false)
-- `multi_model.gemini.model` — Gemini preset: default/thorough/fast
+Settings live in the MERGED Aperant config (shared `.aperant/config.json` + per-device `.aperant/config.local.json`; local wins). Run `/apt:setup` to configure. Read via `apt-tools config read .` or the framework's `loadMergedProjectConfig()` — NEVER raw `JSON.parse(readFileSync('.aperant/config.json'))`, which misses per-device overrides.
+
+- `verification.evidence_capture` — shared. capture screenshots + terminal output (default: true)
+- `verification.open_report` — **per-device (config.local.json)** per AUDIT-001. open HTML in browser when done (default: true)
+- `multi_model.enabled` — shared. run multi-model verification (default: false)
+- `multi_model.cross_verification.tools` — **per-device (config.local.json)** per AUDIT-001. which CLIs to cross-verify with.
+- `multi_model.gemini.model` — shared. Gemini preset: default/thorough/fast

package/src/cli/ci-watch/stop-matrix.mjs

@@ -106,6 +106,23 @@ export function classify({ checks, state, prMetadata }) {
 		}
 	}
 
+	// 6b. BUG-031 defensive wait branch — if no checks are actually
+	// failing (everything is success / skipped / in_progress / neutral),
+	// never fall through to the default-red 'fix' at the bottom. Placed
+	// AFTER reviewer-pause so CHANGES_REQUESTED + no-failures still
+	// produces 'reviewer-pause' (locks existing semantics), BEFORE the
+	// remaining checks (identical-log, flake-skip, infra-backoff, fix)
+	// which all assume at least one failing row. Pre-fix, a PR with a
+	// success + a SKIPPED conditional CI job fell through to 'fix' and
+	// burned a fix attempt every tick on a non-existent failure.
+	if (failed.length === 0) {
+		return {
+			action: 'wait',
+			counts_toward_budget: false,
+			reason: 'no failing checks; awaiting in-flight or skipped',
+		}
+	}
+
 	// 7. Identical-log → non-converging fixer.
 	// Compare aggregate fingerprints (same format as the write side in ci-watch.mjs).
 	if (attempts > 0 && st.last_status && failed.length > 0) {

package/src/cli/commands/ci-watch.mjs

@@ -24,6 +24,7 @@
  * itself never shells out to gh.
  */
 
+import { spawnSync } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
@@ -94,7 +95,7 @@ function validatePr(pr) {
  */
 export function cmdCiWatch(subcommand, projectDir, extraArgs) {
 	if (!subcommand) {
-		return err('Usage: apt-tools ci-watch <start|stop|status|tick> <project-dir> [flags]')
+		return err('Usage: apt-tools ci-watch <start|stop|status|tick|sweep> <project-dir> [flags]')
 	}
 	if (!projectDir) {
 		return err(`Usage: apt-tools ci-watch ${subcommand} <project-dir> [flags]`)
@@ -112,9 +113,34 @@ export function cmdCiWatch(subcommand, projectDir, extraArgs) {
 			return doStatus(root, flags)
 		case 'tick':
 			return doTick(root, flags)
+		case 'sweep':
+			return err(
+				'sweep is async; call cmdCiWatchSweep directly (the apt-tools dispatcher routes it separately)',
+			)
 		default:
-			return err(`Unknown ci-watch subcommand: ${subcommand}. Expected: start, stop, status, tick`)
+			return err(
+				`Unknown ci-watch subcommand: ${subcommand}. Expected: start, stop, status, tick, sweep`,
+			)
+	}
+}
+
+/**
+ * Async sibling for the `sweep` subcommand (the rate-limited orphaned-state
+ * walker). Split out from the sync `cmdCiWatch` dispatcher so the latter's
+ * return type stays `CommandResult` (not a `CommandResult | Promise` union)
+ * and the synchronous tests + callers don't need to be wrapped in `await`.
+ *
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ * @returns {Promise<CommandResult>}
+ */
+export async function cmdCiWatchSweep(projectDir, extraArgs) {
+	if (!projectDir) {
+		return err('Usage: apt-tools ci-watch sweep <project-dir> [flags]')
 	}
+	const root = resolve(projectDir)
+	const flags = parseFlags(extraArgs)
+	return await doSweep(root, flags)
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +271,91 @@ function doStop(root, flags) {
 	})
 }
 
+// ---------------------------------------------------------------------------
+// sweep — BUG-027 (c): manual GC for orphaned ci-watch state files.
+//
+// Enumerates all watcher state files via `listWatches(root)`, shells out
+// to `gh pr view --json state` for each one (rate-limited to ≤5/sec),
+// and removes the state files whose PR state is MERGED or CLOSED. Never
+// auto-runs on startup — opt-in manual subcommand only, per brief.
+// Honors APT_GH_FIXTURE_JSON for hermetic tests (returns the same body
+// for every PR — fine since the test fixtures we ship cover each
+// branch in isolation).
+// ---------------------------------------------------------------------------
+
+async function doSweep(root, flags) {
+	if (flags.get('orphaned') !== true) {
+		return err(
+			'ci-watch sweep currently supports only `--orphaned`. Usage: apt-tools ci-watch sweep <project-dir> --orphaned',
+		)
+	}
+	const dryRun = flags.get('dry-run') === true
+	const watches = listWatches(root)
+	const removed = []
+	const skipped = []
+	const ghFixture = process.env.APT_GH_FIXTURE_JSON
+	for (let i = 0; i < watches.length; i++) {
+		const watch = watches[i]
+		const pr = watch.pr
+		const prUrl = watch.pr_url ?? null
+		// Validate pr_url shape before passing to gh: must be an https:// URL
+		// or absent. An invalid value (e.g. a flag-injection string from a
+		// tampered state file) falls back to the integer pr number.
+		const safeUrl =
+			typeof prUrl === 'string' && /^https:\/\/.+/.test(prUrl) && !prUrl.startsWith('-')
+				? prUrl
+				: null
+		// Need a PR URL to call `gh pr view`; if absent, fall back to the
+		// integer pr arg which gh accepts for the active repo.
+		const target = safeUrl ?? String(pr)
+		let body = null
+		if (ghFixture) {
+			body = ghFixture
+		} else {
+			try {
+				const res = spawnSync('gh', ['pr', 'view', target, '--json', 'state'], {
+					cwd: root,
+					encoding: 'utf-8',
+				})
+				if (res.status === 0 && res.stdout) body = res.stdout
+			} catch {
+				/* gh transport error — skip this entry */
+			}
+		}
+		if (!body) {
+			skipped.push({ pr, reason: 'gh-unavailable' })
+			continue
+		}
+		let parsed
+		try {
+			parsed = JSON.parse(body)
+		} catch {
+			skipped.push({ pr, reason: 'malformed-gh-json' })
+			continue
+		}
+		const state = parsed?.state ?? null
+		if (state !== 'MERGED' && state !== 'CLOSED') {
+			skipped.push({ pr, reason: `pr-state-${state ?? 'unknown'}` })
+			continue
+		}
+		if (!dryRun) deleteState(root, pr)
+		removed.push({ pr, pr_state: state })
+		// Rate-limit ≤5/sec per brief — sleep 200ms between live gh calls.
+		// Use async setTimeout (non-blocking) rather than Atomics.wait.
+		if (!ghFixture && i < watches.length - 1) {
+			await new Promise((resolve) => setTimeout(resolve, 200))
+		}
+	}
+	return ok({
+		status: 'ok',
+		command: 'ci-watch-sweep',
+		dry_run: dryRun,
+		removed,
+		skipped,
+		total_watches: watches.length,
+	})
+}
+
 // ---------------------------------------------------------------------------
 // status
 // ---------------------------------------------------------------------------

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)
@@ -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'
@@ -101,6 +106,11 @@ const TRANSFORM_LOADERS = new Map(
  * @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++) {
@@ -721,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,
 			})
@@ -947,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
 	}
@@ -962,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'
@@ -1482,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
 				}
@@ -1510,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

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 = {