@1aboveio/skills 0.10.0

package/skills/engineering/review-pr/scripts/scan-diff.mjs

@@ -0,0 +1,365 @@
+// Cheap scan of a unified diff. It emits TWO channels, and the distinction is
+// load-bearing:
+//   • LEADS (heuristic) — "look here and verify"; the reviewer reads the code and
+//     builds the counterexample before any becomes a finding (see review-method.md).
+//   • FINDINGS (decidable) — near-zero-false-positive checks that ARE blockers on
+//     their own. Currently: `over-mock-internal-seam` (a vi/jest.mock of a
+//     first-party seam = Over-mocked, zero-tolerance). This makes review-pr the
+//     standalone first line of enforcement — no dependency on ensure-coverage's
+//     gate being wired in the repo.
+//
+//   git diff <merge-base>...HEAD | node scan-diff.mjs        # leads + findings from stdin
+//   node scan-diff.mjs --diff changes.patch
+//
+// Best-effort and JS/TS-oriented (regex/branch heuristics are language-bound; the
+// mock/interception checks are framework-specific). On other languages it simply
+// finds fewer — it is additive, and absence means "the scanner found nothing,"
+// not "the code is fine."
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure core ----
+
+// Parse a unified diff into added lines with their NEW-file line numbers.
+export function parseAddedLines(diffText) {
+  const out = []
+  let file = null
+  let newLine = 0
+  for (const raw of (diffText || '').split(/\r?\n/)) {
+    if (raw.startsWith('+++ ')) {
+      const m = raw.match(/^\+\+\+ b\/(.+)$/)
+      file = m ? m[1] : raw.slice(4).replace(/^b\//, '')
+      continue
+    }
+    if (raw.startsWith('diff --git')) { file = null; continue }
+    const hm = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)
+    if (hm) { newLine = parseInt(hm[1], 10); continue }
+    if (raw.startsWith('+')) { out.push({ file, line: newLine, text: raw.slice(1) }); newLine++; continue }
+    if (raw.startsWith('-')) continue // removed line: no advance in new file
+    if (raw.startsWith('\\')) continue // ""
+    newLine++ // context line
+  }
+  return out
+}
+
+const TEST_FILE = /\.(test|spec)\.[jt]sx?$/
+const INTERCEPT = /\broute\.fulfill\b|\bpage\.route\s*\(|\bsetupServer\s*\(|\bsetupWorker\s*\(|from\s+['"]msw['"]/
+
+export function interceptionLeads(added) {
+  return added
+    .filter((a) => a.file && TEST_FILE.test(a.file) && INTERCEPT.test(a.text))
+    .map((a) => ({ type: 'first-party-interception', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'first-party interception in a test — over-mock risk; verify the real path is actually proven (browser/journey, not stub). Skip if: the route is a third-party/external boundary, or this is a Tier-2 functional failure-injection test (interception is correct there).' }))
+}
+
+// Regex literals / RegExp() added without ^ or $ anchors → boundary-leak risk.
+export function regexLeads(added) {
+  const out = []
+  for (const a of added) {
+    for (const lit of a.text.match(/\/(?:[^/\n\\]|\\.){2,}\/[gimsuy]*/g) || []) {
+      const body = lit.replace(/\/[gimsuy]*$/, '').slice(1)
+      if (!/[\^$]/.test(body) && /[A-Za-z0-9]/.test(body)) {
+        out.push({ type: 'unanchored-pattern', file: a.file, line: a.line, snippet: lit,
+          note: 'regex without ^/$ anchors — verify prefix/substring leakage at boundaries (does /foo also match /foobar?). Skip if: inputs are a closed/validated set where leakage cannot occur, or a substring match is intended — produce the breaking input or drop it.' })
+      }
+    }
+    const re = a.text.match(/new RegExp\(([^)]*)\)/)
+    if (re && !/[\^$]/.test(re[1])) {
+      out.push({ type: 'unanchored-pattern', file: a.file, line: a.line, snippet: re[0].trim(),
+        note: 'RegExp without ^/$ — verify boundary behavior.' })
+    }
+  }
+  return out
+}
+
+// Weakened assertions in tests → a test that can't fail the way its name promises.
+// Two tells from real "smoke wearing a journey label" specs:
+//   - `.catch(() => false)` (or null/undefined/0/'') swallows a locator/await throw
+//     into a falsy, defeating Playwright's web-first retry and any assertion on it.
+//   - `expect(a || b || c).toBeTruthy()` / `.toBe(true)` — a disjunctive truthiness
+//     assertion passes if ANY branch holds, so it pins down no specific behavior.
+// Reviewer then checks the test's @level: a journey/functional test asserting only
+// these is Wrong Level (review-method.md → Spec Compliance).
+const CATCH_SWALLOW = /\.catch\s*\(\s*\(\s*\)\s*=>\s*(?:false|null|undefined|0|''|""|``)\s*\)/
+const DISJUNCTIVE_TRUTHY = /\bexpect\s*\([^;]*\|\|[^;]*\)\s*\.\s*(?:toBeTruthy\b|toBe\s*\(\s*true\s*\))/
+export function weakAssertionLeads(added) {
+  const out = []
+  for (const a of added) {
+    if (!a.file || !TEST_FILE.test(a.file)) continue
+    if (CATCH_SWALLOW.test(a.text)) out.push({ type: 'swallowed-assertion', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'catch swallows a locator/await throw into a falsy — defeats web-first retry and hides real failures; assert directly (web-first expect), do not catch-to-false. Skip if: the falsy genuinely feeds a non-assertion control-flow decision and the real outcome is asserted separately.' })
+    if (DISJUNCTIVE_TRUTHY.test(a.text)) out.push({ type: 'weak-assertion', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'disjunctive truthiness — passes if any branch holds, so it proves nothing specific; if this is a @level journey/functional test it is Wrong Level (drive the flow to a concrete outcome). Skip if: this is a @level render-health test (alias: smoke) where "renders at all" is the whole contract.' })
+  }
+  return out
+}
+
+// A test that *names itself* a race but reads state some earlier test already created
+// cannot exercise the first-writer path: both "concurrent" callers take the
+// already-exists early return, and the contended create never runs. The tell is a
+// pre-existing capture (`x!.id`, `find*OrThrow`) reached before the `Promise.all`.
+// Kept a LEAD, not a finding: post-seal/replay races legitimately look exactly like
+// this. What makes it a defect is the test being cited as first-writer proof — a
+// judgment about the AC mapping that no regex can make.
+const ANY_TEST_TITLE = /\b(?:it|test)\s*(?:\.\w+)?\s*\(\s*['"`]/
+const CONCURRENCY_TEST_TITLE = /\b(?:it|test)\s*(?:\.\w+)?\s*\(\s*['"`][^'"`]*\b(?:race|races|racing|concurrent|concurrently|simultaneous(?:ly)?|parallel)\b/i
+const PREEXISTING_CAPTURE = /\w\s*!\s*\.\s*\w|\bfind(?:First|Unique)OrThrow\s*\(/
+const CONCURRENT_CALL = /\bPromise\s*\.\s*(?:all|allSettled|race)\s*\(/
+
+export function concurrencyFixtureLeads(added) {
+  const out = []
+  const byFile = new Map()
+  for (const a of added) {
+    if (!a.file || !TEST_FILE_ANY.test(a.file)) continue
+    if (!byFile.has(a.file)) byFile.set(a.file, [])
+    byFile.get(a.file).push(a)
+  }
+  for (const [, lines] of byFile) {
+    lines.sort((x, y) => x.line - y.line)
+    let title = null // the concurrency-named test we are inside
+    let capture = null // first pre-existing capture seen since that title
+    for (const a of lines) {
+      // Any test title closes the previous body. Tracking only concurrency titles
+      // would leave scope open across the rest of the file, so the next ordinary
+      // test's fixture would be attributed to a race test that already ended.
+      if (ANY_TEST_TITLE.test(a.text)) {
+        title = CONCURRENCY_TEST_TITLE.test(a.text) ? a : null
+        capture = null
+        continue
+      }
+      if (!title) continue
+      if (!capture && PREEXISTING_CAPTURE.test(a.text)) { capture = a; continue }
+      if (capture && CONCURRENT_CALL.test(a.text)) {
+        out.push({ type: 'concurrency-test-preexisting-fixture', file: capture.file, line: capture.line, snippet: capture.text.trim(),
+          note: `test named as a race/concurrent case reads pre-existing state before ${a.text.trim().slice(0, 40)}… — if that state is what the concurrent calls are supposed to be creating, every caller takes the already-exists path and the contended first-write is never exercised (a green test for an untested race). Verify the fixture starts from ABSENT, with independent clients/connections and a barrier. Skip if: this is deliberately a post-create replay/idempotency case AND a separate test covers the first-write race — then check that the AC cites that one, not this.` })
+        title = null; capture = null
+      }
+    }
+  }
+  return out
+}
+
+// New conditional branches → each needs a test (line coverage ≠ branch coverage).
+export function branchLeads(added) {
+  return added
+    .filter((a) => /\b(if|else if|case)\b/.test(a.text) || /\?[^?]*:/.test(a.text))
+    .map((a) => ({ type: 'new-branch', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'new branch — name a test that exercises it; line coverage is not branch coverage. Skip if: an integration/E2E test already drives it, or the branch is a trivial guard whose failure is inert.' }))
+}
+
+// Files whose EXISTING behavior is modified (edited/removed lines in a non-test
+// SOURCE file) owe a characterization test pinning prior behavior before the
+// change (ensure-coverage → depth/characterization.md). A new file or a test
+// file is excluded; only changed/removed content in a non-test source file
+// signals an existing-behavior modification. The *detection* is decidable; the
+// adjudication ("is there an adequate @characterizes test, or a declared intended
+// change?") is the reviewer's — hence a lead, not a finding.
+const TEST_FILE_ANY = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(e2e|tests?|__tests__)\/|(^|\/)test_[^/]*\.py$|_test\.py$/
+const NON_SOURCE = /\.(md|markdown|json|ya?ml|txt|lock|svg|png|jpe?g|gif|webp|ico|csv|tsv|toml|ini|cfg|snap)$/i
+
+// Parse a diff into per-file change shape: { isNew, removed, added, firstLine }.
+// `removed` counts changed/deleted content lines (the modify signal); a new file
+// (--- /dev/null or `new file mode`) is flagged so it's treated as addition.
+export function parseFileChanges(diffText) {
+  const files = new Map()
+  let file = null
+  let pendingNew = false
+  let newLine = 0
+  for (const raw of (diffText || '').split(/\r?\n/)) {
+    if (raw.startsWith('diff --git')) { file = null; pendingNew = false; continue }
+    if (raw.startsWith('new file mode')) { pendingNew = true; continue }
+    if (raw.startsWith('--- ')) { if (/\/dev\/null/.test(raw)) pendingNew = true; continue }
+    if (raw.startsWith('+++ ')) {
+      const m = raw.match(/^\+\+\+ (?:b\/)?(.+)$/)
+      file = m && m[1] !== '/dev/null' ? m[1] : null
+      if (file && !files.has(file)) files.set(file, { isNew: pendingNew, removed: 0, added: 0, firstLine: 0 })
+      pendingNew = false
+      continue
+    }
+    if (!file) continue
+    const hm = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)
+    if (hm) { newLine = parseInt(hm[1], 10); continue }
+    const rec = files.get(file)
+    if (!rec) continue
+    if (raw.startsWith('-')) { rec.removed++; if (!rec.firstLine) rec.firstLine = newLine; continue } // no new-line advance
+    if (raw.startsWith('+')) { rec.added++; if (!rec.firstLine) rec.firstLine = newLine; newLine++; continue }
+    if (raw.startsWith('\\')) continue
+    newLine++ // context
+  }
+  return files
+}
+
+export function characterizationLeads(diffText) {
+  const out = []
+  for (const [file, rec] of parseFileChanges(diffText)) {
+    if (rec.isNew) continue                    // new file = new behavior, not a modification
+    if (TEST_FILE_ANY.test(file)) continue     // editing tests is not modifying production behavior
+    if (NON_SOURCE.test(file)) continue        // docs/config/snapshots carry no behavior to pin
+    if (rec.removed === 0) continue            // pure addition into an existing file = added behavior
+    out.push({ type: 'modifies-existing-behavior', file, line: rec.firstLine || 1,
+      snippet: `${rec.removed} existing line(s) changed/removed`,
+      note: 'existing behavior modified — verify a characterization test pins the PRIOR behavior (authored to pass on the pre-change tree) so this diff is proven not to shift observable behavior unintentionally; tag it `// @characterizes <surface>`. Skip if: an existing behavior test already covers this exact path and still passes unchanged (cite it), this is a declared intended behavior change with its AC and the assertion delta is in the diff, or the edit is trivial/generated/non-behavioral. See ensure-coverage depth/characterization.md.' })
+  }
+  return out
+}
+
+// ---- VENDORED over-mock classifier — DECIDABLE FINDING, not a lead ----
+//
+// Self-contained copy of ensure-coverage's `mock-internal-seam` classifier
+// (skills/engineering/ensure-coverage/scripts/mock-policy-config.mjs), vendored
+// here so review-pr enforces no-over-mock with ZERO dependency on ensure-coverage
+// being installed/wired. ensure-coverage stays CANONICAL: if the two diverge,
+// ensure-coverage wins and this copy is stale → resync. Kept tiny on purpose.
+//
+// The "externals-allowlist inversion": you can't enumerate internal seams, but
+// the legitimately-fakeable set (third-party/stdlib) is small and known — so a
+// mock whose target resolves to first-party code is a seam (a defect), and the
+// declared externals / stdlib / bare packages are exempt. Unlike the heuristic
+// leads above this is DECIDABLE, so its hits are emitted as `findings`.
+
+export const DEFAULT_MOCK_TOPOLOGY = {
+  firstPartyAliasPrefixes: ['@/', '~/'],
+  firstPartyPackages: [],                 // e.g. a monorepo's own scope '@acme/'
+  externals: [],                          // regex SOURCES for first-party-looking-but-external targets
+  testUtilHints: ['__mocks__', '__fixtures__', 'fixtures', 'mocks', 'helpers',
+    'test-utils', 'testing', 'support', 'stubs', 'factories'],
+}
+
+// Best-effort read of coverage.config.json topology (so a monorepo's own @scope
+// is recognized); never throws — defaults to conventional @/ ~/ when absent.
+// Config declares TOPOLOGY only; it cannot disable the check (zero-tolerance).
+export function loadMockTopology(cwd = process.cwd()) {
+  for (const name of ['coverage.config.json', '.coverage.config.json']) {
+    try {
+      const mp = (JSON.parse(fs.readFileSync(path.join(cwd, name), 'utf8')).mockPolicy) || {}
+      return {
+        firstPartyAliasPrefixes: mp.firstPartyAliasPrefixes ?? DEFAULT_MOCK_TOPOLOGY.firstPartyAliasPrefixes,
+        firstPartyPackages: mp.firstPartyPackages ?? DEFAULT_MOCK_TOPOLOGY.firstPartyPackages,
+        externals: mp.externals ?? DEFAULT_MOCK_TOPOLOGY.externals,
+        testUtilHints: mp.testUtilHints ?? DEFAULT_MOCK_TOPOLOGY.testUtilHints,
+      }
+    } catch { /* missing or malformed → try next, else defaults */ }
+  }
+  return { ...DEFAULT_MOCK_TOPOLOGY }
+}
+
+// Pull the mocked specifier from a vi/jest/vitest `.mock`/`.doMock(...)` call.
+export function extractMockTarget(codeLine) {
+  const m = /\b(?:vi|jest|vitest)\s*\.\s*(?:mock|doMock)\s*\(\s*(['"`])([^'"`]+)\1/.exec(codeLine || '')
+  return m ? m[2] : null
+}
+
+// Classify a mock target as an internal seam (a defect) or an allowed external.
+// Precedence: declared externals > stdlib > relative(util vs source) >
+// first-party alias > first-party package > bare package (external default).
+export function classifyMockTarget(target, topo = DEFAULT_MOCK_TOPOLOGY) {
+  if (!target) return { internal: false, reason: 'no target' }
+  for (const src of topo.externals || []) {
+    try { if (new RegExp(src).test(target)) return { internal: false, reason: 'declared external' } } catch { /* ignore bad regex */ }
+  }
+  if (target.startsWith('node:')) return { internal: false, reason: 'node builtin' }
+  if (target.startsWith('.')) {
+    if (target.split('/').some((s) => (topo.testUtilHints || []).includes(s))) return { internal: false, reason: 'relative test util/fixture/mock' }
+    return { internal: true, reason: 'relative import into first-party source' }
+  }
+  for (const pre of topo.firstPartyAliasPrefixes || []) {
+    if (target.startsWith(pre)) return { internal: true, reason: `first-party alias "${pre}"` }
+  }
+  for (const fp of topo.firstPartyPackages || []) {
+    const base = fp.endsWith('/') ? fp.slice(0, -1) : fp
+    if (target === base || target.startsWith(`${base}/`)) return { internal: true, reason: `first-party package "${fp}"` }
+  }
+  return { internal: false, reason: 'external package' }
+}
+
+// Diff-scoped over-mock FINDINGS: a vi/jest/vitest.mock of a first-party internal
+// seam ADDED in a test file → Over-mocked (a blocker), not a lead. Diff-scoped is
+// the right scope for a PR review (review the diff; pre-existing mocks are notes by
+// diff-discipline) — the whole-tree inherited burndown is ensure-coverage's audit lint.
+export function overMockFindings(added, topo = DEFAULT_MOCK_TOPOLOGY) {
+  const out = []
+  for (const a of added) {
+    if (!a.file || !TEST_FILE_ANY.test(a.file)) continue
+    const target = extractMockTarget(a.text)
+    if (!target) continue
+    const { internal, reason } = classifyMockTarget(target, topo)
+    if (!internal) continue
+    out.push({ type: 'over-mock-internal-seam', file: a.file, line: a.line, snippet: a.text.trim(), target, reason,
+      note: 'mocks a first-party internal seam → Over-mocked (dishonest green): zero-tolerance, NO @mock-ok waiver and no "approved with justification" (ensure-coverage depth/mock-policy.md). Resolve by making the test real, faking only the external, or DELETING it (over-mock is worse than no test). Only NOT a finding if the target is genuinely external — then declare it as topology in coverage.config.json.' })
+  }
+  return out
+}
+
+export function scanDiff(diffText, topo = DEFAULT_MOCK_TOPOLOGY) {
+  const added = parseAddedLines(diffText)
+  const byPlace = (a, b) => (a.file || '').localeCompare(b.file || '') || a.line - b.line
+  const leads = [...interceptionLeads(added), ...regexLeads(added), ...weakAssertionLeads(added), ...branchLeads(added),
+    ...concurrencyFixtureLeads(added), ...characterizationLeads(diffText)].sort(byPlace)
+  const findings = overMockFindings(added, topo).sort(byPlace)
+  const tally = (xs) => xs.reduce((m, l) => ((m[l.type] = (m[l.type] || 0) + 1), m), {})
+  // `counts`/`leads` kept for back-compat; `findings` is the decidable, blocker-grade channel.
+  return { kind: 'leads+findings', counts: tally(leads), leads, findingCounts: tally(findings), findings }
+}
+
+// ---- CLI ----
+
+// Exit codes. Both are usage errors (distinct from 0 = scanned OK, and from a
+// generic crash). NO_INPUT is the fail-open this tool exists NOT to have: a
+// parity proof that returns "all clear" on zero bytes proved nothing about the
+// diff (issue #416). USAGE catches the `--base/--head` invocation producers
+// invented — flags this tool never had, which used to fall through to an empty
+// stdin read and a vacuous clean result.
+export const NO_INPUT_EXIT = 2
+export const USAGE_EXIT = 2
+
+// The ONE correct invocation, echoed in every error so a wrong call self-corrects.
+const USAGE = 'Pipe the net diff: git diff <merge-base>...HEAD | node scan-diff.mjs   (or: node scan-diff.mjs --diff <file>). This tool takes NO --base/--head.'
+
+// A usage/no-input error carrying its own process exit code. Thrown by the arg
+// parser and the empty-input guard; main() prints .message to stderr and exits.
+export class ScanDiffCliError extends Error {
+  constructor(message, code = USAGE_EXIT) { super(message); this.name = 'ScanDiffCliError'; this.code = code }
+}
+
+// Parse argv (already sliced of node + script). Returns { diffPath } — null means
+// read stdin. Anything that isn't `--diff <file>` HARD-FAILS: an unknown flag
+// (the `--base/--head` mistake) or a stray positional would otherwise be silently
+// ignored, dropping through to an empty stdin read and a false-clean proof.
+export function parseCliArgs(argv) {
+  let diffPath = null
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--diff') {
+      diffPath = argv[i + 1]
+      if (diffPath == null) throw new ScanDiffCliError(`scan-diff: --diff requires a file path. ${USAGE}`)
+      i++
+      continue
+    }
+    if (arg.startsWith('-')) throw new ScanDiffCliError(`scan-diff: unknown flag "${arg}". ${USAGE}`)
+    throw new ScanDiffCliError(`scan-diff: unexpected argument "${arg}". ${USAGE}`)
+  }
+  return { diffPath }
+}
+
+function main() {
+  let diff
+  try {
+    const { diffPath } = parseCliArgs(process.argv.slice(2))
+    diff = diffPath != null ? fs.readFileSync(diffPath, 'utf8') : fs.readFileSync(0, 'utf8') // --diff <file> or stdin
+    // Fail LOUD on no input. Empty/whitespace-only means the diff never arrived
+    // (a non-piped context, or the `--base/--head` fall-through) — NOT a clean
+    // diff. A real diff with content but zero findings still exits 0 below;
+    // "no INPUT" and "input with no findings" are different answers.
+    if (!diff.trim()) throw new ScanDiffCliError(`scan-diff: no diff on stdin (or --diff <file> is empty). ${USAGE}`, NO_INPUT_EXIT)
+  } catch (err) {
+    if (err instanceof ScanDiffCliError) { process.stderr.write(`${err.message}\n`); process.exit(err.code) }
+    throw err
+  }
+  const result = scanDiff(diff, loadMockTopology())
+  result.disclaimer = 'TWO channels. `leads` = heuristic "look here and verify" (read the code, build the counterexample first). `findings` = DECIDABLE blockers (over-mock-internal-seam): a vi/jest.mock of a first-party seam is Over-mocked, zero-tolerance, no waiver — fix it, do not merge over it. Best-effort, JS/TS-oriented; absence != code is fine.'
+  console.log(JSON.stringify(result, null, 2))
+}
+
+if (isMainModule(import.meta.url)) main()

package/skills/engineering/review-pr/scripts/theme-contract.mjs

@@ -0,0 +1,57 @@
+// Shared review-finding theme contract. resolve-issues imports this validator so
+// reviewer output and durable fix-round state cannot disagree about identity or
+// state-space completeness.
+
+export const THEME_KINDS = ['other', 'state-machine', 'concurrency']
+export const CONTRACT_COMPLETE_KINDS = new Set(['state-machine', 'concurrency'])
+
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0
+
+export function stateSpaceCells(theme) {
+  const states = theme?.stateSpace?.states || []
+  const taskKinds = theme?.stateSpace?.taskKinds || []
+  return states.flatMap((state) => taskKinds.map((taskKind) => ({ state, taskKind })))
+}
+
+function uniqueNonEmptyStrings(values, label) {
+  const errors = []
+  if (!Array.isArray(values) || values.length === 0) {
+    errors.push(`${label} must contain at least one value`)
+    return errors
+  }
+  const seen = new Set()
+  values.forEach((value) => {
+    if (!nonEmptyString(value)) errors.push(`${label} must contain non-empty strings`)
+    if (seen.has(value)) errors.push(`${label} must not contain duplicates: ${value}`)
+    seen.add(value)
+  })
+  return errors
+}
+
+export function validateTheme(theme) {
+  const errors = []
+  if (!isObject(theme)) return ['theme is required and must be an object']
+  errors.push(...uniqueKeys(theme, ['id', 'kind', 'contract', 'stateSpace'], 'theme'))
+  if (!nonEmptyString(theme.id) || !/^[a-z][a-z0-9-]*$/.test(theme.id)) {
+    errors.push('theme.id must be a stable kebab-case identity')
+  }
+  if (!THEME_KINDS.includes(theme.kind)) errors.push(`theme.kind must be one of ${THEME_KINDS.join('|')}`)
+  if (!nonEmptyString(theme.contract)) errors.push('theme.contract must name the general violated contract')
+  if (CONTRACT_COMPLETE_KINDS.has(theme.kind)) {
+    if (!isObject(theme.stateSpace)) {
+      errors.push('state-machine/concurrency theme requires stateSpace')
+    } else {
+      errors.push(...uniqueKeys(theme.stateSpace, ['states', 'taskKinds'], 'theme.stateSpace'))
+      errors.push(...uniqueNonEmptyStrings(theme.stateSpace.states, 'stateSpace.states'))
+      errors.push(...uniqueNonEmptyStrings(theme.stateSpace.taskKinds, 'stateSpace.taskKinds'))
+    }
+  } else if (theme.stateSpace !== undefined) {
+    errors.push('theme.stateSpace is only allowed for state-machine/concurrency themes')
+  }
+  return errors
+}
+
+function uniqueKeys(value, allowed, label) {
+  return Object.keys(value).filter((key) => !allowed.includes(key)).map((key) => `${label} has unknown property: ${key}`)
+}

package/skills/engineering/smoke/LICENSE

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

package/skills/engineering/smoke/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: smoke
+description: "Curated E2E smoke gate over the golden paths: one ALIVE/DEAD verdict naming the broken path, driving the real app (browser via e2e-test's Playwright; api/cli via runtime observation); also creates/curates the golden-path manifest. Runs standalone, as the per-PR CI floor, the epic integration gate, or post-deploy verification. NOT for authoring tiered specs (e2e-test) or defining what to prove (ensure-coverage)."
+dependencies:
+  - e2e-test
+---
+
+# Smoke (curated E2E happy-path liveness gate)
+
+Answer one question fast: **if a real user walked the few flows that matter right now, would the build be alive?** Smoke runs a small, curated set of **golden paths** against a *running* app and returns a binary **ALIVE / DEAD** verdict plus which path broke. For browser paths this is mechanically E2E — it drives the real UI through `e2e-test`'s Playwright runner — but stays *smoke* by selection, placement, and verdict: tiny, critical, fast enough for every gate, binary. It catches the integrated, render-time, only-breaks-in-the-real-app bugs a green unit/functional suite proves nothing about (the #237 class: a primary button that computed to transparent; a Feishu-QR component that crashed on unmount).
+
+Smoke **owns only** the curated manifest, target-safe selection, the drive-result contract, and the ALIVE/DEAD verdict. It does **not** define coverage (`ensure-coverage`), author tiered specs (`e2e-test`), or review code (`review-pr`) — for browser paths it *drives through* `e2e-test`'s runner rather than forking it.
+
+## It's `/verify` applied to a standing set
+
+Same discipline as `/verify`, pointed at a curated manifest instead of one ad-hoc diff:
+
+- **A verdict is runtime observation — nothing else.** Build it, run it, drive the real interface to where the flow executes, capture what you see. That capture is the evidence — not a green test suite, a typecheck, or import-and-call.
+- **Drive end to end; probe the cheap adjacents.** If users click buttons, click buttons — don't curl the API underneath; seams are where bugs hide. Push one step past the happy path where it's cheap (a 🔍 step).
+- **Capture is evidence; memory isn't.** Screenshots, response bodies, pane dumps. Isolate shared process state (ports, tmux, tmp dirs).
+- **When in doubt, FAIL.** A false ALIVE ships broken code; a false DEAD costs one more look. No partial pass — "3 of 4 worked" is DEAD until the 4th passes or is explained away.
+
+Where it differs:
+
+| | `/verify` | `smoke` |
+|---|---|---|
+| Subject | one change / diff | a **curated standing manifest** |
+| Question | "does *this change* work?" | "is *the build* alive?" |
+| Output | PASS/FAIL/BLOCKED/SKIP | **ALIVE/DEAD** + which path broke |
+| Run by | a human/agent reviewing a PR | callers as a **gate** (epic integration, release, /smoke) |
+| Target | wherever the change surfaces | **configurable**: local build or deployed revision |
+
+## The curated manifest (and ensuring it exists)
+
+The value is the *curation*: the manifest is the **handful of flows whose failure means "do not ship"** — the critical-revenue / critical-trust journeys (sign in, sign up, the core action, pay), not a route census (that's `e2e-test`'s manifest). Keep it small and ruthless. Each path declares its `id`, `surface`, and target-safety (`mutates`/`tenant`); a **browser path references its `@smoke` Tier-3 journey** rather than re-specifying the flow (the spec owns the steps + observable), while `api`/`cli` paths carry their own `start`/`command` + `observable`. Format and fields: [references/manifest.md](references/manifest.md). Starter: [assets/smoke.manifest.example.json](assets/smoke.manifest.example.json).
+
+**Ensure the manifest exists before you gate — the first move, every time.** No manifest = a vacuous pass; a stale one green-lights a flow nobody re-curated. So `validate` is the *ensure* step, not just a lint. Route on what you find:
+
+| Situation | What "ensure" means |
+|---|---|
+| **No manifest** (`validate` reports *no manifest at …*) | **Bootstrap — never fabricate from memory.** Discover candidates (below), get the do-not-ship call from product/release, write concrete observables + synthetic tenants, then `validate`. A guessed "login + dashboard" set is the false-ALIVE this prevents; if the release-blocking decision needs a human, **stop and ask**. |
+| **Manifest exists, this golden path isn't in it** (a new critical flow) | **Add the entry, then `validate`** — a run driving only the old paths silently misses the new do-not-ship flow. |
+| **Manifest covers the path** | Straight to gating — but still `validate` first (a malformed manifest passes vacuously). |
+
+**Discover candidates, then curate.** Discovery is automatable; the do-not-ship decision stays human (a guessed set gives a false ALIVE). Draw candidates strongest-source-first — the already-curated `@smoke`-taggable Tier-3 journeys; core-entity state transitions (each user-driven, money/irreversible transition is a candidate, target state = its observable); ADRs as a ranking signal; the surface inventory (`suggest`) as the crude fallback — none *decide* the set, they stop you starting from memory. Detail: [references/manifest.md](references/manifest.md#where-candidates-come-from-discover-then-curate).
+
+```bash
+node <smoke>/scripts/smoke.mjs validate --manifest smoke.manifest.json --journeys e2e/journeys
+```
+
+`--journeys` **reconciles the browser→journey references against the actual `@smoke` tags** — both directions are errors: a path pointing at a journey that isn't `@smoke`-tagged (the gate can't drive it), *and* a spec tagged `@smoke` that no path references (it silently never runs — a false ALIVE). Wire it into CI wherever the specs are reachable; without it the reference is unchecked prose.
+
+**Prerequisites live in the manifest's `setup` block, not in `AGENTS.md`.** How to boot, env/secrets, the auth-bypass, seed data, synthetic tenants — co-located with the paths so they load with the gate and `validate` can *check* them. Reuse what owns each piece (`setup.fixtures` → `e2e-test`'s harness, `setup.boot` → the `run` skill); keep a one-line pointer in `AGENTS.md`. Fields + reuse rule: [references/manifest.md](references/manifest.md#the-setup-block-prerequisites--co-located-with-the-gate).
+
+## Selection is by Validation Profile (`--profile`), not free-form targeting
+
+The gate selects paths by a **named Validation Profile** from the manifest's `profiles` registry — one name decides *which* paths run and *whether* writes are allowed. Each profile binds three axes the old single `--target` string conflated — a **gate** (why evidence is required), an **environment** (`local`/`dev`/`prod`), an **endpoint** (`local`/`preview`/`active`) — plus its `prerequisites`, `evidencePolicy`, and `mutationPolicy`. Format and the five initial profiles (`pr-local`, `queue-local`, `dev-active`, `prod-preview`, `prod-active`): [references/manifest.md](references/manifest.md#validation-profiles-the-profiles-registry).
+
+```bash
+node <smoke>/scripts/smoke.mjs plan --manifest smoke.manifest.json --profile pr-local
+node <smoke>/scripts/smoke.mjs plan --manifest smoke.manifest.json --profile prod-preview --target https://rev-xyz.run.app
+```
+
+`--target` is now **just the address to drive against** (the deployed candidate/service URL; defaults to `local`) — it no longer participates in selection. The profile does. For a `local` profile, boot the build yourself the `/verify` way (a `run-*`/`verifier-*` skill in `.claude/skills/`, else the **`run`** skill, else cold-start from README/package.json, timebox ~15 min → BLOCKED); for a deployed profile, point `--target` at the revision and confirm it is the SHA you mean to verify.
+
+**Prod safety is mechanical, and it lives on the profile.** A path runs in a profile only if it declares that profile AND the profile's `mutationPolicy` admits it. The **production profiles (`prod-preview`, `prod-active`) are read-only** — every `mutates:true` path is excluded, **tenant or not** (a synthetic tenant still writes to the real production database, and a revision at 0% traffic is not a reason those writes are safe: `resolve-release` principle 4). `dev-active` allows a `mutates:true` path **only with a declared synthetic tenant**; the local profiles allow isolated writes. This is the old `--no-mutations` flag turned into a property of the *named profile*, so nobody has to remember to pass it — and because one name drives both the run and the verdict, the two **cannot disagree** about the selected set (the old run/verdict flag-mismatch is unrepresentable).
+
+**Gate before promote.** On a deployed target the smoke is a gate only if it runs *before* the revision is irreversible — a smoke after traffic shifts is a monitor, not a gate. Deploy the candidate at **0% traffic** (stable, addressable) → smoke that URL under `prod-preview` → **promote only on ALIVE** → confirm the serving revision is the one you smoked, then re-smoke the live service under `prod-active`. Bonus: a DEAD is re-investigable against the same 0%-traffic revision with no rebuild — most of what a deployed smoke catches is config/secret/packaging. **Reuse the platform's deploy notification** (the CI/deploy build-failure → Pub/Sub/webhook path), carrying `smoke-verdict.json` so the alert names the broken path; the concrete placement lives in `cloud-build` / `cloud-deploy`.
+
+## Drive each path, then compute the verdict
+
+1. **Get a handle on the target** (boot via `run`, or point at the URL).
+2. **Drive each selected path through its surface** and observe the declared observable — the drive step emits `smoke-results.json`:
+   - **browser** → run its `@smoke` Tier-3 journey in a real browser via **`e2e-test`'s Playwright runner**. Real render, no first-party interception (a stubbed DOM hides exactly these bugs). The spec asserts the observable *and* render-health (no `pageerror` / `console.error` / error-boundary / 5xx); stub only the true external boundary (CDN SDK, provider endpoint), never the component itself.
+   - **api** → send the request, capture the response, assert the observable.
+   - **cli** → run the command, capture the pane, assert the observable.
+   Each path yields `{ id, status: pass|fail|blocked, evidence, note }`. A path you cannot reach is `blocked` — **never silently skipped or passed**.
+3. **Compute the verdict** (the *same* `--profile` the run used):
+```bash
+node <smoke>/scripts/smoke.mjs verdict --manifest smoke.manifest.json --profile <name> --target <url> \
+  --results smoke-results.json --out smoke-verdict.json
+```
+**ALIVE** iff every selected path PASSED. Any `fail`, `blocked`, or `missing` → **DEAD**, naming the path(s). Exit code is the gate (0 = ALIVE, 1 = DEAD). Selection is a pure function of `--profile` + the manifest, so the run and the verdict select the **same** set by construction — there is no second flag assembly for the verdict to disagree with, which is the whole point: the run/verdict mismatch that free-form targeting permitted is now unrepresentable.
+
+`smoke-verdict.json` is stamped with the facts an automated consumer needs to judge the evidence rather than trust it: **`profile`** (the Validation Profile it selected under), **`target`** (which URL it ran against), **`noMutations`** (DERIVED from the profile's `mutationPolicy` — `true` for the read-only production profiles), and **`generatedAt`** (an ISO-8601 instant — *when*, so a consumer can bound how old the evidence is). `resolve-release`'s traffic-shift gate compares these; an ALIVE from the wrong target, a mutating run, or too long ago is not a green light.
+
+**`generatedAt` dates the verdict, not the run.** `verdict` reduces whatever `--results` file you hand it, however old, and stamps the current instant on the result — so re-running `verdict` alone re-mints freshness without re-validating anything, and a consumer bounding the age cannot tell the difference. That is not a substitute for a stale gate's re-check: when what expired is the *evidence about a live target*, re-drive the paths into a new `smoke-results.json` — re-minting a verdict is not re-validation.
+
+## Report (the `/verify` shape, gate-flavored)
+
+Lead with the verdict, then the per-path steps and findings:
+
+```
+## Smoke: <target>
+**Verdict:** ALIVE | DEAD
+**Target:** local (booted <how>) | <url> (revision <sha>)
+**Paths:** <n passed>/<n run>  (<excluded count> excluded: <why>)
+### Paths
+1. ✅/❌/⚠️/🔍 <path id> — <what you drove> → <what you observed>
+   <evidence: screenshot / response body / pane capture>
+### Findings
+<anything that made you pause — friction, surprise, a near-miss — even on an ALIVE run>
+```
+
+Findings matter even when ALIVE — you're the only check that actually *ran the integrated thing*. A DEAD verdict hands the broken path's evidence to the caller (the epic gate reopens the owning unit; in the release lane the response depends on whether users were ever exposed — before the traffic shift it discards the candidate, after it triggers the rollback policy, both routing to `app-debug`/`diagnose`).
+
+## Where this fits (the callers)
+
+The **per-PR golden-path liveness floor** (`ensure-coverage` CI contract, gate 8) — enforced at every lane:
+
+- **`implement-and-pr` (step 6)** — before opening the PR, boot what you built (`--target local`) and run the golden paths the change touches; a DEAD blocks readiness. New critical flow → it owes a manifest entry.
+- **`review-pr`** — a Review-Contract row: the manifest covers the change's golden path (a new critical flow with no entry is a finding), and the attached `smoke-results.json` + `smoke-verdict.json` are ALIVE against HEAD. A smoke you cannot *run* — no build, no target, missing credential — leaves the row `BLOCKED`, never a finding against the diff ([review-pr](../review-pr/SKILL.md) § Verdicts and the blocking bar); an inability to verify is not evidence the golden path is broken.
+- **CI (gate 8, blocking)** — wired in `e2e-test/assets/ci-gates.*`; boots the app, drives the paths into `smoke-results.json`, runs `smoke.mjs verdict`. The mechanical backstop.
+- **`resolve-issues`** — final step of the [epic integration gate](../resolve-issues/references/deliverables.md#deliverables-the-shippable-component-not-the-whole-epic): boot the assembled integration branch and run the golden paths; a DEAD whose broken paths are `fail` belongs to a specific unit → reopen its fix loop. **A DEAD built from `blocked`/`missing` paths is a gate-environment problem, not a unit's defect** — report it and fix the environment; reopening a fix loop on it spends a producer spawn and an adversarial review on code that is fine, and the round lands in the unit's budget all the same.
+- **`/smoke`** — standalone, any time, against `local` or a URL.
+- **`resolve-release`** — [the exposure gate](../resolve-release/SKILL.md#the-release-loop): the `prod-preview` profile against the 0%-traffic candidate URL (read-only, so it excludes every mutating path), then the `prod-active` profile against the live service after the shift. A DEAD **before** exposure deletes the candidate (no rollback, no user impact); a DEAD after it triggers the rollback policy.
+- **The dev-deploy recorder** (`cloud-build` → Post-deploy smoke gate) — the integration pipeline runs this gate after its 100%-traffic deploy and publishes the verdict as a **SHA-keyed commit status**, never failing the build; that recorded ALIVE is what `resolve-release` requires when pinning a release candidate (its principle 11).
+
+## Reference Map
+
+| When you need to… | Read |
+|---|---|
+| author/validate the manifest (fields, surface→driver, what earns a slot, candidate sources) | [references/manifest.md](references/manifest.md) |
+| a starting manifest to adapt | [assets/smoke.manifest.example.json](assets/smoke.manifest.example.json) |
+| the runtime-observation discipline this borrows | the built-in `/verify` skill |
+| drive a browser path / the Playwright runner + render-health | `e2e-test` → [presentation-sweep.md](../e2e-test/references/presentation-sweep.md) |
+| boot a local build to drive | the `run` skill |
+
+## Scripts
+
+- `scripts/smoke.mjs` — the gate shell: `suggest` (inventory → non-runnable candidates), `validate` (manifest shape + the `profiles` registry + `--journeys` reconciliation of browser paths against the `@smoke` tags, both drift directions), `plan` (profile-based selection + exclusions), `verdict` (reduce results → ALIVE/DEAD, exit code = gate). Pure core (`validateManifest`/`validateProfile`/`selectPathsForProfile`/`computeVerdict`/`suggestCandidates`/`reconcileJourneys`/`journeyCoversId`) is unit-tested in `scripts/smoke.test.mjs`; the driving itself is runtime observation (Playwright / request / pane capture), not this script.

package/skills/engineering/smoke/assets/smoke.manifest.example.json

@@ -0,0 +1,53 @@
+{
+  "_comment": "EXAMPLE ONLY — these paths are specific to one consumer auth product. They are NOT a universal template: a payments app's golden paths are checkout/pay/receipt, a docs app's are create/edit/share. Author your own per-app set whose failure means 'do not ship', then DELETE this example. There is no fixed number of paths. See references/manifest.md.",
+  "profiles": {
+    "pr-local":     { "gate": "pull-request",      "environment": "local", "endpoint": "local",   "prerequisites": ["boot", "seed", "auth-bypass"], "evidencePolicy": "per-PR screens attached to the PR", "mutationPolicy": "isolated-writes" },
+    "queue-local":  { "gate": "merge-queue",       "environment": "local", "endpoint": "local",   "prerequisites": ["boot", "seed", "auth-bypass"], "evidencePolicy": "batch-gate screens",               "mutationPolicy": "isolated-writes" },
+    "dev-active":   { "gate": "trunk-integration", "environment": "dev",   "endpoint": "active",  "prerequisites": ["deployed-revision", "synthetic-tenant-cleanup"], "evidencePolicy": "SHA-keyed recorder verdict", "mutationPolicy": "synthetic-tenant" },
+    "prod-preview": { "gate": "pre-promotion",     "environment": "prod",  "endpoint": "preview", "prerequisites": ["candidate-revision-at-0pct"], "evidencePolicy": "attested identity tuple + smoke-verdict.json", "mutationPolicy": "read-only" },
+    "prod-active":  { "gate": "post-promotion",    "environment": "prod",  "endpoint": "active",  "prerequisites": ["live-service-at-100pct"],     "evidencePolicy": "attested identity tuple + smoke-verdict.json", "mutationPolicy": "read-only" }
+  },
+  "setup": {
+    "boot": "use the run skill (else: pnpm --filter app dev)",
+    "env": ["DATABASE_URL", "AUTH_SECRET", "FEISHU_APP_ID"],
+    "authBypass": "E2E_AUTH_BYPASS=1 (see e2e-test global-setup)",
+    "seed": "pnpm seed:smoke",
+    "fixtures": "reuse e2e-test's Playwright fixtures — do not recreate auth here",
+    "tenants": ["e2e-synthetic"]
+  },
+  "paths": [
+    {
+      "id": "login-to-dashboard",
+      "surface": "browser",
+      "journey": "@smoke login-to-dashboard",
+      "intent": "org-entry → credential card → dashboard heading visible; primary button non-transparent; no console errors (the referenced journey asserts this)",
+      "mutates": false,
+      "profiles": ["pr-local", "queue-local", "dev-active", "prod-preview", "prod-active"]
+    },
+    {
+      "id": "sso-qr-mount",
+      "surface": "browser",
+      "journey": "@smoke sso-qr-mount",
+      "intent": "SSO QR panel mounts (real component, CDN SDK stubbed at the boundary); switching to password does not crash",
+      "mutates": false,
+      "profiles": ["pr-local", "queue-local", "dev-active", "prod-preview", "prod-active"]
+    },
+    {
+      "id": "signup-verify-otp",
+      "surface": "browser",
+      "journey": "@smoke signup-verify-otp",
+      "intent": "sign up → OTP (email boundary faked) → lands authenticated on the dashboard",
+      "mutates": true,
+      "tenant": "e2e-synthetic",
+      "profiles": ["pr-local", "queue-local", "dev-active"]
+    },
+    {
+      "id": "health",
+      "surface": "api",
+      "start": "GET /healthz",
+      "observable": "200 with body { status: \"ok\" }",
+      "mutates": false,
+      "profiles": ["pr-local", "queue-local", "dev-active", "prod-preview", "prod-active"]
+    }
+  ]
+}