@aperant/framework 0.8.4 → 0.8.7

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/install/manifest.mjs

@@ -39,6 +39,11 @@ export const MANIFEST_SCHEMA_VERSION = 1
  * @property {string} installedHash
  * @property {string} sourcePath
  * @property {string} transformVersion
+ * @property {boolean} [headerless]  true when the installed file legitimately
+ *   carries no apt-skill-version/apt-hook-version header (e.g. Codex strips it).
+ *   Drift detection skips the missing_header check for these — installedHash is
+ *   the sole drift signal. Absent (undefined) on pre-0.8.6 manifests → treated
+ *   as header-expected, preserving old behavior until re-install.
  */
 
 /**

package/src/cli/install/pipeline.mjs

@@ -17,6 +17,7 @@ import { atomicWriteText } from './atomic-text.mjs'
 import { addManifestEntry, newManifest, sha256, writeManifest } from './manifest.mjs'
 import { getRuntime } from './runtime-detect.mjs'
 import { classifyFileType } from './transforms/_shared.mjs'
+import { parseVersionHeader } from './version-header.mjs'
 
 const TRANSFORM_VERSION = '1'
 
@@ -67,6 +68,12 @@ function safeResolveWithin(installRoot, outputPath) {
  * @property {string} canonicalRelPath
  * @property {string} version
  * @property {'skill'|'agent'|'hook-js'|'hook-sh'|'unknown'} fileType
+ * @property {Record<string, string>} [agentContentByName]  canonical agent body
+ *   keyed by agent name (basename sans `.md`, e.g. `apt-planner`). Lets a
+ *   transform inline a referenced agent's prompt when the target runtime has
+ *   no separate agent-spawn surface (Codex). The pipeline always supplies it
+ *   (empty object when no agents discovered); optional here so unit tests can
+ *   construct a TransformInput without it — transforms default it to `{}`.
  */
 
 /**
@@ -180,6 +187,19 @@ export function runInstall({
 	const files = canonicalFiles ?? discoverCanonicalFiles(canonicalRoot)
 	const written = []
 	const skipped = []
+	// Map of agent name → canonical agent body, so a transform whose runtime
+	// has no separate agent-spawn surface (Codex) can inline a referenced
+	// agent's prompt. Keyed by basename sans `.md` (e.g. `apt-planner`). When
+	// the same name exists under both skills/ and agents/, last-wins — they are
+	// the same agent (see the de-dupe note below).
+	/** @type {Record<string, string>} */
+	const agentContentByName = {}
+	for (const f of files) {
+		if (f.fileType === 'agent') {
+			const name = f.relPath.replace(/^.*\//, '').replace(/\.md$/, '')
+			agentContentByName[name] = f.content
+		}
+	}
 	// De-dupe by output path — last-write-wins. Two canonical files can
 	// legitimately target the same output (e.g. skills/apt-planner.md and
 	// agents/apt-planner.md both producing agents/apt-planner.md). The
@@ -200,6 +220,7 @@ export function runInstall({
 				canonicalRelPath: f.relPath,
 				version,
 				fileType: f.fileType,
+				agentContentByName,
 			})
 		} catch (err) {
 			skipped.push(
@@ -225,12 +246,19 @@ export function runInstall({
 			}
 			atomicWriteText(absPath, out.content)
 			const installedHash = sha256(out.content)
+			// Record whether the installed file carries a version header. When a
+			// transform legitimately strips it (Codex frontmatter whitelist),
+			// drift detection must not flag it missing_header — installedHash is
+			// the drift signal. Only relevant for header-bearing file types.
+			const headerless =
+				/\.(md|js|mjs|sh)$/.test(out.outputPath) && parseVersionHeader(out.content) === null
 			entryByPath.set(out.outputPath, {
 				path: out.outputPath,
 				sourceHash,
 				installedHash,
 				sourcePath: `packages/framework/${f.relPath}`,
 				transformVersion: TRANSFORM_VERSION,
+				...(headerless ? { headerless: true } : {}),
 			})
 			if (!written.includes(out.outputPath)) written.push(out.outputPath)
 		}

package/src/cli/install/transforms/codex.mjs

@@ -14,6 +14,13 @@
  *     against installRoot `.agents` to land at `.agents/skills/<folder>/SKILL.md`).
  *     Markdown agents are NOT a Codex surface (custom-agents are TOML
  *     under `.codex/agents/`); only skills are emitted.
+ *   - agent inlining: Codex has no markdown agent-spawn surface, so a skill
+ *     declaring `spawns_agent: true` + `agent_name: X` would, on Claude, spawn
+ *     the X agent (whose prompt lives in agents/X.md). On Codex that file is
+ *     never installed and the spawn directive is stripped by the whitelist —
+ *     leaving the skill referencing a non-existent agent. To keep Codex at
+ *     parity, the referenced agent's body is appended inline to the skill body
+ *     so the model has the full methodology even without a spawn primitive.
  */
 
 import { basename, dirname } from 'node:path'
@@ -36,16 +43,33 @@ const KEEP = ['name', 'description']
  * @param {import('../pipeline.mjs').TransformInput} input
  * @returns {import('../pipeline.mjs').TransformOutput[]}
  */
-export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+export function transform({
+	canonicalContent,
+	canonicalRelPath,
+	version,
+	fileType,
+	agentContentByName = {},
+}) {
 	const subbed = substituteVersion(canonicalContent, version)
 	const parsed = parseFrontmatter(subbed)
 	let payload
 	if (parsed.hasFrontmatter && parsed.fm) {
+		// Read the spawn directive BEFORE the whitelist strips it. On Codex
+		// there's no agent-spawn surface, so we inline the agent body instead.
+		const spawnsAgent = parsed.fm.spawns_agent === true
+		const agentName =
+			typeof parsed.fm.agent_name === 'string' && parsed.fm.agent_name.length > 0
+				? parsed.fm.agent_name
+				: null
 		// Whitelist filter: drop every frontmatter key NOT in KEEP.
 		for (const k of Object.keys(parsed.fm)) {
 			if (!KEEP.includes(k)) delete parsed.fm[k]
 		}
-		const wrappedBody = `<codex_agent_role>\n${parsed.body}\n</codex_agent_role>\n`
+		let body = parsed.body
+		if (spawnsAgent && agentName && agentContentByName[agentName]) {
+			body = `${body}\n\n${inlineAgentSection(agentName, agentContentByName[agentName], version)}`
+		}
+		const wrappedBody = `<codex_agent_role>\n${body}\n</codex_agent_role>\n`
 		payload = serializeFrontmatter({ ...parsed, body: wrappedBody })
 	} else {
 		payload = `<codex_agent_role>\n${subbed}\n</codex_agent_role>\n`
@@ -63,3 +87,28 @@ export function transform({ canonicalContent, canonicalRelPath, version, fileTyp
 	// another dead surface. Drop the agent branch entirely.
 	return []
 }
+
+/**
+ * Build the inlined-agent section appended to a Codex skill body. Strips the
+ * agent file's own frontmatter (Codex skills carry a single frontmatter block)
+ * and version-substitutes the body. The fenced header makes it unambiguous to
+ * the model that this is the methodology it should execute directly — there is
+ * no separate agent to spawn on Codex.
+ *
+ * @param {string} agentName
+ * @param {string} agentContent  raw canonical agent file (with frontmatter + {{APT_VERSION}})
+ * @param {string} version
+ * @returns {string}
+ */
+function inlineAgentSection(agentName, agentContent, version) {
+	const agentBody = parseFrontmatter(substituteVersion(agentContent, version)).body.trim()
+	return [
+		`## Inlined agent: ${agentName}`,
+		'',
+		`Codex has no separate agent-spawn surface. Where this skill says to spawn`,
+		`the \`${agentName}\` agent, execute the methodology below directly — you ARE`,
+		`that agent for this task.`,
+		'',
+		agentBody,
+	].join('\n')
+}

package/src/cli/install/version-header.mjs

@@ -99,7 +99,13 @@ export function inspectManifestFiles(manifest, installRoot, opts = {}) {
 			continue
 		}
 		const declared = parseVersionHeader(buf.toString('utf-8'))
-		if (declared === null && /\.(md|js|mjs|sh)$/.test(entry.path)) {
+		// `headerless` entries are files whose runtime transform legitimately
+		// strips the apt-skill-version header (e.g. Codex whitelists frontmatter
+		// to {name, description} and rejects unknown keys). For those, the
+		// installedHash check above is the sole drift signal — requiring a header
+		// would false-positive every install. The flag is recorded at install
+		// time by the pipeline from the post-transform content.
+		if (declared === null && !entry.headerless && /\.(md|js|mjs|sh)$/.test(entry.path)) {
 			stale.push({ path: entry.path, reason: 'missing_header' })
 			continue
 		}

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" }
 					}
 				},
 				{