@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/scripts/adapters/nextjs-inventory.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// REFERENCE Next.js App Router discovery adapter — copy and adapt per repo.
+// Emits a surface inventory satisfying references/breadth/inventory-contract.md.
+//
+//   node nextjs-inventory.mjs <appDir> [--out docs/tests/_generated/surface-inventory.json] [--check]
+//
+// Routes come from `page.*` files; APIs from `route.*` files. Route groups
+// `(group)` are stripped; dynamic segments `[id]`/`[...slug]` are kept as-is so
+// ids are stable.
+//
+// It also emits the MECHANICAL taxonomy the Surface Baseline Contract needs:
+//   - class: route -> read | detail | mutation; api -> read | mutation
+//   - reachability: best-effort reachable | guarded (from the layout/middleware chain)
+// These are deliberately conservative heuristics: the adapter may only emit the
+// mechanical class (never `sensitive`/exclusion — those are human-declared). When
+// in doubt about a write surface it biases to `mutation`, because under-calling a
+// write form `read` would wrongly let it be excluded. Reachability here is a hint;
+// the full Route Reachability Protocol (and human review) refine `blocked`/
+// `unreachable`. It does NOT cover DB tables or events — extend for those kinds.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+const IGNORE = new Set(['node_modules', '.git', '.next'])
+const PAGE_RE = /^page\.(tsx|ts|jsx|js|mdx)$/
+const ROUTE_RE = /^route\.(ts|js)$/
+const LAYOUT_RE = /^layout\.(tsx|ts|jsx|js)$/
+const COMPONENT_RE = /\.(tsx|ts|jsx|js|mdx)$/
+
+// A page (or a component colocated in its route segment) that mutates state.
+const WRITE_RE = /<form\b|onSubmit|action=\{|formAction|use(FormState|ActionState|Mutation)\b|type=["']submit["']|method:\s*["'](post|put|patch|delete)["']|fetch\([^)]*method\s*:\s*["'](post|put|patch|delete)|['"]use server['"]/i
+// An API route file exporting a write method.
+const METHOD_EXPORT_RE = /export\s+(?:async\s+function|const|let|var|function)\s+(POST|PUT|PATCH|DELETE)\b|export\s*\{[^}]*\b(POST|PUT|PATCH|DELETE)\b/
+// Guard signals in a layout / middleware that gate reachability.
+const GUARD_RE = /\bredirect\(|\bnotFound\(|getServerSession|\bauth\(\)|requireAuth|getToken|currentUser|\bunauthorized\(|clerkMiddleware|withAuth/i
+
+function* walk(dir) {
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+  for (const e of entries) {
+    const full = path.join(dir, e.name)
+    if (e.isDirectory()) { if (!IGNORE.has(e.name)) yield* walk(full) }
+    else yield full
+  }
+}
+
+function read(file) { try { return fs.readFileSync(file, 'utf8') } catch { return '' } }
+
+function toRoute(appDir, file) {
+  const rel = path.relative(appDir, path.dirname(file)).split(path.sep)
+    .filter((seg) => seg && !(seg.startsWith('(') && seg.endsWith(')'))) // drop route groups
+    .filter((seg) => !seg.startsWith('@')) // drop parallel route slots
+    .join('/')
+  return '/' + rel
+}
+
+// Mechanical class for a page: mutation > detail > read.
+function routeClass(pageFile) {
+  const dir = path.dirname(pageFile)
+  let text = ''
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isFile() || !COMPONENT_RE.test(e.name)) continue
+    if (LAYOUT_RE.test(e.name) || ROUTE_RE.test(e.name)) continue
+    text += read(path.join(dir, e.name)) + '\n'
+  }
+  if (WRITE_RE.test(text)) return 'mutation'
+  if (/\[[^\]]+\]/.test(dir)) return 'detail' // dynamic segment -> renders one entity
+  return 'read'
+}
+
+// Mechanical class for an API route: mutation if it exports a write method.
+function apiClass(routeFile) {
+  return METHOD_EXPORT_RE.test(read(routeFile)) ? 'mutation' : 'read'
+}
+
+// Best-effort reachability from the layout chain + root middleware.
+function reachability(appDir, pageFile, hasMiddleware) {
+  if (hasMiddleware) return 'guarded'
+  let dir = path.dirname(pageFile)
+  const stop = path.resolve(appDir)
+  while (true) {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isFile() && LAYOUT_RE.test(e.name) && GUARD_RE.test(read(path.join(dir, e.name)))) return 'guarded'
+    }
+    if (path.resolve(dir) === stop) break
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return 'reachable'
+}
+
+function detectMiddleware(appDir) {
+  const parent = path.dirname(appDir)
+  for (const base of [appDir, parent]) {
+    for (const m of ['middleware.ts', 'middleware.js']) {
+      if (fs.existsSync(path.join(base, m))) return true
+    }
+  }
+  return false
+}
+
+// Feature-derived presentation signals (Dimension B escalation). Detected
+// deterministically at the app level and attached to every route, so the ledger
+// raises the presentation floor (dark-theme cell, RTL/long-locale cells). This is
+// the reference granularity; a stack can refine to per-route detection.
+//   - themeToggle: a `next-themes` dep or a useTheme/ThemeProvider reference
+//   - i18n: a known i18n library dependency
+function detectSignals(appDir) {
+  const roots = [appDir, path.dirname(appDir)]
+  let pkg = {}
+  for (const base of roots) {
+    const p = path.join(base, 'package.json')
+    if (fs.existsSync(p)) { try { pkg = JSON.parse(fs.readFileSync(p, 'utf8')) } catch { /* ignore */ } break }
+  }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }
+  const dep = (re) => Object.keys(deps).some((d) => re.test(d))
+  const I18N_DEP = /^(next-intl|next-i18next|react-i18next|i18next|@lingui|react-intl|@formatjs)/
+  const THEME_DEP = /^(next-themes)$/
+  // a cheap source grep for theme toggling when there's no dedicated dep
+  let themeInSource = false
+  for (const f of walk(appDir)) {
+    if (!COMPONENT_RE.test(f)) continue
+    if (/\buseTheme\b|<ThemeProvider\b|data-theme=/.test(fs.readFileSync(f, 'utf8'))) { themeInSource = true; break }
+  }
+  const signals = {}
+  if (dep(THEME_DEP) || themeInSource) signals.themeToggle = true
+  if (dep(I18N_DEP)) signals.i18n = true
+  return Object.keys(signals).length ? signals : null
+}
+
+function build(appDir) {
+  const hasMiddleware = detectMiddleware(appDir)
+  const signals = detectSignals(appDir)
+  const surfaces = []
+  for (const f of walk(appDir)) {
+    const base = path.basename(f)
+    if (PAGE_RE.test(base)) {
+      const s = { id: toRoute(appDir, f), kind: 'route', class: routeClass(f), reachability: reachability(appDir, f, hasMiddleware) }
+      if (signals) s.signals = signals
+      surfaces.push(s)
+    } else if (ROUTE_RE.test(base)) {
+      surfaces.push({ id: toRoute(appDir, f), kind: 'api', class: apiClass(f) })
+    }
+  }
+  // de-dupe by id (e.g. page + nested layout edge cases), keep strongest class.
+  const byId = new Map()
+  const rank = { mutation: 3, detail: 2, read: 1, undefined: 0 }
+  for (const s of surfaces) {
+    const prev = byId.get(s.id)
+    if (!prev || (rank[s.class] || 0) > (rank[prev.class] || 0)) byId.set(s.id, s)
+  }
+  return { surfaces: [...byId.values()].sort((a, b) => a.id.localeCompare(b.id)) }
+}
+
+function main() {
+  const [, , appDir, ...rest] = process.argv
+  if (!appDir) { console.error('usage: nextjs-inventory.mjs <appDir> [--out file] [--check]'); process.exit(2) }
+  let out = 'docs/tests/_generated/surface-inventory.json'
+  let check = false
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--out') out = rest[++i]
+    else if (rest[i] === '--check') check = true
+  }
+  const inv = build(appDir)
+  const json = JSON.stringify(inv, null, 2) + '\n'
+  if (check) {
+    const prev = fs.existsSync(out) ? fs.readFileSync(out, 'utf8') : ''
+    if (prev !== json) { console.error(`inventory stale: ${out} does not match discovered surfaces. Re-run without --check.`); process.exit(1) }
+    console.log(`inventory up to date (${inv.surfaces.length} surfaces)`); return
+  }
+  fs.mkdirSync(path.dirname(out), { recursive: true })
+  fs.writeFileSync(out, json)
+  console.log(`wrote ${out} (${inv.surfaces.length} surfaces)`)
+}
+
+main()

package/skills/engineering/ensure-coverage/scripts/check-quarantine-expiry.mjs

@@ -0,0 +1,101 @@
+// check-quarantine-expiry — the auto-resurface gate for dated exits.
+//
+// A quarantine (or any deferred-but-tracked suppression) is a holding pen with a
+// dated exit, never a destination. The convention is a single marker, anywhere in
+// a file (a test-file comment, a suppressions list, an ADR):
+//
+//   @quarantine(until=2026-07-01, issue=#123)     // canonical
+//   until=2026-07-01                               // also matched (bare)
+//   until: 2026-07-01                              // also matched (yaml-style)
+//
+// Until the date, the item is allowed to sit non-blocking. On/after the date it
+// EXPIRES: this gate fails, so the item re-blocks until it is fixed or the date is
+// extended with a stated reason. Run it in the BLOCKING lane.
+//
+//   node check-quarantine-expiry.mjs --files a,b      # specific files
+//   node check-quarantine-expiry.mjs                  # whole-tree scan of test files
+//   node check-quarantine-expiry.mjs --now 2026-06-08 # pin "today" (default: system date; for tests/CI determinism)
+//   --json                                            # machine output
+//
+// Exit 0 = no expired exits. Exit 1 = at least one expired (the gate blocks).
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// Marker forms: `until=YYYY-MM-DD` or `until: YYYY-MM-DD` (case-insensitive key).
+const UNTIL = /\buntil\s*[:=]\s*(\d{4}-\d{2}-\d{2})\b/gi
+// Pull an issue ref from the same line when present, for the report.
+const ISSUE = /\bissue\s*[:=]\s*(#?\w[\w/-]*)/i
+
+export function isTestFile(p) {
+  return /\.(test|spec)\.[jt]sx?$/.test(p) || /(^|\/)tests?\//.test(p) || /\.coverage\.ya?ml$/.test(p)
+}
+
+// Pure: scan one file's text → expired/pending records against `now` (YYYY-MM-DD).
+export function scanText(file, text, now) {
+  const out = []
+  const lines = (text || '').split(/\r?\n/)
+  lines.forEach((raw, i) => {
+    for (const m of raw.matchAll(UNTIL)) {
+      const until = m[1]
+      const issue = (raw.match(ISSUE) || [])[1] || null
+      out.push({ file, line: i + 1, until, issue, expired: until < now, snippet: raw.trim().slice(0, 120) })
+    }
+  })
+  return out
+}
+
+function discover(dir, acc = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name.startsWith('.git')) continue
+    const full = path.join(dir, e.name)
+    if (e.isDirectory()) discover(full, acc)
+    else if (isTestFile(full)) acc.push(full)
+  }
+  return acc
+}
+
+function today() {
+  // Standalone CI tool — reading the wall clock is correct here (unlike workflow scripts).
+  return new Date().toISOString().slice(0, 10)
+}
+
+export function runCli(argv, { name = 'check-quarantine-expiry' } = {}) {
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') flags.json = true
+    else if (a === '--now') flags.now = argv[++i]
+    else if (a === '--files') flags.files = argv[++i]
+  }
+  const now = flags.now || today()
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(now)) {
+    console.error(`${name}: --now must be YYYY-MM-DD, got "${now}"`)
+    return 2
+  }
+
+  const files = flags.files
+    ? flags.files.split(',').map((s) => s.trim()).filter(Boolean)
+    : discover(process.cwd())
+
+  const records = []
+  for (const f of files) {
+    if (fs.existsSync(f)) records.push(...scanText(f, fs.readFileSync(f, 'utf8'), now))
+  }
+  const expired = records.filter((r) => r.expired)
+
+  if (flags.json) {
+    console.log(JSON.stringify({ now, total: records.length, expired }, null, 2))
+  } else {
+    if (!records.length) console.log(`${name}: no dated exits found.`)
+    else if (!expired.length) console.log(`${name}: ${records.length} dated exit(s), none expired (as of ${now}).`)
+    else {
+      console.log(`${name}: ${expired.length} EXPIRED dated exit(s) (as of ${now}) — fix, or extend the date with a reason:`)
+      for (const r of expired) console.log(`  ${r.file}:${r.line}  until=${r.until}${r.issue ? ` (${r.issue})` : ''}  ${r.snippet}`)
+    }
+  }
+  return expired.length ? 1 : 0
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2)))

package/skills/engineering/ensure-coverage/scripts/ci-audit.mjs

@@ -0,0 +1,358 @@
+// CI audit — the meta-gate. Verifies a repo's CI config actually WIRES the gates
+// in references/enforcement/ci-contract.md and keeps them BLOCKING. The gates catch bugs; this catches the
+// gates being deleted, never added, or quietly turned to warn-only.
+//
+//   node ci-audit.mjs [--files a.yml,b.yaml] [--allow-warn] [--json]   # audit: gate on wired-and-blocking
+//   node ci-audit.mjs --adoption [--files …] [--json]                  # bridge: emit a wiring issue/plan for
+//                                                                      #   a pre-existing CI that lacks the gates
+//
+// Static + best-effort by design: CI configs are heterogeneous, so this is a
+// BENCHMARK that abstains rather than a parser. `absent` and `warn-only` fail the
+// audit; a gate present under an unrecognized command reads as `absent` → a
+// reviewer confirms (false-negative-safe: it never green-lights a missing gate it
+// couldn't see, it flags for a human). Treat the output as leads, not gospel.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// Each gate is "present" if ANY pattern matches a config line. Signatures are the
+// reference commands; extend per-repo if you wrap them under different names.
+export const GATES = [
+  { key: 'inventory', label: 'Gate 1 — inventory freshness', patterns: [/detect-routes/, /gen-inventory/, /surface-inventory/] },
+  { key: 'accounting', label: 'Gate 2 — accounting (ledger validate)', patterns: [/coverage-ledger(\.mjs)?\b[^\n]*\bvalidate\b/] },
+  { key: 'sweep', label: 'Gate 3 — presentation render sweep', patterns: [/presentation-sweep/] },
+  { key: 'e2e', label: 'Gate 4 — functional + journey E2E (integration/nightly lane, not per-PR)', patterns: [/playwright\s+test/, /\btest:e2e\b/, /\brun\s+e2e\b/] },
+  { key: 'mock-seam', label: 'Gate 5 — no over-mock (mock-internal-seam, depth axis)', patterns: [/mock-internal-seam/] },
+  { key: 'checklist', label: 'Gate 6 — Review-Contract checklist validate', patterns: [/coverage-checklist(\.mjs)?\b[^\n]*\bvalidate\b/] },
+  // Newer than the rest: an already-wired repo will report this one absent on its next
+  // audit. That is the adoption path working, not a regression — phase it in with
+  // --allow-warn while the job is added, rather than treating the red as noise.
+  { key: 'evidence-block', label: 'Gate 6b — Review-Contract evidence-block freshness (stamp = HEAD)', patterns: [/evidence-block(\.mjs)?\b[^\n]*\bvalidate\b/] },
+  { key: 'quarantine-expiry', label: 'Gate 7 — quarantine auto-resurface (dated-exit expiry)', patterns: [/check-quarantine-expiry/] },
+  { key: 'smoke', label: 'Gate 8 — curated E2E smoke (golden-path liveness, per-PR floor)', patterns: [/smoke(\.mjs)?\b[^\n]*\bverdict\b/, /smoke-gate/] },
+]
+
+// Markers that turn a blocking gate into theatre. Proximity-scoped to a gate hit so
+// an unrelated `continue-on-error` elsewhere in a big workflow doesn't false-flag.
+export const WEAKEN = [
+  /continue-on-error:\s*true/i,
+  /allowFailure:\s*true/i,
+  /\|\|\s*true\b/,
+  /--warn-only\b/,
+  /--no-strict\b/,
+  /set\s+\+e\b/,
+]
+
+// The meta-gate (gate 0 / bootstrap): is ci-audit ITSELF run by the CI? Without
+// this, nothing catches a gate being deleted or weakened later — the audit only
+// guards the gates if someone runs it. A repo that wires gates but not this can
+// silently lose them. Advisory in normal audit mode; a required step in adoption.
+export const META_GATE = { key: 'meta', label: 'Meta-gate — ci-audit self-check (guards the gates against rot)', patterns: [/ci-audit(\.mjs)?\b/] }
+
+// CI wiring conventions — audited alongside the gates, platform-scoped (a Cloud
+// Build build needs no umbrella job: its single build status IS the one check).
+// `required: true` conventions fail the audit when absent on an applicable platform;
+// `required: false` are PREFERRED — reported as advisory, never failing `ok`
+// (docker-preferred has a sanctioned plain-runner alternative, so it can't hard-fail).
+// Presence-only classification: no weaken-proximity logic (a `timeout-minutes` on the
+// non-blocking quarantine job must not read as weakened).
+export const CONVENTIONS = [
+  {
+    key: 'umbrella',
+    label: 'Umbrella job (all-gates) — branch protection requires exactly ONE check',
+    required: true,
+    platforms: ['github'],
+    patterns: [/^\s*all-gates\s*:/],
+  },
+  {
+    key: 'time-budget',
+    label: 'Time budget — PR-lane jobs carry an explicit timeout (target ≤5 min)',
+    required: true,
+    platforms: ['github', 'cloudbuild'],
+    patterns: [/timeout-minutes:\s*\d+/, /^\s*timeout:\s*['"]?\d+(\.\d+)?s['"]?/],
+  },
+  {
+    key: 'playwright-container',
+    label: 'Docker-preferred — browser jobs run in the pinned official Playwright container',
+    required: false,
+    platforms: ['github', 'cloudbuild'],
+    patterns: [/mcr\.microsoft\.com\/playwright:v?\d+\.\d+/],
+  },
+]
+
+// Pure: classify one convention. Presence-only (no warn-only state): a convention is
+// `present`, `absent`, or `n/a` when the scanned platform is out of its scope.
+export function classifyConvention(corpus, conv, platform) {
+  if (!conv.platforms.includes(platform)) {
+    return { status: 'n/a', evidence: `not applicable to ${platform || 'unknown'} configs` }
+  }
+  for (const file of corpus) {
+    for (let i = 0; i < file.lines.length; i++) {
+      if (conv.patterns.some((p) => p.test(stripComment(file.lines[i])))) {
+        return { status: 'present', evidence: `${file.name}:${i + 1}` }
+      }
+    }
+  }
+  return { status: 'absent', evidence: 'no matching config found in scanned CI config' }
+}
+
+// Visual regression (`presentation:visual`) is the one OPT-IN presentation level —
+// required only when a surface declares it, which CI config alone can't tell us
+// (it lives in coverage.yml, not the workflow). So this is ADVISORY, never part of
+// `ok`: we report whether a `visual-gate` job is wired, but a repo with no opted-in
+// surface legitimately has none. A repo that DOES opt in but lacks the job has a
+// real gap a reviewer must catch — the advisory line is the prompt to check.
+export const VISUAL_GATE = { key: 'visual', label: 'Visual regression (presentation:visual) — advisory, required only when surfaces opt in', patterns: [/visual-gate/, /presentation-visual/] }
+
+// Strip a `#` comment so doc/warning text ("NEVER add continue-on-error: true")
+// is not mistaken for a real gate command or a real weakening. Best-effort: ignores
+// `#` inside quotes (acceptable for a benchmark). A real `run: x || true` has no `#`
+// and is still detected.
+export function stripComment(line) {
+  return line.replace(/(^|\s)#.*$/, '$1')
+}
+
+// A line that runs the quarantine selection (`--grep @quarantine`, not the
+// `--grep-invert` exclusion the blocking gate uses).
+const QUARANTINE_RUN = /--grep(?!-invert)[\s=]+["']?@?quarantine/i
+
+// The quarantine *lane's* job/step HEADER (`quarantine:` GH job key, or `- id:
+// quarantine` Cloud Build step). The lane's weaken marker is JOB-LEVEL
+// (`continue-on-error: true` / `allowFailure: true`) and so sits a few lines BELOW
+// this header but can be ~10 lines ABOVE the `--grep @quarantine` run — too far for
+// the run-anchored check below. Anchored on a `quarantine` job/step identifier
+// specifically (line-start, not any mention), so gate 7 (`check-quarantine-expiry`),
+// whose name merely contains the substring, is never mistaken for the lane.
+const QUARANTINE_LANE = /^\s*(?:quarantine\s*:|-\s*id:\s*quarantine\b)/i
+
+// Is line j within a few lines of the quarantine *lane* (i.e. a weaken marker that
+// belongs to the non-blocking quarantine job, not to the real gate near it)? Anchored
+// on either the lane's `--grep @quarantine` run or its job/step header — NOT any line
+// mentioning "quarantine" — so the blocking `check-quarantine-expiry` gate (gate 7)
+// can never be mistaken for the lane and can never mask a real weakening on a gate
+// wired next to it.
+function nearQuarantine(lines, j, w = 3) {
+  const lo = Math.max(0, j - w)
+  const hi = Math.min(lines.length - 1, j + w)
+  for (let k = lo; k <= hi; k++) if (QUARANTINE_RUN.test(lines[k]) || QUARANTINE_LANE.test(lines[k])) return true
+  return false
+}
+
+// Pure: classify one gate against the corpus. corpus: [{ name, lines:[string] }].
+// Matching runs against comment-stripped code so a command/marker only counts when
+// it is actually wired, not when it is mentioned in a comment.
+export function classifyGate(corpus, gate, { proximity = 10 } = {}) {
+  const hits = []
+  for (const file of corpus) {
+    file.lines.forEach((line, i) => {
+      const code = stripComment(line)
+      // The quarantine lane re-runs a gate command non-blocking (`playwright test
+      // --grep @quarantine`); that line is NOT the blocking gate. But the blocking
+      // gate's `--grep-invert @quarantine` (excluding quarantine) IS the gate — keep it.
+      if (QUARANTINE_RUN.test(code)) return
+      if (gate.patterns.some((p) => p.test(code))) hits.push({ file, i })
+    })
+  }
+  if (hits.length === 0) return { status: 'absent', evidence: 'no matching command found in scanned CI config' }
+  for (const h of hits) {
+    const lo = Math.max(0, h.i - proximity)
+    const hi = Math.min(h.file.lines.length - 1, h.i + proximity)
+    for (let j = lo; j <= hi; j++) {
+      if (WEAKEN.some((w) => w.test(stripComment(h.file.lines[j])))) {
+        // A weaken marker belonging to the (by-design non-blocking) quarantine lane
+        // must not weaken a real gate hit that happens to sit near it.
+        if (nearQuarantine(h.file.lines, j)) continue
+        return { status: 'warn-only', evidence: `${h.file.name}:${h.i + 1} (weakened near ${h.file.name}:${j + 1})` }
+      }
+    }
+  }
+  return { status: 'present', evidence: `${hits[0].file.name}:${hits[0].i + 1}` }
+}
+
+// Pure: is ci-audit itself referenced anywhere in the corpus (the bootstrap check)?
+export function selfAuditWired(corpus) {
+  for (const file of corpus) {
+    for (let i = 0; i < file.lines.length; i++) {
+      if (META_GATE.patterns.some((p) => p.test(stripComment(file.lines[i])))) {
+        return { wired: true, evidence: `${file.name}:${i + 1}` }
+      }
+    }
+  }
+  return { wired: false, evidence: 'ci-audit is not run by any scanned CI config' }
+}
+
+// Pure: audit the whole corpus. ok = every required gate present (warn-only fails
+// unless allowWarn). absent/warn-only are findings.
+export function auditCorpus(files, opts = {}) {
+  const corpus = files.map((f) => ({ name: f.name, lines: (f.text || '').split(/\r?\n/) }))
+  const gates = GATES.map((g) => ({ key: g.key, label: g.label, ...classifyGate(corpus, g, opts) }))
+  const metaGate = selfAuditWired(corpus)
+  // Advisory: report whether the opt-in visual gate is wired, but keep it OUT of `ok`
+  // (a repo with no opted-in surface correctly has no job — see VISUAL_GATE).
+  const visualGate = { key: VISUAL_GATE.key, label: VISUAL_GATE.label, ...classifyGate(corpus, VISUAL_GATE, opts) }
+  // Conventions are platform-scoped; on an unrecognized platform they all read n/a.
+  // Note this is an ABSTAIN, not a pass the audit vouches for — we don't guess
+  // github/cloudbuild conventions for a CI we can't identify; a reviewer owns n/a.
+  const platform = detectPlatform(files.map((f) => f.name))
+  const conventions = CONVENTIONS.map((c) => ({ key: c.key, label: c.label, required: c.required, ...classifyConvention(corpus, c, platform) }))
+  // `ok` = the required content gates + the required conventions. The meta-gate,
+  // visual gate, and preferred (required:false) conventions stay advisory here;
+  // adoption mode makes the meta-gate a required step.
+  const gatesOk = gates.every((g) => g.status === 'present' || (opts.allowWarn && g.status === 'warn-only'))
+  const conventionsOk = conventions.every((c) => !c.required || c.status !== 'absent')
+  const ok = gatesOk && conventionsOk
+  return { gates, conventions, platform, metaGate, visualGate, ok, scanned: files.map((f) => f.name) }
+}
+
+// ---- Adoption: turn a gap into one reviewable PR ----
+//
+// A skill can't enforce against a pre-existing pipeline — the gates must be wired
+// in. This closes the gap: given a repo's CI, report which gates are absent/weak,
+// pick the matching template, and emit a checklist scoped to ONLY the gaps (it
+// never asks you to re-wire a gate you already have), including the bootstrap step.
+
+const TEMPLATE = {
+  github: 'e2e-test/assets/ci-gates.github.yml',
+  cloudbuild: 'e2e-test/assets/ci-gates.cloudbuild.yaml',
+  unknown: null,
+}
+
+// Pure: which template applies, inferred from the scanned paths.
+export function detectPlatform(scanned = []) {
+  if (scanned.some((p) => /\.github[/\\]workflows[/\\]/.test(p))) return 'github'
+  if (scanned.some((p) => /cloudbuild/i.test(p))) return 'cloudbuild'
+  return 'unknown'
+}
+
+// Pure: the adoption plan. `toWire` = gates needing work (absent or warn-only);
+// `ok` = gates already present (no action). `needed` is true if anything is left
+// to wire OR the meta-gate isn't wired (the bootstrap).
+export function buildAdoptionPlan(report, { platform } = {}) {
+  const plat = platform || detectPlatform(report.scanned || [])
+  const toWire = report.gates.filter((g) => g.status !== 'present')
+  const okGates = report.gates.filter((g) => g.status === 'present')
+  const metaWired = report.metaGate?.wired === true
+  // Required conventions that are absent on an applicable platform are part of the
+  // gap; preferred (required:false) ones are surfaced as recommendations only.
+  const conventionsToWire = (report.conventions || []).filter((c) => c.required && c.status === 'absent')
+  const conventionsPreferred = (report.conventions || []).filter((c) => !c.required && c.status === 'absent')
+  return {
+    needed: toWire.length > 0 || conventionsToWire.length > 0 || !metaWired,
+    platform: plat,
+    templatePath: TEMPLATE[plat] ?? null,
+    toWire,
+    conventionsToWire,
+    conventionsPreferred,
+    ok: okGates.map((g) => ({ key: g.key, label: g.label })),
+    metaGate: report.metaGate,
+    scanned: report.scanned || [],
+  }
+}
+
+// Pure: render the plan as a ready-to-file issue body (gh issue create --body-file -).
+export function renderAdoptionIssue(plan) {
+  const mark = (s) => (s === 'present' ? '✓' : s === 'warn-only' ? '⚠' : '✗')
+  const L = []
+  L.push('## Wire coverage gates into CI (ensure-coverage CI contract)')
+  L.push('')
+  L.push('CI does not fully enforce the coverage gate contract (ensure-coverage → `references/enforcement/ci-contract.md`). Until every gate is wired **and blocking**, a route can ship broken with green CI. Close the gap in one PR.')
+  L.push('')
+  L.push(`Scanned: ${plan.scanned.length ? plan.scanned.map((s) => '`' + s + '`').join(', ') : '_no CI config found_'}`)
+  L.push('')
+  L.push('### Gap (from `ci-audit`)')
+  for (const g of plan.toWire) L.push(`- ${mark(g.status)} **${g.label}**: ${g.status} (${g.evidence})`)
+  for (const g of plan.ok) L.push(`- ✓ ${g.label}: present — no action`)
+  L.push(`- ${plan.metaGate?.wired ? '✓' : '✗'} ${META_GATE.label}: ${plan.metaGate?.wired ? `wired (${plan.metaGate.evidence})` : 'not wired'}`)
+  L.push('')
+  L.push('### Close it (one PR)')
+  L.push(plan.templatePath
+    ? `Platform detected: **${plan.platform}** → copy template \`${plan.templatePath}\`.`
+    : 'Platform not detected — pick the template matching your CI: `e2e-test/assets/ci-gates.github.yml` or `ci-gates.cloudbuild.yaml`.')
+  L.push('')
+  let n = 1
+  if (plan.templatePath) L.push(`${n++}. [ ] Copy \`${plan.templatePath}\` into your CI config.`)
+  for (const g of plan.toWire) {
+    L.push(g.status === 'warn-only'
+      ? `${n++}. [ ] Make **${g.label}** blocking — remove the weakening near \`${g.evidence}\` (\`continue-on-error\` / \`|| true\` / \`--warn-only\` / \`--no-strict\`).`
+      : `${n++}. [ ] Wire **${g.label}** as its own blocking job.`)
+  }
+  for (const c of plan.conventionsToWire || []) {
+    L.push(`${n++}. [ ] Wire the **${c.label}** convention (see the template — it encodes this).`)
+  }
+  for (const c of plan.conventionsPreferred || []) {
+    L.push(`${n++}. [ ] (preferred) ${c.label} — recommended, not blocking; the template's default.`)
+  }
+  if (!plan.metaGate?.wired) L.push(`${n++}. [ ] **Bootstrap** — add a job running \`node <ensure-coverage>/scripts/ci-audit.mjs --files <your ci files>\` so the gates can't be silently deleted or weakened later. Without it, nothing guards the gates.`)
+  L.push(`${n++}. [ ] Fill the \`<…>\` placeholders (\`<skill>\` path, \`<seed + migrate>\`, \`<boot app>\`, DB URL) and confirm no gate carries \`continue-on-error\`/\`|| true\`/\`--warn-only\`.`)
+  L.push('')
+  L.push('### Verify')
+  L.push('```bash')
+  L.push(`node <ensure-coverage>/scripts/ci-audit.mjs --files ${plan.scanned.join(',') || '<your ci files>'}`)
+  L.push('```')
+  L.push('Must report every gate `present` (and the meta-gate wired). `absent`/`warn-only` fail the audit.')
+  return L.join('\n')
+}
+
+// ---- CLI (file discovery) ----
+
+function discover(explicit) {
+  if (explicit) return explicit.split(',').map((s) => s.trim()).filter(Boolean)
+  const found = []
+  const wf = '.github/workflows'
+  if (fs.existsSync(wf)) for (const f of fs.readdirSync(wf)) if (/\.ya?ml$/.test(f)) found.push(path.join(wf, f))
+  for (const f of fs.existsSync('.') ? fs.readdirSync('.') : []) {
+    if (/^cloudbuild.*\.ya?ml$/.test(f)) found.push(f)
+  }
+  for (const f of ['Makefile', 'package.json']) if (fs.existsSync(f)) found.push(f)
+  return found
+}
+
+function main() {
+  const argv = process.argv.slice(2)
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--allow-warn') flags.allowWarn = true
+    else if (a === '--json') flags.json = true
+    else if (a === '--adoption') flags.adoption = true
+    else if (a === '--files') flags.files = argv[++i]
+  }
+  const paths = discover(flags.files)
+  if (paths.length === 0) {
+    console.error('ci-audit: no CI config files found to scan (pass --files a.yml,b.yaml)')
+    process.exit(2)
+  }
+  const files = paths.map((p) => ({ name: p, text: fs.readFileSync(p, 'utf8') }))
+  const report = auditCorpus(files, { allowWarn: flags.allowWarn })
+  if (flags.adoption) {
+    const plan = buildAdoptionPlan(report)
+    if (flags.json) console.log(JSON.stringify(plan, null, 2))
+    else if (!plan.needed) console.log(`✓ nothing to adopt — all required gates wired and blocking, and the meta-gate runs (scanned: ${plan.scanned.join(', ')})`)
+    else console.log(renderAdoptionIssue(plan))
+    process.exit(plan.needed ? 1 : 0)
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2))
+  } else {
+    console.log(`ci-audit — scanned: ${report.scanned.join(', ')}`)
+    for (const g of report.gates) {
+      const mark = g.status === 'present' ? '✓' : g.status === 'warn-only' ? '⚠' : '✗'
+      console.log(`  ${mark} ${g.label}: ${g.status} (${g.evidence})`)
+    }
+    for (const c of report.conventions || []) {
+      const cmark = c.status === 'present' ? '✓' : c.status === 'n/a' ? '○' : c.required ? '✗' : '○'
+      const suffix = c.required ? '' : ' — preferred, advisory'
+      console.log(`  ${cmark} ${c.label}: ${c.status}${suffix} (${c.evidence})`)
+    }
+    const m = report.metaGate?.wired ? '✓' : '○'
+    console.log(`  ${m} ${META_GATE.label}: ${report.metaGate?.wired ? 'wired' : 'not wired (advisory — run --adoption)'} (${report.metaGate?.evidence})`)
+    const vmark = report.visualGate?.status === 'present' ? '✓' : '○'
+    console.log(`  ${vmark} ${VISUAL_GATE.label}: ${report.visualGate?.status} (${report.visualGate?.evidence}) — advisory; only a gap if a surface opts into presentation:visual`)
+    console.log(report.ok ? '\nPASS — all required gates wired and blocking' : '\nFAIL — missing/weakened gate(s) or missing required convention(s); see references/enforcement/ci-contract.md')
+    if (!report.ok || !report.metaGate?.wired) console.log('  → generate a wiring issue:  node ci-audit.mjs --adoption --files ' + report.scanned.join(','))
+  }
+  process.exit(report.ok ? 0 : 1)
+}
+
+if (isMainModule(import.meta.url)) main()