@aperant/framework 0.6.7 → 0.7.0

package/src/cli/route/drift-detect.mjs

@@ -0,0 +1,107 @@
+/**
+ * route/drift-detect.mjs — FRAMEWORK-BUG-017 (rung 1 of 3).
+ *
+ * In-band detection of the "installed kernel drifts behind source
+ * workspace" failure mode. When an Aperant contributor self-hosts the
+ * framework out of a monorepo checkout, the kernel at
+ * `.aperant/deps/node_modules/@aperant/framework/` lags behind the
+ * source at `packages/framework/` after every same-PR framework fix.
+ * The SessionStart worker only knows about npm — it cannot tell that
+ * the workspace is ahead of the install.
+ *
+ * This module walks up from `targetDir`, looking for a sibling
+ * `packages/framework/package.json`. When found AND its `version`
+ * differs from the installed kernel's `version`, it returns a synthetic
+ * `update_check`-shaped object so `route.mjs` can surface the chip
+ * immediately — without waiting for the SessionStart hook to fire.
+ *
+ * Safe for the route hot path: synchronous, file-existence checks
+ * only, bounded walk (6 segments max), no network, no spawn.
+ *
+ * Security (Codex review edit 2): the workspace `package.json:version`
+ * is validated against the same semver-shape regex `update-chips.mjs`
+ * uses on the cache. A poisoned workspace `package.json` cannot
+ * propagate a non-semver `latest_version` into the synthesized
+ * `update_check` block.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { compareVersions, SEMVER_RE } from '../util/semver.mjs'
+
+/** Max directory frames to walk before giving up. */
+const MAX_WALK_DEPTH = 6
+
+/**
+ * Walk up from `start`, returning every directory frame including
+ * `start` itself. Stops at the filesystem root or at a depth of
+ * `MAX_WALK_DEPTH` (whichever comes first). The hard cap keeps this
+ * cheap on the route hot path and contains accidental scans on deeply
+ * nested input paths.
+ *
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walkUp(start) {
+	const frames = []
+	let cur = start
+	for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+		frames.push(cur)
+		const parent = dirname(cur)
+		if (parent === cur) break
+		cur = parent
+	}
+	return frames
+}
+
+/**
+ * Detect whether the workspace source for `@aperant/framework` is ahead
+ * of the installed kernel.
+ *
+ * @param {string} targetDir  Absolute path the route was invoked against.
+ * @param {string|null} installedVersion  The installed kernel's version (semver string), or null when unknown.
+ * @returns {null | {
+ *   source_path: string,
+ *   source_version: string,
+ *   installed_version: string,
+ *   drift: true,
+ * }}
+ */
+export function detectSourceWorkspaceDrift(targetDir, installedVersion) {
+	if (!targetDir || typeof targetDir !== 'string') return null
+	if (!installedVersion || typeof installedVersion !== 'string') return null
+	if (!SEMVER_RE.test(installedVersion)) return null
+
+	for (const dir of walkUp(targetDir)) {
+		const candidate = join(dir, 'packages', 'framework', 'package.json')
+		if (!existsSync(candidate)) continue
+
+		let pkg
+		try {
+			pkg = JSON.parse(readFileSync(candidate, 'utf-8'))
+		} catch {
+			return null
+		}
+
+		// Validate the workspace package is actually @aperant/framework —
+		// guard against false matches on unrelated monorepos that happen
+		// to have a `packages/framework/` directory.
+		if (pkg?.name !== '@aperant/framework') continue
+
+		const sourceVersion = pkg?.version
+		if (typeof sourceVersion !== 'string' || !SEMVER_RE.test(sourceVersion)) return null
+		// Only report drift when workspace source is strictly ahead of the installed
+		// kernel. Equal (already up-to-date) and behind (installed is newer) both
+		// return null — only source-ahead is a drift worth surfacing.
+		if (compareVersions(sourceVersion, installedVersion) <= 0) return null
+
+		return {
+			source_path: candidate,
+			source_version: sourceVersion,
+			installed_version: installedVersion,
+			drift: true,
+		}
+	}
+
+	return null
+}

package/src/cli/util/aperant-section.mjs

@@ -0,0 +1,136 @@
+/**
+ * util/aperant-section.mjs — generator for the CLAUDE.md / AGENTS.md
+ * "## Aperant Framework" section (FRAMEWORK-BUG-023).
+ *
+ * Replaces the previously-hardcoded `APT_SECTION` constant in copy.mjs.
+ * The skill TABLE is rebuilt from `discoverSkills` (filesystem source of
+ * truth — same helper the router uses at runtime) so install and runtime
+ * can never disagree about the catalog.
+ *
+ * Curated-doc risk: the appendix template
+ * (`templates/aperant-claude-md-appendix.md`) still contains hand-written
+ * sub-sections — "Fast Path Guarantee", "Discoverability —
+ * `apt-tools modes list`", "Feature Registry", "Config". These are small
+ * (~30 lines), rarely change, and rot would be visible (sections about
+ * non-existent features). Acceptable tradeoff per plan §Approach (c).
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getTrustedSkillSources } from '../config/load.mjs'
+import { discoverSkills } from '../route/skill-discover.mjs'
+
+const SECTION_START = '<!-- APT:framework-start -->'
+const SECTION_END = '<!-- APT:framework-end -->'
+const SECTION_HEADING = '## Aperant Framework'
+const APPENDIX_REL_PATH = ['templates', 'aperant-claude-md-appendix.md']
+
+/**
+ * Escape a SKILL `description` for safe inclusion as a markdown table cell.
+ * The only character we have to defend against is the pipe (`|`) — it
+ * terminates the table column. `apt:triage` ships with a literal `|` in
+ * its description, so this is a live case, not a theoretical one.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function escapePipes(text) {
+	return text.replace(/\|/g, '\\|')
+}
+
+/**
+ * Deterministic sort: the bare `apt` router skill first, then ASCII-sorted
+ * by `name`. The router goes first so the generated table mirrors the user's
+ * mental model — the entry point, then everything reachable from it.
+ *
+ * @param {{ name: string }} a
+ * @param {{ name: string }} b
+ * @returns {number}
+ */
+function sortSkills(a, b) {
+	if (a.name === 'apt' && b.name !== 'apt') return -1
+	if (b.name === 'apt' && a.name !== 'apt') return 1
+	return a.name.localeCompare(b.name)
+}
+
+/**
+ * Build the full "## Aperant Framework" section, wrapped in the
+ * `<!-- APT:framework-* -->` markers.
+ *
+ * @param {Object} opts
+ * @param {string} opts.canonicalRoot   Absolute path to the framework root
+ *                                       (the directory that contains
+ *                                       `templates/aperant-claude-md-appendix.md`).
+ * @param {string} opts.targetDir       Project root (passed to discoverSkills).
+ * @param {string} [opts.cli]           Host CLI label (forwarded to
+ *                                       getTrustedSkillSources so the install
+ *                                       root for the runtime is included).
+ * @returns {string}                     The full section, including markers
+ *                                       and trailing newline before the
+ *                                       end-marker. No leading newline.
+ */
+export function buildAptSection({ canonicalRoot, targetDir, cli }) {
+	const trustedSkillSources = getTrustedSkillSources(targetDir, cli)
+	const discovered = discoverSkills({ targetDir, trustedSkillSources })
+	const skills = discovered.skills
+		.filter((s) => s.user_invocable === true && s.internal === false)
+		.slice()
+		.sort(sortSkills)
+
+	const rows = skills.map((s) => `| \`/${s.name}\` | ${escapePipes(s.description)} |`)
+
+	const tableBlock = [
+		'### Available Skills',
+		'| Skill | Description |',
+		'|-------|-------------|',
+		...rows,
+	].join('\n')
+
+	const appendixPath = join(canonicalRoot, ...APPENDIX_REL_PATH)
+	let appendix
+	try {
+		appendix = readFileSync(appendixPath, 'utf-8').replace(/\n+$/, '')
+	} catch (cause) {
+		const err = new Error(
+			`aperant-section: template not found at ${appendixPath} — re-install the framework package`,
+			{ cause },
+		)
+		err.code = 'aperant-section.template-missing'
+		throw err
+	}
+
+	const body = [SECTION_HEADING, '', appendix, '', tableBlock].join('\n')
+
+	return `${SECTION_START}\n${body}\n${SECTION_END}`
+}
+
+/**
+ * Extract the `/apt:<slug>` (or bare `/apt`) row IDs from the
+ * `<!-- APT:framework-* -->` section of an existing instruction file.
+ * Returns `[]` when the file has no APT section.
+ *
+ * Used by `injectInstructionFile` to detect foreign rows that would be
+ * silently clobbered by a regeneration — see `--force-overwrite-catalog`.
+ *
+ * @param {string} text   Full instruction-file contents.
+ * @returns {string[]}    Row IDs in file order, e.g. `['/apt', '/apt:quick', …]`.
+ */
+export function extractAptSectionRowIds(text) {
+	const match = text.match(/<!-- APT:framework-start -->([\s\S]*?)<!-- APT:framework-end -->/)
+	if (!match) return []
+	// Strip HTML comments (including multiline) before scanning for row IDs so
+	// that commented-out example rows don't trigger false-positive foreign-row exits.
+	const section = match[1].replace(/<!--[\s\S]*?-->/g, '')
+	const ids = []
+	// Match table rows whose first cell is `/apt` or `/apt:<slug>` wrapped in
+	// backticks. The leading `|` plus optional whitespace anchors us to a
+	// markdown table cell; the trailing backtick + ` |` anchors the column
+	// boundary so we don't match prose mentions like "the `/apt` router".
+	const rowRe = /^\|\s*`(\/apt(?::[a-z0-9-]+)?)`\s*\|/gm
+	let m = rowRe.exec(section)
+	while (m !== null) {
+		ids.push(m[1])
+		m = rowRe.exec(section)
+	}
+	return ids
+}

package/src/cli/util/copy.mjs

@@ -1,8 +1,14 @@
 /**
  * copy.mjs — filesystem copy + instruction-file injection helpers (C29).
  *
- * `copyDirRecursive` is a pure leaf; `injectInstructionFile` owns the
- * CLAUDE.md / AGENTS.md "<!-- APT:framework-* -->" section template.
+ * `copyDirRecursive` is a pure leaf. `injectInstructionFile` owns the
+ * CLAUDE.md / AGENTS.md "<!-- APT:framework-* -->" section write path.
+ *
+ * The APT section TEXT is no longer assembled here — it is generated by
+ * `util/aperant-section.mjs#buildAptSection` and passed in (FRAMEWORK-BUG-023).
+ * Callers compute the section once (from the filesystem skill catalog) and
+ * hand it to this helper. The defensive foreign-row check stays in this
+ * file so the read/compare/write happens atomically against `filePath`.
  */
 
 import {
@@ -14,6 +20,7 @@ import {
 	writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
+import { extractAptSectionRowIds } from './aperant-section.mjs'
 
 export function copyDirRecursive(src, dest) {
 	mkdirSync(dest, { recursive: true })
@@ -28,68 +35,48 @@ export function copyDirRecursive(src, dest) {
 	}
 }
 
-const APT_SECTION = `<!-- APT:framework-start -->
-## Aperant Framework
-
-This project uses the [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework) for AI-assisted development.
-
-### Available Skills
-| Skill | Description |
-|-------|-------------|
-| \`/apt\` | Smart router — auto-detects context, routes to the right skill |
-| \`/apt:quick\` | Fast task execution — skip planning, go straight to implementation |
-| \`/apt:discuss\` | Interactive decision-making — assumptions, gray areas, power mode |
-| \`/apt:debug\` | Systematic debugging with persistent state across context resets |
-| \`/apt:scan\` | Scan codebase to build/refresh the feature registry (recommended after setup) |
-| \`/apt:plan\` | Analyze a task, investigate codebase, produce spec + implementation plan |
-| \`/apt:execute\` | Implement subtasks from a plan with atomic commits |
-| \`/apt:verify\` | Score implementation on 4 dimensions (correctness, completeness, quality, coverage) |
-| \`/apt:verify-proof\` | Visual proof verification — screenshots, video, HTML report with feature checklists |
-| \`/apt:review\` | 6-pass inline code review (logic / security / quality / architecture / performance / docs-coherence) with auto-fix pipeline |
-| \`/apt:pr-review\` | Multi-agent PR review — 6 parallel specialists, validator, fixer, self-reviewer (owned / external authorship) |
-| \`/apt:run\` | Full pipeline: plan → execute → verify → review |
-| \`/apt:roundtable\` | 10-agent structured debate for complex decisions |
-| \`/apt:stress-test\` | Scenario simulation to catch gaps in plans |
-| \`/apt:ship\` | Create PR with QA scores and decision traceability |
-| \`/apt:pause\` | Human-initiated session handoff — save state when YOU need to stop (not for agent-initiated bailouts) |
-| \`/apt:resume\` | Restore context from a paused session and route to next action |
-| \`/apt:docs\` | Generate/update documentation verified against the actual codebase |
-| \`/apt:setup\` | Change framework preferences (verification style, multi-model, branching) |
-
-### Feature Registry
-The feature registry (\`.aperant/features/\`) is a living inventory of every interactive
-feature in the app. It's the source of truth for what to verify and review.
-
-- **Created by:** \`/apt:scan\` (initial scan or full refresh)
-- **Updated by:** \`/apt:execute\` post-step (\`apt-tools features-audit --apply-stubs\` auto-registers new UI/core/hook/IPC files per the docs-coherence policy)
-- **Consumed by:** \`/apt:verify-proof\` (generates test cases from registry)
-- **Checked by:** \`/apt:review\` Pass 6 (flags unregistered new components, applies stubs for auto-update policies)
-
-Run \`/apt:scan\` after setting up Aperant on a brownfield project, or after major changes.
-
-### Config
-- Settings: \`.aperant/config.json\` (run \`/apt:setup\` to change)
-- Features: \`.aperant/features/\` (feature registry -- run \`/apt:scan\` to create)
-- State: \`.aperant/state.json\` (execution state)
-- Evidence: \`.aperant/proof/\` (proof reports and screenshots)
-- Prompts: \`.aperant/prompts/\` (agent prompt templates)
-<!-- APT:framework-end -->`
-
-export function injectInstructionFile(filePath) {
+/**
+ * Write the (already-generated) APT section into `filePath`. Creates the
+ * file if missing; replaces the section in-place if the markers are
+ * present.
+ *
+ * FRAMEWORK-BUG-023 — before overwriting an existing section, extract the
+ * row IDs in the on-disk file and compare to the row IDs in the freshly
+ * generated section. If the file contains rows that are NOT in the
+ * generated set ("foreign rows"), the regen would silently clobber them.
+ * In that case we abort and let the caller surface a structured error.
+ * The `--force-overwrite-catalog` escape hatch flips `force: true`.
+ *
+ * @param {string} filePath
+ * @param {Object} opts
+ * @param {string} opts.aptSection   Output of buildAptSection() — wrapped
+ *                                    in `<!-- APT:framework-* -->` markers.
+ * @param {boolean} [opts.force=false]
+ *                                    Bypass the foreign-row check.
+ * @returns {{ status: 'created' | 'updated' | 'aborted-foreign-rows', written: boolean, foreignRowIds?: string[] }}
+ */
+export function injectInstructionFile(filePath, { aptSection, force = false }) {
 	const existing = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : ''
 
 	if (existing.includes('<!-- APT:framework-start -->')) {
-		// Update existing section in-place
+		if (!force) {
+			const existingIds = new Set(extractAptSectionRowIds(existing))
+			const generatedIds = new Set(extractAptSectionRowIds(aptSection))
+			const foreignRowIds = [...existingIds].filter((id) => !generatedIds.has(id))
+			if (foreignRowIds.length > 0) {
+				return { status: 'aborted-foreign-rows', written: false, foreignRowIds }
+			}
+		}
 		const updated = existing.replace(
 			/<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->/,
-			APT_SECTION,
+			aptSection,
 		)
 		writeFileSync(filePath, updated, 'utf-8')
-		return 'updated'
+		return { status: 'updated', written: true }
 	}
 
-	// Append
+	// Append (greenfield create — no foreign-row concern).
 	const separator = existing.length > 0 ? '\n\n' : ''
-	writeFileSync(filePath, existing + separator + APT_SECTION + '\n', 'utf-8')
-	return 'created'
+	writeFileSync(filePath, existing + separator + aptSection + '\n', 'utf-8')
+	return { status: 'created', written: true }
 }

package/src/cli/util/semver.mjs

@@ -0,0 +1,28 @@
+/**
+ * util/semver.mjs — shared semver helpers used by route/drift-detect.mjs
+ * and util/version-preflight.mjs. Extracted to avoid duplication (QUA-002).
+ */
+
+/** Semver-shape pattern — mirrors install/update-chips.mjs:64. */
+export const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/**
+ * Compare two semver-shape strings. Returns -1 / 0 / 1. Ignores
+ * pre-release + build metadata (sufficient for "min version" checks
+ * where we only care about the MAJOR.MINOR.PATCH triple).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareVersions(a, b) {
+	const pa = a.split(/[-+]/, 1)[0].split('.').map(Number)
+	const pb = b.split(/[-+]/, 1)[0].split('.').map(Number)
+	for (let i = 0; i < 3; i++) {
+		const av = pa[i] ?? 0
+		const bv = pb[i] ?? 0
+		if (av < bv) return -1
+		if (av > bv) return 1
+	}
+	return 0
+}

package/src/cli/util/skill-installs.mjs

@@ -1,37 +1,150 @@
 /**
- * skill-installs.mjs — shared skill install surfaces per host.
+ * skill-installs.mjs — shared skill install surfaces per runtime (BUG-022).
+ *
+ * Source of truth for "what does the framework have installed on this
+ * project, per runtime, and is it current?" — the post-022 implementation
+ * is manifest-aware:
+ *
+ *   1. Per surface, prefer `apt-file-manifest.json` (the v0.6.7+ runtime
+ *      manifest). When present and valid, `framework_version` is the
+ *      authoritative answer.
+ *   2. Manifest present but malformed → reported as `installed: true`,
+ *      `stale: true`, `source: 'manifest-malformed'`. Don't silently
+ *      report healthy.
+ *   3. Else fall back to `legacy_version_file` (the pre-manifest
+ *      `.apt-version` stamp; only defined for codex via
+ *      `LEGACY_INSTALL_PATHS` today). `source: 'legacy_version_file'`.
+ *   4. Else → not installed for this surface.
+ *
+ * The surface array is derived from `RUNTIMES` (single source of truth in
+ * `runtime-detect.mjs`) so adding a new runtime there auto-extends every
+ * downstream diagnostic. The legacy fallback path is only populated for
+ * runtimes that declare a legacy topology in `LEGACY_INSTALL_PATHS`.
+ *
+ * Backward-compat: `host` field stays `'claude-code'` for the claude
+ * runtime (the statusline chip + several other consumers key on this
+ * exact string). The new `runtime` field exposes the descriptor id
+ * (`'claude'`, `'codex'`, …) for callers that want the canonical name.
  */
 
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { LEGACY_INSTALL_PATHS } from '../install/legacy-paths.mjs'
+import { MANIFEST_FILENAME, readManifest } from '../install/manifest.mjs'
+import { RUNTIMES } from '../install/runtime-detect.mjs'
 
+/**
+ * Map a runtime descriptor id to the `host` value historical consumers
+ * expect. The Claude runtime is the only one with a non-identity mapping
+ * (`'claude' → 'claude-code'`) — every other id is its own host string.
+ *
+ * @param {string} runtimeId
+ * @returns {string}
+ */
+function hostFor(runtimeId) {
+	return runtimeId === 'claude' ? 'claude-code' : runtimeId
+}
+
+/**
+ * @typedef {Object} SkillInstallSurface
+ * @property {string} host                       Backward-compat host id.
+ * @property {string} runtime                    Canonical runtime id (from RUNTIMES).
+ * @property {string} install_root               Absolute path of the runtime install root.
+ * @property {string} manifest_path              Absolute path of apt-file-manifest.json.
+ * @property {string|null} legacy_version_file   Absolute path of the legacy .apt-version stamp, or null.
+ */
+
+/**
+ * Return one install-surface descriptor per runtime in `RUNTIMES`.
+ *
+ * @param {string} projectDir
+ * @returns {SkillInstallSurface[]}
+ */
 export function getSkillInstallSurfaces(projectDir) {
 	const root = resolve(projectDir)
-	return [
-		{
-			host: 'claude-code',
-			skills_dir: join(root, '.claude', 'skills'),
-		},
-		{
-			host: 'codex',
-			skills_dir: join(root, '.agents', 'skills'),
-		},
-	].map((surface) => ({
-		...surface,
-		version_file: join(surface.skills_dir, '.apt-version'),
-	}))
+	return RUNTIMES.map((descriptor) => {
+		const install_root = join(root, descriptor.installRoot)
+		const legacyTopology = LEGACY_INSTALL_PATHS[descriptor.id]
+		const legacy_version_file = legacyTopology ? join(root, legacyTopology.version_file) : null
+		return {
+			host: hostFor(descriptor.id),
+			runtime: descriptor.id,
+			install_root,
+			manifest_path: join(install_root, MANIFEST_FILENAME),
+			legacy_version_file,
+		}
+	})
 }
 
+/**
+ * @typedef {Object} SkillInstallState
+ * @property {string} host
+ * @property {string} runtime
+ * @property {string} install_root
+ * @property {string} manifest_path
+ * @property {string|null} legacy_version_file
+ * @property {boolean} installed
+ * @property {string|null} installed_version
+ * @property {boolean} stale
+ * @property {'manifest' | 'manifest-malformed' | 'legacy_version_file' | null} source
+ */
+
+/**
+ * Read each surface's install state. See the file header for the
+ * precedence rules.
+ *
+ * @param {string} projectDir
+ * @param {string} frameworkVersion
+ * @returns {SkillInstallState[]}
+ */
 export function readSkillInstallState(projectDir, frameworkVersion) {
 	return getSkillInstallSurfaces(projectDir).map((surface) => {
-		const installed_version = existsSync(surface.version_file)
-			? readFileSync(surface.version_file, 'utf-8').trim()
-			: null
+		const manifestExists = existsSync(surface.manifest_path)
+		if (manifestExists) {
+			const manifest = readManifest(surface.install_root)
+			if (manifest && typeof manifest.framework_version === 'string') {
+				return {
+					...surface,
+					installed: true,
+					installed_version: manifest.framework_version,
+					stale: manifest.framework_version !== frameworkVersion,
+					source: /** @type {const} */ ('manifest'),
+				}
+			}
+			// Manifest file present but parser rejected it (malformed JSON,
+			// missing required fields, …). Don't silently report healthy.
+			return {
+				...surface,
+				installed: true,
+				installed_version: null,
+				stale: true,
+				source: /** @type {const} */ ('manifest-malformed'),
+			}
+		}
+
+		if (surface.legacy_version_file && existsSync(surface.legacy_version_file)) {
+			try {
+				if (statSync(surface.legacy_version_file).isFile()) {
+					const version = readFileSync(surface.legacy_version_file, 'utf-8').trim()
+					return {
+						...surface,
+						installed: true,
+						installed_version: version,
+						stale: version !== frameworkVersion,
+						source: /** @type {const} */ ('legacy_version_file'),
+					}
+				}
+			} catch {
+				/* fall through to "not installed" */
+			}
+		}
+
 		return {
 			...surface,
-			installed: installed_version !== null,
-			installed_version,
-			stale: installed_version !== null && installed_version !== frameworkVersion,
+			installed: false,
+			installed_version: null,
+			stale: false,
+			source: null,
 		}
 	})
 }

package/src/cli/util/version-preflight.mjs

@@ -0,0 +1,65 @@
+/**
+ * util/version-preflight.mjs — FRAMEWORK-BUG-017 (rung 2 of 3).
+ *
+ * Pure helper for cmds that depend on a flag / behavior introduced in a
+ * specific framework version. When the installed kernel predates that
+ * version, returning a structured `version_drift` envelope is strictly
+ * better than the silent infra-backoff loop that bit us in
+ * FRAMEWORK-BUG-010.
+ *
+ * Scope (Codex review edit 1): this is a **future-guard** for the next
+ * framework fix that introduces a new flag. A stale 0.6.6 install
+ * obviously cannot execute 0.6.8 preflight code (the helper doesn't
+ * exist there). The actual catch-point for already-stale installs is
+ * the route-side `detectSourceWorkspaceDrift`. This helper makes the
+ * NEXT bug bundle cheaper to ship safely.
+ */
+
+import { compareVersions, SEMVER_RE } from './semver.mjs'
+
+/**
+ * Preflight check: is the installed kernel new enough to support the
+ * named feature?
+ *
+ * - Returns `null` when the install is at-or-above `introducedIn` (pass).
+ * - Returns `null` when `installedVersion` is malformed (fail-open — a
+ *   corrupted `package.json` shouldn't lock users out of every cmd; the
+ *   route-level drift check still catches the same install via the
+ *   version mismatch path).
+ * - Returns a `version_drift` error envelope when the install predates
+ *   `introducedIn`. Callers `exitWith(envelope, 1)`.
+ *
+ * @param {Object} args
+ * @param {string} args.feature  Short name of the feature being gated.
+ * @param {string} args.introducedIn  Minimum framework version that ships the feature.
+ * @param {string} args.installedVersion  The installed kernel's version.
+ * @param {string} args.missingFlag  The CLI flag that requires this version (e.g. '--payload-file').
+ * @returns {null | {
+ *   status: 'error',
+ *   command: 'version-preflight',
+ *   error_code: 'version_drift',
+ *   feature: string,
+ *   introduced_in: string,
+ *   installed_version: string,
+ *   missing_flag: string,
+ *   reason: string,
+ * }}
+ */
+export function requireMinVersion({ feature, introducedIn, installedVersion, missingFlag }) {
+	if (!installedVersion || typeof installedVersion !== 'string') return null
+	if (!SEMVER_RE.test(installedVersion)) return null
+	if (!SEMVER_RE.test(introducedIn)) return null
+
+	if (compareVersions(installedVersion, introducedIn) >= 0) return null
+
+	return {
+		status: 'error',
+		command: 'version-preflight',
+		error_code: 'version_drift',
+		feature,
+		introduced_in: introducedIn,
+		installed_version: installedVersion,
+		missing_flag: missingFlag,
+		reason: `cmd needs feature ${feature} introduced in version ${introducedIn}; installed version is ${installedVersion} — run /apt:update`,
+	}
+}