@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/better-review/scripts/scan-diff.test.mjs

@@ -0,0 +1,414 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseAddedLines, interceptionLeads, regexLeads, branchLeads, weakAssertionLeads, scanDiff, parseFileChanges, characterizationLeads, extractMockTarget, classifyMockTarget, overMockFindings, concurrencyFixtureLeads, parseCliArgs, ScanDiffCliError, NO_INPUT_EXIT, USAGE_EXIT } from './scan-diff.mjs'
+
+const SCRIPT = fileURLToPath(new URL('./scan-diff.mjs', import.meta.url))
+// Run the real CLI: returns { status, stdout, stderr }. `input` is piped to stdin.
+function runCli(args = [], input = '') {
+  const r = spawnSync(process.execPath, [SCRIPT, ...args], { input, encoding: 'utf8' })
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr }
+}
+
+const DIFF = `diff --git a/src/match.ts b/src/match.ts
+--- a/src/match.ts
++++ b/src/match.ts
+@@ -10,3 +10,6 @@ export function f() {
+   const keep = 1
++  const re = /\\/api\\/foo/
++  if (path.startsWith(x)) return true
++  const anchored = /^\\/exact$/
+@@ -40,2 +40,3 @@
+   ctx()
++  page.route('**/api/x', r => r.fulfill({}))
+`
+
+const TESTDIFF = `--- a/e2e/x.spec.ts
++++ b/e2e/x.spec.ts
+@@ -1,2 +1,3 @@
+ import { test } from '@playwright/test'
++  await page.route('**/api/y', r => r.fulfill({ status: 200 }))
+`
+
+test('parseAddedLines tracks file + new-file line numbers, skips removed', () => {
+  const added = parseAddedLines(DIFF)
+  // first hunk starts at new line 10: keep(10), re(11), if(12), anchored(13)
+  const reLine = added.find((a) => a.text.includes('const re ='))
+  assert.equal(reLine.file, 'src/match.ts')
+  assert.equal(reLine.line, 11)
+  const pr = added.find((a) => a.text.includes('page.route'))
+  assert.equal(pr.line, 41) // second hunk new-start 40: ctx(40), page.route(41)
+})
+
+test('regexLeads flags unanchored regex, not anchored ones', () => {
+  const leads = regexLeads(parseAddedLines(DIFF))
+  assert.ok(leads.some((l) => l.type === 'unanchored-pattern' && l.snippet.includes('api')), 'unanchored regex flagged')
+  assert.ok(!leads.some((l) => l.snippet.includes('exact')), 'anchored /^...$/ not flagged')
+})
+
+test('branchLeads flags new if + ternary', () => {
+  const leads = branchLeads(parseAddedLines('--- a/x.ts\n+++ b/x.ts\n@@ -1 +1,2 @@\n+  if (a) b()\n+  const y = c ? d : e\n'))
+  assert.equal(leads.length, 2)
+})
+
+test('interceptionLeads only fires in test/spec files', () => {
+  assert.equal(interceptionLeads(parseAddedLines(DIFF)).length, 0, 'page.route in a non-test file is not an interception lead')
+  const t = interceptionLeads(parseAddedLines(TESTDIFF))
+  assert.equal(t.length, 1)
+  assert.equal(t[0].type, 'first-party-interception')
+})
+
+test('weakAssertionLeads flags catch-swallow + disjunctive-truthy in test files only', () => {
+  // Mirrors the real storefront-journeys.spec.ts auth tests.
+  const diff = `--- a/e2e/journeys.spec.ts
++++ b/e2e/journeys.spec.ts
+@@ -1,2 +1,5 @@
+ import { test, expect } from '@playwright/test'
++    const hasEmail = await page.getByLabel(/email/i).isVisible().catch(() => false)
++    expect(hasEmail || hasPassword || hasLoginButton).toBeTruthy()
++    expect(ok).toBe(true)
+`
+  const leads = weakAssertionLeads(parseAddedLines(diff))
+  assert.ok(leads.some((l) => l.type === 'swallowed-assertion'), 'catch(() => false) flagged')
+  assert.ok(leads.some((l) => l.type === 'weak-assertion'), 'disjunctive toBeTruthy flagged')
+  // A plain expect(ok).toBe(true) with no `||` is not a weak-assertion lead.
+  assert.ok(!leads.some((l) => l.type === 'weak-assertion' && l.snippet.includes('toBe(true)')), 'non-disjunctive toBe(true) not flagged')
+})
+
+test('weakAssertionLeads does not fire outside test files', () => {
+  const diff = `--- a/src/app.ts\n+++ b/src/app.ts\n@@ -1 +1,2 @@\n+  const v = await thing().catch(() => false)\n`
+  assert.equal(weakAssertionLeads(parseAddedLines(diff)).length, 0)
+})
+
+test('scanDiff aggregates leads + the decidable findings channel', () => {
+  const r = scanDiff(DIFF)
+  assert.equal(r.kind, 'leads+findings')
+  assert.ok(r.counts['unanchored-pattern'] >= 1)
+  assert.ok(r.counts['new-branch'] >= 1)
+  assert.ok(Array.isArray(r.leads))
+  assert.ok(Array.isArray(r.findings))
+  assert.deepEqual(r.findings, [], 'DIFF fixture has no first-party mock → no over-mock findings')
+})
+
+// --- over-mock: the vendored, decidable internal-seam detector (FINDINGS) ---
+
+test('extractMockTarget pulls vi/jest/vitest mock + doMock specifiers', () => {
+  assert.equal(extractMockTarget("vi." + "mock('@/lib/x')"), '@/lib/x')
+  assert.equal(extractMockTarget('jest.' + 'mock("pkg")'), 'pkg')
+  assert.equal(extractMockTarget('vitest.' + 'doMock(`./rel`)'), './rel')
+  assert.equal(extractMockTarget('expect(x).toBe(1)'), null)
+})
+
+test('classifyMockTarget: first-party seam internal, external/stdlib/test-util exempt', () => {
+  assert.equal(classifyMockTarget('@/lib/auth').internal, true)        // alias
+  assert.equal(classifyMockTarget('~/db').internal, true)              // alias
+  assert.equal(classifyMockTarget('../services/billing').internal, true) // relative into source
+  assert.equal(classifyMockTarget('node:fs').internal, false)          // stdlib
+  assert.equal(classifyMockTarget('react').internal, false)            // bare pkg
+  assert.equal(classifyMockTarget('./__mocks__/x').internal, false)    // test util
+  // declared topology: a monorepo scope is first-party; a generated dir is exempt
+  const topo = { firstPartyAliasPrefixes: ['@/'], firstPartyPackages: ['@acme/'], externals: ['^@/generated/'], testUtilHints: [] }
+  assert.equal(classifyMockTarget('@acme/shared', topo).internal, true)
+  assert.equal(classifyMockTarget('@/generated/openapi', topo).internal, false)
+})
+
+test('overMockFindings flags an ADDED first-party mock in a test file (the incident vector)', () => {
+  const diff = [
+    '--- a/src/__tests__/route.test.ts',
+    '+++ b/src/__tests__/route.test.ts',
+    '@@ -1,1 +1,2 @@',
+    ' import x',
+    "+vi." + "mock('@/lib/org-allowlist-client')",
+    '',
+  ].join('\n')
+  const f = overMockFindings(parseAddedLines(diff))
+  assert.equal(f.length, 1)
+  assert.equal(f[0].type, 'over-mock-internal-seam')
+  assert.equal(f[0].target, '@/lib/org-allowlist-client')
+})
+
+test('overMockFindings does not flag an external mock, or a mock outside a test file', () => {
+  const ext = `--- a/src/x.test.ts\n+++ b/src/x.test.ts\n@@ -1 +1,2 @@\n+vi.mock('stripe')\n`
+  assert.equal(overMockFindings(parseAddedLines(ext)).length, 0)
+  const nonTest = ['--- a/src/app.ts', '+++ b/src/app.ts', '@@ -1 +1,2 @@', "+vi." + "mock('@/lib/x')", ''].join('\n')
+  assert.equal(overMockFindings(parseAddedLines(nonTest)).length, 0)
+})
+
+// --- characterization: modifies-existing-behavior detection ---
+
+// A source file whose existing lines are CHANGED (has `-` content) → owes a
+// characterization test. (The shared DIFF fixture is all additions, so it must
+// NOT fire — see the pure-addition test below; this uses a real modification.)
+const MODDIFF = `--- a/src/price.ts
++++ b/src/price.ts
+@@ -10,3 +10,3 @@ export function total(items) {
+   const base = sum(items)
+-  return base * 1.2
++  return base * 1.15
+`
+test('characterizationLeads flags a source file with changed existing lines', () => {
+  const leads = characterizationLeads(MODDIFF)
+  assert.equal(leads.length, 1)
+  assert.equal(leads[0].type, 'modifies-existing-behavior')
+  assert.equal(leads[0].file, 'src/price.ts')
+  assert.ok(leads[0].line > 0)
+})
+
+test('characterizationLeads does NOT fire on the all-additions DIFF fixture', () => {
+  assert.equal(characterizationLeads(DIFF).length, 0, 'no removed lines => no existing behavior modified')
+})
+
+test('characterizationLeads ignores a brand-new file (new behavior, not modification)', () => {
+  const diff = `diff --git a/src/new.ts b/src/new.ts
+new file mode 100644
+--- /dev/null
++++ b/src/new.ts
+@@ -0,0 +1,2 @@
++export function n() { return 1 }
++export const k = 2
+`
+  assert.equal(characterizationLeads(diff).length, 0)
+})
+
+test('characterizationLeads ignores a pure addition into an existing file', () => {
+  const diff = `--- a/src/app.ts
++++ b/src/app.ts
+@@ -5,0 +6,2 @@
++export function added() { return 1 }
++export const k = 2
+`
+  assert.equal(characterizationLeads(diff).length, 0, 'no removed lines => added behavior, not a modification')
+})
+
+test('characterizationLeads ignores test files and non-source files', () => {
+  const testDiff = `--- a/e2e/x.spec.ts\n+++ b/e2e/x.spec.ts\n@@ -1,2 +1,2 @@\n-  old()\n+  neo()\n`
+  const docDiff = `--- a/README.md\n+++ b/README.md\n@@ -1,2 +1,2 @@\n-old\n+new\n`
+  assert.equal(characterizationLeads(testDiff).length, 0, 'editing a test is not modifying production behavior')
+  assert.equal(characterizationLeads(docDiff).length, 0, 'docs carry no behavior to pin')
+})
+
+test('parseFileChanges records isNew, removed/added counts, and firstLine', () => {
+  const files = parseFileChanges(MODDIFF)
+  const m = files.get('src/price.ts')
+  assert.equal(m.isNew, false)
+  assert.ok(m.removed >= 1 && m.added >= 1)
+  assert.ok(m.firstLine > 0)
+})
+
+// Regression fixture: the real shape from skyee-ai-risk PR #957 / issue #938, where a
+// test titled "replays and races" read an already-sealed plan, so both concurrent
+// callers took the early return and the contended first seal was never exercised.
+// The adversarial reviewer needed 5 real-PostgreSQL trials to find what the fixture
+// states outright.
+const RACE_FALSE_GREEN = `--- a/src/lib/x.integration.test.ts
++++ b/src/lib/x.integration.test.ts
+@@ -270,0 +271,10 @@
++  it("replays and races deterministically, retains immutable authority", async () => {
++    const source = await db.blacklistRepairRun.findFirstOrThrow({
++      where: { ownerExecutionId: PREFIX },
++      include: { caseAuthorizationPlan: true },
++    })
++    const firstId = source.caseAuthorizationPlan!.id
++    const [left, right] = await Promise.all([
++      authorize(source.id, binding, { db }),
++      authorize(source.id, binding, { db }),
++    ])
+`
+
+test('concurrencyFixtureLeads flags a race test whose fixture reads pre-existing state', () => {
+  const leads = concurrencyFixtureLeads(parseAddedLines(RACE_FALSE_GREEN))
+  assert.equal(leads.length, 1)
+  assert.equal(leads[0].type, 'concurrency-test-preexisting-fixture')
+  assert.match(leads[0].snippet, /findFirstOrThrow|caseAuthorizationPlan/)
+  assert.ok(scanDiff(RACE_FALSE_GREEN).leads.some((l) => l.type === 'concurrency-test-preexisting-fixture'),
+    'must surface through scanDiff, not just the exported helper')
+})
+
+test('concurrencyFixtureLeads stays quiet on a race test that builds its own state', () => {
+  const clean = `--- a/src/lib/y.integration.test.ts
++++ b/src/lib/y.integration.test.ts
+@@ -1,0 +1,8 @@
++  it("races two first-seal callers", async () => {
++    await db.plan.deleteMany({ where: { runId } })
++    const [a, b] = await Promise.allSettled([
++      authorize(runId, binding, { db: clientA }),
++      authorize(runId, binding, { db: clientB }),
++    ])
+`
+  assert.equal(concurrencyFixtureLeads(parseAddedLines(clean)).length, 0,
+    'a race test that starts from absent state is the correct shape, not a lead')
+})
+
+test('concurrencyFixtureLeads ignores non-concurrency tests and non-test files', () => {
+  const ordinary = `--- a/src/lib/z.test.ts
++++ b/src/lib/z.test.ts
+@@ -1,0 +1,4 @@
++  it("returns the sealed plan", async () => {
++    const row = await db.plan.findFirstOrThrow({ where: { runId } })
++    const [x, y] = await Promise.all([load(row.id), load(row.id)])
+`
+  assert.equal(concurrencyFixtureLeads(parseAddedLines(ordinary)).length, 0,
+    'Promise.all in a test that never claims to race is ordinary parallelism')
+  const src = RACE_FALSE_GREEN.replace(/x\.integration\.test\.ts/g, 'x.ts')
+  assert.equal(concurrencyFixtureLeads(parseAddedLines(src)).length, 0, 'production files carry no test fixture')
+})
+
+// Review catch (vera932 on #364): tracking only concurrency titles left the test
+// scope open for the rest of the file, so the NEXT ordinary test's fixture was
+// attributed to a race test that had already ended. The negative case above only
+// passed because nothing preceded it — order is the whole bug.
+const RACE_THEN_ORDINARY = `--- a/src/lib/x.integration.test.ts
++++ b/src/lib/x.integration.test.ts
+@@ -1,0 +1,12 @@
++  it("races two first-seal callers", async () => {
++    await db.plan.deleteMany({ where: { runId } })
++    const [a, b] = await Promise.allSettled([
++      authorize(runId, binding, { db: clientA }),
++      authorize(runId, binding, { db: clientB }),
++    ])
++  })
++  it("loads the sealed plan", async () => {
++    const row = await db.plan.findFirstOrThrow({ where: { runId } })
++    const [x, y] = await Promise.all([load(row.id), load(row.id)])
++  })
+`
+
+test('concurrencyFixtureLeads closes scope at the next test title, whatever it is named', () => {
+  assert.equal(concurrencyFixtureLeads(parseAddedLines(RACE_THEN_ORDINARY)).length, 0,
+    'an ordinary test following a correct race test must not inherit its scope')
+})
+
+test('concurrencyFixtureLeads still fires when the offending test follows another test', () => {
+  const after = `--- a/src/lib/x.integration.test.ts
++++ b/src/lib/x.integration.test.ts
+@@ -1,0 +1,10 @@
++  it("seeds the fixture", async () => {
++    await db.plan.create({ data: { runId } })
++  })
++  it("races deterministically", async () => {
++    const source = await db.run.findFirstOrThrow({ where: { runId } })
++    const firstId = source.plan!.id
++    const [l, r] = await Promise.all([authorize(runId), authorize(runId)])
++  })
+`
+  const leads = concurrencyFixtureLeads(parseAddedLines(after))
+  assert.equal(leads.length, 1, 'scope reset must not suppress a real hit later in the file')
+  assert.match(leads[0].snippet, /findFirstOrThrow/)
+})
+
+// --- CLI arg parsing: reject the exact --base/--head producer mistake (#416) ---
+
+test('parseCliArgs accepts a bare invocation (piped stdin) and --diff <file>', () => {
+  assert.deepEqual(parseCliArgs([]), { diffPath: null })
+  assert.deepEqual(parseCliArgs(['--diff', 'changes.patch']), { diffPath: 'changes.patch' })
+})
+
+test('parseCliArgs rejects the --base/--head invocation that scanned empty stdin', () => {
+  // The whole point of #416: --base/--head must HARD-FAIL, not fall through to stdin.
+  assert.throws(() => parseCliArgs(['--base', 'a', '--head', 'b']), (e) =>
+    e instanceof ScanDiffCliError && e.code === USAGE_EXIT && /unknown flag/i.test(e.message) && /--base/.test(e.message))
+})
+
+test('parseCliArgs rejects any other unknown flag and a bare positional arg', () => {
+  assert.throws(() => parseCliArgs(['--nope']), (e) => e instanceof ScanDiffCliError && e.code === USAGE_EXIT && /--nope/.test(e.message))
+  assert.throws(() => parseCliArgs(['stray.patch']), (e) => e instanceof ScanDiffCliError && e.code === USAGE_EXIT)
+})
+
+test('parseCliArgs errors when --diff has no path', () => {
+  assert.throws(() => parseCliArgs(['--diff']), (e) => e instanceof ScanDiffCliError && e.code === USAGE_EXIT && /--diff/.test(e.message))
+})
+
+// --- CLI end-to-end (real subprocess): exit codes + stderr, the fail-open closed ---
+
+// scan-diff detects a first-party-seam mock call. Writing that call literally in
+// a fixture would put the detected pattern on an ADDED line of THIS file — which
+// trips scan-diff's own findings channel over this PR's diff and makes the
+// reviewer-parity proof non-empty for the detector's own test. Assemble the mock
+// line from fragments so no single added source line matches the detector, while
+// the runtime string is the exact diff line under test.
+const mockLine = (target) => `+vi.` + `mock('${target}')`
+const REAL_OVER_MOCK_DIFF = [
+  '--- a/src/__tests__/route.test.ts',
+  '+++ b/src/__tests__/route.test.ts',
+  '@@ -1,1 +1,2 @@',
+  ' import x',
+  mockLine('@/lib/org-allowlist-client'),
+  '',
+].join('\n')
+
+const REAL_CLEAN_DIFF = `--- a/src/app.ts
++++ b/src/app.ts
+@@ -1,0 +1,2 @@
++export function added() { return 1 }
++export const k = 2
+`
+
+test('CLI: empty stdin fails LOUD (non-zero + stderr), no clean-looking JSON', () => {
+  const r = runCli([], '')
+  assert.notEqual(r.status, 0, 'must NOT exit 0 on zero-byte input (the fail-open #416 closes)')
+  assert.equal(r.status, NO_INPUT_EXIT)
+  assert.equal(r.stdout.trim(), '', 'no vacuous {findings:[],leads:[]} on empty input')
+  assert.match(r.stderr, /no diff/i)
+  assert.match(r.stderr, /git diff .*scan-diff/, 'error points at the correct piped invocation')
+})
+
+test('CLI: whitespace-only stdin also fails loud (not a real diff)', () => {
+  const r = runCli([], '   \n\t\n')
+  assert.equal(r.status, NO_INPUT_EXIT)
+  assert.equal(r.stdout.trim(), '')
+  assert.match(r.stderr, /no diff/i)
+})
+
+test('CLI: --diff <empty-file> fails loud, same as empty stdin', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scan-diff-'))
+  const empty = path.join(dir, 'empty.patch')
+  fs.writeFileSync(empty, '')
+  try {
+    const r = runCli(['--diff', empty], '')
+    assert.equal(r.status, NO_INPUT_EXIT)
+    assert.equal(r.stdout.trim(), '')
+    assert.match(r.stderr, /no diff|empty/i)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('CLI: unknown flag (--base X --head Y) exits 2 + "unknown flag", not empty-stdin scan', () => {
+  const r = runCli(['--base', 'aaa', '--head', 'bbb'], '')
+  assert.equal(r.status, USAGE_EXIT)
+  assert.equal(r.stdout.trim(), '', 'the producer mistake no longer yields a false-clean proof')
+  assert.match(r.stderr, /unknown flag/i)
+  assert.match(r.stderr, /--base/)
+})
+
+test('CLI: a real diff with a planted over-mock still detected — guard did not break scanning', () => {
+  const r = runCli([], REAL_OVER_MOCK_DIFF)
+  assert.equal(r.status, 0)
+  const out = JSON.parse(r.stdout)
+  assert.equal(out.findings.length, 1, 'the real over-mock finding is still emitted')
+  assert.equal(out.findings[0].type, 'over-mock-internal-seam')
+})
+
+test('CLI: a real diff with no findings exits 0 with empty findings (legit clean result)', () => {
+  const r = runCli([], REAL_CLEAN_DIFF)
+  assert.equal(r.status, 0, 'input with content but zero findings is the legitimate clean result, not "no input"')
+  const out = JSON.parse(r.stdout)
+  assert.deepEqual(out.findings, [])
+})
+
+test('CLI: --diff <file> with a real diff works (the non-piped legit path)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scan-diff-'))
+  const p = path.join(dir, 'real.patch')
+  fs.writeFileSync(p, REAL_OVER_MOCK_DIFF)
+  try {
+    const r = runCli(['--diff', p], '')
+    assert.equal(r.status, 0)
+    assert.equal(JSON.parse(r.stdout).findings.length, 1)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})

package/skills/engineering/better-review/scripts/vendor-sync.test.mjs

@@ -0,0 +1,96 @@
+// Drift check for the VENDORED over-mock classifier in scan-diff.mjs.
+//
+// scan-diff.mjs carries a self-contained copy of ensure-coverage's
+// `mock-internal-seam` classifier so better-review enforces no-over-mock with zero
+// dependency on ensure-coverage being installed. ensure-coverage stays CANONICAL
+// ("if the two diverge, ensure-coverage wins and this copy is stale → resync").
+// That resync rule used to be prose; this test mechanizes it: it runs the full
+// classification decision tree through BOTH copies and fails on any divergence
+// in verdict or reason, plus compares the default topology field-for-field.
+//
+// When the canonical module is absent (better-review installed standalone), the
+// whole suite skips — there is nothing to be out of sync with.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const CANONICAL = path.resolve(here, '../../ensure-coverage/scripts/mock-policy-config.mjs')
+const standalone = !fs.existsSync(CANONICAL)
+
+const vendored = await import('./scan-diff.mjs')
+const canonical = standalone ? null : await import(CANONICAL)
+
+// One topology per declared-config shape we support; classifyMockTarget takes
+// the same plain object in both copies (canonical compiles externals lazily).
+const TOPOLOGIES = {
+  defaults: undefined, // both sides fall back to their own DEFAULT_*
+  declared: {
+    firstPartyAliasPrefixes: ['@/', '~/', '#app/'],
+    firstPartyPackages: ['@acme/', 'our-lib'],
+    externals: ['^@acme/generated-', '^virtual:'],
+    testUtilHints: ['__mocks__', 'fixtures', 'test-utils'],
+  },
+  badExternalRegex: {
+    firstPartyAliasPrefixes: ['@/'],
+    firstPartyPackages: [],
+    externals: ['[unclosed'], // must be ignored identically, never thrown
+    testUtilHints: ['mocks'],
+  },
+}
+
+// Targets covering every branch of the precedence chain:
+// declared externals > stdlib > relative(util vs source) > alias > first-party
+// package (exact / subpath / trailing-slash config) > bare package > no target.
+const TARGETS = [
+  null, '', 'node:fs', 'node:path',
+  './db', '../services/payment', './__mocks__/db', '../fixtures/user', './test-utils/render',
+  '../mocks/server', './helpers/seed', '@/lib/db', '@/server/auth', '~/utils/format',
+  '#app/db', '@acme/core', '@acme/core/client', '@acme/generated-client', 'our-lib',
+  'our-lib/deep', 'our-library', 'virtual:module', 'react', 'msw', '@tanstack/react-query',
+  'lodash/merge',
+]
+
+test('vendored classifier tracks ensure-coverage (canonical)', { skip: standalone && 'ensure-coverage not installed — standalone better-review, nothing to sync against' }, async (t) => {
+  await t.test('default topology fields match DEFAULT_MOCK_POLICY', () => {
+    const want = canonical.DEFAULT_MOCK_POLICY
+    const got = vendored.DEFAULT_MOCK_TOPOLOGY
+    for (const field of ['firstPartyAliasPrefixes', 'firstPartyPackages', 'externals', 'testUtilHints']) {
+      assert.deepEqual(got[field], want[field], `DEFAULT_MOCK_TOPOLOGY.${field} drifted from canonical DEFAULT_MOCK_POLICY.${field}`)
+    }
+  })
+
+  await t.test('extractMockTarget agrees on a line corpus', () => {
+    const LINES = [
+      `vi.${'mock'}('@/lib/db')`,
+      `jest.${'mock'}("../services/payment", () => ({}))`,
+      `vitest.${'mock'}(\`~/utils/format\`)`,
+      `vi.${'doMock'}('./db')`,
+      `jest.${'doMock'}('react')`,
+      `vi . mock ( '@acme/core' )`,
+      `vi.mock(someVariable)`, // non-literal → null
+      `expect(page).toBeTruthy()`,
+      '', null,
+    ]
+    for (const line of LINES) {
+      assert.equal(vendored.extractMockTarget(line), canonical.extractMockTarget(line), `extractMockTarget diverged on: ${JSON.stringify(line)}`)
+    }
+  })
+
+  await t.test('classifyMockTarget agrees across the full precedence tree', () => {
+    for (const [name, topo] of Object.entries(TOPOLOGIES)) {
+      for (const target of TARGETS) {
+        const got = topo === undefined ? vendored.classifyMockTarget(target) : vendored.classifyMockTarget(target, topo)
+        const want = topo === undefined ? canonical.classifyMockTarget(target) : canonical.classifyMockTarget(target, topo)
+        assert.deepEqual(
+          { internal: got.internal, reason: got.reason },
+          { internal: want.internal, reason: want.reason },
+          `classifyMockTarget diverged on target=${JSON.stringify(target)} topology=${name}`
+        )
+      }
+    }
+  })
+})

package/skills/engineering/e2e-test/LICENSE

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

package/skills/engineering/e2e-test/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: e2e-test
+description: "Playwright end-to-end standard: the 3-tier suite (render-health / functional / journey), generated route manifest, and presentation sweep. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), the curated ALIVE/DEAD golden-path gate (golden-path), or CI workflow YAML (github-actions)."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# E2E Testing Standard
+
+The executable browser layer for `ensure-coverage`'s doctrine. ensure-coverage says *what must be proven* (required levels, the ledger, the presentation floor, the golden-path-only CI contract). This skill is *how* browser and journey surfaces get proven. `resolve-issues` implementers author the tests and run the sweep; `better-review` checks them against [reviewing.md](references/reviewing.md); `golden-path` selects the `@golden-path` subset of Tier 3 as the sole per-PR liveness gate.
+
+## Test tiers
+
+| Tier | Name | What to test | Required when |
+|---|---|---|---|
+| 1 | **Render-health** | Route loads, no crash, heading visible, no console errors (the `presentation:render-health` spine) | Every route not already proven by a Tier 2/3 test that calls `assertRenderHealthy` |
+| 2 | **Functional** | Forms, filters, auth, API responses, error states | Routes with user interaction |
+| 3 | **Journey** | Multi-step flows crossing pages and APIs; the golden paths whose failure means do-not-ship | Core business flows |
+
+Tier 3 is where the golden paths live. `golden-path` authors nothing new: it selects the curated `@golden-path`-tagged subset and gates it ALIVE/DEAD. A tagged spec holds one journey, named by one `@covers <journey-id>` beside its surface `@covers`.
+
+## Directory layout
+
+```
+e2e/
+├── route-manifest.json          # generated projection of the surface inventory
+├── route-manifest.overlay.json  # curated tier / ignore deviations
+├── render/                      # Tier 1
+├── functional/                  # Tier 2, subdirs by feature
+├── journeys/                    # Tier 3; do-not-ship subset tagged @golden-path
+├── fixtures/                    # shared auth, seeded data
+└── utils/
+```
+
+## Writing tests
+
+1. Every new route needs render-health proof: a Tier 1 test, or a Tier 2/3 test on that route that calls `assertRenderHealthy`. Interactive routes need Tier 2 with success, error, and edge cases. Core flows need a Tier 3 journey; tag the do-not-ship subset `@golden-path`.
+2. One test per page and behavior. Never add a Tier 1 test for a route a Tier 2/3 test already proves, and never repeat an assertion another test on the same page makes.
+3. The manifest is generated, never hand-edited. Regenerate it and put curation in the overlay ([route-manifest.md](references/route-manifest.md)).
+4. Tag every spec `// @covers <surface-id>` and `// @level <level>` so the ledger resolves it. Untagged specs are invisible to the accounting gate.
+5. `getByRole` / `getByLabel` / `getByText`, never CSS selectors. Wait for real state, never `waitForTimeout()`.
+6. Auth lives in shared fixtures. Seeded accounts and tenants carry the `e2e-` prefix with a run-scoped suffix ([auth-flows.md](references/authoring/auth-flows.md)).
+7. Journeys drive real APIs. Mock only external third-party boundaries; a first-party `page.route` in a journey grades `Over-mocked`.
+8. **Never skip a test** (the one exception: a platform or optional-dependency skip that CI still runs elsewhere). Seed the missing state, route by Playwright project, quarantine an un-sandboxable external with a dated exit (`@quarantine(until=YYYY-MM-DD, issue=#nnn)`), or delete an obsolete test. Policy and the full solutions map: `ensure-coverage/references/process/test-strategy.md`. `lint-tests.mjs --diff <base>` flags a skip or fixed timeout added in the change.
+9. Bug-fix PRs carry a regression test that fails on the unfixed code.
+
+Patterns and tier examples: [playwright-patterns.md](references/authoring/playwright-patterns.md). Config and the AGENTS.md snippet: [playwright-config.md](references/authoring/playwright-config.md).
+
+## The two commands every browser change owes
+
+Regenerate the manifest from the inventory:
+
+```bash
+node "$SKILL_DIR/scripts/project-route-manifest.mjs" \
+  --inventory docs/tests/_generated/surface-inventory.json \
+  --overlay e2e/route-manifest.overlay.json --out e2e/route-manifest.json
+```
+
+Run the presentation sweep over every manifest route against the real render path:
+
+```bash
+E2E_AUTH_BYPASS=1 node "$SKILL_DIR/scripts/presentation-sweep.mjs" \
+  --manifest e2e/route-manifest.json --base-url http://127.0.0.1:3000 \
+  --out docs/tests/_generated/presentation-results.json [--fixtures e2e/sweep-fixtures.mjs]
+```
+
+`SKILL_DIR` is this skill's own directory, the path you read this file from. Never resolve a script against your CWD, and never locate one with `find` over `$HOME`.
+
+The sweep is separate evidence from the functional suite. A green functional run is not presentation proof: a spec that intercepts its own API never exercises the render path that crashes. Instruments, fixtures, mutate-health, and the result shape the ledger reads: [presentation-sweep.md](references/presentation-sweep.md). A route with no in-app link is still reachable by URL; "no way to view it" is never `blocked`.
+
+## Verify locally before the queue
+
+A merge queue re-runs the browser matrix on the merged candidate, so one regression resets every PR in the batch. Before relying on that: probe the environment instead of assuming it can't run (`docker info`, `pg_isready`, the Playwright browser cache), run the affected specs with `--grep`, not the whole suite, and unit-test your own helper changes where a mocked page object suffices.
+
+## Lead with the verdict
+
+Whether you added tests, wrote notes, or reviewed a PR, the first line answers "is this surface covered and ship-ready?" Then what the new tests prove and deliberately do not, then concrete follow-ups for anything uncovered.
+
+## CI
+
+Curated golden-path smoke is the sole CI gate (`ensure-coverage/references/enforcement/ci-contract.md`). On GitHub Actions, `golden-path init --write` generates the workflow from the repo's contract; on Cloud Build, copy [`assets/ci-gates.cloudbuild.yaml`](assets/ci-gates.cloudbuild.yaml). Verify either with `ci-audit.mjs`. Wiring notes: [ci-integration.md](references/ci-integration.md). Running Playwright in a pinned container on self-hosted runners: [ci-playwright-container.md](references/ci-playwright-container.md).
+
+## Reviewing
+
+Checklist and comment template: [reviewing.md](references/reviewing.md). Block on: a new route without a manifest entry, an interactive route without Tier 2, a browser-route change with no sweep run, any skipped or guarded test, or an assertion that would pass on a 404 or empty page.
+
+## Scripts
+
+| script | does |
+|---|---|
+| `detect-routes-nextjs.mjs` | enumerate Next.js App Router pages and route handlers into the surface inventory |
+| `project-route-manifest.mjs` | project `kind: route` surfaces plus the overlay into `route-manifest.json` |
+| `validate-manifest.mjs` | shape-check the manifest and its entries |
+| `presentation-sweep.mjs` | open every manifest route, assert the presentation floor, write the results the ledger reads |
+| `presentation-render-health.mjs` | `assertRenderHealthy` / `assertHealthyThrough` (the spine, and mutate-health) |
+| `presentation-checks.mjs` | `assertNoHorizontalOverflow` / `assertNoOverlap` (`presentation:spatial`) |
+| `presentation-perceivability.mjs` | `assertContrast` / `assertHiddenFromWrongRole` / `assertRemovedAfterMutation` |
+| `presentation-reachability.mjs` | `assertNoNavOrphans` / `assertTargetSizes` / `assertFocusVisible` |
+| `presentation-temporal.mjs` | `assertNoFirstPartyShift` / `assertNoThirdPartyShift` / `assertNoDynamicViewportShift` |

package/skills/engineering/e2e-test/assets/ci-gates.cloudbuild.yaml

@@ -0,0 +1,24 @@
+# Golden-path smoke - Cloud Build template.
+# The sole CI gate in ensure-coverage's CI contract. It calls the engine copy that
+# `golden-path init` writes into the repo. Replace <...> and audit with:
+# node <ensure-coverage>/scripts/ci-audit.mjs --files cloudbuild.gates.yaml
+
+steps:
+  - id: golden-paths
+    name: mcr.microsoft.com/playwright:v1.61.0-noble
+    timeout: 600s
+    entrypoint: bash
+    env: ['DATABASE_URL=${_DATABASE_URL}']
+    args:
+      - -c
+      - |
+        set -euo pipefail
+        <install dependencies>
+        node scripts/golden-paths/golden-path.mjs check
+        <build the app (setup.build): --boot runs only setup.seed and setup.boot>
+        node scripts/golden-paths/golden-path.mjs run --profile queue-local --boot
+        node scripts/golden-paths/golden-path.mjs verdict --profile queue-local
+
+timeout: 600s
+substitutions:
+  _DATABASE_URL: ''