@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/rollback-floor.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// rollback-floor — terminal close when floor smoke cannot go ALIVE after a correct restore (#800).
+//
+// Doctrine wants smoke ALIVE for verified-rollback (routing.md). identity-v0.4.1 attempt.1
+// restored traffic to v0.4.0 correctly, then prod-active stayed DEAD on the incumbent for the
+// same pre-existing CF Insights vs app CSP reason (identity#677). Agents had no terminal path
+// and invented lease states or blamed the candidate code.
+//
+// This module defines the close:
+//   state: rolled-back
+//   closedBy: verified-rollback
+//   smoke: blocked-by-preexisting-gate
+//   incident: REQUIRED
+// when traffic+attestation prove restore AND the floor itself fails the same check.
+//
+// Pure classifier — the agent (or a thin CLI) still issues the traffic restore and the
+// record-release-attempt call; this only decides whether that close is legal and shapes
+// the evidence string. It does not invent a new lease state.
+//
+// Doctrine: references/routing.md § Verification failed after exposure.
+// Regression: identity-v0.4.1 · identity#677 · #800.
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const SMOKE_BLOCKED_BY_PREEXISTING_GATE = 'blocked-by-preexisting-gate'
+
+/**
+ * Concrete traffic attestation is required for any verified-rollback close.
+ * A missing/empty/malformed attestation must not produce evidence that claims
+ * "traffic+attestation verified" (#800 / identity-v0.4.1).
+ */
+export function hasConcreteAttestation(attestation) {
+  if (!attestation || typeof attestation !== 'object' || Array.isArray(attestation)) return false
+  // Accept a revision id, a source SHA, a resource name, or an explicit verified flag.
+  const revision = attestation.revision != null ? String(attestation.revision).trim() : ''
+  const sourceSha = attestation.sourceSha != null ? String(attestation.sourceSha).trim() : ''
+  const resource = attestation.resource != null ? String(attestation.resource).trim() : ''
+  if (revision || sourceSha || resource) return true
+  if (attestation.verified === true || attestation.ok === true) return true
+  return false
+}
+
+/**
+ * @param {object} input
+ * @param {{ previousRevision?: string, previousPercent?: number, candidatePercent?: number, attestation?: object }} input.traffic
+ * @param {{ verdict?: string, profile?: string, target?: string, floorAlsoDead?: boolean, reason?: string }} input.smoke
+ * @param {{ number?: number, url?: string } | null} input.incidentIssue
+ */
+export function classifyRollbackClose({ traffic = {}, smoke = {}, incidentIssue = null } = {}) {
+  const prevPct = Number(traffic.previousPercent)
+  const candPct = traffic.candidatePercent == null ? 0 : Number(traffic.candidatePercent)
+  const percentsRestored =
+    typeof traffic.previousRevision === 'string' &&
+    traffic.previousRevision.length > 0 &&
+    Number.isFinite(prevPct) &&
+    prevPct === 100 &&
+    Number.isFinite(candPct) &&
+    candPct === 0
+
+  if (!percentsRestored) {
+    return {
+      closeable: false,
+      reason: 'traffic-not-restored',
+      detail: 'verified-rollback requires previousRevision at exactly 100% and candidate at 0%',
+    }
+  }
+
+  // Attestation is part of the restore proof, not optional garnish. Without it the
+  // close cannot claim "traffic+attestation verified".
+  if (!hasConcreteAttestation(traffic.attestation)) {
+    return {
+      closeable: false,
+      reason: 'attestation-missing',
+      detail:
+        'verified-rollback requires traffic.attestation with a concrete revision/sourceSha/resource (or verified:true); percents alone are not enough',
+    }
+  }
+
+  const verdict = String(smoke.verdict || '').toUpperCase()
+  if (verdict === 'ALIVE') {
+    // Standard path — still requires an incident on post-exposure rollback (routing.md).
+    if (!hasIncident(incidentIssue)) {
+      return {
+        closeable: false,
+        reason: 'incident-required',
+        detail: 'post-exposure rollback always files an incident issue',
+        closedBy: 'verified-rollback',
+        smoke: 'ALIVE',
+      }
+    }
+    return {
+      closeable: true,
+      closedBy: 'verified-rollback',
+      smoke: 'ALIVE',
+      requiresIncident: true,
+      incidentIssue: normalizeIncident(incidentIssue),
+      traffic: {
+        previousRevision: traffic.previousRevision,
+        previousPercent: 100,
+        candidatePercent: 0,
+        attestation: traffic.attestation,
+      },
+    }
+  }
+
+  // DEAD / EMPTY / cannot-run: only closeable when the floor itself is known to fail the
+  // same check (pre-existing gate/env), not when the restore may have left production bad.
+  if (verdict === 'DEAD' || verdict === 'EMPTY' || verdict === 'CANNOT-RUN' || verdict === 'CANNOT_RUN') {
+    if (!smoke.floorAlsoDead) {
+      return {
+        closeable: false,
+        reason: 'smoke-dead-without-floor-preexistence',
+        detail:
+          'prod-active DEAD after restore without floorAlsoDead evidence — do not invent a close; page and establish whether the incumbent itself fails the same check',
+      }
+    }
+    if (!hasIncident(incidentIssue)) {
+      return {
+        closeable: false,
+        reason: 'incident-required',
+        detail: 'blocked-by-preexisting-gate requires a filed incident issue (identity#677 class)',
+        smoke: SMOKE_BLOCKED_BY_PREEXISTING_GATE,
+      }
+    }
+    return {
+      closeable: true,
+      closedBy: 'verified-rollback',
+      smoke: SMOKE_BLOCKED_BY_PREEXISTING_GATE,
+      requiresIncident: true,
+      incidentIssue: normalizeIncident(incidentIssue),
+      floorReason: smoke.reason || 'pre-existing floor gate/env failure',
+      traffic: {
+        previousRevision: traffic.previousRevision,
+        previousPercent: 100,
+        candidatePercent: 0,
+        attestation: traffic.attestation,
+      },
+    }
+  }
+
+  return {
+    closeable: false,
+    reason: 'smoke-unreadable',
+    detail: `smoke verdict ${JSON.stringify(smoke.verdict)} is not ALIVE or a floor-preexistence DEAD`,
+  }
+}
+
+export function buildRollbackClosePayload(classified) {
+  if (!classified || !classified.closeable) {
+    throw new Error(
+      `buildRollbackClosePayload: not closeable (${classified && classified.reason}) — ${classified && classified.detail}`,
+    )
+  }
+  const rev = classified.traffic.previousRevision
+  const incident = classified.incidentIssue
+  const incidentRef = incident.number != null ? `#${incident.number}` : incident.url
+  let evidence
+  if (classified.smoke === SMOKE_BLOCKED_BY_PREEXISTING_GATE) {
+    evidence =
+      `${rev} restored to 100%; traffic+attestation verified; ` +
+      `smoke: ${SMOKE_BLOCKED_BY_PREEXISTING_GATE} (${classified.floorReason}); ` +
+      `incident ${incidentRef}`
+  } else {
+    evidence =
+      `${rev} restored to 100%; smoke ALIVE against live service; incident ${incidentRef}`
+  }
+  return {
+    state: 'rolled-back',
+    closedBy: classified.closedBy,
+    evidence,
+    smoke: classified.smoke,
+    incidentIssue: incident,
+  }
+}
+
+function hasIncident(issue) {
+  return !!(issue && (issue.number != null || issue.url))
+}
+
+function normalizeIncident(issue) {
+  if (!issue) return null
+  return {
+    number: issue.number != null ? Number(issue.number) : null,
+    url: issue.url || null,
+  }
+}
+
+export const USAGE = `rollback-floor — classify a post-exposure rollback close when floor smoke cannot pass.
+
+  rollback-floor classify --traffic <json> --smoke <json> [--incident <json>]
+      Pure decision. Prints {closeable, closedBy, smoke, ...}. Exit 0 always when readable;
+      exit 2 on usage.
+
+  rollback-floor payload  --traffic <json> --smoke <json> --incident <json>
+      Shape the record-release-attempt JSON when closeable. Exit 0 on closeable, 1 otherwise.
+
+Why: identity-v0.4.1 restored traffic correctly then prod-active stayed DEAD on the
+incumbent (CF Insights vs CSP, identity#677). Without this path agents invent lease
+states. See references/routing.md and issue #800.`
+
+export function parseArgs(argv) {
+  const args = { positional: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') args.help = true
+    else if (a === '--traffic') args.traffic = argv[++i]
+    else if (a === '--smoke') args.smoke = argv[++i]
+    else if (a === '--incident') args.incident = argv[++i]
+    else if (a.startsWith('-')) args.unknown = a
+    else args.positional.push(a)
+  }
+  args.cmd = args.positional[0] || null
+  return args
+}
+
+function parseJsonFlag(raw, name) {
+  if (!raw) return null
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`${name} is not valid JSON: ${err.message}`)
+  }
+}
+
+export function main(argv) {
+  const args = parseArgs(argv)
+  if (args.help || args.cmd === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+  if (args.unknown) {
+    console.error(`rollback-floor: unknown flag ${args.unknown}`)
+    return 2
+  }
+  if (!args.cmd || !['classify', 'payload'].includes(args.cmd)) {
+    console.error('rollback-floor: use classify|payload (see --help)')
+    return 2
+  }
+  try {
+    const traffic = parseJsonFlag(args.traffic, '--traffic') || {}
+    const smoke = parseJsonFlag(args.smoke, '--smoke') || {}
+    const incidentIssue = parseJsonFlag(args.incident, '--incident')
+    const classified = classifyRollbackClose({ traffic, smoke, incidentIssue })
+    if (args.cmd === 'classify') {
+      console.log(JSON.stringify(classified, null, 2))
+      return 0
+    }
+    if (!classified.closeable) {
+      console.error(`rollback-floor: not closeable — ${classified.reason}: ${classified.detail}`)
+      console.log(JSON.stringify(classified, null, 2))
+      return 1
+    }
+    console.log(JSON.stringify(buildRollbackClosePayload(classified), null, 2))
+    return 0
+  } catch (err) {
+    console.error(`rollback-floor: ${err.message}`)
+    return 2
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}

package/skills/engineering/resolve-release/scripts/version-assert.mjs

@@ -0,0 +1,339 @@
+// version-assert — display-version policy check for the release lane (issue #822).
+//
+// A release has two version concepts:
+//   - identity version: the immutable tag / SHA that names what is running
+//     (candidate-identity.mjs owns this: sourceSha, revision, imageDigest).
+//   - display version: the string the running service prints in UI and /api/health.
+//
+// Under rc-tag deploy topology the pipeline triggers on vX.Y.Z-rc.N, but the version
+// that should be SHOWN to operators is the final vX.Y.Z — otherwise a verified release
+// leaves every dashboard claiming it is still an rc. This script asserts that the
+// serving health endpoint's displayed version matches the policy declared in the
+// authorization envelope, or records an explicit exception.
+//
+// Contract:
+//   version-assert serving --health <health.json> --settings <settings.json> --frontend-asset <asset.json> [--policy <policy>] [--deploy-trigger <topology>] [--version <v>] [--sha <sha>] [--trigger-tag <tag>] [--record-mismatch <reason>]
+//       Reads the health, settings, and frontend-asset JSON files, extracts each `version`
+//       display value, and checks every one against the policy. Prints JSON
+//       { decision, policy, displayed, expected, mismatch, failed }.
+//         final-semver  --version <v>      displayed version must equal the final semver vX.Y.Z
+//         trigger-tag   --trigger-tag <t>  displayed version must equal the attempt tag (e.g. vX.Y.Z-rc.N)
+//         short-sha     --sha <sha>        displayed version must match the short SHA
+//       --deploy-trigger rc-tag  when --policy is omitted, resolves to final-semver (the rc-tag default).
+//       --record-mismatch <reason>  on mismatch, record a declared exception and ACCEPT instead of refusing.
+//
+//   exit 0 = ACCEPT  — display version matches policy, or a mismatch was recorded with reason.
+//   exit 1 = REFUSE  — display version does not match policy and no exception was recorded.
+//   exit 2 = usage / unreadable-input error.
+
+import fs from 'node:fs'
+import { shaMatches } from './candidate-identity.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const DISPLAY_VERSION_POLICIES = ['final-semver', 'trigger-tag', 'short-sha']
+
+// Health endpoints may render with or without a leading 'v'. Normalize so the policy
+// comparison is about the version, not the rendering choice.
+export function normalizeVersion(s) {
+  if (typeof s !== 'string') return ''
+  return s.trim().toLowerCase().replace(/^v/, '')
+}
+
+export function isSemver(s) {
+  return /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/i.test(String(s ?? '').replace(/^v/, ''))
+}
+
+// Compute the expected display string from the policy and the supplied identity inputs.
+export function expectedDisplayVersion(policy, { version, triggerTag, sha } = {}) {
+  if (policy === 'final-semver') {
+    const v = normalizeVersion(version)
+    if (!isSemver(v)) return null
+    // Expected display is the release semver, with no prerelease segment.
+    const base = v.split('-')[0].split('+')[0]
+    return base
+  }
+  if (policy === 'trigger-tag') {
+    const t = normalizeVersion(triggerTag)
+    return t || null
+  }
+  if (policy === 'short-sha') {
+    const s = String(sha ?? '').trim().toLowerCase()
+    if (!s) return null
+    return s.slice(0, 7)
+  }
+  return null
+}
+
+// Resolve an omitted policy against the deploy topology. rc-tag defaults to
+// final-semver so a verified release does not leave operators staring at the
+// attempt tag while the published tag is the final semver.
+export function resolveDisplayVersionPolicy(policy, deployTrigger) {
+  if (policy) return { policy }
+  if (deployTrigger === 'rc-tag') return { policy: 'final-semver' }
+  return { error: 'e:missing-display-version-policy' }
+}
+
+// Read the display version from a health JSON payload. Field aliases are intentionally
+// narrow: the point is to read a real endpoint, not to accept anything version-shaped.
+export function readDisplayVersion(health) {
+  if (!health || typeof health !== 'object') return { error: 'e:unreadable-health' }
+  const version = health.version ?? health.displayVersion ?? health.deployedVersion ?? health.DEPLOYED_VERSION
+  if (typeof version !== 'string' || version.trim().length === 0) {
+    return { error: 'e:no-display-version', missing: ['version'] }
+  }
+  return { version: version.trim() }
+}
+
+export function evaluateDisplayVersion({ health, settings, frontendAsset, policy, version, triggerTag, sha, recordMismatch = null }) {
+  if (!DISPLAY_VERSION_POLICIES.includes(policy)) {
+    return { decision: 'refuse', phase: 'display-version', policy, failed: ['e:unknown-policy'], evidence: {} }
+  }
+
+  const sourceInputs = [
+    ['health', health],
+    ['settings', settings],
+    ['frontend-asset', frontendAsset],
+  ].filter(([, value]) => value !== undefined)
+  const displayedBySource = {}
+  for (const [source, input] of sourceInputs) {
+    const read = readDisplayVersion(input)
+    if (read.error) {
+      const error = source === 'health' ? read.error : `${read.error}:${source}`
+      return { decision: 'refuse', phase: 'display-version', policy, failed: [error], evidence: { missing: read.missing } }
+    }
+    displayedBySource[source] = read.version
+  }
+
+  const displayed = sourceInputs.length === 1 ? displayedBySource.health : displayedBySource
+  const expected = expectedDisplayVersion(policy, { version, triggerTag, sha })
+  if (expected == null) {
+    return {
+      decision: 'refuse',
+      phase: 'display-version',
+      policy,
+      displayed,
+      failed: ['e:missing-expected-input'],
+      evidence: { policy, version, triggerTag, sha },
+    }
+  }
+
+  const mismatchedSources = Object.entries(displayedBySource)
+    .filter(([, sourceDisplayed]) => (
+      policy === 'short-sha'
+        ? !shaMatches(sourceDisplayed, expected)
+        : normalizeVersion(sourceDisplayed) !== normalizeVersion(expected)
+    ))
+    .map(([source]) => source)
+
+  if (mismatchedSources.length === 0) {
+    return {
+      decision: 'accept',
+      phase: 'display-version',
+      policy,
+      displayed,
+      expected,
+      mismatch: null,
+      failed: [],
+    }
+  }
+
+  if (recordMismatch && String(recordMismatch).trim().length > 0) {
+    return {
+      decision: 'accept',
+      phase: 'display-version',
+      policy,
+      displayed,
+      expected,
+      mismatch: { recorded: true, reason: String(recordMismatch).trim(), sources: mismatchedSources },
+      failed: [],
+    }
+  }
+
+  return {
+    decision: 'refuse',
+    phase: 'display-version',
+    policy,
+    displayed,
+    expected,
+    mismatch: null,
+    failed: mismatchedSources.map((source) => (
+      source === 'health' ? 'e:display-version-mismatch' : `e:display-version-mismatch:${source}`
+    )),
+  }
+}
+
+const USAGE = `version-assert — display-version policy check for the release lane.
+
+A release has an identity version (the immutable tag/SHA that names what is running,
+owned by candidate-identity.mjs) and a display version (the string UI and /api/health
+show). Under rc-tag topology the pipeline triggers on vX.Y.Z-rc.N, but the operator-
+visible version should be vX.Y.Z unless the envelope deliberately says otherwise.
+
+Usage:
+  version-assert serving --health <health.json> --settings <settings.json> --frontend-asset <asset.json> --policy <policy> [policy-inputs] [--record-mismatch <reason>]
+  version-assert serving --health <health.json> --settings <settings.json> --frontend-asset <asset.json> --deploy-trigger rc-tag [policy-inputs] [--record-mismatch <reason>]
+
+All three JSON inputs must expose the operator-visible version under version,
+displayVersion, deployedVersion, or DEPLOYED_VERSION.
+
+Policies:
+  final-semver  --version <v>       displayed version must equal the final semver vX.Y.Z
+  trigger-tag   --trigger-tag <t>   displayed version must equal the attempt tag (e.g. vX.Y.Z-rc.N)
+  short-sha     --sha <sha>         displayed version must match the short SHA
+
+  --deploy-trigger <rc-tag|branch-push|final-tag|no-deploy>
+                              when --policy is omitted, rc-tag resolves to final-semver;
+                              other topologies must declare the policy explicitly.
+  --record-mismatch <reason>  on mismatch, record a declared exception and ACCEPT instead of refusing.
+
+Exit codes:
+  0  ACCEPT — display version matches policy, or a mismatch was recorded with reason
+  1  REFUSE — display version does not match policy and no exception was recorded
+  2  usage / unreadable-input error / missing policy on a topology with no default
+
+Output: JSON { decision, phase, policy, displayed, expected, mismatch, failed }
+
+Doctrine (display vs identity version, rc-tag default, Cloud Build strip pattern):
+references/versioning.md.`
+
+/** Known serving flags that take a value. Anything else is refused (exit 2). */
+const KNOWN_VALUE_FLAGS = new Set([
+  'health',
+  'settings',
+  'frontend-asset',
+  'policy',
+  'version',
+  'sha',
+  'trigger-tag',
+  'deploy-trigger',
+  'record-mismatch',
+])
+
+function parseArgs(argv) {
+  const opts = {}
+  const positional = []
+  const unknown = []
+  const missing = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') {
+      opts.help = true
+      continue
+    }
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      if (!KNOWN_VALUE_FLAGS.has(key)) {
+        unknown.push(a)
+        // If the next token looks like a value (not a flag), consume it so it is not
+        // re-classified as a bare positional — the flag itself is the error.
+        const next = argv[i + 1]
+        if (next !== undefined && !next.startsWith('-')) i++
+        continue
+      }
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith('-')) {
+        if (next !== undefined && next.startsWith('-')) {
+          // leave next token for the next iteration (flag/unknown)
+        }
+        missing.push(a)
+        continue
+      }
+      opts[key] = next
+      i++
+      continue
+    }
+    positional.push(a)
+  }
+  return { opts, positional, unknown, missing }
+}
+
+function readJson(file, what) {
+  if (!file) return { error: `usage: --${what} <file> is required` }
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch {
+    return { error: `${what} not readable: ${file}` }
+  }
+  try {
+    return { value: JSON.parse(raw) }
+  } catch {
+    return { error: `${what} is not valid JSON: ${file}` }
+  }
+}
+
+export function main(argv) {
+  const { opts, positional, unknown, missing } = parseArgs(argv)
+  const cmd = positional[0]
+  const extraPositionals = positional.slice(1)
+
+  if (opts.help || cmd === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+
+  if (unknown.length > 0) {
+    console.error(`version-assert: unknown argument(s): ${unknown.join(', ')}`)
+    return 2
+  }
+  if (missing.length > 0) {
+    console.error(`version-assert: missing or invalid value for: ${missing.join(', ')}`)
+    return 2
+  }
+  if (extraPositionals.length > 0) {
+    console.error(`version-assert: unexpected positional argument(s): ${extraPositionals.join(', ')}`)
+    return 2
+  }
+
+  if (cmd !== 'serving') {
+    const what = cmd ? `unknown command "${cmd}"` : 'no subcommand given'
+    console.error(`version-assert: ${what}. Use serving (see --help).`)
+    return 2
+  }
+
+  const health = readJson(opts.health, 'health')
+  const settings = readJson(opts.settings, 'settings')
+  const frontendAsset = readJson(opts['frontend-asset'], 'frontend-asset')
+  for (const source of [health, settings, frontendAsset]) {
+    if (source.error) {
+      console.error(`version-assert: ${source.error}`)
+      return 2
+    }
+  }
+
+  if (!opts.policy && !opts['deploy-trigger']) {
+    console.error('version-assert: serving requires --policy <final-semver|trigger-tag|short-sha>, or --deploy-trigger <topology> to resolve a default')
+    return 2
+  }
+
+  // Explicit --policy must be a known policy before we evaluate health. An invalid
+  // policy is a usage error (exit 2), not a display-version mismatch (exit 1).
+  if (opts.policy && !DISPLAY_VERSION_POLICIES.includes(opts.policy)) {
+    console.error(`version-assert: unknown policy "${opts.policy}". Use one of: ${DISPLAY_VERSION_POLICIES.join(', ')}`)
+    return 2
+  }
+
+  const resolved = resolveDisplayVersionPolicy(opts.policy, opts['deploy-trigger'])
+  if (resolved.error) {
+    console.error(`version-assert: ${resolved.error}: --policy is required when --deploy-trigger is not rc-tag`)
+    return 2
+  }
+
+  const result = evaluateDisplayVersion({
+    health: health.value,
+    settings: settings.value,
+    frontendAsset: frontendAsset.value,
+    policy: resolved.policy,
+    version: opts.version ?? null,
+    triggerTag: opts['trigger-tag'] ?? null,
+    sha: opts.sha ?? null,
+    recordMismatch: opts['record-mismatch'] ?? null,
+  })
+
+  console.log(JSON.stringify(result, null, 2))
+  return result.decision === 'accept' ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}