@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/scripts/evidence-block.mjs

@@ -0,0 +1,367 @@
+// evidence-block — derive the Review Contract's volatile evidence, never transcribe it.
+//
+// A Review Contract carries two kinds of claim with very different lifetimes:
+//
+//   DURABLE   what this PR proves, which surfaces it touches, which rows are
+//             Partial/Unverified and why. Changes when the CLAIM changes.
+//   VOLATILE  scan counts, CI job tables, test counts, gate results, SHAs.
+//             Invalidated by ANY commit.
+//
+// Hand-writing the volatile half is a defect generator: every fix round rewrites
+// the document, and every rewrite is a fresh chance to overclaim or go stale. The
+// observed incident: one PR carried five docs-only "record round N evidence"
+// commits, each invalidated within the hour by the next, producing evidence-fidelity
+// review findings for three consecutive rounds while the production diff was empty.
+//
+// So: the volatile block is GENERATED at a known SHA and STAMPED with it, and
+// `validate` fails when the stamp is not the current HEAD. Nobody transcribes it,
+// so nobody can transcribe it wrong; staleness becomes mechanical rather than a
+// reviewer's catch. The contract prose references this file instead of restating it.
+//
+//   node evidence-block.mjs collect --base <sha> [--head <sha>] [--source a,b,c]
+//                                   [--scan-diff <path to review-pr/scripts/scan-diff.mjs>]
+//                                   [--ingest <file.json>] [--no-ci] [-o evidence.json]
+//                                   [--exact-head <exact-head-artifact.json>]
+//   node evidence-block.mjs validate <evidence.json> [--source a,b,c]
+//
+// `--source` is COMMA-separated in a single argv token (`--source src,app,packages`).
+// Space-separating it silently yields one bogus pathspec, and git exits 0 on a pathspec
+// that matches nothing — so the production-diff claim would read EMPTY on every run and
+// tell the orchestrator to skip the review round. Failing open is the one failure mode
+// this file cannot afford, so the shape is spelled out here and in the CI templates.
+//
+// `collect` derives what it can run (git identity, scan-diff channels, CI jobs for
+// the exact SHA, production-diff emptiness) and INGESTS what it cannot (repo-specific
+// suite results — see --ingest below). Everything lands stamped with the same head.
+//
+// --ingest takes { "entries": [ { "name", "command", "result", "status", "sha"?,
+// "reused"?, "note"? } ] }. `status` is Pass | Fail | Partial/Unverified. An entry
+// whose sha differs from head must set `reused: true` and carry a note — that is the
+// honest label for reusing a prior probe, and validate reports it rather than
+// letting it read as fresh exact-head evidence.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+import { validateExactHeadArtifact } from '../../engineering-runtime/scripts/exact-head-artifact.mjs'
+import { ciAbsence, observeActionsRuns, startupFailures } from '../../engineering-runtime/scripts/head-check-set.mjs'
+export const EVIDENCE_BLOCK_VERSION = 1
+export const INGEST_STATUSES = ['Pass', 'Fail', 'Partial/Unverified']
+
+// ---- pure core ----
+
+// A stamped entry is fresh only when it was produced at the head being claimed.
+// Anything else must be explicitly labelled as reuse; silence is the failure mode
+// this whole module exists to remove.
+export function classifyEntry(entry, headSha) {
+  if (!entry || typeof entry !== 'object') return { ok: false, errors: ['ingested entry must be an object'] }
+  const errors = []
+  for (const field of ['name', 'command', 'result']) {
+    if (typeof entry[field] !== 'string' || !entry[field].trim()) errors.push(`ingested entry requires a non-empty ${field}`)
+  }
+  if (!INGEST_STATUSES.includes(entry.status)) errors.push(`ingested entry "${entry.name}" needs status one of ${INGEST_STATUSES.join(' | ')}`)
+  const sha = entry.sha || headSha
+  const fresh = sha === headSha
+  if (!fresh && !entry.reused) errors.push(`ingested entry "${entry.name}" was produced at ${sha}, not head ${headSha} — mark it reused:true with a note or re-run it`)
+  if (!fresh && entry.reused && !String(entry.note || '').trim()) errors.push(`reused entry "${entry.name}" requires a note saying what it covers and why reuse is honest`)
+  if (entry.reused && entry.status === 'Pass') errors.push(`reused entry "${entry.name}" cannot be Pass — reuse is Partial/Unverified by definition`)
+  return { ok: errors.length === 0, errors, fresh, sha }
+}
+
+export function validateBlock(block, { headSha, productionDiffEmpty = null } = {}) {
+  const errors = []
+  const warnings = []
+  if (!block || typeof block !== 'object') return { ok: false, errors: ['evidence block must be an object'], warnings }
+  if (block.version !== EVIDENCE_BLOCK_VERSION) errors.push(`unsupported evidence block version ${block.version}`)
+  if (!block.headSha) errors.push('evidence block requires a headSha stamp')
+  // The load-bearing check: a block that does not describe the current tree is not
+  // evidence about it. This is what a hand-written table could never enforce.
+  if (headSha && block.headSha && block.headSha !== headSha) {
+    errors.push(`evidence block is STALE: stamped ${block.headSha}, current HEAD is ${headSha} — re-run collect`)
+  }
+  for (const entry of block.ingested || []) {
+    const verdict = classifyEntry(entry, block.headSha)
+    errors.push(...verdict.errors)
+    if (verdict.ok && entry.reused) warnings.push(`reused (not fresh exact-head): ${entry.name} — ${entry.note}`)
+    if (verdict.ok && entry.status === 'Partial/Unverified' && !entry.reused) warnings.push(`Partial/Unverified: ${entry.name} — ${entry.note || 'no note given'}`)
+  }
+  // A WARNING and not an error, deliberately, and the distinction is #1082 AC4. A workflow
+  // GitHub refused to parse is red, but nothing declared it required, and turning that into
+  // an error here would make this block silently decide a merge policy that belongs to the
+  // human and to `.mergify.yml`. Silence is the only outcome that is not allowed.
+  for (const failure of block.ci?.startupFailures || []) {
+    warnings.push(
+      `WORKFLOW RAN ZERO JOBS at ${block.headSha}: run ${failure.runId} "${failure.name}" completed ${failure.conclusion} having executed no job at all`
+      + `${failure.nameEqualsPath ? ', and its name equals its file path' : ''}`
+      + ' — the signature of a workflow GitHub rejected at validation (#1081). It produces no check-run, so no check is red; this is not blocking here and it is not nothing.',
+    )
+  }
+  if (block.ci?.status === 'collected') {
+    for (const job of block.ci.skipped || []) warnings.push(`CI job SKIPPED (not passed): ${job}`)
+    if ((block.ci.failed || []).length) errors.push(`CI jobs failed at ${block.headSha}: ${block.ci.failed.join(', ')}`)
+  } else if (block.ci?.status) {
+    // Intentional: uncollected/unavailable CI is a WARNING, not an error, so
+    // `validate` still exits 0. This block is the *pre-spawn decidable check*, not
+    // the loop's exit gate — CI-green on the final HEAD is enforced separately (the
+    // loop exit condition), and a pre-spawn block legitimately runs before CI has
+    // been gathered. What must never read as green is a *collected* result with
+    // failures (errored above); "not yet collected" is honestly reported as such,
+    // never as pass, and the caller reads block.ci.status to see it.
+    warnings.push(`CI evidence ${block.ci.status} (not a pass — the exit gate, not this block, enforces CI-green on the final HEAD): ${block.ci.reason || 'no reason recorded'}`)
+  }
+  if (block.exactHead !== undefined) {
+    const verdict = validateExactHeadArtifact(block.exactHead, { expectedHeadSha: block.headSha })
+    errors.push(...verdict.errors.map((error) => `exact-head: ${error}`))
+    for (const job of block.exactHead.jobs || []) {
+      if (job.conclusion === 'skipped') warnings.push(`Exact-head job ${job.name} SKIPPED (not passed)`)
+    }
+  }
+  // Surfaced, never enforced: an empty production diff is the orchestrator's signal
+  // that a round is evidence-only and must not buy a full re-review round.
+  if (productionDiffEmpty === true) warnings.push('production diff is EMPTY since the last reviewed SHA — the first of the two evidence-lane signals; the lane also needs every surviving finding classed subject: evidence by the reviewer, and its fix runs as the constrained evidence-fix spawn, not an inline commit')
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+export function renderMarkdown(block) {
+  const lines = [`<!-- generated by evidence-block.mjs — do not hand-edit; re-run collect -->`,
+    `**Evidence at \`${block.headSha}\`** (base \`${block.baseSha}\`, collected ${block.collectedAt})`, '']
+  lines.push(`- Scan \`${block.baseSha}...${block.headSha}\`: findings ${JSON.stringify(block.scan?.findingCounts ?? {})}, ${block.scan?.leadCount ?? 0} heuristic leads ${JSON.stringify(block.scan?.leadCounts ?? {})}`)
+  if (block.ci?.status === 'collected') {
+    lines.push(`- CI at this exact SHA: ${block.ci.success.length} succeeded, ${block.ci.skipped.length} skipped, ${block.ci.failed.length} failed`)
+    if (block.ci.skipped.length) lines.push(`  - skipped (NOT passed): ${block.ci.skipped.join('; ')}`)
+    if (block.ci.failed.length) lines.push(`  - failed: ${block.ci.failed.join('; ')}`)
+  } else lines.push(`- CI at this exact SHA: ${block.ci?.status || 'not collected'}${block.ci?.ciState ? ` (${block.ci.ciState})` : ''} — ${block.ci?.reason || ''}`)
+  for (const failure of block.ci?.startupFailures || []) {
+    lines.push(`  - **workflow ran ZERO jobs**: run ${failure.runId} \`${failure.name}\` (${failure.conclusion})${failure.nameEqualsPath ? ', name equals file path' : ''} — rejected at validation; it produces no check-run, so nothing is red (#1081). Not blocking here.`)
+  }
+  if (block.exactHead) {
+    const provenance = block.exactHead.collectionMode === 'choreographed'
+      ? `collection choreographed; restoration ${block.exactHead.restoration?.proved ? 'proved' : 'unproved'}`
+      : `collection observed-existing-run; live head observed before and after provider evidence acquisition`
+    lines.push(`- Exact-head CI at this SHA: **${block.exactHead.summary?.outcome || 'unknown'}** — ${provenance}`)
+    for (const job of block.exactHead.jobs || []) {
+      if (job.conclusion === 'skipped') lines.push(`  - ${job.name}: skipped (NOT passed)`)
+    }
+  }
+  if (block.productionDiff) lines.push(`- Production diff vs \`${block.productionDiff.since}\`: ${block.productionDiff.empty ? 'EMPTY (evidence-only round)' : 'non-empty'} over ${block.productionDiff.paths.join(', ')}`)
+  for (const entry of block.ingested || []) {
+    const tag = entry.reused ? ' _(reused, not fresh exact-head)_' : ''
+    lines.push(`- ${entry.name}: **${entry.status}** — \`${entry.command}\` → ${entry.result}${tag}${entry.note ? ` (${entry.note})` : ''}`)
+  }
+  return lines.join('\n')
+}
+
+// ---- impure edges (each isolated so the core above stays testable) ----
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).trim()
+}
+
+// `collect` needs review-pr's scan-diff.mjs — a hop out of this skill into a sibling.
+// The relative shape below covers both real layouts (a monorepo checkout, and skills
+// installed side-by-side in ~/.claude/skills — Node resolves a symlinked module to its
+// realpath, so a symlink farm lands in the monorepo case). It still misses when
+// ensure-coverage is COPIED somewhere without review-pr, or under --preserve-symlinks.
+//
+// When it misses, say so and stop. The tempting alternative — carry on and record a
+// scan channel of zero — is the `leadCount=0` incident with extra steps: "we did not
+// scan" and "the scan found nothing" must never render identically, because the whole
+// point of this file is that a reviewer can trust the numbers without re-deriving them.
+export function resolveScanDiff(here, override, exists = fs.existsSync) {
+  if (override) {
+    if (exists(override)) return override
+    throw new Error(`--scan-diff points at ${override}, which does not exist`)
+  }
+  const candidate = path.resolve(here, '../../review-pr/scripts/scan-diff.mjs')
+  if (exists(candidate)) return candidate
+  throw new Error(
+    `cannot find review-pr's scan-diff.mjs (looked in ${candidate}). ` +
+      `The scan channel is load-bearing evidence, so this fails rather than reporting an empty scan. ` +
+      `Install review-pr beside ensure-coverage, or pass --scan-diff <path>.`,
+  )
+}
+
+export function collectScan(baseSha, headSha, cwd, scanDiffPath) {
+  const diff = git(['diff', `${baseSha}...${headSha}`], cwd)
+  const raw = execFileSync(process.execPath, [scanDiffPath], { input: diff, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  const parsed = JSON.parse(raw)
+  const leadCount = Object.values(parsed.counts || {}).reduce((sum, n) => sum + n, 0)
+  return { findingCounts: parsed.findingCounts || {}, findings: parsed.findings || [], leadCounts: parsed.counts || {}, leadCount }
+}
+
+// Best-effort: `gh` may be absent, unauthenticated, or the SHA may have no run yet.
+// An unavailable CI channel is recorded as unavailable — never as "passed".
+export function ghJson(args, cwd) {
+  const text = execFileSync('gh', args, { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 }).trim()
+  return text ? JSON.parse(text) : null
+}
+
+/**
+ * The CI channel, read as a QUESTION ABOUT THE SHA rather than about a run list.
+ *
+ * Two defects this closes, and they are the same defect seen from two sides (#1058, #1081):
+ *
+ *   · "no workflow run found for <sha>" was the reported reason for three situations that
+ *     call for opposite responses — the event was never delivered (waiting is futile), the
+ *     run exists but no runner has picked it up (waiting is exactly right), and a run
+ *     exists only because somebody dispatched it by hand (honest exact-head evidence that
+ *     satisfies no queue condition). All three read as *still queued*. Now each carries
+ *     `ciState` plus a reason a reader can act on without a second investigation.
+ *   · A workflow GitHub refuses to parse contributes NOTHING to this channel: it produces
+ *     a run with zero jobs and no check-run at all, so a job-by-job walk sees nothing and
+ *     reports the SHA as clean. That is #1081, and it is why `startupFailures` is read
+ *     from the run list rather than inferred from the jobs.
+ *
+ * `startupFailures` is a WARNING, never an error. It is not this block's business to
+ * decide that a red workflow nobody declared required blocks a merge — see head-check-set's
+ * header and #1082 AC4. What it must not be is silent.
+ *
+ * The run list moved from `gh run list` to the REST API for one reason: `path`. The
+ * corroborating half of the #1081 signature is a run whose `name` equals its file path,
+ * and `gh run list --json` cannot report the path.
+ */
+export function collectCi(headSha, cwd, api = ghJson) {
+  try {
+    const runs = api(['api', `repos/{owner}/{repo}/actions/runs?head_sha=${headSha}&per_page=100`], cwd)?.workflow_runs || []
+    const success = [], skipped = [], failed = [], pending = []
+    const counted = runs.map((run) => {
+      let jobs = null
+      try { jobs = api(['api', `repos/{owner}/{repo}/actions/runs/${run.id}/jobs?per_page=100`], cwd) } catch { jobs = null }
+      for (const job of jobs?.jobs || []) {
+        if (job.conclusion === 'success') success.push(job.name)
+        else if (job.conclusion === 'skipped') skipped.push(job.name)
+        else if (job.conclusion == null) pending.push(job.name)
+        else failed.push(`${job.name} (${job.conclusion})`)
+      }
+      // `total_count`, never the length of a page we may have failed to read: "we did not
+      // look" and "it ran nothing" are the two readings this whole function separates.
+      return { ...run, jobCount: Number.isInteger(jobs?.total_count) ? jobs.total_count : null }
+    })
+    const observations = observeActionsRuns(counted)
+    const zeroJob = startupFailures(observations)
+    if (success.length || skipped.length || failed.length || pending.length) {
+      return { status: 'collected', success, skipped, failed, pending, startupFailures: zeroJob }
+    }
+    const absence = ciAbsence(observations)
+    return { status: 'unavailable', ciState: absence.reason, reason: `${absence.reason} for ${headSha} — ${absence.detail}`, startupFailures: zeroJob }
+  } catch (error) {
+    return { status: 'unavailable', ciState: 'unreadable', reason: String(error.message || error).split('\n')[0], startupFailures: [] }
+  }
+}
+
+export function productionDiffEmpty(sinceSha, headSha, sourcePaths, cwd) {
+  try {
+    git(['diff', '--quiet', `${sinceSha}..${headSha}`, '--', ...sourcePaths], cwd)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function collect({ base, head, cwd = process.cwd(), sourcePaths = [], since = null, withCi = true, ingest = [], exactHead = null, scanDiffPath, now = new Date().toISOString() }) {
+  const headSha = head || git(['rev-parse', 'HEAD'], cwd)
+  const baseSha = base || git(['merge-base', 'HEAD@{upstream}', 'HEAD'], cwd)
+  const block = {
+    version: EVIDENCE_BLOCK_VERSION,
+    headSha,
+    baseSha,
+    collectedAt: now,
+    scan: collectScan(baseSha, headSha, cwd, scanDiffPath),
+    ci: withCi ? collectCi(headSha, cwd) : { status: 'not-collected', reason: '--no-ci' },
+    ingested: ingest,
+  }
+  if (exactHead) block.exactHead = exactHead
+  if (since && sourcePaths.length) {
+    block.productionDiff = { since, paths: sourcePaths, empty: productionDiffEmpty(since, headSha, sourcePaths, cwd) }
+  }
+  return block
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const positional = []
+  const opts = { ci: true }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--base') opts.base = argv[++i]
+    else if (a === '--head') opts.head = argv[++i]
+    else if (a === '--since') opts.since = argv[++i]
+    else if (a === '--source') opts.source = argv[++i]
+    else if (a === '--ingest') opts.ingest = argv[++i]
+    else if (a === '--exact-head') opts.exactHead = argv[++i]
+    else if (a === '--no-ci') opts.ci = false
+    else if (a === '-o' || a === '--out') opts.out = argv[++i]
+    else if (a === '--markdown') opts.markdown = true
+    else if (a === '--cwd') opts.cwd = argv[++i]
+    else if (a === '--scan-diff') opts.scanDiff = argv[++i]
+    else positional.push(a)
+  }
+  return { positional, opts }
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv
+  const { positional, opts } = parseArgs(rest)
+  const cwd = opts.cwd || process.cwd()
+  const sourcePaths = (opts.source || '').split(',').map((s) => s.trim()).filter(Boolean)
+  const here = path.dirname(decodeURIComponent(new URL(import.meta.url).pathname))
+
+  if (cmd === 'collect') {
+    if (!opts.base) { console.error('evidence-block collect: --base <sha> is required (the merge-base the PR is reviewed against)'); return 2 }
+    // Resolved inside `collect` only — `validate` and `render` never scan, so a repo
+    // without review-pr can still run the CI gate.
+    let scanDiffPath
+    try {
+      scanDiffPath = resolveScanDiff(here, opts.scanDiff)
+    } catch (e) {
+      console.error(`evidence-block collect: ${e.message}`)
+      return 2
+    }
+    let ingest = []
+    if (opts.ingest) {
+      const parsed = JSON.parse(fs.readFileSync(opts.ingest, 'utf8'))
+      ingest = Array.isArray(parsed) ? parsed : parsed.entries || []
+    }
+    const exactHead = opts.exactHead ? JSON.parse(fs.readFileSync(opts.exactHead, 'utf8')) : null
+    const block = collect({ base: opts.base, head: opts.head, cwd, sourcePaths, since: opts.since, withCi: opts.ci, ingest, exactHead, scanDiffPath })
+    const { ok, errors, warnings } = validateBlock(block, { headSha: block.headSha })
+    for (const w of warnings) console.error(`warn: ${w}`)
+    for (const e of errors) console.error(`error: ${e}`)
+    const out = opts.markdown ? renderMarkdown(block) : `${JSON.stringify(block, null, 2)}\n`
+    if (opts.out) fs.writeFileSync(opts.out, out.endsWith('\n') ? out : `${out}\n`)
+    else console.log(out)
+    return ok ? 0 : 1
+  }
+
+  if (cmd === 'validate') {
+    const file = positional[0]
+    if (!file) { console.error('evidence-block validate: <evidence.json> is required'); return 2 }
+    const block = JSON.parse(fs.readFileSync(file, 'utf8'))
+    const headSha = git(['rev-parse', 'HEAD'], cwd)
+    const empty = block.productionDiff?.since && sourcePaths.length
+      ? productionDiffEmpty(block.productionDiff.since, headSha, sourcePaths, cwd)
+      : null
+    const { ok, errors, warnings } = validateBlock(block, { headSha, productionDiffEmpty: empty })
+    for (const w of warnings) console.error(`warn: ${w}`)
+    for (const e of errors) console.error(`error: ${e}`)
+    if (ok) console.error(`evidence-block: valid at ${headSha}`)
+    return ok ? 0 : 1
+  }
+
+  if (cmd === 'render') {
+    const file = positional[0]
+    if (!file) { console.error('evidence-block render: <evidence.json> is required'); return 2 }
+    console.log(renderMarkdown(JSON.parse(fs.readFileSync(file, 'utf8'))))
+    return 0
+  }
+
+  console.error('evidence-block: unknown command. Use collect|validate|render (see header).')
+  return 2
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}

package/skills/engineering/ensure-coverage/scripts/lint-tests.mjs

@@ -0,0 +1,269 @@
+// lint-tests — static GATE lints over test files. The decidable subset of the
+// skills' test-authoring doctrine, turned into deterministic checks that don't
+// need an LLM: fast, free, robust, run in CI on every PR.
+//
+//   node lint-tests.mjs --diff <base>           # PR mode: only violations ADDED in base...HEAD (CI default)
+//   node lint-tests.mjs [--files a,b]           # specific files
+//   node lint-tests.mjs                          # whole-tree scan of discovered test files
+//   --rules no-skip,no-fixed-timeout             # run a subset (default: all gate rules)
+//   --json                                        # machine output
+//
+// (Named lint-tests, not test-lint, so node's --test runner doesn't glob it as a
+//  test file via its `test-*` pattern and execute the CLI mid-suite.)
+//
+// SCOPE — what belongs here vs. not:
+//   GATE (here): syntactically decidable, ~zero false positives → safe to BLOCK.
+//     A noisy blocking lint gets disabled, so only near-certain rules live here.
+//   LEAD (NOT here): heuristic/judgment — "is this assertion meaningful?",
+//     over-mocking, asserting on an error page. Those stay LEADS for the reviewer
+//     (review-pr → scripts/scan-diff.mjs) and human/LLM judgment. Lint the
+//     decidable shell; leave the semantics to review.
+//
+// Adding a gate rule = append to RULES below (id + message + line patterns). Keep
+// the false-positive bar high: if a legitimate test could trip it, it's a lead.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execSync } from 'node:child_process'
+import { loadMockPolicyFromFile, extractMockTarget, classifyMockTarget } from './mock-policy-config.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// Skip / focus / expected-fail forms. `.only`/focus silently disable every OTHER
+// test; skip/xfail/fixme disable this one. All banned (see test-skipping.md).
+export const SKIP_PATTERNS = [
+  { kind: 'skip', re: /\b(?:test|it|describe|suite|context)\s*\.\s*skip\b/ },
+  { kind: 'only', re: /\b(?:test|it|describe|suite|context)\s*\.\s*only\b/ },
+  { kind: 'fixme', re: /\b(?:test|it)\s*\.\s*fixme\b/ },
+  { kind: 'skip', re: /\b(?:xit|xdescribe|xtest)\s*\(/ },
+  { kind: 'only', re: /\b(?:fit|fdescribe|ftest)\s*\(/ },
+  { kind: 'skip', re: /@(?:pytest\.mark\.)?skip(?:if)?\b/ },
+  { kind: 'skip', re: /@unittest\.skip/ },
+  { kind: 'skip', re: /\bpytest\.skip\s*\(/ },
+  { kind: 'xfail', re: /@(?:pytest\.mark\.)?xfail\b/ },
+]
+
+// Fixed sleeps — a timer instead of an explicit wait. The single biggest source of
+// flake; doctrine is "never waitForTimeout()". Precise: these forms are ~never
+// legitimate in a test (an aliased `cy.wait('@x')` or polling helper is not matched).
+export const FIXED_TIMEOUT_PATTERNS = [
+  { kind: 'waitForTimeout', re: /\.waitForTimeout\s*\(/ },
+  { kind: 'cy.wait', re: /\bcy\.wait\s*\(\s*\d/ },     // numeric only; cy.wait('@alias') is fine
+  { kind: 'time.sleep', re: /\btime\.sleep\s*\(/ },
+]
+
+// Empty test body — a `test`/`it` whose callback body is `{}`. A placeholder
+// that passes vacuously and asserts nothing: the Missing-Assertion smell in its
+// one decidable, ~zero-false-positive form. The BROADER "has statements but no
+// assertion" case is NOT here — a test can assert through a helper, so a block
+// with no `expect`/`assert` token may still assert; that stays a review LEAD
+// (review-pr) and the test-smells doctrine ([../references/depth/test-smells.md]).
+// Matches only single-line empty bodies (`() => {}` / `function () {}`), incl.
+// `.skip`/`.each(...)`/`.concurrent` chains and Playwright `async ({ page })`
+// fixtures; `describe`/`suite` are excluded (an empty suite is not a fake test).
+// A multi-line empty body is rarer and deliberately left to the lead, not
+// false-blocked.
+export const EMPTY_TEST_PATTERNS = [
+  { kind: 'empty-test', re: /\b(?:it|test)\s*(?:\.\s*\w+\s*(?:\([^)]*\)\s*)?)?\(\s*[`'"][^`'"]*[`'"]\s*,\s*(?:async\s+)?(?:function\s*\*?\s*)?\([^)]*\)\s*(?:=>\s*)?\{\s*\}\s*\)?/ },
+]
+
+// Swallowed assertion — an assertion matcher whose rejection is eaten by a
+// chained `.catch(...)`, so the assertion can NEVER fail the test. The vacuous
+// form behind the #237 login regression: `expect(locator).not.toBeVisible().catch(() => {})`
+// passed whether or not the button was actually visible. Decidable and
+// ~zero-false-positive: a Playwright web-first matcher (`.toXxx(...)`) directly
+// chained to `.catch(` is never legitimate — a real assertion's rejection must
+// surface, not be discarded. (Synchronous Jest matchers don't return a promise,
+// so `.toBe(x).catch()` only appears as a deliberate swallow.) The broader
+// "assertion guarded by a try/catch that re-passes" case stays a review LEAD
+// (review-pr); only the directly-chained matcher form is gated here.
+export const SWALLOWED_ASSERTION_PATTERNS = [
+  { kind: 'swallowed-catch', re: /\.to[A-Z]\w*\s*\([^)]*\)\s*\.catch\s*\(/ },
+]
+
+export const RULES = [
+  { id: 'no-skip', message: 'test skipped/focused — seed/quarantine/route/delete instead (test-skipping.md)', patterns: SKIP_PATTERNS },
+  { id: 'no-fixed-timeout', message: 'fixed sleep — use an explicit wait (waitForResponse / expect.poll / web-first assertion), never a timer', patterns: FIXED_TIMEOUT_PATTERNS },
+  { id: 'no-empty-test', message: 'empty test body — a placeholder that asserts nothing (passes vacuously); write the behavior assertion or delete it (test-smells.md)', patterns: EMPTY_TEST_PATTERNS },
+  { id: 'no-swallowed-assertion', message: 'assertion failure swallowed by .catch() — the matcher can never fail (vacuous green); let it throw, or assert the real condition (test-smells.md)', patterns: SWALLOWED_ASSERTION_PATTERNS },
+]
+
+// Default-on GATE for over-mocking — the decidable core of the depth axis
+// (mock-policy.md), mechanized via the externals-allowlist inversion
+// (mock-policy-config.mjs). A `match`-style rule (not a line pattern): it pulls
+// the mock target, exempts declared externals, and flags a mock
+// of a first-party internal seam. ZERO-TOLERANCE: default-on, no waiver, and
+// never silently inert — over-mock is a hard gate (mock-policy.md), not an
+// opt-in. `coverage.config.json` only *declares topology* (a monorepo's own
+// package scope, generated dirs to exempt); it cannot turn the gate off. With
+// no config the rule runs on conventional `@/`/`~/` defaults. Run it diff-scoped
+// in the PR lane (catch new seams) AND whole-tree (no inherited seam is
+// grandfathered — the tree stays red until they are removed).
+export const MOCK_INTERNAL_SEAM_RULE = {
+  id: 'mock-internal-seam',
+  defaultOn: true,
+  message: 'mocks an internal seam — real internals, faked externals (mock-policy.md): replace it with a real-boundary test, or fake the external instead. No waivers; no inherited grace.',
+  match(raw, code, ctx) {
+    const target = extractMockTarget(code)
+    if (!target) return null
+    // classifyMockTarget falls back to DEFAULT_MOCK_POLICY when ctx has no
+    // policy, so the gate can never be silently disabled by omitting config.
+    const { internal, reason } = classifyMockTarget(target, ctx && ctx.policy)
+    if (!internal) return null
+    return { kind: 'internal-seam', detail: target, reason }
+  },
+}
+
+// Every known rule. RULES is the original authoring-gate set; ALL_RULES is the
+// full registry. mock-internal-seam is default-on (defaultOn:true), so it is in
+// the default selection too — it is a standard gate now, not an opt-in.
+export const ALL_RULES = [...RULES, MOCK_INTERNAL_SEAM_RULE]
+
+export function selectRules(ruleIds) {
+  if (ruleIds && ruleIds.length > 0) {
+    const set = new Set(ruleIds)
+    return ALL_RULES.filter((r) => set.has(r.id))
+  }
+  // Default: every rule that isn't explicitly opted out (defaultOn:false).
+  return ALL_RULES.filter((r) => r.defaultOn !== false)
+}
+
+// Strip line comments so a doc line or a commented-out example is not flagged.
+// Best-effort (ignores strings/block comments) — live code has no leading `//`.
+export function stripComment(line) {
+  return line.replace(/\/\/.*$/, '').replace(/(^|\s)#.*$/, '$1')
+}
+
+// Skips/timeouts only matter in tests; linting app code would false-flag a
+// legitimate `.skip()`/`.only` array method or a real `sleep`.
+export function isTestFile(p) {
+  if (!p) return false
+  return /\.(spec|test)\.[cm]?[jt]sx?$/.test(p)
+    || /(^|\/)(e2e|tests?|__tests__)\//.test(p)
+    || /(^|\/)test_[^/]*\.py$/.test(p)
+    || /_test\.py$/.test(p)
+}
+
+// Pure: run the selected rules over one line → findings (≤ one per rule). `ctx`
+// carries the resolved mock policy (declared topology) for `match`-style rules;
+// pattern rules ignore it. A `match` rule sees the raw line and the
+// comment-stripped code (so a commented-out example never trips).
+function scanLine(file, raw, lineNo, rules, ctx) {
+  const code = stripComment(raw)
+  const out = []
+  for (const rule of rules) {
+    if (typeof rule.match === 'function') {
+      const hit = rule.match(raw, code, ctx)
+      if (hit) {
+        out.push({
+          file, line: lineNo, rule: rule.id, kind: hit.kind || rule.id,
+          snippet: raw.trim().slice(0, 120),
+          ...(hit.detail ? { detail: hit.detail } : {}),
+          ...(hit.reason ? { reason: hit.reason } : {}),
+        })
+      }
+      continue
+    }
+    const hit = rule.patterns.find((p) => p.re.test(code))
+    if (hit) out.push({ file, line: lineNo, rule: rule.id, kind: hit.kind || rule.id, snippet: raw.trim().slice(0, 120) })
+  }
+  return out
+}
+
+export function scanLines(file, lines, ruleIds, ctx) {
+  const rules = selectRules(ruleIds)
+  const out = []
+  lines.forEach((raw, i) => out.push(...scanLine(file, raw, i + 1, rules, ctx)))
+  return out
+}
+
+export function scanText(file, text, ruleIds, ctx) {
+  return scanLines(file, (text || '').split(/\r?\n/), ruleIds, ctx)
+}
+
+// Pure: scan a unified diff, flagging only ADDED lines in test files (inherited
+// violations on context lines are left alone — review-pr diff-discipline).
+export function scanDiff(diffText, ruleIds, ctx) {
+  const rules = selectRules(ruleIds)
+  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] !== '/dev/null' ? m[1] : null
+      continue
+    }
+    if (raw.startsWith('@@')) {
+      const m = raw.match(/\+(\d+)/)
+      newLine = m ? parseInt(m[1], 10) : 0
+      continue
+    }
+    if (raw.startsWith('+')) {
+      if (isTestFile(file)) out.push(...scanLine(file, raw.slice(1), newLine, rules, ctx))
+      newLine++
+    } else if (raw.startsWith('-') || raw.startsWith('\\')) {
+      // removed line / "No newline" marker — do not advance the new-file counter
+    } else {
+      newLine++ // context line
+    }
+  }
+  return out
+}
+
+// ---- CLI ----
+
+function discover(dir, acc = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) discover(full, acc)
+    else if (isTestFile(full)) acc.push(full)
+  }
+  return acc
+}
+
+export function runCli(argv, { name = 'lint-tests' } = {}) {
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') flags.json = true
+    else if (a === '--diff') flags.diff = argv[++i]
+    else if (a === '--files') flags.files = argv[++i]
+    else if (a === '--rules') flags.rules = argv[++i].split(',').map((s) => s.trim()).filter(Boolean)
+    else if (a === '--config') flags.config = argv[++i]
+  }
+  const ruleIds = flags.rules || null
+  // Resolve the project's mock policy once — this only declares *topology*
+  // (first-party scopes, exempt externals); it cannot disable the gate.
+  // `--config <file>` reads THAT file; otherwise discover coverage.config.json
+  // in cwd; with neither, the conventional `@/`/`~/` defaults apply.
+  const ctx = { policy: loadMockPolicyFromFile(flags.config) }
+
+  let findings = []
+  if (flags.diff) {
+    const diff = execSync(`git diff ${flags.diff}...HEAD`, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+    findings = scanDiff(diff, ruleIds, ctx)
+  } else {
+    const files = flags.files
+      ? flags.files.split(',').map((s) => s.trim()).filter(Boolean)
+      : discover('.')
+    for (const f of files) {
+      if (fs.existsSync(f)) findings.push(...scanText(f, fs.readFileSync(f, 'utf8'), ruleIds, ctx))
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: findings.length === 0, findings }, null, 2))
+  } else if (findings.length === 0) {
+    console.log(`${name}: ✓ no violations` + (flags.diff ? ' introduced in this change' : ' in scanned test files'))
+  } else {
+    console.log(`${name}: ✗ ${findings.length} violation(s):\n`)
+    for (const f of findings) {
+      const why = f.detail ? `  → ${f.detail}${f.reason ? ` (${f.reason})` : ''}` : ''
+      console.log(`  ${f.file}:${f.line} [${f.rule}/${f.kind}]  ${f.snippet}${why}`)
+    }
+  }
+  return findings.length === 0 ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2), { name: 'lint-tests' }))