@1aboveio/skills 0.18.0 → 0.19.0

package/skills/engineering/rush-issues/scripts/preflight-models.mjs

@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+// Rush fast path for model selection.
+//
+// One command: discover → tier (shared harness-runtime catalog) → recommend
+// implementer + fill explorer + fill reviewer ≠ implementer. Prints a ready
+// ask payload so the orchestrator can feed it into the shared preflight planner
+// without reading longer workflow doctrine before model selection.
+//
+// Maintenance (sync / bank) is deferred until AFTER the human answers — never
+// block the picker on catalog writes.
+//
+// Usage:
+//   node preflight-models.mjs --harness <pi|codex|claude-code> [--risk routine|high]
+//        [--available id,id,...] [--human-named id,id,...] [--ask-only]
+//
+// Exit: 0 ok · 2 usage · 3 discovery yielded nothing proposable
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  detectHarness,
+  discover,
+} from '../../harness-runtime/discover-models.mjs'
+import {
+  tierProposals,
+  pointsFromTiers,
+  isSlotEligible,
+  DEFAULT_EFFORT,
+  readCatalog,
+  pathForHarness,
+  readSeed,
+  defaultSeedPath,
+  findSeedEntry,
+} from '../../harness-runtime/model-catalog.mjs'
+
+export const RISK = Object.freeze(['routine', 'high'])
+
+// Preferred fills when discovery actually yielded the id (rush skill defaults).
+export const TEAM_REVIEWER_DEFAULT = Object.freeze({
+  pi: { id: 'openai/gpt-5.5', family: 'openai', effort: 'high', tier: 'deep-reasoner' },
+  codex: { id: 'gpt-5.5', family: 'openai', effort: 'high', tier: 'deep-reasoner' },
+  'claude-code': { id: 'gpt-5.5', family: 'openai', effort: 'high', tier: 'deep-reasoner' },
+})
+
+export const TEAM_EXPLORER_DEFAULT = Object.freeze({
+  pi: { id: 'openai/gpt-5.6-terra', family: 'openai', effort: 'high', tier: 'balanced-coder' },
+  codex: { id: 'gpt-5.6-terra', family: 'openai', effort: 'high', tier: 'balanced-coder' },
+  'claude-code': { id: 'gpt-5.6-terra', family: 'openai', effort: 'high', tier: 'balanced-coder' },
+})
+
+const TIER_RANK = Object.freeze({
+  frontier: 0,
+  'deep-reasoner': 1,
+  'balanced-coder': 2,
+})
+
+function usage() {
+  return `preflight-models — discover + recommend implementer, fill explorer + reviewer (rush fast path)
+
+Usage:
+  node preflight-models.mjs --harness <pi|codex|claude-code> [--risk routine|high]
+       [--available <id,id,...>] [--human-named <id,id,...>] [--ask-only]
+
+Output JSON:
+  { harness, risk, discovery, models, implementer, explorer, reviewer, ask, deferred }
+
+--ask-only prints only the ask block (for piping into a question UI).
+Deferred: run catalog sync/bank AFTER the human answers — never before the ask.`
+}
+
+function parseList(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+export function parseArgs(argv) {
+  const out = {
+    harness: null,
+    risk: 'routine',
+    available: [],
+    humanNamed: [],
+    askOnly: false,
+    help: false,
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h' || a === 'help') out.help = true
+    else if (a === '--ask-only') out.askOnly = true
+    else if (a === '--harness') out.harness = argv[++i]
+    else if (a === '--risk') out.risk = argv[++i]
+    else if (a === '--available') out.available = parseList(argv[++i])
+    else if (a === '--human-named') out.humanNamed = parseList(argv[++i])
+    else if (a.startsWith('--harness=')) out.harness = a.slice('--harness='.length)
+    else if (a.startsWith('--risk=')) out.risk = a.slice('--risk='.length)
+    else if (a.startsWith('--available=')) out.available = parseList(a.slice('--available='.length))
+    else if (a.startsWith('--human-named=')) out.humanNamed = parseList(a.slice('--human-named='.length))
+    else throw new Error(`unknown argument: ${a}`)
+  }
+  return out
+}
+
+function familyOf(id, hinted) {
+  if (hinted) return hinted
+  if (id.includes('/')) return id.slice(0, id.indexOf('/'))
+  return 'unknown'
+}
+
+/** Prefer banked catalog family, then seed, then id prefix. */
+export function resolveFamily(harness, id, { catalog = null, seed = null } = {}) {
+  const banked = (catalog?.models || []).find((m) => m && m.id === id)
+  if (banked?.family) return banked.family
+  const seeded = seed ? findSeedEntry(seed, harness, id) : null
+  if (seeded?.family) return seeded.family
+  return familyOf(id)
+}
+
+function pointKey(id, effort) {
+  return `${id}@${effort || DEFAULT_EFFORT}`
+}
+
+/** Expand tierProposals().models into slot-eligible operating points. */
+export function slotPoints(tieredModels, { harness, catalog = null, seed = null } = {}) {
+  const points = []
+  for (const model of tieredModels) {
+    const entries = Object.keys(model.tiers || {}).length
+      ? pointsFromTiers(model.tiers)
+      : []
+    const family = resolveFamily(harness, model.id, { catalog, seed })
+    for (const p of entries) {
+      if (!isSlotEligible(p.tier)) continue
+      points.push({
+        id: model.id,
+        effort: p.effort || DEFAULT_EFFORT,
+        tier: p.tier,
+        family,
+        source: model.source,
+        citation: model.citation || null,
+        key: pointKey(model.id, p.effort || DEFAULT_EFFORT),
+      })
+    }
+  }
+  return points
+}
+
+function preferRisk(tier, risk) {
+  if (risk === 'high') {
+    if (tier === 'deep-reasoner') return 0
+    if (tier === 'balanced-coder') return 1
+    return 2 // frontier never recommended for implementer
+  }
+  // routine
+  if (tier === 'balanced-coder') return 0
+  if (tier === 'deep-reasoner') return 1
+  return 2
+}
+
+/**
+ * Recommend implementer: never frontier as the recommendation (still listed).
+ * routine → balanced-coder; high → deep-reasoner.
+ */
+export function recommendImplementer(points, risk = 'routine') {
+  if (!points.length) return null
+  const sorted = [...points].sort((a, b) => {
+    const ra = preferRisk(a.tier, risk)
+    const rb = preferRisk(b.tier, risk)
+    if (ra !== rb) return ra - rb
+    // Prefer the floor effort when tied; then stable id.
+    if (a.effort !== b.effort) {
+      if (a.effort === DEFAULT_EFFORT) return -1
+      if (b.effort === DEFAULT_EFFORT) return 1
+      return a.effort < b.effort ? -1 : 1
+    }
+    return a.id.localeCompare(b.id)
+  })
+  // First non-frontier if any; else first point (single-model / only-frontier harness)
+  return sorted.find((p) => p.tier !== 'frontier') || sorted[0]
+}
+
+function findPreferredPoint(points, preferred) {
+  if (!preferred) return null
+  return points.find(
+    (p) => p.id === preferred.id && (p.effort || DEFAULT_EFFORT) === (preferred.effort || DEFAULT_EFFORT),
+  ) || null
+}
+
+/**
+ * Explorer fill: balanced-coder; prefers gpt-5.6-terra@high when discovered.
+ */
+export function fillExplorer(points, harness) {
+  const preferred = TEAM_EXPLORER_DEFAULT[harness] || null
+  const preferredPoint = findPreferredPoint(points, preferred)
+  if (preferredPoint && preferredPoint.tier === 'balanced-coder') {
+    return { fill: preferredPoint, reason: 'team-default' }
+  }
+  const balanced = points
+    .filter((p) => p.tier === 'balanced-coder')
+    .sort((a, b) => {
+      if (a.effort === DEFAULT_EFFORT && b.effort !== DEFAULT_EFFORT) return -1
+      if (b.effort === DEFAULT_EFFORT && a.effort !== DEFAULT_EFFORT) return 1
+      return a.id.localeCompare(b.id)
+    })
+  const fill = balanced[0] || null
+  return {
+    fill,
+    reason: fill ? (preferredPoint ? 'ladder' : 'balanced-coder') : 'none',
+  }
+}
+
+/**
+ * Reviewer fill: deep-reasoner preferred (gpt-5.5@high when discovered),
+ * must differ from implementer. Ladder is diversity-first among remaining points.
+ */
+export function rankReviewers(points, implementer, harness) {
+  const team = TEAM_REVIEWER_DEFAULT[harness] || null
+  const deepPool = points.filter((p) => p.tier === 'deep-reasoner' || p.tier === 'frontier')
+  const pool = deepPool.length ? deepPool : points
+  const scored = pool.map((p) => {
+    const sameId = p.id === implementer.id
+    const sameFamily = p.family && implementer.family && p.family === implementer.family
+    let diversity
+    if (sameId) diversity = 5
+    else if (!sameFamily && p.tier === 'deep-reasoner') diversity = 0
+    else if (!sameFamily && p.tier === 'frontier') diversity = 1
+    else if (sameFamily && p.tier === 'deep-reasoner') diversity = 2
+    else if (!sameFamily) diversity = 3
+    else diversity = 4
+    return { ...p, diversity, tierRank: TIER_RANK[p.tier] ?? 9 }
+  })
+  scored.sort((a, b) => {
+    if (a.diversity !== b.diversity) return a.diversity - b.diversity
+    if (a.tierRank !== b.tierRank) return a.tierRank - b.tierRank
+    return a.id.localeCompare(b.id)
+  })
+
+  const teamPoint = findPreferredPoint(points, team)
+
+  let fill
+  let reason
+  if (teamPoint && teamPoint.id !== implementer.id) {
+    fill = teamPoint
+    reason = 'team-default'
+  } else {
+    fill = scored.find((p) => p.id !== implementer.id) || scored[0]
+    reason = fill?.id === implementer.id ? 'no-distinct-candidate' : 'ladder'
+  }
+
+  return {
+    fill,
+    reason,
+    ranking: scored,
+    teamDefaultApplied: reason === 'team-default',
+    reducedDiversity: !!(fill && implementer && fill.family && fill.family === implementer.family && fill.id !== implementer.id),
+    notIndependent: !!(fill && implementer && fill.id === implementer.id),
+  }
+}
+
+function optionFromPoint(p, { recommended = false, role }) {
+  const why =
+    role === 'implementer'
+      ? p.tier === 'balanced-coder'
+        ? 'routine implementer band'
+        : p.tier === 'deep-reasoner'
+          ? 'deep-reasoner for risk-heavy work'
+          : p.tier === 'frontier'
+            ? 'frontier (alternate only — not the rush recommendation)'
+            : p.tier
+      : p.tier
+  return {
+    id: p.key, // operating point id for the picker; parse back to model+effort
+    modelId: p.id,
+    label: `${p.id} @ ${p.effort}`,
+    description: `${p.tier}${recommended ? ' · recommended' : ''} · ${why}`,
+    family: p.family,
+    effort: p.effort,
+    tier: p.tier,
+  }
+}
+
+/** Native question UIs typically allow 2–4 options. Keep the rest as `alternates`. */
+export const ASK_OPTION_LIMIT = 4
+
+function slotFillPayload(slot) {
+  if (!slot?.fill) return null
+  return {
+    id: slot.fill.key,
+    modelId: slot.fill.id,
+    effort: slot.fill.effort,
+    family: slot.fill.family,
+    tier: slot.fill.tier,
+    reason: slot.reason,
+    reducedDiversity: slot.reducedDiversity || false,
+    notIndependent: slot.notIndependent || false,
+  }
+}
+
+export function buildAsk(implementer, points, reviewer, { risk = 'routine', explorer = null } = {}) {
+  const seen = new Set()
+  const ordered = []
+  const push = (p) => {
+    if (!p || seen.has(p.key)) return
+    seen.add(p.key)
+    ordered.push(p)
+  }
+  push(implementer)
+  // Prefer risk-matched bands next; always try to keep one frontier visible.
+  const rest = [...points].sort((a, b) => preferRisk(a.tier, risk) - preferRisk(b.tier, risk) || a.id.localeCompare(b.id))
+  for (const p of rest) push(p)
+  const frontier = ordered.find((p) => p.tier === 'frontier' && p.key !== implementer?.key)
+  let primary = ordered.slice(0, ASK_OPTION_LIMIT)
+  if (frontier && !primary.some((p) => p.key === frontier.key) && primary.length === ASK_OPTION_LIMIT) {
+    primary = [...primary.slice(0, ASK_OPTION_LIMIT - 1), frontier]
+  }
+  const primaryKeys = new Set(primary.map((p) => p.key))
+  const options = primary.map((p) => optionFromPoint(p, { recommended: p.key === implementer?.key, role: 'implementer' }))
+  const alternates = ordered
+    .filter((p) => !primaryKeys.has(p.key))
+    .map((p) => optionFromPoint(p, { recommended: false, role: 'implementer' }))
+
+  return {
+    header: 'Implementer',
+    question: 'Which model should implement every issue in this rush run? (Explorer + reviewer are filled automatically; reviewer ≠ implementer.)',
+    recommended: implementer?.key || null,
+    options,
+    alternates,
+    explorerFill: slotFillPayload(explorer),
+    reviewerFill: slotFillPayload(reviewer),
+  }
+}
+
+export function buildPreflightModels({
+  harness,
+  risk = 'routine',
+  available = [],
+  humanNamed = [],
+  env = process.env,
+  discoverFn = discover,
+  tierFn = tierProposals,
+} = {}) {
+  if (!harness) throw new Error('harness is required')
+  if (!RISK.includes(risk)) throw new Error(`risk must be one of ${RISK.join('|')}`)
+
+  const discovery = discoverFn(harness, env, {
+    spawnModelIds: available,
+    humanNamedModelIds: humanNamed,
+  })
+  const seenIds = discovery.discovered.map((d) => d.id)
+  const tiered = tierFn(harness, seenIds)
+  const catalog = readCatalog(pathForHarness(harness, env))
+  const seed = readSeed(defaultSeedPath())
+  const points = slotPoints(tiered.models, { harness, catalog, seed })
+  const implementer = recommendImplementer(points, risk)
+  if (!implementer) {
+    return {
+      ok: false,
+      code: 'no-slot-eligible',
+      harness,
+      risk,
+      discovery,
+      models: tiered,
+      points: [],
+      implementer: null,
+      explorer: null,
+      reviewer: null,
+      ask: null,
+      deferred: {
+        afterConfirm: [
+          'model-catalog.mjs sync --harness <h> --seen <ids>',
+          'model-catalog.mjs bank / bank-from-seed for any human confirmation',
+        ],
+      },
+    }
+  }
+  const explorer = fillExplorer(points, harness)
+  const reviewer = rankReviewers(points, implementer, harness)
+  const ask = buildAsk(implementer, points, reviewer, { risk, explorer })
+  return {
+    ok: true,
+    harness,
+    risk,
+    discovery: {
+      completeness: discovery.completeness,
+      discovered: discovery.discovered,
+      notes: discovery.notes,
+    },
+    models: tiered,
+    points,
+    implementer,
+    explorer: {
+      fill: explorer.fill,
+      reason: explorer.reason,
+    },
+    reviewer: {
+      fill: reviewer.fill,
+      reason: reviewer.reason,
+      ranking: reviewer.ranking.map((p) => p.key),
+      teamDefaultApplied: reviewer.teamDefaultApplied,
+      reducedDiversity: reviewer.reducedDiversity,
+      notIndependent: reviewer.notIndependent,
+    },
+    ask,
+    deferred: {
+      afterConfirm: [
+        `model-catalog.mjs sync --harness ${harness} --seen ${seenIds.join(',')}`,
+        'bank confirmations only after the human answers — never before the ask',
+      ],
+      doNotReadBeforeAsk: [
+        'resolve-issues/references/pre-flight.md',
+        'resolve-issues/references/pre-flight-model-slots.md',
+        'harness-runtime/references/model-catalog.md',
+      ],
+    },
+  }
+}
+
+export function runCli(argv, env = process.env) {
+  let args
+  try {
+    args = parseArgs(argv)
+  } catch (e) {
+    console.error(`preflight-models: ${e.message}`)
+    console.error(usage())
+    return 2
+  }
+  if (args.help) {
+    console.log(usage())
+    return 0
+  }
+  const harness = args.harness || detectHarness(env)
+  if (!harness) {
+    console.error('preflight-models: pass --harness <pi|codex|claude-code>')
+    return 2
+  }
+  if (!RISK.includes(args.risk)) {
+    console.error(`preflight-models: --risk must be ${RISK.join('|')}`)
+    return 2
+  }
+
+  let result
+  try {
+    result = buildPreflightModels({
+      harness,
+      risk: args.risk,
+      available: args.available,
+      humanNamed: args.humanNamed,
+      env,
+    })
+  } catch (e) {
+    console.error(`preflight-models: ${e.message}`)
+    return 2
+  }
+
+  if (!result.ok) {
+    console.log(JSON.stringify(result, null, 2))
+    return 3
+  }
+  if (args.askOnly) {
+    console.log(JSON.stringify(result.ask, null, 2))
+    return 0
+  }
+  console.log(JSON.stringify(result, null, 2))
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}

package/skills/engineering/rush-release/LICENSE

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

package/skills/engineering/rush-release/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: rush-release
+description: "Slash/explicit-only (/rush-release). Cut a GitHub Flow release from main: freeze the latest CI-green trunk SHA, write the changelog, choose SemVer, merge the metadata cut through a verified PR, tag the exact merged main SHA, and watch Cloud Build or npm publish. Do not auto-select. Use only on explicit user/orchestrator invoke. NOT for GitFlow/release-branch/0%-traffic promotion (resolve-release) and NOT for implementing a spec (rush-issues)."
+disable-model-invocation: true
+---
+
+# Rush release
+
+Cut a **GitHub Flow** release from **main**. Freeze one already-green trunk
+SHA, write a metadata-only version cut on that parent, merge it through a
+verified PR, tag the exact merged SHA on `main`, and watch the publisher.
+
+The orchestrator sequences local programs and one confirmation. It does not
+assemble a release branch, shift traffic, or verify production like
+`resolve-release`.
+
+```text
+preflight (main + publisher)
+  -> latest CI-green HEAD on main
+  -> changelog + SemVer plan (show user)
+  -> confirm
+  -> bump version files + commit the cut
+  -> merge metadata PR + verify merged main SHA
+  -> annotated tag on the merged SHA
+  -> push tag -> watch Cloud Build or npm
+```
+
+This file is the workflow and index. Read the linked procedure immediately
+before its stage; do not invent an unlinked substitute.
+
+| Stage / concern | Procedure |
+|---|---|
+| Trunk, publisher, version files | [references/preflight.md](references/preflight.md) |
+| Latest CI-green HEAD | [references/candidate.md](references/candidate.md) |
+| Changelog, SemVer, file bump, commit | [references/cut.md](references/cut.md) |
+| Tag, push, watch deploy | [references/publish.md](references/publish.md) |
+
+Run every script as
+`node <skillsRoot>/rush-release/scripts/<name>.mjs …` with the absolute skill
+root this file was loaded from. A CWD-relative `scripts/…` path resolves in the
+target repo and will not find these files.
+
+## Run invariants
+
+- Trunk is `main`. Another default branch is a different workflow.
+- The candidate is the newest SHA on `main` whose required CI is green — not
+  "the tip looks fine" and not a commit that is still pending.
+- The cut's parent is that frozen SHA. Do not rebase, merge, or cherry-pick
+  later `main` onto the cut branch; the provider merge is a separate identity.
+- Never publish an off-main cut. Merge the metadata PR through the repository's
+  queue, verify its exact merged SHA is reachable from `origin/main`, then tag
+  that merged SHA. Its Git tree must exactly equal the approved cut tree; any
+  post-freeze trunk content requires a new plan. The queue verdict is the
+  release tree's CI evidence.
+- Tags are immutable annotated `vMAJOR.MINOR.PATCH` names. Do not move, delete,
+  or force-push a tag that reached a remote.
+- Show the plan and wait for confirmation before any git mutation or push.
+- A failed watch is a hand-back. This lane does not roll back production.
+- The cut is metadata only (changelog + version identity files). Refuse a
+  cut that changes product code.
+
+## Workflow
+
+### 1. Preflight
+
+Confirm `main` is the trunk, detect whether the tag should fire Cloud Build,
+npm, or both, and list the files that carry the version. Details:
+[preflight.md](references/preflight.md).
+
+### 2. Candidate
+
+Fetch `origin/main` and pick the newest green SHA. Freeze it. Details:
+[candidate.md](references/candidate.md).
+
+### 3. Plan and confirm
+
+Derive the changelog and SemVer bump from `baselineTag..frozenSHA`. Show SHA,
+bump, version, tag, files, publisher, and notes. Do not mutate until the human
+confirms. Details: [cut.md](references/cut.md).
+
+### 4. Cut
+
+Branch from the frozen SHA, apply the changelog and version files, commit.
+Keep the diff metadata-only.
+
+### 5. Merge, tag, and watch
+
+Push the cut ref, merge its PR through the repository queue, verify the exact
+merged SHA on `main`, create the annotated tag on that SHA, push
+`refs/tags/<tag>` with hook-safe `--no-verify`, then watch Cloud Build and/or
+npm. Details: [publish.md](references/publish.md).
+
+## Done
+
+Success is the confirmed version tagged at the verified merged `main` SHA, the tag visible on the
+remote, and the chosen publisher reporting that version (Cloud Build SUCCESS
+and/or `npm view <pkg>@<version>`). Hand back the cut SHA, merged SHA, tag,
+changelog excerpt, publisher evidence, and the merged metadata PR. A publisher failure hands back the same identities without claiming
+the version shipped to users.

package/skills/engineering/rush-release/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Rush Release"
+  short_description: "Slash/explicit-only GitHub Flow release from green main"
+
+policy:
+  # Codex counterpart to SKILL.md disable-model-invocation: true.
+  # Keeps $rush-release / explicit invoke while blocking description-based selection.
+  allow_implicit_invocation: false

package/skills/engineering/rush-release/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "rush-release",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Dry-run only: do not modify Git, push a tag, or contact a publisher. Plan a GitHub Flow release from main. origin/main tip is pending CI; the previous first-parent commit abcdef1 is green. Commits since v1.4.0 are feat: export csv and fix: timezone. package.json is 1.4.0. Publisher is npm. Show the frozen SHA, changelog, SemVer, tag target, and watch command you would use after confirmation.",
+      "expected_output": "A dry-run plan that freezes abcdef1 rather than the pending tip, proposes a minor bump to 1.5.0 from the feat, writes changelog entries for both commits, merges the metadata cut through the queue, tags the verified merged main SHA only if its tree exactly equals the cut tree, and watches npm view rather than a Cloud Build traffic shift.",
+      "files": [],
+      "expectations": [
+        "Freezes the green SHA abcdef1 instead of the pending origin/main tip.",
+        "Proposes a minor SemVer bump to 1.5.0 because of feat: export csv.",
+        "Includes changelog entries derived from both the feat and the fix.",
+        "Tags only the queue-verified merged main SHA whose tree exactly equals the version-cut tree.",
+        "Watches npm publish (npm view) and does not describe a 0% traffic candidate or GitFlow release branch."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Dry-run only. Main is protected. Latest green HEAD is 2222222. Plan says v2.0.0 from a breaking change. The metadata PR merges through the queue as 3333333 and its tree exactly equals the approved cut. After you would push tag v2.0.0, Cloud Build returns FAILURE. What do you tag, how do you push it, and what happens after the failed watch? Assume cloudbuild.yaml is present.",
+      "expected_output": "A dry-run that verifies 3333333 is on main and tree-identical to the cut, tags merged SHA 3333333 with annotated v2.0.0, pushes refs/tags/v2.0.0 with --no-verify, watches gcloud builds list, and on FAILURE leaves the tag in place, treats the version as burned, and hands back without deleting the tag or rolling back production.",
+      "files": [],
+      "expectations": [
+        "Creates an annotated v2.0.0 tag on the verified merged main SHA 3333333.",
+        "Pushes the fully-qualified tag ref with --no-verify.",
+        "Watches Cloud Build filtered by that tag.",
+        "On FAILURE, does not move or delete the tag and does not roll back production.",
+        "States the next attempt takes a new patch from a new green HEAD."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Dry-run only. origin/main moved after the candidate was frozen: green SHA is 3333333, then an ungreen commit 4444444 landed on main. How do you cut 1.2.3 so the ungreen commit is not in the tag? Publisher is both Cloud Build and npm.",
+      "expected_output": "A dry-run that branches from 3333333 and commits metadata only, but refuses publication because a merge containing 4444444 cannot be tree-identical to the approved cut. It creates no tag, waits for a new eligible main state, then restarts candidate selection and the changelog/SemVer plan before watching either publisher.",
+      "files": [],
+      "expectations": [
+        "Branches the cut from frozen SHA 3333333.",
+        "Refuses to rebase or merge the later ungreen commit into the tagged object.",
+        "Creates no tag while the only merged result would contain unplanned commit 4444444.",
+        "Restarts the changelog and SemVer plan from a new eligible main state before watching Cloud Build and npm.",
+        "Does not squash-merge the metadata PR onto moved main."
+      ]
+    }
+  ]
+}

package/skills/engineering/rush-release/references/candidate.md

@@ -0,0 +1,30 @@
+# Candidate
+
+The release candidate is the newest commit that is on `main` and already green.
+The current tip is eligible only when that exact SHA is green.
+
+## Procedure
+
+1. Fetch `origin/main`.
+2. Walk first-parent history of `origin/main`, newest first.
+3. Run the picker:
+
+```bash
+node <skillsRoot>/rush-release/scripts/green-head.mjs --trunk main --json
+```
+
+4. Freeze `candidateSha` from the JSON. Do not keep walking after a green SHA
+   in the hope of a "nicer" commit.
+5. If the script exits 1 (`no-green-head`), stop. Repair CI or wait; do not
+   release a pending or failed SHA, and do not treat "no checks configured" as
+   green.
+
+## Why freeze
+
+`main` keeps moving. The changelog, the bump, and the tag all describe one
+commit. If a later commit lands while you write notes, including it would ship
+code that never passed this candidate check.
+
+The frozen SHA is the **parent of the cut**, not yet the tag. Version files
+still need a metadata commit on top; that child is what gets tagged
+([cut.md](cut.md)).