@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/production-endpoints.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { normalizeReleaseVerdict } from '../../resolve-issues/scripts/release-state-contract.mjs'
+
+export const PRODUCTION_ENDPOINTS_SCHEMA_VERSION = 1
+export const DEFAULT_FLOOR_FRESHNESS_MINUTES = 30
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+export function normalizeProductionUrl(value) {
+  if (!nonEmpty(value)) throw new Error('endpoint URL must be a non-empty HTTPS URL')
+  let parsed
+  try {
+    parsed = new URL(value.trim())
+  } catch {
+    throw new Error('endpoint URL must be a non-empty HTTPS URL')
+  }
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error('endpoint URL must use HTTPS and must not contain credentials, query, or fragment')
+  }
+  const pathname = parsed.pathname.replace(/\/+$/, '')
+  return `${parsed.origin}${pathname}`
+}
+
+function endpointRecord(canonicalProductionUrl, cloudRunServiceUrl, now) {
+  const canonical = normalizeProductionUrl(canonicalProductionUrl)
+  const service = normalizeProductionUrl(cloudRunServiceUrl)
+  const canonicalHost = new URL(canonical).hostname.toLowerCase()
+  const serviceHost = new URL(service).hostname.toLowerCase()
+  const configurationFingerprint = createHash('sha256')
+    .update(JSON.stringify({ canonicalProductionUrl: canonical, cloudRunServiceUrl: service }))
+    .digest('hex')
+  return {
+    schemaVersion: PRODUCTION_ENDPOINTS_SCHEMA_VERSION,
+    canonicalProductionUrl: canonical,
+    cloudRunServiceUrl: service,
+    distinctPublicEdgeHost: canonicalHost !== serviceHost,
+    publicEdgeHostname: canonicalHost !== serviceHost ? canonicalHost : null,
+    configurationFingerprint,
+    canonicalSource: "deploy-trigger-config",
+    serviceSource: "cloud-run-service",
+    checkedAt: new Date(now).toISOString(),
+  }
+}
+
+export function validateProductionEndpointRecord(record) {
+  if (!record || record.schemaVersion !== PRODUCTION_ENDPOINTS_SCHEMA_VERSION) {
+    return { ok: false, id: 'production-endpoints-missing', detail: 'preflight production endpoint record is missing or malformed' }
+  }
+  let expected
+  try { expected = endpointRecord(record.canonicalProductionUrl, record.cloudRunServiceUrl, Date.parse(record.checkedAt)) } catch (error) {
+    return { ok: false, id: 'production-endpoints-invalid', detail: error.message }
+  }
+  if (!Number.isFinite(Date.parse(record.checkedAt))
+    || record.canonicalSource !== expected.canonicalSource
+    || record.serviceSource !== expected.serviceSource
+    || record.canonicalProductionUrl !== expected.canonicalProductionUrl
+    || record.cloudRunServiceUrl !== expected.cloudRunServiceUrl
+    || record.distinctPublicEdgeHost !== expected.distinctPublicEdgeHost
+    || record.publicEdgeHostname !== expected.publicEdgeHostname
+    || record.configurationFingerprint !== expected.configurationFingerprint) {
+    return { ok: false, id: 'production-endpoints-invalid', detail: 'endpoint topology or fingerprint does not match the recorded URLs' }
+  }
+  return { ok: true, record }
+}
+
+function usableFreshness(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : DEFAULT_FLOOR_FRESHNESS_MINUTES
+}
+
+function freshnessFailure(checkedAt, now, freshnessMinutes) {
+  const timestamp = typeof checkedAt === "string" ? Date.parse(checkedAt) : NaN
+  if (!Number.isFinite(timestamp)) return "floor-verdict-unstamped"
+  const ageMinutes = (now - timestamp) / 60_000
+  if (ageMinutes < 0 || ageMinutes > usableFreshness(freshnessMinutes)) return "floor-verdict-stale"
+  return null
+}
+
+export function evaluateProductionFloor(record, floorReadiness, {
+  now = Date.now(), freshnessMinutes = DEFAULT_FLOOR_FRESHNESS_MINUTES,
+} = {}) {
+  const recordValidation = validateProductionEndpointRecord(record)
+  if (!recordValidation.ok) return recordValidation
+  if (!floorReadiness || typeof floorReadiness !== "object") {
+    return { ok: false, id: "floor-verdict-missing", detail: "floor readiness was not recorded at endpoint preflight" }
+  }
+  if (floorReadiness.endpointFingerprint !== record.configurationFingerprint) {
+    return { ok: false, id: "floor-endpoint-configuration-mismatch", detail: "floor readiness describes a different endpoint configuration" }
+  }
+
+  const status = String(floorReadiness.status || "").toLowerCase()
+  if (!record.distinctPublicEdgeHost) {
+    if (status !== "skipped" || !nonEmpty(floorReadiness.reason)) {
+      return { ok: false, id: "cloud-run-only-skip-missing", detail: "Cloud Run-only topology requires the reasoned preflight skip" }
+    }
+    return { ok: true, evidence: { floorReadiness } }
+  }
+
+  if (status !== "alive") {
+    return { ok: false, id: "floor-not-alive", detail: "a distinct public/edge host requires prod-active ALIVE and cannot be skipped" }
+  }
+  if (floorReadiness.profile !== "prod-active") {
+    return { ok: false, id: "floor-profile-mismatch", detail: "distinct-host floor evidence must use profile prod-active" }
+  }
+  let target
+  try { target = normalizeProductionUrl(floorReadiness.target) } catch {
+    return { ok: false, id: "floor-target-mismatch", detail: "floor target is not the canonical configured production URL" }
+  }
+  if (target !== record.canonicalProductionUrl) {
+    return { ok: false, id: "floor-target-mismatch", detail: "floor target is not the canonical configured production URL" }
+  }
+  if (floorReadiness.noMutations !== true) {
+    return { ok: false, id: "floor-not-read-only", detail: "prod-active floor evidence must be read-only" }
+  }
+  const freshness = freshnessFailure(floorReadiness.checkedAt, now, freshnessMinutes)
+  if (freshness) return { ok: false, id: freshness, detail: "prod-active floor evidence is missing a fresh timestamp" }
+  return { ok: true, evidence: { floorReadiness } }
+}
+
+export function buildProductionEndpointRecord({
+  canonicalProductionUrl, cloudRunServiceUrl, floorVerdict = null,
+  now = Date.now(), freshnessMinutes = DEFAULT_FLOOR_FRESHNESS_MINUTES,
+} = {}) {
+  let record
+  try {
+    record = endpointRecord(canonicalProductionUrl, cloudRunServiceUrl, now)
+  } catch (error) {
+    return { ok: false, failed: ["endpoint-read-invalid"], detail: error.message }
+  }
+
+  if (!record.distinctPublicEdgeHost) {
+    const floorReadiness = {
+      status: "skipped",
+      reason: "canonical configured production URL has the same hostname as the Cloud Run service URL; no distinct public/edge hostname exists",
+      endpointFingerprint: record.configurationFingerprint,
+      checkedAt: record.checkedAt,
+    }
+    return { ok: true, record, floorReadiness, failed: [] }
+  }
+
+  const normalized = normalizeReleaseVerdict(floorVerdict)
+  const floorReadiness = normalized && {
+    status: String(normalized.state).toLowerCase(),
+    profile: normalized.profile,
+    target: normalized.target,
+    noMutations: normalized.noMutations,
+    checkedAt: normalized.generatedAt,
+    endpointFingerprint: record.configurationFingerprint,
+  }
+  const evaluation = evaluateProductionFloor(record, floorReadiness, { now, freshnessMinutes })
+  return evaluation.ok
+    ? { ok: true, record, floorReadiness, failed: [] }
+    : { ok: false, record, floorReadiness, failed: [evaluation.id], detail: evaluation.detail }
+}
+
+export function revalidateProductionEndpoints(stored, {
+  canonicalProductionUrl, cloudRunServiceUrl, now = Date.now(),
+} = {}) {
+  const storedValidation = validateProductionEndpointRecord(stored)
+  if (!storedValidation.ok) return { ...storedValidation, detail: `resume requires a valid preflight endpoint record: ${storedValidation.detail}` }
+  let current
+  try { current = endpointRecord(canonicalProductionUrl, cloudRunServiceUrl, now) } catch (error) {
+    return { ok: false, id: "endpoint-read-invalid", detail: error.message }
+  }
+  if (stored.configurationFingerprint !== current.configurationFingerprint) {
+    return { ok: false, id: "endpoint-configuration-changed", previous: stored, current }
+  }
+  return { ok: true, id: null, previous: stored, current }
+}
+
+export function verifyCanonicalProductionTarget(record, target) {
+  const recordValidation = validateProductionEndpointRecord(record)
+  if (!recordValidation.ok) return recordValidation
+  let normalized
+  try { normalized = normalizeProductionUrl(target) } catch {
+    return { ok: false, id: "canonical-production-target-mismatch" }
+  }
+  if (normalized !== record.canonicalProductionUrl) {
+    return { ok: false, id: "canonical-production-target-mismatch", expected: record.canonicalProductionUrl, actual: normalized }
+  }
+  return { ok: true, target: normalized }
+}
+
+function runCommand(command) {
+  try {
+    const stdout = execFileSync('/bin/sh', ['-c', command], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 })
+    const lines = stdout.split("\n").map((line) => line.trim()).filter(Boolean)
+    if (lines.length !== 1) return { ok: false, detail: `command must emit exactly one URL line (got ${lines.length})` }
+    return { ok: true, value: lines[0] }
+  } catch (error) {
+    return { ok: false, detail: error.stderr?.toString?.().trim() || error.message }
+  }
+}
+
+function readJson(file, label) {
+  try { return { ok: true, value: JSON.parse(fs.readFileSync(file, "utf8")) } } catch (error) {
+    return { ok: false, detail: `${label} is unreadable or invalid JSON: ${error.message}` }
+  }
+}
+
+const VALUE_FLAGS = new Set([
+  "canonical-url-command", "service-url-command", "floor-verdict", "manifest", "target",
+  "now", "freshness-minutes",
+])
+
+function parseArgs(argv) {
+  const opts = {}, positional = [], errors = []
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === "--help" || arg === "-h") opts.help = true
+    else if (arg.startsWith("--")) {
+      const key = arg.slice(2)
+      if (!VALUE_FLAGS.has(key)) { errors.push(`unknown flag ${arg}`); continue }
+      const value = argv[++i]
+      if (value == null || value.startsWith("--")) {
+        errors.push(`missing value for ${arg}`)
+        if (value != null) i -= 1
+      } else opts[key] = value
+    } else positional.push(arg)
+  }
+  return { command: positional[0], opts, extra: positional.slice(1), errors }
+}
+
+function help() {
+  return `production-endpoints — decide production floor applicability before RC mint.
+
+Usage:
+  production-endpoints preflight --canonical-url-command <cmd> --service-url-command <cmd> [--floor-verdict <json>]
+  production-endpoints resume --manifest <json> --canonical-url-command <cmd> --service-url-command <cmd>
+  production-endpoints verify-live --manifest <json> --target <url>
+  production-endpoints live-target --manifest <json>
+
+The canonical command reads the deploy trigger configured production URL (for example
+_APP_BASE_URL). The service command independently reads the active Cloud Run service URL.
+A distinct hostname requires a fresh read-only prod-active ALIVE verdict on the canonical
+URL. Equal hostnames produce a reasoned Cloud Run-only skip. Resume re-runs both reads.
+
+Output from preflight is a run-state merge patch. Record it before candidate deployment.
+
+Exit: 0 pass; 1 hold/configuration changed; 2 usage or unreadable input.`
+}
+
+function loadManifest(file) {
+  const loaded = readJson(file, "manifest")
+  if (!loaded.ok) return loaded
+  if (loaded.value?.skill !== "resolve-release") return { ok: false, detail: "manifest is not a resolve-release run" }
+  return loaded
+}
+
+export function main(argv) {
+  const { command, opts, extra, errors } = parseArgs(argv)
+  if (opts.help || command === "help") { console.log(help()); return 0 }
+  if (errors.length || extra.length || !["preflight", "resume", "verify-live", "live-target"].includes(command)) {
+    if (errors.length) console.error(`production-endpoints: ${errors.join("; ")}`)
+    console.error(help())
+    return 2
+  }
+  const now = opts.now ? Date.parse(opts.now) : Date.now()
+  if (!Number.isFinite(now)) { console.error("production-endpoints: --now must be an ISO timestamp"); return 2 }
+
+  if (command === "live-target") {
+    if (!opts.manifest) { console.error(help()); return 2 }
+    const manifest = loadManifest(opts.manifest)
+    if (!manifest.ok) { console.error(`production-endpoints: ${manifest.detail}`); return 2 }
+    const record = manifest.value.release?.productionEndpoints
+    const result = verifyCanonicalProductionTarget(record, record?.canonicalProductionUrl)
+    if (!result.ok) { console.log(JSON.stringify(result, null, 2)); return 1 }
+    console.log(result.target)
+    return 0
+  }
+
+  if (command === "verify-live") {
+    if (!opts.manifest || !opts.target) { console.error(help()); return 2 }
+    const manifest = loadManifest(opts.manifest)
+    if (!manifest.ok) { console.error(`production-endpoints: ${manifest.detail}`); return 2 }
+    const result = verifyCanonicalProductionTarget(manifest.value.release?.productionEndpoints, opts.target)
+    console.log(JSON.stringify(result, null, 2))
+    return result.ok ? 0 : 1
+  }
+
+  if (!opts["canonical-url-command"] || !opts["service-url-command"]) { console.error(help()); return 2 }
+  const canonical = runCommand(opts["canonical-url-command"])
+  const service = runCommand(opts["service-url-command"])
+  if (!canonical.ok || !service.ok) {
+    console.error(`production-endpoints: endpoint read failed: ${canonical.detail || service.detail}`)
+    return 1
+  }
+
+  if (command === "resume") {
+    if (!opts.manifest) { console.error(help()); return 2 }
+    const manifest = loadManifest(opts.manifest)
+    if (!manifest.ok) { console.error(`production-endpoints: ${manifest.detail}`); return 2 }
+    const result = revalidateProductionEndpoints(manifest.value.release?.productionEndpoints, {
+      canonicalProductionUrl: canonical.value, cloudRunServiceUrl: service.value, now,
+    })
+    console.log(JSON.stringify(result, null, 2))
+    return result.ok ? 0 : 1
+  }
+
+  let floorVerdict = null
+  if (opts["floor-verdict"]) {
+    const loaded = readJson(opts["floor-verdict"], "floor verdict")
+    if (!loaded.ok) { console.error(`production-endpoints: ${loaded.detail}`); return 2 }
+    floorVerdict = loaded.value
+  }
+  const freshnessMinutes = opts["freshness-minutes"] == null ? DEFAULT_FLOOR_FRESHNESS_MINUTES : Number(opts["freshness-minutes"])
+  if (!usableFreshness(freshnessMinutes)) { console.error("production-endpoints: --freshness-minutes must be positive"); return 2 }
+  const result = buildProductionEndpointRecord({
+    canonicalProductionUrl: canonical.value, cloudRunServiceUrl: service.value,
+    floorVerdict, now, freshnessMinutes,
+  })
+  if (!result.ok) { console.log(JSON.stringify(result, null, 2)); return 1 }
+  console.log(JSON.stringify({ release: {
+    productionEndpoints: result.record, floorReadiness: result.floorReadiness,
+  } }, null, 2))
+  return 0
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = main(process.argv.slice(2))

package/skills/engineering/resolve-release/scripts/rc-circuit-breaker.mjs

@@ -0,0 +1,272 @@
+// rc-circuit-breaker — hold repeated release-tooling failures behind a circuit breaker (#962).
+//
+// WHY THIS EXISTS. Forex v0.1.12 minted NINE immutable RCs. After RC.2 and RC.3, two healthy
+// candidates had reached 100% and been rolled back because the lane's own verifier misread valid
+// platform state — and nothing stopped the larger loop in which tooling-only retries kept
+// generating new production attempts. Each attempt's fail-closed behavior was correct; what was
+// missing was a breaker over the LOOP: after enough failures owned by the release tooling or the
+// gate environment, the next immutable RC is held for explicit release-design review instead of
+// being minted on autopilot.
+//
+// WHAT IT READS. The durable evidence bundles only — the same immutable record
+// version-postmortem.mjs aggregates — via `discoverVersionBundles`, classified by #961's
+// `classifyFailureOwner`. It never reads a live service, never a run manifest, and it NEVER
+// writes: the check is read-only over the durable dir, so a hold deletes nothing, moves no tag,
+// and burns no version (the issue's AC). The release lane runs it at step 3, BEFORE
+// `version.mjs rc` mints the next immutable RC (references/candidate.md), and records the
+// decision JSON on the manifest (`release.circuitBreaker`) so the post-mortem can report whether
+// the breaker fired and how it was resolved.
+//
+// THE COUNT. Prior NON-RELEASED attempts for the same proposed version whose normalized failure
+// owner is `release-tooling` or `gate-environment` (BREAKER_OWNERS — the two lane-side owners of
+// #961's taxonomy). Application, configuration and platform failures are real failures with
+// their own routes; they are reported in `ownerCounts` but never consume this threshold, because
+// this breaker exists for exactly one signal: the lane's own machinery failing repeatedly.
+// `released` is not a failure; `revoked`/`blocked-manual` classify to no owner and never count.
+//
+// THE THRESHOLD. Default 2 prior qualifying failures (the issue's approved default).
+// Configurable: `--threshold <n>` beats `$RC_CIRCUIT_BREAKER_THRESHOLD` beats the default, and
+// the decision records which source set it — configuration is DECLARED IN THE RECORD, never
+// silent. What no flag or env var can do is skip the check: the only way past a hold is the
+// recorded human authorization below.
+//
+// THE HOLD. Crossing the threshold returns `hold-for-release-design-review` (exit 1) with the
+// count, the per-owner breakdown, the qualifying attempt ids, their phases, and the bundle files
+// as evidence links. Fail-closed both ways: an unreadable dir or an unparseable bundle is a
+// refusal (exit 2, nothing on stdout) — the same reading evidence-bundle.mjs's mint takes —
+// never an empty history.
+//
+// CONTINUING PAST A HOLD is a human's explicit, recorded decision — not an env bypass. The
+// authorization is a structured JSON record (`--authorization <file>`):
+//   {
+//     "version": "<the proposed version>",          // must match the check's version
+//     "againstCount": <current qualifyingCount>,    // binds the record to THIS count: one
+//                                                   // authorization covers exactly ONE
+//                                                   // continuation; a further qualifying
+//                                                   // failure re-holds and the stale record
+//                                                   // does not carry
+//     "authorizedBy": "<the human>",
+//     "authorizedAt": "<ISO timestamp>",
+//     "rationale": "<why another RC is preferable to simplifying, removing, or externally
+//                    repairing the gate>",
+//     "alternativesConsidered": { "simplify": …, "remove": …, "externalRepair": … }  // optional
+//   }
+// A valid record turns the hold into `authorized-continue` (exit 0) echoing the record, which
+// the lane merges onto the manifest. An invalid or stale record leaves the hold standing and
+// names why (`authorizationError`).
+
+import fs from 'node:fs'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  FAILURE_OWNERS,
+  classifyFailureOwner,
+  classifyFailurePhase,
+  discoverVersionBundles,
+} from './version-postmortem.mjs'
+
+// The contract surface. The two lane-side owners, the default of two, the env var name, and the
+// decision strings are what the doctrine (references/candidate.md, references/postmortem.md)
+// states — changing any of them is a breaking change to that contract.
+export const BREAKER_OWNERS = ['release-tooling', 'gate-environment']
+export const DEFAULT_THRESHOLD = 2
+export const THRESHOLD_ENV = 'RC_CIRCUIT_BREAKER_THRESHOLD'
+export const HOLD_DECISION = 'hold-for-release-design-review'
+export const PROCEED_DECISION = 'proceed'
+export const AUTHORIZED_DECISION = 'authorized-continue'
+
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== ''
+
+// Flag beats env beats default; an invalid value from any source is a refusal, never a silent
+// fall-back — a threshold nobody can account for is the check not running.
+export function resolveThreshold({ flag = null, env = process.env } = {}) {
+  const parse = (raw, source) => {
+    const n = Number(raw)
+    if (!Number.isInteger(n) || n < 1) {
+      throw new Error(`rc-circuit-breaker: invalid threshold ${JSON.stringify(raw)} from ${source} — an integer >= 1 is required`)
+    }
+    return { threshold: n, thresholdSource: source }
+  }
+  if (flag != null) return parse(flag, 'flag')
+  if (nonEmpty(env[THRESHOLD_ENV])) return parse(env[THRESHOLD_ENV], 'env')
+  return { threshold: DEFAULT_THRESHOLD, thresholdSource: 'default' }
+}
+
+// The evaluation: count prior non-released attempts for this proposed version by normalized
+// failure owner, and decide. THROWS on an unreadable dir or an unparseable bundle — the caller
+// (CLI) turns that into the exit-2 refusal; a gate that cannot establish the count does not get
+// to answer "below threshold".
+export function evaluateRcCircuitBreaker({ dir, version, threshold = DEFAULT_THRESHOLD, thresholdSource = 'default' } = {}) {
+  const { attempts, unreadable } = discoverVersionBundles(dir, version)
+  if (unreadable.length) {
+    throw new Error(`cannot establish the failure history for ${version} — ${unreadable.length} durable bundle(s) do not parse (${unreadable.join('; ')}). Repair the record; a gate that cannot read the history does not get to proceed.`)
+  }
+
+  const rows = attempts.map((a) => {
+    const failure = classifyFailureOwner(a.bundle)
+    return {
+      attemptId: a.attemptId,
+      ordinal: a.ordinal,
+      terminalState: a.terminalState,
+      failureOwner: failure?.owner ?? null,
+      failureBasis: failure?.basis ?? null,
+      failurePhase: classifyFailurePhase(a.bundle),
+      evidence: a.file,
+    }
+  })
+
+  const ownerCounts = Object.fromEntries(FAILURE_OWNERS.map((o) => [o, 0]))
+  for (const r of rows) if (r.failureOwner) ownerCounts[r.failureOwner] += 1
+  const qualifying = rows.filter((r) => r.failureOwner && BREAKER_OWNERS.includes(r.failureOwner))
+
+  const held = qualifying.length >= threshold
+  return {
+    kind: 'rc-circuit-breaker',
+    version: String(version),
+    threshold,
+    thresholdSource,
+    countedOwners: BREAKER_OWNERS,
+    attempts: rows.length,
+    nonReleased: rows.filter((r) => r.terminalState !== 'released').length,
+    ownerCounts,
+    qualifyingCount: qualifying.length,
+    qualifying,
+    decision: held ? HOLD_DECISION : PROCEED_DECISION,
+    decisionBasis: held
+      ? `${qualifying.length} prior non-released attempt(s) of ${version} owned by ${BREAKER_OWNERS.join('/')} reach the configured threshold ${threshold} — the loop #962 exists to stop`
+      : `${qualifying.length} prior non-released attempt(s) of ${version} owned by ${BREAKER_OWNERS.join('/')}, below the configured threshold ${threshold}`,
+    continue: held
+      ? 'Minting the next immutable RC requires an explicit human authorization (--authorization <file>) recording why another RC is preferable to simplifying, removing, or externally repairing the gate; record this decision JSON at release.circuitBreaker on the manifest. The hold deletes nothing, moves no tag, and burns no version.'
+      : null,
+  }
+}
+
+// Validates the human's continuation record against the CURRENT evaluation. `againstCount`
+// binding is the anti-silent-carry rule: the record authorizes one continuation past exactly the
+// count it was written against, so a further qualifying failure re-holds instead of inheriting
+// yesterday's decision.
+export function validateAuthorization(record, evaluation) {
+  const errors = []
+  const isObj = record != null && typeof record === 'object' && !Array.isArray(record)
+  if (!isObj) return { valid: false, errors: ['authorization must be a JSON object'] }
+  if (!nonEmpty(record.authorizedBy)) errors.push('authorizedBy is required (the human authorizing the continuation)')
+  if (!nonEmpty(record.authorizedAt) || !Number.isFinite(Date.parse(record.authorizedAt))) errors.push('authorizedAt is required and must be an ISO timestamp')
+  if (!nonEmpty(record.rationale)) errors.push('rationale is required — why another RC is preferable to simplifying, removing, or externally repairing the gate')
+  if (!nonEmpty(record.version)) errors.push('version is required')
+  else if (evaluation && record.version.trim().replace(/^v/, '') !== String(evaluation.version).replace(/^v/, '')) {
+    errors.push(`version ${record.version} does not match the held version ${evaluation.version}`)
+  }
+  if (!Number.isInteger(record.againstCount)) errors.push('againstCount is required (the qualifying count this record was written against)')
+  else if (evaluation && record.againstCount !== evaluation.qualifyingCount) {
+    errors.push(`againstCount ${record.againstCount} is stale — the current qualifying count is ${evaluation.qualifyingCount}; one authorization covers exactly one continuation`)
+  }
+  return { valid: errors.length === 0, errors }
+}
+
+// ---- CLI ----
+
+const USAGE = `rc-circuit-breaker — the release-lane circuit breaker for repeated tooling failures (#962).
+
+Run BEFORE minting the next immutable RC (step 3, references/candidate.md). Counts prior
+non-released attempts for the proposed version whose normalized failure owner is release-tooling
+or gate-environment (#961's taxonomy), and holds when the count reaches the threshold.
+
+Usage:
+  rc-circuit-breaker check --dir <durable-evidence-dir> --version <v> [--threshold <n>] [--authorization <file.json>]
+
+  --threshold <n>       qualifying failures that trip the hold (default ${DEFAULT_THRESHOLD};
+                        env ${THRESHOLD_ENV}; flag beats env beats default; the source is
+                        recorded in the decision). No flag or env var skips the check.
+  --authorization <f>   a structured human authorization (see references/postmortem.md):
+                        version, againstCount, authorizedBy, authorizedAt, rationale. Valid
+                        only against the CURRENT count — one authorization, one continuation.
+
+Exit codes:
+  0  proceed (below threshold) or authorized-continue (record valid) — decision JSON on stdout
+  1  hold-for-release-design-review — decision JSON on stdout, with count, owners, attempt ids
+     and evidence files
+  2  cannot evaluate (usage, unreadable dir, unparseable bundle, invalid threshold) — stderr
+     only; fail closed, nothing is minted
+
+The check is read-only: a hold deletes nothing, moves no immutable RC tag, and burns no version.`
+
+function parseArgs(argv) {
+  const opts = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') opts.help = true
+    else if (a.startsWith('--')) opts[a.slice(2)] = argv[++i]
+    else opts._.push(a)
+  }
+  return opts
+}
+
+export function main(argv, env = process.env) {
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const [cmd] = opts._
+  if (cmd !== 'check' || !nonEmpty(opts.dir) || !nonEmpty(opts.version)) {
+    console.error('rc-circuit-breaker: usage: check --dir <durable-evidence-dir> --version <v> are all required (see --help)')
+    return 2
+  }
+
+  let resolved
+  try {
+    resolved = resolveThreshold({ flag: opts.threshold ?? null, env })
+  } catch (e) {
+    console.error(e.message)
+    return 2
+  }
+
+  let evaluation
+  try {
+    evaluation = evaluateRcCircuitBreaker({
+      dir: opts.dir,
+      version: opts.version,
+      threshold: resolved.threshold,
+      thresholdSource: resolved.thresholdSource,
+    })
+  } catch (e) {
+    console.error(`rc-circuit-breaker: ${e.message}`)
+    return 2
+  }
+
+  if (evaluation.decision !== HOLD_DECISION) {
+    process.stdout.write(JSON.stringify(evaluation, null, 2) + '\n')
+    return 0
+  }
+
+  // The hold stands unless a valid human authorization is presented. A malformed or stale one
+  // never turns into a proceed — it is named and the hold stands.
+  if (opts.authorization != null) {
+    let record = null
+    try {
+      record = JSON.parse(fs.readFileSync(opts.authorization, 'utf8'))
+    } catch (e) {
+      process.stdout.write(JSON.stringify({ ...evaluation, authorizationError: `authorization file unreadable: ${e.message}` }, null, 2) + '\n')
+      return 1
+    }
+    const v = validateAuthorization(record, evaluation)
+    if (v.valid) {
+      process.stdout.write(JSON.stringify({
+        ...evaluation,
+        decision: AUTHORIZED_DECISION,
+        decisionBasis: `${evaluation.decisionBasis} — continued under a recorded human authorization`,
+        authorization: record,
+      }, null, 2) + '\n')
+      return 0
+    }
+    process.stdout.write(JSON.stringify({ ...evaluation, authorizationError: v.errors.join('; ') }, null, 2) + '\n')
+    return 1
+  }
+
+  process.stdout.write(JSON.stringify(evaluation, null, 2) + '\n')
+  return 1
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2))
+}