@aperant/framework 0.13.0 → 0.15.0

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

@@ -0,0 +1,1023 @@
+/**
+ * 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
+ * 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
+ * JSON (ID-01).
+ *
+ * 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
+ *      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`.
+ *   2. Collect signals from repo baseline ∪ PR diff (ID-02). A `--diff <path>`
+ *      flag (the orchestrator already writes diff.patch) adds changed-file
+ *      paths + added lines as diff-introduced signals.
+ *   3. Apply --scope (ID-02a). Default `repo`: baseline counts repo-wide.
+ *      `diff`: a baseline signal only counts when it shares an owning/top-level
+ *      directory with a diff-touched path; otherwise only diff signals count.
+ *   4. Decide engage via the STRONG/WEAK tier rule (ID-03a):
+ *          engage = (>= 1 STRONG signal) OR (>= 2 distinct WEAK signals)
+ *      A lone weak token never spawns a specialist.
+ *
+ * Each signal is `{ kind, detail, tier }` where `tier ∈ {strong, weak}` and
+ * `detail` names the exact match (file path / manifest dep / token + file) so
+ * the human-readable `reason` is traceable.
+ *
+ * The signal tables are CURATED + EXTENSIBLE — a new ecosystem is added by
+ * appending one entry; the engine logic is unchanged.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { extname, join, relative, resolve, sep } from 'node:path'
+import { parseFlags } from '../../util/args.mjs'
+import { err, ok } from '../../util/result.mjs'
+
+/**
+ * @typedef {{ kind: string, detail: string, tier: 'strong' | 'weak' }} Signal
+ *
+ * @typedef {{ engage: boolean, signals: Signal[], reason: string }} SpecialistDecision
+ */
+
+// Manifests scanned for dependency-substring i18n/xplatform library markers.
+// No YAML/TOML parse — substring/regex on the raw text, mirroring
+// toolchain-detect.mjs:isBerryNodeLinker (R2).
+const MANIFEST_FILES = [
+	'package.json',
+	'Cargo.toml',
+	'pyproject.toml',
+	'requirements.txt',
+	'go.mod',
+	'Gemfile',
+	'composer.json',
+	'build.gradle',
+	'build.gradle.kts',
+	'Podfile',
+	'pubspec.yaml',
+]
+
+// CI workflow files scanned for a multi-OS matrix (substring of runs-on:/os:).
+const CI_FILES = ['.gitlab-ci.yml', 'azure-pipelines.yml']
+
+// Directories never walked when collecting baseline file-pattern signals.
+const SKIP_DIRS = new Set([
+	'.git',
+	'node_modules',
+	'.aperant',
+	'dist',
+	'build',
+	'target',
+	'.next',
+	'vendor',
+	'.venv',
+	'venv',
+	'__pycache__',
+])
+
+// Cap the baseline file walk so a huge repo can't make the detector slow.
+const MAX_WALK_FILES = 20000
+
+/**
+ * Walk `root` collecting relative file paths (POSIX-normalized), skipping
+ * heavy/irrelevant dirs. Bounded by MAX_WALK_FILES.
+ *
+ * @param {string} root
+ * @returns {string[]} repo-relative paths using '/'
+ */
+function walkFiles(root) {
+	const out = []
+	const stack = [root]
+	while (stack.length > 0 && out.length < MAX_WALK_FILES) {
+		const dir = stack.pop()
+		let entries
+		try {
+			entries = readdirSync(dir, { withFileTypes: true })
+		} catch {
+			continue
+		}
+		for (const entry of entries) {
+			const abs = join(dir, entry.name)
+			if (entry.isDirectory()) {
+				if (SKIP_DIRS.has(entry.name)) continue
+				stack.push(abs)
+			} else if (entry.isFile()) {
+				out.push(relative(root, abs).split(sep).join('/'))
+				if (out.length >= MAX_WALK_FILES) break
+			}
+		}
+	}
+	return out
+}
+
+/** Read a file as UTF-8, returning '' on any error. */
+function readSafe(absPath) {
+	try {
+		if (!existsSync(absPath)) return ''
+		if (statSync(absPath).isDirectory()) return ''
+		return readFileSync(absPath, 'utf-8')
+	} catch {
+		return ''
+	}
+}
+
+// ── i18n file-pattern matchers (STRONG) ─────────────────────────────────────
+
+// Locale/translation file EXTENSIONS that are unambiguous on their own.
+const I18N_LOCALE_EXTS = new Set([
+	'.po',
+	'.pot',
+	'.mo',
+	'.xliff',
+	'.xlf',
+	'.arb',
+	'.strings',
+	'.stringsdict',
+	'.resx',
+	'.resw',
+	'.xcstrings',
+	'.ftl',
+])
+
+// Directory-name segments that mark a path as i18n/locale territory.
+const I18N_DIR_SEGMENTS = ['locales', 'i18n', 'translations']
+
+/**
+ * Decide whether a repo-relative path is a STRONG i18n locale-file signal.
+ * Returns a `detail` string when it matches, else null. Encodes the ID-03 +
+ * ID-03b file-pattern rules (Android values-*, Java messages bundle, Qt *.ts
+ * disambiguation).
+ *
+ * @param {string} relPath POSIX-normalized repo-relative path
+ * @returns {string | null}
+ */
+function i18nLocaleFileDetail(relPath) {
+	const lower = relPath.toLowerCase()
+	const segments = lower.split('/')
+	const base = segments[segments.length - 1]
+	const ext = extname(lower)
+
+	// 1. Unambiguous locale-file extension.
+	if (I18N_LOCALE_EXTS.has(ext)) return `locale-file ${relPath}`
+
+	// 2. Path lives under a locale/i18n/translations dir.
+	if (segments.some((s) => I18N_DIR_SEGMENTS.includes(s))) {
+		return `locale-dir file ${relPath}`
+	}
+
+	// 3. lang/**/*.json
+	if (segments.includes('lang') && ext === '.json') return `lang-json ${relPath}`
+
+	// 4. messages.<locale>.json (e.g. messages.fr.json)
+	if (/^messages\.[a-z-]+\.json$/.test(base)) return `messages-json ${relPath}`
+
+	// 5. Android string resources: res/values/strings.xml + res/values-*/strings.xml
+	if (base === 'strings.xml') {
+		const valuesIdx = segments.findIndex((s) => s === 'values' || s.startsWith('values-'))
+		if (valuesIdx >= 0 && segments[valuesIdx - 1] === 'res') {
+			return `android-strings ${relPath}`
+		}
+	}
+
+	// 6. Java resource bundles: *_*.properties under a messages/i18n/resources dir.
+	if (/^[a-zA-Z0-9]+_[a-zA-Z]{2}(_[A-Za-z]+)?\.properties$/.test(base)) {
+		if (segments.some((s) => ['messages', 'i18n', 'resources'].includes(s))) {
+			return `java-bundle ${relPath}`
+		}
+	}
+
+	// 7. Qt translation *.ts — ID-03b: ONLY under a translations/i18n dir
+	//    (a bare top-level *.ts is TypeScript and is NOT an i18n signal; a plain
+	//    source dir literally named `ts/` is the common false positive, so it is
+	//    NOT a translation-dir marker — real Qt Linguist files live under
+	//    translations/ or i18n/).
+	if (ext === '.ts') {
+		if (segments.some((s) => ['translations', 'i18n'].includes(s))) {
+			return `qt-translation ${relPath}`
+		}
+	}
+
+	return null
+}
+
+// ── i18n manifest-dependency matchers ───────────────────────────────────────
+
+// Unambiguous i18n libraries (STRONG) matched as substrings in ANY manifest
+// EXCEPT the Python-only Babel family (handled separately in
+// scanManifestForI18n because JS babel is a transpiler, NOT i18n — ID-03b).
+const I18N_LIB_SUBSTRINGS = [
+	'i18next',
+	'react-i18next',
+	'vue-i18n',
+	'@formatjs',
+	'intl-messageformat',
+	'lingui',
+	'@lingui',
+	'node-polyglot',
+	'@fluent',
+	'fluent-bundle',
+	'rust-i18n',
+	'go-i18n',
+	'gotext',
+	'symfony/translation',
+	'gettext',
+	'rails-i18n',
+]
+
+// Python-only Babel family (STRONG) — only counts in a Python manifest
+// (pyproject.toml / requirements.txt). ID-03b: a package.json babel* dep is
+// NEVER an i18n signal.
+const PY_BABEL_SUBSTRINGS = ['babel', 'flask-babel', 'pybabel']
+
+// ACCEPTED LIMITATION (no-parse design, R2): this scans the manifest's RAW
+// text as a substring, NOT a parsed dependency graph. A library name that
+// appears in prose — e.g. `"description": "a gettext parser"` — can therefore
+// false-trigger an i18n signal. A real fix requires parsing the manifest
+// (YAML/TOML/JSON), which this detector DELIBERATELY avoids (see the file
+// header + the MANIFEST_FILES comment). The STRONG/WEAK tier model bounds the
+// blast radius for source TOKENS, but a manifest LIBRARY match is STRONG, so
+// this specific prose-substring false positive is knowingly tolerated.
+/**
+ * Scan a single manifest's raw text for i18n library substrings.
+ *
+ * @param {string} manifestName
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanManifestForI18n(manifestName, text) {
+	const found = []
+	const lower = text.toLowerCase()
+	const isPythonManifest = manifestName === 'pyproject.toml' || manifestName === 'requirements.txt'
+
+	for (const lib of I18N_LIB_SUBSTRINGS) {
+		if (lower.includes(lib.toLowerCase())) {
+			found.push({ kind: 'i18n-lib', detail: `${lib} in ${manifestName}`, tier: 'strong' })
+		}
+	}
+
+	// Python Babel family — ID-03b. `flask-babel`/`pybabel` are unambiguous;
+	// bare `babel` only counts in a Python manifest context.
+	if (isPythonManifest) {
+		for (const lib of PY_BABEL_SUBSTRINGS) {
+			// Match `babel` as a token (word boundary) so we don't catch e.g.
+			// some unrelated `babelfish` substring; flask-babel/pybabel are
+			// matched as plain substrings.
+			const re =
+				lib === 'babel' ? /\bbabel\b/i : new RegExp(lib.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
+			if (re.test(text)) {
+				found.push({
+					kind: 'i18n-lib',
+					detail: `python-${lib} in ${manifestName}`,
+					tier: 'strong',
+				})
+			}
+		}
+	}
+
+	return found
+}
+
+// ── i18n source-token matchers (WEAK unless corroborated by an i18n import) ──
+
+// An i18n import present in a source file makes a `t(`/`i18n.t(` token STRONG.
+const I18N_IMPORT_HINTS = [
+	'i18next',
+	'react-i18next',
+	'vue-i18n',
+	'@lingui',
+	'@formatjs',
+	'use-intl',
+	'next-intl',
+	'gettext',
+	'@fluent',
+]
+
+// Lone i18n source tokens (WEAK). `_(` is DROPPED entirely (ID-03b — too noisy).
+const I18N_WEAK_TOKEN_RES = [
+	{ re: /\bi18n\.t\s*\(/, label: 'i18n.t(' },
+	{ re: /(?<![\w.])t\s*\(\s*['"]/, label: 't(' },
+	{ re: /\bgettext\s*\(/, label: 'gettext(' },
+	{ re: /\bngettext\s*\(/, label: 'ngettext(' },
+	{ re: /\bNSLocalizedString\s*\(/, label: 'NSLocalizedString(' },
+	{ re: /\bR\.string\./, label: 'R.string.' },
+	{ re: /\bString\.localized\b/, label: 'String.localized' },
+	{ re: /#\[derive\(Localize\)\]/, label: '#[derive(Localize)]' },
+]
+
+/**
+ * Scan one source blob for i18n tokens. A `t(`/`i18n.t(` token is STRONG when
+ * an i18n import is present in the SAME blob; otherwise WEAK (ID-03b).
+ *
+ * @param {string} detailLabel  where the blob came from (file path or "diff")
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanSourceForI18nTokens(detailLabel, text) {
+	const found = []
+	const hasI18nImport = I18N_IMPORT_HINTS.some((h) => text.includes(h))
+	for (const { re, label } of I18N_WEAK_TOKEN_RES) {
+		if (re.test(text)) {
+			const corroborated = (label === 't(' || label === 'i18n.t(') && hasI18nImport
+			found.push({
+				kind: 'i18n-token',
+				detail: corroborated
+					? `${label} in ${detailLabel} (i18n import present)`
+					: `${label} in ${detailLabel} (no i18n import)`,
+				tier: corroborated ? 'strong' : 'weak',
+			})
+		}
+	}
+	return found
+}
+
+// ── xplatform matchers ──────────────────────────────────────────────────────
+
+// Cross-platform app frameworks (STRONG) matched as manifest substrings.
+const XPL_FRAMEWORK_SUBSTRINGS = [
+	'electron',
+	'@tauri-apps',
+	'react-native',
+	'flutter',
+	'@capacitor',
+	'nativescript',
+	'maui',
+	'xamarin',
+	'pyqt',
+	'pyside',
+	'kivy',
+]
+
+/**
+ * Scan a manifest for cross-platform framework substrings.
+ *
+ * @param {string} manifestName
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanManifestForXplatform(manifestName, text) {
+	const found = []
+	const lower = text.toLowerCase()
+	for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+		if (lower.includes(fw)) {
+			found.push({
+				kind: 'xplatform-framework',
+				detail: `${fw} in ${manifestName}`,
+				tier: 'strong',
+			})
+		}
+	}
+	// Qt via a generic `qt` substring is too noisy for a manifest scan; PyQt /
+	// PySide above are the unambiguous Python Qt markers. (Qt C++ projects are
+	// caught by the compile-guard / *.ui paths instead.)
+	return found
+}
+
+// Compile-time platform guards (STRONG) — source-token regexes spanning
+// Rust / Go / C/C++ / CMake / Swift.
+const XPL_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>' },
+	{ re: /\bruntime\.GOOS\b/, label: 'runtime.GOOS' },
+	{ re: /#ifdef\s+_WIN32/, label: '#ifdef _WIN32' },
+	{ re: /#ifdef\s+__APPLE__/, label: '#ifdef __APPLE__' },
+	{ re: /#ifdef\s+__linux__/, label: '#ifdef __linux__' },
+	{ re: /\bif\s*\(\s*WIN32\s*\)/, label: 'if(WIN32)' },
+	{ re: /\bif\s*\(\s*APPLE\s*\)/, label: 'if(APPLE)' },
+	{ re: /\bif\s*\(\s*UNIX\s*\)/, label: 'if(UNIX)' },
+	{ re: /#if\s+os\s*\(/, label: '#if os(' },
+]
+
+// Lone runtime platform checks (WEAK).
+const XPL_WEAK_TOKEN_RES = [
+	{ re: /\bprocess\.platform\b/, label: 'process.platform' },
+	{ re: /\bos\.platform\s*\(/, label: 'os.platform()' },
+	{ re: /\bsys\.platform\b/, label: 'sys.platform' },
+	{ re: /\bplatform\.system\s*\(/, label: 'platform.system()' },
+	{ re: /\bRuntimeInformation\.IsOSPlatform\b/, label: 'RuntimeInformation.IsOSPlatform' },
+	{ re: /System\.getProperty\s*\(\s*["']os\.name["']/, label: 'System.getProperty("os.name")' },
+	{ re: /\bPlatform\.OS\b/, label: 'Platform.OS' },
+	{ re: /\bPlatform\.isAndroid\b/, label: 'Platform.isAndroid' },
+]
+
+/**
+ * Scan one source blob for xplatform 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) {
+	const found = []
+	for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+		if (re.test(text)) {
+			found.push({
+				kind: 'xplatform-guard',
+				detail: `${label} in ${detailLabel}`,
+				tier: 'strong',
+			})
+		}
+	}
+	for (const { re, label } of XPL_WEAK_TOKEN_RES) {
+		if (re.test(text)) {
+			found.push({
+				kind: 'xplatform-runtime',
+				detail: `${label} in ${detailLabel}`,
+				tier: 'weak',
+			})
+		}
+	}
+	return found
+}
+
+const OS_TOKEN_GROUPS = [
+	['ubuntu', 'linux'],
+	['macos', 'darwin', 'macos-latest'],
+	['windows', 'windows-latest'],
+]
+
+// Per-family recognized RUNNER value regexes for a YAML list-item branch — these
+// must match the WHOLE list-item value (anchored), and stay INDEX-ALIGNED with
+// OS_TOKEN_GROUPS (linux, macos, windows). A list item like `- windows-build-tools`
+// or `- macos-codesign-helper` (e.g. under a `packages:` key) is NOT a recognized
+// runner and must NOT inflate the multi-OS family count, while real block-list
+// runners `- ubuntu-latest` / `- macos-latest` / `- windows-latest` / `- ubuntu-22.04`
+// still match.
+const OS_RUNNER_RES = [
+	/^(ubuntu(-(latest|\d[\w.-]*))?|linux)$/,
+	/^(macos(-(latest|\d[\w.-]*))?|darwin)$/,
+	/^(windows(-(latest|\d[\w.-]*))?)$/,
+]
+
+/**
+ * Detect a multi-OS CI matrix in a workflow's raw text. No YAML parse (R2) —
+ * substring scan of `runs-on:`/`os:` lines for >1 distinct OS family.
+ *
+ * @param {string} workflowName
+ * @param {string} text
+ * @returns {{kind:string, detail:string, tier:string} | null}
+ */
+function detectCiMatrix(workflowName, text) {
+	const lines = text.split('\n')
+	const osFamilies = new Set()
+	for (const line of lines) {
+		// R2: only OS-bearing config lines count — a `runs-on:` / `os:` key line,
+		// or a YAML list-item line (e.g. `- ubuntu-latest`) that sits under an
+		// `os:` matrix key without repeating the key. Scanning EVERY line would
+		// let an unrelated dep/comment/path mentioning an OS substring (e.g.
+		// `npm install windows-build-tools` under a single `runs-on: ubuntu`)
+		// inflate the family count into a phantom multi-OS matrix — exactly the
+		// false-positive the STRONG/WEAK tier model exists to prevent.
+		const isKeyLine = /\b(runs-on|os)\s*:/i.test(line)
+		const listItemMatch = line.match(/^\s*-\s+['"]?([\w.-]+)['"]?\s*$/)
+		if (!isKeyLine && !listItemMatch) continue
+		if (isKeyLine) {
+			// Key-line (`runs-on:` / `os:`) substring branch — UNCHANGED.
+			const lower = line.toLowerCase()
+			for (let gi = 0; gi < OS_TOKEN_GROUPS.length; gi++) {
+				if (OS_TOKEN_GROUPS[gi].some((tok) => lower.includes(tok))) osFamilies.add(gi)
+			}
+		} else if (listItemMatch) {
+			// List-item branch — count an OS family ONLY when the WHOLE list-item
+			// value is a recognized runner token (anchored OS_RUNNER_RES). This
+			// stops a non-`os:` list like `- windows-build-tools` /
+			// `- macos-codesign-helper` (e.g. under a `packages:` key) from
+			// inflating the multi-OS family count.
+			const value = listItemMatch[1].toLowerCase()
+			for (let gi = 0; gi < OS_RUNNER_RES.length; gi++) {
+				if (OS_RUNNER_RES[gi].test(value)) osFamilies.add(gi)
+			}
+		}
+	}
+	if (osFamilies.size > 1) {
+		return {
+			kind: 'xplatform-ci-matrix',
+			detail: `multi-OS CI matrix in ${workflowName} (${osFamilies.size} OS families)`,
+			tier: 'strong',
+		}
+	}
+	return null
+}
+
+/**
+ * Detect platform-conditional directory siblings (STRONG) over a list of
+ * repo-relative paths: windows/ + macos/ + linux/ co-present, or
+ * *.xcodeproj + build.gradle co-presence.
+ *
+ * @param {string[]} relPaths POSIX-normalized
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function detectPlatformDirSiblings(relPaths) {
+	const found = []
+	const hasWindowsDir = relPaths.some((p) => p.split('/').includes('windows'))
+	const hasMacosDir = relPaths.some((p) => p.split('/').includes('macos'))
+	const hasLinuxDir = relPaths.some((p) => p.split('/').includes('linux'))
+	if (hasWindowsDir && hasMacosDir && hasLinuxDir) {
+		found.push({
+			kind: 'xplatform-dir-siblings',
+			detail: 'platform dir siblings windows/ + macos/ + linux/ co-present',
+			tier: 'strong',
+		})
+	}
+	const hasXcodeproj = relPaths.some((p) => p.endsWith('.xcodeproj') || p.includes('.xcodeproj/'))
+	const hasGradle = relPaths.some((p) => {
+		const base = p.split('/').pop()
+		return base === 'build.gradle' || base === 'build.gradle.kts'
+	})
+	if (hasXcodeproj && hasGradle) {
+		found.push({
+			kind: 'xplatform-dir-siblings',
+			detail: '*.xcodeproj + build.gradle co-presence',
+			tier: 'strong',
+		})
+	}
+	return found
+}
+
+/**
+ * Lone weak file signals over a path list: a *.plist or *.rc file.
+ *
+ * @param {string[]} relPaths
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function detectWeakXplatformFiles(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' })
+	}
+	return found
+}
+
+// ── Diff parsing ─────────────────────────────────────────────────────────────
+
+/**
+ * Parse a unified diff into { touchedPaths: string[], addedText: string }.
+ * `touchedPaths` are POSIX-normalized repo-relative paths from the `+++ b/...`
+ * (and `--- a/...` for deletions) headers; `addedText` concatenates added
+ * lines (those starting with `+` but not `+++`).
+ *
+ * @param {string} patch
+ * @returns {{ touchedPaths: string[], addedText: string }}
+ */
+export function parseUnifiedDiff(patch) {
+	const touched = new Set()
+	const added = []
+	for (const line of patch.split('\n')) {
+		if (line.startsWith('+++ ')) {
+			const p = line.slice(4).trim()
+			if (p && p !== '/dev/null') touched.add(stripDiffPrefix(p))
+		} else if (line.startsWith('--- ')) {
+			const p = line.slice(4).trim()
+			if (p && p !== '/dev/null') touched.add(stripDiffPrefix(p))
+		} else if (line.startsWith('diff --git ')) {
+			// `diff --git a/x b/x` — capture both sides defensively.
+			const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/)
+			if (m) {
+				touched.add(m[1])
+				touched.add(m[2])
+			}
+		} else if (line.startsWith('+') && !line.startsWith('+++')) {
+			added.push(line.slice(1))
+		}
+	}
+	return { touchedPaths: [...touched], addedText: added.join('\n') }
+}
+
+function stripDiffPrefix(p) {
+	// Strip a/ b/ prefixes git emits, and any timestamp suffix after a tab.
+	let out = p.split('\t')[0]
+	if (out.startsWith('a/') || out.startsWith('b/')) out = out.slice(2)
+	return out.split(sep).join('/')
+}
+
+// ── Engagement decision ──────────────────────────────────────────────────────
+
+/**
+ * Decide engage from a signal list + reason string per ID-03a, after scoping.
+ *
+ * @param {Signal[]} signals
+ * @returns {SpecialistDecision}
+ */
+function decideFromSignals(signals) {
+	const strong = signals.filter((s) => s.tier === 'strong')
+	const weak = signals.filter((s) => s.tier === 'weak')
+	if (strong.length >= 1) {
+		return {
+			engage: true,
+			signals,
+			reason: `strong: ${strong.map((s) => s.detail).join('; ')}`,
+		}
+	}
+	if (weak.length >= 2) {
+		return {
+			engage: true,
+			signals,
+			reason: `weak x${weak.length}: ${weak.map((s) => s.detail).join(' + ')}`,
+		}
+	}
+	if (weak.length === 1) {
+		return {
+			engage: false,
+			signals,
+			reason: `weak x1 uncorroborated: ${weak[0].detail} — not engaged`,
+		}
+	}
+	return { engage: false, signals, reason: 'no signals' }
+}
+
+// Common monorepo container dirs: a path under one of these is owned by its
+// SECOND segment (the package name), not the container itself — so
+// `packages/a/...` and `packages/b/...` are in DIFFERENT owning packages.
+const MONOREPO_CONTAINERS = new Set(['packages', 'apps', 'crates', 'libs', 'modules', 'services'])
+
+/**
+ * The owning directory of a repo-relative POSIX path. Used by the `--scope
+ * diff` rule to decide whether a baseline signal "shares an owning directory"
+ * with a diff-touched path. For a path under a monorepo container (e.g.
+ * `packages/a/...`) the owning dir is `packages/a` (the package), so two
+ * sibling packages don't collapse to the shared container. Otherwise it is the
+ * first path segment.
+ *
+ * @param {string} relPath
+ * @returns {string} owning dir, or '' for a top-level file
+ */
+function owningDir(relPath) {
+	const segments = relPath.split('/')
+	if (segments.length <= 1) return ''
+	if (MONOREPO_CONTAINERS.has(segments[0]) && segments.length >= 3) {
+		return `${segments[0]}/${segments[1]}`
+	}
+	return segments[0]
+}
+
+/**
+ * Extract a repo-relative path out of a signal `detail` string when one is
+ * present (locale files, tokens-in-file, weak files all embed a path). Returns
+ * null for path-less signals (manifest deps, CI matrices, dir-siblings) — those
+ * are treated as repo-wide and are NOT subject to diff-scoping path matching.
+ *
+ * @param {{detail:string}} signal
+ * @returns {string | null}
+ */
+function signalPath(signal) {
+	const d = signal.detail
+	// All file/token details carry the path as the last whitespace-delimited
+	// token that contains a '/' or a recognized file extension, but we encode
+	// them as "<label> <path>" / "<label> in <path> (...)". Pull the path out.
+	const inMatch = d.match(/ in ([^\s(]+)/)
+	if (inMatch && inMatch[1].includes('/')) return inMatch[1]
+	const tailMatch = d.match(/([^\s]+\/[^\s]+)$/)
+	if (tailMatch) return tailMatch[1]
+	// "<label> <path>" form (e.g. "locale-file src/locales/fr.json").
+	const parts = d.split(' ')
+	const last = parts[parts.length - 1]
+	if (last?.includes('/')) return last
+	return null
+}
+
+/**
+ * Apply --scope. Returns the signal subset that counts for engagement.
+ *
+ * @param {Array} baselineSignals
+ * @param {Array} diffSignals
+ * @param {string[]} diffTouchedPaths
+ * @param {'repo'|'diff'} scope
+ * @returns {{ counted: Array, scopingNote: string | null }}
+ */
+function applyScope(baselineSignals, diffSignals, diffTouchedPaths, scope) {
+	if (scope === 'repo') {
+		return { counted: [...baselineSignals, ...diffSignals], scopingNote: null }
+	}
+	// scope === 'diff': a baseline signal only counts when it shares an owning
+	// dir with a diff-touched path (or is path-less → repo-wide manifest/CI
+	// marker, which we conservatively still count). Otherwise drop it.
+	const touchedOwningDirs = new Set(diffTouchedPaths.map(owningDir))
+	const counted = [...diffSignals]
+	const dropped = []
+	for (const sig of baselineSignals) {
+		const p = signalPath(sig)
+		if (p === null) {
+			// Path-less repo-wide marker (manifest dep / CI matrix / dir-sibling)
+			// — keep counting it; --scope diff only constrains path-bearing
+			// baseline signals.
+			counted.push(sig)
+			continue
+		}
+		if (touchedOwningDirs.has(owningDir(p))) {
+			counted.push(sig)
+		} else {
+			dropped.push(sig)
+		}
+	}
+	let scopingNote = null
+	if (dropped.length > 0 && counted.length === diffSignals.length) {
+		// All baseline path-bearing signals were dropped as unrelated.
+		const first = dropped[0]
+		const fp = signalPath(first)
+		const touched = diffTouchedPaths.slice(0, 3).join(', ') || '(none)'
+		scopingNote = `baseline ${first.kind} signal in unrelated package ${fp}; diff touches only ${touched} (scope=diff)`
+	}
+	return { counted, scopingNote }
+}
+
+/**
+ * Read `.aperant/config.json:pr_review.specialists` (best-effort).
+ *
+ * @param {string} root
+ * @returns {{ i18n?: string, xplatform?: string }}
+ */
+function readSpecialistConfig(root) {
+	try {
+		const path = join(resolve(root), '.aperant', 'config.json')
+		if (!existsSync(path)) return {}
+		const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+		const spec = parsed?.pr_review?.specialists
+		return spec && typeof spec === 'object' ? spec : {}
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Normalize a config value to auto|always|never (default auto for absent /
+ * invalid).
+ *
+ * @param {unknown} v
+ * @returns {'auto'|'always'|'never'}
+ */
+function normalizeMode(v) {
+	return v === 'always' || v === 'never' ? v : 'auto'
+}
+
+/**
+ * The core detector. Pure over its inputs (reads the filesystem at `root` and
+ * the supplied `diffText`); returns the full
+ * `{ i18n, xplatform }` 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
+ *        (read from .aperant/config.json when omitted)
+ * @returns {{ i18n: SpecialistDecision, xplatform: SpecialistDecision }}
+ */
+export function detectSpecialists(opts) {
+	const root = resolve(opts.root)
+	const scope = opts.scope === 'diff' ? 'diff' : 'repo'
+	const config = opts.config ?? readSpecialistConfig(root)
+	const diffText = opts.diffText ?? ''
+
+	const i18nMode = normalizeMode(config.i18n)
+	const xplatformMode = normalizeMode(config.xplatform)
+
+	// Parse diff once (shared by both specialists).
+	const diff = diffText ? parseUnifiedDiff(diffText) : { touchedPaths: [], addedText: '' }
+
+	// ── i18n ──────────────────────────────────────────────────────────────
+	const i18n = decideSpecialist({
+		mode: i18nMode,
+		root,
+		diff,
+		scope,
+		collectBaseline: collectI18nBaseline,
+		collectDiff: collectI18nDiff,
+	})
+
+	// ── xplatform ───────────────────────────────────────────────────────────
+	const xplatform = decideSpecialist({
+		mode: xplatformMode,
+		root,
+		diff,
+		scope,
+		collectBaseline: collectXplatformBaseline,
+		collectDiff: collectXplatformDiff,
+	})
+
+	return { i18n, xplatform }
+}
+
+/**
+ * Run the full ordered decision for one specialist: config short-circuit (1) →
+ * collect baseline ∪ diff (2) → scope (3) → tier decision (4).
+ *
+ * @returns {SpecialistDecision}
+ */
+function decideSpecialist({ mode, root, diff, scope, collectBaseline, collectDiff }) {
+	// (1) Config check FIRST and absolute (ID-01a).
+	if (mode === 'always') {
+		return { engage: true, signals: [], reason: 'config override: always' }
+	}
+	if (mode === 'never') {
+		return { engage: false, signals: [], reason: 'config override: never' }
+	}
+
+	// (2) Collect baseline ∪ diff signals.
+	const baselineSignals = collectBaseline(root)
+	const diffSignals = collectDiff(diff)
+
+	// (3) Apply scope.
+	const { counted, scopingNote } = applyScope(
+		baselineSignals,
+		diffSignals,
+		diff.touchedPaths,
+		scope,
+	)
+
+	// (4) Tier decision.
+	const decision = decideFromSignals(counted)
+	if (!decision.engage && scopingNote && counted.length === 0) {
+		decision.reason = scopingNote
+	} else if (!decision.engage && scopingNote && decision.reason === 'no signals') {
+		decision.reason = scopingNote
+	}
+	return decision
+}
+
+// ── Per-specialist collectors ────────────────────────────────────────────────
+
+function collectI18nBaseline(root) {
+	const signals = []
+	const files = walkFiles(root)
+	for (const rel of files) {
+		const detail = i18nLocaleFileDetail(rel)
+		if (detail) signals.push({ kind: 'i18n-locale-file', detail, tier: 'strong' })
+	}
+	for (const manifest of MANIFEST_FILES) {
+		const abs = join(root, manifest)
+		if (!existsSync(abs)) continue
+		const text = readSafe(abs)
+		if (text) signals.push(...scanManifestForI18n(manifest, text))
+	}
+	return dedupeSignals(signals)
+}
+
+function collectI18nDiff(diff) {
+	const signals = []
+	for (const rel of diff.touchedPaths) {
+		const detail = i18nLocaleFileDetail(rel)
+		if (detail)
+			signals.push({ kind: 'i18n-locale-file', detail: `${detail} (diff)`, tier: 'strong' })
+	}
+	if (diff.addedText) {
+		// A newly-added i18n library import counts as a manifest-equivalent
+		// strong signal when the added text mentions an unambiguous lib.
+		const lowerAdded = diff.addedText.toLowerCase()
+		for (const lib of I18N_LIB_SUBSTRINGS) {
+			if (lowerAdded.includes(lib.toLowerCase())) {
+				signals.push({ kind: 'i18n-lib', detail: `${lib} (diff added line)`, tier: 'strong' })
+			}
+		}
+		signals.push(...scanSourceForI18nTokens('diff', diff.addedText))
+	}
+	return dedupeSignals(signals)
+}
+
+function collectXplatformBaseline(root) {
+	const signals = []
+	const files = walkFiles(root)
+
+	// Manifest frameworks.
+	for (const manifest of MANIFEST_FILES) {
+		const abs = join(root, manifest)
+		if (!existsSync(abs)) continue
+		const text = readSafe(abs)
+		if (text) signals.push(...scanManifestForXplatform(manifest, text))
+	}
+	// pubspec.yaml present → Flutter (its presence alone is the flutter marker).
+	if (existsSync(join(root, 'pubspec.yaml'))) {
+		signals.push({
+			kind: 'xplatform-framework',
+			detail: 'flutter (pubspec.yaml present)',
+			tier: 'strong',
+		})
+	}
+
+	// CI matrices — .github/workflows/*.yml + standalone CI files.
+	const workflowsDir = join(root, '.github', 'workflows')
+	if (existsSync(workflowsDir)) {
+		try {
+			for (const entry of readdirSync(workflowsDir)) {
+				if (!/\.ya?ml$/i.test(entry)) continue
+				const text = readSafe(join(workflowsDir, entry))
+				const m = detectCiMatrix(`.github/workflows/${entry}`, text)
+				if (m) signals.push(m)
+			}
+		} catch {
+			/* unreadable */
+		}
+	}
+	for (const ci of CI_FILES) {
+		const abs = join(root, ci)
+		if (!existsSync(abs)) continue
+		const m = detectCiMatrix(ci, readSafe(abs))
+		if (m) signals.push(m)
+	}
+
+	// Compile-time guards in source files (scan a bounded set of source files).
+	for (const rel of files) {
+		const ext = extname(rel.toLowerCase())
+		if (
+			['.rs', '.go', '.c', '.cc', '.cpp', '.h', '.hpp', '.swift', '.m', '.mm'].includes(ext) ||
+			rel.split('/').pop()?.toLowerCase() === 'cmakelists.txt'
+		) {
+			const text = readSafe(join(root, rel))
+			if (text) {
+				for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+					if (re.test(text)) {
+						signals.push({ kind: 'xplatform-guard', detail: `${label} in ${rel}`, tier: 'strong' })
+					}
+				}
+			}
+		}
+	}
+
+	// Platform dir siblings + weak files.
+	signals.push(...detectPlatformDirSiblings(files))
+	signals.push(...detectWeakXplatformFiles(files))
+
+	return dedupeSignals(signals)
+}
+
+function collectXplatformDiff(diff) {
+	const signals = []
+	if (diff.addedText) {
+		const lowerAdded = diff.addedText.toLowerCase()
+		for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+			if (lowerAdded.includes(fw)) {
+				signals.push({
+					kind: 'xplatform-framework',
+					detail: `${fw} (diff added line)`,
+					tier: 'strong',
+				})
+			}
+		}
+		signals.push(...scanSourceForXplatformTokens('diff', diff.addedText))
+	}
+	// CI matrix introduced in the diff.
+	for (const rel of diff.touchedPaths) {
+		if (/\.ya?ml$/i.test(rel) && (rel.includes('.github/workflows/') || CI_FILES.includes(rel))) {
+			const m = detectCiMatrix(`${rel} (diff)`, diff.addedText)
+			if (m) signals.push(m)
+		}
+	}
+	signals.push(...detectWeakXplatformFiles(diff.touchedPaths))
+	return dedupeSignals(signals)
+}
+
+/** De-dupe signals by `detail` (a path/token can match more than one rule). */
+function dedupeSignals(signals) {
+	const seen = new Set()
+	const out = []
+	for (const s of signals) {
+		if (seen.has(s.detail)) continue
+		seen.add(s.detail)
+		out.push(s)
+	}
+	return out
+}
+
+/**
+ * CLI subcommand handler: `apt-tools pr-review detect-specialists <dir>
+ * [--diff <patch>] [--scope diff|repo]`.
+ *
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ * @returns {import('../../util/result.mjs').CommandResult}
+ */
+export function cmdDetectSpecialists(projectDir, extraArgs = []) {
+	if (!projectDir) {
+		return err(
+			'Usage: apt-tools pr-review detect-specialists <project-dir> [--diff <patch>] [--scope diff|repo]',
+		)
+	}
+	const root = resolve(projectDir)
+	if (!existsSync(root)) return err(`Directory does not exist: ${root}`)
+
+	const flags = parseFlags(extraArgs)
+	const diffFlag = flags.get('diff')
+	let diffText = ''
+	if (typeof diffFlag === 'string') {
+		if (!existsSync(diffFlag)) return err(`Diff file not found: ${diffFlag}`)
+		diffText = readSafe(resolve(diffFlag))
+	}
+	const scopeFlag = flags.get('scope')
+	const scope = scopeFlag === 'diff' ? 'diff' : 'repo'
+
+	const result = detectSpecialists({ root, diffText, scope })
+
+	return ok({
+		status: 'ok',
+		command: 'pr-review-detect-specialists',
+		scope,
+		i18n: result.i18n,
+		xplatform: result.xplatform,
+	})
+}