@aperant/framework 0.15.0 → 0.16.0

package/skills/apt-pr-review/SKILL.md

@@ -480,12 +480,12 @@ The detector returns:
 ```json
 {
   "i18n":      { "engage": true,  "signals": [{ "kind": "...", "detail": "...", "tier": "strong|weak" }], "reason": "strong: locale-file src/locales/fr.json" },
-  "xplatform": { "engage": false, "signals": [], "reason": "no signals" }
+  "crossplatform": { "engage": false, "signals": [], "reason": "no signals" }
 }
 ```
 
 Engagement precedence (the detector encodes it; you just read the result):
-config `pr_review.specialists.{i18n,xplatform}` ∈ `auto|always|never` (default
+config `pr_review.specialists.{i18n,crossplatform}` ∈ `auto|always|never` (default
 `auto`) is checked FIRST and is absolute — `always` engages with no scan,
 `never` skips with no scan (even when the diff introduces the first locale
 file). Otherwise `auto` defers to the STRONG/WEAK tier scan.
@@ -500,17 +500,17 @@ verbatim, e.g. `config override: never`):
 // metadata.json (additive key)
 "conditional_specialists": {
   "i18n":      { "engaged": true,  "reason": "strong: locale-file src/locales/fr.json" },
-  "xplatform": { "engaged": false, "reason": "no signals" }
+  "crossplatform": { "engaged": false, "reason": "no signals" }
 }
 ```
 
 ```
 i18n: ENGAGED (strong: locale-file src/locales/fr.json)
-xplatform: SKIPPED (no platform signals; config: auto)
+crossplatform: SKIPPED (no platform signals; config: auto)
 ```
 
-Store `result.i18n.engage` and `result.xplatform.engage` as `ENGAGE_I18N` /
-`ENGAGE_XPLATFORM` for Phase 3.
+Store `result.i18n.engage` and `result.crossplatform.engage` as `ENGAGE_I18N` /
+`ENGAGE_CROSSPLATFORM` for Phase 3.
 
 **R3: pin the reviewed head SHA (PR reviews only).** After `gh pr diff` fetches into `pr-review-${REVIEW_ID}`, capture the SHA and pass it to `pr-review start-round`. All subsequent evidence reads within this round should reference this pinned SHA, not a fresh `gh pr view` call — otherwise a mid-round force-push invalidates cited line numbers.
 
@@ -839,7 +839,7 @@ DO NOT return full error output in your response -- write it to the file.
 node packages/framework/bin/apt-tools.mjs workflow advance . --id ${REVIEW_ID} --phase specialist-review
 ```
 
-**CRITICAL: Spawn all SELECTED review agents (6-8) in ONE message using parallel Agent tool calls.** The 6 core specialists ALWAYS spawn. Additionally append the **i18n** agent when `ENGAGE_I18N` is true and the **cross-platform** agent when `ENGAGE_XPLATFORM` is true (from Step 4b). So the set is 6, 7, or 8 agents — all in the SAME message.
+**CRITICAL: Spawn all SELECTED review agents (6-8) in ONE message using parallel Agent tool calls.** The 6 core specialists ALWAYS spawn. Additionally append the **i18n** agent when `ENGAGE_I18N` is true and the **cross-platform** agent when `ENGAGE_CROSSPLATFORM` is true (from Step 4b). So the set is 6, 7, or 8 agents — all in the SAME message.
 
 Each agent receives:
 1. The changed file list
@@ -909,10 +909,10 @@ Agent(
   prompt: "{CONSTRUCTED_PROMPT_WITH_FILLED_PLACEHOLDERS}",
 )
 
-# Append ONLY if ENGAGE_XPLATFORM is true:
+# Append ONLY if ENGAGE_CROSSPLATFORM is true:
 Agent(
-  name: "xplatform-reviewer",
-  subagent_type: "apt-pr-review-xplatform",
+  name: "crossplatform-reviewer",
+  subagent_type: "apt-pr-review-crossplatform",
   description: "Cross-platform review of PR changes",
   prompt: "{CONSTRUCTED_PROMPT_WITH_FILLED_PLACEHOLDERS}",
 )
@@ -1027,7 +1027,7 @@ Review Directory: {REVIEW_DIR}
 
 Read all finding files from {REVIEW_DIR}/findings/ (excluding validated.md if it exists).
 The core finding files are: security.md, quality.md, logic.md, codebase-fit.md, test-integrity.md, performance.md.
-Additionally read i18n.md and/or xplatform.md when present (the conditional specialists write them only when engaged).
+Additionally read i18n.md and/or crossplatform.md when present (the conditional specialists write them only when engaged).
 
 For each finding in each file, run the hypothesis-validation process from your instructions.
 
@@ -1935,7 +1935,7 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 | `review.max_iterations` | number | 4 | Maximum fix-review iterations before stopping. |
 | `review.optional_agents` | string[] | [] | Reserved for future use. Additional specialist agents to spawn beyond the core 6. |
 | `pr_review.specialists.i18n` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional i18n specialist. `always` forces engage, `never` forces skip (over the detector AND over a diff-introduced signal), `auto`/absent defers to `detect-specialists`. Override is the TOP of the precedence chain (ID-01a). |
-| `pr_review.specialists.xplatform` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional cross-platform specialist. Same semantics as `pr_review.specialists.i18n`. |
+| `pr_review.specialists.crossplatform` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional cross-platform specialist. Same semantics as `pr_review.specialists.i18n`. |
 
 ---
 
@@ -1964,7 +1964,7 @@ Agent(
 | Test-integrity reviewer | `.claude/agents/apt-pr-review-test-integrity.md` | Read, Write, Grep, Glob | 3 |
 | Performance reviewer | `.claude/agents/apt-pr-review-performance.md` | Read, Write, Grep, Glob | 3 |
 | i18n reviewer **(conditional)** | `.claude/agents/apt-pr-review-i18n.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages i18n (or config `always`) |
-| Cross-platform reviewer **(conditional)** | `.claude/agents/apt-pr-review-xplatform.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages xplatform (or config `always`) |
+| Cross-platform reviewer **(conditional)** | `.claude/agents/apt-pr-review-crossplatform.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages crossplatform (or config `always`) |
 | Finding validator | `.claude/agents/apt-pr-review-validator.md` | Read, Write, Grep, Glob | 4 |
 | Fix agent (x3) | `.claude/agents/apt-pr-review-fixer.md` | Read, Write, Edit, Bash, Grep, Glob | 6 |
 | Self-reviewer | `.claude/agents/apt-pr-review-self-reviewer.md` | Read, Write, Edit, Bash, Grep, Glob | 7 |

package/src/cli/commands/init.mjs

@@ -23,6 +23,7 @@ import {
 	mkdirSync,
 	readdirSync,
 	readFileSync,
+	unlinkSync,
 	writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
@@ -1276,6 +1277,34 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			}
 		}
 
+		// Orphan-removal sweep — the cross-platform PR-review agent was renamed
+		// from `apt-pr-review-xplatform` to `apt-pr-review-crossplatform`. The
+		// install pipeline writes the current agent set + a fresh manifest but
+		// has NO stale-removal pass (readManifest is consumed only by
+		// skill-installs.mjs + check-version.mjs, never pipeline.mjs), so a
+		// rename leaves the OLD-named file orphaned in every active runtime
+		// root. Targeted, best-effort unlink of that ONE basename from each
+		// requested runtime's install root (the agent lands under different
+		// per-runtime subdirs: claude→agents, pi→skills, windsurf→workflows).
+		// Mirrors runLegacyCleanup's conservative idempotent posture; ENOENT
+		// and any other unlink error is swallowed.
+		const ORPHANED_AGENT_BASENAME = 'apt-pr-review-xplatform.md'
+		const ORPHAN_AGENT_SUBDIRS = ['agents', 'skills', 'workflows', 'rules']
+		for (const runtimeId of effectiveAnswers.runtimes) {
+			const runtime = getRuntime(runtimeId)
+			if (!runtime?.installRoot) continue
+			for (const subdir of ORPHAN_AGENT_SUBDIRS) {
+				const orphanPath = join(installTarget, runtime.installRoot, subdir, ORPHANED_AGENT_BASENAME)
+				if (existsSync(orphanPath)) {
+					try {
+						unlinkSync(orphanPath)
+					} catch {
+						// best-effort — a missing/locked orphan must not fail init
+					}
+				}
+			}
+		}
+
 		const results = await installRuntimes(
 			effectiveAnswers.runtimes,
 			canonicalRoot,

package/src/cli/commands/pr-review/detect-specialists.mjs

@@ -2,7 +2,7 @@
  * commands/pr-review/detect-specialists.mjs — deterministic detector for the
  * two CONDITIONAL /apt:pr-review specialists (i18n + cross-platform).
  *
- * Restores the 2.8 `i18n-reviewer` + `xplatform` perspectives but gates their
+ * Restores the 2.8 `i18n-reviewer` + `crossplatform` perspectives but gates their
  * Phase-3 spawn on a reproducible, language/platform/ecosystem-agnostic scan
  * with a config override on top. The SKILL orchestrator NEVER decides
  * engagement by reading the diff itself — it calls this detector and obeys the
@@ -11,7 +11,7 @@
  * Engagement model (spec ID-01/ID-01a/ID-02/ID-02a/ID-03/ID-03a/ID-03b):
  *
  *   1. Config check FIRST and short-circuit (ID-01a). `.aperant/config.json`
- *      pr_review.specialists.{i18n,xplatform} ∈ {auto|always|never}, default
+ *      pr_review.specialists.{i18n,crossplatform} ∈ {auto|always|never}, default
  *      auto. `always` → engage (no scan); `never` → skip (no scan); only
  *      `auto`/absent proceeds. Config is the TOP of the precedence chain — a
  *      diff-introduced STRONG signal does NOT override `never`.
@@ -44,7 +44,7 @@ import { err, ok } from '../../util/result.mjs'
  * @typedef {{ engage: boolean, signals: Signal[], reason: string }} SpecialistDecision
  */
 
-// Manifests scanned for dependency-substring i18n/xplatform library markers.
+// Manifests scanned for dependency-substring i18n/crossplatform library markers.
 // No YAML/TOML parse — substring/regex on the raw text, mirroring
 // toolchain-detect.mjs:isBerryNodeLinker (R2).
 const MANIFEST_FILES = [
@@ -334,10 +334,10 @@ function scanSourceForI18nTokens(detailLabel, text) {
 	return found
 }
 
-// ── xplatform matchers ──────────────────────────────────────────────────────
+// ── crossplatform matchers ──────────────────────────────────────────────────────
 
 // Cross-platform app frameworks (STRONG) matched as manifest substrings.
-const XPL_FRAMEWORK_SUBSTRINGS = [
+const CROSSPLATFORM_FRAMEWORK_SUBSTRINGS = [
 	'electron',
 	'@tauri-apps',
 	'react-native',
@@ -358,13 +358,13 @@ const XPL_FRAMEWORK_SUBSTRINGS = [
  * @param {string} text
  * @returns {Array<{kind:string, detail:string, tier:string}>}
  */
-function scanManifestForXplatform(manifestName, text) {
+function scanManifestForCrossplatform(manifestName, text) {
 	const found = []
 	const lower = text.toLowerCase()
-	for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+	for (const fw of CROSSPLATFORM_FRAMEWORK_SUBSTRINGS) {
 		if (lower.includes(fw)) {
 			found.push({
-				kind: 'xplatform-framework',
+				kind: 'crossplatform-framework',
 				detail: `${fw} in ${manifestName}`,
 				tier: 'strong',
 			})
@@ -378,7 +378,7 @@ function scanManifestForXplatform(manifestName, text) {
 
 // Compile-time platform guards (STRONG) — source-token regexes spanning
 // Rust / Go / C/C++ / CMake / Swift.
-const XPL_COMPILE_GUARD_RES = [
+const CROSSPLATFORM_COMPILE_GUARD_RES = [
 	{ re: /#\[cfg\(target_os/, label: '#[cfg(target_os' },
 	{ re: /\bcfg!\s*\(\s*windows\b/, label: 'cfg!(windows)' },
 	{ re: /\/\/go:build\s+(windows|darwin|linux)/, label: '//go:build <os>' },
@@ -393,7 +393,7 @@ const XPL_COMPILE_GUARD_RES = [
 ]
 
 // Lone runtime platform checks (WEAK).
-const XPL_WEAK_TOKEN_RES = [
+const CROSSPLATFORM_WEAK_TOKEN_RES = [
 	{ re: /\bprocess\.platform\b/, label: 'process.platform' },
 	{ re: /\bos\.platform\s*\(/, label: 'os.platform()' },
 	{ re: /\bsys\.platform\b/, label: 'sys.platform' },
@@ -405,28 +405,28 @@ const XPL_WEAK_TOKEN_RES = [
 ]
 
 /**
- * Scan one source blob for xplatform compile-guard (STRONG) + lone runtime
+ * Scan one source blob for crossplatform compile-guard (STRONG) + lone runtime
  * (WEAK) tokens.
  *
  * @param {string} detailLabel
  * @param {string} text
  * @returns {Array<{kind:string, detail:string, tier:string}>}
  */
-function scanSourceForXplatformTokens(detailLabel, text) {
+function scanSourceForCrossplatformTokens(detailLabel, text) {
 	const found = []
-	for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+	for (const { re, label } of CROSSPLATFORM_COMPILE_GUARD_RES) {
 		if (re.test(text)) {
 			found.push({
-				kind: 'xplatform-guard',
+				kind: 'crossplatform-guard',
 				detail: `${label} in ${detailLabel}`,
 				tier: 'strong',
 			})
 		}
 	}
-	for (const { re, label } of XPL_WEAK_TOKEN_RES) {
+	for (const { re, label } of CROSSPLATFORM_WEAK_TOKEN_RES) {
 		if (re.test(text)) {
 			found.push({
-				kind: 'xplatform-runtime',
+				kind: 'crossplatform-runtime',
 				detail: `${label} in ${detailLabel}`,
 				tier: 'weak',
 			})
@@ -496,7 +496,7 @@ function detectCiMatrix(workflowName, text) {
 	}
 	if (osFamilies.size > 1) {
 		return {
-			kind: 'xplatform-ci-matrix',
+			kind: 'crossplatform-ci-matrix',
 			detail: `multi-OS CI matrix in ${workflowName} (${osFamilies.size} OS families)`,
 			tier: 'strong',
 		}
@@ -519,7 +519,7 @@ function detectPlatformDirSiblings(relPaths) {
 	const hasLinuxDir = relPaths.some((p) => p.split('/').includes('linux'))
 	if (hasWindowsDir && hasMacosDir && hasLinuxDir) {
 		found.push({
-			kind: 'xplatform-dir-siblings',
+			kind: 'crossplatform-dir-siblings',
 			detail: 'platform dir siblings windows/ + macos/ + linux/ co-present',
 			tier: 'strong',
 		})
@@ -531,7 +531,7 @@ function detectPlatformDirSiblings(relPaths) {
 	})
 	if (hasXcodeproj && hasGradle) {
 		found.push({
-			kind: 'xplatform-dir-siblings',
+			kind: 'crossplatform-dir-siblings',
 			detail: '*.xcodeproj + build.gradle co-presence',
 			tier: 'strong',
 		})
@@ -545,12 +545,14 @@ function detectPlatformDirSiblings(relPaths) {
  * @param {string[]} relPaths
  * @returns {Array<{kind:string, detail:string, tier:string}>}
  */
-function detectWeakXplatformFiles(relPaths) {
+function detectWeakCrossplatformFiles(relPaths) {
 	const found = []
 	for (const p of relPaths) {
 		const ext = extname(p.toLowerCase())
-		if (ext === '.plist') found.push({ kind: 'xplatform-file', detail: `plist ${p}`, tier: 'weak' })
-		else if (ext === '.rc') found.push({ kind: 'xplatform-file', detail: `rc ${p}`, tier: 'weak' })
+		if (ext === '.plist')
+			found.push({ kind: 'crossplatform-file', detail: `plist ${p}`, tier: 'weak' })
+		else if (ext === '.rc')
+			found.push({ kind: 'crossplatform-file', detail: `rc ${p}`, tier: 'weak' })
 	}
 	return found
 }
@@ -731,7 +733,7 @@ function applyScope(baselineSignals, diffSignals, diffTouchedPaths, scope) {
  * Read `.aperant/config.json:pr_review.specialists` (best-effort).
  *
  * @param {string} root
- * @returns {{ i18n?: string, xplatform?: string }}
+ * @returns {{ i18n?: string, crossplatform?: string }}
  */
 function readSpecialistConfig(root) {
 	try {
@@ -759,15 +761,15 @@ function normalizeMode(v) {
 /**
  * The core detector. Pure over its inputs (reads the filesystem at `root` and
  * the supplied `diffText`); returns the full
- * `{ i18n, xplatform }` decision object.
+ * `{ i18n, crossplatform }` decision object.
  *
  * @param {object} opts
  * @param {string} opts.root            absolute project dir
  * @param {string} [opts.diffText]      unified-diff text (optional)
  * @param {'repo'|'diff'} [opts.scope]  default 'repo'
- * @param {{i18n?:string, xplatform?:string}} [opts.config]  override config
+ * @param {{i18n?:string, crossplatform?:string}} [opts.config]  override config
  *        (read from .aperant/config.json when omitted)
- * @returns {{ i18n: SpecialistDecision, xplatform: SpecialistDecision }}
+ * @returns {{ i18n: SpecialistDecision, crossplatform: SpecialistDecision }}
  */
 export function detectSpecialists(opts) {
 	const root = resolve(opts.root)
@@ -776,7 +778,7 @@ export function detectSpecialists(opts) {
 	const diffText = opts.diffText ?? ''
 
 	const i18nMode = normalizeMode(config.i18n)
-	const xplatformMode = normalizeMode(config.xplatform)
+	const crossplatformMode = normalizeMode(config.crossplatform)
 
 	// Parse diff once (shared by both specialists).
 	const diff = diffText ? parseUnifiedDiff(diffText) : { touchedPaths: [], addedText: '' }
@@ -791,17 +793,17 @@ export function detectSpecialists(opts) {
 		collectDiff: collectI18nDiff,
 	})
 
-	// ── xplatform ───────────────────────────────────────────────────────────
-	const xplatform = decideSpecialist({
-		mode: xplatformMode,
+	// ── crossplatform ───────────────────────────────────────────────────────────
+	const crossplatform = decideSpecialist({
+		mode: crossplatformMode,
 		root,
 		diff,
 		scope,
-		collectBaseline: collectXplatformBaseline,
-		collectDiff: collectXplatformDiff,
+		collectBaseline: collectCrossplatformBaseline,
+		collectDiff: collectCrossplatformDiff,
 	})
 
-	return { i18n, xplatform }
+	return { i18n, crossplatform }
 }
 
 /**
@@ -880,7 +882,7 @@ function collectI18nDiff(diff) {
 	return dedupeSignals(signals)
 }
 
-function collectXplatformBaseline(root) {
+function collectCrossplatformBaseline(root) {
 	const signals = []
 	const files = walkFiles(root)
 
@@ -889,12 +891,12 @@ function collectXplatformBaseline(root) {
 		const abs = join(root, manifest)
 		if (!existsSync(abs)) continue
 		const text = readSafe(abs)
-		if (text) signals.push(...scanManifestForXplatform(manifest, text))
+		if (text) signals.push(...scanManifestForCrossplatform(manifest, text))
 	}
 	// pubspec.yaml present → Flutter (its presence alone is the flutter marker).
 	if (existsSync(join(root, 'pubspec.yaml'))) {
 		signals.push({
-			kind: 'xplatform-framework',
+			kind: 'crossplatform-framework',
 			detail: 'flutter (pubspec.yaml present)',
 			tier: 'strong',
 		})
@@ -930,9 +932,13 @@ function collectXplatformBaseline(root) {
 		) {
 			const text = readSafe(join(root, rel))
 			if (text) {
-				for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+				for (const { re, label } of CROSSPLATFORM_COMPILE_GUARD_RES) {
 					if (re.test(text)) {
-						signals.push({ kind: 'xplatform-guard', detail: `${label} in ${rel}`, tier: 'strong' })
+						signals.push({
+							kind: 'crossplatform-guard',
+							detail: `${label} in ${rel}`,
+							tier: 'strong',
+						})
 					}
 				}
 			}
@@ -941,25 +947,25 @@ function collectXplatformBaseline(root) {
 
 	// Platform dir siblings + weak files.
 	signals.push(...detectPlatformDirSiblings(files))
-	signals.push(...detectWeakXplatformFiles(files))
+	signals.push(...detectWeakCrossplatformFiles(files))
 
 	return dedupeSignals(signals)
 }
 
-function collectXplatformDiff(diff) {
+function collectCrossplatformDiff(diff) {
 	const signals = []
 	if (diff.addedText) {
 		const lowerAdded = diff.addedText.toLowerCase()
-		for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+		for (const fw of CROSSPLATFORM_FRAMEWORK_SUBSTRINGS) {
 			if (lowerAdded.includes(fw)) {
 				signals.push({
-					kind: 'xplatform-framework',
+					kind: 'crossplatform-framework',
 					detail: `${fw} (diff added line)`,
 					tier: 'strong',
 				})
 			}
 		}
-		signals.push(...scanSourceForXplatformTokens('diff', diff.addedText))
+		signals.push(...scanSourceForCrossplatformTokens('diff', diff.addedText))
 	}
 	// CI matrix introduced in the diff.
 	for (const rel of diff.touchedPaths) {
@@ -968,7 +974,7 @@ function collectXplatformDiff(diff) {
 			if (m) signals.push(m)
 		}
 	}
-	signals.push(...detectWeakXplatformFiles(diff.touchedPaths))
+	signals.push(...detectWeakCrossplatformFiles(diff.touchedPaths))
 	return dedupeSignals(signals)
 }
 
@@ -1018,6 +1024,6 @@ export function cmdDetectSpecialists(projectDir, extraArgs = []) {
 		command: 'pr-review-detect-specialists',
 		scope,
 		i18n: result.i18n,
-		xplatform: result.xplatform,
+		crossplatform: result.crossplatform,
 	})
 }

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

@@ -181,6 +181,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-improver.md',
 			'agents/apt-planner.md',
 			'agents/apt-pr-review-codebase-fit.md',
+			'agents/apt-pr-review-crossplatform.md',
 			'agents/apt-pr-review-fixer.md',
 			'agents/apt-pr-review-i18n.md',
 			'agents/apt-pr-review-logic.md',