@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,147 @@
+// Presentation route SWEEP — the runner that opens every manifest route in a real
+// browser and asserts the presentation floor, spine first. This is the evidence run 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.
+//
+// Implements the result shape in references/presentation-sweep.md. It stays separate
+// from the functional/journey suite and is not a CI gate.
+//
+// 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-sweep.test.mjs

@@ -0,0 +1,71 @@
+// Unit tests for the sweep's pure core (planning + summarize) — no browser.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { planRoutes, summarize } from './presentation-sweep.mjs'
+
+test('static routes plan to themselves; route-kind filter applies', () => {
+  const plan = planRoutes({ surfaces: [
+    { route: '/tasks', kind: 'route' },
+    { route: '/api/tasks/list', kind: 'api' }, // not a browser route → excluded
+    { route: '/dashboard', kind: 'route' },
+  ] })
+  assert.deepEqual(plan, [
+    { route: '/tasks', url: '/tasks' },
+    { route: '/dashboard', url: '/dashboard' },
+  ])
+})
+
+test('dynamic route with a resolver becomes a concrete url', () => {
+  const plan = planRoutes(
+    { routes: [{ route: '/tasks/[taskRunId]', kind: 'route' }] },
+    { paramResolver: (r) => (r.includes('taskRunId') ? '/tasks/tr_seeded_1' : null) },
+  )
+  assert.deepEqual(plan, [{ route: '/tasks/[taskRunId]', url: '/tasks/tr_seeded_1' }])
+})
+
+test('dynamic route with NO resolver answer is blocked, not skipped or passed', () => {
+  const plan = planRoutes({ routes: [{ route: '/tasks/[id]', kind: 'route' }] })
+  assert.equal(plan.length, 1)
+  assert.equal(plan[0].url, null)
+  assert.match(plan[0].blocked, /param resolver/)
+})
+
+test('ignore list drops routes', () => {
+  const plan = planRoutes(
+    { routes: [{ route: '/tasks', kind: 'route' }, { route: '/_debug/x', kind: 'route' }] },
+    { ignore: ['/_debug'] },
+  )
+  assert.deepEqual(plan.map((p) => p.route), ['/tasks'])
+})
+
+test('accepts a bare string manifest entry', () => {
+  const plan = planRoutes({ routes: ['/a', '/b'] })
+  assert.deepEqual(plan.map((p) => p.url), ['/a', '/b'])
+})
+
+test('summarize: a render-health fail flips the gate to non-ok', () => {
+  const s = summarize([
+    { route: '/dashboard', levels: [{ level: 'presentation:render-health', status: 'pass' }] },
+    { route: '/tasks', levels: [
+      { level: 'presentation:render-health', status: 'fail', evidence: "pageerror: reading 'id'" },
+      { level: 'presentation:spatial', status: 'blocked', evidence: 'not assessable' },
+    ] },
+  ])
+  assert.equal(s.ok, false)
+  assert.equal(s.failedCount, 2) // the fail + the blocked
+  assert.deepEqual(s.viewportFloor, [375, 1280])
+  const tasksHealth = s.results.find((r) => r.route === '/tasks' && r.level === 'presentation:render-health')
+  assert.equal(tasksHealth.status, 'fail')
+})
+
+test('summarize: all-pass is ok', () => {
+  const s = summarize([
+    { route: '/dashboard', levels: [
+      { level: 'presentation:render-health', status: 'pass' },
+      { level: 'presentation:spatial', status: 'pass' },
+    ] },
+  ])
+  assert.equal(s.ok, true)
+  assert.equal(s.failedCount, 0)
+})

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-temporal.test.mjs

@@ -0,0 +1,59 @@
+// Unit tests for the pure Temporal-stability cores (issue #199). Run: `node --test`.
+// The Playwright wrappers (assertNoFirstPartyShift / assertNoThirdPartyShift /
+// assertNoDynamicViewportShift) need a real browser and are exercised downstream.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { findLayoutShift, cumulativeShiftScore } from './presentation-temporal.mjs'
+
+const r = (left, top, right, bottom) => ({ rect: { left, top, right, bottom } })
+const at = (selector, left, top, right, bottom) => ({ selector, ...r(left, top, right, bottom) })
+
+// ---------- findLayoutShift ----------
+
+test('no shift when geometry is unchanged', () => {
+  const snap = [at('.header', 0, 0, 375, 60), at('.cta', 0, 100, 375, 140)]
+  assert.deepEqual(findLayoutShift(snap, snap), [])
+})
+
+test('flags an element pushed down by injected content', () => {
+  const before = [at('.cta', 0, 100, 375, 140)]
+  const after = [at('.cta', 0, 260, 375, 300)] // shoved down 160px (a banner injected above)
+  const shifted = findLayoutShift(before, after)
+  assert.equal(shifted.length, 1)
+  assert.equal(shifted[0].selector, '.cta')
+  assert.equal(shifted[0].dy, 160)
+})
+
+test('sub-tolerance movement is not a shift', () => {
+  const before = [at('.x', 0, 100, 375, 140)]
+  const after = [at('.x', 0, 101, 375, 141)] // 1px < default 2px tolerance
+  assert.deepEqual(findLayoutShift(before, after), [])
+})
+
+test('a newly-injected element is not itself counted as a shift', () => {
+  const before = [at('.cta', 0, 100, 375, 140)]
+  const after = [at('.cta', 0, 100, 375, 140), at('.banner', 0, 0, 375, 80)] // banner is new, cta did not move
+  assert.deepEqual(findLayoutShift(before, after), [])
+})
+
+test('an element that disappears is not a shift of a stable element', () => {
+  const before = [at('.spinner', 0, 0, 50, 50), at('.cta', 0, 100, 375, 140)]
+  const after = [at('.cta', 0, 100, 375, 140)] // spinner gone, cta stable
+  assert.deepEqual(findLayoutShift(before, after), [])
+})
+
+// ---------- cumulativeShiftScore ----------
+
+test('cumulativeShiftScore sums values without recent input', () => {
+  const entries = [
+    { value: 0.05, hadRecentInput: false },
+    { value: 0.10, hadRecentInput: false },
+    { value: 0.30, hadRecentInput: true }, // user-initiated — excluded
+  ]
+  assert.ok(Math.abs(cumulativeShiftScore(entries) - 0.15) < 1e-9)
+})
+
+test('cumulativeShiftScore is 0 for no entries', () => {
+  assert.equal(cumulativeShiftScore([]), 0)
+})

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

@@ -0,0 +1,82 @@
+// 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 and compare during the audit).
+//
+//   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 }
+
+const USAGE = 'usage: project-route-manifest.mjs --inventory <surface-inventory.json> [--overlay e2e/route-manifest.overlay.json] [--out e2e/route-manifest.json]'
+
+function main() {
+  const argv = process.argv.slice(2)
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); return }
+  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')
+
+  if (!fs.existsSync(inventoryPath)) {
+    console.error(`project-route-manifest: inventory not found: ${inventoryPath} — run your inventory adapter first\n${USAGE}`)
+    process.exit(1)
+  }
+  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/project-route-manifest.test.mjs

@@ -0,0 +1,76 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { projectManifest, staleOverlayEntries } from './project-route-manifest.mjs'
+
+const INVENTORY = {
+  surfaces: [
+    { id: '/tasks', kind: 'route', class: 'read', reachability: 'reachable' },
+    { id: '/tasks/[id]', kind: 'route', class: 'detail', reachability: 'reachable' },
+    { id: '/settings/models', kind: 'route', class: 'mutation', reachability: 'reachable' },
+    { id: '/legacy', kind: 'route', class: 'read', reachability: 'reachable' },
+    { id: '/api/tasks/list', kind: 'api', class: 'read' }, // not a browser route
+    { id: 'tasks_table', kind: 'table' },
+  ],
+}
+
+test('projects only browser routes, default tier from class, sorted', () => {
+  const m = projectManifest(INVENTORY)
+  assert.equal(m.generated, true)
+  assert.deepEqual(m.routes, [
+    { path: '/legacy', tier: 1 },
+    { path: '/settings/models', tier: 2 },
+    { path: '/tasks', tier: 1 },
+    { path: '/tasks/[id]', tier: 2 },
+  ])
+})
+
+test('overlay raises tier and drops ignored routes', () => {
+  const overlay = { routes: { '/tasks': { tier: 3 }, '/legacy': { ignore: true } }, spatialIgnore: ['.sticky-header'] }
+  const m = projectManifest(INVENTORY, overlay)
+  assert.equal(m.routes.find((r) => r.path === '/tasks').tier, 3)
+  assert.ok(!m.routes.some((r) => r.path === '/legacy'), 'ignored route dropped from sweep')
+  assert.deepEqual(m.spatialIgnore, ['.sticky-header'])
+})
+
+test('overlay specs are passed through but optional (informational only)', () => {
+  const m = projectManifest(INVENTORY, { routes: { '/tasks': { specs: ['render/tasks.spec.ts'] } } })
+  assert.deepEqual(m.routes.find((r) => r.path === '/tasks').specs, ['render/tasks.spec.ts'])
+  // a route with no overlay has no specs key
+  assert.equal('specs' in m.routes.find((r) => r.path === '/settings/models'), false)
+})
+
+test('same inventory + overlay → identical manifest (no drift, stable diff)', () => {
+  const a = projectManifest(INVENTORY, { routes: { '/tasks': { tier: 3 } } })
+  const b = projectManifest(INVENTORY, { routes: { '/tasks': { tier: 3 } } })
+  assert.deepEqual(a, b)
+})
+
+test('staleOverlayEntries flags curation for a route no longer in inventory', () => {
+  const stale = staleOverlayEntries(INVENTORY, { routes: { '/tasks': { tier: 3 }, '/removed': { ignore: true } } })
+  assert.deepEqual(stale, ['/removed'])
+})
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const CLI = fileURLToPath(new URL('./project-route-manifest.mjs', import.meta.url))
+
+test('CLI: --help prints usage; a missing inventory is a one-line error, not a stack trace', () => {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'prm-cli-'))
+  try {
+    const help = spawnSync('node', [CLI, '--help'], { cwd, encoding: 'utf8' })
+    assert.equal(help.status, 0)
+    assert.match(help.stdout, /usage: project-route-manifest\.mjs/)
+    const missing = spawnSync('node', [CLI, '--inventory', path.join(cwd, 'nope.json')], { cwd, encoding: 'utf8' })
+    assert.equal(missing.status, 1)
+    assert.match(missing.stderr, /inventory not found/)
+    assert.doesNotMatch(missing.stderr, /at Object\.|node:internal/, 'no stack trace')
+    assert.deepEqual(fs.readdirSync(cwd), [], 'nothing written')
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true })
+  }
+})

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);
+}