@aperant/framework 0.8.4 → 0.8.6

package/src/cli/coverage-check/user-outcomes.mjs

@@ -0,0 +1,273 @@
+/**
+ * coverage-check/user-outcomes.mjs — `## User Outcomes` PRD section parser.
+ *
+ * Pure, file-IO-free. Mirrors the `coverage-check/acceptance-criteria.mjs`
+ * pattern: takes spec.md content as a string and returns a structured
+ * `{header_present, body_kind, epic?, outcomes[], validation_warnings?}`
+ * envelope the coverage-check command consumes.
+ *
+ * The `## User Outcomes` section is the verify-proof input contract
+ * introduced in v0.8.6 (spec.md §ID-01 / §ID-07). The grammar:
+ *
+ *   ## User Outcomes
+ *
+ *   **Epic:** {one-sentence headline}
+ *
+ *   - **ON** [surface]: {prose}
+ *   - **ON** [surface]: {prose} *(requires ON N)*
+ *
+ *   (refactor-only escape — INSTEAD of the outcome list:)
+ *   _No user-observable changes — pure refactor._
+ *
+ * `surface` is the closed set: electron | web | cli | api | electron+web.
+ *
+ * **Positional ID synthesis (§ID-07 / M1).** The parser counts outcome
+ * rows in document order and synthesizes `id = "O" + (i+1)`. The literal
+ * `**ON**` regex stays — IDs are NOT author-written. The `requires N`
+ * digit captured from `*(requires ON N)*` is validated against the set
+ * of synthesized IDs; on mismatch the parser emits a
+ * `validation_warnings[]` entry of kind `unknown_requires_target`,
+ * skips the dep edge, but still includes the outcome row.
+ *
+ * See packages/framework/skills/apt-plan/SKILL.md Section 5.B for the
+ * authoring contract.
+ */
+
+const VALID_SURFACES = new Set(['electron', 'web', 'cli', 'api', 'electron+web'])
+
+const HEADING_RE = /^(#{1,6})\s+(.*)$/
+const USER_OUTCOMES_HEADING_RE = /^user\s+outcomes\s*$/i
+const EPIC_RE = /^\*\*Epic:\*\*\s+(.+)$/
+const EMPTY_WITH_NOTE_RE = /^_No user-observable changes — pure refactor\._\s*$/
+const OUTCOME_RE =
+	/^-\s+\*\*ON\*\*\s+\[(electron|web|cli|api|electron\+web)\]:\s+(.+?)(\s+\*\(requires\s+ON\s+(\d+)\)\*)?\s*$/
+
+/**
+ * @typedef {Object} UserOutcome
+ * @property {string} id                — synthesized positional ID (O1, O2, ...)
+ * @property {('electron'|'web'|'cli'|'api'|'electron+web')} surface
+ * @property {string} text              — outcome prose (sans the surface tag and requires suffix)
+ * @property {number} [requires]        — the digit captured from `*(requires ON N)*`, when present and valid
+ */
+
+/**
+ * @typedef {Object} ValidationWarning
+ * @property {'unknown_requires_target'} kind
+ * @property {string} outcome_id        — synthesized ID of the outcome carrying the bad `requires`
+ * @property {number} requires          — the offending digit
+ * @property {string} reason            — human-readable explanation
+ */
+
+/**
+ * @typedef {Object} UserOutcomesParseResult
+ * @property {boolean} header_present
+ * @property {('absent'|'empty'|'empty-with-note'|'outcomes')} body_kind
+ * @property {string} [epic]
+ * @property {UserOutcome[]} outcomes
+ * @property {ValidationWarning[]} [validation_warnings]
+ */
+
+/**
+ * Parse the `## User Outcomes` section from a spec.md string.
+ *
+ * @param {string} specContent
+ * @returns {UserOutcomesParseResult}
+ */
+export function parseUserOutcomes(specContent) {
+	if (typeof specContent !== 'string' || specContent.length === 0) {
+		return { header_present: false, body_kind: 'absent', outcomes: [] }
+	}
+
+	const lines = specContent.split('\n')
+
+	// Find the `## User Outcomes` heading + scope to its body (until the next
+	// heading of equal or lower depth).
+	let headingLine = -1
+	let headingLevel = 0
+	for (let i = 0; i < lines.length; i++) {
+		const m = lines[i].trim().match(HEADING_RE)
+		if (m && USER_OUTCOMES_HEADING_RE.test(m[2])) {
+			headingLine = i
+			headingLevel = m[1].length
+			break
+		}
+	}
+
+	if (headingLine === -1) {
+		return { header_present: false, body_kind: 'absent', outcomes: [] }
+	}
+
+	// Collect body lines from heading+1 until the next heading of ANY
+	// depth. The User Outcomes section is intentionally flat — a
+	// downstream sub-heading (e.g. `### Acceptance Criteria` following
+	// directly without a `## ` separator) ends the body. This matches
+	// how authors write the section and avoids accidentally pulling
+	// stray prose from later sections into the outcomes pool.
+	const bodyLines = []
+	for (let i = headingLine + 1; i < lines.length; i++) {
+		const trimmed = lines[i].trim()
+		if (HEADING_RE.test(trimmed)) break
+		bodyLines.push(lines[i])
+	}
+
+	// Classify body shape.
+	const nonBlank = bodyLines.map((l) => l.trim()).filter((l) => l.length > 0)
+
+	if (nonBlank.length === 0) {
+		return { header_present: true, body_kind: 'empty', outcomes: [] }
+	}
+
+	// Empty-with-note escape — body MUST contain only the verbatim
+	// italic-underscore-em-dash-period sentinel (other lines may exist
+	// only if they are the Epic header or blank — but the spec says the
+	// sentinel REPLACES the outcome list, so we require it to be the only
+	// non-blank line OR the only non-Epic non-blank line).
+	let epic
+	const sentinelLines = []
+	const outcomeLines = []
+	for (const line of nonBlank) {
+		const epicMatch = line.match(EPIC_RE)
+		if (epicMatch) {
+			epic = epicMatch[1].trim()
+			continue
+		}
+		if (EMPTY_WITH_NOTE_RE.test(line)) {
+			sentinelLines.push(line)
+			continue
+		}
+		outcomeLines.push(line)
+	}
+
+	// If the sentinel is present and there are NO outcome lines, this is
+	// the empty-with-note branch. The sentinel may co-exist with an Epic
+	// header — that's not required but not forbidden either.
+	if (sentinelLines.length > 0 && outcomeLines.length === 0) {
+		/** @type {UserOutcomesParseResult} */
+		const result = {
+			header_present: true,
+			body_kind: 'empty-with-note',
+			outcomes: [],
+		}
+		if (epic) result.epic = epic
+		return result
+	}
+
+	// If neither the sentinel nor any outcome rows are present, the body
+	// is effectively empty (header present, no parseable content).
+	if (outcomeLines.length === 0) {
+		/** @type {UserOutcomesParseResult} */
+		const result = {
+			header_present: true,
+			body_kind: 'empty',
+			outcomes: [],
+		}
+		if (epic) result.epic = epic
+		return result
+	}
+
+	// Parse outcome rows in document order. Skip non-matching lines (e.g.
+	// stray prose between outcomes) — they don't count as outcomes.
+	/** @type {UserOutcome[]} */
+	const outcomes = []
+	const rawRequires = []
+	for (const line of outcomeLines) {
+		const m = line.match(OUTCOME_RE)
+		if (!m) continue
+		const surface = /** @type {UserOutcome['surface']} */ (m[1])
+		if (!VALID_SURFACES.has(surface)) continue
+		const text = m[2].trim()
+		const id = 'O' + (outcomes.length + 1)
+		const outcome = /** @type {UserOutcome} */ ({ id, surface, text })
+		if (m[4]) {
+			const n = Number.parseInt(m[4], 10)
+			rawRequires.push({ outcomeIndex: outcomes.length, requires: n })
+		}
+		outcomes.push(outcome)
+	}
+
+	if (outcomes.length === 0) {
+		// Header present, prose present, but no parseable `**ON**` rows —
+		// effectively empty.
+		/** @type {UserOutcomesParseResult} */
+		const result = {
+			header_present: true,
+			body_kind: 'empty',
+			outcomes: [],
+		}
+		if (epic) result.epic = epic
+		return result
+	}
+
+	// Validate `requires` cross-refs against the set of synthesized IDs.
+	/** @type {ValidationWarning[]} */
+	const warnings = []
+	for (const r of rawRequires) {
+		if (r.requires >= 1 && r.requires <= outcomes.length) {
+			outcomes[r.outcomeIndex].requires = r.requires
+		} else {
+			warnings.push({
+				kind: 'unknown_requires_target',
+				outcome_id: outcomes[r.outcomeIndex].id,
+				requires: r.requires,
+				reason: `requires ON ${r.requires} but only ${outcomes.length} outcome(s) parsed`,
+			})
+		}
+	}
+
+	/** @type {UserOutcomesParseResult} */
+	const result = {
+		header_present: true,
+		body_kind: 'outcomes',
+		outcomes,
+	}
+	if (epic) result.epic = epic
+	if (warnings.length > 0) result.validation_warnings = warnings
+	return result
+}
+
+/**
+ * Compute the coverage-check gate result for a parsed user-outcomes
+ * envelope. Per §ID-07 table — warn-not-block in v0.8.x, hard-block in
+ * v0.9.0.
+ *
+ *  | header_present | body_kind         | v0.8.x | v0.9.0 |
+ *  |----------------|-------------------|--------|--------|
+ *  | false          | —                 | warn   | block  |
+ *  | true           | empty-with-note   | pass   | pass   |
+ *  | true           | outcomes (≥1)     | pass   | pass   |
+ *  | true           | empty             | block  | block  |
+ *
+ * @param {UserOutcomesParseResult} parsed
+ * @param {string} frameworkVersion — semver string from the kernel's package.json (e.g. "0.8.6")
+ * @returns {('pass'|'warn'|'block')}
+ */
+export function userOutcomesGateResult(parsed, frameworkVersion) {
+	if (parsed.body_kind === 'empty-with-note' || parsed.body_kind === 'outcomes') {
+		return 'pass'
+	}
+	if (parsed.body_kind === 'empty') {
+		// Header present, body empty — author started the section and forgot
+		// to fill it in. Block at every version.
+		return 'block'
+	}
+	// Missing header (body_kind: 'absent'). Warn in 0.8.x, block in 0.9.0+.
+	const major = parseFrameworkMajorMinor(frameworkVersion)
+	if (major === null) return 'warn'
+	const { major: maj, minor: min } = major
+	if (maj > 0 || (maj === 0 && min >= 9)) return 'block'
+	return 'warn'
+}
+
+/**
+ * Parse the leading `major.minor` of a semver string. Returns null on
+ * malformed input (caller treats as "warn" — fail-soft).
+ *
+ * @param {string} version
+ * @returns {{major: number, minor: number} | null}
+ */
+function parseFrameworkMajorMinor(version) {
+	if (typeof version !== 'string') return null
+	const m = version.match(/^(\d+)\.(\d+)/)
+	if (!m) return null
+	return { major: Number.parseInt(m[1], 10), minor: Number.parseInt(m[2], 10) }
+}

package/src/cli/host/detect.mjs

@@ -345,6 +345,6 @@ function detectRawCli(partner, pathEntries, exists) {
 function rawCliInvocation(partner) {
 	if (partner === 'codex') return 'codex exec'
 	if (partner === 'claude') return 'claude -p'
-	if (partner === 'gemini') return 'gemini -m'
+	if (partner === 'gemini') return 'gemini'
 	return partner
 }

package/src/cli/install/install-from-source.mjs

@@ -3,9 +3,9 @@
  *
  * `apt-tools install-from-source <project-dir>` for the Aperant-contributor
  * self-host case. Resolves the workspace `@aperant/framework` chain — packs
- * the framework itself AND every `workspace:*` dependency (currently
- * `@aperant/driver-sdk`, but the walker is general). Hands the full tarball
- * list to a single `npm install --prefix` invocation so the same-PR
+ * the framework itself AND every `workspace:*` dependency (none today after
+ * the 0.8.5 driver-sdk inline, but the walker is general). Hands the full
+ * tarball list to a single `npm install --prefix` invocation so any future
  * unpublished-pair case stops blowing up with `EUNSUPPORTEDPROTOCOL`.
  *
  * Stable envelope:

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

@@ -109,6 +109,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-prototype.md',
 			'agents/apt-quick.md',
 			'agents/apt-release-notes.md',
+			'agents/apt-research.md',
 			'agents/apt-resume.md',
 			'agents/apt-review.md',
 			'agents/apt-roadmap.md',
@@ -151,6 +152,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'commands/apt-prototype.md',
 			'commands/apt-quick.md',
 			'commands/apt-release-notes.md',
+			'commands/apt-research.md',
 			'commands/apt-resume.md',
 			'commands/apt-review.md',
 			'commands/apt-roadmap.md',

package/src/cli/verify-proof/idl/index.mjs

@@ -1,14 +1,13 @@
 /**
  * idl/index.mjs — framework-side re-export of the IDL v1 runtime registry.
  *
- * The SINGLE SOURCE OF TRUTH lives in `@aperant/driver-sdk` (idl.ts) — see
- * ID-04 in spec.md. This file just re-exports those runtime values so
- * framework-internal callers (bundled drivers, resolver, driver-doctor,
- * conformance kit) can import from the existing relative path without
- * paying the cost of refactoring every callsite.
+ * Single source of truth lives at packages/framework/src/driver-sdk/idl.ts
+ * (inlined in 0.8.5 — originally `@aperant/driver-sdk`). This file
+ * re-exports those runtime values so existing callers (bundled drivers,
+ * resolver, driver-doctor, conformance kit) keep working without a
+ * refactor of every callsite.
  *
- * If you add a verb, edit packages/framework-driver-sdk/src/idl.ts. This
- * file requires no maintenance.
+ * If you add a verb, edit packages/framework/src/driver-sdk/idl.ts.
  */
 
 export {
@@ -21,4 +20,4 @@ export {
 	isVerbResult,
 	LIFECYCLE_VERBS,
 	validateVerbArgs,
-} from '@aperant/driver-sdk'
+} from '@aperant/framework/driver-sdk'

package/src/cli/verify-proof/idl/types.ts

@@ -1,9 +1,10 @@
 /**
  * idl/types.ts — re-export the SDK's IDL types for framework-internal use.
  *
- * Single source of truth lives in `@aperant/driver-sdk/idl.ts`. Framework
- * code imports from here so future moves (e.g. an internal-only IDL
- * extension) only touch this re-export, not every call site.
+ * Single source of truth lives at packages/framework/src/driver-sdk/idl.ts
+ * (inlined in 0.8.5). Framework code imports from here so future moves
+ * (e.g. an internal-only IDL extension or re-extraction) only touch this
+ * re-export, not every call site.
  */
 
 export type {
@@ -38,4 +39,4 @@ export type {
 	VerbResult,
 	WaitForEventArgs,
 	WaitForIdleArgs,
-} from '@aperant/driver-sdk'
+} from '@aperant/framework/driver-sdk'

package/src/cli/verify-proof/manifest-schema.json

@@ -164,7 +164,8 @@
 					"type": "object",
 					"required": ["mcp_server_id"],
 					"properties": {
-						"mcp_server_id": { "type": "string" }
+						"mcp_server_id": { "type": "string" },
+						"skill_id": { "type": "string" }
 					}
 				},
 				{

package/src/cli/verify-proof/resolver.mjs

@@ -16,12 +16,24 @@
  *
  * Ties are broken by the next dimension; if every dimension is equal the
  * driver with the lexicographically smaller driverId wins (deterministic).
+ *
+ * v0.8.6 — `resolveDriversForOutcomes(opts)` adds per-outcome driver
+ * dispatch for cross-surface specs (per spec §ID-03). It accepts the
+ * positional `outcomes[]` produced by `parseUserOutcomes` and returns
+ * `Array<{outcome_id, surface, driver}>` — one entry per
+ * (outcome, surface) pair. For `[electron+web]` outcomes it emits TWO
+ * entries with the same outcome_id and different drivers. The
+ * outcome_id field is passed through verbatim from parser → resolver
+ * → workflow runner with no name rewriting (the positional-ID
+ * contract).
+ *
+ * Existing `resolveDriver()` and `scoreDriver()` exports are unchanged.
  */
 
-import { UnsatisfiedRequiredCapabilityError } from '@aperant/driver-sdk'
+import { UnsatisfiedRequiredCapabilityError } from '@aperant/framework/driver-sdk'
 
 /**
- * @typedef {import('@aperant/driver-sdk').DriverManifest} DriverManifest
+ * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
  * @typedef {import('./runtime-detect.mjs').RuntimeCapabilities} RuntimeCapabilities
  */
 
@@ -131,8 +143,29 @@ export function resolveDriver(opts) {
 		stableOnly.push(d)
 	}
 
-	// Score every survivor against required capabilities.
-	const scored = stableOnly.map((m) => ({ manifest: m, ...scoreDriver(m, runtime, required) }))
+	// Override is hard precedence (per opts.override docstring "explicit
+	// driverId precedence"): when set, try override-listed drivers in
+	// override order — the first one that satisfies every required
+	// capability wins, regardless of compatibility/priority/stability
+	// ranking. Non-matching override entries land in fallback. Only when
+	// every override entry misses a required cap do we fall through to
+	// score-based pick on the remaining drivers.
+	const overrideListed = stableOnly.filter((m) => overrideSet.has(m.driverId))
+	for (const candidate of overrideListed) {
+		const caps = new Set(candidate.capabilities ?? [])
+		const missing = required.filter((c) => !caps.has(c))
+		if (missing.length === 0) {
+			return { selected: candidate, fallback_attempts: fallback }
+		}
+		fallback.push({
+			driver_id: candidate.driverId,
+			reason: `override-listed but missing required capabilities: ${missing.join(', ')}`,
+		})
+	}
+
+	// Score every non-override survivor against required capabilities.
+	const nonOverride = stableOnly.filter((m) => !overrideSet.has(m.driverId))
+	const scored = nonOverride.map((m) => ({ manifest: m, ...scoreDriver(m, runtime, required) }))
 
 	// Sort highest-first, tie-break on driverId for determinism.
 	scored.sort((a, b) => {
@@ -161,3 +194,137 @@ export function resolveDriver(opts) {
 		fallback,
 	)
 }
+
+/**
+ * Map a User Outcomes surface tag to the runtime-capability flag a driver
+ * must carry (via `matchesRuntime`) to be eligible for that surface.
+ *
+ * Closed surface set: `electron | web | cli | api | electron+web`.
+ * `electron+web` is NOT a single flag — it's a cross-surface tag the
+ * workflow runner expands into two single-surface dispatches.
+ *
+ * @param {('electron'|'web'|'cli'|'api')} surface
+ * @returns {('is_electron'|'is_web_frontend'|'has_node')}
+ */
+export function surfaceToRequiredFlag(surface) {
+	switch (surface) {
+		case 'electron':
+			return 'is_electron'
+		case 'web':
+			return 'is_web_frontend'
+		case 'cli':
+		case 'api':
+			return 'has_node'
+		default:
+			throw new Error(`surfaceToRequiredFlag: unknown surface "${surface}"`)
+	}
+}
+
+/**
+ * Resolve a driver per outcome surface tag, NOT per verify-proof run
+ * (per spec §ID-03). For each input outcome the function returns one
+ * `{outcome_id, surface, driver}` entry; for `[electron+web]` outcomes
+ * it returns TWO entries (electron + web) sharing the same outcome_id.
+ *
+ * The `outcome_id` field on each returned entry is the positional ID
+ * produced by `parseUserOutcomes` (e.g. `O1`, `O2`). The resolver does
+ * NOT rewrite or regenerate IDs — they pass through verbatim so the
+ * workflow runner can correlate proof artifacts to spec lines.
+ *
+ * Each per-surface dispatch synthesizes a runtime-capabilities view
+ * that ONLY claims the surface's required flag (e.g. `is_electron`
+ * alone for an electron-surface outcome, even when the project also
+ * carries `is_web_frontend`). This forces the existing scoring to
+ * pick the per-surface driver — without it, a project with BOTH
+ * electron AND web capabilities would always select the highest-
+ * priority bundled driver (currently `browser`) for every outcome.
+ *
+ * Delegates to the existing `resolveDriver()` for the actual scoring
+ * — the scoring code stays in one place.
+ *
+ * @param {Object} opts
+ * @param {DriverManifest[]} opts.drivers
+ * @param {RuntimeCapabilities} opts.runtime
+ * @param {Array<{id: string, surface: 'electron'|'web'|'cli'|'api'|'electron+web'}>} opts.outcomes
+ * @param {string[]} [opts.override]
+ * @param {string[]} [opts.required_stability]
+ * @param {string[]} [opts.required_capabilities] — defaults to ['screenshot']
+ * @returns {Array<{outcome_id: string, surface: string, driver: DriverManifest, fallback_attempts: Array<{driver_id: string, reason: string}>}>}
+ */
+export function resolveDriversForOutcomes(opts) {
+	const drivers = opts.drivers ?? []
+	const runtime = opts.runtime
+	const outcomes = opts.outcomes ?? []
+	const required = opts.required_capabilities ?? ['screenshot']
+	const override = opts.override
+	const stability = opts.required_stability
+
+	/** @type {Array<{outcome_id: string, surface: string, driver: DriverManifest, fallback_attempts: Array<{driver_id: string, reason: string}>}>} */
+	const results = []
+
+	for (const outcome of outcomes) {
+		const surfacesToDispatch =
+			outcome.surface === 'electron+web' ? ['electron', 'web'] : [outcome.surface]
+
+		for (const surface of surfacesToDispatch) {
+			const flag = surfaceToRequiredFlag(/** @type {'electron'|'web'|'cli'|'api'} */ (surface))
+			// Synthesize a per-surface runtime view: only the surface's
+			// required flag is on; every other flag is masked off so the
+			// scoring prefers per-surface drivers (otherwise, on a
+			// multi-runtime project, the highest-priority bundled driver
+			// always wins). `has_node` stays on for cli/api since multiple
+			// drivers may target node.
+			const surfaceRuntime = maskRuntimeForSurface(runtime, flag)
+			const resolved = resolveDriver({
+				drivers,
+				runtime: surfaceRuntime,
+				required_capabilities: required,
+				...(override ? { override } : {}),
+				...(stability ? { required_stability: stability } : {}),
+			})
+			results.push({
+				outcome_id: outcome.id,
+				surface,
+				driver: resolved.selected,
+				fallback_attempts: resolved.fallback_attempts,
+			})
+		}
+	}
+
+	return results
+}
+
+/**
+ * Return a copy of `runtime` with every flag false EXCEPT the one named
+ * by `flag`. Used to scope the resolver's compatibility check to a
+ * single surface during per-outcome dispatch.
+ *
+ * @param {RuntimeCapabilities} runtime
+ * @param {string} flag — one of: is_electron | is_web_frontend | has_node
+ * @returns {RuntimeCapabilities}
+ */
+function maskRuntimeForSurface(runtime, flag) {
+	/** @type {RuntimeCapabilities} */
+	const masked = {
+		is_electron: false,
+		is_tauri: false,
+		is_nextjs: false,
+		is_nuxt: false,
+		is_web_frontend: false,
+		is_expo: false,
+		is_react_native: false,
+		has_node: false,
+	}
+	// Only flip the surface's flag on if the project actually carries it
+	// (otherwise the resolver should genuinely fail — fail-closed).
+	if (flag === 'is_electron' && runtime.is_electron) masked.is_electron = true
+	if (flag === 'is_web_frontend' && runtime.is_web_frontend) {
+		masked.is_web_frontend = true
+		// Carry the framework hint too (Next.js / Nuxt) so drivers that
+		// target browser via those frameworks still match.
+		masked.is_nextjs = runtime.is_nextjs
+		masked.is_nuxt = runtime.is_nuxt
+	}
+	if (flag === 'has_node') masked.has_node = runtime.has_node
+	return masked
+}