@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/scripts/scope-class.mjs

@@ -0,0 +1,554 @@
+// scope-class — infer a unit's SCOPE CLASS from its net `merge-base...HEAD` diff.
+//
+// The axis this adds, and why it is not the risk tier. `highRisk` decides HOW DEEP
+// the review goes. `scopeClass` decides WHICH COVERAGE/EVIDENCE ARTIFACTS APPLY.
+// They are orthogonal on purpose: `.mergify.yml`, CI workflows, Dockerfile base
+// images, IAM bindings and feature-flag defaults are all config-only *and* commonly
+// high-risk. A rule of the form "config-only ⇒ lighter review" fires hardest exactly
+// where it is most wrong, so this file never touches review depth — see
+// SCOPE_KEPT_OBLIGATIONS, which is identical for every class and is asserted so.
+//
+// Named incident (the removal path's rule 1 — a new artifact names the incident it
+// would have caught): a consumer product repo, PR #1065, a policy-only diff
+// (`.mergify.yml` −5, `mergify-policy.test.ts` +2/−5) whose reviewer wrote:
+//   "The generic coverage checklist was generated for the policy-only diff but is
+//    not fully applicable without a dedicated checklist artifact."
+// Every other artifact in that run was load-bearing (`mergify config validate`,
+// `config simulate` against a live PR, the focused policy suite, `scan-diff` = 0).
+// The checklist was the only one that cost work and said nothing.
+//
+// DENY-BY-DEFAULT is the whole safety argument. A unit is `no-surface` only if EVERY
+// path in the net diff matches a configured non-runtime pattern; one unmatched path
+// ⇒ `surface-bearing`. The asymmetry: misclassifying config as surface-bearing costs
+// one useless checklist, misclassifying source as `no-surface` silently drops the
+// breadth and depth gates. So every ambiguous case fails toward `surface-bearing` —
+// an empty diff, a malformed config, a non-array input.
+//
+// THE COROLLARY DENY-BY-DEFAULT DEPENDS ON (PR #519 round 2, hazard
+// `rename-preimage-escapes-path-classifiers`): **no changed path may reach the
+// classifier in a form that hides what it is. Every side of every change is a changed
+// path, and anything the parser cannot take at face value fails toward
+// `surface-bearing`.** Deny-by-default is only as good as the path list it is handed —
+// a path the list never contains cannot be denied. The reported instance was a rename:
+// `git mv src/lib/auth.ts docs/auth-notes.md` classified `no-surface`, because only the
+// `b/` side survived, so a diff that DELETED a runtime source file looked like a docs
+// edit. Members closed here, all four: the rename pre-image (`rename from`), copies
+// (`copy from`, same shape), the `--diff` mode's `git diff --name-only` (which collapses
+// a detected rename to its post-image one layer above pathsFromDiff), and paths the
+// parser cannot take at face value — a `..` segment (`docs/../src/app.ts` reads as
+// `docs/**` to a glob and as `src/app.ts` to a filesystem) and an unparseable
+// `diff --git` header (a changed path of UNKNOWN identity is not a path that matched
+// nothing). See isOpaquePath and pathsFromDiff.
+//
+// THE ORACLE IS A REQUIREMENT, NOT A WAIVER. The pattern table carries the oracle
+// beside the pattern because both are repo-specific and they answer one question:
+// "this artifact is inapplicable — so what proves the change instead?" A matched
+// class with no declared oracle is not a pass, it is the finding (`oracle-undeclared`,
+// blocking): write one, or declare the class unproven-by-design (`oracle: null` +
+// `unprovenReason`), which forces the Review Contract to say so.
+//
+//   node scope-class.mjs classify --diff <base>        # git diff --name-only <base>...HEAD
+//   node scope-class.mjs classify --stdin              # newline-separated paths OR a unified diff
+//   node scope-class.mjs classify --paths <file>       # same, from a file
+//     [--json] [--config <file>] [--root <dir>]
+//   node scope-class.mjs table [--json]                # print the resolved pattern→oracle table
+//
+// Exit codes: 0 = classified (either class), 1 = a blocking finding, 2 = usage error.
+// `surface-bearing` is exit 0 — it is a normal, safe outcome, not a failure.
+//
+// Doctrine: references/process/scope-class.md.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+export const SURFACE_BEARING = 'surface-bearing'
+export const NO_SURFACE = 'no-surface'
+/** The enum `units[].scopeClass` is bounded by (run-state.mjs imports this). */
+export const SCOPE_CLASSES = [SURFACE_BEARING, NO_SURFACE]
+
+// ---- what `no-surface` NEVER drops -----------------------------------------
+//
+// Rendered into every result, identical for both classes, and asserted identical by
+// the tests. This is the mechanized form of "an inferred scope class never lightens
+// the review": if someone later tries to route a review obligation through this
+// classifier, the constant list is where it has to be added, in the open.
+export const SCOPE_KEPT_OBLIGATIONS = Object.freeze([
+  "scan-diff's findings channel — zero-tolerance for EVERY scope class",
+  'CI green on the exact head',
+  'the independent review on a different model — same reviewer spawn, same model-diversity rule, same verdict bar',
+  'delivery recording with ancestry proof',
+])
+
+// ---- the built-in default table (patterns → oracle) -------------------------
+//
+// Repo-tunable via `coverage.config.json` → `scopeClass` (see resolveScopeClassConfig).
+// `highRisk: true` marks the paths that govern merge authority, CI, deploy and IAM —
+// these set the risk auto-flag ALONGSIDE `no-surface`, never instead of it.
+export const DEFAULT_SCOPE_CLASSES = Object.freeze([
+  {
+    id: 'merge-policy',
+    patterns: ['.mergify.yml', '.mergify.yaml', '.github/mergify.yml', '.github/CODEOWNERS', 'CODEOWNERS', '.github/branch-protection*.y*ml'],
+    oracle: '`mergify config validate` + `mergify config simulate` against a live PR',
+    highRisk: true,
+  },
+  {
+    id: 'ci-workflows',
+    patterns: ['.github/workflows/**', '.github/actions/**', '.gitlab-ci.yml', 'azure-pipelines.yml'],
+    oracle: '`actionlint`',
+    highRisk: true,
+  },
+  {
+    id: 'deploy-config',
+    patterns: ['cloudbuild*.y*ml', 'skaffold*.y*ml', 'clouddeploy*.y*ml', 'deploy/**', 'k8s/**', 'kustomize/**', 'Dockerfile', '**/Dockerfile', '**/*.dockerfile', 'docker-compose*.y*ml'],
+    oracle: 'render/build the artifact without deploying — e.g. `skaffold render`, `kustomize build`, `docker build --check`',
+    highRisk: true,
+  },
+  {
+    id: 'iam-policy',
+    patterns: ['iam/**', '**/*.iam.y*ml', '**/*.iam.json', 'policies/**', '**/*.rego'],
+    oracle: 'policy evaluation against the intended principals — e.g. `opa test`, `gcloud policy-troubleshoot`',
+    highRisk: true,
+  },
+  {
+    id: 'docs',
+    patterns: ['docs/**', '**/*.md', '**/*.mdx', 'LICENSE', 'CODE_OF_CONDUCT*', 'CONTRIBUTING*'],
+    // Declared unproven BY DESIGN: prose has no executable oracle. Declaring it is
+    // the point — the reviewer learns the change is unproven rather than assuming a
+    // gate covered it. This is a declaration, not a waiver: it still has to be said
+    // in the Review Contract (inapplicableArtifacts carries it there).
+    oracle: null,
+    unprovenReason: 'documentation prose has no executable oracle — unproven by design; say so in the Review Contract rather than implying a gate covered it',
+    highRisk: false,
+  },
+  {
+    id: 'lockfiles',
+    patterns: ['**/package-lock.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/uv.lock', '**/poetry.lock', '**/Cargo.lock', '**/go.sum', '**/Gemfile.lock'],
+    oracle: 'install determinism — re-run the repo installer (`npm ci` / `uv sync --frozen` / …) then `git diff --exit-code <lockfile>`',
+    highRisk: false,
+  },
+  {
+    id: 'generated',
+    patterns: ['**/generated/**', '**/__generated__/**', '**/*.generated.*', '**/*.gen.*', '**/*.snap'],
+    oracle: 'regen determinism — re-run the generator then `git diff --exit-code`',
+    highRisk: false,
+  },
+  {
+    id: 'tests',
+    // Test files do not break the classification (#1065 touched `mergify-policy.test.ts`
+    // and must still classify `no-surface`). The guard against "weakened the test so the
+    // config passes" is NOT this table — it is scan-diff's findings channel, which stays
+    // zero-tolerance for every class (SCOPE_KEPT_OBLIGATIONS).
+    patterns: ['**/*.test.*', '**/*.spec.*', 'tests/**', 'test/**', '**/__tests__/**', 'e2e/**', '**/*.coverage.yml'],
+    oracle: 'run the changed test suite and paste its output',
+    highRisk: false,
+  },
+])
+
+export const DEFAULT_SCOPE_CLASS_CONFIG = Object.freeze({ classes: DEFAULT_SCOPE_CLASSES })
+
+/**
+ * Merge a repo's `scopeClass` override over the defaults.
+ * - `classes` REPLACES the table wholesale (a repo that wants full control gets it).
+ * - `extraClasses` is additive and checked BEFORE the defaults, so a repo's own
+ *   declaration wins over an overlapping built-in guess — the built-in any-depth
+ *   `.rego` pattern must not decide the oracle for a repo that declared its own
+ *   `policy/` class.
+ * Anything malformed falls back to the defaults — a broken config must never widen
+ * `no-surface` (it would fail in the expensive direction).
+ */
+export function resolveScopeClassConfig(override = {}) {
+  const o = override && typeof override === 'object' ? override : {}
+  const base = Array.isArray(o.classes) && o.classes.length ? o.classes : DEFAULT_SCOPE_CLASSES
+  const extra = Array.isArray(o.extraClasses) ? o.extraClasses : []
+  const classes = [...extra, ...base].filter((c) => c && typeof c.id === 'string' && Array.isArray(c.patterns) && c.patterns.length)
+  return { classes: classes.length ? classes : DEFAULT_SCOPE_CLASSES }
+}
+
+function readConfigFile(p) {
+  if (!fs.existsSync(p)) return null
+  try {
+    return resolveScopeClassConfig(JSON.parse(fs.readFileSync(p, 'utf8')).scopeClass ?? {})
+  } catch (e) {
+    process.stderr.write(`scope-class: ignoring malformed ${p} (${e.message}); running on the built-in default table\n`)
+    return resolveScopeClassConfig({})
+  }
+}
+
+/** Discover `coverage.config.json` / `.coverage.config.json` in rootDir. Never throws. */
+export function loadScopeClassConfig(rootDir = process.cwd()) {
+  for (const name of ['coverage.config.json', '.coverage.config.json']) {
+    const got = readConfigFile(path.join(rootDir, name))
+    if (got) return got
+  }
+  return resolveScopeClassConfig({})
+}
+
+/** Resolve an explicit `--config <file>`; warns (non-fatal) when it is missing. */
+export function loadScopeClassConfigFromFile(configFile, rootDir = process.cwd()) {
+  if (!configFile) return loadScopeClassConfig(rootDir)
+  const got = readConfigFile(configFile)
+  if (got) return got
+  process.stderr.write(`scope-class: --config ${configFile} not found; running on the built-in default table\n`)
+  return resolveScopeClassConfig({})
+}
+
+// ---- globbing --------------------------------------------------------------
+
+/**
+ * Compile a glob to an anchored RegExp. `*` stops at `/`, `**` crosses it, `?` is one
+ * non-separator char. Deliberately tiny and dependency-free: this runs in a producer's
+ * close-out, and a classifier that needs an install is one that gets skipped.
+ *
+ * A leading double-star segment also matches the bare basename (so a glob of
+ * "double-star slash *.md" matches "c.md"), which is what every reader expects and
+ * what a naive translation gets wrong.
+ */
+export function globToRegExp(glob) {
+  let re = ''
+  const g = String(glob)
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i]
+    if (c === '*') {
+      if (g[i + 1] === '*') {
+        // `**/` → any number of leading segments, including none.
+        if (g[i + 2] === '/') { re += '(?:[^/]+/)*'; i += 2 } else { re += '.*'; i += 1 }
+      } else {
+        re += '[^/]*'
+      }
+    } else if (c === '?') re += '[^/]'
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${re}$`)
+}
+
+const patternCache = new Map()
+function compiled(pattern) {
+  if (!patternCache.has(pattern)) patternCache.set(pattern, globToRegExp(pattern))
+  return patternCache.get(pattern)
+}
+
+/** The first class whose patterns match, or null (⇒ the path is surface-bearing). */
+export function matchScopeClass(filePath, config = DEFAULT_SCOPE_CLASS_CONFIG) {
+  const p = normalizePath(filePath)
+  if (!p) return null
+  // An opaque path is never matched — it lands in `unmatched` and forces
+  // surface-bearing, rather than being globbed on a spelling it does not mean.
+  if (isOpaquePath(p)) return null
+  for (const cls of config.classes || []) {
+    if ((cls.patterns || []).some((pat) => compiled(pat).test(p))) return cls
+  }
+  return null
+}
+
+function normalizePath(p) {
+  if (typeof p !== 'string') return ''
+  return p.trim().replace(/^\.\//, '')
+}
+
+/** Marker carried by pathsFromDiff for a `diff --git` header it could not split. */
+export const UNPARSEABLE_PATH = '<unparseable diff header>'
+
+/**
+ * A path the classifier must NOT take at face value — it fails toward `surface-bearing`
+ * by matching no class, and it is deliberately NOT dropped (a dropped path leaves an
+ * all-matched set behind, which is exactly the `no-surface` misclassification the whole
+ * design exists to prevent).
+ *
+ * - a `..` segment: `docs/../src/app.ts` matches `docs/**` as a string and means
+ *   `src/app.ts` as a file, so any glob verdict on it is meaningless;
+ * - the unparseable-header sentinel: a changed path whose identity is unknown.
+ */
+export function isOpaquePath(p) {
+  const s = normalizePath(p)
+  if (!s) return false
+  if (s.startsWith(UNPARSEABLE_PATH)) return true
+  return s.split('/').includes('..')
+}
+
+// ---- diff parsing ----------------------------------------------------------
+
+/**
+ * BOTH SIDES of every entry in a unified diff. Not "post-image paths" — that was the
+ * bug: a rename's pre-image is a path the diff DELETES, and dropping it let
+ * `git mv src/lib/auth.ts docs/auth-notes.md` classify `no-surface`.
+ *
+ * Per entry: take `a/` and `b/` from the `diff --git` header, then let an explicit
+ * `rename from`/`rename to` (and `copy from`/`copy to`, identical shape) OVERRIDE
+ * them — those lines are the unambiguous record, and the header is not: git emits
+ * unquoted spaces in it (`diff --git a/a b.ts b/b c.ts`), so the split is a guess.
+ * Emit `b`, plus `a` whenever it differs. An add and a delete both have `a === b`
+ * and yield one path; a copy's source is unmodified but is emitted anyway, because
+ * deny-by-default prefers one useless checklist over a dropped gate.
+ *
+ * A header this cannot split yields the UNPARSEABLE_PATH sentinel rather than nothing:
+ * a changed path of unknown identity must reach `unmatched`, not vanish. Quoted paths
+ * (`"a/x y.ts"`) are unquoted.
+ */
+export function pathsFromDiff(text) {
+  const out = []
+  const push = (p) => { const n = normalizePath(p); if (n && !out.includes(n)) out.push(n) }
+  let pending = null
+  const flush = () => {
+    if (!pending) return
+    push(pending.b)
+    if (pending.a && pending.a !== pending.b) push(pending.a)
+    pending = null
+  }
+  for (const line of String(text || '').split(/\r?\n/)) {
+    if (/^diff --git /.test(line)) {
+      flush()
+      const m = /^diff --git (?:"?a\/(.+?)"?) (?:"?b\/(.+?)"?)$/.exec(line)
+      pending = m ? { a: m[1], b: m[2] } : { a: null, b: `${UNPARSEABLE_PATH} ${line}` }
+      continue
+    }
+    if (!pending) continue
+    const from = /^(?:rename|copy) from (?:"?)(.+?)(?:"?)$/.exec(line)
+    if (from) { pending.a = from[1]; continue }
+    const to = /^(?:rename|copy) to (?:"?)(.+?)(?:"?)$/.exec(line)
+    if (to) { pending.b = to[1]; continue }
+  }
+  flush()
+  return out
+}
+
+/** True when the blob looks like a unified diff rather than a path list. */
+export function looksLikeDiff(text) {
+  return /^diff --git /m.test(String(text || ''))
+}
+
+// ---- classification --------------------------------------------------------
+
+/**
+ * Classify a unit's net diff. `paths` is the changed-path list (or use pathsFromDiff).
+ * Everything ambiguous fails toward `surface-bearing`.
+ */
+export function classifyScope(paths, config = DEFAULT_SCOPE_CLASS_CONFIG) {
+  const cfg = config && Array.isArray(config.classes) ? config : DEFAULT_SCOPE_CLASS_CONFIG
+  const kept = SCOPE_KEPT_OBLIGATIONS
+
+  if (!Array.isArray(paths) || paths.length === 0) {
+    return {
+      scopeClass: SURFACE_BEARING,
+      reason: Array.isArray(paths)
+        ? 'no paths in the net diff — nothing to classify, so it fails toward surface-bearing (deny-by-default)'
+        : 'the changed-path input was not a list — it fails toward surface-bearing (deny-by-default)',
+      paths: [], unmatched: [], matched: [], oracles: [], unproven: [],
+      highRisk: false, highRiskRaiseOnly: true, findings: [], ok: true, kept,
+    }
+  }
+
+  const classified = []
+  const unmatched = []
+  const byClass = new Map()
+  for (const raw of paths) {
+    const p = normalizePath(raw)
+    if (!p) continue
+    const cls = matchScopeClass(p, cfg)
+    classified.push({ path: p, class: cls ? cls.id : null })
+    if (!cls) { unmatched.push(p); continue }
+    if (!byClass.has(cls.id)) byClass.set(cls.id, { ...cls, paths: [] })
+    byClass.get(cls.id).paths.push(p)
+  }
+
+  if (!classified.length) {
+    return {
+      scopeClass: SURFACE_BEARING,
+      reason: 'no usable paths in the net diff — it fails toward surface-bearing (deny-by-default)',
+      paths: [], unmatched: [], matched: [], oracles: [], unproven: [],
+      highRisk: false, highRiskRaiseOnly: true, findings: [], ok: true, kept,
+    }
+  }
+
+  const matched = [...byClass.values()].map((m) => ({
+    id: m.id, paths: m.paths, oracle: m.oracle ?? null, unprovenReason: m.unprovenReason ?? null, highRisk: !!m.highRisk,
+  }))
+  const scopeClass = unmatched.length ? SURFACE_BEARING : NO_SURFACE
+
+  if (scopeClass === SURFACE_BEARING) {
+    return {
+      scopeClass,
+      reason: `${unmatched.length} path(s) match no configured non-runtime pattern — ${unmatched.slice(0, 5).join(', ')}${unmatched.length > 5 ? ', …' : ''}; one unmatched path is enough (deny-by-default)`,
+      paths: classified,
+      unmatched,
+      matched,
+      // The oracle requirement is scoped to the `no-surface` lane: a surface-bearing
+      // unit already owes the full breadth/depth gates, so raising an oracle finding
+      // there would be a second bill for the same obligation.
+      oracles: [], unproven: [], findings: [], ok: true,
+      highRisk: matched.some((m) => m.highRisk),
+      highRiskRaiseOnly: true,
+      kept,
+    }
+  }
+
+  const oracles = []
+  const unproven = []
+  const findings = []
+  for (const m of matched) {
+    const hasOracle = typeof m.oracle === 'string' && m.oracle.trim().length > 0
+    const declaredUnproven = !hasOracle && typeof m.unprovenReason === 'string' && m.unprovenReason.trim().length > 0
+    if (hasOracle) oracles.push({ class: m.id, oracle: m.oracle })
+    else if (declaredUnproven) unproven.push({ class: m.id, reason: m.unprovenReason })
+    else {
+      findings.push({
+        code: 'oracle-undeclared',
+        severity: 'blocking',
+        class: m.id,
+        paths: m.paths,
+        message: `scope class "${m.id}" matched ${m.paths.length} path(s) but declares no oracle — the oracle REPLACES the checklist, it is not a waiver. Declare an oracle command for "${m.id}" in coverage.config.json → scopeClass, or declare it unproven-by-design (oracle: null + unprovenReason) and say so in the Review Contract.`,
+      })
+    }
+  }
+
+  const names = matched.map((m) => m.id).sort()
+  return {
+    scopeClass,
+    reason: `every path in the net diff matches a configured non-runtime pattern (${names.join(', ')}) — no runtime surface changed`,
+    paths: classified,
+    unmatched: [],
+    matched,
+    oracles,
+    unproven,
+    findings,
+    ok: findings.length === 0,
+    // The risk auto-flag: merge/CI/deploy/IAM paths are config-only AND high-risk.
+    // RAISE-ONLY — a consumer ORs this into the unit's existing flag and NEVER writes
+    // `false` back over a set one (the orchestrator's manifest write enforces that).
+    highRisk: matched.some((m) => m.highRisk),
+    highRiskRaiseOnly: true,
+    kept,
+  }
+}
+
+// ---- what the class derives downstream -------------------------------------
+
+/**
+ * The smoke `not-applicable` REASON, derived from the scope class — never written
+ * per run. `no-surface` keeps the existing `gates.smoke = 'not-applicable'` +
+ * `smokeNotApplicableReason` path (a reasoned N/A reaches ALIVE, an unreasoned one
+ * stays DEAD); it is NOT a new skip path. Returns null for a surface-bearing unit,
+ * which still owes a real ALIVE.
+ */
+export function scopeSmokeReason(result) {
+  if (!result || result.scopeClass !== NO_SURFACE) return null
+  const names = (result.matched || []).map((m) => m.id).sort().join(', ')
+  return `scopeClass: no-surface — the net diff is entirely ${names} (no runtime surface to boot); proven instead by its declared oracle(s)`
+}
+
+const INAPPLICABLE = [
+  ['coverage-checklist', '`coverage-checklist.mjs generate` / `validate`', 'no surface rows to fill'],
+  ['coverage-ledger', '`coverage-ledger.mjs validate`', 'nothing enters the surface inventory'],
+  ['presentation-sweep', 'e2e route manifest + presentation sweep', 'no browser route changed'],
+  ['test-criteria', 'TDD mode + the create-mode test-criteria gate', 'no behavioural surface to write criteria against — the declared oracle is the proof instead'],
+]
+
+/**
+ * The Review Contract rows a `no-surface` unit records `Not applicable` WITH a
+ * scope-derived reason — never generated-then-marked-N/A. Empty for a surface-bearing
+ * unit. Nothing on this list is a review-depth obligation, and the tests assert that:
+ * scan-diff, CI, the independent review and delivery are in SCOPE_KEPT_OBLIGATIONS.
+ */
+export function inapplicableArtifacts(result) {
+  if (!result || result.scopeClass !== NO_SURFACE) return []
+  const names = (result.matched || []).map((m) => m.id).sort().join(', ')
+  return INAPPLICABLE.map(([id, artifact, why]) => ({
+    id,
+    artifact,
+    reason: `Not applicable — scopeClass: no-surface (${names}): ${why}`,
+  }))
+}
+
+// ---- CLI -------------------------------------------------------------------
+
+function readPaths(flags) {
+  let raw = ''
+  if (flags.stdin) raw = fs.readFileSync(0, 'utf8')
+  else if (flags.paths) raw = fs.readFileSync(flags.paths, 'utf8')
+  else if (flags.diff) {
+    const base = execFileSync('git', ['merge-base', flags.diff, 'HEAD'], { encoding: 'utf8' }).trim()
+    // `--no-renames` is load-bearing, not tidiness: with rename detection on (git's
+    // default), `--name-only` collapses a rename to its post-image alone, so a source
+    // file moved out of a runtime tree is a deletion this classifier never sees — the
+    // same hole pathsFromDiff closes, one layer up. Off, git reports the delete and
+    // the add separately and both sides reach the classifier.
+    raw = execFileSync('git', ['diff', '--name-only', '--no-renames', `${base}...HEAD`], { encoding: 'utf8' })
+  } else return null
+  if (looksLikeDiff(raw)) return pathsFromDiff(raw)
+  return raw.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)
+}
+
+function main() {
+  const argv = process.argv.slice(2)
+  const cmd = argv[0]
+  const flags = {}
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') flags.json = true
+    else if (a === '--stdin') flags.stdin = true
+    else if (a === '--diff') flags.diff = argv[++i]
+    else if (a === '--paths') flags.paths = argv[++i]
+    else if (a === '--config') flags.config = argv[++i]
+    else if (a === '--root') flags.root = argv[++i]
+    else { console.error(`scope-class: unrecognized flag "${a}"`); process.exit(2) }
+  }
+  const config = loadScopeClassConfigFromFile(flags.config, flags.root || process.cwd())
+
+  if (cmd === 'table') {
+    if (flags.json) console.log(JSON.stringify(config, null, 2))
+    else {
+      console.log('| class | patterns | oracle | high-risk |')
+      console.log('|---|---|---|---|')
+      for (const c of config.classes) {
+        console.log(`| ${c.id} | ${c.patterns.join(', ')} | ${c.oracle || `none — ${c.unprovenReason || 'UNDECLARED (blocking)'}`} | ${c.highRisk ? 'yes' : 'no'} |`)
+      }
+    }
+    process.exit(0)
+  }
+
+  if (cmd !== 'classify') {
+    console.error('usage: scope-class.mjs <classify|table> [--diff <base>|--stdin|--paths <file>] [--json] [--config <file>] [--root <dir>]')
+    process.exit(2)
+  }
+
+  const paths = readPaths(flags)
+  if (paths === null) { console.error('scope-class: classify needs one of --diff <base>, --stdin, --paths <file>'); process.exit(2) }
+  const result = classifyScope(paths, config)
+  const smoke = scopeSmokeReason(result)
+  const payload = { ...result, smokeNotApplicableReason: smoke, inapplicable: inapplicableArtifacts(result) }
+
+  if (flags.json) console.log(JSON.stringify(payload, null, 2))
+  else {
+    console.log(`scopeClass: ${result.scopeClass}${result.highRisk ? '  highRisk: true (auto-flag, raise-only)' : ''}`)
+    console.log(`  ${result.reason}`)
+    for (const o of result.oracles) console.log(`  oracle [${o.class}]: ${o.oracle}`)
+    for (const u of result.unproven) console.log(`  unproven [${u.class}]: ${u.reason}`)
+    if (smoke) console.log(`  smokeNotApplicableReason: ${smoke}`)
+    for (const row of payload.inapplicable) console.log(`  ${row.artifact} → ${row.reason}`)
+    for (const f of result.findings) console.log(`  ** BLOCKING (${f.code}): ${f.message}`)
+  }
+  process.exit(result.findings.length ? 1 : 0)
+}
+
+let launchedDirectly = false
+let mainModuleError = null
+try {
+  const { isMainModule } = await import('../../engineering-runtime/scripts/main-module.mjs')
+  if (typeof isMainModule !== 'function') throw new Error('main-module.mjs does not export isMainModule')
+  launchedDirectly = isMainModule(import.meta.url)
+} catch (error) {
+  mainModuleError = error
+  try {
+    launchedDirectly = fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    launchedDirectly = false
+  }
+}
+
+if (launchedDirectly && mainModuleError) {
+  console.error(`scope-class: cannot load engineering-runtime main-module helper: ${mainModuleError.message}`)
+  process.exitCode = 1
+} else if (launchedDirectly) {
+  main()
+}

package/skills/engineering/harness-runtime/LICENSE

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

package/skills/engineering/harness-runtime/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: harness-runtime
+description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
+disable-model-invocation: true
+user-invocable: false
+---
+
+# Harness Runtime
+
+This support-only runtime package exposes shared programmatic contracts plus canonical model discovery and model-catalog utilities. It ships the team catalog baseline; per-harness user files carry only explicit confirmed overrides. It has no user or model-invocable workflow.
+
+## Package Map
+
+- `contracts.md` defines the neutral values, planner boundary, discovery handoff, and topology rules.
+- `native-question-contracts.md` pins the Pi, Codex, and Claude Code adapter schemas and response behavior.
+- `index.mjs` exports neutral constructors plus pure question planning and response normalization.
+- `discover-models.mjs` enumerates model evidence; `model-catalog.mjs` manages per-harness classifications.
+- `references/model-catalog.md` documents catalog policy; `bin/` contains the installed command wrappers.

package/skills/engineering/harness-runtime/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Harness Runtime"
+  short_description: "Internal harness-neutral support package"
+
+policy:
+  allow_implicit_invocation: false

package/skills/engineering/harness-runtime/bin/discover-models.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../discover-models.mjs'
+
+process.exit(runCli(process.argv.slice(2)))

package/skills/engineering/harness-runtime/bin/model-catalog.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../model-catalog.mjs'
+
+process.exit(runCli(process.argv.slice(2)))

package/skills/engineering/harness-runtime/contracts.md

@@ -0,0 +1,15 @@
+# Harness runtime contracts
+
+`index.mjs` exports four neutral constructors: `defineCurrentTurnCapabilities`, `defineQuestionSpec`, `defineQuestionAnswers`, and `defineModelAvailability`. It also exports the pure adapter layer, `planStructuredQuestions` and `normalizeQuestionResponses`. Model enumeration and persistence are separate entrypoints in `discover-models.mjs` and `model-catalog.mjs`; they are not re-exported from `index.mjs`.
+
+The runtime accepts current-turn capabilities as explicit input. It never infers native tools or spawn-model ids from training data or static configuration.
+
+Question and answer values are harness-neutral immutable data. `planStructuredQuestions` selects only an advertised Pi, Codex, or Claude Code question tool, validates its native limits, orders recommendations, and emits deterministic payload batches. After all adapter-specific label and response-format transformations, each native representation must identify exactly one neutral stable option id; collisions fail before emission with structured `invalid-question` details. `normalizeQuestionResponses` maps unique native labels and custom text back to frozen `{ questionId: answers[] }` values and rejects duplicate mappings instead of choosing one. See `native-question-contracts.md` for the pinned schemas, adapter rules, response fixtures, and cancellation behavior.
+
+Model discovery unions explicit current-turn spawn ids and human-named runnable ids with configured or credentialed evidence. Its `{ discovered: [{ id, source }] }` output is evidence, not a neutral model-availability value: callers map each item to `{ id, sources: [source] }`, preserve `harness` and `completeness`, then pass that shape to `defineModelAvailability`; discovery `notes` remain operator diagnostics. Pi labels configuration discovery `full` even when it finds no runnable ids because its credential-aware configuration is the complete evidence class. Codex and Claude Code static configuration remains partial unless current-turn or runtime-enumeration evidence completes it. Catalog writes remain isolated to each harness's user directory, and the installation-relative team seed is read-only.
+
+Shell code cannot invoke a native question tool inside the agent's current turn. It may validate and plan data; the agent performs each planned native tool call and passes the responses back for normalization.
+
+When no supported native question tool is advertised, concise free-text input is permitted only for one optionless question. Textual multiple-choice emulation is forbidden. Unsupported multi-select and all secret input fail explicitly rather than degrading silently.
+
+Model discovery and catalog persistence remain separate from question planning. Current-turn tool availability is never inferred from model or harness configuration. Source-tree imports outside `skills/engineering` are unsupported until an installation-aware adapter entrypoint exists; consumers must not copy the runtime to work around that boundary.