@aperant/framework 0.10.0 → 0.12.0

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

@@ -4,10 +4,14 @@
  *
  * Requires {task_dir}/qa_signoff.json to exist, parse, and carry
  * 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).
+ * and underscore/hyphen variants collapse to canonical).
+ *
+ * v0.9.0 (verify-proof-v2-outcome-walker_27-05-26) — the legacy
+ * `approved-with-notes` acceptance branch is REMOVED. `verify-approved`
+ * only accepts a verdict of exactly `approved`. Tasks whose verify-proof
+ * run returned `needs_human` MUST re-run verify-proof with the missing
+ * transport installed; tasks whose run returned `rejected` MUST fix the
+ * code. There is no middle band.
  *
  * Accepts both `verdict` (newer) and `status` (older) field names — that
  * normalization is delegated to parseQaSignoff.
@@ -18,39 +22,9 @@ 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" (or "approved-with-notes" when configured)',
+	description: 'qa_signoff.json exists with verdict === "approved" (v0.9.0+ two-gate verdict)',
 	severity: 'blocking',
 	skills: ['ship'],
 	applies_to_profile: (ctx) => ctx.profile === 'full-pipeline',
@@ -77,65 +51,32 @@ const gate = {
 
 		// 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') {
+		// ' approved ', 'APPROVED_WITH_NOTES' all behave canonically).
+		// v0.9.0: parseQaSignoff THROWS on legacy approved_with_notes —
+		// surface that as a gate fail with the migration message verbatim.
+		let parsed
+		try {
+			parsed = parseQaSignoff(doc)
+		} catch (err) {
 			return {
-				status: 'pass',
-				reason: 'qa_signoff.json verdict normalized to "approved"',
+				status: 'fail',
+				reason: `qa_signoff.json carries a legacy verdict that requires migration: ${err.message}`,
 				inputs,
 			}
 		}
+		const { verdict } = parsed
 
-		// 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,
-				}
-			}
+		if (verdict === 'approved') {
 			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 },
+				reason: 'qa_signoff.json verdict normalized to "approved"',
 				inputs,
 			}
 		}
 
 		return {
 			status: 'fail',
-			reason: `qa_signoff.json verdict is "${verdict}" (expected "approved" or "approved-with-notes" with threshold)`,
+			reason: `qa_signoff.json verdict is "${verdict}" (expected "approved"; v0.9.0 enum is {approved, rejected, needs_human})`,
 			evidence: { verdict },
 			inputs,
 		}

package/src/cli/git/default-branch.mjs

@@ -0,0 +1,250 @@
+/**
+ * git/default-branch.mjs — local default-branch resolution + merged-PR parsing
+ * for the Team-Change Digest (LD-03/04/05).
+ *
+ * Pure git helpers (no .aperant IO). Every git call uses the no-throw
+ * execFileSync pattern from git/remote.mjs (stdio ['ignore','pipe','ignore'])
+ * so a non-git dir / unresolvable ref returns null instead of throwing.
+ *
+ * The resolver reads the LOCAL default-branch ref only — it NEVER calls
+ * `git fetch`. The digest surfaces work the user has actually pulled, not
+ * unfetched server state (ADR Consequences ¶1).
+ *
+ * @internal
+ */
+
+import { execFileSync } from 'node:child_process'
+
+/**
+ * Run a git command, returning trimmed stdout or null on any error.
+ * @param {string} targetDir
+ * @param {string[]} args
+ * @returns {string|null}
+ */
+function git(targetDir, args) {
+	try {
+		return execFileSync('git', args, {
+			cwd: targetDir,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim()
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Resolve the local default-branch ref, with its current sha. Resolution order:
+ *   1. `git symbolic-ref refs/remotes/origin/HEAD` (strip the
+ *      'refs/remotes/origin/' prefix);
+ *   2. `git config init.defaultBranch`;
+ *   3. existence check of `main` then `master` via `git rev-parse --verify`.
+ *
+ * NEVER fetches. Returns null outside a git repo or when nothing resolves.
+ *
+ * @param {string} targetDir
+ * @returns {{ branch: string, sha: string }|null}
+ */
+export function resolveLocalDefaultBranch(targetDir) {
+	// Fast bail when not a git repo.
+	if (git(targetDir, ['rev-parse', '--git-dir']) === null) return null
+
+	let branch = null
+
+	// (1) origin/HEAD symbolic-ref — the authoritative "what main points at".
+	const originHead = git(targetDir, ['symbolic-ref', 'refs/remotes/origin/HEAD'])
+	if (originHead?.startsWith('refs/remotes/origin/')) {
+		branch = originHead.slice('refs/remotes/origin/'.length)
+	}
+
+	// (2) init.defaultBranch config.
+	if (!branch) {
+		const configured = git(targetDir, ['config', 'init.defaultBranch'])
+		if (configured) branch = configured
+	}
+
+	// (3) existence check main → master.
+	if (!branch) {
+		for (const candidate of ['main', 'master']) {
+			if (git(targetDir, ['rev-parse', '--verify', '--quiet', candidate]) !== null) {
+				branch = candidate
+				break
+			}
+		}
+	}
+
+	if (!branch) return null
+
+	const sha = git(targetDir, ['rev-parse', branch])
+	if (!sha) return null
+
+	return { branch, sha }
+}
+
+/**
+ * Parse a PR number + title from a merge-commit subject/body.
+ *
+ * GitHub merge-commit format:
+ *   subject: "Merge pull request #N from owner/branch"
+ *   body:    "<PR title>"  (first non-empty body line)
+ * Squash-merge format:
+ *   subject: "<PR title> (#N)"
+ *
+ * @param {string} subject
+ * @param {string} body
+ * @returns {{ number: number, title: string }|null}
+ */
+function parsePullRequest(subject, body) {
+	const mergeMatch = subject.match(/^Merge pull request #(\d+) from /)
+	if (mergeMatch) {
+		const number = Number(mergeMatch[1])
+		const firstBodyLine = (body || '')
+			.split('\n')
+			.map((l) => l.trim())
+			.find((l) => l.length > 0)
+		return { number, title: firstBodyLine || subject }
+	}
+
+	// GitHub squash-merge convention: greedy `(.*)` captures the longest prefix
+	// so titles with parentheses (e.g. "feat(core): ...") are handled correctly.
+	const squashMatch = subject.match(/^(.*)\s\(#(\d+)\)\s*$/)
+	if (squashMatch) {
+		return { number: Number(squashMatch[2]), title: squashMatch[1].trim() }
+	}
+
+	return null
+}
+
+/**
+ * Resolve both the introduced-commit author emails (LD-05) and a display name
+ * from a single `git log` call per merge. Replaces the former separate
+ * `introducedAuthorEmails` + `pickAuthorName` pair (PRF-002).
+ *
+ * @param {string} targetDir
+ * @param {string[]} parents          parent shas of the merge commit
+ * @param {string} authorEmail        the merge commit's own author email
+ * @param {string} currentUserEmail   the user's git email (for name picking)
+ * @param {string} fallbackName       merge/commit author name when no better pick
+ * @returns {{ emails: string[], authorName: string }}
+ */
+function resolveIntroducedAuthors(targetDir, parents, authorEmail, currentUserEmail, fallbackName) {
+	if (parents.length >= 2) {
+		const raw = git(targetDir, ['log', `${parents[0]}..${parents[1]}`, '--format=%ae%x1f%an'])
+		if (raw) {
+			const emails = new Set()
+			let pickedName = null
+			for (const line of raw.split('\n')) {
+				const [email, name] = line.split('\x1f')
+				if (!email) continue
+				const normEmail = email.trim().toLowerCase()
+				if (normEmail.length > 0) emails.add(normEmail)
+				if (!pickedName && normEmail !== currentUserEmail) {
+					pickedName = (name || fallbackName).trim()
+				}
+			}
+			if (emails.size > 0) {
+				return { emails: [...emails], authorName: pickedName || fallbackName.trim() }
+			}
+		}
+	}
+	const own = authorEmail.trim().toLowerCase()
+	return {
+		emails: own.length > 0 ? [own] : [],
+		authorName: fallbackName.trim(),
+	}
+}
+
+/**
+ * List merged PRs on the local default branch since `sinceSha`, attributed to
+ * whoever actually wrote the work (LD-04/05).
+ *
+ * Walks `git log --first-parent <sinceSha>..<defaultBranch>`. Each commit that
+ * parses as a PR (merge-commit or squash form) becomes one entry, attributed
+ * via its introduced-commit author emails. An entry is excluded only when ALL
+ * its introduced emails equal `currentUserEmail` (the user's own work) — so a
+ * PR the user merged but a teammate authored still appears.
+ *
+ * The scan is bounded (R3): at most `maxEntries * SCAN_MULTIPLIER` commits are
+ * inspected, so a stale marker can't enumerate an unbounded history.
+ *
+ * @param {string} targetDir
+ * @param {object} opts
+ * @param {string} opts.sinceSha            baseline sha (exclusive lower bound)
+ * @param {string} [opts.defaultBranch]     branch to walk to (default: resolved)
+ * @param {string} opts.currentUserEmail    the user's git email (own-work filter)
+ * @param {number} [opts.maxEntries=7]      cap on returned entries
+ * @returns {{ entries: Array<{ number: number, title: string, author: string }>, more_count: number }}
+ */
+export function listMergedPullRequests(targetDir, opts = {}) {
+	const empty = { entries: [], more_count: 0, more_capped: false }
+	const sinceSha = opts.sinceSha
+	const maxEntries = Number.isInteger(opts.maxEntries) && opts.maxEntries > 0 ? opts.maxEntries : 7
+	const currentUserEmail = (opts.currentUserEmail || '').trim().toLowerCase()
+
+	let defaultBranch = opts.defaultBranch
+	if (!defaultBranch) {
+		const resolved = resolveLocalDefaultBranch(targetDir)
+		if (!resolved) return empty
+		defaultBranch = resolved.branch
+	}
+	if (!sinceSha) return empty
+	if (!/^[0-9a-f]{7,40}$/i.test(sinceSha)) return empty
+
+	const SCAN_MULTIPLIER = 4
+	const scanCap = maxEntries * SCAN_MULTIPLIER
+
+	// One commit per record, fields separated by \x1f, records by \x1e.
+	// %H sha · %P parents · %an author name · %ae author email · %s subject · %b body
+	const FIELD = '\x1f'
+	const RECORD = '\x1e'
+	const format = `%H${FIELD}%P${FIELD}%an${FIELD}%ae${FIELD}%s${FIELD}%b${RECORD}`
+	const raw = git(targetDir, [
+		'log',
+		'--first-parent',
+		`--max-count=${scanCap}`,
+		`--format=${format}`,
+		`${sinceSha}..${defaultBranch}`,
+	])
+	if (!raw) return empty
+
+	const records = raw
+		.split(RECORD)
+		.map((r) => r.replace(/^\n+/, ''))
+		.filter((r) => r.trim().length > 0)
+
+	const matched = []
+	for (const rec of records) {
+		const [sha, parentsRaw, authorName, authorEmail, subject, body] = rec.split(FIELD)
+		if (!sha) continue
+		const pr = parsePullRequest(subject || '', body || '')
+		if (!pr) continue
+
+		const parents = (parentsRaw || '').trim().split(/\s+/).filter(Boolean)
+		const { emails, authorName: resolvedAuthor } = resolveIntroducedAuthors(
+			targetDir,
+			parents,
+			authorEmail || '',
+			currentUserEmail,
+			authorName || 'unknown',
+		)
+
+		// Exclude only when EVERY introduced commit is the current user's own.
+		const allOwn =
+			currentUserEmail.length > 0 &&
+			emails.length > 0 &&
+			emails.every((e) => e === currentUserEmail)
+		if (allOwn) continue
+
+		matched.push({ number: pr.number, title: pr.title, author: resolvedAuthor })
+	}
+
+	const more_capped = records.length >= scanCap
+	if (matched.length <= maxEntries) {
+		return { entries: matched, more_count: 0, more_capped }
+	}
+	return {
+		entries: matched.slice(0, maxEntries),
+		more_count: matched.length - maxEntries,
+		more_capped,
+	}
+}

package/src/cli/git/identity.mjs

@@ -4,10 +4,15 @@
 
 import { execSync } from 'node:child_process'
 
+const _identityCache = new Map()
+
 /**
  * Auto-detect the current user's git identity. Returns null if git config is unset.
+ * Memoized per targetDir for the process lifetime (git identity is stable within a CLI invocation).
  */
 export function getGitIdentity(targetDir) {
+	if (_identityCache.has(targetDir)) return _identityCache.get(targetDir)
+	let result = null
 	try {
 		const name = execSync('git config user.name 2>/dev/null', {
 			cwd: targetDir,
@@ -17,11 +22,12 @@ export function getGitIdentity(targetDir) {
 			cwd: targetDir,
 			encoding: 'utf-8',
 		}).trim()
-		if (!name || !email) return null
-		return { name, email }
+		if (name && email) result = { name, email }
 	} catch {
-		return null
+		/* no git config — result stays null */
 	}
+	_identityCache.set(targetDir, result)
+	return result
 }
 
 /**

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

@@ -88,6 +88,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt.md',
 			'agents/apt-author-skill.md',
 			'agents/apt-bootstrap.md',
+			'agents/apt-catch-up.md',
 			'agents/apt-caveman.md',
 			'agents/apt-classify.md',
 			'agents/apt-close-task.md',
@@ -131,6 +132,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'commands/apt.md',
 			'commands/apt-author-skill.md',
 			'commands/apt-bootstrap.md',
+			'commands/apt-catch-up.md',
 			'commands/apt-caveman.md',
 			'commands/apt-classify.md',
 			'commands/apt-close-task.md',

package/src/cli/install/mcp-server-specs.mjs

@@ -61,6 +61,17 @@ export const PROVISION_SPECS = {
 		args: ['./scripts/tauri-mcp.sh'],
 		requiresLauncherScript: true,
 	},
+	'mobile-mcp': {
+		kind: 'mcp-server',
+		// Unified iOS + Android UI-driving server (Apache-2.0). Pure npm —
+		// the iOS/Android SYSTEM prereqs (idb-companion / adb / Xcode /
+		// Android SDK) are validated by the mobile driver's preflight, NOT
+		// installed here (decision D-09). Matches the driver manifest's
+		// transport.mcp_server_id = "mobile-mcp".
+		command: 'npx',
+		args: ['-y', '@mobilenext/mobile-mcp@latest'],
+		env: {},
+	},
 	// kind 'skill'
 	'agent-browser': {
 		kind: 'skill',
@@ -79,14 +90,15 @@ export const PROVISION_SPECS = {
  * triggers. A multi-surface monorepo (e.g. electron + nextjs) returns
  * multiple ids.
  *
- *   is_electron                          → ['electron']
- *   is_tauri                             → ['tauri']
- *   is_web_frontend|is_nextjs|is_nuxt    → ['agent-browser']
+ *   is_electron                                       → ['electron']
+ *   is_tauri                                          → ['tauri']
+ *   is_web_frontend|is_nextjs|is_nuxt                 → ['agent-browser']
+ *   is_ios_native|is_android_native|is_expo|is_react_native → ['mobile-mcp']
  *
  * Accepts a partial capability record — only the flags it reads need be
  * present (the rest default to absent/false).
  *
- * @param {Partial<import('../util/runtime-capabilities.mjs').RuntimeCapabilities>} runtimeCaps
+ * @param {Partial<import('../util/runtime-capabilities.mjs').RuntimeCapabilities> | null | undefined} runtimeCaps
  * @returns {string[]}
  */
 export function capabilityToProvisionIds(runtimeCaps) {
@@ -97,5 +109,13 @@ export function capabilityToProvisionIds(runtimeCaps) {
 	if (runtimeCaps.is_web_frontend || runtimeCaps.is_nextjs || runtimeCaps.is_nuxt) {
 		ids.push('agent-browser')
 	}
+	if (
+		runtimeCaps.is_ios_native ||
+		runtimeCaps.is_android_native ||
+		runtimeCaps.is_expo ||
+		runtimeCaps.is_react_native
+	) {
+		ids.push('mobile-mcp')
+	}
 	return ids
 }