@1aboveio/skills 0.10.0

package/skills/engineering/e2e-test/scripts/presentation-sweep.mjs

@@ -0,0 +1,148 @@
+// Presentation route SWEEP — the runner that opens every manifest route in a real
+// browser and asserts the presentation floor, spine first. This is the gate that
+// catches a crashing route a green functional E2E suite sails past, because it
+// drives the REAL render path (no first-party interception) over the WHOLE manifest
+// instead of the handful of routes someone wrote a spec for.
+//
+// Satisfies ensure-coverage references/presentation/runner-contract.md and is the
+// "render sweep" gate (#3) of references/enforcement/ci-contract.md. It is a SEPARATE CI job
+// from the functional/journey suite.
+//
+// Usage (reference; adapt the fixtures to the repo):
+//   E2E_AUTH_BYPASS=1 node presentation-sweep.mjs \
+//     --manifest e2e/route-manifest.json --base-url http://127.0.0.1:3000 \
+//     --out docs/tests/_generated/presentation-results.json
+//
+// Fixtures the repo supplies (see the contract): auth bypass, seeded data, and a
+// param resolver for dynamic segments. Routes that cannot be rendered are reported
+// `blocked`, never silently skipped or passed.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure, unit-testable core (no browser) ----
+
+// Expand a manifest into the concrete routes to visit. Dynamic segments ([id], :id)
+// are resolved via `paramResolver(route) -> concreteUrl | null`. A dynamic route
+// with no resolver answer becomes a `blocked` plan entry (cannot render → not pass).
+export function planRoutes(manifest, { paramResolver = () => null, ignore = [] } = {}) {
+  const routes = (manifest?.routes || manifest?.surfaces || [])
+    .map((r) => (typeof r === 'string' ? { route: r } : r))
+    .filter((r) => r.route && (r.kind ? r.kind === 'route' : true))
+    .filter((r) => !ignore.some((ig) => r.route.includes(ig)))
+  const plan = []
+  for (const r of routes) {
+    const isDynamic = /[:\[]/.test(r.route)
+    if (!isDynamic) { plan.push({ route: r.route, url: r.route }); continue }
+    const concrete = paramResolver(r.route)
+    if (concrete) plan.push({ route: r.route, url: concrete })
+    else plan.push({ route: r.route, url: null, blocked: 'dynamic segment has no param resolver answer' })
+  }
+  return plan
+}
+
+// Reduce raw per-route outcomes into the contract's result rows + an exit verdict.
+// `fail` and `blocked` fail the gate (exit non-zero); `pass` does not.
+export function summarize(rawResults) {
+  const results = rawResults.flatMap((r) => r.levels.map((l) => ({
+    route: r.route, level: l.level, status: l.status, evidence: l.evidence || undefined,
+  })))
+  const failed = results.filter((r) => r.status === 'fail' || r.status === 'blocked')
+  return { viewportFloor: [375, 1280], results, ok: failed.length === 0, failedCount: failed.length }
+}
+
+function parseArgs(argv) {
+  const f = {}
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) f[a.slice(2)] = argv[i + 1]?.startsWith('--') || i + 1 >= argv.length ? true : argv[++i]
+  }
+  return f
+}
+
+// ---- browser orchestration (Playwright, lazy-imported) ----
+
+// Run the sweep. `fixtures` lets the repo inject auth + param resolution:
+//   { applyAuth: async (context) => {}, paramResolver: (route) => url|null,
+//     extraFatal: [], ignoreRoutes: [], spatialIgnore: [] }
+export async function runSweep({ manifestPath, baseURL, outPath, fixtures = {} }) {
+  const { chromium } = await import('@playwright/test')
+  const { watchRenderHealth, isFatalResponse } = await import('./presentation-render-health.mjs')
+  const { assertNoHorizontalOverflow } = await import('./presentation-checks.mjs')
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  const plan = planRoutes(manifest, { paramResolver: fixtures.paramResolver, ignore: fixtures.ignoreRoutes })
+
+  const browser = await chromium.launch()
+  const context = await browser.newContext()
+  if (fixtures.applyAuth) await fixtures.applyAuth(context)
+
+  const raw = []
+  for (const entry of plan) {
+    if (entry.blocked) {
+      raw.push({ route: entry.route, levels: [
+        { level: 'presentation:render-health', status: 'blocked', evidence: entry.blocked },
+        { level: 'presentation:spatial', status: 'blocked', evidence: entry.blocked },
+      ] })
+      continue
+    }
+    const page = await context.newPage()
+    const levels = []
+    const health = watchRenderHealth(page, { origin: baseURL, extraFatal: fixtures.extraFatal })
+    try {
+      const res = await page.goto(baseURL + entry.url, { waitUntil: 'domcontentloaded' })
+      await page.waitForLoadState('networkidle').catch(() => {})
+      // spine: render-health
+      const docFatal = res && isFatalResponse(res.status(), res.url(), { origin: baseURL })
+      const verdict = await health.evaluate()
+      if (docFatal || !verdict.healthy) {
+        const ev = docFatal ? `document ${res.status()}` : verdict.offenders.map((o) => `[${o.kind}] ${o.detail}`).join('; ')
+        levels.push({ level: 'presentation:render-health', status: 'fail', evidence: ev })
+        // layout is not assessable once the page failed to render
+        levels.push({ level: 'presentation:spatial', status: 'blocked', evidence: 'render-health failed; layout not assessable' })
+      } else {
+        levels.push({ level: 'presentation:render-health', status: 'pass' })
+        try {
+          await assertNoHorizontalOverflow(page, { ignore: fixtures.spatialIgnore || [] })
+          levels.push({ level: 'presentation:spatial', status: 'pass' })
+        } catch (e) {
+          levels.push({ level: 'presentation:spatial', status: 'fail', evidence: e.message })
+        }
+      }
+    } catch (e) {
+      levels.push({ level: 'presentation:render-health', status: 'fail', evidence: e.message })
+    } finally {
+      await page.close()
+    }
+    raw.push({ route: entry.route, levels })
+  }
+  await browser.close()
+
+  const summary = summarize(raw)
+  if (outPath) {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true })
+    fs.writeFileSync(outPath, JSON.stringify(summary, null, 2))
+  }
+  return summary
+}
+
+// CLI entry: load a repo-supplied fixtures module via --fixtures (optional).
+async function main() {
+  const f = parseArgs(process.argv)
+  const manifestPath = f.manifest || 'e2e/route-manifest.json'
+  const baseURL = (f['base-url'] || 'http://127.0.0.1:3000').replace(/\/$/, '')
+  const outPath = f.out || 'docs/tests/_generated/presentation-results.json'
+  let fixtures = {}
+  if (f.fixtures) fixtures = (await import(path.resolve(f.fixtures))).default || {}
+  const summary = await runSweep({ manifestPath, baseURL, outPath, fixtures })
+  const failed = summary.results.filter((r) => r.status === 'fail' || r.status === 'blocked')
+  for (const r of failed) console.error(`✖ ${r.route} ${r.level} — ${r.status}: ${r.evidence || ''}`)
+  console.log(`presentation sweep: ${summary.results.length} checks, ${summary.failedCount} failing across ${summary.results.length ? new Set(summary.results.map((r) => r.route)).size : 0} routes`)
+  process.exit(summary.ok ? 0 : 1)
+}
+
+// Run as CLI only when invoked directly (not when imported by tests).
+if (isMainModule(import.meta.url)) {
+  main().catch((e) => { console.error(e); process.exit(1) })
+}

package/skills/engineering/e2e-test/scripts/presentation-temporal.mjs

@@ -0,0 +1,127 @@
+// Presentation-axis Temporal-stability instrument for e2e-test (issue #199).
+//
+// "Does the layout hold still" — content must not jump as things inject. Tag specs
+// `@level presentation:temporal`. Drives a REAL browser; DOM-only is Over-mocked.
+//
+// Split by WHO renders the shift (the functional axis says "fake externals", but
+// faking the payment iframe makes the shift we want to catch disappear):
+//
+//   • FIRST-PARTY shift (lazy images, async data, our own dynamic fields) — a
+//     HERMETIC gate: real render, no network. Gate on a stable condition, not a
+//     fixed sleep.
+//   • THIRD-PARTY iframe shift (Stripe/Adyen/Braintree payfields) — the provider's
+//     official SANDBOX iframe in a SEPARATE NON-BLOCKING PR lane: a failure posts a
+//     visible annotation and the surface stays `Unverified` until a reviewer
+//     attests — never a silent advisory. (Faking the iframe defeats the check.)
+//
+// Why not top-page CLS: the Layout Instability API does NOT report shifts inside
+// cross-origin iframes (WICG spec excludes descendant browsing contexts). So a
+// top-page PerformanceObserver is blind to the payfields case — the deterministic
+// answer is a before/after getBoundingClientRect assertion gated on a provider-ready
+// signal. CLS IS fine for first-party shift.
+
+// ---------- pure cores (no browser) ----------
+
+// Compare two geometry snapshots and return elements that MOVED beyond tolerance.
+// `before`/`after` are arrays of { selector, rect:{left,top,right,bottom} }; matched
+// by selector. An element only present after (newly injected) is not itself a shift —
+// what matters is whether EXISTING elements moved because of the injection.
+export function findLayoutShift(before, after, { tolerancePx = 2 } = {}) {
+  const afterBySel = new Map(after.map((e) => [e.selector, e.rect]))
+  const shifted = []
+  for (const b of before) {
+    const a = afterBySel.get(b.selector)
+    if (!a) continue // element gone — not a shift of a stable element
+    const dx = Math.max(Math.abs(a.left - b.rect.left), Math.abs(a.right - b.rect.right))
+    const dy = Math.max(Math.abs(a.top - b.rect.top), Math.abs(a.bottom - b.rect.bottom))
+    if (dx > tolerancePx || dy > tolerancePx) {
+      shifted.push({ selector: b.selector, dx: Math.round(dx), dy: Math.round(dy) })
+    }
+  }
+  return shifted
+}
+
+// Cumulative Layout Shift from PerformanceObserver `layout-shift` entries: sum of
+// `value` for entries NOT following recent user input. Pure; feed it the raw entries
+// captured in-page. An OPTIONAL first-party alternative to the geometry diff — the
+// wrappers below use `findLayoutShift` (before/after geometry) as the default
+// mechanism because it pinpoints the offending element; CLS is offered for teams
+// that prefer the Web Vital. (First-party only — see header note on the iframe blind spot.)
+export function cumulativeShiftScore(entries = []) {
+  return entries
+    .filter((e) => !e.hadRecentInput)
+    .reduce((sum, e) => sum + (e.value || 0), 0)
+}
+
+// ---------- in-browser collectors ----------
+
+// NOTE: elements are keyed by a derived selector (`#id` else `tag.class…`). Two
+// id-less elements sharing tag+classes collide on the same key (last-wins), which
+// can mask or spoof a shift. Prefer stable ids / `data-testid` on elements whose
+// stability you assert; id'd elements are unaffected.
+function collectGeometryAll() {
+  const sel = (el) => {
+    if (el.id) return '#' + el.id
+    let s = el.tagName.toLowerCase()
+    if (typeof el.className === 'string' && el.className.trim()) s += '.' + el.className.trim().split(/\s+/).join('.')
+    return s
+  }
+  return [...document.querySelectorAll('body *')].map((el) => {
+    const r = el.getBoundingClientRect()
+    return { selector: sel(el), rect: { left: r.left, top: r.top, right: r.right, bottom: r.bottom } }
+  })
+}
+
+// ---------- Playwright wrappers (need a real browser) ----------
+
+// FIRST-PARTY hermetic gate. Snapshot geometry, run `trigger` (the action that
+// injects first-party content — load more, resolve async data), wait for a STABLE
+// condition (a settle locator becoming visible, else network-idle — never a fixed
+// sleep), snapshot again, and fail if existing elements moved beyond tolerance.
+export async function assertNoFirstPartyShift(page, { trigger, settle, tolerancePx = 2 } = {}) {
+  const before = await page.evaluate(collectGeometryAll)
+  if (trigger) await trigger()
+  if (settle) await settle.waitFor({ state: 'visible' })
+  else await page.waitForLoadState('networkidle').catch(() => {})
+  const after = await page.evaluate(collectGeometryAll)
+  const shifted = findLayoutShift(before, after, { tolerancePx })
+  if (shifted.length) {
+    const lines = shifted.map((s) => `  ${s.selector} moved Δx=${s.dx} Δy=${s.dy}px`)
+    throw new Error(`presentation:temporal (first-party) — layout shifted after injection:\n${lines.join('\n')}`)
+  }
+}
+
+// THIRD-PARTY (payfields) check. Runs against the provider's SANDBOX iframe. Wait on
+// a provider-ready signal (`ready`: a locator or async fn — NOT a sleep), then assert
+// the elements AROUND the payment container did not move. Intended for the separate
+// NON-BLOCKING lane; a failure here should be annotated and tracked as `Unverified`,
+// not block the PR (it touches an external sandbox).
+export async function assertNoThirdPartyShift(page, { container, ready, tolerancePx = 2 } = {}) {
+  const before = await page.evaluate(collectGeometryAll)
+  if (typeof ready === 'function') await ready()
+  else if (ready) await ready.waitFor({ state: 'visible' })
+  const after = await page.evaluate(collectGeometryAll)
+  const shifted = findLayoutShift(before, after, { tolerancePx })
+    .filter((s) => !container || !s.selector.includes(container)) // the iframe box itself may grow; we care about NEIGHBORS moving
+  if (shifted.length) {
+    const lines = shifted.map((s) => `  ${s.selector} moved Δx=${s.dx} Δy=${s.dy}px`)
+    throw new Error(`presentation:temporal (third-party payfields) — surrounding layout shifted when the provider iframe injected:\n${lines.join('\n')}`)
+  }
+}
+
+// Mobile dynamic-viewport (dvh) gate. Emulate a mobile viewport, then shrink the
+// height (the mobile address bar collapsing/expanding) and assert content does not
+// jump — catches `100vh`-behind-the-chrome bugs. Gated via emulation with a tuned
+// tolerance; fall back to staging if flake proves unmanageable (see design doc).
+export async function assertNoDynamicViewportShift(page, { width = 390, tall = 844, short = 740, tolerancePx = 2 } = {}) {
+  await page.setViewportSize({ width, height: tall })
+  await page.waitForLoadState('networkidle').catch(() => {})
+  const before = await page.evaluate(collectGeometryAll)
+  await page.setViewportSize({ width, height: short }) // address bar appears
+  const after = await page.evaluate(collectGeometryAll)
+  const shifted = findLayoutShift(before, after, { tolerancePx })
+  if (shifted.length) {
+    const lines = shifted.map((s) => `  ${s.selector} moved Δx=${s.dx} Δy=${s.dy}px`)
+    throw new Error(`presentation:temporal (dynamic viewport) — content jumped when the mobile viewport height changed (100vh/dvh):\n${lines.join('\n')}`)
+  }
+}

package/skills/engineering/e2e-test/scripts/presentation-visual.mjs

@@ -0,0 +1,84 @@
+// Presentation-axis instrument for e2e-test: visual regression (`presentation:visual`).
+//
+// The OPT-IN presentation level. The floor levels (render-health/spatial/
+// perceivability/reachability/temporal) are auto-applied and assert *structure*;
+// this level pins *appearance* against a committed pixel baseline and fails on
+// drift — catching the restyle / wrong-content / looks-broken-but-doesn't-throw
+// class the structural levels miss. A surface earns it only by declaring
+// `requiredLevels: [presentation:visual]` in its `*.coverage.yml` (raise-only).
+//
+// Wraps Playwright's built-in `toHaveScreenshot()` — we do NOT hand-roll a differ;
+// baselines, the 3-up diff on failure, masking, and `maxDiffPixelRatio` are native.
+//
+// NON-NEGOTIABLE (see ensure-coverage references/presentation/runner-contract.md
+// and references/enforcement/ci-contract.md):
+//   1. CI-only, in a pinned Playwright container (mcr.microsoft.com/playwright:vX.Y)
+//      for BOTH baseline generation and the gate. Never mint baselines on a dev host
+//      — host-OS anti-aliasing differs from Linux CI and reds every PR.
+//   2. Baselines are committed; only the on-demand `visual-baseline-regen` job
+//      (`--update-snapshots`) writes them. The blocking `visual-gate` job only reads.
+//
+// Tag the proving spec `@covers <route>` / `@level presentation:visual` so the
+// Coverage Ledger resolves it. Drives a REAL browser — a DOM/JSDOM snapshot cannot
+// see pixels and is graded `Over-mocked`.
+
+// ---- pure, unit-testable core (no browser) ----
+
+// The floor viewports visual is captured at — mirrors PRESENTATION_VIEWPORT_FLOOR
+// in ensure-coverage's coverage-ledger.mjs. Visual is captured per viewport.
+export const VISUAL_VIEWPORT_FLOOR = [375, 1280]
+
+// Deterministic baseline filename for a (route, viewport) cell. Stable + filesystem
+// safe so the committed PNG path never churns. Playwright appends its own
+// `-<project>-<platform>` suffix; we own the route+viewport stem.
+export function baselineName(route, viewport) {
+  const slug = route.replace(/^\//, '').replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '') || 'index'
+  return `${slug}-${viewport}.png`
+}
+
+// Normalize a coverage-file `visual.mask` list into the shape the spec consumes,
+// dropping entries with no `reason` (masking is a GATED concession — every masked
+// region must carry a reason, surfaced in the census). Returns { selectors, gaps }
+// where `gaps` names mask entries rejected for a missing reason (a finding).
+export function resolveMasks(visualConfig = {}) {
+  const raw = Array.isArray(visualConfig.mask) ? visualConfig.mask : []
+  const selectors = []
+  const gaps = []
+  for (const m of raw) {
+    if (typeof m === 'string') { gaps.push({ selector: m, why: 'mask entry has no reason' }); continue }
+    if (!m.reason || !String(m.reason).trim()) { gaps.push({ selector: m.selector, why: 'mask entry has no reason' }); continue }
+    selectors.push(m.selector)
+  }
+  return { selectors, gaps }
+}
+
+// Build the per-(route, viewport) result the ledger consumes (runner-contract.md
+// "Result shape"). `status` ∈ pass|fail|blocked. On fail, carry the committed
+// baseline path (durable evidence) and the diff artifact URL (ephemeral).
+export function visualResult({ route, viewport, status, evidence, baseline, diffArtifact }) {
+  const r = { route, level: 'presentation:visual', status, viewport }
+  if (evidence) r.evidence = evidence
+  if (baseline) r.baseline = baseline
+  if (diffArtifact) r.diffArtifact = diffArtifact
+  return r
+}
+
+// ---- browser wrapper (thin over Playwright's native assertion) ----
+
+// Assert a route matches its committed visual baseline at one viewport. Applies the
+// determinism prep the surface owes (animations off — the rest, clock-freeze/seed,
+// is the harness's job before calling this) and masks the gated dynamic regions.
+// `expect` and `page` are injected so this stays testable and Playwright-version
+// agnostic. Throws (Playwright's assertion) on drift; the sweep maps that to a
+// `fail` result via visualResult().
+export async function assertVisualBaseline(page, expect, route, viewport, opts = {}) {
+  const { maskSelectors = [], maxDiffPixelRatio = 0.001, settle } = opts
+  await page.setViewportSize({ width: viewport, height: 900 })
+  await page.goto(route)
+  if (settle) await settle(page) // gate on a stable condition, NEVER a fixed sleep
+  await expect(page).toHaveScreenshot(baselineName(route, viewport), {
+    mask: maskSelectors.map((s) => page.locator(s)),
+    maxDiffPixelRatio,
+    animations: 'disabled',
+  })
+}

package/skills/engineering/e2e-test/scripts/project-route-manifest.mjs

@@ -0,0 +1,75 @@
+// Project the E2E route-manifest FROM the canonical surface inventory + a curated
+// overlay. The manifest is GENERATED, never hand-enumerated — so its route set
+// cannot drift from the inventory (regenerate + `git diff --exit-code` is CI gate 1).
+//
+//   node project-route-manifest.mjs \
+//     --inventory docs/tests/_generated/surface-inventory.json \
+//     --overlay e2e/route-manifest.overlay.json \
+//     --out e2e/route-manifest.json
+//
+// What lives where:
+//   - inventory  (ensure-coverage, generated)  = the route SET + (kind, class).
+//   - overlay    (curated, small)              = E2E-only deviations: tier, ignore
+//                                                (don't sweep), spatial allowlist.
+//   - manifest   (generated here)              = inventory(routes) ⨝ overlay.
+// Coverage is NOT tracked here — the ledger computes it from `@covers` annotations.
+// `specs` is optional/informational only; it is not a coverage signal.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// Default E2E tier from the inventory's mechanical class. Overlay can raise it
+// (e.g. a route on a core journey → tier 3); it cannot be derived from a single
+// route because "journey" is a cross-page property.
+const DEFAULT_TIER = { read: 1, detail: 2, mutation: 2 }
+
+// Pure: inventory + overlay -> manifest object. Deterministic + sorted so the diff
+// is stable.
+export function projectManifest(inventory, overlay = {}) {
+  const ov = overlay.routes || {}
+  const routes = (inventory?.surfaces || [])
+    .filter((s) => s.kind === 'route')
+    .filter((s) => !ov[s.id]?.ignore) // curated: explicitly not swept (still owes its ledger floor)
+    .map((s) => {
+      const o = ov[s.id] || {}
+      const entry = { path: s.id, tier: o.tier ?? DEFAULT_TIER[s.class] ?? 1 }
+      if (o.specs) entry.specs = o.specs // informational only
+      return entry
+    })
+    .sort((a, b) => a.path.localeCompare(b.path))
+  const manifest = { version: 1, generated: true, routes }
+  if (overlay.spatialIgnore) manifest.spatialIgnore = overlay.spatialIgnore
+  return manifest
+}
+
+// Report overlay entries that reference a route no longer in the inventory — curated
+// rot the diff alone won't explain. Returned so the CLI can warn (not throw).
+export function staleOverlayEntries(inventory, overlay = {}) {
+  const ids = new Set((inventory?.surfaces || []).filter((s) => s.kind === 'route').map((s) => s.id))
+  return Object.keys(overlay.routes || {}).filter((id) => !ids.has(id))
+}
+
+function arg(flags, name, def) { return flags[name] ?? def }
+
+function main() {
+  const argv = process.argv.slice(2)
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) if (argv[i].startsWith('--')) flags[argv[i].slice(2)] = argv[++i]
+  const inventoryPath = arg(flags, 'inventory', 'docs/tests/_generated/surface-inventory.json')
+  const overlayPath = arg(flags, 'overlay', 'e2e/route-manifest.overlay.json')
+  const outPath = arg(flags, 'out', 'e2e/route-manifest.json')
+
+  const inventory = JSON.parse(fs.readFileSync(inventoryPath, 'utf8'))
+  const overlay = fs.existsSync(overlayPath) ? JSON.parse(fs.readFileSync(overlayPath, 'utf8')) : {}
+
+  const stale = staleOverlayEntries(inventory, overlay)
+  if (stale.length) console.error(`⚠ overlay references routes not in inventory (stale curation): ${stale.join(', ')}`)
+
+  const manifest = projectManifest(inventory, overlay)
+  fs.mkdirSync(path.dirname(outPath), { recursive: true })
+  fs.writeFileSync(outPath, JSON.stringify(manifest, null, 2) + '\n')
+  console.log(`wrote ${outPath} — ${manifest.routes.length} routes (generated from ${inventoryPath})`)
+}
+
+if (isMainModule(import.meta.url)) main()

package/skills/engineering/e2e-test/scripts/validate-manifest.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * Validate route manifest against actual spec files.
+ *
+ * Usage:
+ *   node scripts/validate-manifest.mjs [--manifest e2e/route-manifest.json] [--e2e-dir e2e]
+ *
+ * Checks:
+ * 1. Manifest is valid JSON with required fields
+ * 2. All referenced spec files exist
+ * 3. Reports uncovered routes (specs: [])
+ * 4. Reports coverage percentage
+ *
+ * Exit codes:
+ *   0 = valid (may have warnings)
+ *   1 = errors found (missing files, invalid format)
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+
+const args = process.argv.slice(2);
+function getArg(name, defaultVal) {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : defaultVal;
+}
+
+const manifestPath = resolve(getArg('manifest', 'e2e/route-manifest.json'));
+const e2eDir = resolve(getArg('e2e-dir', 'e2e'));
+
+let errors = 0;
+let warnings = 0;
+
+// Check manifest exists
+if (!existsSync(manifestPath)) {
+  console.error(`❌ Manifest not found: ${manifestPath}`);
+  process.exit(1);
+}
+
+// Parse manifest
+let manifest;
+try {
+  manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+} catch (e) {
+  console.error(`❌ Invalid JSON in manifest: ${e.message}`);
+  process.exit(1);
+}
+
+const routes = manifest.routes || manifest.endpoints || [];
+
+if (routes.length === 0) {
+  console.error('❌ Manifest has no routes/endpoints');
+  process.exit(1);
+}
+
+console.log(`📋 Validating ${routes.length} routes from ${manifestPath}\n`);
+
+// Validate each route
+let covered = 0;
+for (const route of routes) {
+  const label = route.method ? `${route.method} ${route.path}` : route.path;
+
+  // Check required fields
+  if (!route.path) {
+    console.error(`❌ Route missing "path" field`);
+    errors++;
+    continue;
+  }
+  if (typeof route.tier !== 'number' || route.tier < 1 || route.tier > 3) {
+    console.error(`❌ ${label}: invalid tier (must be 1-3, got ${route.tier})`);
+    errors++;
+  }
+
+  // Check specs
+  const specs = route.specs || [];
+  if (specs.length === 0) {
+    console.warn(`⚠️  ${label}: uncovered (no specs)`);
+    warnings++;
+    continue;
+  }
+
+  covered++;
+  for (const spec of specs) {
+    const specPath = join(e2eDir, spec);
+    if (!existsSync(specPath)) {
+      console.error(`❌ ${label}: spec file not found: ${specPath}`);
+      errors++;
+    }
+  }
+}
+
+// Summary
+const coverage = Math.round((covered / routes.length) * 100);
+console.log(`\n${'─'.repeat(50)}`);
+console.log(`📊 Coverage: ${coverage}% (${covered}/${routes.length} routes covered)`);
+console.log(`❌ Errors: ${errors}`);
+console.log(`⚠️  Warnings: ${warnings}`);
+
+if (errors > 0) {
+  console.log('\n🚫 Validation failed');
+  process.exit(1);
+} else {
+  console.log('\n✅ Validation passed');
+  process.exit(0);
+}

package/skills/engineering/engineering-runtime/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/engineering/engineering-runtime/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: engineering-runtime
+description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
+disable-model-invocation: true
+user-invocable: false
+---
+
+# Engineering Runtime
+
+This is a support-only runtime package for Engineering Workflow consumers. It exposes no user workflow.

package/skills/engineering/engineering-runtime/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Engineering Runtime"
+  short_description: "Internal Engineering Workflow support package"
+
+policy:
+  allow_implicit_invocation: false