@renzrollon/interlock 1.0.0

package/lib/ship-stage.mjs

@@ -0,0 +1,223 @@
+// The stage marker — the one channel from a ship run to the stateless
+// `PreToolUse` guards that fire in a different process.
+//
+// A hook cannot ask the workflow "what stage are we in". It shares no memory
+// with `workflows/ship.js`, it is spawned per tool call, and env vars do not
+// survive across the separate subagent processes the workflow spawns. The only
+// thing that reliably spans the run process and the hook process is the
+// filesystem. So the run PUBLISHES its stage to a file, and the guard READS it.
+//
+// Three properties are load-bearing, and they mirror lib/doctor.mjs's own:
+//
+//   1. NEVER THROWS. A guard whose own crash blocks a tool call is worse than
+//      no guard. Every function here collapses a failure to a value: a write
+//      error returns a warning object, an absent or malformed marker reads back
+//      as `{ stage: 'unknown' }`. The caller decides; this module never throws
+//      the decision away as an exception.
+//
+//   2. AN UNKNOWN IS NOT A STAGE. A marker that is absent, unparseable, carries
+//      a stage outside the known set, or is stale resolves to `stage: 'unknown'`
+//      — never to the nearest known stage. The edit guards fail OPEN on unknown
+//      (see the stage-guard spec): treating a marker we could not trust as a
+//      real stage is exactly the false-positive that would brick ordinary TDD
+//      the moment the plugin is installed.
+//
+//   3. STALENESS NARROWS, IT DOES NOT CLOSE. A run that is killed before it can
+//      clear its marker leaves the file behind. Two signals catch that orphan:
+//      `pid` (is the run's process still alive?) and `index` (is this marker's
+//      write count the current run's, or one an abandoned run left?). Neither is
+//      trusted alone — pids recycle, and an index has no meaning without a
+//      caller that knows the current run's count — but together they narrow the
+//      window in which a leftover `remediation` marker could spuriously block an
+//      edit in a later session. They do not close it, and the guards' fail-open
+//      default is what makes that residual window safe rather than harmful.
+//
+// WHO WRITES IT. Not a driver. `lib/prompts/stage.mjs` renders the publish
+// fragment from THIS module's own `stagePath`, `MARKER_FIELDS` and `STAGES`, and
+// the agent performing each step writes the file as it enters the stage — so the
+// path and JSON shape have exactly one definition, here, and no driver carries a
+// second copy of them. `test/spine/ship-stage-drift.test.mjs` asserts that: it
+// fails if any driver declares a marker literal at all.
+//
+// WHO CLEARS IT. `runClose` in `lib/run.mjs`, on every terminal path — the
+// program routes a halt through `run close --halt` and both drivers' `stop()`
+// call it, so the clean close and the halt clear the same way. A clear that
+// fails is spoken as a degradation, never as an exit code: the marker is a guard
+// input, not a gate.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The stages a run publishes. A marker holding anything else reads as unknown. */
+export const STAGES = Object.freeze(['implement', 'verify', 'review', 'remediation', 'fix-tests', 'commit'])
+
+/** The fields a marker carries. The workflow's duplicated literal must match. */
+export const MARKER_FIELDS = Object.freeze(['stage', 'change', 'index', 'pid'])
+
+/** Root of the per-run state tree the doctor already probes for writability. */
+export const SHIP_DIR = join('.claude', 'ship')
+
+/** The marker filename under `<SHIP_DIR>/<change>/`. */
+export const MARKER_FILE = 'stage.json'
+
+/** The reading returned whenever no trustworthy stage can be established. */
+export const UNKNOWN = Object.freeze({ stage: 'unknown' })
+
+/**
+ * The marker path for a change: `.claude/ship/<change>/stage.json`, rooted at
+ * `root` (default cwd). The only derivation of it: `lib/prompts/stage.mjs`
+ * renders the agent's publish fragment from this function, and the drift test
+ * fails if a driver ever declares the path as a literal of its own.
+ */
+export function stagePath(change, root = '.') {
+  return join(root, SHIP_DIR, String(change), MARKER_FILE)
+}
+
+/** Is `pid` a live process? A probe, not a gate — any error resolves to a boolean. */
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    // Signal 0 performs the permission/existence check without delivering a
+    // signal. ESRCH means no such process; EPERM means it exists but is not
+    // ours, which for a liveness question still counts as alive.
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err && err.code === 'EPERM'
+  }
+}
+
+/**
+ * Publish `stage` for `change`. Reads any existing marker to advance `index`
+ * monotonically, then writes `{ stage, change, index, pid }`. Records `pid` as
+ * this process's id — in a ship run the writer is a step agent whose parent is
+ * the run session, so the recorded pid is alive for the run and dead once the
+ * session ends, which is the signal a later session uses to reject an orphan.
+ *
+ * Never throws. On any filesystem error returns `{ ok: false, warning }` so the
+ * run can record a non-fatal note and continue — the marker is a guard input,
+ * not a gate the run itself depends on.
+ *
+ * @returns {{ ok: true, marker: object } | { ok: false, warning: string }}
+ */
+export function writeStage(change, stage, opts = {}) {
+  const root = opts.root || '.'
+  const pid = Number.isInteger(opts.pid) ? opts.pid : process.pid
+  const path = stagePath(change, root)
+  let index = 1
+  try {
+    const prior = readMarkerFile(path)
+    if (prior && Number.isInteger(prior.index) && prior.index > 0) index = prior.index + 1
+  } catch {
+    // A prior marker we cannot read is not a reason to refuse to write a new
+    // one — start the counter fresh rather than throw.
+    index = 1
+  }
+  const marker = { stage, change, index, pid }
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(marker) + '\n')
+    return { ok: true, marker }
+  } catch (err) {
+    return { ok: false, warning: `stage marker unwritable at ${path}: ${(err && err.message) || String(err)}` }
+  }
+}
+
+/** Read and parse one marker file. Returns null on absence or malformed JSON. */
+function readMarkerFile(path) {
+  let raw
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+  try {
+    const value = JSON.parse(raw)
+    return value && typeof value === 'object' ? value : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read the current ship stage, for a guard that knows only the filesystem.
+ *
+ * With no change name (the hook's situation) it scans `.claude/ship/*` for
+ * markers and returns the freshest live one. A marker is LIVE when its `pid` is
+ * still a running process; a marker whose process is gone is treated as an
+ * orphan and ignored. Among live markers the highest `index` wins — that is the
+ * most recent transition. When a caller knows the current run's write count it
+ * passes `minIndex`, and any marker whose `index` is below it is rejected as a
+ * leftover from an earlier run.
+ *
+ * Returns `{ stage: 'unknown' }` when nothing trustworthy is found: no marker,
+ * malformed marker, unrecognized stage value, dead pid, or stale index. Never
+ * throws — a scan that blows up is an unknown stage, not an exception.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.root]         project root (default cwd)
+ * @param {string} [opts.change]       read only this change's marker
+ * @param {number} [opts.minIndex]     reject markers whose index is below this
+ * @param {(pid:number)=>boolean} [opts.isAlive]  liveness probe (injected in tests)
+ * @returns {{ stage: string, change?: string, index?: number, pid?: number, reason?: string }}
+ */
+export function readStage(opts = {}) {
+  const root = opts.root || '.'
+  const isAlive = typeof opts.isAlive === 'function' ? opts.isAlive : processAlive
+  const minIndex = Number.isInteger(opts.minIndex) ? opts.minIndex : null
+
+  let paths
+  try {
+    if (opts.change) {
+      paths = [stagePath(opts.change, root)]
+    } else {
+      const base = join(root, SHIP_DIR)
+      if (!existsSync(base)) return { ...UNKNOWN }
+      paths = readdirSync(base, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => join(base, e.name, MARKER_FILE))
+    }
+  } catch {
+    return { ...UNKNOWN }
+  }
+
+  let best = null
+  for (const path of paths) {
+    const marker = readMarkerFile(path)
+    if (!marker) continue
+    if (!STAGES.includes(marker.stage)) continue // unrecognized stage → not a match
+    if (!Number.isInteger(marker.index) || marker.index <= 0) continue
+    if (minIndex !== null && marker.index < minIndex) continue // stale: behind the current run
+    if (!isAlive(marker.pid)) continue // orphaned: the run that wrote it is gone
+    if (!best || marker.index > best.index) best = marker
+  }
+
+  if (!best) return { ...UNKNOWN }
+  return { stage: best.stage, change: best.change, index: best.index, pid: best.pid }
+}
+
+/**
+ * Remove a change's marker. Called on every terminal path of a run so no stage
+ * leaks into the next session. Never throws — an already-absent marker is
+ * success, and a marker we cannot delete becomes a warning, not a crash.
+ *
+ * @returns {{ ok: true } | { ok: false, warning: string }}
+ */
+export function clearStage(change, opts = {}) {
+  const path = stagePath(change, opts.root || '.')
+  try {
+    rmSync(path, { force: true })
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, warning: `stage marker not cleared at ${path}: ${(err && err.message) || String(err)}` }
+  }
+}
+
+// Kept for callers that want to know a marker exists without interpreting it.
+export function markerExists(change, root = '.') {
+  try {
+    return statSync(stagePath(change, root)).isFile()
+  } catch {
+    return false
+  }
+}

package/lib/spill.mjs

@@ -0,0 +1,150 @@
+// Spill store for oversized verify output (add-ship-run-inspectability §3).
+//
+// A unit suite's combined stdout/stderr can run into hundreds of KB. Pasting
+// that into a verify agent's structured result would blow past the very
+// token-economy rules the ship loop exists to enforce. This module writes the
+// full bytes to a stable on-disk locator once, and hands back a head-and-tail
+// preview plus a hash — the caller's result object carries the locator and
+// preview, never the full text.
+//
+// Not a dsh `ctx.spillStore`, not a generic tool-result bus: one function, one
+// directory layout, consumed by the verify CLI helper (task 3.3). This module
+// never judges pass/fail — that stays in `lib/verify.mjs`, which stays pure.
+//
+// Exposed to skills indirectly via `interlock verify` (spill wiring lands in
+// task 3.3); this module is pure I/O with no agent, no fs-reading-back.
+
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { join, posix as pathPosix } from 'node:path'
+import { createHash } from 'node:crypto'
+import { LIMITS } from './limits.mjs'
+
+/** Where spilled suite output lives, relative to the repo root, POSIX-joined. */
+export const SPILL_DIR = '.claude/ship/spill'
+
+// Falls back to the design's pinned default if `lib/limits.mjs` has not yet
+// grown `verifyPreviewChars` (see task 3.1) — keeps this module usable
+// independent of load order, without restating the number as policy.
+const DEFAULT_PREVIEW_CHARS = 4096
+
+/**
+ * Is this output big enough to spill?
+ *
+ * The threshold `interlock limits` prints, read here rather than described in
+ * prose. It used to be a sentence in a prompt — "if a check's combined
+ * stdout/stderr exceeds the spill threshold" — with the number itself living
+ * only in `LIMITS.verifySpillBytes` and in a test asserting it equals 8192. A
+ * cap whose only reader is a test pinning its value is not an enforced cap; it
+ * just looks like one.
+ *
+ * @param {string|Buffer|number} output the bytes, or a byte count
+ * @param {{threshold?: number}} [opts]
+ * @returns {boolean} true when the caller must spill rather than inline
+ */
+export function shouldSpill(output, opts = {}) {
+  const threshold =
+    Number.isInteger(opts.threshold) && opts.threshold >= 0
+      ? opts.threshold
+      : (LIMITS.verifySpillBytes ?? 8192)
+  return byteLength(output) > threshold
+}
+
+function byteLength(output) {
+  if (typeof output === 'number') return Number.isFinite(output) ? output : 0
+  if (Buffer.isBuffer(output)) return output.length
+  return Buffer.byteLength(String(output ?? ''), 'utf8')
+}
+
+function safeSegment(value, fallback) {
+  const s = typeof value === 'string' ? value.trim() : ''
+  const cleaned = s.replace(/[^a-zA-Z0-9._-]/g, '-')
+  return cleaned.length ? cleaned : fallback
+}
+
+// Next seq for this run's spill directory: contiguous, starting at 1, derived
+// from what is already on disk rather than threaded through by the caller —
+// `spillBytes`'s only inputs are the run id, the kind, and the bytes.
+function nextSeq(dirAbs) {
+  if (!existsSync(dirAbs)) return 1
+  let max = 0
+  for (const name of readdirSync(dirAbs)) {
+    const m = /^(\d+)-/.exec(name)
+    if (m) max = Math.max(max, Number(m[1]))
+  }
+  return max + 1
+}
+
+/**
+ * Build a head-and-tail preview with an explicit omission marker, so a model
+ * can see the start of a failure and its summary line without loading the
+ * middle of the suite output.
+ *
+ * @param {string} text - full decoded content
+ * @param {number} bytes - byte length of the full content
+ * @param {string} locator - repo-relative POSIX path the full bytes live at
+ * @param {number} previewChars - total character budget for the preview
+ * @returns {{ preview: string, truncated: boolean }}
+ */
+export function buildPreview(text, bytes, locator, previewChars = DEFAULT_PREVIEW_CHARS) {
+  if (text.length <= previewChars) {
+    return { preview: text, truncated: false }
+  }
+  const marker = `\n…[spilled ${bytes} bytes, locator=${locator}]…\n`
+  const half = Math.max(0, Math.floor((previewChars - marker.length) / 2))
+  const head = text.slice(0, half)
+  const tail = half > 0 ? text.slice(text.length - half) : ''
+  return { preview: `${head}${marker}${tail}`, truncated: true }
+}
+
+/**
+ * Write verify output to `.claude/ship/spill/<runId>/<seq>-<kind>.log` and
+ * return a locator plus a bounded preview so callers never have to paste the
+ * full bytes into an agent-facing result.
+ *
+ * Never throws on its own account beyond what `mkdirSync`/`writeFileSync`
+ * raise for a genuinely unwritable tree — spill is only ever called from an
+ * impure CLI helper (task 3.3) that decides how to report that upward.
+ *
+ * The returned record carries `overThreshold`, computed by `shouldSpill` from
+ * `LIMITS.verifySpillBytes`, so the caller can report a step that spilled
+ * output it did not have to — and so the published threshold has a reader on
+ * the path it governs.
+ *
+ * @param {string} root - repo root
+ * @param {{ runId: string, kind: string, bytes: string|Buffer, previewChars?: number }} opts
+ * @returns {{ locator: string, bytes: number, overThreshold: boolean, threshold: number,
+ *   preview: string, truncated: boolean, sha256: string }}
+ */
+export function spillBytes(root, { runId, kind, bytes, previewChars } = {}) {
+  const runSeg = safeSegment(runId, 'unknown-run')
+  const kindSeg = safeSegment(kind, 'output')
+  const budget = Number.isInteger(previewChars)
+    ? previewChars
+    : (LIMITS.verifyPreviewChars ?? DEFAULT_PREVIEW_CHARS)
+
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes ?? ''), 'utf8')
+
+  const dirRel = pathPosix.join(SPILL_DIR, runSeg)
+  const dirAbs = join(root, ...dirRel.split('/'))
+  mkdirSync(dirAbs, { recursive: true })
+
+  const seq = nextSeq(dirAbs)
+  const fileName = `${seq}-${kindSeg}.log`
+  const locator = pathPosix.join(dirRel, fileName)
+  const fileAbs = join(dirAbs, fileName)
+
+  writeFileSync(fileAbs, buf)
+
+  const sha256 = createHash('sha256').update(buf).digest('hex')
+  const { preview, truncated } = buildPreview(buf.toString('utf8'), buf.length, locator, budget)
+
+  return {
+    locator,
+    bytes: buf.length,
+    overThreshold: shouldSpill(buf),
+    threshold: LIMITS.verifySpillBytes ?? 8192,
+    preview,
+    truncated,
+    sha256
+  }
+}

package/lib/surface.mjs

@@ -0,0 +1,195 @@
+// Deterministic UI-surface classifier for a set of changed files.
+//
+// This question used to be answered twice, in English prose, by two skills that
+// disagreed: the manual-test-plan skill asked the model to re-derive a tri-state
+// UI-TESTABLE / UI-INDIRECT / NOT-UI-TESTABLE split on every run, while the
+// devops review dimension made a looser, separate binary judgement about whether
+// a change is "purely UI/frontend" and can be skipped. Same inputs, two
+// hand-rolled answers, no reason for them to agree. This module replaces both
+// prose implementations with one pure function so the tri-state and the devops
+// skip decision are derived from the same rules, reproducibly, with no model
+// call.
+//
+// Exposed to skills as `interlock surface --changed <files...>`.
+//
+// Path + extension logic only: no fs, no git, no agent, no I/O, no clock.
+// Paths are repo-relative and POSIX-separated ('/').
+
+export const UI_TESTABLE = 'UI-TESTABLE'
+export const UI_INDIRECT = 'UI-INDIRECT'
+export const NOT_UI_TESTABLE = 'NOT-UI-TESTABLE'
+
+// --- rule tables ---------------------------------------------------------
+
+const TEST_DIRS = new Set(['__tests__', 'e2e', 'tests', 'cypress', 'playwright'])
+const DOC_EXTS = new Set(['md', 'mdx', 'txt'])
+const DOC_DIRS = new Set(['docs', 'openspec'])
+const CONFIG_EXTS = new Set(['json', 'yml', 'yaml', 'toml', 'ini', 'lock'])
+const TOOLING_DIRS = new Set(['scripts', 'tools'])
+
+const UI_EXTS = new Set(['tsx', 'jsx', 'vue', 'svelte'])
+const UI_DIRS = new Set(['app', 'pages', 'components', 'views', 'screens'])
+const STYLE_EXTS = new Set(['css', 'scss', 'sass', 'less', 'styl'])
+
+const STATE_DIRS = new Set(['hooks', 'store', 'stores', 'context', 'providers', 'reducers', 'selectors'])
+const DATA_DIRS = new Set(['lib', 'services', 'models', 'schemas', 'db', 'prisma', 'graphql', 'resolvers', 'controllers', 'middleware'])
+
+// Dependency manifests that make a change infra-relevant regardless of class.
+const DEP_MANIFESTS = new Set(['package.json', 'requirements.txt', 'go.mod', 'cargo.toml'])
+
+// --- helpers -------------------------------------------------------------
+
+// Tolerate junk entries: non-strings become '', surrounding space is trimmed,
+// and any number of leading './' segments are stripped.
+function normalize(entry) {
+  if (typeof entry !== 'string') return ''
+  let p = entry.trim()
+  while (p.startsWith('./')) p = p.slice(2)
+  return p
+}
+
+// Split a normalized path once into the pieces every rule needs. Directory
+// segments and the basename are compared lowercased so that Components/ and
+// components/, Dockerfile and dockerfile, behave the same.
+function parts(path) {
+  const segments = path.split('/').filter(Boolean)
+  const base = segments.length ? segments[segments.length - 1] : ''
+  const dirs = segments.slice(0, -1).map(s => s.toLowerCase())
+  const lower = base.toLowerCase()
+  const dot = lower.lastIndexOf('.')
+  const ext = dot > 0 ? lower.slice(dot + 1) : ''
+  return { dirs, lower, ext }
+}
+
+const notUI = (reason) => ({ class: NOT_UI_TESTABLE, reason, apiRoute: false })
+const uiTestable = (reason) => ({ class: UI_TESTABLE, reason, apiRoute: false })
+const uiIndirect = (reason, apiRoute = false) => ({ class: UI_INDIRECT, reason, apiRoute })
+
+// Classify one path. Order is load-bearing: exclusions, then route/API
+// handlers, then UI-TESTABLE, then UI-INDIRECT, then default.
+function classifyOne(p) {
+  const { dirs, lower, ext } = p
+  const inDir = (set) => dirs.find(d => set.has(d))
+
+  // 1. NOT-UI-TESTABLE exclusions run first so that tests/, docs/ and tooling
+  //    beat the UI rules — tests/components/Foo.tsx is a test, not a component.
+  if (/\.(test|spec)\./.test(lower)) return notUI('test file')
+  const testDir = inDir(TEST_DIRS)
+  if (testDir) return notUI(`test dir ${testDir}/`)
+  if (DOC_EXTS.has(ext)) return notUI('docs file')
+  const docDir = inDir(DOC_DIRS)
+  if (docDir) return notUI(`docs dir ${docDir}/`)
+  if (lower === 'license' || lower.startsWith('changelog')) return notUI('docs file')
+
+  // tailwind.config.* is the one config file with a user-visible effect, so it
+  // is carved out ahead of every config/tooling exclusion below.
+  const isTailwind = lower.startsWith('tailwind.config.')
+  if (!isTailwind) {
+    if (lower.startsWith('.') || dirs.some(d => d.startsWith('.'))) return notUI('dotfile or dot dir')
+    if (CONFIG_EXTS.has(ext)) return notUI('config file')
+    const toolDir = inDir(TOOLING_DIRS)
+    if (toolDir) return notUI(`tooling dir ${toolDir}/`)
+    if (lower.startsWith('dockerfile')) return notUI('container config')
+    if (lower === 'makefile') return notUI('build tooling')
+    if (/\.config\.[^.]+$/.test(lower)) return notUI('config file')
+  }
+
+  if (lower === 'types.ts' || lower.endsWith('.d.ts')) return notUI('type-only file')
+  if (dirs.includes('types')) return notUI('type-only dir types/')
+
+  // 2. Request handlers, checked ahead of the UI rules: a file under app/ or
+  //    pages/ that serves a request is reachable only via UI side-effects.
+  //    Server actions belong here too — manual-test-plan names them explicitly
+  //    as UI-INDIRECT, and review-code counts them toward the devops review
+  //    alongside API routes ("no new API routes or Server Actions").
+  if (dirs.includes('api')) return uiIndirect('API route path', true)
+  if (lower === 'route.ts' || lower === 'route.js') return uiIndirect('route handler', true)
+  if (lower.startsWith('+server.')) return uiIndirect('server endpoint', true)
+  if (dirs.includes('actions') || dirs.includes('server-actions')) return uiIndirect('server actions', true)
+  if (lower === 'actions.ts' || lower === 'actions.js') return uiIndirect('server actions', true)
+  if (lower.endsWith('.server.ts')) return uiIndirect('server module', true)
+
+  // 3. UI-TESTABLE — directly user-visible surface.
+  if (UI_EXTS.has(ext)) return uiTestable(`.${ext} component`)
+  const uiDir = inDir(UI_DIRS)
+  if (uiDir) return uiTestable(`under ${uiDir}/`)
+  if (STYLE_EXTS.has(ext)) return uiTestable('style file')
+  if (isTailwind) return uiTestable('tailwind config')
+
+  // 4. UI-INDIRECT — reachable only through UI side-effects. Server actions and
+  //    server modules are handled in rule 2 so they escape the UI directories;
+  //    what remains here is state and data-layer code outside app/ and pages/.
+  const stateDir = inDir(STATE_DIRS)
+  if (stateDir) return uiIndirect(`under ${stateDir}/`)
+  const dataDir = inDir(DATA_DIRS)
+  if (dataDir) return uiIndirect(`under ${dataDir}/`)
+
+  // 5. Nothing matched — assume no user-visible effect.
+  return notUI('no UI surface match')
+}
+
+// review-devops' "purely UI/frontend, skip" rule, inverted: does this one file
+// suggest infra impact? Independent of the tri-state class except that any
+// API-route file counts.
+function suggestsInfraImpact(p, record) {
+  const { dirs, lower, ext } = p
+  if (record.apiRoute) return true
+  if (DEP_MANIFESTS.has(lower)) return true
+  if (ext === 'lock') return true
+  if (lower.startsWith('.env')) return true
+  if (lower === '.gitlab-ci.yml') return true
+  if (lower.startsWith('dockerfile') || lower.startsWith('docker-compose')) return true
+  const gh = dirs.indexOf('.github')
+  if (gh !== -1 && dirs[gh + 1] === 'workflows') return true
+  return false
+}
+
+// --- public API ----------------------------------------------------------
+
+// Classify an array of repo-relative path strings into the manual-test-plan
+// tri-state, plus the rollups both callers need.
+//
+// Returns {
+//   files: [{ path, class, reason, infra }],  // normalized path, one entry per usable input
+//                                       // `infra` is this file's own infra-impact
+//                                       // verdict — the per-file half of the
+//                                       // needsDevopsReview rollup, carried so a
+//                                       // caller naming the triggering paths does
+//                                       // not re-run the classifier per path
+//   hasUI,                              // any UI_TESTABLE or UI_INDIRECT
+//   uiCount, indirectCount, backendCount,
+//   needsManualTestPlan,                // === hasUI
+//   needsDevopsReview                   // inverse of review-devops' skip rule
+// }
+export function classifySurface(changedFiles) {
+  const list = Array.isArray(changedFiles) ? changedFiles : []
+  const files = []
+  let uiCount = 0
+  let indirectCount = 0
+  let backendCount = 0
+  let needsDevopsReview = false
+
+  for (const entry of list) {
+    const path = normalize(entry)
+    if (!path) continue
+    const p = parts(path)
+    const record = classifyOne(p)
+    const infra = suggestsInfraImpact(p, record)
+    files.push({ path, class: record.class, reason: record.reason, infra })
+    if (record.class === UI_TESTABLE) uiCount += 1
+    else if (record.class === UI_INDIRECT) indirectCount += 1
+    else backendCount += 1
+    if (infra) needsDevopsReview = true
+  }
+
+  const hasUI = uiCount > 0 || indirectCount > 0
+  return {
+    files,
+    hasUI,
+    uiCount,
+    indirectCount,
+    backendCount,
+    needsManualTestPlan: hasUI,
+    needsDevopsReview
+  }
+}