@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/green-gate.mjs

@@ -0,0 +1,599 @@
+// green-gate — the mechanized unattended-promotion gate for the release lane (issue #405).
+//
+// `auto-when-green` (references/auto-when-green.md) lets a promotion run unattended, but
+// only behind a real gate. Today an agent evaluates that gate's (a)-(e) conditions by
+// reading prose, at the single most dangerous point in the system: an unattended
+// production traffic shift with no human present. This script makes each condition a
+// DECIDABLE ARTIFACT CHECK that FAILS CLOSED and NAMES the failing condition — so the
+// green light is a comparison against a recorded fact, never a claim the agent makes
+// about its own prior work.
+//
+// The doc has two authorization points, so this has two subcommands:
+//   green-gate.mjs promote --manifest <run-manifest.json>
+//       Gates the promotion + rc mint on (a)-(d) plus the "force the human even when
+//       green" carve-outs (major bump, rollback not armed, irreversible content).
+//   green-gate.mjs shift   --manifest <run-manifest.json> --verdict <smoke-verdict.json>
+//       Gates the traffic shift on (e): the candidate's smoke verdict is ALIVE, on the
+//       EXACT candidate URL, was a --no-mutations run, and is still INSIDE the envelope's
+//       freshness window. This is the crux — "on that exact candidate" is a compared field
+//       (`target === candidateUrl`), never asserted; and "recently enough" is a compared
+//       field too (`generatedAt` vs `envelope.verdictFreshnessMinutes`), because the
+//       authorization this gate runs after can arrive hours after the validation.
+//
+// Contract:
+//   exit 0 = FIRE   — every condition holds and no carve-out triggered.
+//   exit 1 = HOLD   — fall back to a per-step human confirm; the SPECIFIC failing
+//                     condition ids are named in `failed`.
+//   exit 2 = usage / unreadable-input error — bad flags, unknown subcommand, or a
+//                     manifest that is absent / unparseable / not a resolve-release run.
+//
+// FAIL CLOSED is the invariant: EVERY missing / malformed / wrong-shape condition input
+// is a HOLD, never a FIRE. A missing smoke-verdict.json HOLDs. A `release` field the gate
+// needs but the manifest does not carry HOLDs and is named. The only inputs that produce
+// exit 2 (not HOLD) are the ones that stop the gate from running at all: the CLI flags
+// and the manifest file itself.
+//
+// WHAT A HOLD MEANS, doctrinally (principle 13, issue #439). The behaviour above was always
+// right and was nowhere written down, which left the reading of it to whoever hit it: an
+// APPLICABLE CONDITION WHOSE INPUT COULD NOT BE PRODUCED IS A FAILING CONDITION, NOT A
+// MISSING ONE. The credential the readiness check needed was absent, the service it drives
+// was down, the fixture had drifted — none of that is a step to note and continue past, and
+// none of it is an `n/a` (which says the condition does not apply here, and is decided). So
+// the gate never distinguishes "nobody filled this in" from "nobody could": it cannot, and
+// neither is a result.
+//
+// AND THE HOLD IS SCOPED. It blocks THIS release — this SHA does not promote, this candidate
+// does not take traffic. It is not a reason to pause the merge queue, dequeue an unrelated
+// PR, or lift a branch protection: a fail-closed mechanism that also freezes the repair path
+// is the one people bypass, and a bypassed gate has stopped existing without anyone deciding
+// to remove it. The fix to the harness, the fixture or the credential is enqueued like any
+// other unit and lands the way everything else lands.
+//
+// Every condition is read from an ARTIFACT the release lane already records:
+//   - the run manifest — resolve-issues' scripts/run-state.mjs, release variant
+//     (references/../resolve-issues/references/run-state.md): `envelope` (the pre-flight
+//     authorization block) and `release` (the version/candidate/CI record).
+//   - smoke-verdict.json — the smoke skill's verdict output (verdict/target/noMutations/
+//     generatedAt, all stamped by smoke's stampTarget).
+//   - version.mjs plan's recorded output, carried in `release.versionPlan`
+//     ({ bump, collision, ... }) — the gate trusts the plan computed at step 1b rather
+//     than re-running git, so the gate reads the same fact the human saw at the cut.
+//
+// NOTE ON THE MANIFEST SCHEMA. run-state.mjs validates the release variant LOOSELY (only
+// `envelope` presence and the `step` enum). The `release.*` and `envelope.*` fields this
+// gate reads are therefore not yet formally in that schema; the gate reads them from the
+// raw JSON and fails closed on any it does not find. `envelope.reversibilityConfirmed` in
+// particular is a field the pre-flight gate does not record today — until it does, the
+// irreversible-content carve-out HOLDs (the safe default: force the human), rather than
+// silently passing an unverifiable carve-out. See the PR body for the full field list.
+
+import fs from 'node:fs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { normalizeReleaseVerdict } from '../../resolve-issues/scripts/release-state-contract.mjs'
+import { evaluateProductionFloor } from './production-endpoints.mjs'
+
+// The conservative default freshness window for the step-4a verdict, in minutes (issue #431).
+//
+// (e) bounds WHICH candidate the evidence covers; it did not bound how OLD that evidence is,
+// and step 4b's shape is "validate at 0% → wait for an authorization → shift" with nothing
+// bounding the wait. A four-hour-old ALIVE describes coordinates that may have moved since:
+// a newer build may hold the `candidate` tag, the previous revision may no longer hold 100%.
+// So the shift gate reads the verdict's `generatedAt` stamp and refuses evidence older than
+// the window the envelope declared (pre-flight item 3), defaulting to this when it declared
+// none. Conservative on purpose — the default governs an unattended production traffic shift
+// with no human present, so it must read evidence minted minutes ago, not hours; a release
+// that legitimately needs a longer wait declares the longer window in the envelope, where a
+// human saw it. Expiry routes back to step 4a (re-validate the candidate), not to the shift.
+export const DEFAULT_VERDICT_FRESHNESS_MINUTES = 30
+
+// ---- condition helpers (pure) ----
+
+const isGreen = (v) => v === 'green'
+
+// (b)'s SHA-keyed integration smoke sub-check. The integration environment may or may not
+// run a SHA-keyed recorder (principle 11): the manifest declares which. An explicit
+// "not-recorded" waives the sub-check; a recorded verdict must be ALIVE and on the EXACT
+// promoted SHA (a verdict from another SHA is not evidence for this one). Anything else —
+// absent, or a malformed value — fails closed: the presence of a recorder must be an
+// explicit statement, never an inference from a missing field.
+function integrationSmokeGreen(smoke, candidateSha) {
+  if (smoke === 'not-recorded') return true
+  if (!smoke || typeof smoke !== 'object') return false
+  // Require a real SHA match, not merely equal fields: an absent candidateSha and a
+  // sha-less verdict are both `undefined`, and `undefined === undefined` would fail OPEN —
+  // firing production on "a verdict for no particular SHA." A truthy-string match on both
+  // sides is the fail-closed form.
+  return (
+    smoke.verdict === 'ALIVE' &&
+    typeof candidateSha === 'string' &&
+    candidateSha.length > 0 &&
+    smoke.sha === candidateSha
+  )
+}
+
+// (c)'s evidence must BE a CHECKABLE LOCATOR, not a prose sentence that merely CONTAINS a
+// locator-shaped token. An unattended production-promotion gate must not accept "looks good"
+// as proof that a readiness row passed — it accepts only evidence a second reader could
+// independently re-open. This is the coverage-checklist.mjs / review-contract evidence
+// convention (ensure-coverage), widened to the forms a release-readiness row actually cites.
+//
+// THE ANCHORING RULE (why containment was a fail-OPEN). Every form below is anchored at `^`:
+// the evidence must PRESENT as a locator — it must wholly BE one, or LEAD with one, with a
+// trailing NOTE (whitespace/punctuation + free text) allowed after the complete token. A
+// locator-shaped token buried inside a prose sentence is NO LONGER sufficient, because that
+// containment let realistic prose fire the gate: a date ("verified 20260721") and a big number
+// ("ran 1000000 iterations") are valid [0-9a-f]{7,40} SHAs; an all-hex English word ("acceded",
+// "defaced") is too; a dotted abbreviation ("e.g.", "i.e.", "U.S."), a glued sentence ("wrapped
+// up.Next steps"), and an email TLD ("a@b.com") all carry a "filename.ext"-shaped substring.
+// Anchoring means only the LEADING token can qualify, so none of those pass. Accepted anchored
+// forms (the trailing-note allowance, issue #412 fix 3, is IDENTICAL for every one — a complete
+// token then end / whitespace / punctuation [ , ; ) ] } ] then any note; '.' is excluded so a
+// leading abbreviation never reads as "file.ext" + a period note):
+//   - a file path with a REAL extension   docs/release/checklist.md, run-state.mjs
+//     and an optional :line / :line-range  path/to/file.ext:123  (or :12-20), then the tail.
+//     The extension must be LETTER-initial (`.md`, not a `.5` decimal). The name part accepts a
+//     leading '@' only at index 0 (npm scope `@scope/pkg/file.ts`); an '@' after index 0 makes
+//     it an email, not a path, so "ops@example.com confirmed" does NOT qualify (issue #412 fix
+//     1). An abbreviation's trailing "." ("e.g. ok") has no ext char before the space, so it
+//     still fails.
+//   - an extensionless named file :line   ./Makefile:5, path/to/file:12 — the :line is the
+//     discriminator, and the left side must be PATH-LIKE: contain a '/' or a real '.ext' (issue
+//     #412 fix 2). A bare "word:number" ("error:500", "attempt:2") is not a locator, and a bare
+//     "Makefile:5" must be path-qualified ("./Makefile:5"). The name part must contain a letter,
+//     so "12:30" is not a locator.
+//   - a URL                               http://… / https://…
+//   - an issue / PR ref                   #123
+//   - a backticked shell command          `node --test …`
+//   - a bare git SHA                      7-40 hex chars, the whole TOKEN (a trailing note is
+//     allowed, e.g. "AbCdEf1 rest"), containing BOTH a hex letter AND a digit — the digit+letter
+//     requirement is what separates a real SHA from an all-hex English word or an all-digit
+//     date/number, each of which is otherwise a valid hex string, and it is tested on the token,
+//     not the note. It rejects the ~0.1% of genuine SHAs that are all-letters — the safe
+//     direction for a production gate.
+// RESIDUAL (shape-inherent, out of scope). A leading glued sentence or product name that is
+// shape-identical to a real file — "Done.Next steps", "Next.js routes unchanged", "Mrs.Smith
+// approved" — still qualifies: without a filesystem check they are indistinguishable from a
+// legitimate ".js"/".ts"/".md" reference, and rejecting them would reject real file locators.
+// Bare prose ("looks good", "done", "verified", "N/A", "TODO") leads with none of these →
+// NOT a locator → the row is not green and condition (c) HOLDs (forces the human).
+export function isCheckableLocator(s) {
+  if (typeof s !== 'string') return false
+  const t = s.trim()
+  if (t.length === 0) return false
+
+  // The shared trailing boundary (issue #412 fix 3): a COMPLETE locator token ends at
+  // end-of-string, whitespace, or a note-attaching punctuation ( , ; ) ] } ) — the SAME rule
+  // for every form below, so "AbCdEf1 rest" (SHA + note) and "CHANGELOG.md:1, note" (locator
+  // glued to a comma) qualify exactly as "docs/x.md:12 note" always did. It DELIBERATELY
+  // excludes '.' — a leading abbreviation ("e.g.", "U.S.") must never read as "file.ext" + a
+  // trailing period note (that is the dotted-abbreviation fail-open the anchoring closed) —
+  // and ':' / '-' / '/', which are locator-internal.
+  const TAIL = '(?:[\\s,;)\\]}]|$)'
+
+  // a file path with a letter-initial extension + optional :line, then the tail.
+  // The name part accepts a leading '@' at index 0 (npm scope: @scope/pkg/file.ts) but NO '@'
+  // after it (issue #412 fix 1): "ops@example.com confirmed" is an email TLD, not a path.
+  if (new RegExp('^\\S[^\\s@]*\\.[A-Za-z][\\w-]{0,9}(:\\d+(-\\d+)?)?' + TAIL).test(t)) return true
+
+  // an extensionless named file with a :line ref. The left side must be PATH-LIKE — contain a
+  // '/' or a real '.ext' (issue #412 fix 2) — so bare "word:number" prose ("error:500",
+  // "attempt:2", "Makefile:5") is NOT a locator; and the name part must contain a letter
+  // ("12:30" is a time, not a locator). A bare extensionless name needs a path: "./Makefile:5".
+  if (new RegExp('^(?=[\\w./-]*[A-Za-z])(?=[\\w./-]*(?:/|\\.[A-Za-z]))[\\w./-]+:\\d+(-\\d+)?' + TAIL).test(t)) return true
+
+  // a URL
+  if (/^https?:\/\//.test(t)) return true
+
+  // an issue / PR ref
+  if (/^#\d+/.test(t)) return true
+
+  // a backticked command / code span
+  if (/^`[^`]+`/.test(t)) return true
+
+  // a bare git SHA: a 7-40 hex token, then the shared tail (issue #412 fix 3 — a SHA + note
+  // now qualifies like every other form, not only a whole-string SHA). The digit-AND-hex-letter
+  // requirement — what separates a real SHA from an all-hex English word or an all-digit
+  // date/number — is tested on the captured TOKEN, never on the trailing note.
+  const sha = new RegExp('^([0-9a-f]{7,40})' + TAIL, 'i').exec(t)
+  if (sha && /[0-9]/.test(sha[1]) && /[a-f]/i.test(sha[1])) return true
+
+  return false
+}
+
+const SECRET_EVIDENCE = [
+  /-----BEGIN [^-]*PRIVATE KEY-----/i,
+  /(?:^|[?&\s,;])(?:access[_-]?token|id[_-]?token|token|secret|password|passwd|api[_-]?key|authorization|credential)\s*[:=]\s*\S+/i,
+  /\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,}|AIza[A-Za-z0-9_-]{20,})\b/,
+]
+
+function diagnosticEvidence(value) {
+  let serialized
+  try {
+    serialized = typeof value === 'string' ? value : JSON.stringify(value)
+  } catch {
+    serialized = '[UNSERIALIZABLE]'
+  }
+  if (SECRET_EVIDENCE.some((pattern) => pattern.test(serialized || ''))) {
+    return { value: '[REDACTED]', redacted: true }
+  }
+  return { value: value ?? '', redacted: false }
+}
+
+export function releaseReadinessFailures(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return [{
+      index: null,
+      row: '(releaseReadiness)',
+      status: null,
+      evidenceValue: '',
+      evidenceRedacted: false,
+      violations: [{
+        rule: 'releaseReadiness-must-be-non-empty-array',
+        actual: Array.isArray(rows) ? 'empty-array' : rows == null ? null : typeof rows,
+      }],
+    }]
+  }
+
+  return rows.flatMap((entry, index) => {
+    const row = entry && typeof entry === 'object' ? entry : {}
+    const evidence = diagnosticEvidence(row.evidence)
+    const violations = []
+    if (row.status !== 'PASS') violations.push({ rule: 'status-must-be-PASS', actual: row.status ?? null })
+    if (!isCheckableLocator(row.evidence)) {
+      violations.push({ rule: 'evidence-must-start-with-checkable-locator', actual: evidence.value })
+    }
+    if (violations.length === 0) return []
+    return [{
+      index,
+      row: typeof row.row === 'string' && row.row ? row.row : `(row ${index})`,
+      status: row.status ?? null,
+      evidenceValue: evidence.value,
+      evidenceRedacted: evidence.redacted,
+      violations,
+    }]
+  })
+}
+
+// (c) release-readiness: every row decided PASS with a CHECKABLE evidence locator (see
+// isCheckableLocator — prose alone is not evidence), no blank/TODO row (coverage-checklist.mjs
+// validate semantics). Plus the version/changelog row: the cut is committed and the recorded
+// plan reports no collision on the final tag.
+function releaseReadinessGreen(release) {
+  const plan = release.versionPlan
+  const versionRowGreen =
+    typeof release.cutCommit === 'string' &&
+    release.cutCommit.length > 0 &&
+    !!plan &&
+    plan.collision === false
+  return releaseReadinessFailures(release.releaseReadiness).length === 0 && versionRowGreen
+}
+
+// ---- promote: (a)-(d) + carve-outs ----
+
+export function evaluatePromote(manifest) {
+  const release = (manifest && manifest.release) || {}
+  const envelope = (manifest && manifest.envelope) || {}
+  const failed = []
+  const evidence = {}
+  const diagnostics = { readiness: releaseReadinessFailures(release.releaseReadiness) }
+
+  // (a) Fast-forwardable.
+  evidence.fastForwardable = release.fastForwardable
+  if (release.fastForwardable !== true) failed.push('a')
+
+  // (b) Gates green: PR-lane CI, integration CI, and (where recorded) the SHA-keyed smoke
+  // verdict ALIVE on the exact promoted SHA.
+  evidence.prLaneCi = release.prLaneCi
+  evidence.integrationCi = release.integrationCi
+  evidence.integrationSmoke = release.integrationSmoke
+  evidence.candidateSha = release.candidateSha
+  if (
+    !isGreen(release.prLaneCi) ||
+    !isGreen(release.integrationCi) ||
+    !integrationSmokeGreen(release.integrationSmoke, release.candidateSha)
+  ) {
+    failed.push('b')
+  }
+
+  // (c) Release-readiness fully decided (rows + the version/changelog row).
+  evidence.releaseReadiness = Array.isArray(release.releaseReadiness)
+    ? release.releaseReadiness.map((row) => {
+        const safe = diagnosticEvidence(row && row.evidence)
+        return { ...row, evidence: safe.value, evidenceRedacted: safe.redacted }
+      })
+    : release.releaseReadiness
+  evidence.cutCommit = release.cutCommit
+  evidence.versionPlan = release.versionPlan
+  if (!releaseReadinessGreen(release)) failed.push('c')
+
+  // (d) No unresolved blocking finding on the combined diff (from the integration-review
+  // verdict, a recorded manifest field). Absent count fails closed.
+  evidence.blockingFindings = release.blockingFindings
+  if (release.blockingFindings !== 0) failed.push('d')
+
+  // Carve-out: a major version bump reaches consumers who already pinned — irreversible
+  // for them whatever the rollback does. version.mjs plan names the bump, so it is
+  // mechanically checkable. FAIL CLOSED like every other carve-out: clear this ONLY on a
+  // positively-known non-major bump. version.mjs only ever emits lowercase major|minor|
+  // patch, so an absent versionPlan, an absent bump, or ANY non-canonical value ('Major',
+  // 'MAJOR', a typo) is a malformed input the gate cannot read as safe — it must force the
+  // human, never take the green branch. A knowably-major bump is named distinctly from a
+  // manifest we can't trust to be non-major.
+  const bump = release.versionPlan && release.versionPlan.bump
+  if (bump === 'major') failed.push('carveout:major-bump')
+  else if (bump !== 'patch' && bump !== 'minor') failed.push('malformed-version-plan')
+
+  // Carve-out: rollback must be armed — auto-rollback policy AND a candidate deletable
+  // without confirmation. Without the validate→expose→verify→rollback loop, auto-when-green
+  // is not available.
+  evidence.rollbackPolicy = envelope.rollbackPolicy
+  evidence.candidateDeletableWithoutConfirm = envelope.candidateDeletableWithoutConfirm
+  if (envelope.rollbackPolicy !== 'auto-rollback' || envelope.candidateDeletableWithoutConfirm !== true) {
+    failed.push('carveout:rollback-not-armed')
+  }
+
+  // Carve-out: irreversible content always forces the human. This depends on an input the
+  // pre-flight gate does not record today, so it fails closed: a positive
+  // `reversibilityConfirmed` is REQUIRED to clear it, and an explicit `irreversibleContent`
+  // flag forces the human. Absence HOLDs rather than silently passing.
+  evidence.reversibilityConfirmed = envelope.reversibilityConfirmed
+  evidence.irreversibleContent = envelope.irreversibleContent
+  if (envelope.reversibilityConfirmed !== true || envelope.irreversibleContent === true) {
+    failed.push('carveout:irreversible-content')
+  }
+
+  return { decision: failed.length === 0 ? 'fire' : 'hold', phase: 'promote', failed, evidence, diagnostics }
+}
+
+// ---- shift: (e) checked against the artifact, not asserted ----
+
+// The freshness window in force for this release: the envelope's declared value when it is a
+// usable one, the conservative default otherwise. Only a positive finite NUMBER counts —
+// a string "240", a 0, a negative, NaN/Infinity, an object are all unreadable, and an
+// unreadable window must never become "no window". Falling back NARROWS rather than widens,
+// so the failure direction is a HOLD (fall back to the human), never an unbounded fire.
+function freshnessWindowMinutes(envelope) {
+  const declared = envelope && envelope.verdictFreshnessMinutes
+  const usable = typeof declared === 'number' && Number.isFinite(declared) && declared > 0
+  return usable ? declared : DEFAULT_VERDICT_FRESHNESS_MINUTES
+}
+
+// Floor readiness before the first traffic shift (#800 / identity-v0.4.1).
+//
+// Applicability is decided before the RC mint by production-endpoints.mjs. The shift gate
+// consumes that record rather than accepting a detached floor assertion: a distinct host cannot
+// be skipped, ALIVE must target the recorded canonical URL, and Cloud Run-only is accepted only
+// through the fingerprint-bound reasoned skip produced from equal endpoint reads.
+export function evaluateFloorReadiness(manifest, now = Date.now()) {
+  const release = (manifest && manifest.release) || {}
+  const envelope = (manifest && manifest.envelope) || {}
+  const floor = release.floorReadiness || null
+  const result = evaluateProductionFloor(release.productionEndpoints, floor, {
+    now,
+    freshnessMinutes: freshnessWindowMinutes(envelope),
+  })
+  return result.ok
+    ? { ok: true, id: null, evidence: result.evidence }
+    : { ok: false, id: "e:floor-not-ready", evidence: { floorReadiness: floor }, detail: `${result.id}: ${result.detail}` }
+}
+
+export function evaluateShift(manifest, verdict, now = Date.now()) {
+  const release = (manifest && manifest.release) || {}
+  const envelope = (manifest && manifest.envelope) || {}
+  const candidateUrl = release.candidateUrl
+  const failed = []
+  const evidence = { candidateUrl }
+  const normalizedVerdict = normalizeReleaseVerdict(verdict)
+
+  // (e) The candidate's smoke verdict must be ALIVE, on the EXACT candidate URL, and a
+  // --no-mutations run. A missing/malformed verdict, a mismatched target, an EMPTY or DEAD
+  // verdict, or a mutating run all HOLD. Comparing the recorded target is the whole point:
+  // it turns "on that exact candidate" from an assertion into a check.
+  evidence.verdict = normalizedVerdict && normalizedVerdict.state
+  evidence.verdictTarget = normalizedVerdict && normalizedVerdict.target
+  evidence.noMutations = normalizedVerdict && normalizedVerdict.noMutations
+  const green =
+    !!normalizedVerdict &&
+    typeof candidateUrl === 'string' &&
+    candidateUrl.length > 0 &&
+    normalizedVerdict.state === 'ALIVE' &&
+    normalizedVerdict.target === candidateUrl &&
+    normalizedVerdict.noMutations === true
+  if (!green) {
+    // Issue #823: a CANNOT-RUN (or BLOCKED) verdict is a gate failure, not a candidate failure.
+    // Distinguish it so the operator repairs the gate rather than deleting a healthy candidate.
+    if (normalizedVerdict && (normalizedVerdict.state === 'CANNOT-RUN' || normalizedVerdict.state === 'BLOCKED')) {
+      failed.push('e:cannot-run')
+    } else {
+      failed.push('e')
+    }
+  }
+
+  // (e)'s freshness half. Named as its own condition rather than folded into `e` so the
+  // operator can tell the two routes apart: a failed `e` means the candidate did not pass
+  // (route to step 5's pre-exposure path), while a failed freshness check means the evidence
+  // aged out while the authorization was pending — the candidate may be perfectly fine, and
+  // the route is back to step 4a to re-validate it, never onward to the shift.
+  const windowMinutes = freshnessWindowMinutes(envelope)
+  evidence.verdictFreshnessMinutes = windowMinutes
+  evidence.generatedAt = normalizedVerdict && normalizedVerdict.generatedAt
+  const stampedAt =
+    normalizedVerdict && typeof normalizedVerdict.generatedAt === 'string' ? Date.parse(normalizedVerdict.generatedAt) : NaN
+  if (!Number.isFinite(stampedAt)) {
+    // Absent evidence is not fresh evidence. A verdict with no readable stamp cannot be aged,
+    // so it can never be shown to be fresh — the fail-closed reading is HOLD, and it is the
+    // one an older smoke build (which stamped no timestamp at all) lands on.
+    failed.push('e:unstamped-verdict')
+  } else {
+    const ageMinutes = (now - stampedAt) / 60_000
+    evidence.verdictAgeMinutes = Math.round(ageMinutes * 100) / 100
+    // A NEGATIVE age — a stamp ahead of now — is not freshness either: it is a clock the gate
+    // cannot trust, and left unchecked a future-dated verdict would read as fresh forever.
+    if (ageMinutes < 0 || ageMinutes > windowMinutes) failed.push('e:stale-verdict')
+  }
+
+  // Floor public-host readiness (#800). Independent of (e): the candidate can be ALIVE on
+  // *.run.app while the public host is DEAD for a pre-existing edge reason. Named so the
+  // operator can tell "candidate bad" from "floor already broken".
+  const floor = evaluateFloorReadiness(manifest, now)
+  Object.assign(evidence, floor.evidence)
+  if (!floor.ok) failed.push(floor.id)
+
+  return { decision: failed.length === 0 ? 'fire' : 'hold', phase: 'shift', failed, evidence }
+}
+
+// ---- CLI ----
+
+const USAGE = `green-gate — the mechanized unattended-promotion gate for the release lane.
+
+Every (a)-(e) condition of the auto-when-green envelope is decided from an ARTIFACT and
+FAILS CLOSED: a missing or malformed input HOLDs, it never fires. The two subcommands
+mirror the doc's two authorization points.
+
+Usage:
+  green-gate promote --manifest <run-manifest.json>
+      Gate the promotion + rc mint on:
+        (a) fastForwardable === true
+        (b) PR-lane CI green, integration CI green, and (where the integration env records
+            one) the SHA-keyed smoke verdict ALIVE on the exact promoted SHA
+        (c) every release-readiness row PASS whose evidence BEGINS WITH a CHECKABLE
+            locator — a file path (real extension) / path:line / URL / #ref / backticked
+            command / mixed-hex SHA; prose that merely mentions a dotted abbreviation, a
+            date, or a hex word HOLDs — and the version cut committed with no tag collision
+        (d) no unresolved blocking finding on the combined diff
+      Carve-outs that force the human even when (a)-(d) hold:
+        - a major version bump (version.mjs plan bump === "major")
+        - rollback not armed (policy not auto-rollback, or candidate not deletable w/o confirm)
+        - irreversible content (destructive migration / unverifiable secret / first deploy)
+
+  green-gate shift   --manifest <run-manifest.json> --verdict <smoke-verdict.json>
+      Gate the traffic shift on:
+        (e) verdict === "ALIVE" AND target === candidateUrl AND noMutations === true
+            (EMPTY, DEAD, missing, CANNOT-RUN/BLOCKED, or an ALIVE from a different target all HOLD)
+        e:stale-verdict     the verdict's generatedAt is outside the freshness window
+            (envelope.verdictFreshnessMinutes; default ${DEFAULT_VERDICT_FRESHNESS_MINUTES} min, and an unreadable
+            declared window falls back to that default rather than widening). A future-dated
+            stamp is stale too. Route back to step 4a and re-validate the candidate — do NOT
+            shift on aged coordinates.
+        e:unstamped-verdict the verdict carries no readable generatedAt, so its age cannot
+            be bounded — absent evidence is not fresh evidence.
+        e:floor-not-ready   public-host (prod-active) readiness on the CURRENT production
+            floor is missing, DEAD/blocked, or skipped without a reason. Candidate ALIVE on
+            *.run.app is not floor readiness — CF Insights / edge scripts only inject on the
+            proxied public host (identity-v0.4.1 / #800). Record release.floorReadiness
+            {status:"alive", profile:"prod-active", target, checkedAt} or
+            {status:"skipped", reason} before the first shift.
+
+Exit codes:
+  0  FIRE — every condition holds, no carve-out triggered
+  1  HOLD — fall back to a per-step human confirm; the failing condition ids are named
+  2  usage / unreadable-input error — bad flags, unknown subcommand, or a manifest that is
+     absent, unparseable, or not a resolve-release run
+
+A condition whose input could not be produced is a FAILING condition, not a missing one: an
+applicable gate that cannot run is a failure, not an absence (principle 13). An absent
+credential, an unavailable service or a drifted fixture HOLDs exactly as a red result does —
+this gate cannot tell "nobody filled it in" from "nobody could", and neither is a result. An
+"n/a" is the other thing: a condition that does not apply here, decided, with a reason.
+
+A HOLD blocks THIS release — this SHA does not promote, this candidate takes no traffic. It
+is never a reason to pause the merge queue, dequeue an unrelated PR, or lift a branch
+protection: the repair reaches the repo through that lane, and a block that freezes it too is
+the one people bypass.
+
+Output: JSON { decision: "fire"|"hold", phase, failed: [<condition ids>], evidence: {...} }
+
+Doctrine (why each condition, the two authorization points, the (e)-must-be-artifact rule,
+the carve-outs): references/auto-when-green.md.`
+
+function parseArgs(argv) {
+  const opts = {}
+  const positional = []
+  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 positional.push(a)
+  }
+  return { opts, positional }
+}
+
+// Read + parse the run manifest. Distinguishes the two exit-2 causes (no path given, file
+// unreadable/unparseable, wrong-shape run) from a HOLD: you cannot evaluate ANY condition
+// without a readable resolve-release manifest, so those are operational errors, not
+// condition failures.
+function loadManifest(file) {
+  if (!file) return { error: 'usage: --manifest <run-manifest.json> is required' }
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch {
+    return { error: `manifest not readable: ${file}` }
+  }
+  let manifest
+  try {
+    manifest = JSON.parse(raw)
+  } catch {
+    return { error: `manifest is not valid JSON: ${file}` }
+  }
+  if (!manifest || typeof manifest !== 'object' || !manifest.envelope) {
+    return { error: `not a resolve-release run manifest (no authorization envelope): ${file}` }
+  }
+  return { manifest }
+}
+
+// A verdict file that is absent or unparseable is a HOLD, not an error: a missing
+// smoke-verdict.json must never fire the traffic shift. Returns null on any failure, which
+// evaluateShift treats as a (e) HOLD.
+function loadVerdict(file) {
+  if (!file) return null
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function main(argv) {
+  const { opts, positional } = parseArgs(argv)
+  const cmd = positional[0]
+
+  // Only an EXPLICIT help request earns exit 0. A missing subcommand fails CLOSED to the
+  // same exit-2 usage error as an unknown one: `green-gate <empty> --manifest …` (or a bare
+  // invocation) inside `green-gate … && shift-traffic` must NOT print usage and exit 0 — a
+  // 0 there is a FIRE, shifting production traffic on no gate at all.
+  if (opts.help || cmd === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+
+  if (cmd !== 'promote' && cmd !== 'shift') {
+    const what = cmd ? `unknown command "${cmd}"` : 'no subcommand given'
+    console.error(`green-gate: ${what}. Use promote|shift (see --help).`)
+    return 2
+  }
+
+  const loaded = loadManifest(opts.manifest)
+  if (loaded.error) {
+    console.error(`green-gate: ${loaded.error}`)
+    return 2
+  }
+
+  let result
+  if (cmd === 'promote') {
+    result = evaluatePromote(loaded.manifest)
+  } else {
+    if (!opts.verdict) {
+      console.error('green-gate: usage: shift requires --verdict <smoke-verdict.json>')
+      return 2
+    }
+    result = evaluateShift(loaded.manifest, loadVerdict(opts.verdict))
+  }
+
+  console.log(JSON.stringify(result, null, 2))
+  return result.decision === 'fire' ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}