@aperant/framework 0.6.6 → 0.7.0

package/src/cli/commands/release-notes.mjs

@@ -0,0 +1,187 @@
+/**
+ * commands/release-notes.mjs — `apt-tools release-notes <sub>` (subtask 2-3
+ * of persona-aware-changelog-and-release-note_16-05-26).
+ *
+ * Deterministic I/O surface for the apt:release-notes skill. NEVER calls
+ * an LLM. The SKILL.md body invokes the host LLM to author the note text
+ * and hands the structured payload to this CLI for persistence + compile.
+ *
+ * Sub-verb menu:
+ *
+ *   apt-tools release-notes draft <project-dir> --pr <n> --note "<text>"
+ *       [--persona <id>] [--output-dir <path>] [--commits <sha,sha,...>]
+ *       [--date <YYYY-MM-DD>]
+ *     → write `<output_dir>/_unreleased/PR-<n>.md`. Idempotent.
+ *
+ *   apt-tools release-notes compile <project-dir> --tag <tag>
+ *       [--output-dir <path>]
+ *     → read every `_unreleased/PR-*.md`, filter by persona_filter, write
+ *       `<output_dir>/<tag>.md`, clear `_unreleased/` only on success.
+ *
+ *   apt-tools release-notes publish <project-dir> --tag <tag>
+ *       [--output-dir <path>] [--dry-run]
+ *     → read `<output_dir>/<tag>.md` + shell `gh release create/edit`.
+ *
+ * Return shape: always `{ status, command, ... }`. The wrap() helper in
+ * dispatch.mjs translates `{ status: 'error' }` envelopes into exit-1.
+ */
+
+import { resolve } from 'node:path'
+
+import { compileTag } from '../release-notes/compile.mjs'
+import { writeDraft } from '../release-notes/draft.mjs'
+import { publishTag } from '../release-notes/publish.mjs'
+import { getFlagValue } from '../util/common-flags.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Dispatch shape (mirrors `audit`): `release-notes: (args) =>
+ * wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3))` — args[1] is the
+ * sub-verb, args[2] is the project dir.
+ *
+ * @param {string | undefined} subcommand
+ * @param {string | undefined} projectDirArg
+ * @param {string[] | undefined} extraArgs
+ */
+export async function cmdReleaseNotes(subcommand, projectDirArg, extraArgs) {
+	const args = extraArgs ?? []
+	if (!subcommand) {
+		return err(
+			'Usage: apt-tools release-notes <draft|compile|publish> <project-dir> [flags]\n' +
+				'  draft     write docs/releases/_unreleased/PR-<n>.md\n' +
+				'  compile   read fragments → docs/releases/<tag>.md, clear _unreleased/\n' +
+				'  publish   shell gh release create/edit',
+		)
+	}
+	const projectDir = resolve(projectDirArg && projectDirArg.length > 0 ? projectDirArg : '.')
+
+	switch (subcommand) {
+		case 'draft':
+			return runDraft(projectDir, args)
+		case 'compile':
+			return runCompile(projectDir, args)
+		case 'publish':
+			return runPublish(projectDir, args)
+		default:
+			return err(
+				`apt-tools release-notes: unknown subcommand "${subcommand}". Known: draft, compile, publish.`,
+			)
+	}
+}
+
+/**
+ * draft — write a single PR fragment.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runDraft(projectDir, args) {
+	const prRaw = getFlagValue(args, '--pr')
+	const note = getFlagValue(args, '--note')
+	const persona = getFlagValue(args, '--persona')
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const commitsFlag = getFlagValue(args, '--commits')
+	const dateFlag = getFlagValue(args, '--date')
+
+	if (!prRaw) {
+		return err('release-notes draft: --pr <number> is required')
+	}
+	const pr = Number.parseInt(prRaw, 10)
+	if (!Number.isFinite(pr) || pr <= 0) {
+		return err(`release-notes draft: --pr must be a positive integer (got "${prRaw}")`)
+	}
+	if (!note || note.trim().length === 0) {
+		return err('release-notes draft: --note "<text>" is required (and must be non-empty)')
+	}
+
+	const commits = commitsFlag
+		? commitsFlag
+				.split(',')
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0)
+		: null
+
+	const result = writeDraft({
+		projectDir,
+		pr,
+		note,
+		persona,
+		outputDir: outputDirFlag,
+		commits,
+		date: dateFlag,
+	})
+
+	return ok({
+		status: 'ok',
+		command: 'release-notes-draft',
+		projectDir,
+		pr,
+		written: result.written,
+		reason: result.reason,
+		path: result.path,
+	})
+}
+
+/**
+ * compile — produce the per-tag narrative file from accumulated fragments.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runCompile(projectDir, args) {
+	const tag = getFlagValue(args, '--tag')
+	if (!tag) {
+		return err('release-notes compile: --tag <tag> is required')
+	}
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const result = compileTag({ projectDir, tag, outputDir: outputDirFlag })
+	return ok({
+		status: 'ok',
+		command: 'release-notes-compile',
+		projectDir,
+		tag,
+		written: result.written,
+		path: result.path,
+		fragments_total: result.fragmentsTotal,
+		fragments_in_body: result.fragmentsInBody,
+		fragments_in_triage: result.fragmentsInTriage,
+		fragments_filtered: result.fragmentsFiltered,
+		cleared_unreleased: result.clearedUnreleased,
+	})
+}
+
+/**
+ * publish — shell `gh release create/edit`. Returns a graceful
+ * `{status: 'skipped', reason: 'gh-not-found'}` when gh is unavailable.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runPublish(projectDir, args) {
+	const tag = getFlagValue(args, '--tag')
+	if (!tag) {
+		return err('release-notes publish: --tag <tag> is required')
+	}
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const dryRun = args.includes('--dry-run')
+	const result = publishTag({ projectDir, tag, outputDir: outputDirFlag, dryRun })
+	if (result.status === 'skipped') {
+		return ok({
+			status: 'skipped',
+			command: 'release-notes-publish',
+			projectDir,
+			tag,
+			reason: result.reason,
+			notes_path: result.notesPath ?? null,
+		})
+	}
+	return ok({
+		status: 'ok',
+		command: 'release-notes-publish',
+		projectDir,
+		tag,
+		mode: result.mode,
+		dry_run: dryRun,
+		notes_path: result.notesPath,
+	})
+}

package/src/cli/commands/route.mjs

@@ -26,16 +26,36 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { getTaskIsolationConfig, getTrustedSkillSources } from '../config/load.mjs'
 import '../gate/gates/index.mjs'
 import * as gateRegistry from '../gate/registry.mjs'
 import { detectHost, SUPPORTED_HOSTS } from '../host/detect.mjs'
+import { detectSourceWorkspaceDrift } from '../route/drift-detect.mjs'
 import { buildEnvelope } from '../route/envelope.mjs'
 import { discoverSkills } from '../route/skill-discover.mjs'
 import { executionModesList, isValidExecutionMode } from '../task/execution-mode.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
 
+/**
+ * Read the installed kernel's own version from its package.json.
+ * Same pattern as commands/check-version.mjs:108-109 — `__dirname` of
+ * the running module resolves to the installed kernel for npm-installed
+ * users and to the source workspace for in-monorepo runs. Returns null
+ * on any I/O / parse failure (drift-detect treats null as "skip").
+ */
+function readInstalledKernelVersion() {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkgPath = resolve(here, '..', '..', '..', 'package.json')
+		const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		return typeof pkg?.version === 'string' ? pkg.version : null
+	} catch {
+		return null
+	}
+}
+
 /**
  * Read the shared update-check cache (written by the SessionStart hook
  * via apt-check-update-worker.js) and extract the fields /apt's SKILL.md
@@ -254,7 +274,23 @@ export function cmdRoute(projectDir, extraArgs) {
 	const task_isolation = getTaskIsolationConfig(targetDir)
 
 	const updateCheck = readUpdateCheckCache()
-	const update_check = updateCheck ? { ...updateCheck } : null
+	let update_check = updateCheck ? { ...updateCheck } : null
+
+	// FRAMEWORK-BUG-017 rung 1: in-band detection of workspace-ahead-of-
+	// installed-kernel drift. Catches the self-host contributor case
+	// where the SessionStart worker can't see the local same-PR fix yet.
+	// Workspace wins when both signals fire (workspace is the source of
+	// truth for self-host).
+	const installedKernelVersion = readInstalledKernelVersion()
+	const drift = detectSourceWorkspaceDrift(targetDir, installedKernelVersion)
+	if (drift) {
+		update_check = {
+			update_available: true,
+			installed_version: drift.installed_version,
+			latest_version: drift.source_version,
+			reason: 'workspace source ahead of installed kernel — run /apt:update --from-source',
+		}
+	}
 
 	// ---------------- Deterministic branches (zero-behavior-change) ----------------
 	// These fire regardless of host detection status — missing host is not

package/src/cli/commands/task.mjs

@@ -1006,6 +1006,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						updateOut.ci_watch_armed = ciWatchResult.ci_watch_armed
 						updateOut.ci_watch_skip_reason = ciWatchResult.ci_watch_skip_reason
 						if (ciWatchResult.ci_watch) updateOut.ci_watch = ciWatchResult.ci_watch
+						// FRAMEWORK-BUG-018 Track 1: surface `scheduler_handle` at the top
+						// level so `apt-ship/SKILL.md` §7.2 can read it via
+						// `.scheduler_handle // empty` without dotting through `.ci_watch.*`.
+						// `null` today (no production path populates it); Track 2 lands
+						// non-null values without re-plumbing the envelope shape.
+						updateOut.scheduler_handle = ciWatchResult.scheduler_handle ?? null
 					}
 					updateResult = ok(updateOut)
 				},
@@ -1217,6 +1223,46 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			// `gh pr view`, and close the ones GitHub says merged. Per spec §B1.
 			const onlyTaskId = flags.get('task') || null
 			const dryRun = flags.has('dry-run')
+			const narrateOnly = flags.has('narrate-only')
+
+			// FRAMEWORK-BUG-020 — `--narrate-only` is read-only enumeration of
+			// the pending_narration[] ledger. No `gh pr view`, no `task close`
+			// spawn, no ledger writes. The skill body (apt-close-task §4) drains
+			// per row via `task narration-drain` AFTER a successful narrator
+			// spawn — at-least-once semantics is safe because the narrator is
+			// anchor-replace idempotent (agents/apt-team-docs-narrator.md §6/§2).
+			if (narrateOnly) {
+				if (!existsSync(statePath)) {
+					return ok({
+						status: 'ok',
+						command: 'task-close-merged',
+						mode: 'narrate-only',
+						closed: [],
+						skipped: [],
+						errors: [],
+					})
+				}
+				const stateBlob = JSON.parse(readFileSync(statePath, 'utf-8'))
+				const ledger = Array.isArray(stateBlob.pending_narration) ? stateBlob.pending_narration : []
+				const filtered = onlyTaskId
+					? ledger.filter((row) => row && row.task_id === onlyTaskId)
+					: ledger
+				return ok({
+					status: 'ok',
+					command: 'task-close-merged',
+					mode: 'narrate-only',
+					closed: filtered.map((row) => ({
+						task_id: row.task_id,
+						scope: row.scope ?? null,
+						phase_id: row.phase_id ?? null,
+						closed_at: row.closed_at ?? null,
+						pr_number: row.pr_number ?? null,
+						narration_pending: true,
+					})),
+					skipped: [],
+					errors: [],
+				})
+			}
 
 			if (!existsSync(statePath)) {
 				return ok({
@@ -1675,6 +1721,7 @@ function armCiWatchAfterPrUrl(targetDir, task, prUrl) {
 			ci_watch_armed: true,
 			ci_watch_skip_reason: null,
 			ci_watch: envelope,
+			scheduler_handle: envelope.scheduler_handle ?? null,
 		}
 	}
 	if (envelope.status === 'busy' && envelope.reason === 'already-armed') {
@@ -1682,12 +1729,14 @@ function armCiWatchAfterPrUrl(targetDir, task, prUrl) {
 			ci_watch_armed: true,
 			ci_watch_skip_reason: 'already-armed',
 			ci_watch: envelope,
+			scheduler_handle: envelope.scheduler_handle ?? null,
 		}
 	}
 	return {
 		ci_watch_armed: false,
 		ci_watch_skip_reason: envelope.reason || 'start-failed',
 		ci_watch: envelope,
+		scheduler_handle: envelope.scheduler_handle ?? null,
 	}
 }
 

package/src/cli/config/load.mjs

@@ -20,6 +20,43 @@ export function loadProjectConfig(targetDir) {
 	}
 }
 
+/**
+ * Load `.aperant/config.json` deep-merged with `.aperant/config.local.json`.
+ * Local wins on key collision. Nested objects merge key-by-key; arrays and
+ * primitives replace wholesale.
+ *
+ * Returns null if config.json is missing/malformed (same as loadProjectConfig).
+ * Throws Error("config.local.json parse error: <msg>") if config.local.json
+ * exists but is malformed — this is a user-visible failure surface; silent
+ * fallback would mask the user's broken override. See FRAMEWORK-AUDIT-001.
+ *
+ * @param {string} targetDir
+ * @returns {object | null}
+ */
+export function loadMergedProjectConfig(targetDir) {
+	const shared = loadProjectConfig(targetDir)
+	if (shared === null) return null
+	const localPath = join(targetDir, '.aperant', 'config.local.json')
+	if (!existsSync(localPath)) return shared
+	let local
+	try {
+		local = JSON.parse(readFileSync(localPath, 'utf-8'))
+	} catch (e) {
+		throw new Error(`config.local.json parse error: ${e.message}`)
+	}
+	return deepMerge(shared, local)
+}
+
+function deepMerge(a, b) {
+	if (a === null || typeof a !== 'object' || Array.isArray(a)) return b
+	if (b === null || typeof b !== 'object' || Array.isArray(b)) return b
+	const out = { ...a }
+	for (const k of Object.keys(b)) {
+		out[k] = k in a ? deepMerge(a[k], b[k]) : b[k]
+	}
+	return out
+}
+
 /**
  * Return a normalized task_isolation config object with safe fallbacks.
  * Always returns a concrete object even when the project has no config at all,

package/src/cli/config/upgrade-gitignore.mjs

@@ -183,6 +183,12 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 	lines.push('events/')
 	lines.push('locks/')
 	lines.push('team-status/')
+	// config.local.json — per-user override file (FRAMEWORK-AUDIT-001). The
+	// deny-by-default `*` rule above already ignores it because no allow line
+	// exists for it; this explicit deny is defense in depth so a future
+	// maintainer cannot accidentally un-ignore it with a broad `!config*.json`
+	// allow rule.
+	lines.push('config.local.json')
 	lines.push('')
 	lines.push('# ── Derived markdown indexes (regenerated from JSON) ──────────────')
 	lines.push('tasks/INDEX.md')

package/src/cli/consistency/parse-review.mjs

@@ -10,7 +10,8 @@
  * `warning` -> `major`. `suggestion|nitpick|note|info` are dropped.
  *
  * Status normalizes to `fixed | deferred | open` (default `open`).
- * `resolved: true` is treated as `status: 'fixed'`.
+ * Both `fixed: true` and `resolved: true` are treated as `status: 'fixed'`
+ * (the reviewer skill writes `fixed: true`; `resolved: true` is legacy).
  *
  * Output: {findings: [{id, severity, status, title, file}]}
  */
@@ -89,6 +90,7 @@ function normalizeSeverity(sev) {
 }
 
 function normalizeStatus(f) {
+	if (f.fixed === true) return 'fixed'
 	if (f.resolved === true) return 'fixed'
 	if (typeof f.status === 'string') {
 		const s = f.status.toLowerCase().trim()

package/src/cli/dispatch.mjs

@@ -71,6 +71,7 @@ import { cmdPrReview } from './commands/pr-review.mjs'
 import { cmdPrecompactHook } from './commands/precompact-hook.mjs'
 import { cmdProductContext } from './commands/product-context.mjs'
 import { cmdProfile } from './commands/profile.mjs'
+import { cmdReleaseNotes } from './commands/release-notes.mjs'
 import { cmdRiskCheck } from './commands/risk-check.mjs'
 import { cmdRoadmap } from './commands/roadmap.mjs'
 import { cmdRoute } from './commands/route.mjs'
@@ -253,6 +254,7 @@ export const DISPATCH = {
 	'variant-pick': (args) => wrap(cmdVariantPick)(args[1], args[2], args.slice(3)),
 	worktree: (args) => wrap(cmdWorktree)(args[1], args[2], args.slice(3)),
 	audit: (args) => wrap(cmdAudit)(args[1], args[2], args.slice(3)),
+	'release-notes': (args) => wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3)),
 	team: (args) => wrap(cmdTeam)(args[1], args[2], args.slice(3)),
 	active: (args) => wrap(cmdActive)(args[1], args[2], args.slice(3)),
 	roadmap: (args) => wrap(cmdRoadmap)(args[1], args[2], args.slice(3)),

package/src/cli/gate/gates/review-clean.mjs

@@ -4,7 +4,9 @@
  *
  * Skipped when {task_dir}/review.json is absent (review is optional for some
  * tracks). When it is present, fails if any finding has
- * severity ∈ {"critical", "warning"} AND resolved !== true.
+ * severity ∈ {"critical", "warning"} AND neither `resolved === true` nor
+ * `fixed === true`. The reviewer skill writes resolution as `fixed: true`
+ * paired with `fix_commit`; `resolved: true` is a legacy alias.
  *
  * The findings array may be under `findings` or `issues` depending on the
  * reviewer format — we accept either.
@@ -47,7 +49,7 @@ const gate = {
 				? doc.issues
 				: []
 		const unresolved = findings.filter(
-			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true,
+			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true && f?.fixed !== true,
 		)
 		if (unresolved.length > 0) {
 			return {

package/src/cli/help.mjs

@@ -31,6 +31,7 @@ Commands:
   task update <dir> --id <id> [--lifecycle-phase <p>] [--pr-url <url>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state; --pr-url may arm ci-watch per ci_watch.after_ship
   task move <dir> --id <id> [--to-scope <s>] [--to-milestone <id>] [--to-phase <id>] [--to-roadmap-ref-url <url>] [--reason <text>] [--force]  Reassign scope/milestone/phase with history
   task close <dir> --id <task-id> [--verdict <v>]  Close task and move to completed
+  task close-merged <dir> [--task <id>] [--narrate-only] [--dry-run]   Sweep shipped-pending-merge tasks for confirmed merges (--narrate-only returns pending_narration[] entries read-only without closing).
   task narration-drain <dir> --task <task-id>     Remove a row from state.pending_narration[] under withFileLock (called by /apt:close-task --narrate-only after a successful narrator spawn)
   task complete-subtask <dir> --task-id <id> --subtask-id <sid|a+b+c> [--commit <sha>] [--notes <text>]  Atomic plan ↔ build-progress sync
   features-audit <dir> [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files

package/src/cli/host/detect.mjs

@@ -12,6 +12,9 @@
  * for misses over silently routing into the wrong runtime.
  */
 
+import { existsSync as fsExistsSync } from 'node:fs'
+import { delimiter as PATH_DELIMITER, join as pathJoin } from 'node:path'
+
 /**
  * Canonical list of runtime identifiers accepted by detectHost's
  * `overrideCli` parameter AND by the route command's `--runtime <id>` flag.
@@ -211,5 +214,137 @@ export function detectHost(opts = {}) {
 		capabilities,
 		aperant_terminal: isAperantTerminal,
 		aperant_socket: aperantSocket,
+		partner_transports: detectPartnerTransports({ env }),
+	}
+}
+
+/**
+ * Partner-transport ladder used by `apt:spar` (FRAMEWORK-BUG-024).
+ *
+ * For each partner (codex / claude / gemini) we resolve a 3-rung ladder in
+ * preference order — MCP first (cleanest integration), then plugin shim
+ * (codex only), then raw CLI on $PATH. The first rung with `detected: true`
+ * wins; the spar skill's gate fails only when all three rungs report
+ * `detected: false`.
+ *
+ * Detection is best-effort and side-effect-free w/r/t the FS — only
+ * `existsSync` reads. No spawn, no network. The MCP rung uses
+ * `detected: "runtime-host-only"` when the framework process cannot probe
+ * the host's deferred-tool registry (the common case — MCP availability
+ * is host-internal), signalling the SKILL body to self-check at invocation
+ * time rather than fail the gate.
+ *
+ * Pure function w/r/t injected `env` + `existsSync` so tests can mock both
+ * without monkey-patching `process.env` or `node:fs`.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] — defaults to `process.env`
+ * @param {(p: string) => boolean} [opts.existsSync] — defaults to `node:fs` existsSync
+ */
+export function detectPartnerTransports(opts = {}) {
+	const env = opts.env ?? process.env
+	const exists = opts.existsSync ?? fsExistsSync
+	const pathEntries = (env.PATH ?? '').split(PATH_DELIMITER).filter(Boolean)
+
+	return {
+		codex: [
+			detectMcpRung('codex', env),
+			detectPluginShim('codex', env, exists),
+			detectRawCli('codex', pathEntries, exists),
+		],
+		claude: [
+			detectMcpRung('claude', env),
+			// No plugin shim exists for Claude today — kept as `detected: false`
+			// for ladder-shape symmetry so consumers can index by rung uniformly.
+			{ rung: 'plugin', detected: false, reason: 'no plugin shim for claude' },
+			detectRawCli('claude', pathEntries, exists),
+		],
+		gemini: [
+			detectMcpRung('gemini', env),
+			{ rung: 'plugin', detected: false, reason: 'no plugin shim for gemini' },
+			detectRawCli('gemini', pathEntries, exists),
+		],
+	}
+}
+
+/**
+ * MCP rung — detected if the host exposes its deferred-tool manifest via
+ * `CLAUDE_MCP_DEFERRED_TOOLS` (a JSON array of tool names) AND a matching
+ * `mcp__<partner>-mcp__*` entry is present. When the env var is absent the
+ * framework cannot observe the host's tool registry from outside, so we
+ * return `detected: "runtime-host-only"` — the SKILL body interprets this
+ * as "try it; if the host has the tool, use it; otherwise fall through".
+ */
+function detectMcpRung(partner, env) {
+	const toolPrefix = mcpToolPrefix(partner)
+	const manifest = env.CLAUDE_MCP_DEFERRED_TOOLS
+	if (manifest) {
+		try {
+			const tools = JSON.parse(manifest)
+			if (
+				Array.isArray(tools) &&
+				tools.some((t) => typeof t === 'string' && t.startsWith(toolPrefix))
+			) {
+				return { rung: 'mcp', detected: true, invocation: `${toolPrefix}*` }
+			}
+			return {
+				rung: 'mcp',
+				detected: false,
+				reason: `no ${toolPrefix}* tool in CLAUDE_MCP_DEFERRED_TOOLS`,
+			}
+		} catch {
+			// Malformed manifest — fall through to runtime-deferred
+		}
+	}
+	return { rung: 'mcp', detected: 'runtime-host-only', invocation: `${toolPrefix}*` }
+}
+
+function mcpToolPrefix(partner) {
+	if (partner === 'codex') return 'mcp__codex-mcp__'
+	if (partner === 'claude') return 'mcp__claude-code-mcp__'
+	if (partner === 'gemini') return 'mcp__gemini-mcp__'
+	return `mcp__${partner}-mcp__`
+}
+
+/**
+ * Plugin-shim rung — Claude Code plugins drop helper scripts under
+ * `${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`. Only codex
+ * ships a companion today; the caller passes `'codex'` to probe.
+ */
+function detectPluginShim(partner, env, exists) {
+	const root = env.CLAUDE_PLUGIN_ROOT
+	if (!root) {
+		return { rung: 'plugin', detected: false, reason: 'CLAUDE_PLUGIN_ROOT unset' }
+	}
+	const script = pathJoin(root, 'scripts', `${partner}-companion.mjs`)
+	if (!exists(script)) {
+		return { rung: 'plugin', detected: false, reason: `${script} not found` }
 	}
+	return { rung: 'plugin', detected: true, invocation: `node "${script}" task` }
+}
+
+/**
+ * Raw-CLI rung — probe pre-split $PATH entries for the partner binary using
+ * existsSync (no spawn). Accepts a pre-split array so detectPartnerTransports
+ * can parse $PATH once and share it across all partner probes.
+ *
+ * The binary name matches the partner id for all three currently-supported
+ * partners (codex / claude / gemini).
+ */
+function detectRawCli(partner, pathEntries, exists) {
+	const bin = partner
+	for (const dir of pathEntries) {
+		const candidate = pathJoin(dir, bin)
+		if (exists(candidate)) {
+			return { rung: 'cli', detected: true, invocation: rawCliInvocation(partner) }
+		}
+	}
+	return { rung: 'cli', detected: false, reason: `${bin} not found on $PATH` }
+}
+
+function rawCliInvocation(partner) {
+	if (partner === 'codex') return 'codex exec'
+	if (partner === 'claude') return 'claude -p'
+	if (partner === 'gemini') return 'gemini -m'
+	return partner
 }

package/src/cli/install/legacy-paths.mjs

@@ -0,0 +1,69 @@
+/**
+ * install/legacy-paths.mjs — shared registry of legacy install topologies
+ * the framework once wrote to but no longer owns. Single source of truth
+ * for both:
+ *
+ *   - BUG-021: `runLegacyCleanup` in `install/runtime-migrate.mjs` knows
+ *     which files under a legacy root are framework-owned (safe to
+ *     remove) vs user-added (preserve).
+ *   - BUG-022: `readSkillInstallState` in `util/skill-installs.mjs` falls
+ *     back to `version_file` here when no manifest is present, so a
+ *     pre-manifest install still surfaces as "installed" rather than
+ *     "missing-skills".
+ *
+ * Derivation: the codex `framework_files` list was extracted from
+ * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
+ * skill install surface" commit) — every `.agents/skills/…` path the
+ * installer once wrote, including the `.apt-version` stamp and the
+ * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
+ * codex installer was retargeted to `.codex/`, that entire tree became
+ * orphaned on upgrading projects.
+ *
+ * Schema:
+ *   { [runtimeId]: {
+ *       install_root:     relative path the runtime once wrote into,
+ *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       framework_files:  array of relative paths the installer once owned
+ *                         (under install_root).
+ *   } }
+ *
+ * Frozen via Object.freeze so callers cannot mutate the shared registry.
+ */
+
+/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
+export const LEGACY_INSTALL_PATHS = Object.freeze({
+	codex: Object.freeze({
+		install_root: '.agents/skills',
+		version_file: '.agents/skills/.apt-version',
+		framework_files: Object.freeze([
+			'.apt-version',
+			'apt/SKILL.md',
+			'apt-debug/SKILL.md',
+			'apt-discuss/SKILL.md',
+			'apt-discuss/examples/rationalization-example.md',
+			'apt-docs/SKILL.md',
+			'apt-execute/SKILL.md',
+			'apt-pause/SKILL.md',
+			'apt-plan/SKILL.md',
+			'apt-pr-review/SCHEMA.md',
+			'apt-pr-review/SKILL.md',
+			'apt-pr-review/prompts/fp-gate-codex.md',
+			'apt-pr-review/templates/external-comment.md',
+			'apt-quick/SKILL.md',
+			'apt-resume/SKILL.md',
+			'apt-review/SKILL.md',
+			'apt-roadmap/SKILL.md',
+			'apt-roundtable/SKILL.md',
+			'apt-run/SKILL.md',
+			'apt-scan/SKILL.md',
+			'apt-setup/SKILL.md',
+			'apt-ship/SKILL.md',
+			'apt-stress-test/SKILL.md',
+			'apt-verify/SKILL.md',
+			'apt-verify-proof/SKILL.md',
+			'apt-verify-proof/references/multi-model-setup.md',
+			'apt-verify-proof/references/multi-model-verification.md',
+			'apt-verify-proof/references/proof-capture.md',
+		]),
+	}),
+})