@aperant/framework 0.8.4 → 0.8.6

package/src/cli/verify-proof/runtime-detect.mjs

@@ -8,9 +8,17 @@
  *
  * Pattern: pure data in → pure data out. No filesystem walking, no exec.
  * Use loadRuntimeCapabilities(projectDir) for the cwd-rooted variant.
+ *
+ * v0.8.6 — `loadRuntimeCapabilities` now ALSO walks `apps/*` by default
+ * (configurable via the second arg `{monorepo_globs}`) and OR-merges
+ * each match's `package.json` capabilities with the root. The default
+ * `['apps/*']` matches the canonical Aperant monorepo layout; adopters
+ * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
+ * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
+ * walk entirely (root-only escape hatch).
  */
 
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 /**
@@ -103,20 +111,101 @@ export function detectFromPackageJson(packageJson) {
 
 /**
  * Load and detect capabilities from a project directory's package.json.
- * Returns empty capabilities if no package.json exists (malformed or
- * missing — both cases fall through to "nothing detected").
+ * v0.8.6 — also walks `monorepo_globs` (default `['apps/*']`) and
+ * OR-merges each match's capabilities with the root.
  *
  * @param {string} projectDir
+ * @param {{monorepo_globs?: string[]}} [opts]
  * @returns {RuntimeCapabilities}
  */
-export function loadRuntimeCapabilities(projectDir) {
-	const pkgPath = join(resolve(projectDir), 'package.json')
-	if (!existsSync(pkgPath)) return emptyCapabilities()
-	let parsed
+export function loadRuntimeCapabilities(projectDir, opts) {
+	const root = resolve(projectDir)
+	const rootPkgPath = join(root, 'package.json')
+	let rootCaps = emptyCapabilities()
+	if (existsSync(rootPkgPath)) {
+		try {
+			rootCaps = detectFromPackageJson(JSON.parse(readFileSync(rootPkgPath, 'utf-8')))
+		} catch {
+			/* fall through with empty caps */
+		}
+	}
+
+	// Default to the canonical Aperant monorepo layout. Passing `[]`
+	// disables the walk entirely (root-only escape hatch per spec ID-05).
+	const globs = opts && Array.isArray(opts.monorepo_globs) ? opts.monorepo_globs : ['apps/*']
+	if (globs.length === 0) return rootCaps
+
+	let merged = rootCaps
+	for (const glob of globs) {
+		const matches = expandSimpleGlob(root, glob)
+		for (const dir of matches) {
+			const childPkgPath = join(dir, 'package.json')
+			if (!existsSync(childPkgPath)) continue
+			try {
+				const childCaps = detectFromPackageJson(JSON.parse(readFileSync(childPkgPath, 'utf-8')))
+				merged = orMergeCapabilities(merged, childCaps)
+			} catch {
+				/* skip malformed package.json */
+			}
+		}
+	}
+	return merged
+}
+
+/**
+ * Expand a simple `prefix/*` glob against the root. Supports ONLY the
+ * `<dir>/*` shape (matches each direct subdirectory of `<dir>`). Other
+ * glob syntax is intentionally rejected — v1 keeps the dep surface
+ * small. Fails closed on malformed patterns (returns []).
+ *
+ * @param {string} root
+ * @param {string} glob
+ * @returns {string[]}
+ */
+function expandSimpleGlob(root, glob) {
+	if (typeof glob !== 'string' || !glob.endsWith('/*')) return []
+	const prefix = glob.slice(0, -2)
+	if (prefix.length === 0 || prefix.includes('*')) return []
+	const dir = join(root, prefix)
+	if (!existsSync(dir)) return []
+	let entries
 	try {
-		parsed = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		entries = readdirSync(dir)
 	} catch {
-		return emptyCapabilities()
+		return []
+	}
+	const matches = []
+	for (const name of entries) {
+		const sub = join(dir, name)
+		try {
+			if (statSync(sub).isDirectory()) matches.push(sub)
+		} catch {
+			/* skip unreadable entries */
+		}
+	}
+	return matches
+}
+
+/**
+ * Boolean OR-merge of two capability records. Any flag true in either
+ * input is true in the output. The "Electron wins over web" rule from
+ * `detectFromPackageJson` is preserved when this is called repeatedly —
+ * each child's flags are honest about that child's own shape, and the
+ * OR-merge just unions them.
+ *
+ * @param {RuntimeCapabilities} a
+ * @param {RuntimeCapabilities} b
+ * @returns {RuntimeCapabilities}
+ */
+function orMergeCapabilities(a, b) {
+	return {
+		is_electron: a.is_electron || b.is_electron,
+		is_tauri: a.is_tauri || b.is_tauri,
+		is_nextjs: a.is_nextjs || b.is_nextjs,
+		is_nuxt: a.is_nuxt || b.is_nuxt,
+		is_web_frontend: a.is_web_frontend || b.is_web_frontend,
+		is_expo: a.is_expo || b.is_expo,
+		is_react_native: a.is_react_native || b.is_react_native,
+		has_node: a.has_node || b.has_node,
 	}
-	return detectFromPackageJson(parsed)
 }

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

@@ -23,7 +23,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
 /**
- * @typedef {import('@aperant/driver-sdk').DriverManifest} DriverManifest
+ * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
  */
 
 const TOFU_PATH = '.aperant/driver-tofu.json'

package/templates/proof-verification.md

@@ -53,7 +53,13 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "tested_count": 0,
     "skipped_count": 0,
     "percent": 0,
-    "gate_result": "pass | warn | block"
+    "gate_result": "pass | warn | block",
+    "by_surface": {
+      "electron": { "tested": 0, "total": 0 },
+      "web": { "tested": 0, "total": 0 },
+      "cli": { "tested": 0, "total": 0 },
+      "api": { "tested": 0, "total": 0 }
+    }
   },
 
   "tests": [
@@ -61,14 +67,33 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
       "id": "TEST-01",
       "registry_id": "terminals-grid-auto-tile",
       "name": "Three Terminal Grid Auto-Tile",
+      "outcome_id": "O3",
+      "surface": "electron",
+      "transport": "mcp",
       "precondition": "2 terminals active",
       "action": "Press Cmd+T",
       "expected": "Grid reflows to 2+1 layout",
       "actual": "Grid correctly tiled to 2+1",
-      "evidence": "screenshots/03-grid.png",
+      "evidence": "electron/screenshots/03-grid.png",
       "analysis": "Screenshot shows three terminal panes. Top row has 2 equal-width panes, bottom row has 1 centered pane. Grid lines are clean, no overlap or gap artifacts. Each pane shows an active shell prompt with correct path.",
       "result": "pass | fail | blocked | skip",
       "severity": null
+    },
+    {
+      "id": "TEST-02",
+      "registry_id": "settings-theme-picker",
+      "name": "Theme picker — cross-surface",
+      "outcome_id": "O5",
+      "surface": "web",
+      "transport": "skill",
+      "precondition": "App loaded in web shell",
+      "action": "Click 'Dark mode' in the theme picker",
+      "expected": "Background flips to dark; persists across reload",
+      "actual": "Dark mode applied, persisted across reload",
+      "evidence": "web/screenshots/05-dark-mode.png",
+      "analysis": "Screenshot shows app body with #111 background, all text legible on dark surface. After reload, dark mode is still active — localStorage entry confirmed.",
+      "result": "pass",
+      "severity": null
     }
   ],
 
@@ -175,6 +200,7 @@ Each check has `status` (pass/fail) and `output` (captured terminal output). The
 | `skipped_count` | number | Number of entries in the skipped array |
 | `percent` | number | `tested_count / registered_count * 100` |
 | `gate_result` | string | `block` if < 50%, `warn` if < 80%, `pass` if >= 80% |
+| `by_surface` | object | v0.8.6 — per-surface rollup. Each surface key (`electron`, `web`, `cli`, `api`) maps to `{tested, total}` so reviewers can tell which surface fell short. |
 
 ### tests
 Each test entry tracks one sub-feature verification. Fields:
@@ -184,11 +210,14 @@ Each test entry tracks one sub-feature verification. Fields:
 | `id` | string | IMMUTABLE | Sequential ID: TEST-01, TEST-02, etc. |
 | `registry_id` | string | IMMUTABLE | Must match a sub-feature `id` from `.aperant/features/{area}.json` |
 | `name` | string | IMMUTABLE | Human-readable test name |
+| `outcome_id` | string | IMMUTABLE | v0.8.6 — positional ID from `## User Outcomes` (e.g. `O1`, `O2`). Synthesized by `parseUserOutcomes`; passed through verbatim by `resolveDriversForOutcomes`. Optional for legacy specs without `## User Outcomes`. |
+| `surface` | string | IMMUTABLE | v0.8.6 — one of `electron | web | cli | api`. Drives the per-surface screenshot path and the `coverage.by_surface` rollup. Cross-surface outcomes (`[electron+web]`) produce TWO test entries with the same `outcome_id` and different `surface` values. |
+| `transport` | string | OVERWRITE | v0.8.6 — `skill | mcp | binary | http`. Populated by the workflow runner from the dispatcher's directive (per Step 7a of `workflows/verify-proof.md`). For browser-driver web outcomes on Skill-capable hosts the value is `"skill"`; on legacy MCP hosts it falls back to `"mcp"`. |
 | `precondition` | string | IMMUTABLE | What must be true before testing |
 | `action` | string | IMMUTABLE | Specific action to perform |
 | `expected` | string | IMMUTABLE | Specific observable result expected |
 | `actual` | string | OVERWRITE | What actually happened (filled after testing) |
-| `evidence` | string | OVERWRITE | Screenshot filename or video timestamp |
+| `evidence` | string | OVERWRITE | Screenshot filename or video timestamp. v0.8.6 — paths are PER-SURFACE: `{surface}/screenshots/{outcome-id}.png`. |
 | `analysis` | string | OVERWRITE | Adversarial analysis of evidence — describe what you SEE, not what you expect |
 | `result` | string | OVERWRITE | `pass`, `fail`, `blocked`, or `skip` |
 | `severity` | string/null | OVERWRITE | `blocker`, `major`, `minor`, `cosmetic`, or `null` if pass |

package/workflows/verify-proof.md

@@ -43,13 +43,25 @@ cat implementation_plan.json 2>/dev/null
 cat testable_features.json 2>/dev/null
 ```
 
-Generate run ID and create proof directory:
+Generate run ID and create proof directory. v0.8.6 — when the spec
+carries `## User Outcomes` with cross-surface tags (e.g.
+`[electron+web]`), proof artifacts MUST land under PER-SURFACE
+subdirectories so reviewers can tell at a glance which surface failed.
+Set up the path template here:
+
 ```bash
 RUN_ID="$(date +%H%M%S)"
 APP_NAME=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).name)}catch{console.log('app')}" 2>/dev/null)
 PROOF_DIR=".aperant/proof/${APP_NAME}/$(date +%Y%m%d)/${RUN_ID}"
-mkdir -p "${PROOF_DIR}/screenshots"
+# Per-surface screenshot path template — Step 7c populates ${surface}
+# from the per-outcome resolver dispatch:
+#   ${PROOF_DIR}/${surface}/screenshots/${outcome-id}.png
+mkdir -p "${PROOF_DIR}"
 ```
+
+Sub-directories under `${PROOF_DIR}/${surface}/screenshots/` are
+created lazily in Step 7c when the workflow runner takes the first
+screenshot for that surface.
 </step>
 
 <step name="pre_check">
@@ -83,6 +95,18 @@ If no driver satisfies a REQUIRED capability, the resolver throws
 `unsatisfied_required_capability` — fail-closed, NOT a silent
 `blocked_by_platform` skip (per ID-02).
 
+**v0.8.6 — per-outcome dispatch.** When the spec carries
+`## User Outcomes`, the workflow runner picks a driver PER OUTCOME
+SURFACE via `resolveDriversForOutcomes()` instead of a single
+per-run driver pick. Each outcome's `[surface]` tag maps to the
+runtime-capability flag a driver must carry; `[electron+web]`
+outcomes dispatch to TWO drivers (one per surface) sharing the same
+`outcome_id`. The legacy `apt-tools detect-runtime .` call above
+still works for the per-run "what driver would be picked?" preview
+— it answers the OLD question. For the new per-outcome question,
+the workflow runner imports `resolveDriversForOutcomes` directly
+from the resolver module in Step 7c.
+
 ### 2b. Probe optional evidence-capture tools
 
 ```bash
@@ -142,6 +166,16 @@ If no feature registry exists:
 - Suggest: "No feature registry found. Consider running `/apt:scan {area}` first for exhaustive coverage."
 - Proceed with manual discovery below, but warn that coverage may be incomplete
 
+**v0.8.6 — read `## User Outcomes` from spec.md FIRST when present.**
+The PRD-shaped spec.md (STANDARD/DEEP tracks) ships a
+`## User Outcomes` section that is the verify-proof input contract:
+`**Epic:**` headline + N atomic outcomes tagged by `[surface]`. When
+present, each outcome maps 1:1 to a test entry — the workflow runner
+does NOT have to invent test units from the feature registry. Fall
+back to the feature-registry-based discovery below ONLY when the spec
+lacks `## User Outcomes` (the v0.8.x warn-not-block migration window
+per spec ID-06; the section becomes a hard block in v0.9.0).
+
 ### 4b. Read the source code
 
 You MUST read the actual source code for the features under test. Do not guess.
@@ -278,19 +312,49 @@ a local binary, or a built-in HTTP request). Workflow prose names ONLY
 IDL verbs per ID-01 — concrete tool names live in
 `packages/framework/drivers/<driver>/driver.mjs`.
 
+**v0.8.6 — transport dispatch directive (MUST honor).** When
+`driver.transport.skill_id` is set AND the host CLI exposes the
+Skill tool AND the outcome surface is `web`, the workflow runner
+MUST invoke `Skill({skill: driver.transport.skill_id, args: ...})`
+(passing the IDL verb args) and MUST record `transport: "skill"` on
+the resulting test entry in verification.json. When the host CLI
+does NOT expose the Skill tool, fall back to the MCP transport via
+the existing puppeteer MCP server and record `transport: "mcp"`.
+The driver's `chooseTransport({has_skill_tool})` helper computes
+the choice; the workflow runner is the site that knows
+`has_skill_tool`. This directive is LLM-honored (the v1 verify-proof
+runner is the host LLM following this workflow as prose); a
+text-level grep guard (TD-08) pins the `MUST` language so future
+edits cannot silently soften it to `SHOULD`.
+
 ### 7b. Wait for Result
 Wait for the action to complete. If it involves loading, wait for the load.
 Add a short delay (1-2 seconds) so the CDP capture also captures this state.
 
 ### 7c. Capture Evidence
-Take a screenshot AFTER the action completes:
+Take a screenshot AFTER the action completes. v0.8.6 — screenshots
+land under PER-SURFACE subdirectories, with the per-outcome driver
+returned by `resolveDriversForOutcomes()`:
+
 ```
-driver.screenshot({
-  target: { kind: "css", value: "body" },
-  output_path: "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png"
-})
+// Pick a driver per outcome surface (NOT per run). `entries[]` is
+// the resolver's per-(outcome, surface) dispatch — for an
+// [electron+web] outcome you get TWO entries sharing outcome_id
+// and you loop both, capturing one screenshot per surface.
+for (const entry of entries) {
+  await entry.driver.screenshot({
+    target: { kind: "css", value: "body" },
+    output_path: `${PROOF_DIR}/${entry.surface}/screenshots/${outcome.id}.png`
+  })
+}
 ```
 
+Single-surface outcomes (`[electron]`, `[web]`, `[cli]`, `[api]`)
+produce one screenshot under `${PROOF_DIR}/${surface}/screenshots/`;
+cross-surface (`[electron+web]`) produces two — one per surface tree
+— with both test entries in `verification.json:tests[]` carrying the
+same `id` but distinct `surface` and `evidence` fields.
+
 ### 7d. Analyze Evidence
 **MANDATORY and CRITICAL.** Every screenshot must be analyzed in detail.
 
@@ -313,18 +377,23 @@ apt-proof-video analyze "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png" \
 ```
 
 ### 7e. Record Result to verification.json
-After each test, update the test entry in verification.json `tests` array:
+After each test, update the test entry in verification.json `tests` array.
+v0.8.6 adds `surface` and `transport` fields per test entry — the workflow
+runner populates them from the per-outcome dispatch directive:
 
 ```json
 {
   "id": "TEST-01",
   "registry_id": "terminals-grid-auto-tile",
   "name": "Three Terminal Grid Auto-Tile",
+  "outcome_id": "O3",
+  "surface": "electron",
+  "transport": "mcp",
   "precondition": "2 terminals active",
   "action": "Press Cmd+T",
   "expected": "Grid reflows to 2+1 layout",
   "actual": "Grid correctly tiled",
-  "evidence": "screenshots/03-grid.png",
+  "evidence": "electron/screenshots/03-grid.png",
   "analysis": "Detailed adversarial analysis of what is actually visible in the screenshot...",
   "result": "pass",
   "severity": null