@aperant/framework 0.6.7 → 0.7.3

package/src/cli/gate/gates/verify-approved.mjs

@@ -3,22 +3,54 @@
  * G4 verify-approved — blocking gate for `apt:ship`.
  *
  * Requires {task_dir}/qa_signoff.json to exist, parse, and carry
- * verdict === "approved". The ship skill's existing prose only asked the
- * agent to "confirm" approval; this gate enforces it deterministically.
+ * verdict === "approved" (BUG-013: normalized via parseQaSignoff — case
+ * and underscore/hyphen variants collapse to canonical). BUG-012: also
+ * accepts `approved-with-notes` when config.qa.approved_with_notes_threshold
+ * is set AND every dimension score meets the threshold (best-effort when
+ * dimensions are missing or in an unknown shape).
  *
- * NOTE: the file may use either `verdict` (newer) or `status` (older) field
- * name for the QA result. We accept both for forwards/backwards compatibility,
- * but only the string "approved" passes — "approved-with-notes" fails
- * because ship-time deserves the strongest signal.
+ * Accepts both `verdict` (newer) and `status` (older) field names — that
+ * normalization is delegated to parseQaSignoff.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { parseQaSignoff } from '../../consistency/parse-qa.mjs'
 import { registerGate } from '../registry.mjs'
 
+/**
+ * Extract dimension scores from the qa_signoff.json shape. We've seen two
+ * shapes in the wild:
+ *   - Array: `dimensions: [{name: 'security', score: 0.9}, ...]`
+ *   - Object: `dimensions: {security: 0.9, performance: 0.85}` OR
+ *     `dimensions: {security: {score: 0.9}, ...}`
+ * Returns an array of numeric scores, or null when no recognizable shape
+ * is present (best-effort accept per brief).
+ */
+function extractDimensionScores(doc) {
+	const dims = doc.dimensions ?? doc.qa?.dimensions ?? null
+	if (!dims) return null
+	if (Array.isArray(dims)) {
+		const scores = dims
+			.map((d) => (typeof d?.score === 'number' ? d.score : null))
+			.filter((s) => s !== null)
+		return scores.length > 0 ? scores : null
+	}
+	if (typeof dims === 'object') {
+		const scores = []
+		for (const v of Object.values(dims)) {
+			if (typeof v === 'number') scores.push(v)
+			else if (typeof v?.score === 'number') scores.push(v.score)
+		}
+		return scores.length > 0 ? scores : null
+	}
+	return null
+}
+
 const gate = {
 	id: 'verify-approved',
-	description: 'qa_signoff.json exists with verdict === "approved"',
+	description:
+		'qa_signoff.json exists with verdict === "approved" (or "approved-with-notes" when configured)',
 	severity: 'blocking',
 	skills: ['ship'],
 	async check(ctx) {
@@ -41,18 +73,69 @@ const gate = {
 				inputs,
 			}
 		}
-		const verdict = doc.verdict ?? doc.status ?? null
-		if (verdict !== 'approved') {
+
+		// BUG-013: route through parseQaSignoff so the verdict is
+		// case-insensitive AND tolerates `_↔-` (so 'APPROVED', 'Approved',
+		// ' approved ', 'APPROVED_WITH_NOTES' all behave canonically). The
+		// pre-fix gate compared the raw string against `'approved'` which
+		// false-rejected every legitimate variant.
+		const { verdict } = parseQaSignoff(doc)
+
+		if (verdict === 'approved') {
 			return {
-				status: 'fail',
-				reason: `qa_signoff.json verdict is "${verdict}" (expected "approved")`,
-				evidence: { verdict },
+				status: 'pass',
+				reason: 'qa_signoff.json verdict normalized to "approved"',
 				inputs,
 			}
 		}
+
+		// BUG-012: accept `approved-with-notes` when the project has opted
+		// in via config.qa.approved_with_notes_threshold. The threshold is
+		// the minimum per-dimension score required. Best-effort: when
+		// dimensions are missing / in an unknown shape we still accept and
+		// log, rather than hard-failing, so projects that haven't started
+		// scoring dimensions yet aren't blocked.
+		if (verdict === 'approved-with-notes') {
+			const threshold = ctx.config?.qa?.approved_with_notes_threshold
+			if (typeof threshold !== 'number') {
+				return {
+					status: 'fail',
+					reason:
+						'qa_signoff.json verdict is "approved-with-notes" but config.qa.approved_with_notes_threshold is not set',
+					evidence: { verdict, threshold: threshold ?? null },
+					inputs,
+				}
+			}
+			const scores = extractDimensionScores(doc)
+			if (scores === null) {
+				return {
+					status: 'pass',
+					reason: `qa_signoff.json verdict is "approved-with-notes" and threshold ${threshold} is enabled; dimensions missing or unknown-shape — accepting best-effort`,
+					evidence: { verdict, threshold, dimensions_present: false },
+					inputs,
+				}
+			}
+			const failing = scores.filter((s) => s < threshold)
+			if (failing.length > 0) {
+				return {
+					status: 'fail',
+					reason: `qa_signoff.json verdict is "approved-with-notes" but ${failing.length}/${scores.length} dimension score(s) below threshold ${threshold}`,
+					evidence: { verdict, threshold, scores, failing },
+					inputs,
+				}
+			}
+			return {
+				status: 'pass',
+				reason: `qa_signoff.json verdict is "approved-with-notes" and all ${scores.length} dimension score(s) meet threshold ${threshold}`,
+				evidence: { verdict, threshold, scores },
+				inputs,
+			}
+		}
+
 		return {
-			status: 'pass',
-			reason: 'qa_signoff.json.verdict === "approved"',
+			status: 'fail',
+			reason: `qa_signoff.json verdict is "${verdict}" (expected "approved" or "approved-with-notes" with threshold)`,
+			evidence: { verdict },
 			inputs,
 		}
 	},

package/src/cli/help.mjs

@@ -31,9 +31,10 @@ 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
+  features-audit <dir> [--task-id <id>] [--no-worktree-redirect] [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files (BUG-025b: --task-id redirects writes to active task's worktree)
   docs-audit <dir> [--diff-files <csv>|--since <ref>|--dry-run] [--policy <path>] [--format json|md]  Audit documented surfaces for docs-drift
 
   lock claim <dir> --subtask <id>       Claim exclusive lock on a subtask
@@ -109,7 +110,9 @@ Commands:
 
   migrate-pr-reviews <project-dir>       Migrate legacy .aperant/reviews/ → .aperant/pr-reviews/pr-{N}/rounds/{R}/ (idempotent)
 
-  validate-evidence <findings-dir> --worktree <path>   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place
+  validate-evidence <findings-dir> --worktree <path> [--allow-approx-evidence] [--approx-floor <n>] [--llm-validator-confirmed]   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place. BUG-014: --allow-approx-evidence opts into Jaccard + line-anchor fallback (downgrade to dismissed_evidence_approx_confirmed unless --llm-validator-confirmed promotes to confirmed_valid_approx).
+
+  vitest doctor <project-dir> [--format json|md]   BUG-026: walk vitest.config.{ts,js,mjs} files, report NODE_ENV/jsxAutomaticShim matrix, warn when JSX-rendering tests lack jsxAutomaticShim coverage (exits 1 on warnings)
 
   wfrun validate <workflow.yaml>                         C17: parse + schema-check a declarative YAML workflow (exits 0 on success)
   wfrun plan <workflow.yaml> [--input k=v …]             C17: resolve DAG waves + inputs, emit run-plan JSON (no side effects)
@@ -125,6 +128,9 @@ Commands:
   pr-review record-comment <dir> --pr <N> --round <R> --url <url> --body-hash <sha256> [--review-id <id>] [--posted-at <iso>]  Append entry to comment_timeline (Phase 6b)
   pr-review audit-fixer <dir> --review-dir <path> --iteration <N> --fixer <name> --worktree <path> --status-line <str>  Audit fixer output against git state; exits 0 with JSON envelope (verdict: verified|hallucinated|skipped)
 
+  ci-watch start|stop|status|tick <dir> [--pr <N>] [...]   /apt:watch-ci primitives — see SKILL.md for full flag matrix
+  ci-watch sweep <dir> --orphaned [--dry-run]              BUG-027: enumerate ci-watches state files, query gh per PR, remove terminal-state (MERGED|CLOSED) entries (manual GC; rate-limited)
+
 Flags:
   --version                             Print version and exit
   --help                                Print usage and exit

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',
+		]),
+	}),
+})

package/src/cli/install/runtime-detect.mjs

@@ -33,6 +33,11 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  *                                  target mapped to a host CLI (e.g. `pi`,
  *                                  which has a detectable host but no apt
  *                                  install root of its own).
+ * @property {string} [displayLabel] Optional user-facing label (e.g. "Kilo Code").
+ *                                  When unset, callers fall back to the
+ *                                  capitalized form of `id`. Use for runtimes
+ *                                  whose product branding differs from the
+ *                                  internal id (C58: `kilo` → "Kilo Code").
  */
 
 /** @type {RuntimeDescriptor[]} */
@@ -78,6 +83,10 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.kilo',
 		markers: ['.kilo/config.json'],
 		cliId: 'kilo',
+		// C58 (0.7.2): user-visible label. Internal id stays `kilo` (zero
+		// migration per spec ID-01). `--kilocode` is also accepted as a
+		// deprecated alias of `--kilo` at the CLI flag parser layer.
+		displayLabel: 'Kilo Code',
 	},
 	{
 		id: 'copilot',

package/src/cli/install/runtime-migrate.mjs

@@ -0,0 +1,252 @@
+/**
+ * install/runtime-migrate.mjs — at-install cleanup of legacy install
+ * trees the framework no longer owns (FRAMEWORK-BUG-021).
+ *
+ * Codex was originally installed into `.agents/skills/` (commit 1a8dd8a8)
+ * and later moved to `.codex/`. Projects that upgraded across that move
+ * end up with a stale `.agents/skills/` tree that:
+ *
+ *   - keeps `.apt-version` on disk → the legacy fallback in
+ *     `readSkillInstallState` reports a stale codex install.
+ *   - shows up in `health-check` as `stale-skills`.
+ *   - leaves dozens of orphaned SKILL.md files the runtime no longer
+ *     reads.
+ *
+ * `runLegacyCleanup` runs once per `apt-tools init` when codex is in the
+ * requested runtime set. It is conservative by default:
+ *
+ *   - Only files listed in `LEGACY_INSTALL_PATHS.codex.framework_files`
+ *     are removed. User-added skill directories (`my-skill/`, …) are
+ *     preserved. If anything beyond the known framework set remains,
+ *     `retained[]` lists those paths.
+ *   - A present-and-current `apt-file-manifest.json` is treated as the
+ *     authoritative "this is a managed install, leave it alone" signal:
+ *     the function no-ops with `reason: 'managed'`.
+ *   - The caller can suppress cleanup entirely via `--keep-legacy` at the
+ *     init.mjs site; the function itself is dumb about flags.
+ */
+
+import { existsSync, readdirSync, rmdirSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { LEGACY_INSTALL_PATHS } from './legacy-paths.mjs'
+import { MANIFEST_FILENAME } from './manifest.mjs'
+
+/**
+ * @typedef {Object} LegacyCodexDetection
+ * @property {boolean} present              True when `.agents/skills/` exists.
+ * @property {string[]} frameworkFiles      Subset of `framework_files` that
+ *                                          actually exist on disk (relative
+ *                                          to install_root).
+ * @property {string[]} userFiles           Everything else under
+ *                                          install_root (relative to
+ *                                          install_root). May include both
+ *                                          files and directories. Drives the
+ *                                          `retained[]` warning.
+ * @property {boolean} hasAptVersion        Whether the legacy `.apt-version`
+ *                                          stamp is present.
+ * @property {boolean} hasManifest          Whether an
+ *                                          `apt-file-manifest.json` is
+ *                                          present at install_root (signals
+ *                                          a managed install — cleanup
+ *                                          should no-op).
+ */
+
+const LEGACY = LEGACY_INSTALL_PATHS.codex
+
+/**
+ * Recursively enumerate every file path under `dir`, returning paths
+ * relative to `dir`. Used to compute the "user files" set (anything not
+ * in the framework_files list).
+ *
+ * Returns []  when the dir doesn't exist. Swallows per-entry errors so a
+ * single unreadable symlink doesn't abort detection.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkRelative(dir) {
+	/** @type {string[]} */
+	const out = []
+	if (!existsSync(dir)) return out
+	/** @param {string} current @param {string} rel */
+	const visit = (current, rel) => {
+		let entries
+		try {
+			entries = readdirSync(current, { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const entry of entries) {
+			const childPath = join(current, entry.name)
+			const childRel = rel ? `${rel}/${entry.name}` : entry.name
+			if (entry.isDirectory()) {
+				visit(childPath, childRel)
+			} else if (entry.isFile()) {
+				out.push(childRel)
+			}
+			// Symlinks / other entry types are intentionally ignored — the
+			// framework only ever writes regular files.
+		}
+	}
+	visit(dir, '')
+	return out
+}
+
+/**
+ * Probe the codex legacy install tree at `<targetDir>/.agents/skills/`.
+ *
+ * @param {string} targetDir
+ * @returns {LegacyCodexDetection}
+ */
+export function detectLegacyCodexTree(targetDir) {
+	const installRoot = join(targetDir, LEGACY.install_root)
+	if (!existsSync(installRoot)) {
+		return {
+			present: false,
+			frameworkFiles: [],
+			userFiles: [],
+			hasAptVersion: false,
+			hasManifest: false,
+		}
+	}
+
+	const onDisk = walkRelative(installRoot)
+	const frameworkSet = new Set(LEGACY.framework_files)
+	const frameworkFiles = onDisk.filter((p) => frameworkSet.has(p))
+	const userFiles = onDisk.filter((p) => !frameworkSet.has(p) && p !== MANIFEST_FILENAME)
+
+	return {
+		present: true,
+		frameworkFiles,
+		userFiles,
+		hasAptVersion: onDisk.includes('.apt-version'),
+		hasManifest: onDisk.includes(MANIFEST_FILENAME),
+	}
+}
+
+/**
+ * Try to remove a directory if it is empty. Swallows ENOTEMPTY / ENOENT
+ * so the caller can blindly sweep candidate dirs in any order.
+ *
+ * @param {string} dir
+ * @returns {boolean} true iff the dir was actually removed.
+ */
+function rmEmptyDir(dir) {
+	if (!existsSync(dir)) return false
+	try {
+		rmdirSync(dir)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Clean up the legacy `.agents/skills/` tree if it looks orphaned.
+ *
+ * Branches:
+ *   1. `present: false` OR `frameworkFiles.length === 0` → no-op,
+ *      `{ ran: false, reason: 'no-legacy' }`.
+ *   2. `hasManifest: true` → managed install, no-op,
+ *      `{ ran: false, reason: 'managed' }`.
+ *   3. Otherwise: per-file `unlinkSync` each framework-owned file;
+ *      `rmdirSync` any now-empty `apt-*` subdirectory; sweep
+ *      `.agents/skills/` only if it is empty; sweep `.agents/` only if
+ *      its `skills/` got removed and `.agents/` is empty.
+ *
+ * Returns `{ ran: true, removed, retained, rmdirs }` on the cleanup
+ * branch:
+ *   - `removed`  — relative paths under `install_root` that were unlinked.
+ *   - `retained` — relative paths under `install_root` that were NOT
+ *     removed (user-added skills / files not in the legacy set).
+ *   - `rmdirs`   — absolute paths of directories that were removed
+ *     (apt-* subdirs, the install_root itself, .agents/), in removal order.
+ *
+ * Atomicity: per-file unlink is non-atomic. A partial-failure scenario
+ * (process killed mid-loop) is tolerable — the next `init` run will
+ * re-detect the remaining framework files and finish the sweep.
+ *
+ * @param {{ targetDir: string, dryRun?: boolean }} args
+ * @returns {
+ *   | { ran: false, reason: 'no-legacy' | 'managed' }
+ *   | { ran: true, removed: string[], retained: string[], rmdirs: string[] }
+ * }
+ */
+export function runLegacyCleanup({ targetDir, dryRun = false }) {
+	const detection = detectLegacyCodexTree(targetDir)
+
+	if (!detection.present || detection.frameworkFiles.length === 0) {
+		return { ran: false, reason: 'no-legacy' }
+	}
+	if (detection.hasManifest) {
+		return { ran: false, reason: 'managed' }
+	}
+
+	const installRoot = join(targetDir, LEGACY.install_root)
+	const removed = []
+	const rmdirs = []
+
+	if (dryRun) {
+		// Dry-run: report what WOULD be removed without touching the filesystem.
+		// `retained` is the user-file set from the pre-walk (no sweep occurred).
+		// `rmdirs` is the set of apt-* subdirs that would become empty after removal.
+		const wouldRemove = detection.frameworkFiles
+		const retained = detection.userFiles
+		const candidateDirs = new Set()
+		for (const rel of wouldRemove) {
+			let parent = dirname(rel)
+			while (parent !== '.' && parent !== '') {
+				candidateDirs.add(parent)
+				parent = dirname(parent)
+			}
+		}
+		const wouldRmdirs = [...candidateDirs]
+			.sort((a, b) => b.length - a.length)
+			.map((rel) => join(installRoot, rel))
+		return { ran: true, dryRun: true, removed: wouldRemove, retained, rmdirs: wouldRmdirs }
+	}
+
+	for (const rel of detection.frameworkFiles) {
+		const abs = join(installRoot, rel)
+		try {
+			unlinkSync(abs)
+			removed.push(rel)
+		} catch {
+			/* best-effort: leave a partial sweep; next run finishes it */
+		}
+	}
+
+	// Sweep any now-empty `apt-*/` subdirs the unlinks left behind.
+	// Walk parent dirs of every removed file in reverse-depth order so
+	// nested `apt-pr-review/prompts/` empties before `apt-pr-review/`.
+	const candidateDirs = new Set()
+	for (const rel of removed) {
+		let parent = dirname(rel)
+		while (parent !== '.' && parent !== '') {
+			candidateDirs.add(parent)
+			parent = dirname(parent)
+		}
+	}
+	const sortedDirs = [...candidateDirs].sort((a, b) => b.length - a.length)
+	for (const rel of sortedDirs) {
+		const abs = join(installRoot, rel)
+		if (rmEmptyDir(abs)) rmdirs.push(abs)
+	}
+
+	// Sweep `.agents/skills/` only if fully empty after the per-file
+	// pass — preserves any user-added skill dirs.
+	if (rmEmptyDir(installRoot)) {
+		rmdirs.push(installRoot)
+		// Sweep `.agents/` only if it became empty too (i.e. no other
+		// `.agents/<sibling>` content the user keeps there).
+		const agentsRoot = dirname(installRoot)
+		if (rmEmptyDir(agentsRoot)) rmdirs.push(agentsRoot)
+	}
+
+	// Use the pre-walk's userFiles as `retained` — the post-walk only existed
+	// to defensively re-scan, but pre-walk already captured user files accurately.
+	// (PRF-002: avoid redundant detectLegacyCodexTree call.)
+	const retained = detection.userFiles
+
+	return { ran: true, removed, retained, rmdirs }
+}